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