--- /dev/null
+/** @file\r
+ This file declares EFI IDE Controller Init Protocol\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 - 2009, 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
+ @par Revision Reference:\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
+\r
+///\r
+/// Global ID for the EFI_IDE_CONTROLLER_INIT_PROTOCOL\r
+///\r
+#define EFI_IDE_CONTROLLER_INIT_PROTOCOL_GUID \\r
+ { \\r
+ 0xa1e37052, 0x80d9, 0x4e65, {0xa3, 0x17, 0x3e, 0x9a, 0x55, 0xc4, 0x3e, 0xc9 } \\r
+ }\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
+/// 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
+/// 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
+} 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
+/// EFI_ATA_MODE structure\r
+///\r
+typedef struct {\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
+/// 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
+/// EFI_ATA_COLLECTIVE_MODE structure\r
+///\r
+typedef struct {\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
+ ///\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
+/// EFI_ATA_IDENTIFY_DATA structure\r
+///\r
+/// This structure definition is not part of the protocol\r
+/// definition because the ATA/ATAPI Specification controls\r
+/// the definition of all the fields. The ATA/ATAPI\r
+/// Specification can obsolete old fields or redefine existing\r
+/// fields. This definition is provided here for reference only.\r
+///\r
+#pragma pack(1)\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_105[17];\r
+ UINT16 phy_logic_sector_support; ///< word 106\r
+ UINT16 reserved_107_116[10];\r
+ UINT16 logic_sector_size_lo; ///< word 117\r
+ UINT16 logic_sector_size_hi; ///< word 118\r
+ UINT16 reserved_119_127[9];\r
+ UINT16 security_status;\r
+ UINT16 vendor_data_129_159[31];\r
+ UINT16 reserved_160_208[49];\r
+ UINT16 alignment_logic_in_phy_blocks; ///< word 209\r
+ UINT16 reserved_210_255[46];\r
+} EFI_ATA_IDENTIFY_DATA;\r
+#pragma pack()\r
+\r
+///\r
+/// EFI_ATAPI_IDENTIFY_DATA structure\r
+///\r
+/// This structure definition is not part of the protocol\r
+/// definition because the ATA/ATAPI Specification controls\r
+/// the definition of all the fields. The ATA/ATAPI\r
+/// Specification can obsolete old fields or redefine existing\r
+/// fields. This definition is provided here for reference only.\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
+#pragma pack()\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
+/**\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 an 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 15 SATA devices, this number can be as large as 15. The IDE bus \r
+ 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 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
+ 1 or 2. For Serial ATA (SATA) configurations with a \r
+ port multiplier, this number can be as large as 15.\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
+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
+\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
+ 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 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
+EFI_STATUS\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
+ 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 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
+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
+\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 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] 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
+\r
+/**\r
+ Returns the information about the optimum modes for the specified IDE device.\r
+\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 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[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
+\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
+ 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
+/// 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. FALSE if an enumeration group consists of\r
+ /// only one channel. \r
+ ///\r
+ BOOLEAN EnumAll;\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 15 devices.\r
+ ///\r
+ UINT8 ChannelCount;\r
+};\r
+\r
+extern EFI_GUID gEfiIdeControllerInitProtocolGuid;\r
+\r
+#endif\r
projects / mirror_edk2.git / blobdiff