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