/** @file\r
This file declares EFI IDE Controller Init Protocol\r
-\r
- Copyright (c) 2006, Intel Corporation \r
- All rights reserved. This program and the accompanying materials \r
- are licensed and made available under the terms and conditions of the BSD License \r
- which accompanies this distribution. The full text of the license may be found at \r
- http://opensource.org/licenses/bsd-license.php \r
-\r
- THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
- WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
-\r
- Module Name: IdeControllerInit.h\r
+ \r
+ The EFI_IDE_CONTROLLER_INIT_PROTOCOL provides the chipset-specific information\r
+ to the IDE bus driver. This protocol is mandatory for IDE controllers if the\r
+ IDE devices behind the controller are to be enumerated by an IDE bus driver.\r
+ \r
+ There can only be one instance of EFI_IDE_CONTROLLER_INIT_PROTOCOL for each IDE\r
+ controller in a system. It is installed on the handle that corresponds to the\r
+ IDE controller. An IDE bus driver that wishes to manage an IDE bus and possibly\r
+ IDE devices in a system will have to retrieve the EFI_IDE_CONTROLLER_INIT_PROTOCOL\r
+ instance that is associated with the controller to be managed.\r
+ \r
+ A device handle for an IDE controller must contain an EFI_DEVICE_PATH_PROTOCOL.\r
+\r
+Copyright (c) 2007 - 2010, Intel Corporation. All rights reserved<BR>\r
+This program and the accompanying materials are licensed and made available under \r
+the terms and conditions of the BSD License that accompanies this distribution. \r
+The full text of the license may be found at\r
+http://opensource.org/licenses/bsd-license.php. \r
+ \r
+THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
+WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
@par Revision Reference:\r
- This Protocol is defined in IDE Controller Initialization Protocol Specification\r
- Version 0.9\r
-\r
+ This Protocol is defined in UEFI Platform Initialization Specification 1.2 \r
+ Volume 5: Standards.\r
+ \r
**/\r
\r
-#ifndef _EFI_IDE_CONTROLLER_INIT_PROTOCOL_H\r
-#define _EFI_IDE_CONTROLLER_INIT_PROTOCOL_H\r
+#ifndef _EFI_IDE_CONTROLLER_INIT_PROTOCOL_H_\r
+#define _EFI_IDE_CONTROLLER_INIT_PROTOCOL_H_\r
+\r
+#include <IndustryStandard/Atapi.h>\r
\r
-//\r
-// Global ID for the EFI Platform IDE Protocol GUID\r
-//\r
+///\r
+/// Global ID for the EFI_IDE_CONTROLLER_INIT_PROTOCOL.\r
+///\r
#define EFI_IDE_CONTROLLER_INIT_PROTOCOL_GUID \\r
- { 0xa1e37052, 0x80d9, 0x4e65, {0xa3, 0x17, 0x3e, 0x9a, 0x55, 0xc4, 0x3e, 0xc9 } }\r
+ { \\r
+ 0xa1e37052, 0x80d9, 0x4e65, {0xa3, 0x17, 0x3e, 0x9a, 0x55, 0xc4, 0x3e, 0xc9 } \\r
+ }\r
\r
-//\r
-// Forward reference for pure ANSI compatability\r
-//\r
+///\r
+/// Forward declaration for EFI_IDE_CONTROLLER_INIT_PROTOCOL.\r
+///\r
typedef struct _EFI_IDE_CONTROLLER_INIT_PROTOCOL EFI_IDE_CONTROLLER_INIT_PROTOCOL;\r
\r
-//\r
-//////////////////////////////////////////////////////////////////////////////////////////\r
-// EFI_IDE_BUS_ENUMERATION_PHASE\r
-// EFI_IDE_CONTROLLER_ENUM_PHASE\r
-//\r
-typedef enum{\r
+///\r
+/// The phase of the IDE Controller enumeration.\r
+///\r
+typedef enum {\r
+ ///\r
+ /// The IDE bus driver is about to begin enumerating the devices\r
+ /// behind the specified channel. This notification can be used to\r
+ /// perform any chipset-specific programming.\r
+ ///\r
EfiIdeBeforeChannelEnumeration,\r
+ ///\r
+ /// The IDE bus driver has completed enumerating the devices\r
+ /// behind the specified channel. This notification can be used to\r
+ /// perform any chipset-specific programming.\r
+ ///\r
EfiIdeAfterChannelEnumeration,\r
+ ///\r
+ /// The IDE bus driver is about to reset the devices behind the\r
+ /// specified channel. This notification can be used to perform any\r
+ /// chipset-specific programming.\r
+ ///\r
EfiIdeBeforeChannelReset,\r
+ ///\r
+ /// The IDE bus driver has completed resetting the devices behind\r
+ /// the specified channel. This notification can be used to perform\r
+ /// any chipset-specific programming. \r
+ ///\r
EfiIdeAfterChannelReset,\r
+ ///\r
+ /// The IDE bus driver is about to detect the presence of devices\r
+ /// behind the specified channel. This notification can be used to\r
+ /// set up the bus signals to default levels or for implementing\r
+ /// predelays.\r
+ ///\r
EfiIdeBusBeforeDevicePresenceDetection,\r
+ ///\r
+ /// The IDE bus driver is done with detecting the presence of\r
+ /// devices behind the specified channel. This notification can be\r
+ /// used to perform any chipset-specific programming. \r
+ ///\r
EfiIdeBusAfterDevicePresenceDetection,\r
+ ///\r
+ /// The IDE bus is requesting the IDE controller driver to\r
+ /// reprogram the IDE controller hardware and thereby reset all\r
+ /// the mode and timing settings to default settings. \r
+ ///\r
EfiIdeResetMode,\r
EfiIdeBusPhaseMaximum\r
} EFI_IDE_CONTROLLER_ENUM_PHASE;\r
\r
-//\r
-//******************************************************\r
-// EFI_ATA_EXT_TRANSFER_PROTOCOL\r
-//******************************************************\r
-//\r
-// This extended mode describes the SATA physical protocol.\r
-// SATA physical layers can operate at different speeds. \r
-// These speeds are defined below. Various PATA protocols \r
-// and associated modes are not applicable to SATA devices.\r
-//\r
-\r
+///\r
+/// This extended mode describes the SATA physical protocol.\r
+/// SATA physical layers can operate at different speeds.\r
+/// These speeds are defined below. Various PATA protocols\r
+/// and associated modes are not applicable to SATA devices.\r
+///\r
typedef enum {\r
- EfiAtaSataTransferProtocol \r
+ EfiAtaSataTransferProtocol\r
} EFI_ATA_EXT_TRANSFER_PROTOCOL;\r
\r
+///\r
+/// Automatically detects the optimum SATA speed.\r
+///\r
#define EFI_SATA_AUTO_SPEED 0\r
+\r
+///\r
+/// Indicates a first-generation (Gen1) SATA speed.\r
+///\r
#define EFI_SATA_GEN1_SPEED 1\r
+\r
+///\r
+/// Indicates a second-generation (Gen2) SATA speed.\r
+///\r
#define EFI_SATA_GEN2_SPEED 2\r
\r
-//\r
-//*******************************************************\r
-// EFI_IDE_CABLE_TYPE\r
-//*******************************************************\r
-//\r
-typedef enum {\r
- EfiIdeCableTypeUnknown,\r
- EfiIdeCableType40pin,\r
- EfiIdeCableType80Pin,\r
- EfiIdeCableTypeSerial,\r
- EfiIdeCableTypeMaximum\r
-} EFI_IDE_CABLE_TYPE;\r
-\r
-//\r
-//******************************************************\r
-// EFI_ATA_MODE\r
-//******************************************************\r
-//\r
+///\r
+/// EFI_ATA_MODE structure.\r
+///\r
typedef struct {\r
- BOOLEAN Valid;\r
- UINT32 Mode; \r
+ BOOLEAN Valid; ///< TRUE if Mode is valid.\r
+ UINT32 Mode; ///< The actual ATA mode. This field is not a bit map.\r
} EFI_ATA_MODE;\r
\r
-//\r
-//******************************************************\r
-// EFI_ATA_EXTENDED_MODE\r
-//******************************************************\r
-//\r
+///\r
+/// EFI_ATA_EXTENDED_MODE structure\r
+///\r
typedef struct {\r
+ ///\r
+ /// An enumeration defining various transfer protocols other than the protocols\r
+ /// that exist at the time this specification was developed (i.e., PIO, single \r
+ /// word DMA, multiword DMA, and UDMA). Each transfer protocol is associated \r
+ /// with a mode. The various transfer protocols are defined by the ATA/ATAPI \r
+ /// specification. This enumeration makes the interface extensible because we \r
+ /// can support new transport protocols beyond UDMA. Type EFI_ATA_EXT_TRANSFER_PROTOCOL \r
+ /// is defined below.\r
+ ///\r
EFI_ATA_EXT_TRANSFER_PROTOCOL TransferProtocol;\r
+ ///\r
+ /// The mode for operating the transfer protocol that is identified by TransferProtocol.\r
+ ///\r
UINT32 Mode;\r
} EFI_ATA_EXTENDED_MODE;\r
\r
-//\r
-//******************************************************\r
-// EFI_ATA_COLLECTIVE_MODE\r
-//******************************************************\r
-//\r
+///\r
+/// EFI_ATA_COLLECTIVE_MODE structure.\r
+///\r
typedef struct {\r
- EFI_ATA_MODE PioMode; \r
+ ///\r
+ /// This field specifies the PIO mode. PIO modes are defined in the ATA/ATAPI\r
+ /// specification. The ATA/ATAPI specification defines the enumeration. In \r
+ /// other words, a value of 1 in this field means PIO mode 1. The actual meaning\r
+ /// of PIO mode 1 is governed by the ATA/ATAPI specification. Type EFI_ATA_MODE\r
+ /// is defined below.\r
+ ///\r
+ EFI_ATA_MODE PioMode;\r
+ ///\r
+ /// This field specifies the single word DMA mode. Single word DMA modes are defined\r
+ /// in the ATA/ATAPI specification, versions 1 and 2. Single word DMA support was\r
+ /// obsoleted in the ATA/ATAPI specification, version 3. Therefore, most devices and\r
+ /// controllers will not support this transfer mode. The ATA/ATAPI specification defines\r
+ /// the enumeration. In other words, a value of 1 in this field means single word DMA\r
+ /// mode 1. The actual meaning of single word DMA mode 1 is governed by the ATA/\r
+ /// ATAPI specification. \r
+ ///\r
EFI_ATA_MODE SingleWordDmaMode;\r
+ ///\r
+ /// This field specifies the multiword DMA mode. Various multiword DMA modes are\r
+ /// defined in the ATA/ATAPI specification. A value of 1 in this field means multiword\r
+ /// DMA mode 1. The actual meaning of multiword DMA mode 1 is governed by the\r
+ /// ATA/ATAPI specification. \r
+ ///\r
EFI_ATA_MODE MultiWordDmaMode;\r
+ ///\r
+ /// This field specifies the ultra DMA (UDMA) mode. UDMA modes are defined in the\r
+ /// ATA/ATAPI specification. A value of 1 in this field means UDMA mode 1. The\r
+ /// actual meaning of UDMA mode 1 is governed by the ATA/ATAPI specification. \r
+ ///\r
EFI_ATA_MODE UdmaMode;\r
+ ///\r
+ /// The number of extended-mode bitmap entries. Extended modes describe transfer\r
+ /// protocols beyond PIO, single word DMA, multiword DMA, and UDMA. This field\r
+ /// can be zero and provides extensibility. \r
+ ///\r
UINT32 ExtModeCount;\r
- EFI_ATA_EXTENDED_MODE ExtMode[1]; \r
+ ///\r
+ /// ExtModeCount number of entries. Each entry represents a transfer protocol other\r
+ /// than the ones defined above (i.e., PIO, single word DMA, multiword DMA, and\r
+ /// UDMA). This field is defined for extensibility. At this time, only one extended\r
+ /// transfer protocol is defined to cover SATA transfers. Type\r
+ /// EFI_ATA_EXTENDED_MODE is defined below. \r
+ ///\r
+ EFI_ATA_EXTENDED_MODE ExtMode[1];\r
} EFI_ATA_COLLECTIVE_MODE;\r
\r
-//\r
-//*******************************************************\r
-// EFI_ATA_IDENTIFY_DATA\r
-//*******************************************************\r
-//\r
-\r
-#pragma pack(1)\r
-\r
-typedef struct { \r
- UINT16 config; // General Configuration\r
- UINT16 cylinders; // Number of Cylinders\r
- UINT16 reserved_2;\r
- UINT16 heads; //Number of logical heads\r
- UINT16 vendor_data1;\r
- UINT16 vendor_data2;\r
- UINT16 sectors_per_track;\r
- UINT16 vendor_specific_7_9[3];\r
- CHAR8 SerialNo[20]; // ASCII \r
- UINT16 vendor_specific_20_21[2]; \r
- UINT16 ecc_bytes_available; \r
- CHAR8 FirmwareVer[8]; // ASCII \r
- CHAR8 ModelName[40]; // ASCII \r
- UINT16 multi_sector_cmd_max_sct_cnt;\r
- UINT16 reserved_48;\r
- UINT16 capabilities;\r
- UINT16 reserved_50; \r
- UINT16 pio_cycle_timing; \r
- UINT16 reserved_52; \r
- UINT16 field_validity; \r
- UINT16 current_cylinders;\r
- UINT16 current_heads;\r
- UINT16 current_sectors; \r
- UINT16 CurrentCapacityLsb;\r
- UINT16 CurrentCapacityMsb; \r
- UINT16 reserved_59; \r
- UINT16 user_addressable_sectors_lo;\r
- UINT16 user_addressable_sectors_hi;\r
- UINT16 reserved_62; \r
- UINT16 multi_word_dma_mode; \r
- UINT16 advanced_pio_modes;\r
- UINT16 min_multi_word_dma_cycle_time;\r
- UINT16 rec_multi_word_dma_cycle_time;\r
- UINT16 min_pio_cycle_time_without_flow_control;\r
- UINT16 min_pio_cycle_time_with_flow_control;\r
- UINT16 reserved_69_79[11]; \r
- UINT16 major_version_no;\r
- UINT16 minor_version_no;\r
- UINT16 command_set_supported_82; // word 82\r
- UINT16 command_set_supported_83; // word 83\r
- UINT16 command_set_feature_extn; // word 84\r
- UINT16 command_set_feature_enb_85; // word 85\r
- UINT16 command_set_feature_enb_86; // word 86\r
- UINT16 command_set_feature_default; // word 87\r
- UINT16 ultra_dma_mode; // word 88\r
- UINT16 reserved_89_127[39];\r
- UINT16 security_status;\r
- UINT16 vendor_data_129_159[31];\r
- UINT16 reserved_160_255[96];\r
-} EFI_ATA_IDENTIFY_DATA;\r
-\r
-#pragma pack()\r
-//\r
-//*******************************************************\r
-// EFI_ATAPI_IDENTIFY_DATA\r
-//*******************************************************\r
-//\r
-#pragma pack(1)\r
-typedef struct {\r
- UINT16 config; // General Configuration\r
- UINT16 obsolete_1;\r
- UINT16 specific_config;\r
- UINT16 obsolete_3; \r
- UINT16 retired_4_5[2];\r
- UINT16 obsolete_6; \r
- UINT16 cfa_reserved_7_8[2];\r
- UINT16 retired_9;\r
- CHAR8 SerialNo[20]; // ASCII \r
- UINT16 retired_20_21[2];\r
- UINT16 obsolete_22;\r
- CHAR8 FirmwareVer[8]; // ASCII \r
- CHAR8 ModelName[40]; // ASCII \r
- UINT16 multi_sector_cmd_max_sct_cnt;\r
- UINT16 reserved_48;\r
- UINT16 capabilities_49;\r
- UINT16 capabilities_50;\r
- UINT16 obsolete_51_52[2]; \r
- UINT16 field_validity;\r
- UINT16 obsolete_54_58[5];\r
- UINT16 mutil_sector_setting;\r
- UINT16 user_addressable_sectors_lo;\r
- UINT16 user_addressable_sectors_hi;\r
- UINT16 obsolete_62;\r
- UINT16 multi_word_dma_mode;\r
- UINT16 advanced_pio_modes;\r
- UINT16 min_multi_word_dma_cycle_time;\r
- UINT16 rec_multi_word_dma_cycle_time;\r
- UINT16 min_pio_cycle_time_without_flow_control;\r
- UINT16 min_pio_cycle_time_with_flow_control;\r
- UINT16 reserved_69_74[6];\r
- UINT16 queue_depth;\r
- UINT16 reserved_76_79[4];\r
- UINT16 major_version_no;\r
- UINT16 minor_version_no;\r
- UINT16 cmd_set_support_82;\r
- UINT16 cmd_set_support_83;\r
- UINT16 cmd_feature_support;\r
- UINT16 cmd_feature_enable_85;\r
- UINT16 cmd_feature_enable_86;\r
- UINT16 cmd_feature_default;\r
- UINT16 ultra_dma_select;\r
- UINT16 time_required_for_sec_erase;\r
- UINT16 time_required_for_enhanced_sec_erase;\r
- UINT16 current_advanced_power_mgmt_value;\r
- UINT16 master_pwd_revison_code;\r
- UINT16 hardware_reset_result;\r
- UINT16 current_auto_acoustic_mgmt_value;\r
- UINT16 reserved_95_99[5];\r
- UINT16 max_user_lba_for_48bit_addr[4];\r
- UINT16 reserved_104_126[23];\r
- UINT16 removable_media_status_notification_support;\r
- UINT16 security_status;\r
- UINT16 vendor_data_129_159[31];\r
- UINT16 cfa_power_mode;\r
- UINT16 cfa_reserved_161_175[15];\r
- UINT16 current_media_serial_no[30];\r
- UINT16 reserved_206_254[49];\r
- UINT16 integrity_word;\r
-} EFI_ATAPI_IDENTIFY_DATA;\r
-\r
-#pragma pack()\r
-//\r
-//*******************************************************\r
-// EFI_IDENTIFY_DATA\r
-//*******************************************************\r
-//\r
+///\r
+/// EFI_ATA_IDENTIFY_DATA & EFI_ATAPI_IDENTIFY_DATA structure\r
+///\r
+/// The definition of these two structures is not part of the protocol\r
+/// definition because the ATA/ATAPI Specification controls the definition\r
+/// of all the fields. The ATA/ATAPI Specification can obsolete old fields\r
+/// or redefine existing fields. \r
+typedef ATA_IDENTIFY_DATA EFI_ATA_IDENTIFY_DATA;\r
+typedef ATAPI_IDENTIFY_DATA EFI_ATAPI_IDENTIFY_DATA;\r
+\r
+///\r
+/// This flag indicates whether the IDENTIFY data is a response from an ATA device\r
+/// (EFI_ATA_IDENTIFY_DATA) or response from an ATAPI device \r
+/// (EFI_ATAPI_IDENTIFY_DATA). According to the ATA/ATAPI specification,\r
+/// EFI_IDENTIFY_DATA is for an ATA device if bit 15 of the Config field is zero. \r
+/// The Config field is common to both EFI_ATA_IDENTIFY_DATA and \r
+/// EFI_ATAPI_IDENTIFY_DATA.\r
+///\r
+#define EFI_ATAPI_DEVICE_IDENTIFY_DATA 0x8000\r
+\r
+///\r
+/// EFI_IDENTIFY_DATA structure.\r
+///\r
typedef union {\r
+ ///\r
+ /// The data that is returned by an ATA device upon successful completion \r
+ /// of the ATA IDENTIFY_DEVICE command. \r
+ ///\r
EFI_ATA_IDENTIFY_DATA AtaData;\r
+ ///\r
+ /// The data that is returned by an ATAPI device upon successful completion\r
+ /// of the ATA IDENTIFY_PACKET_DEVICE command.\r
+ ///\r
EFI_ATAPI_IDENTIFY_DATA AtapiData;\r
-} EFI_IDENTIFY_DATA; \r
-\r
-#define EFI_ATAPI_DEVICE_IDENTIFY_DATA 0x8000\r
+} EFI_IDENTIFY_DATA;\r
\r
-//\r
-/////////////////////////////////////////////////////////////////////////////////////////\r
-// Function prototype declaration, for ANSI compatability\r
-//\r
/**\r
- Returns the information about the specified IDE channel. \r
-\r
- @param This Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.\r
- @param Channel Zero-based channel number.\r
- @param Enabled TRUE if this channel is enabled. Disabled channels are not scanned\r
- to see if any devices are present.\r
- @param MaxDevices The maximum number of IDE devices that the bus driver\r
- can expect on this channel.\r
-\r
- @retval EFI_SUCCESS Information was returned without any errors.\r
- @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount).\r
+ Returns the information about the specified IDE channel.\r
+ \r
+ This function can be used to obtain information about a particular IDE channel.\r
+ The IDE bus driver uses this information during the enumeration process. \r
+ \r
+ If Enabled is set to FALSE, the IDE bus driver will not scan the channel. Note \r
+ that it will not prevent an operating system driver from scanning the channel.\r
+ \r
+ For most of today's controllers, MaxDevices will either be 1 or 2. For SATA \r
+ controllers, this value will always be 1. SATA configurations can contain SATA \r
+ port multipliers. SATA port multipliers behave like SATA bridges and can support\r
+ up to 16 devices on the other side. If a SATA port out of the IDE controller \r
+ is connected to a port multiplier, MaxDevices will be set to the number of SATA \r
+ devices that the port multiplier supports. Because today's port multipliers \r
+ support up to fifteen SATA devices, this number can be as large as fifteen. The IDE \r
+ bus driver is required to scan for the presence of port multipliers behind an SATA \r
+ controller and enumerate up to MaxDevices number of devices behind the port \r
+ multiplier. \r
+ \r
+ In this context, the devices behind a port multiplier constitute a channel. \r
+ \r
+ @param[in] This The pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.\r
+ @param[in] Channel Zero-based channel number.\r
+ @param[out] Enabled TRUE if this channel is enabled. Disabled channels \r
+ are not scanned to see if any devices are present.\r
+ @param[out] MaxDevices The maximum number of IDE devices that the bus driver\r
+ can expect on this channel. For the ATA/ATAPI \r
+ specification, version 6, this number will either be \r
+ one or two. For Serial ATA (SATA) configurations with a \r
+ port multiplier, this number can be as large as fifteen.\r
+\r
+ @retval EFI_SUCCESS Information was returned without any errors.\r
+ @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount).\r
\r
**/\r
-typedef \r
+typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_IDE_CONTROLLER_GET_CHANNEL_INFO) (\r
- IN EFI_IDE_CONTROLLER_INIT_PROTOCOL *This,\r
- IN UINT8 Channel, \r
- OUT BOOLEAN *Enabled,\r
- OUT UINT8 *MaxDevices\r
-);\r
+(EFIAPI *EFI_IDE_CONTROLLER_GET_CHANNEL_INFO)(\r
+ IN EFI_IDE_CONTROLLER_INIT_PROTOCOL *This,\r
+ IN UINT8 Channel,\r
+ OUT BOOLEAN *Enabled,\r
+ OUT UINT8 *MaxDevices\r
+ );\r
\r
/**\r
- The notifications from the IDE bus driver that it is about to enter a certain \r
- phase of the IDE channel enumeration process. \r
-\r
- @param This Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.\r
- @param Phase The phase during enumeration.\r
- @param Channel Zero-based channel number.\r
-\r
- @retval EFI_SUCCESS The notification was accepted without any errors.\r
- @retval EFI_NOT_SUPPORTED Phase is not supported.\r
- @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount).\r
- @retval EFI_NOT_READY This phase cannot be entered at this time.\r
+ The notifications from the IDE bus driver that it is about to enter a certain\r
+ phase of the IDE channel enumeration process.\r
+ \r
+ This function can be used to notify the IDE controller driver to perform \r
+ specific actions, including any chipset-specific initialization, so that the \r
+ chipset is ready to enter the next phase. Seven notification points are defined \r
+ at this time. \r
+ \r
+ More synchronization points may be added as required in the future. \r
+\r
+ @param[in] This The pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.\r
+ @param[in] Phase The phase during enumeration.\r
+ @param[in] Channel Zero-based channel number.\r
+\r
+ @retval EFI_SUCCESS The notification was accepted without any errors.\r
+ @retval EFI_NOT_SUPPORTED Phase is not supported.\r
+ @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount).\r
+ @retval EFI_NOT_READY This phase cannot be entered at this time; for \r
+ example, an attempt was made to enter a Phase \r
+ without having entered one or more previous \r
+ Phase.\r
\r
**/\r
-typedef \r
+typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_IDE_CONTROLLER_NOTIFY_PHASE) (\r
+(EFIAPI *EFI_IDE_CONTROLLER_NOTIFY_PHASE)(\r
IN EFI_IDE_CONTROLLER_INIT_PROTOCOL *This,\r
IN EFI_IDE_CONTROLLER_ENUM_PHASE Phase,\r
IN UINT8 Channel\r
-);\r
+ );\r
\r
/**\r
- Submits the device information to the IDE controller driver. \r
-\r
- @param This Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.\r
- @param Channel Zero-based channel number.\r
- @param Device Zero-based device number on the Channel.\r
- @param IdentifyData The device¡¯s response to the ATA IDENTIFY_DEVICE command.\r
-\r
- @retval EFI_SUCCESS The information was accepted without any errors.\r
- @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount).\r
- Or Device is invalid.\r
+ Submits the device information to the IDE controller driver.\r
+\r
+ This function is used by the IDE bus driver to pass detailed information about \r
+ a particular device to the IDE controller driver. The IDE bus driver obtains \r
+ this information by issuing an ATA or ATAPI IDENTIFY_DEVICE command. IdentifyData\r
+ is the pointer to the response data buffer. The IdentifyData buffer is owned \r
+ by the IDE bus driver, and the IDE controller driver must make a local copy \r
+ of the entire buffer or parts of the buffer as needed. The original IdentifyData \r
+ buffer pointer may not be valid when\r
+ \r
+ - EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode() or\r
+ - EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode() is called at a later point.\r
+ \r
+ The IDE controller driver may consult various fields of EFI_IDENTIFY_DATA to \r
+ compute the optimum mode for the device. These fields are not limited to the \r
+ timing information. For example, an implementation of the IDE controller driver \r
+ may examine the vendor and type/mode field to match known bad drives. \r
+ \r
+ The IDE bus driver may submit drive information in any order, as long as it \r
+ submits information for all the devices belonging to the enumeration group \r
+ before EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode() is called for any device\r
+ in that enumeration group. If a device is absent, EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData()\r
+ should be called with IdentifyData set to NULL. The IDE controller driver may \r
+ not have any other mechanism to know whether a device is present or not. Therefore, \r
+ setting IdentifyData to NULL does not constitute an error condition. \r
+ EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData() can be called only once for a \r
+ given (Channel, Device) pair. \r
+ \r
+ @param[in] This A pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.\r
+ @param[in] Channel Zero-based channel number.\r
+ @param[in] Device Zero-based device number on the Channel.\r
+ @param[in] IdentifyData The device's response to the ATA IDENTIFY_DEVICE command.\r
+\r
+ @retval EFI_SUCCESS The information was accepted without any errors.\r
+ @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount).\r
+ @retval EFI_INVALID_PARAMETER Device is invalid.\r
\r
**/\r
-typedef \r
+typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_IDE_CONTROLLER_SUBMIT_DATA) (\r
- IN EFI_IDE_CONTROLLER_INIT_PROTOCOL *This,\r
- IN UINT8 Channel,\r
- IN UINT8 Device,\r
- IN EFI_IDENTIFY_DATA *IdentifyData\r
-);\r
+(EFIAPI *EFI_IDE_CONTROLLER_SUBMIT_DATA)(\r
+ IN EFI_IDE_CONTROLLER_INIT_PROTOCOL *This,\r
+ IN UINT8 Channel,\r
+ IN UINT8 Device,\r
+ IN EFI_IDENTIFY_DATA *IdentifyData\r
+ );\r
\r
/**\r
- Disqualifies specific modes for an IDE device. \r
-\r
- @param This Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.\r
- @param Channel Zero-based channel number.\r
- @param Device Zero-based device number on the Channel.\r
- @param BadModes The modes that the device does not support and that\r
- should be disqualified.\r
-\r
- @retval EFI_SUCCESS The modes were accepted without any errors.\r
- @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount).\r
- Or Device is invalid.\r
-\r
+ Disqualifies specific modes for an IDE device.\r
+\r
+ This function allows the IDE bus driver or other drivers (such as platform \r
+ drivers) to reject certain timing modes and request the IDE controller driver\r
+ to recalculate modes. This function allows the IDE bus driver and the IDE \r
+ controller driver to negotiate the timings on a per-device basis. This function \r
+ is useful in the case of drives that lie about their capabilities. An example \r
+ is when the IDE device fails to accept the timing modes that are calculated \r
+ by the IDE controller driver based on the response to the Identify Drive command.\r
+\r
+ If the IDE bus driver does not want to limit the ATA timing modes and leave that \r
+ decision to the IDE controller driver, it can either not call this function for \r
+ the given device or call this function and set the Valid flag to FALSE for all \r
+ modes that are listed in EFI_ATA_COLLECTIVE_MODE.\r
+ \r
+ The IDE bus driver may disqualify modes for a device in any order and any number \r
+ of times.\r
+ \r
+ This function can be called multiple times to invalidate multiple modes of the \r
+ same type (e.g., Programmed Input/Output [PIO] modes 3 and 4). See the ATA/ATAPI \r
+ specification for more information on PIO modes. \r
+ \r
+ For Serial ATA (SATA) controllers, this member function can be used to disqualify\r
+ a higher transfer rate mode on a given channel. For example, a platform driver\r
+ may inform the IDE controller driver to not use second-generation (Gen2) speeds \r
+ for a certain SATA drive.\r
+ \r
+ @param[in] This The pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.\r
+ @param[in] Channel The zero-based channel number.\r
+ @param[in] Device The zero-based device number on the Channel.\r
+ @param[in] BadModes The modes that the device does not support and that\r
+ should be disqualified.\r
+\r
+ @retval EFI_SUCCESS The modes were accepted without any errors.\r
+ @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount).\r
+ @retval EFI_INVALID_PARAMETER Device is invalid.\r
+ @retval EFI_INVALID_PARAMETER IdentifyData is NULL.\r
+ \r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_IDE_CONTROLLER_DISQUALIFY_MODE) (\r
- IN EFI_IDE_CONTROLLER_INIT_PROTOCOL *This,\r
- IN UINT8 Channel,\r
- IN UINT8 Device,\r
- IN EFI_ATA_COLLECTIVE_MODE *BadModes\r
-);\r
+(EFIAPI *EFI_IDE_CONTROLLER_DISQUALIFY_MODE)(\r
+ IN EFI_IDE_CONTROLLER_INIT_PROTOCOL *This,\r
+ IN UINT8 Channel,\r
+ IN UINT8 Device,\r
+ IN EFI_ATA_COLLECTIVE_MODE *BadModes\r
+ );\r
\r
/**\r
Returns the information about the optimum modes for the specified IDE device.\r
\r
- @param This Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.\r
- @param Channel Zero-based channel number.\r
- @param Device Zero-based device number on the Channel.\r
- @param SupportedModes The optimum modes for the device.\r
-\r
- @retval EFI_SUCCESS SupportedModes was returned.\r
- @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount).\r
- Or Device is invalid. Or SupportedModes is NULL.\r
- @retval EFI_NOT_READY Modes cannot be calculated due to a lack of data.\r
+ This function is used by the IDE bus driver to obtain the optimum ATA modes for\r
+ a specific device. The IDE controller driver takes into account the following \r
+ while calculating the mode:\r
+ - The IdentifyData inputs to EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData()\r
+ - The BadModes inputs to EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode()\r
+\r
+ The IDE bus driver is required to call EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData() \r
+ for all the devices that belong to an enumeration group before calling \r
+ EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode() for any device in the same group. \r
+ \r
+ The IDE controller driver will use controller- and possibly platform-specific \r
+ algorithms to arrive at SupportedModes. The IDE controller may base its \r
+ decision on user preferences and other considerations as well. This function \r
+ may be called multiple times because the IDE bus driver may renegotiate the mode \r
+ with the IDE controller driver using EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode().\r
+ \r
+ The IDE bus driver may collect timing information for various devices in any \r
+ order. The IDE bus driver is responsible for making sure that all the dependencies\r
+ are satisfied. For example, the SupportedModes information for device A that \r
+ was previously returned may become stale after a call to \r
+ EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode() for device B.\r
+ \r
+ The buffer SupportedModes is allocated by the callee because the caller does \r
+ not necessarily know the size of the buffer. The type EFI_ATA_COLLECTIVE_MODE \r
+ is defined in a way that allows for future extensibility and can be of variable \r
+ length. This memory pool should be deallocated by the caller when it is no \r
+ longer necessary. \r
+ \r
+ The IDE controller driver for a Serial ATA (SATA) controller can use this \r
+ member function to force a lower speed (first-generation [Gen1] speeds on a \r
+ second-generation [Gen2]-capable hardware). The IDE controller driver can \r
+ also allow the IDE bus driver to stay with the speed that has been negotiated \r
+ by the physical layer.\r
+ \r
+ @param[in] This The pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.\r
+ @param[in] Channel A zero-based channel number.\r
+ @param[in] Device A zero-based device number on the Channel.\r
+ @param[out] SupportedModes The optimum modes for the device.\r
+\r
+ @retval EFI_SUCCESS SupportedModes was returned.\r
+ @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount).\r
+ @retval EFI_INVALID_PARAMETER Device is invalid. \r
+ @retval EFI_INVALID_PARAMETER SupportedModes is NULL.\r
+ @retval EFI_NOT_READY Modes cannot be calculated due to a lack of \r
+ data. This error may happen if \r
+ EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData() \r
+ and EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyData() \r
+ were not called for at least one drive in the \r
+ same enumeration group.\r
\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_IDE_CONTROLLER_CALCULATE_MODE) (\r
- IN EFI_IDE_CONTROLLER_INIT_PROTOCOL *This,\r
- IN UINT8 Channel,\r
- IN UINT8 Device,\r
- OUT EFI_ATA_COLLECTIVE_MODE **SupportedModes\r
-);\r
+(EFIAPI *EFI_IDE_CONTROLLER_CALCULATE_MODE)(\r
+ IN EFI_IDE_CONTROLLER_INIT_PROTOCOL *This,\r
+ IN UINT8 Channel,\r
+ IN UINT8 Device,\r
+ OUT EFI_ATA_COLLECTIVE_MODE **SupportedModes\r
+ );\r
\r
/**\r
- Commands the IDE controller driver to program the IDE controller hardware \r
- so that the specified device can operate at the specified mode. \r
-\r
- @param This Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.\r
- @param Channel Zero-based channel number.\r
- @param Device Zero-based device number on the Channel.\r
- @param Modes The modes to set.\r
-\r
- @retval EFI_SUCCESS The command was accepted without any errors.\r
- @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount).\r
- Or Device is invalid.\r
- @retval EFI_NOT_READY Modes cannot be set at this time due to lack of data.\r
- @retval EFI_DEVICE_ERROR Modes cannot be set due to hardware failure.\r
- The IDE bus driver should not use this device.\r
+ Commands the IDE controller driver to program the IDE controller hardware\r
+ so that the specified device can operate at the specified mode.\r
+\r
+ This function is used by the IDE bus driver to instruct the IDE controller \r
+ driver to program the IDE controller hardware to the specified modes. This \r
+ function can be called only once for a particular device. For a Serial ATA \r
+ (SATA) Advanced Host Controller Interface (AHCI) controller, no controller-\r
+ specific programming may be required.\r
+\r
+ @param[in] This Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.\r
+ @param[in] Channel Zero-based channel number.\r
+ @param[in] Device Zero-based device number on the Channel.\r
+ @param[in] Modes The modes to set.\r
+\r
+ @retval EFI_SUCCESS The command was accepted without any errors.\r
+ @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount).\r
+ @retval EFI_INVALID_PARAMETER Device is invalid.\r
+ @retval EFI_NOT_READY Modes cannot be set at this time due to lack of data.\r
+ @retval EFI_DEVICE_ERROR Modes cannot be set due to hardware failure.\r
+ The IDE bus driver should not use this device.\r
\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_IDE_CONTROLLER_SET_TIMING) (\r
- IN EFI_IDE_CONTROLLER_INIT_PROTOCOL *This,\r
- IN UINT8 Channel,\r
- IN UINT8 Device,\r
- IN EFI_ATA_COLLECTIVE_MODE *Modes\r
-);\r
-\r
-//\r
-////////////////////////////////////////////////////////////////////////////////////////////////////\r
-// Interface structure \r
-// EFI_IDE_CONTROLLER_INIT_PROTOCOL protocol provides the chipset specific information to the IDE bus driver.\r
-// An IDE Bus driver wants to manage an IDE bus and possible IDE devices will have to retrieve the \r
-// EFI_IDE_CONTROLLER_INIT_PROTOCOL instances.\r
-//\r
-/**\r
- @par Protocol Description:\r
- Provides the basic interfaces to abstract an IDE controller.\r
-\r
- @param GetChannelInfo\r
- Returns the information about a specific channel. \r
-\r
- @param NotifyPhase\r
- The notification that the IDE bus driver is about to enter the \r
- specified phase during the enumeration process. \r
-\r
- @param SubmitData \r
- Submits the Drive Identify data that was returned by the device. \r
-\r
- @param DisqualifyMode \r
- Submits information about modes that should be disqualified. \r
-\r
- @param CalculateMode \r
- Calculates and returns the optimum mode for a particular IDE device.\r
-\r
- @param SetTiming \r
- Programs the IDE controller hardware to the default timing or per the modes \r
- that were returned by the last call to CalculateMode().\r
-\r
- @param EnumAll \r
- Set to TRUE if the enumeration group includes all the channels that are \r
- produced by this controller. FALSE if an enumeration group consists of \r
- only one channel. \r
-\r
- @param ChannelCount\r
- The number of channels that are produced by this controller.\r
-\r
-**/\r
+(EFIAPI *EFI_IDE_CONTROLLER_SET_TIMING)(\r
+ IN EFI_IDE_CONTROLLER_INIT_PROTOCOL *This,\r
+ IN UINT8 Channel,\r
+ IN UINT8 Device,\r
+ IN EFI_ATA_COLLECTIVE_MODE *Modes\r
+ );\r
+\r
+///\r
+/// Provides the basic interfaces to abstract an IDE controller.\r
+///\r
struct _EFI_IDE_CONTROLLER_INIT_PROTOCOL {\r
+ ///\r
+ /// Returns the information about a specific channel.\r
+ ///\r
EFI_IDE_CONTROLLER_GET_CHANNEL_INFO GetChannelInfo;\r
+ \r
+ ///\r
+ /// The notification that the IDE bus driver is about to enter the\r
+ /// specified phase during the enumeration process. \r
+ ///\r
EFI_IDE_CONTROLLER_NOTIFY_PHASE NotifyPhase;\r
+ \r
+ ///\r
+ /// Submits the Drive Identify data that was returned by the device.\r
+ ///\r
EFI_IDE_CONTROLLER_SUBMIT_DATA SubmitData;\r
+ \r
+ ///\r
+ /// Submits information about modes that should be disqualified. The specified \r
+ /// IDE device does not support these modes and these modes should not be \r
+ /// returned by EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode()\r
+ ///\r
EFI_IDE_CONTROLLER_DISQUALIFY_MODE DisqualifyMode;\r
+ \r
+ ///\r
+ /// Calculates and returns the optimum mode for a particular IDE device.\r
+ ///\r
EFI_IDE_CONTROLLER_CALCULATE_MODE CalculateMode;\r
+ \r
+ ///\r
+ /// Programs the IDE controller hardware to the default timing or per the modes\r
+ /// that were returned by the last call to EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode(). \r
+ ///\r
EFI_IDE_CONTROLLER_SET_TIMING SetTiming;\r
+ \r
+ ///\r
+ /// Set to TRUE if the enumeration group includes all the channels that are\r
+ /// produced by this controller. Set to FALSE if an enumeration group consists of\r
+ /// only one channel. \r
+ ///\r
BOOLEAN EnumAll;\r
- UINT8 ChannelCount; \r
+ \r
+ ///\r
+ /// The number of channels that are produced by this controller. Parallel ATA\r
+ /// (PATA) controllers can support up to two channels. Advanced Host Controller \r
+ /// Interface (AHCI) Serial ATA (SATA) controllers can support up to 32 channels,\r
+ /// each of which can have up to one device. In the presence of a multiplier, \r
+ /// each channel can have fifteen devices.\r
+ ///\r
+ UINT8 ChannelCount;\r
};\r
\r
extern EFI_GUID gEfiIdeControllerInitProtocolGuid;\r
\r
#endif\r
-\r
-\r
projects / mirror_edk2.git / blobdiff