IntelFrameworkPkg/Include/Protocol/IdeControllerInit.h

   1 /** @file
   2   This file declares EFI IDE Controller Init Protocol
   3   The EFI_IDE_CONTROLLER_INIT_PROTOCOL provides the chipset-specific information to
   4   the IDE bus driver. This protocol is mandatory for IDE controllers if the IDE devices behind the
   5   controller are to be enumerated by an IDE bus driver.
   6   There can only be one instance of EFI_IDE_CONTROLLER_INIT_PROTOCOL for each IDE
   7   controller in a system. It is installed on the handle that corresponds to the IDE controller. An IDE
   8   bus driver that wishes to manage an IDE bus and possibly IDE devices in a system will have to
   9   retrieve the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance that is associated with the
  10   controller to be managed.
  11
  12   Copyright (c) 2007 - 2009, Intel Corporation
  13   All rights reserved. This program and the accompanying materials
  14   are licensed and made available under the terms and conditions of the BSD License
  15   which accompanies this distribution.  The full text of the license may be found at
  16   http://opensource.org/licenses/bsd-license.php
  17
  18   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  19   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  20
  21   @par Revision Reference:
  22   This Protocol is defined in IDE Controller Initialization Protocol Specification
  23   Version 0.9.
  24
  25 **/
  26
  27 #ifndef _EFI_IDE_CONTROLLER_INIT_PROTOCOL_H_
  28 #define _EFI_IDE_CONTROLLER_INIT_PROTOCOL_H_
  29
  30
  31 ///
  32 /// Global ID for the EFI Platform IDE Protocol GUID
  33 ///
  34 #define EFI_IDE_CONTROLLER_INIT_PROTOCOL_GUID \
  35   { 0xa1e37052, 0x80d9, 0x4e65, {0xa3, 0x17, 0x3e, 0x9a, 0x55, 0xc4, 0x3e, 0xc9 } }
  36
  37 ///
  38 /// Forward reference for pure ANSI compatability
  39 ///
  40 typedef struct _EFI_IDE_CONTROLLER_INIT_PROTOCOL  EFI_IDE_CONTROLLER_INIT_PROTOCOL;
  41
  42 //
  43 //////////////////////////////////////////////////////////////////////////////////////////
  44 // EFI_IDE_BUS_ENUMERATION_PHASE
  45 // EFI_IDE_CONTROLLER_ENUM_PHASE
  46 //
  47 typedef enum{
  48   EfiIdeBeforeChannelEnumeration,
  49   EfiIdeAfterChannelEnumeration,
  50   EfiIdeBeforeChannelReset,
  51   EfiIdeAfterChannelReset,
  52   EfiIdeBusBeforeDevicePresenceDetection,
  53   EfiIdeBusAfterDevicePresenceDetection,
  54   EfiIdeResetMode,
  55   EfiIdeBusPhaseMaximum
  56 } EFI_IDE_CONTROLLER_ENUM_PHASE;
  57
  58 //
  59 //******************************************************
  60 // EFI_ATA_EXT_TRANSFER_PROTOCOL
  61 //******************************************************
  62 //
  63 // This extended mode describes the SATA physical protocol.
  64 // SATA physical layers can operate at different speeds.
  65 // These speeds are defined below. Various PATA protocols
  66 // and associated modes are not applicable to SATA devices.
  67 //
  68
  69 typedef enum {
  70   EfiAtaSataTransferProtocol
  71 } EFI_ATA_EXT_TRANSFER_PROTOCOL;
  72
  73 #define  EFI_SATA_AUTO_SPEED  0
  74 #define  EFI_SATA_GEN1_SPEED  1
  75 #define  EFI_SATA_GEN2_SPEED  2
  76
  77 //
  78 //*******************************************************
  79 // EFI_IDE_CABLE_TYPE
  80 //*******************************************************
  81 //
  82 typedef enum {
  83   EfiIdeCableTypeUnknown,
  84   EfiIdeCableType40pin,
  85   EfiIdeCableType80Pin,
  86   EfiIdeCableTypeSerial,
  87   EfiIdeCableTypeMaximum
  88 } EFI_IDE_CABLE_TYPE;
  89
  90 //
  91 //******************************************************
  92 // EFI_ATA_MODE
  93 //******************************************************
  94 //
  95 typedef struct {
  96   BOOLEAN      Valid;
  97   UINT32       Mode;
  98 } EFI_ATA_MODE;
  99
 100 //
 101 //******************************************************
 102 // EFI_ATA_EXTENDED_MODE
 103 //******************************************************
 104 //
 105 typedef struct {
 106   EFI_ATA_EXT_TRANSFER_PROTOCOL  TransferProtocol;
 107   UINT32                         Mode;
 108 } EFI_ATA_EXTENDED_MODE;
 109
 110 //
 111 //******************************************************
 112 // EFI_ATA_COLLECTIVE_MODE
 113 //******************************************************
 114 //
 115 typedef struct {
 116   EFI_ATA_MODE           PioMode;
 117   EFI_ATA_MODE           SingleWordDmaMode;
 118   EFI_ATA_MODE           MultiWordDmaMode;
 119   EFI_ATA_MODE           UdmaMode;
 120   UINT32                 ExtModeCount;
 121   EFI_ATA_EXTENDED_MODE  ExtMode[1];
 122 } EFI_ATA_COLLECTIVE_MODE;
 123
 124 //
 125 //*******************************************************
 126 // EFI_ATA_IDENTIFY_DATA
 127 //*******************************************************
 128 //
 129
 130 #pragma pack(1)
 131
 132 typedef struct {
 133   UINT16  config;                 ///< General Configuration
 134   UINT16  cylinders;              ///< Number of Cylinders
 135   UINT16  reserved_2;
 136   UINT16  heads;                  ///< Number of logical heads
 137   UINT16  vendor_data1;
 138   UINT16  vendor_data2;
 139   UINT16  sectors_per_track;
 140   UINT16  vendor_specific_7_9[3];
 141   CHAR8   SerialNo[20];           ///< ASCII
 142   UINT16  vendor_specific_20_21[2];
 143   UINT16  ecc_bytes_available;
 144   CHAR8   FirmwareVer[8];         ///< ASCII
 145   CHAR8   ModelName[40];          ///< ASCII
 146   UINT16  multi_sector_cmd_max_sct_cnt;
 147   UINT16  reserved_48;
 148   UINT16  capabilities;
 149   UINT16  reserved_50;
 150   UINT16  pio_cycle_timing;
 151   UINT16  reserved_52;
 152   UINT16  field_validity;
 153   UINT16  current_cylinders;
 154   UINT16  current_heads;
 155   UINT16  current_sectors;
 156   UINT16  CurrentCapacityLsb;
 157   UINT16  CurrentCapacityMsb;
 158   UINT16  reserved_59;
 159   UINT16  user_addressable_sectors_lo;
 160   UINT16  user_addressable_sectors_hi;
 161   UINT16  reserved_62;
 162   UINT16  multi_word_dma_mode;
 163   UINT16  advanced_pio_modes;
 164   UINT16  min_multi_word_dma_cycle_time;
 165   UINT16  rec_multi_word_dma_cycle_time;
 166   UINT16  min_pio_cycle_time_without_flow_control;
 167   UINT16  min_pio_cycle_time_with_flow_control;
 168   UINT16  reserved_69_79[11];
 169   UINT16  major_version_no;
 170   UINT16  minor_version_no;
 171   UINT16  command_set_supported_82;   ///< word 82
 172   UINT16  command_set_supported_83;   ///< word 83
 173   UINT16  command_set_feature_extn;   ///< word 84
 174   UINT16  command_set_feature_enb_85; ///< word 85
 175   UINT16  command_set_feature_enb_86; ///< word 86
 176   UINT16  command_set_feature_default; ///< word 87
 177   UINT16  ultra_dma_mode;             ///< word 88
 178   UINT16  reserved_89_105[17];
 179   UINT16  phy_logic_sector_support;   ///< word 106
 180   UINT16  reserved_107_116[10];
 181   UINT16  logic_sector_size_lo;       ///< word 117
 182   UINT16  logic_sector_size_hi;       ///< word 118
 183   UINT16  reserved_119_127[9];
 184   UINT16  security_status;
 185   UINT16  vendor_data_129_159[31];
 186   UINT16  reserved_160_208[49];
 187   UINT16  alignment_logic_in_phy_blocks; ///< word 209
 188   UINT16  reserved_210_255[46];
 189 } EFI_ATA_IDENTIFY_DATA;
 190
 191 #pragma pack()
 192 //
 193 //*******************************************************
 194 // EFI_ATAPI_IDENTIFY_DATA
 195 //*******************************************************
 196 //
 197 #pragma pack(1)
 198 typedef struct {
 199     UINT16  config;             ///< General Configuration
 200     UINT16  obsolete_1;
 201     UINT16  specific_config;
 202     UINT16  obsolete_3;
 203     UINT16  retired_4_5[2];
 204     UINT16  obsolete_6;
 205     UINT16  cfa_reserved_7_8[2];
 206     UINT16  retired_9;
 207     CHAR8   SerialNo[20];       ///< ASCII
 208     UINT16  retired_20_21[2];
 209     UINT16  obsolete_22;
 210     CHAR8   FirmwareVer[8];     ///< ASCII
 211     CHAR8   ModelName[40];      ///< ASCII
 212     UINT16  multi_sector_cmd_max_sct_cnt;
 213     UINT16  reserved_48;
 214     UINT16  capabilities_49;
 215     UINT16  capabilities_50;
 216     UINT16  obsolete_51_52[2];
 217     UINT16  field_validity;
 218     UINT16  obsolete_54_58[5];
 219     UINT16  mutil_sector_setting;
 220     UINT16  user_addressable_sectors_lo;
 221     UINT16  user_addressable_sectors_hi;
 222     UINT16  obsolete_62;
 223     UINT16  multi_word_dma_mode;
 224     UINT16  advanced_pio_modes;
 225     UINT16  min_multi_word_dma_cycle_time;
 226     UINT16  rec_multi_word_dma_cycle_time;
 227     UINT16  min_pio_cycle_time_without_flow_control;
 228     UINT16  min_pio_cycle_time_with_flow_control;
 229     UINT16  reserved_69_74[6];
 230     UINT16  queue_depth;
 231     UINT16  reserved_76_79[4];
 232     UINT16  major_version_no;
 233     UINT16  minor_version_no;
 234     UINT16  cmd_set_support_82;
 235     UINT16  cmd_set_support_83;
 236     UINT16  cmd_feature_support;
 237     UINT16  cmd_feature_enable_85;
 238     UINT16  cmd_feature_enable_86;
 239     UINT16  cmd_feature_default;
 240     UINT16  ultra_dma_select;
 241     UINT16  time_required_for_sec_erase;
 242     UINT16  time_required_for_enhanced_sec_erase;
 243     UINT16  current_advanced_power_mgmt_value;
 244     UINT16  master_pwd_revison_code;
 245     UINT16  hardware_reset_result;
 246     UINT16  current_auto_acoustic_mgmt_value;
 247     UINT16  reserved_95_99[5];
 248     UINT16  max_user_lba_for_48bit_addr[4];
 249     UINT16  reserved_104_126[23];
 250     UINT16  removable_media_status_notification_support;
 251     UINT16  security_status;
 252     UINT16  vendor_data_129_159[31];
 253     UINT16  cfa_power_mode;
 254     UINT16  cfa_reserved_161_175[15];
 255     UINT16  current_media_serial_no[30];
 256     UINT16  reserved_206_254[49];
 257     UINT16  integrity_word;
 258 } EFI_ATAPI_IDENTIFY_DATA;
 259
 260 #pragma pack()
 261 //
 262 //*******************************************************
 263 // EFI_IDENTIFY_DATA
 264 //*******************************************************
 265 //
 266 typedef union {
 267   EFI_ATA_IDENTIFY_DATA       AtaData;
 268   EFI_ATAPI_IDENTIFY_DATA     AtapiData;
 269 } EFI_IDENTIFY_DATA;
 270
 271 #define   EFI_ATAPI_DEVICE_IDENTIFY_DATA  0x8000
 272
 273 //
 274 /////////////////////////////////////////////////////////////////////////////////////////
 275 // Function prototype declaration, for ANSI compatability
 276 //
 277 /**
 278   Returns the information about the specified IDE channel.
 279
 280   @param  This                  Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
 281   @param  Channel               Zero-based channel number.
 282   @param  Enabled               TRUE if this channel is enabled. Disabled channels are not scanned
 283                                 to see if any devices are present.
 284   @param  MaxDevices            The maximum number of IDE devices that the bus driver
 285                                 can expect on this channel.
 286
 287   @retval EFI_SUCCESS           Information was returned without any errors.
 288   @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount).
 289
 290 **/
 291 typedef
 292 EFI_STATUS
 293 (EFIAPI *EFI_IDE_CONTROLLER_GET_CHANNEL_INFO)(
 294   IN EFI_IDE_CONTROLLER_INIT_PROTOCOL *This,
 295   IN  UINT8                           Channel,
 296   OUT BOOLEAN                         *Enabled,
 297   OUT UINT8                           *MaxDevices
 298 );
 299
 300 /**
 301   The notifications from the IDE bus driver that it is about to enter a certain
 302   phase of the IDE channel enumeration process.
 303
 304   @param  This                  Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
 305   @param  Phase                 The phase during enumeration.
 306   @param  Channel               Zero-based channel number.
 307
 308   @retval EFI_SUCCESS           The notification was accepted without any errors.
 309   @retval EFI_NOT_SUPPORTED     Phase is not supported.
 310   @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount).
 311   @retval EFI_NOT_READY         This phase cannot be entered at this time.
 312
 313 **/
 314 typedef
 315 EFI_STATUS
 316 (EFIAPI *EFI_IDE_CONTROLLER_NOTIFY_PHASE)(
 317   IN EFI_IDE_CONTROLLER_INIT_PROTOCOL  *This,
 318   IN EFI_IDE_CONTROLLER_ENUM_PHASE     Phase,
 319   IN UINT8                             Channel
 320 );
 321
 322 /**
 323   Submits the device information to the IDE controller driver.
 324
 325   @param  This                  Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
 326   @param  Channel               Zero-based channel number.
 327   @param  Device                Zero-based device number on the Channel.
 328   @param  IdentifyData          The device's response to the ATA IDENTIFY_DEVICE command.
 329
 330   @retval EFI_SUCCESS           The information was accepted without any errors.
 331   @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount).
 332                                 Or Device is invalid.
 333
 334 **/
 335 typedef
 336 EFI_STATUS
 337 (EFIAPI *EFI_IDE_CONTROLLER_SUBMIT_DATA)(
 338   IN EFI_IDE_CONTROLLER_INIT_PROTOCOL *This,
 339   IN  UINT8                           Channel,
 340   IN  UINT8                           Device,
 341   IN  EFI_IDENTIFY_DATA               *IdentifyData
 342 );
 343
 344 /**
 345   Disqualifies specific modes for an IDE device.
 346
 347   @param  This                  Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
 348   @param  Channel               Zero-based channel number.
 349   @param  Device                Zero-based device number on the Channel.
 350   @param  BadModes              The modes that the device does not support and that
 351                                 should be disqualified.
 352
 353   @retval EFI_SUCCESS           The modes were accepted without any errors.
 354   @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount).
 355                                 Or Device is invalid.
 356
 357   @note: Inconsistent with specification here:
 358          Framework Spec IdeCont defined another case to return EFI_INVALID_PARAMETER when
 359          IdentifyData is NULL. However in the function there is no parameter named IdentifyData.
 360          So that should be a typo error in spec.
 361
 362 **/
 363 typedef
 364 EFI_STATUS
 365 (EFIAPI *EFI_IDE_CONTROLLER_DISQUALIFY_MODE)(
 366   IN EFI_IDE_CONTROLLER_INIT_PROTOCOL *This,
 367   IN  UINT8                           Channel,
 368   IN  UINT8                           Device,
 369   IN  EFI_ATA_COLLECTIVE_MODE         *BadModes
 370 );
 371
 372 /**
 373   Returns the information about the optimum modes for the specified IDE device.
 374
 375   @param  This                  Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
 376   @param  Channel               Zero-based channel number.
 377   @param  Device                Zero-based device number on the Channel.
 378   @param  SupportedModes        The optimum modes for the device.
 379
 380   @retval EFI_SUCCESS           SupportedModes was returned.
 381   @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount).
 382                                 Or Device is invalid. Or SupportedModes is NULL.
 383   @retval EFI_NOT_READY         Modes cannot be calculated due to a lack of data.
 384
 385 **/
 386 typedef
 387 EFI_STATUS
 388 (EFIAPI *EFI_IDE_CONTROLLER_CALCULATE_MODE)(
 389   IN EFI_IDE_CONTROLLER_INIT_PROTOCOL *This,
 390   IN  UINT8                           Channel,
 391   IN  UINT8                           Device,
 392   OUT EFI_ATA_COLLECTIVE_MODE         **SupportedModes
 393 );
 394
 395 /**
 396   Commands the IDE controller driver to program the IDE controller hardware
 397   so that the specified device can operate at the specified mode.
 398
 399   @param  This                  Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
 400   @param  Channel               Zero-based channel number.
 401   @param  Device                Zero-based device number on the Channel.
 402   @param  Modes                 The modes to set.
 403
 404   @retval EFI_SUCCESS           The command was accepted without any errors.
 405   @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount).
 406                                 Or Device is invalid.
 407   @retval EFI_NOT_READY         Modes cannot be set at this time due to lack of data.
 408   @retval EFI_DEVICE_ERROR      Modes cannot be set due to hardware failure.
 409                                 The IDE bus driver should not use this device.
 410
 411 **/
 412 typedef
 413 EFI_STATUS
 414 (EFIAPI *EFI_IDE_CONTROLLER_SET_TIMING)(
 415   IN EFI_IDE_CONTROLLER_INIT_PROTOCOL *This,
 416   IN  UINT8                           Channel,
 417   IN  UINT8                           Device,
 418   IN  EFI_ATA_COLLECTIVE_MODE         *Modes
 419 );
 420
 421 //
 422 ////////////////////////////////////////////////////////////////////////////////////////////////////
 423 // Interface structure
 424 // EFI_IDE_CONTROLLER_INIT_PROTOCOL protocol provides the chipset specific information to the IDE bus driver.
 425 // An IDE Bus driver wants to manage an IDE bus and possible IDE devices will have to retrieve the
 426 // EFI_IDE_CONTROLLER_INIT_PROTOCOL instances.
 427 //
 428 /**
 429   Provides the basic interfaces to abstract an IDE controller.
 430 **/
 431 struct _EFI_IDE_CONTROLLER_INIT_PROTOCOL {
 432   ///
 433   /// Returns the information about a specific channel.
 434   ///
 435   EFI_IDE_CONTROLLER_GET_CHANNEL_INFO    GetChannelInfo;
 436
 437   ///
 438   /// The notification that the IDE bus driver is about to enter the
 439   /// specified phase during the enumeration process.
 440   ///
 441   EFI_IDE_CONTROLLER_NOTIFY_PHASE        NotifyPhase;
 442
 443   ///
 444   /// Submits the Drive Identify data that was returned by the device.
 445   ///
 446   EFI_IDE_CONTROLLER_SUBMIT_DATA         SubmitData;
 447
 448   ///
 449   /// Submits information about modes that should be disqualified.
 450   ///
 451   EFI_IDE_CONTROLLER_DISQUALIFY_MODE     DisqualifyMode;
 452
 453   ///
 454   /// Calculates and returns the optimum mode for a particular IDE device.
 455   ///
 456   EFI_IDE_CONTROLLER_CALCULATE_MODE      CalculateMode;
 457
 458   ///
 459   /// Programs the IDE controller hardware to the default timing or per the modes
 460   /// that were returned by the last call to CalculateMode().
 461   ///
 462   EFI_IDE_CONTROLLER_SET_TIMING          SetTiming;
 463
 464   ///
 465   /// Set to TRUE if the enumeration group includes all the channels that are
 466   /// produced by this controller. FALSE if an enumeration group consists of
 467   /// only one channel.
 468   ///
 469   BOOLEAN                                EnumAll;
 470
 471   ///
 472   /// The number of channels that are produced by this controller.
 473   ///
 474   UINT8                                  ChannelCount;
 475 };
 476
 477 extern EFI_GUID gEfiIdeControllerInitProtocolGuid;
 478
 479 #endif