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_105[17];
 182   UINT16  phy_logic_sector_support; // word 106
 183   UINT16  reserved_107_116[10];
 184   UINT16  logic_sector_size_lo; // word 117
 185   UINT16  logic_sector_size_hi; // word 118
 186   UINT16  reserved_119_127[9];
 187   UINT16  security_status;
 188   UINT16  vendor_data_129_159[31];
 189   UINT16  reserved_160_208[49];
 190   UINT16  alignment_logic_in_phy_blocks; // word 209
 191   UINT16  reserved_210_255[46];
 192 } EFI_ATA_IDENTIFY_DATA;
 193
 194 #pragma pack()
 195 //
 196 //*******************************************************
 197 // EFI_ATAPI_IDENTIFY_DATA
 198 //*******************************************************
 199 //
 200 #pragma pack(1)
 201 typedef struct {
 202     UINT16  config;             // General Configuration
 203     UINT16  obsolete_1;
 204     UINT16  specific_config;
 205     UINT16  obsolete_3;
 206     UINT16  retired_4_5[2];
 207     UINT16  obsolete_6;
 208     UINT16  cfa_reserved_7_8[2];
 209     UINT16  retired_9;
 210     CHAR8   SerialNo[20];       // ASCII
 211     UINT16  retired_20_21[2];
 212     UINT16  obsolete_22;
 213     CHAR8   FirmwareVer[8];     // ASCII
 214     CHAR8   ModelName[40];      // ASCII
 215     UINT16  multi_sector_cmd_max_sct_cnt;
 216     UINT16  reserved_48;
 217     UINT16  capabilities_49;
 218     UINT16  capabilities_50;
 219     UINT16  obsolete_51_52[2];
 220     UINT16  field_validity;
 221     UINT16  obsolete_54_58[5];
 222     UINT16  mutil_sector_setting;
 223     UINT16  user_addressable_sectors_lo;
 224     UINT16  user_addressable_sectors_hi;
 225     UINT16  obsolete_62;
 226     UINT16  multi_word_dma_mode;
 227     UINT16  advanced_pio_modes;
 228     UINT16  min_multi_word_dma_cycle_time;
 229     UINT16  rec_multi_word_dma_cycle_time;
 230     UINT16  min_pio_cycle_time_without_flow_control;
 231     UINT16  min_pio_cycle_time_with_flow_control;
 232     UINT16  reserved_69_74[6];
 233     UINT16  queue_depth;
 234     UINT16  reserved_76_79[4];
 235     UINT16  major_version_no;
 236     UINT16  minor_version_no;
 237     UINT16  cmd_set_support_82;
 238     UINT16  cmd_set_support_83;
 239     UINT16  cmd_feature_support;
 240     UINT16  cmd_feature_enable_85;
 241     UINT16  cmd_feature_enable_86;
 242     UINT16  cmd_feature_default;
 243     UINT16  ultra_dma_select;
 244     UINT16  time_required_for_sec_erase;
 245     UINT16  time_required_for_enhanced_sec_erase;
 246     UINT16  current_advanced_power_mgmt_value;
 247     UINT16  master_pwd_revison_code;
 248     UINT16  hardware_reset_result;
 249     UINT16  current_auto_acoustic_mgmt_value;
 250     UINT16  reserved_95_99[5];
 251     UINT16  max_user_lba_for_48bit_addr[4];
 252     UINT16  reserved_104_126[23];
 253     UINT16  removable_media_status_notification_support;
 254     UINT16  security_status;
 255     UINT16  vendor_data_129_159[31];
 256     UINT16  cfa_power_mode;
 257     UINT16  cfa_reserved_161_175[15];
 258     UINT16  current_media_serial_no[30];
 259     UINT16  reserved_206_254[49];
 260     UINT16  integrity_word;
 261 } EFI_ATAPI_IDENTIFY_DATA;
 262
 263 #pragma pack()
 264 //
 265 //*******************************************************
 266 // EFI_IDENTIFY_DATA
 267 //*******************************************************
 268 //
 269 typedef union {
 270   EFI_ATA_IDENTIFY_DATA       AtaData;
 271   EFI_ATAPI_IDENTIFY_DATA     AtapiData;
 272 } EFI_IDENTIFY_DATA;
 273
 274 #define   EFI_ATAPI_DEVICE_IDENTIFY_DATA  0x8000
 275
 276 //
 277 /////////////////////////////////////////////////////////////////////////////////////////
 278 // Function prototype declaration, for ANSI compatability
 279 //
 280 /**
 281   Returns the information about the specified IDE channel.
 282
 283   @param  This                  Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
 284   @param  Channel               Zero-based channel number.
 285   @param  Enabled               TRUE if this channel is enabled. Disabled channels are not scanned
 286                                 to see if any devices are present.
 287   @param  MaxDevices            The maximum number of IDE devices that the bus driver
 288                                 can expect on this channel.
 289
 290   @retval EFI_SUCCESS           Information was returned without any errors.
 291   @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount).
 292
 293 **/
 294 typedef
 295 EFI_STATUS
 296 (EFIAPI *EFI_IDE_CONTROLLER_GET_CHANNEL_INFO)(
 297   IN EFI_IDE_CONTROLLER_INIT_PROTOCOL *This,
 298   IN  UINT8                           Channel,
 299   OUT BOOLEAN                         *Enabled,
 300   OUT UINT8                           *MaxDevices
 301 );
 302
 303 /**
 304   The notifications from the IDE bus driver that it is about to enter a certain
 305   phase of the IDE channel enumeration process.
 306
 307   @param  This                  Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
 308   @param  Phase                 The phase during enumeration.
 309   @param  Channel               Zero-based channel number.
 310
 311   @retval EFI_SUCCESS           The notification was accepted without any errors.
 312   @retval EFI_NOT_SUPPORTED     Phase is not supported.
 313   @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount).
 314   @retval EFI_NOT_READY         This phase cannot be entered at this time.
 315
 316 **/
 317 typedef
 318 EFI_STATUS
 319 (EFIAPI *EFI_IDE_CONTROLLER_NOTIFY_PHASE)(
 320   IN EFI_IDE_CONTROLLER_INIT_PROTOCOL  *This,
 321   IN EFI_IDE_CONTROLLER_ENUM_PHASE     Phase,
 322   IN UINT8                             Channel
 323 );
 324
 325 /**
 326   Submits the device information to the IDE controller driver.
 327
 328   @param  This                  Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
 329   @param  Channel               Zero-based channel number.
 330   @param  Device                Zero-based device number on the Channel.
 331   @param  IdentifyData          The device's response to the ATA IDENTIFY_DEVICE command.
 332
 333   @retval EFI_SUCCESS           The information was accepted without any errors.
 334   @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount).
 335                                 Or Device is invalid.
 336
 337 **/
 338 typedef
 339 EFI_STATUS
 340 (EFIAPI *EFI_IDE_CONTROLLER_SUBMIT_DATA)(
 341   IN EFI_IDE_CONTROLLER_INIT_PROTOCOL *This,
 342   IN  UINT8                           Channel,
 343   IN  UINT8                           Device,
 344   IN  EFI_IDENTIFY_DATA               *IdentifyData
 345 );
 346
 347 /**
 348   Disqualifies specific modes for an IDE device.
 349
 350   @param  This                  Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
 351   @param  Channel               Zero-based channel number.
 352   @param  Device                Zero-based device number on the Channel.
 353   @param  BadModes              The modes that the device does not support and that
 354                                 should be disqualified.
 355
 356   @retval EFI_SUCCESS           The modes were accepted without any errors.
 357   @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount).
 358                                 Or Device is invalid.
 359
 360 **/
 361 typedef
 362 EFI_STATUS
 363 (EFIAPI *EFI_IDE_CONTROLLER_DISQUALIFY_MODE)(
 364   IN EFI_IDE_CONTROLLER_INIT_PROTOCOL *This,
 365   IN  UINT8                           Channel,
 366   IN  UINT8                           Device,
 367   IN  EFI_ATA_COLLECTIVE_MODE         *BadModes
 368 );
 369
 370 /**
 371   Returns the information about the optimum modes for the specified IDE device.
 372
 373   @param  This                  Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
 374   @param  Channel               Zero-based channel number.
 375   @param  Device                Zero-based device number on the Channel.
 376   @param  SupportedModes        The optimum modes for the device.
 377
 378   @retval EFI_SUCCESS           SupportedModes was returned.
 379   @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount).
 380                                 Or Device is invalid. Or SupportedModes is NULL.
 381   @retval EFI_NOT_READY         Modes cannot be calculated due to a lack of data.
 382
 383 **/
 384 typedef
 385 EFI_STATUS
 386 (EFIAPI *EFI_IDE_CONTROLLER_CALCULATE_MODE)(
 387   IN EFI_IDE_CONTROLLER_INIT_PROTOCOL *This,
 388   IN  UINT8                           Channel,
 389   IN  UINT8                           Device,
 390   OUT EFI_ATA_COLLECTIVE_MODE         **SupportedModes
 391 );
 392
 393 /**
 394   Commands the IDE controller driver to program the IDE controller hardware
 395   so that the specified device can operate at the specified mode.
 396
 397   @param  This                  Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
 398   @param  Channel               Zero-based channel number.
 399   @param  Device                Zero-based device number on the Channel.
 400   @param  Modes                 The modes to set.
 401
 402   @retval EFI_SUCCESS           The command was accepted without any errors.
 403   @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount).
 404                                 Or Device is invalid.
 405   @retval EFI_NOT_READY         Modes cannot be set at this time due to lack of data.
 406   @retval EFI_DEVICE_ERROR      Modes cannot be set due to hardware failure.
 407                                 The IDE bus driver should not use this device.
 408
 409 **/
 410 typedef
 411 EFI_STATUS
 412 (EFIAPI *EFI_IDE_CONTROLLER_SET_TIMING)(
 413   IN EFI_IDE_CONTROLLER_INIT_PROTOCOL *This,
 414   IN  UINT8                           Channel,
 415   IN  UINT8                           Device,
 416   IN  EFI_ATA_COLLECTIVE_MODE         *Modes
 417 );
 418
 419 //
 420 ////////////////////////////////////////////////////////////////////////////////////////////////////
 421 // Interface structure
 422 // EFI_IDE_CONTROLLER_INIT_PROTOCOL protocol provides the chipset specific information to the IDE bus driver.
 423 // An IDE Bus driver wants to manage an IDE bus and possible IDE devices will have to retrieve the
 424 // EFI_IDE_CONTROLLER_INIT_PROTOCOL instances.
 425 //
 426 /**
 427   @par Protocol Description:
 428   Provides the basic interfaces to abstract an IDE controller.
 429
 430   @param GetChannelInfo
 431   Returns the information about a specific channel.
 432
 433   @param NotifyPhase
 434   The notification that the IDE bus driver is about to enter the
 435   specified phase during the enumeration process.
 436
 437   @param SubmitData
 438   Submits the Drive Identify data that was returned by the device.
 439
 440   @param DisqualifyMode
 441   Submits information about modes that should be disqualified.
 442
 443   @param CalculateMode
 444   Calculates and returns the optimum mode for a particular IDE device.
 445
 446   @param SetTiming
 447   Programs the IDE controller hardware to the default timing or per the modes
 448   that were returned by the last call to CalculateMode().
 449
 450   @param EnumAll
 451   Set to TRUE if the enumeration group includes all the channels that are
 452   produced by this controller. FALSE if an enumeration group consists of
 453   only one channel.
 454
 455   @param ChannelCount
 456   The number of channels that are produced by this controller.
 457
 458 **/
 459 struct _EFI_IDE_CONTROLLER_INIT_PROTOCOL {
 460   EFI_IDE_CONTROLLER_GET_CHANNEL_INFO    GetChannelInfo;
 461   EFI_IDE_CONTROLLER_NOTIFY_PHASE        NotifyPhase;
 462   EFI_IDE_CONTROLLER_SUBMIT_DATA         SubmitData;
 463   EFI_IDE_CONTROLLER_DISQUALIFY_MODE     DisqualifyMode;
 464   EFI_IDE_CONTROLLER_CALCULATE_MODE      CalculateMode;
 465   EFI_IDE_CONTROLLER_SET_TIMING          SetTiming;
 466   BOOLEAN                                EnumAll;
 467   UINT8                                  ChannelCount;
 468 };
 469
 470 extern EFI_GUID gEfiIdeControllerInitProtocolGuid;
 471
 472 #endif