PcAtChipsetPkg/Bus/Pci/IdeControllerDxe/IdeController.h

   1 /** @file
   2   Header file for IDE controller driver.
   3
   4   Copyright (c) 2008 - 2010, Intel Corporation. All rights reserved.<BR>
   5   This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #ifndef _IDE_CONTROLLER_H
  16 #define _IDE_CONTROLLER_H
  17
  18 #include <Uefi.h>
  19 #include <Protocol/ComponentName.h>
  20 #include <Protocol/DriverBinding.h>
  21 #include <Protocol/PciIo.h>
  22 #include <Protocol/IdeControllerInit.h>
  23 #include <Library/UefiDriverEntryPoint.h>
  24 #include <Library/DebugLib.h>
  25 #include <Library/UefiLib.h>
  26 #include <Library/BaseLib.h>
  27 #include <Library/BaseMemoryLib.h>
  28 #include <Library/MemoryAllocationLib.h>
  29 #include <Library/UefiBootServicesTableLib.h>
  30 #include <IndustryStandard/Pci.h>
  31
  32 //
  33 // Global Variables definitions
  34 //
  35 extern EFI_DRIVER_BINDING_PROTOCOL  gIdeControllerDriverBinding;
  36 extern EFI_COMPONENT_NAME_PROTOCOL  gIdeControllerComponentName;
  37 extern EFI_COMPONENT_NAME2_PROTOCOL gIdeControllerComponentName2;
  38
  39 ///
  40 /// Supports 2 channel max
  41 ///
  42 #define ICH_IDE_MAX_CHANNEL 0x02
  43
  44 ///
  45 /// Supports 2 devices max
  46 ///
  47 #define ICH_IDE_MAX_DEVICES 0x02
  48 #define ICH_IDE_ENUMER_ALL  FALSE
  49
  50 //
  51 // Driver binding functions declaration
  52 //
  53 /**
  54   Register Driver Binding protocol for this driver.
  55
  56   @param This                   A pointer points to the Binding Protocol instance
  57   @param Controller             The handle of controller to be tested.
  58   @param RemainingDevicePath    A pointer to the device path. Ignored by device
  59                                 driver but used by bus driver
  60
  61   @retval EFI_SUCCESS           Driver loaded.
  62   @retval !EFI_SUCESS           Driver not loaded.
  63 **/
  64 EFI_STATUS
  65 EFIAPI
  66 IdeControllerSupported (
  67   IN EFI_DRIVER_BINDING_PROTOCOL       *This,
  68   IN EFI_HANDLE                        Controller,
  69   IN EFI_DEVICE_PATH_PROTOCOL          *RemainingDevicePath
  70   )
  71 ;
  72
  73 /**
  74   This routine is called right after the .Supported() called and return
  75   EFI_SUCCESS. Notes: The supported protocols are checked but the Protocols
  76   are closed.
  77
  78   @param This                   A pointer points to the Binding Protocol instance
  79   @param Controller             The handle of controller to be tested. Parameter
  80                                 passed by the caller
  81   @param RemainingDevicePath    A pointer to the device path. Should be ignored by
  82                                 device driver
  83
  84   @return EFI_STATUS            Status of InstallMultipleProtocolInterfaces()
  85 **/
  86 EFI_STATUS
  87 EFIAPI
  88 IdeControllerStart (
  89   IN EFI_DRIVER_BINDING_PROTOCOL        *This,
  90   IN EFI_HANDLE                         Controller,
  91   IN EFI_DEVICE_PATH_PROTOCOL           *RemainingDevicePath
  92   )
  93 ;
  94
  95 /**
  96   Stop this driver on Controller Handle.
  97
  98   @param This               Protocol instance pointer.
  99   @param Controller         Handle of device to stop driver on
 100   @param NumberOfChildren   Not used
 101   @param ChildHandleBuffer  Not used
 102
 103   @retval EFI_SUCESS        This driver is removed DeviceHandle
 104   @retval !EFI_SUCCESS      This driver was not removed from this device
 105 **/
 106 EFI_STATUS
 107 EFIAPI
 108 IdeControllerStop (
 109   IN  EFI_DRIVER_BINDING_PROTOCOL       *This,
 110   IN  EFI_HANDLE                        Controller,
 111   IN  UINTN                             NumberOfChildren,
 112   IN  EFI_HANDLE                        *ChildHandleBuffer
 113   )
 114 ;
 115
 116 //
 117 // IDE controller init functions declaration
 118 //
 119 /**
 120   This function can be used to obtain information about a specified channel.
 121   It's usually used by IDE Bus driver during enumeration process.
 122
 123   @param This           the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
 124   @param Channel        Channel number (0 based, either 0 or 1)
 125   @param Enabled        TRUE if the channel is enabled. If the channel is disabled,
 126                         then it will no be enumerated.
 127   @param MaxDevices     The Max number of IDE devices that the bus driver can expect
 128                         on this channel. For ATA/ATAPI, this number is either 1 or 2.
 129
 130   @retval EFI_SUCCESS           Success to get channel information
 131   @retval EFI_INVALID_PARAMETER Invalid channel id.
 132 **/
 133 EFI_STATUS
 134 EFIAPI
 135 IdeInitGetChannelInfo (
 136   IN   EFI_IDE_CONTROLLER_INIT_PROTOCOL *This,
 137   IN   UINT8                            Channel,
 138   OUT  BOOLEAN                          *Enabled,
 139   OUT  UINT8                            *MaxDevices
 140   )
 141 ;
 142
 143 /**
 144   This function is called by IdeBus driver before executing certain actions.
 145   This allows IDE Controller Init to prepare for each action.
 146
 147   @param This       the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
 148   @param Phase      phase indicator defined by IDE_CONTROLLER_INIT protocol
 149   @param Channel    Channel number (0 based, either 0 or 1)
 150
 151   @return EFI_SUCCESS Success operation.
 152 **/
 153 EFI_STATUS
 154 EFIAPI
 155 IdeInitNotifyPhase (
 156   IN  EFI_IDE_CONTROLLER_INIT_PROTOCOL  *This,
 157   IN  EFI_IDE_CONTROLLER_ENUM_PHASE     Phase,
 158   OUT UINT8                             Channel
 159   )
 160 ;
 161
 162 /**
 163   This function is called by IdeBus driver to submit EFI_IDENTIFY_DATA data structure
 164   obtained from IDE deivce. This structure is used to set IDE timing
 165
 166   @param This           The EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
 167   @param Channel        IDE channel number (0 based, either 0 or 1)
 168   @param Device         IDE device number
 169   @param IdentifyData   A pointer to EFI_IDENTIFY_DATA data structure
 170
 171   @return EFI_SUCCESS   Success operation.
 172 **/
 173 EFI_STATUS
 174 EFIAPI
 175 IdeInitSubmitData (
 176   IN  EFI_IDE_CONTROLLER_INIT_PROTOCOL  *This,
 177   IN  UINT8                             Channel,
 178   IN  UINT8                             Device,
 179   IN  EFI_IDENTIFY_DATA                 *IdentifyData
 180   )
 181 ;
 182
 183 /**
 184   This function is called by IdeBus driver to disqualify unsupported operation
 185   mode on specfic IDE device
 186
 187   @param This       the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
 188   @param Channel    IDE channel number (0 based, either 0 or 1)
 189   @param Device     IDE device number
 190   @param BadModes   Operation mode indicator
 191
 192   @return EFI_SUCCESS Success operation.
 193 **/
 194 EFI_STATUS
 195 EFIAPI
 196 IdeInitDisqualifyMode (
 197   IN  EFI_IDE_CONTROLLER_INIT_PROTOCOL  *This,
 198   IN  UINT8                             Channel,
 199   IN  UINT8                             Device,
 200   IN  EFI_ATA_COLLECTIVE_MODE           *BadModes
 201   )
 202 ;
 203
 204 /**
 205   This function is called by IdeBus driver to calculate the best operation mode
 206   supported by specific IDE device
 207
 208   @param This               the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
 209   @param Channel            IDE channel number (0 based, either 0 or 1)
 210   @param Device             IDE device number
 211   @param SupportedModes     Modes collection supported by IDE device
 212
 213   @retval EFI_OUT_OF_RESOURCES  Fail to allocate pool.
 214   @retval EFI_INVALID_PARAMETER Invalid channel id and device id.
 215 **/
 216 EFI_STATUS
 217 EFIAPI
 218 IdeInitCalculateMode (
 219   IN  EFI_IDE_CONTROLLER_INIT_PROTOCOL  *This,
 220   IN  UINT8                             Channel,
 221   IN  UINT8                             Device,
 222   IN  EFI_ATA_COLLECTIVE_MODE           **SupportedModes
 223   )
 224 ;
 225
 226 /**
 227   This function is called by IdeBus driver to set appropriate timing on IDE
 228   controller according supported operation mode.
 229
 230   @param This       the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
 231   @param Channel    IDE channel number (0 based, either 0 or 1)
 232   @param Device     IDE device number
 233   @param Modes      IDE device modes
 234
 235   @retval EFI_SUCCESS Sucess operation.
 236 **/
 237 EFI_STATUS
 238 EFIAPI
 239 IdeInitSetTiming (
 240   IN  EFI_IDE_CONTROLLER_INIT_PROTOCOL  *This,
 241   IN  UINT8                             Channel,
 242   IN  UINT8                             Device,
 243   IN  EFI_ATA_COLLECTIVE_MODE           *Modes
 244   )
 245 ;
 246
 247 //
 248 // Forward reference declaration
 249 //
 250 /**
 251   Retrieves a Unicode string that is the user readable name of the EFI Driver.
 252
 253   @param This           A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.
 254   @param Language       A pointer to a three character ISO 639-2 language identifier.
 255                         This is the language of the driver name that that the caller
 256                         is requesting, and it must match one of the languages specified
 257                         in SupportedLanguages.  The number of languages supported by a
 258                         driver is up to the driver writer.
 259   @param DriverName     A pointer to the Unicode string to return.  This Unicode string
 260                         is the name of the driver specified by This in the language
 261                         specified by Language.
 262
 263   @retval EFI_SUCCESS           The Unicode string for the Driver specified by This
 264                                 and the language specified by Language was returned
 265                                 in DriverName.
 266   @retval EFI_INVALID_PARAMETER Language is NULL.
 267   @retval EFI_INVALID_PARAMETER DriverName is NULL.
 268   @retval EFI_UNSUPPORTED       The driver specified by This does not support the
 269                                 language specified by Language.
 270 **/
 271 EFI_STATUS
 272 EFIAPI
 273 IdeControllerComponentNameGetDriverName (
 274   IN  EFI_COMPONENT_NAME_PROTOCOL  *This,
 275   IN  CHAR8                        *Language,
 276   OUT CHAR16                       **DriverName
 277   )
 278 ;
 279
 280 /**
 281   Retrieves a Unicode string that is the user readable name of the controller
 282   that is being managed by an EFI Driver.
 283
 284   @param This                   A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.
 285   @param ControllerHandle       The handle of a controller that the driver specified by
 286                                 This is managing.  This handle specifies the controller
 287                                 whose name is to be returned.
 288   @param OPTIONAL               The handle of the child controller to retrieve the name
 289                                 of.  This is an optional parameter that may be NULL.  It
 290                                 will be NULL for device drivers.  It will also be NULL
 291                                 for a bus drivers that wish to retrieve the name of the
 292                                 bus controller.  It will not be NULL for a bus driver
 293                                 that wishes to retrieve the name of a child controller.
 294   @param Language               A pointer to a three character ISO 639-2 language
 295                                 identifier.  This is the language of the controller name
 296                                 that that the caller is requesting, and it must match one
 297                                 of the languages specified in SupportedLanguages.  The
 298                                 number of languages supported by a driver is up to the
 299                                 driver writer.
 300   @param ControllerName         A pointer to the Unicode string to return.  This Unicode
 301                                 string is the name of the controller specified by
 302                                 ControllerHandle and ChildHandle in the language
 303                                 specified by Language from the point of view of the
 304                                 driver specified by This.
 305
 306   @retval EFI_SUCCESS           The Unicode string for the user readable name in the
 307                                 language specified by Language for the driver
 308                                 specified by This was returned in DriverName.
 309   @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.
 310   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
 311                                 EFI_HANDLE.
 312   @retval EFI_INVALID_PARAMETER Language is NULL.
 313   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
 314   @retval EFI_UNSUPPORTED       The driver specified by This is not currently
 315                                 managing the controller specified by
 316                                 ControllerHandle and ChildHandle.
 317   @retval EFI_UNSUPPORTED       The driver specified by This does not support the
 318                                 language specified by Language.
 319 **/
 320 EFI_STATUS
 321 EFIAPI
 322 IdeControllerComponentNameGetControllerName (
 323   IN  EFI_COMPONENT_NAME_PROTOCOL                     *This,
 324   IN  EFI_HANDLE                                      ControllerHandle,
 325   IN  EFI_HANDLE                                      ChildHandle        OPTIONAL,
 326   IN  CHAR8                                           *Language,
 327   OUT CHAR16                                          **ControllerName
 328   )
 329 ;
 330
 331 #endif