MdePkg/Include/Protocol/IdeControllerInit.h

   1 /** @file
   2   This file declares EFI IDE Controller Init Protocol
   3
   4   The EFI_IDE_CONTROLLER_INIT_PROTOCOL provides the chipset-specific information
   5   to the IDE bus driver. This protocol is mandatory for IDE controllers if the
   6   IDE devices behind the controller are to be enumerated by an IDE bus driver.
   7
   8   There can only be one instance of EFI_IDE_CONTROLLER_INIT_PROTOCOL for each IDE
   9   controller in a system. It is installed on the handle that corresponds to the
  10   IDE controller. An IDE bus driver that wishes to manage an IDE bus and possibly
  11   IDE devices in a system will have to retrieve the EFI_IDE_CONTROLLER_INIT_PROTOCOL
  12   instance that is associated with the controller to be managed.
  13
  14   A device handle for an IDE controller must contain an EFI_DEVICE_PATH_PROTOCOL.
  15
  16   Copyright (c) 2007 - 2009, Intel Corporation
  17   All rights reserved. This program and the accompanying materials
  18   are licensed and made available under the terms and conditions of the BSD License
  19   which accompanies this distribution.  The full text of the license may be found at
  20   http://opensource.org/licenses/bsd-license.php
  21
  22   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  23   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  24
  25   @par Revision Reference:
  26   This Protocol is defined in UEFI Platform Initialization Specification 1.2
  27   Volume 5: Standards
  28
  29 **/
  30
  31 #ifndef _EFI_IDE_CONTROLLER_INIT_PROTOCOL_H_
  32 #define _EFI_IDE_CONTROLLER_INIT_PROTOCOL_H_
  33
  34 ///
  35 /// Global ID for the EFI_IDE_CONTROLLER_INIT_PROTOCOL
  36 ///
  37 #define EFI_IDE_CONTROLLER_INIT_PROTOCOL_GUID \
  38   { \
  39     0xa1e37052, 0x80d9, 0x4e65, {0xa3, 0x17, 0x3e, 0x9a, 0x55, 0xc4, 0x3e, 0xc9 } \
  40   }
  41
  42 ///
  43 /// Forward declaration for EFI_IDE_CONTROLLER_INIT_PROTOCOL
  44 ///
  45 typedef struct _EFI_IDE_CONTROLLER_INIT_PROTOCOL  EFI_IDE_CONTROLLER_INIT_PROTOCOL;
  46
  47 ///
  48 /// The phase of the IDE Controller enumeration
  49 ///
  50 typedef enum {
  51   ///
  52   /// The IDE bus driver is about to begin enumerating the devices
  53   /// behind the specified channel. This notification can be used to
  54   /// perform any chipset-specific programming.
  55   ///
  56   EfiIdeBeforeChannelEnumeration,
  57   ///
  58   /// The IDE bus driver has completed enumerating the devices
  59   /// behind the specified channel. This notification can be used to
  60   /// perform any chipset-specific programming.
  61   ///
  62   EfiIdeAfterChannelEnumeration,
  63   ///
  64   /// The IDE bus driver is about to reset the devices behind the
  65   /// specified channel. This notification can be used to perform any
  66   /// chipset-specific programming.
  67   ///
  68   EfiIdeBeforeChannelReset,
  69   ///
  70   /// The IDE bus driver has completed resetting the devices behind
  71   /// the specified channel. This notification can be used to perform
  72   /// any chipset-specific programming.
  73   ///
  74   EfiIdeAfterChannelReset,
  75   ///
  76   /// The IDE bus driver is about to detect the presence of devices
  77   /// behind the specified channel. This notification can be used to
  78   /// set up the bus signals to default levels or for implementing
  79   /// predelays.
  80   ///
  81   EfiIdeBusBeforeDevicePresenceDetection,
  82   ///
  83   /// The IDE bus driver is done with detecting the presence of
  84   /// devices behind the specified channel. This notification can be
  85   /// used to perform any chipset-specific programming.
  86   ///
  87   EfiIdeBusAfterDevicePresenceDetection,
  88   ///
  89   /// The IDE bus is requesting the IDE controller driver to
  90   /// reprogram the IDE controller hardware and thereby reset all
  91   /// the mode and timing settings to default settings.
  92   ///
  93   EfiIdeResetMode,
  94   EfiIdeBusPhaseMaximum
  95 } EFI_IDE_CONTROLLER_ENUM_PHASE;
  96
  97 ///
  98 /// This extended mode describes the SATA physical protocol.
  99 /// SATA physical layers can operate at different speeds.
 100 /// These speeds are defined below. Various PATA protocols
 101 /// and associated modes are not applicable to SATA devices.
 102 ///
 103 typedef enum {
 104   EfiAtaSataTransferProtocol
 105 } EFI_ATA_EXT_TRANSFER_PROTOCOL;
 106
 107 ///
 108 /// Automatically detects the optimum SATA speed.
 109 ///
 110 #define  EFI_SATA_AUTO_SPEED  0
 111
 112 ///
 113 /// Indicates a first-generation (Gen1) SATA speed.
 114 ///
 115 #define  EFI_SATA_GEN1_SPEED  1
 116
 117 ///
 118 /// Indicates a second-generation (Gen2) SATA speed.
 119 ///
 120 #define  EFI_SATA_GEN2_SPEED  2
 121
 122 ///
 123 /// EFI_ATA_MODE structure
 124 ///
 125 typedef struct {
 126   BOOLEAN      Valid;   ///< TRUE if Mode is valid.
 127   UINT32       Mode;    ///< The actual ATA mode. This field is not a bit map.
 128 } EFI_ATA_MODE;
 129
 130 ///
 131 /// EFI_ATA_EXTENDED_MODE structure
 132 ///
 133 typedef struct {
 134   ///
 135   /// An enumeration defining various transfer protocols other than the protocols
 136   /// that exist at the time this specification was developed (i.e., PIO, single
 137   /// word DMA, multiword DMA, and UDMA). Each transfer protocol is associated
 138   /// with a mode. The various transfer protocols are defined by the ATA/ATAPI
 139   /// specification. This enumeration makes the interface extensible because we
 140   /// can support new transport protocols beyond UDMA. Type EFI_ATA_EXT_TRANSFER_PROTOCOL
 141   /// is defined below.
 142   ///
 143   EFI_ATA_EXT_TRANSFER_PROTOCOL  TransferProtocol;
 144   ///
 145   /// The mode for operating the transfer protocol that is identified by TransferProtocol.
 146   ///
 147   UINT32                         Mode;
 148 } EFI_ATA_EXTENDED_MODE;
 149
 150 ///
 151 /// EFI_ATA_COLLECTIVE_MODE structure
 152 ///
 153 typedef struct {
 154   ///
 155   /// This field specifies the PIO mode. PIO modes are defined in the ATA/ATAPI
 156   /// specification. The ATA/ATAPI specification defines the enumeration.  In
 157   /// other words, a value of 1 in this field means PIO mode 1. The actual meaning
 158   /// of PIO mode 1 is governed by the ATA/ATAPI specification. Type EFI_ATA_MODE
 159   /// is defined below.
 160   ///
 161   EFI_ATA_MODE           PioMode;
 162   ///
 163   /// This field specifies the single word DMA mode. Single word DMA modes are defined
 164   /// in the ATA/ATAPI specification, versions 1 and 2. Single word DMA support was
 165   /// obsoleted in the ATA/ATAPI specification, version 3; therefore, most devices and
 166   /// controllers will not support this transfer mode. The ATA/ATAPI specification defines
 167   /// the enumeration. In other words, a value of 1 in this field means single word DMA
 168   /// mode 1. The actual meaning of single word DMA mode 1 is governed by the ATA/
 169   /// ATAPI specification.
 170   ///
 171   EFI_ATA_MODE           SingleWordDmaMode;
 172   ///
 173   /// This field specifies the multiword DMA mode. Various multiword DMA modes are
 174   /// defined in the ATA/ATAPI specification. A value of 1 in this field means multiword
 175   /// DMA mode 1. The actual meaning of multiword DMA mode 1 is governed by the
 176   /// ATA/ATAPI specification.
 177   ///
 178   EFI_ATA_MODE           MultiWordDmaMode;
 179   ///
 180   /// This field specifies the ultra DMA (UDMA) mode. UDMA modes are defined in the
 181   /// ATA/ATAPI specification. A value of 1 in this field means UDMA mode 1. The
 182   /// actual meaning of UDMA mode 1 is governed by the ATA/ATAPI specification.
 183   ///
 184   EFI_ATA_MODE           UdmaMode;
 185   ///
 186   /// The number of extended-mode bitmap entries. Extended modes describe transfer
 187   /// protocols beyond PIO, single word DMA, multiword DMA, and UDMA. This field
 188   /// can be zero and provides extensibility.
 189   ///
 190   UINT32                 ExtModeCount;
 191   ///
 192   /// ExtModeCount number of entries. Each entry represents a transfer protocol other
 193   /// than the ones defined above (i.e., PIO, single word DMA, multiword DMA, and
 194   /// UDMA). This field is defined for extensibility. At this time, only one extended
 195   /// transfer protocol is defined to cover SATA transfers. Type
 196   /// EFI_ATA_EXTENDED_MODE is defined below.
 197   ///
 198   EFI_ATA_EXTENDED_MODE  ExtMode[1];
 199 } EFI_ATA_COLLECTIVE_MODE;
 200
 201 ///
 202 /// EFI_ATA_IDENTIFY_DATA structure
 203 ///
 204 /// This structure definition is not part of the protocol
 205 /// definition because the ATA/ATAPI Specification controls
 206 /// the definition of all the fields. The ATA/ATAPI
 207 /// Specification can obsolete old fields or redefine existing
 208 /// fields. This definition is provided here for reference only.
 209 ///
 210 #pragma pack(1)
 211 typedef struct {
 212   UINT16  config;                 ///< General Configuration
 213   UINT16  cylinders;              ///< Number of Cylinders
 214   UINT16  reserved_2;
 215   UINT16  heads;                  ///< Number of logical heads
 216   UINT16  vendor_data1;
 217   UINT16  vendor_data2;
 218   UINT16  sectors_per_track;
 219   UINT16  vendor_specific_7_9[3];
 220   CHAR8   SerialNo[20];           ///< ASCII
 221   UINT16  vendor_specific_20_21[2];
 222   UINT16  ecc_bytes_available;
 223   CHAR8   FirmwareVer[8];         ///< ASCII
 224   CHAR8   ModelName[40];          ///< ASCII
 225   UINT16  multi_sector_cmd_max_sct_cnt;
 226   UINT16  reserved_48;
 227   UINT16  capabilities;
 228   UINT16  reserved_50;
 229   UINT16  pio_cycle_timing;
 230   UINT16  reserved_52;
 231   UINT16  field_validity;
 232   UINT16  current_cylinders;
 233   UINT16  current_heads;
 234   UINT16  current_sectors;
 235   UINT16  CurrentCapacityLsb;
 236   UINT16  CurrentCapacityMsb;
 237   UINT16  reserved_59;
 238   UINT16  user_addressable_sectors_lo;
 239   UINT16  user_addressable_sectors_hi;
 240   UINT16  reserved_62;
 241   UINT16  multi_word_dma_mode;
 242   UINT16  advanced_pio_modes;
 243   UINT16  min_multi_word_dma_cycle_time;
 244   UINT16  rec_multi_word_dma_cycle_time;
 245   UINT16  min_pio_cycle_time_without_flow_control;
 246   UINT16  min_pio_cycle_time_with_flow_control;
 247   UINT16  reserved_69_79[11];
 248   UINT16  major_version_no;
 249   UINT16  minor_version_no;
 250   UINT16  command_set_supported_82;   ///< word 82
 251   UINT16  command_set_supported_83;   ///< word 83
 252   UINT16  command_set_feature_extn;   ///< word 84
 253   UINT16  command_set_feature_enb_85; ///< word 85
 254   UINT16  command_set_feature_enb_86; ///< word 86
 255   UINT16  command_set_feature_default; ///< word 87
 256   UINT16  ultra_dma_mode;             ///< word 88
 257   UINT16  reserved_89_105[17];
 258   UINT16  phy_logic_sector_support;   ///< word 106
 259   UINT16  reserved_107_116[10];
 260   UINT16  logic_sector_size_lo;       ///< word 117
 261   UINT16  logic_sector_size_hi;       ///< word 118
 262   UINT16  reserved_119_127[9];
 263   UINT16  security_status;
 264   UINT16  vendor_data_129_159[31];
 265   UINT16  reserved_160_208[49];
 266   UINT16  alignment_logic_in_phy_blocks; ///< word 209
 267   UINT16  reserved_210_255[46];
 268 } EFI_ATA_IDENTIFY_DATA;
 269 #pragma pack()
 270
 271 ///
 272 /// EFI_ATAPI_IDENTIFY_DATA structure
 273 ///
 274 /// This structure definition is not part of the protocol
 275 /// definition because the ATA/ATAPI Specification controls
 276 /// the definition of all the fields. The ATA/ATAPI
 277 /// Specification can obsolete old fields or redefine existing
 278 /// fields. This definition is provided here for reference only.
 279 ///
 280 #pragma pack(1)
 281 typedef struct {
 282     UINT16  config;             ///< General Configuration
 283     UINT16  obsolete_1;
 284     UINT16  specific_config;
 285     UINT16  obsolete_3;
 286     UINT16  retired_4_5[2];
 287     UINT16  obsolete_6;
 288     UINT16  cfa_reserved_7_8[2];
 289     UINT16  retired_9;
 290     CHAR8   SerialNo[20];       ///< ASCII
 291     UINT16  retired_20_21[2];
 292     UINT16  obsolete_22;
 293     CHAR8   FirmwareVer[8];     ///< ASCII
 294     CHAR8   ModelName[40];      ///< ASCII
 295     UINT16  multi_sector_cmd_max_sct_cnt;
 296     UINT16  reserved_48;
 297     UINT16  capabilities_49;
 298     UINT16  capabilities_50;
 299     UINT16  obsolete_51_52[2];
 300     UINT16  field_validity;
 301     UINT16  obsolete_54_58[5];
 302     UINT16  mutil_sector_setting;
 303     UINT16  user_addressable_sectors_lo;
 304     UINT16  user_addressable_sectors_hi;
 305     UINT16  obsolete_62;
 306     UINT16  multi_word_dma_mode;
 307     UINT16  advanced_pio_modes;
 308     UINT16  min_multi_word_dma_cycle_time;
 309     UINT16  rec_multi_word_dma_cycle_time;
 310     UINT16  min_pio_cycle_time_without_flow_control;
 311     UINT16  min_pio_cycle_time_with_flow_control;
 312     UINT16  reserved_69_74[6];
 313     UINT16  queue_depth;
 314     UINT16  reserved_76_79[4];
 315     UINT16  major_version_no;
 316     UINT16  minor_version_no;
 317     UINT16  cmd_set_support_82;
 318     UINT16  cmd_set_support_83;
 319     UINT16  cmd_feature_support;
 320     UINT16  cmd_feature_enable_85;
 321     UINT16  cmd_feature_enable_86;
 322     UINT16  cmd_feature_default;
 323     UINT16  ultra_dma_select;
 324     UINT16  time_required_for_sec_erase;
 325     UINT16  time_required_for_enhanced_sec_erase;
 326     UINT16  current_advanced_power_mgmt_value;
 327     UINT16  master_pwd_revison_code;
 328     UINT16  hardware_reset_result;
 329     UINT16  current_auto_acoustic_mgmt_value;
 330     UINT16  reserved_95_99[5];
 331     UINT16  max_user_lba_for_48bit_addr[4];
 332     UINT16  reserved_104_126[23];
 333     UINT16  removable_media_status_notification_support;
 334     UINT16  security_status;
 335     UINT16  vendor_data_129_159[31];
 336     UINT16  cfa_power_mode;
 337     UINT16  cfa_reserved_161_175[15];
 338     UINT16  current_media_serial_no[30];
 339     UINT16  reserved_206_254[49];
 340     UINT16  integrity_word;
 341 } EFI_ATAPI_IDENTIFY_DATA;
 342 #pragma pack()
 343
 344 ///
 345 /// This flag indicates whether the IDENTIFY data is a response from an ATA device
 346 /// (EFI_ATA_IDENTIFY_DATA) or response from an ATAPI device
 347 /// (EFI_ATAPI_IDENTIFY_DATA).  According to the ATA/ATAPI specification,
 348 /// EFI_IDENTIFY_DATA is for an ATA device if bit 15 of the Config field is zero.
 349 /// The Config field is common to both EFI_ATA_IDENTIFY_DATA and
 350 /// EFI_ATAPI_IDENTIFY_DATA.
 351 ///
 352 #define   EFI_ATAPI_DEVICE_IDENTIFY_DATA  0x8000
 353
 354 ///
 355 /// EFI_IDENTIFY_DATA structure
 356 ///
 357 typedef union {
 358   ///
 359   /// The data that is returned by an ATA device upon successful completion
 360   /// of the ATA IDENTIFY_DEVICE command.
 361   ///
 362   EFI_ATA_IDENTIFY_DATA       AtaData;
 363   ///
 364   /// The data that is returned by an ATAPI device upon successful completion
 365   /// of the ATA IDENTIFY_PACKET_DEVICE command.
 366   ///
 367   EFI_ATAPI_IDENTIFY_DATA     AtapiData;
 368 } EFI_IDENTIFY_DATA;
 369
 370 /**
 371   Returns the information about the specified IDE channel.
 372
 373   This function can be used to obtain information about a particular IDE channel.
 374   The IDE bus driver uses this information during the enumeration process.
 375
 376   If Enabled is set to FALSE, the IDE bus driver will not scan the channel. Note
 377   that it will not prevent an operating system driver from scanning the channel.
 378
 379   For most of today's controllers, MaxDevices will either be 1 or 2. For SATA
 380   controllers, this value will always be 1. SATA configurations can contain SATA
 381   port multipliers. SATA port multipliers behave like SATA bridges and can support
 382   up to 16 devices on the other side. If an SATA port out of the IDE controller
 383   is connected to a port multiplier, MaxDevices will be set to the number of SATA
 384   devices that the port multiplier supports. Because today's port multipliers
 385   support up to 15 SATA devices, this number can be as large as 15. The IDE bus
 386   driver is required to scan for the presence of port multipliers behind an SATA
 387   controller and enumerate up to MaxDevices number of devices behind the port
 388   multiplier.
 389
 390   In this context, the devices behind a port multiplier constitute a channel.
 391
 392   @param[in]  This         Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
 393   @param[in]  Channel      Zero-based channel number.
 394   @param[out] Enabled      TRUE if this channel is enabled.  Disabled channels
 395                            are not scanned to see if any devices are present.
 396   @param[out] MaxDevices   The maximum number of IDE devices that the bus driver
 397                            can expect on this channel.  For the ATA/ATAPI
 398                            specification, version 6, this number will either be
 399                            1 or 2. For Serial ATA (SATA) configurations with a
 400                            port multiplier, this number can be as large as 15.
 401
 402   @retval EFI_SUCCESS             Information was returned without any errors.
 403   @retval EFI_INVALID_PARAMETER   Channel is invalid (Channel >= ChannelCount).
 404
 405 **/
 406 typedef
 407 EFI_STATUS
 408 (EFIAPI *EFI_IDE_CONTROLLER_GET_CHANNEL_INFO)(
 409   IN  EFI_IDE_CONTROLLER_INIT_PROTOCOL  *This,
 410   IN  UINT8                             Channel,
 411   OUT BOOLEAN                           *Enabled,
 412   OUT UINT8                             *MaxDevices
 413   );
 414
 415 /**
 416   The notifications from the IDE bus driver that it is about to enter a certain
 417   phase of the IDE channel enumeration process.
 418
 419   This function can be used to notify the IDE controller driver to perform
 420   specific actions, including any chipset-specific initialization, so that the
 421   chipset is ready to enter the next phase. Seven notification points are defined
 422   at this time.
 423
 424   More synchronization points may be added as required in the future.
 425
 426   @param[in] This      Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
 427   @param[in] Phase     The phase during enumeration.
 428   @param[in] Channel   Zero-based channel number.
 429
 430   @retval EFI_SUCCESS             The notification was accepted without any errors.
 431   @retval EFI_NOT_SUPPORTED       Phase is not supported.
 432   @retval EFI_INVALID_PARAMETER   Channel is invalid (Channel >= ChannelCount).
 433   @retval EFI_NOT_READY           This phase cannot be entered at this time; for
 434                                   example, an attempt was made to enter a Phase
 435                                   without having entered one or more previous
 436                                   Phase.
 437
 438 **/
 439 typedef
 440 EFI_STATUS
 441 (EFIAPI *EFI_IDE_CONTROLLER_NOTIFY_PHASE)(
 442   IN EFI_IDE_CONTROLLER_INIT_PROTOCOL  *This,
 443   IN EFI_IDE_CONTROLLER_ENUM_PHASE     Phase,
 444   IN UINT8                             Channel
 445   );
 446
 447 /**
 448   Submits the device information to the IDE controller driver.
 449
 450   This function is used by the IDE bus driver to pass detailed information about
 451   a particular device to the IDE controller driver. The IDE bus driver obtains
 452   this information by issuing an ATA or ATAPI IDENTIFY_DEVICE command. IdentifyData
 453   is the pointer to the response data buffer. The IdentifyData buffer is owned
 454   by the IDE bus driver, and the IDE controller driver must make a local copy
 455   of the entire buffer or parts of the buffer as needed. The original IdentifyData
 456   buffer pointer may not be valid when
 457
 458     - EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode() or
 459     - EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode() is called at a later point.
 460
 461   The IDE controller driver may consult various fields of EFI_IDENTIFY_DATA to
 462   compute the optimum mode for the device. These fields are not limited to the
 463   timing information. For example, an implementation of the IDE controller driver
 464   may examine the vendor and type/mode field to match known bad drives.
 465
 466   The IDE bus driver may submit drive information in any order, as long as it
 467   submits information for all the devices belonging to the enumeration group
 468   before EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode() is called for any device
 469   in that enumeration group. If a device is absent, EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData()
 470   should be called with IdentifyData set to NULL.  The IDE controller driver may
 471   not have any other mechanism to know whether a device is present or not. Therefore,
 472   setting IdentifyData to NULL does not constitute an error condition.
 473   EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData() can be called only once for a
 474   given (Channel, Device) pair.
 475
 476   @param[in] This           Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
 477   @param[in] Channel        Zero-based channel number.
 478   @param[in] Device         Zero-based device number on the Channel.
 479   @param[in] IdentifyData   The device's response to the ATA IDENTIFY_DEVICE command.
 480
 481   @retval EFI_SUCCESS             The information was accepted without any errors.
 482   @retval EFI_INVALID_PARAMETER   Channel is invalid (Channel >= ChannelCount).
 483   @retval EFI_INVALID_PARAMETER   Device is invalid.
 484
 485 **/
 486 typedef
 487 EFI_STATUS
 488 (EFIAPI *EFI_IDE_CONTROLLER_SUBMIT_DATA)(
 489   IN EFI_IDE_CONTROLLER_INIT_PROTOCOL  *This,
 490   IN UINT8                             Channel,
 491   IN UINT8                             Device,
 492   IN EFI_IDENTIFY_DATA                 *IdentifyData
 493   );
 494
 495 /**
 496   Disqualifies specific modes for an IDE device.
 497
 498   This function allows the IDE bus driver or other drivers (such as platform
 499   drivers) to reject certain timing modes and request the IDE controller driver
 500   to recalculate modes. This function allows the IDE bus driver and the IDE
 501   controller driver to negotiate the timings on a per-device basis. This function
 502   is useful in the case of drives that lie about their capabilities. An example
 503   is when the IDE device fails to accept the timing modes that are calculated
 504   by the IDE controller driver based on the response to the Identify Drive command.
 505
 506   If the IDE bus driver does not want to limit the ATA timing modes and leave that
 507   decision to the IDE controller driver, it can either not call this function for
 508   the given device or call this function and set the Valid flag to FALSE for all
 509   modes that are listed in EFI_ATA_COLLECTIVE_MODE.
 510
 511   The IDE bus driver may disqualify modes for a device in any order and any number
 512   of times.
 513
 514   This function can be called multiple times to invalidate multiple modes of the
 515   same type (e.g., Programmed Input/Output [PIO] modes 3 and 4). See the ATA/ATAPI
 516   specification for more information on PIO modes.
 517
 518   For Serial ATA (SATA) controllers, this member function can be used to disqualify
 519   a higher transfer rate mode on a given channel. For example, a platform driver
 520   may inform the IDE controller driver to not use second-generation (Gen2) speeds
 521   for a certain SATA drive.
 522
 523   @param[in] This       Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
 524   @param[in] Channel    Zero-based channel number.
 525   @param[in] Device     Zero-based device number on the Channel.
 526   @param[in] BadModes   The modes that the device does not support and that
 527                         should be disqualified.
 528
 529   @retval EFI_SUCCESS             The modes were accepted without any errors.
 530   @retval EFI_INVALID_PARAMETER   Channel is invalid (Channel >= ChannelCount).
 531   @retval EFI_INVALID_PARAMETER   Device is invalid.
 532   @retval EFI_INVALID_PARAMETER   IdentifyData is NULL.
 533
 534 **/
 535 typedef
 536 EFI_STATUS
 537 (EFIAPI *EFI_IDE_CONTROLLER_DISQUALIFY_MODE)(
 538   IN EFI_IDE_CONTROLLER_INIT_PROTOCOL  *This,
 539   IN UINT8                             Channel,
 540   IN UINT8                             Device,
 541   IN EFI_ATA_COLLECTIVE_MODE           *BadModes
 542   );
 543
 544 /**
 545   Returns the information about the optimum modes for the specified IDE device.
 546
 547   This function is used by the IDE bus driver to obtain the optimum ATA modes for
 548   a specific device.  The IDE controller driver takes into account the following
 549   while calculating the mode:
 550     - The IdentifyData inputs to EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData()
 551     - The BadModes inputs to EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode()
 552
 553   The IDE bus driver is required to call EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData()
 554   for all the devices that belong to an enumeration group before calling
 555   EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode() for any device in the same group.
 556
 557   The IDE controller driver will use controller- and possibly platform-specific
 558   algorithms to arrive at SupportedModes.  The IDE controller may base its
 559   decision on user preferences and other considerations as well. This function
 560   may be called multiple times because the IDE bus driver may renegotiate the mode
 561   with the IDE controller driver using EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode().
 562
 563   The IDE bus driver may collect timing information for various devices in any
 564   order. The IDE bus driver is responsible for making sure that all the dependencies
 565   are satisfied; for example, the SupportedModes information for device A that
 566   was previously returned may become stale after a call to
 567   EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode() for device B.
 568
 569   The buffer SupportedModes is allocated by the callee because the caller does
 570   not necessarily know the size of the buffer. The type EFI_ATA_COLLECTIVE_MODE
 571   is defined in a way that allows for future extensibility and can be of variable
 572   length. This memory pool should be deallocated by the caller when it is no
 573   longer necessary.
 574
 575   The IDE controller driver for a Serial ATA (SATA) controller can use this
 576   member function to force a lower speed (first-generation [Gen1] speeds on a
 577   second-generation [Gen2]-capable hardware).  The IDE controller driver can
 578   also allow the IDE bus driver to stay with the speed that has been negotiated
 579   by the physical layer.
 580
 581   @param[in]  This             Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
 582   @param[in]  Channel          Zero-based channel number.
 583   @param[in]  Device           Zero-based device number on the Channel.
 584   @param[out] SupportedModes   The optimum modes for the device.
 585
 586   @retval EFI_SUCCESS             SupportedModes was returned.
 587   @retval EFI_INVALID_PARAMETER   Channel is invalid (Channel >= ChannelCount).
 588   @retval EFI_INVALID_PARAMETER   Device is invalid.
 589   @retval EFI_INVALID_PARAMETER   SupportedModes is NULL.
 590   @retval EFI_NOT_READY           Modes cannot be calculated due to a lack of
 591                                   data.  This error may happen if
 592                                   EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData()
 593                                   and EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyData()
 594                                   were not called for at least one drive in the
 595                                   same enumeration group.
 596
 597 **/
 598 typedef
 599 EFI_STATUS
 600 (EFIAPI *EFI_IDE_CONTROLLER_CALCULATE_MODE)(
 601   IN  EFI_IDE_CONTROLLER_INIT_PROTOCOL  *This,
 602   IN  UINT8                             Channel,
 603   IN  UINT8                             Device,
 604   OUT EFI_ATA_COLLECTIVE_MODE           **SupportedModes
 605   );
 606
 607 /**
 608   Commands the IDE controller driver to program the IDE controller hardware
 609   so that the specified device can operate at the specified mode.
 610
 611   This function is used by the IDE bus driver to instruct the IDE controller
 612   driver to program the IDE controller hardware to the specified modes. This
 613   function can be called only once for a particular device. For a Serial ATA
 614   (SATA) Advanced Host Controller Interface (AHCI) controller, no controller-
 615   specific programming may be required.
 616
 617   @param[in] This      Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
 618   @param[in] Channel   Zero-based channel number.
 619   @param[in] Device    Zero-based device number on the Channel.
 620   @param[in] Modes     The modes to set.
 621
 622   @retval EFI_SUCCESS             The command was accepted without any errors.
 623   @retval EFI_INVALID_PARAMETER   Channel is invalid (Channel >= ChannelCount).
 624   @retval EFI_INVALID_PARAMETER   Device is invalid.
 625   @retval EFI_NOT_READY           Modes cannot be set at this time due to lack of data.
 626   @retval EFI_DEVICE_ERROR        Modes cannot be set due to hardware failure.
 627                                   The IDE bus driver should not use this device.
 628
 629 **/
 630 typedef
 631 EFI_STATUS
 632 (EFIAPI *EFI_IDE_CONTROLLER_SET_TIMING)(
 633   IN EFI_IDE_CONTROLLER_INIT_PROTOCOL  *This,
 634   IN UINT8                             Channel,
 635   IN UINT8                             Device,
 636   IN EFI_ATA_COLLECTIVE_MODE           *Modes
 637   );
 638
 639 ///
 640 /// Provides the basic interfaces to abstract an IDE controller.
 641 ///
 642 struct _EFI_IDE_CONTROLLER_INIT_PROTOCOL {
 643   ///
 644   /// Returns the information about a specific channel.
 645   ///
 646   EFI_IDE_CONTROLLER_GET_CHANNEL_INFO    GetChannelInfo;
 647
 648   ///
 649   /// The notification that the IDE bus driver is about to enter the
 650   /// specified phase during the enumeration process.
 651   ///
 652   EFI_IDE_CONTROLLER_NOTIFY_PHASE        NotifyPhase;
 653
 654   ///
 655   /// Submits the Drive Identify data that was returned by the device.
 656   ///
 657   EFI_IDE_CONTROLLER_SUBMIT_DATA         SubmitData;
 658
 659   ///
 660   /// Submits information about modes that should be disqualified.  The specified
 661   /// IDE device does not support these modes and these modes should not be
 662   /// returned by EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode()
 663   ///
 664   EFI_IDE_CONTROLLER_DISQUALIFY_MODE     DisqualifyMode;
 665
 666   ///
 667   /// Calculates and returns the optimum mode for a particular IDE device.
 668   ///
 669   EFI_IDE_CONTROLLER_CALCULATE_MODE      CalculateMode;
 670
 671   ///
 672   /// Programs the IDE controller hardware to the default timing or per the modes
 673   /// that were returned by the last call to EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode().
 674   ///
 675   EFI_IDE_CONTROLLER_SET_TIMING          SetTiming;
 676
 677   ///
 678   /// Set to TRUE if the enumeration group includes all the channels that are
 679   /// produced by this controller. FALSE if an enumeration group consists of
 680   /// only one channel.
 681   ///
 682   BOOLEAN                                EnumAll;
 683
 684   ///
 685   /// The number of channels that are produced by this controller. Parallel ATA
 686   /// (PATA) controllers can support up to two channels. Advanced Host Controller
 687   /// Interface (AHCI) Serial ATA (SATA) controllers can support up to 32 channels,
 688   /// each of which can have up to one device. In the presence of a multiplier,
 689   /// each channel can have 15 devices.
 690   ///
 691   UINT8                                  ChannelCount;
 692 };
 693
 694 extern EFI_GUID gEfiIdeControllerInitProtocolGuid;
 695
 696 #endif