From 73c31a3d5e7a2c401f839cf5eea82c39d4a08ec4 Mon Sep 17 00:00:00 2001 From: mdkinney Date: Tue, 14 Jul 2009 19:33:32 +0000 Subject: [PATCH] Add the following PI 1.2 Protocols to the MdePkg 1) IDE Controller Init 2) Incompatible PCI Device Support 3) PCI Hot Bridge Resource Allocation 4) PCI Hot Plug 5) PCI Platform git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@8940 6f19259b-4bc3-4df7-8a09-765794883524 --- MdePkg/Include/Protocol/IdeControllerInit.h | 696 ++++++++++++++++++ .../Protocol/IncompatiblePciDeviceSupport.h | 173 +++++ .../PciHostBridgeResourceAllocation.h | 421 +++++++++++ MdePkg/Include/Protocol/PciHotPlugInit.h | 278 +++++++ MdePkg/Include/Protocol/PciPlatform.h | 344 +++++++++ MdePkg/MdePkg.dec | 17 +- 6 files changed, 1928 insertions(+), 1 deletion(-) create mode 100644 MdePkg/Include/Protocol/IdeControllerInit.h create mode 100644 MdePkg/Include/Protocol/IncompatiblePciDeviceSupport.h create mode 100644 MdePkg/Include/Protocol/PciHostBridgeResourceAllocation.h create mode 100644 MdePkg/Include/Protocol/PciHotPlugInit.h create mode 100644 MdePkg/Include/Protocol/PciPlatform.h diff --git a/MdePkg/Include/Protocol/IdeControllerInit.h b/MdePkg/Include/Protocol/IdeControllerInit.h new file mode 100644 index 0000000000..b4c5dcb0df --- /dev/null +++ b/MdePkg/Include/Protocol/IdeControllerInit.h @@ -0,0 +1,696 @@ +/** @file + This file declares EFI IDE Controller Init Protocol + + The EFI_IDE_CONTROLLER_INIT_PROTOCOL provides the chipset-specific information + to the IDE bus driver. This protocol is mandatory for IDE controllers if the + IDE devices behind the controller are to be enumerated by an IDE bus driver. + + There can only be one instance of EFI_IDE_CONTROLLER_INIT_PROTOCOL for each IDE + controller in a system. It is installed on the handle that corresponds to the + IDE controller. An IDE bus driver that wishes to manage an IDE bus and possibly + IDE devices in a system will have to retrieve the EFI_IDE_CONTROLLER_INIT_PROTOCOL + instance that is associated with the controller to be managed. + + A device handle for an IDE controller must contain an EFI_DEVICE_PATH_PROTOCOL. + + Copyright (c) 2007 - 2009, Intel Corporation + All rights reserved. This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php + + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + + @par Revision Reference: + This Protocol is defined in UEFI Platform Initialization Specification 1.2 + Volume 5: Standards + +**/ + +#ifndef _EFI_IDE_CONTROLLER_INIT_PROTOCOL_H_ +#define _EFI_IDE_CONTROLLER_INIT_PROTOCOL_H_ + +/// +/// Global ID for the EFI_IDE_CONTROLLER_INIT_PROTOCOL +/// +#define EFI_IDE_CONTROLLER_INIT_PROTOCOL_GUID \ + { \ + 0xa1e37052, 0x80d9, 0x4e65, {0xa3, 0x17, 0x3e, 0x9a, 0x55, 0xc4, 0x3e, 0xc9 } \ + } + +/// +/// Forward declaration for EFI_IDE_CONTROLLER_INIT_PROTOCOL +/// +typedef struct _EFI_IDE_CONTROLLER_INIT_PROTOCOL EFI_IDE_CONTROLLER_INIT_PROTOCOL; + +/// +/// The phase of the IDE Controller enumeration +/// +typedef enum { + /// + /// The IDE bus driver is about to begin enumerating the devices + /// behind the specified channel. This notification can be used to + /// perform any chipset-specific programming. + /// + EfiIdeBeforeChannelEnumeration, + /// + /// The IDE bus driver has completed enumerating the devices + /// behind the specified channel. This notification can be used to + /// perform any chipset-specific programming. + /// + EfiIdeAfterChannelEnumeration, + /// + /// The IDE bus driver is about to reset the devices behind the + /// specified channel. This notification can be used to perform any + /// chipset-specific programming. + /// + EfiIdeBeforeChannelReset, + /// + /// The IDE bus driver has completed resetting the devices behind + /// the specified channel. This notification can be used to perform + /// any chipset-specific programming. + /// + EfiIdeAfterChannelReset, + /// + /// The IDE bus driver is about to detect the presence of devices + /// behind the specified channel. This notification can be used to + /// set up the bus signals to default levels or for implementing + /// predelays. + /// + EfiIdeBusBeforeDevicePresenceDetection, + /// + /// The IDE bus driver is done with detecting the presence of + /// devices behind the specified channel. This notification can be + /// used to perform any chipset-specific programming. + /// + EfiIdeBusAfterDevicePresenceDetection, + /// + /// The IDE bus is requesting the IDE controller driver to + /// reprogram the IDE controller hardware and thereby reset all + /// the mode and timing settings to default settings. + /// + EfiIdeResetMode, + EfiIdeBusPhaseMaximum +} EFI_IDE_CONTROLLER_ENUM_PHASE; + +/// +/// This extended mode describes the SATA physical protocol. +/// SATA physical layers can operate at different speeds. +/// These speeds are defined below. Various PATA protocols +/// and associated modes are not applicable to SATA devices. +/// +typedef enum { + EfiAtaSataTransferProtocol +} EFI_ATA_EXT_TRANSFER_PROTOCOL; + +/// +/// Automatically detects the optimum SATA speed. +/// +#define EFI_SATA_AUTO_SPEED 0 + +/// +/// Indicates a first-generation (Gen1) SATA speed. +/// +#define EFI_SATA_GEN1_SPEED 1 + +/// +/// Indicates a second-generation (Gen2) SATA speed. +/// +#define EFI_SATA_GEN2_SPEED 2 + +/// +/// EFI_ATA_MODE structure +/// +typedef struct { + BOOLEAN Valid; ///< TRUE if Mode is valid. + UINT32 Mode; ///< The actual ATA mode. This field is not a bit map. +} EFI_ATA_MODE; + +/// +/// EFI_ATA_EXTENDED_MODE structure +/// +typedef struct { + /// + /// An enumeration defining various transfer protocols other than the protocols + /// that exist at the time this specification was developed (i.e., PIO, single + /// word DMA, multiword DMA, and UDMA). Each transfer protocol is associated + /// with a mode. The various transfer protocols are defined by the ATA/ATAPI + /// specification. This enumeration makes the interface extensible because we + /// can support new transport protocols beyond UDMA. Type EFI_ATA_EXT_TRANSFER_PROTOCOL + /// is defined below. + /// + EFI_ATA_EXT_TRANSFER_PROTOCOL TransferProtocol; + /// + /// The mode for operating the transfer protocol that is identified by TransferProtocol. + /// + UINT32 Mode; +} EFI_ATA_EXTENDED_MODE; + +/// +/// EFI_ATA_COLLECTIVE_MODE structure +/// +typedef struct { + /// + /// This field specifies the PIO mode. PIO modes are defined in the ATA/ATAPI + /// specification. The ATA/ATAPI specification defines the enumeration. In + /// other words, a value of 1 in this field means PIO mode 1. The actual meaning + /// of PIO mode 1 is governed by the ATA/ATAPI specification. Type EFI_ATA_MODE + /// is defined below. + /// + EFI_ATA_MODE PioMode; + /// + /// This field specifies the single word DMA mode. Single word DMA modes are defined + /// in the ATA/ATAPI specification, versions 1 and 2. Single word DMA support was + /// obsoleted in the ATA/ATAPI specification, version 3; therefore, most devices and + /// controllers will not support this transfer mode. The ATA/ATAPI specification defines + /// the enumeration. In other words, a value of 1 in this field means single word DMA + /// mode 1. The actual meaning of single word DMA mode 1 is governed by the ATA/ + /// ATAPI specification. + /// + EFI_ATA_MODE SingleWordDmaMode; + /// + /// This field specifies the multiword DMA mode. Various multiword DMA modes are + /// defined in the ATA/ATAPI specification. A value of 1 in this field means multiword + /// DMA mode 1. The actual meaning of multiword DMA mode 1 is governed by the + /// ATA/ATAPI specification. + /// + EFI_ATA_MODE MultiWordDmaMode; + /// + /// This field specifies the ultra DMA (UDMA) mode. UDMA modes are defined in the + /// ATA/ATAPI specification. A value of 1 in this field means UDMA mode 1. The + /// actual meaning of UDMA mode 1 is governed by the ATA/ATAPI specification. + /// + EFI_ATA_MODE UdmaMode; + /// + /// The number of extended-mode bitmap entries. Extended modes describe transfer + /// protocols beyond PIO, single word DMA, multiword DMA, and UDMA. This field + /// can be zero and provides extensibility. + /// + UINT32 ExtModeCount; + /// + /// ExtModeCount number of entries. Each entry represents a transfer protocol other + /// than the ones defined above (i.e., PIO, single word DMA, multiword DMA, and + /// UDMA). This field is defined for extensibility. At this time, only one extended + /// transfer protocol is defined to cover SATA transfers. Type + /// EFI_ATA_EXTENDED_MODE is defined below. + /// + EFI_ATA_EXTENDED_MODE ExtMode[1]; +} EFI_ATA_COLLECTIVE_MODE; + +/// +/// EFI_ATA_IDENTIFY_DATA structure +/// +/// This structure definition is not part of the protocol +/// definition because the ATA/ATAPI Specification controls +/// the definition of all the fields. The ATA/ATAPI +/// Specification can obsolete old fields or redefine existing +/// fields. This definition is provided here for reference only. +/// +#pragma pack(1) +typedef struct { + UINT16 config; ///< General Configuration + UINT16 cylinders; ///< Number of Cylinders + UINT16 reserved_2; + UINT16 heads; ///< Number of logical heads + UINT16 vendor_data1; + UINT16 vendor_data2; + UINT16 sectors_per_track; + UINT16 vendor_specific_7_9[3]; + CHAR8 SerialNo[20]; ///< ASCII + UINT16 vendor_specific_20_21[2]; + UINT16 ecc_bytes_available; + CHAR8 FirmwareVer[8]; ///< ASCII + CHAR8 ModelName[40]; ///< ASCII + UINT16 multi_sector_cmd_max_sct_cnt; + UINT16 reserved_48; + UINT16 capabilities; + UINT16 reserved_50; + UINT16 pio_cycle_timing; + UINT16 reserved_52; + UINT16 field_validity; + UINT16 current_cylinders; + UINT16 current_heads; + UINT16 current_sectors; + UINT16 CurrentCapacityLsb; + UINT16 CurrentCapacityMsb; + UINT16 reserved_59; + UINT16 user_addressable_sectors_lo; + UINT16 user_addressable_sectors_hi; + UINT16 reserved_62; + UINT16 multi_word_dma_mode; + UINT16 advanced_pio_modes; + UINT16 min_multi_word_dma_cycle_time; + UINT16 rec_multi_word_dma_cycle_time; + UINT16 min_pio_cycle_time_without_flow_control; + UINT16 min_pio_cycle_time_with_flow_control; + UINT16 reserved_69_79[11]; + UINT16 major_version_no; + UINT16 minor_version_no; + UINT16 command_set_supported_82; ///< word 82 + UINT16 command_set_supported_83; ///< word 83 + UINT16 command_set_feature_extn; ///< word 84 + UINT16 command_set_feature_enb_85; ///< word 85 + UINT16 command_set_feature_enb_86; ///< word 86 + UINT16 command_set_feature_default; ///< word 87 + UINT16 ultra_dma_mode; ///< word 88 + UINT16 reserved_89_105[17]; + UINT16 phy_logic_sector_support; ///< word 106 + UINT16 reserved_107_116[10]; + UINT16 logic_sector_size_lo; ///< word 117 + UINT16 logic_sector_size_hi; ///< word 118 + UINT16 reserved_119_127[9]; + UINT16 security_status; + UINT16 vendor_data_129_159[31]; + UINT16 reserved_160_208[49]; + UINT16 alignment_logic_in_phy_blocks; ///< word 209 + UINT16 reserved_210_255[46]; +} EFI_ATA_IDENTIFY_DATA; +#pragma pack() + +/// +/// EFI_ATAPI_IDENTIFY_DATA structure +/// +/// This structure definition is not part of the protocol +/// definition because the ATA/ATAPI Specification controls +/// the definition of all the fields. The ATA/ATAPI +/// Specification can obsolete old fields or redefine existing +/// fields. This definition is provided here for reference only. +/// +#pragma pack(1) +typedef struct { + UINT16 config; ///< General Configuration + UINT16 obsolete_1; + UINT16 specific_config; + UINT16 obsolete_3; + UINT16 retired_4_5[2]; + UINT16 obsolete_6; + UINT16 cfa_reserved_7_8[2]; + UINT16 retired_9; + CHAR8 SerialNo[20]; ///< ASCII + UINT16 retired_20_21[2]; + UINT16 obsolete_22; + CHAR8 FirmwareVer[8]; ///< ASCII + CHAR8 ModelName[40]; ///< ASCII + UINT16 multi_sector_cmd_max_sct_cnt; + UINT16 reserved_48; + UINT16 capabilities_49; + UINT16 capabilities_50; + UINT16 obsolete_51_52[2]; + UINT16 field_validity; + UINT16 obsolete_54_58[5]; + UINT16 mutil_sector_setting; + UINT16 user_addressable_sectors_lo; + UINT16 user_addressable_sectors_hi; + UINT16 obsolete_62; + UINT16 multi_word_dma_mode; + UINT16 advanced_pio_modes; + UINT16 min_multi_word_dma_cycle_time; + UINT16 rec_multi_word_dma_cycle_time; + UINT16 min_pio_cycle_time_without_flow_control; + UINT16 min_pio_cycle_time_with_flow_control; + UINT16 reserved_69_74[6]; + UINT16 queue_depth; + UINT16 reserved_76_79[4]; + UINT16 major_version_no; + UINT16 minor_version_no; + UINT16 cmd_set_support_82; + UINT16 cmd_set_support_83; + UINT16 cmd_feature_support; + UINT16 cmd_feature_enable_85; + UINT16 cmd_feature_enable_86; + UINT16 cmd_feature_default; + UINT16 ultra_dma_select; + UINT16 time_required_for_sec_erase; + UINT16 time_required_for_enhanced_sec_erase; + UINT16 current_advanced_power_mgmt_value; + UINT16 master_pwd_revison_code; + UINT16 hardware_reset_result; + UINT16 current_auto_acoustic_mgmt_value; + UINT16 reserved_95_99[5]; + UINT16 max_user_lba_for_48bit_addr[4]; + UINT16 reserved_104_126[23]; + UINT16 removable_media_status_notification_support; + UINT16 security_status; + UINT16 vendor_data_129_159[31]; + UINT16 cfa_power_mode; + UINT16 cfa_reserved_161_175[15]; + UINT16 current_media_serial_no[30]; + UINT16 reserved_206_254[49]; + UINT16 integrity_word; +} EFI_ATAPI_IDENTIFY_DATA; +#pragma pack() + +/// +/// This flag indicates whether the IDENTIFY data is a response from an ATA device +/// (EFI_ATA_IDENTIFY_DATA) or response from an ATAPI device +/// (EFI_ATAPI_IDENTIFY_DATA). According to the ATA/ATAPI specification, +/// EFI_IDENTIFY_DATA is for an ATA device if bit 15 of the Config field is zero. +/// The Config field is common to both EFI_ATA_IDENTIFY_DATA and +/// EFI_ATAPI_IDENTIFY_DATA. +/// +#define EFI_ATAPI_DEVICE_IDENTIFY_DATA 0x8000 + +/// +/// EFI_IDENTIFY_DATA structure +/// +typedef union { + /// + /// The data that is returned by an ATA device upon successful completion + /// of the ATA IDENTIFY_DEVICE command. + /// + EFI_ATA_IDENTIFY_DATA AtaData; + /// + /// The data that is returned by an ATAPI device upon successful completion + /// of the ATA IDENTIFY_PACKET_DEVICE command. + /// + EFI_ATAPI_IDENTIFY_DATA AtapiData; +} EFI_IDENTIFY_DATA; + +/** + Returns the information about the specified IDE channel. + + This function can be used to obtain information about a particular IDE channel. + The IDE bus driver uses this information during the enumeration process. + + If Enabled is set to FALSE, the IDE bus driver will not scan the channel. Note + that it will not prevent an operating system driver from scanning the channel. + + For most of today's controllers, MaxDevices will either be 1 or 2. For SATA + controllers, this value will always be 1. SATA configurations can contain SATA + port multipliers. SATA port multipliers behave like SATA bridges and can support + up to 16 devices on the other side. If an SATA port out of the IDE controller + is connected to a port multiplier, MaxDevices will be set to the number of SATA + devices that the port multiplier supports. Because today's port multipliers + support up to 15 SATA devices, this number can be as large as 15. The IDE bus + driver is required to scan for the presence of port multipliers behind an SATA + controller and enumerate up to MaxDevices number of devices behind the port + multiplier. + + In this context, the devices behind a port multiplier constitute a channel. + + @param[in] This Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance. + @param[in] Channel Zero-based channel number. + @param[out] Enabled TRUE if this channel is enabled. Disabled channels + are not scanned to see if any devices are present. + @param[out] MaxDevices The maximum number of IDE devices that the bus driver + can expect on this channel. For the ATA/ATAPI + specification, version 6, this number will either be + 1 or 2. For Serial ATA (SATA) configurations with a + port multiplier, this number can be as large as 15. + + @retval EFI_SUCCESS Information was returned without any errors. + @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount). + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_IDE_CONTROLLER_GET_CHANNEL_INFO)( + IN EFI_IDE_CONTROLLER_INIT_PROTOCOL *This, + IN UINT8 Channel, + OUT BOOLEAN *Enabled, + OUT UINT8 *MaxDevices + ); + +/** + The notifications from the IDE bus driver that it is about to enter a certain + phase of the IDE channel enumeration process. + + This function can be used to notify the IDE controller driver to perform + specific actions, including any chipset-specific initialization, so that the + chipset is ready to enter the next phase. Seven notification points are defined + at this time. + + More synchronization points may be added as required in the future. + + @param[in] This Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance. + @param[in] Phase The phase during enumeration. + @param[in] Channel Zero-based channel number. + + @retval EFI_SUCCESS The notification was accepted without any errors. + @retval EFI_NOT_SUPPORTED Phase is not supported. + @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount). + @retval EFI_NOT_READY This phase cannot be entered at this time; for + example, an attempt was made to enter a Phase + without having entered one or more previous + Phase. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_IDE_CONTROLLER_NOTIFY_PHASE)( + IN EFI_IDE_CONTROLLER_INIT_PROTOCOL *This, + IN EFI_IDE_CONTROLLER_ENUM_PHASE Phase, + IN UINT8 Channel + ); + +/** + Submits the device information to the IDE controller driver. + + This function is used by the IDE bus driver to pass detailed information about + a particular device to the IDE controller driver. The IDE bus driver obtains + this information by issuing an ATA or ATAPI IDENTIFY_DEVICE command. IdentifyData + is the pointer to the response data buffer. The IdentifyData buffer is owned + by the IDE bus driver, and the IDE controller driver must make a local copy + of the entire buffer or parts of the buffer as needed. The original IdentifyData + buffer pointer may not be valid when + + - EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode() or + - EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode() is called at a later point. + + The IDE controller driver may consult various fields of EFI_IDENTIFY_DATA to + compute the optimum mode for the device. These fields are not limited to the + timing information. For example, an implementation of the IDE controller driver + may examine the vendor and type/mode field to match known bad drives. + + The IDE bus driver may submit drive information in any order, as long as it + submits information for all the devices belonging to the enumeration group + before EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode() is called for any device + in that enumeration group. If a device is absent, EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData() + should be called with IdentifyData set to NULL. The IDE controller driver may + not have any other mechanism to know whether a device is present or not. Therefore, + setting IdentifyData to NULL does not constitute an error condition. + EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData() can be called only once for a + given (Channel, Device) pair. + + @param[in] This Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance. + @param[in] Channel Zero-based channel number. + @param[in] Device Zero-based device number on the Channel. + @param[in] IdentifyData The device's response to the ATA IDENTIFY_DEVICE command. + + @retval EFI_SUCCESS The information was accepted without any errors. + @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount). + @retval EFI_INVALID_PARAMETER Device is invalid. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_IDE_CONTROLLER_SUBMIT_DATA)( + IN EFI_IDE_CONTROLLER_INIT_PROTOCOL *This, + IN UINT8 Channel, + IN UINT8 Device, + IN EFI_IDENTIFY_DATA *IdentifyData + ); + +/** + Disqualifies specific modes for an IDE device. + + This function allows the IDE bus driver or other drivers (such as platform + drivers) to reject certain timing modes and request the IDE controller driver + to recalculate modes. This function allows the IDE bus driver and the IDE + controller driver to negotiate the timings on a per-device basis. This function + is useful in the case of drives that lie about their capabilities. An example + is when the IDE device fails to accept the timing modes that are calculated + by the IDE controller driver based on the response to the Identify Drive command. + + If the IDE bus driver does not want to limit the ATA timing modes and leave that + decision to the IDE controller driver, it can either not call this function for + the given device or call this function and set the Valid flag to FALSE for all + modes that are listed in EFI_ATA_COLLECTIVE_MODE. + + The IDE bus driver may disqualify modes for a device in any order and any number + of times. + + This function can be called multiple times to invalidate multiple modes of the + same type (e.g., Programmed Input/Output [PIO] modes 3 and 4). See the ATA/ATAPI + specification for more information on PIO modes. + + For Serial ATA (SATA) controllers, this member function can be used to disqualify + a higher transfer rate mode on a given channel. For example, a platform driver + may inform the IDE controller driver to not use second-generation (Gen2) speeds + for a certain SATA drive. + + @param[in] This Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance. + @param[in] Channel Zero-based channel number. + @param[in] Device Zero-based device number on the Channel. + @param[in] BadModes The modes that the device does not support and that + should be disqualified. + + @retval EFI_SUCCESS The modes were accepted without any errors. + @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount). + @retval EFI_INVALID_PARAMETER Device is invalid. + @retval EFI_INVALID_PARAMETER IdentifyData is NULL. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_IDE_CONTROLLER_DISQUALIFY_MODE)( + IN EFI_IDE_CONTROLLER_INIT_PROTOCOL *This, + IN UINT8 Channel, + IN UINT8 Device, + IN EFI_ATA_COLLECTIVE_MODE *BadModes + ); + +/** + Returns the information about the optimum modes for the specified IDE device. + + This function is used by the IDE bus driver to obtain the optimum ATA modes for + a specific device. The IDE controller driver takes into account the following + while calculating the mode: + - The IdentifyData inputs to EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData() + - The BadModes inputs to EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode() + + The IDE bus driver is required to call EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData() + for all the devices that belong to an enumeration group before calling + EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode() for any device in the same group. + + The IDE controller driver will use controller- and possibly platform-specific + algorithms to arrive at SupportedModes. The IDE controller may base its + decision on user preferences and other considerations as well. This function + may be called multiple times because the IDE bus driver may renegotiate the mode + with the IDE controller driver using EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode(). + + The IDE bus driver may collect timing information for various devices in any + order. The IDE bus driver is responsible for making sure that all the dependencies + are satisfied; for example, the SupportedModes information for device A that + was previously returned may become stale after a call to + EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode() for device B. + + The buffer SupportedModes is allocated by the callee because the caller does + not necessarily know the size of the buffer. The type EFI_ATA_COLLECTIVE_MODE + is defined in a way that allows for future extensibility and can be of variable + length. This memory pool should be deallocated by the caller when it is no + longer necessary. + + The IDE controller driver for a Serial ATA (SATA) controller can use this + member function to force a lower speed (first-generation [Gen1] speeds on a + second-generation [Gen2]-capable hardware). The IDE controller driver can + also allow the IDE bus driver to stay with the speed that has been negotiated + by the physical layer. + + @param[in] This Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance. + @param[in] Channel Zero-based channel number. + @param[in] Device Zero-based device number on the Channel. + @param[out] SupportedModes The optimum modes for the device. + + @retval EFI_SUCCESS SupportedModes was returned. + @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount). + @retval EFI_INVALID_PARAMETER Device is invalid. + @retval EFI_INVALID_PARAMETER SupportedModes is NULL. + @retval EFI_NOT_READY Modes cannot be calculated due to a lack of + data. This error may happen if + EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData() + and EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyData() + were not called for at least one drive in the + same enumeration group. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_IDE_CONTROLLER_CALCULATE_MODE)( + IN EFI_IDE_CONTROLLER_INIT_PROTOCOL *This, + IN UINT8 Channel, + IN UINT8 Device, + OUT EFI_ATA_COLLECTIVE_MODE **SupportedModes + ); + +/** + Commands the IDE controller driver to program the IDE controller hardware + so that the specified device can operate at the specified mode. + + This function is used by the IDE bus driver to instruct the IDE controller + driver to program the IDE controller hardware to the specified modes. This + function can be called only once for a particular device. For a Serial ATA + (SATA) Advanced Host Controller Interface (AHCI) controller, no controller- + specific programming may be required. + + @param[in] This Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance. + @param[in] Channel Zero-based channel number. + @param[in] Device Zero-based device number on the Channel. + @param[in] Modes The modes to set. + + @retval EFI_SUCCESS The command was accepted without any errors. + @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount). + @retval EFI_INVALID_PARAMETER Device is invalid. + @retval EFI_NOT_READY Modes cannot be set at this time due to lack of data. + @retval EFI_DEVICE_ERROR Modes cannot be set due to hardware failure. + The IDE bus driver should not use this device. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_IDE_CONTROLLER_SET_TIMING)( + IN EFI_IDE_CONTROLLER_INIT_PROTOCOL *This, + IN UINT8 Channel, + IN UINT8 Device, + IN EFI_ATA_COLLECTIVE_MODE *Modes + ); + +/// +/// Provides the basic interfaces to abstract an IDE controller. +/// +struct _EFI_IDE_CONTROLLER_INIT_PROTOCOL { + /// + /// Returns the information about a specific channel. + /// + EFI_IDE_CONTROLLER_GET_CHANNEL_INFO GetChannelInfo; + + /// + /// The notification that the IDE bus driver is about to enter the + /// specified phase during the enumeration process. + /// + EFI_IDE_CONTROLLER_NOTIFY_PHASE NotifyPhase; + + /// + /// Submits the Drive Identify data that was returned by the device. + /// + EFI_IDE_CONTROLLER_SUBMIT_DATA SubmitData; + + /// + /// Submits information about modes that should be disqualified. The specified + /// IDE device does not support these modes and these modes should not be + /// returned by EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode() + /// + EFI_IDE_CONTROLLER_DISQUALIFY_MODE DisqualifyMode; + + /// + /// Calculates and returns the optimum mode for a particular IDE device. + /// + EFI_IDE_CONTROLLER_CALCULATE_MODE CalculateMode; + + /// + /// Programs the IDE controller hardware to the default timing or per the modes + /// that were returned by the last call to EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode(). + /// + EFI_IDE_CONTROLLER_SET_TIMING SetTiming; + + /// + /// Set to TRUE if the enumeration group includes all the channels that are + /// produced by this controller. FALSE if an enumeration group consists of + /// only one channel. + /// + BOOLEAN EnumAll; + + /// + /// The number of channels that are produced by this controller. Parallel ATA + /// (PATA) controllers can support up to two channels. Advanced Host Controller + /// Interface (AHCI) Serial ATA (SATA) controllers can support up to 32 channels, + /// each of which can have up to one device. In the presence of a multiplier, + /// each channel can have 15 devices. + /// + UINT8 ChannelCount; +}; + +extern EFI_GUID gEfiIdeControllerInitProtocolGuid; + +#endif diff --git a/MdePkg/Include/Protocol/IncompatiblePciDeviceSupport.h b/MdePkg/Include/Protocol/IncompatiblePciDeviceSupport.h new file mode 100644 index 0000000000..f10675b243 --- /dev/null +++ b/MdePkg/Include/Protocol/IncompatiblePciDeviceSupport.h @@ -0,0 +1,173 @@ +/** @file + This file declares Incompatible PCI Device Support Protocol + + Allows the PCI bus driver to support resource allocation for some PCI devices + that do not comply with the PCI Specification. + + @par Note: + This protocol is optional. Only those platforms that implement this protocol + will have the capability to support incompatible PCI devices. The absence of + this protocol can cause the PCI bus driver to configure these incompatible + PCI devices incorrectly. As a result, these devices may not work properly. + + The EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL is used by the PCI bus driver + to support resource allocation for some PCI devices that do not comply with the + PCI Specification. This protocol can find some incompatible PCI devices and + report their special resource requirements to the PCI bus driver. The generic + PCI bus driver does not have prior knowledge of any incompatible PCI devices. + It interfaces with the EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL to find out + if a device is incompatible and to obtain the special configuration requirements + for a specific incompatible PCI device. + + This protocol is optional, and only one instance of this protocol can be present + in the system. If a platform supports this protocol, this protocol is produced + by a Driver Execution Environment (DXE) driver and must be made available before + the Boot Device Selection (BDS) phase. The PCI bus driver will look for the + presence of this protocol before it begins PCI enumeration. If this protocol + exists in a platform, it indicates that the platform has the capability to support + those incompatible PCI devices. However, final support for incompatible PCI + devices still depends on the implementation of the PCI bus driver. The PCI bus + driver may fully, partially, or not even support these incompatible devices. + + During PCI bus enumeration, the PCI bus driver will probe the PCI Base Address + Registers (BARs) for each PCI device regardless of whether the PCI device is + incompatible or not to determine the resource requirements so that the PCI bus + driver can invoke the proper PCI resources for them. Generally, this resource + information includes the following: + - Resource type + - Resource length + - Alignment + + However, some incompatible PCI devices may have special requirements. As a result, + the length or the alignment that is derived through BAR probing may not be exactly + the same as the actual resource requirement of the device. For example, there + are some devices that request I/O resources at a length of 0x100 from their I/O + BAR, but these incompatible devices will never work correctly if an odd I/O base + address, such as 0x100, 0x300, or 0x500, is assigned to the BAR. Instead, these + devices request an even base address, such as 0x200 or 0x400. The Incompatible + PCI Device Support Protocol can then be used to obtain these special resource + requirements for these incompatible PCI devices. In this way, the PCI bus driver + will take special consideration for these devices during PCI resource allocation + to ensure that they can work correctly. + + This protocol may support the following incompatible PCI BAR types: + - I/O or memory length that is different from what the BAR reports + - I/O or memory alignment that is different from what the BAR reports + - Fixed I/O or memory base address + + See the Conventional PCI Specification 3.0 for the details of how a PCI BAR + reports the resource length and the alignment that it requires. + + Copyright (c) 2007 - 2009, Intel Corporation + All rights reserved. This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php + + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + + @par Revision Reference: + This Protocol is defined in UEFI Platform Initialization Specification 1.2 + Volume 5: Standards + +**/ + +#ifndef _INCOMPATIBLE_PCI_DEVICE_SUPPORT_H_ +#define _INCOMPATIBLE_PCI_DEVICE_SUPPORT_H_ + +/// +/// Global ID for EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL +/// +#define EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL_GUID \ + { \ + 0xeb23f55a, 0x7863, 0x4ac2, {0x8d, 0x3d, 0x95, 0x65, 0x35, 0xde, 0x03, 0x75} \ + } + +/// +/// Forward declaration for EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL +/// +typedef struct _EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL; + +/** + Returns a list of ACPI resource descriptors that detail the special resource + configuration requirements for an incompatible PCI device. + + This function returns a list of ACPI resource descriptors that detail the + special resource configuration requirements for an incompatible PCI device. + + Prior to bus enumeration, the PCI bus driver will look for the presence + of the EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL. Only one instance of this + protocol can be present in the system. For each PCI device that the PCI bus + driver discovers, the PCI bus driver calls this function with the device's vendor + ID, device ID, revision ID, subsystem vendor ID, and subsystem device ID. If the + VendorId, DeviceId, RevisionId, SubsystemVendorId, or SubsystemDeviceId value is + set to (UINTN)-1, that field will be ignored. The ID values that are not (UINTN)-1 + will be used to identify the current device. + + This function will only return EFI_SUCCESS. However, if the device is an + incompatible PCI device, a list of ACPI resource descriptors will be returned + in Configuration. Otherwise, NULL will be returned in Configuration instead. + The PCI bus driver does not need to allocate memory for Configuration. However, + it is the PCI bus driver's responsibility to free it. The PCI bus driver then + can configure this device with the information that is derived from this list + of resource nodes, rather than the result of BAR probing. + + Only the following two resource descriptor types from the ACPI Specification + may be used to describe the incompatible PCI device resource requirements: + - QWORD Address Space Descriptor (ACPI 2.0, section 6.4.3.5.1; also ACPI 3.0) + - End Tag (ACPI 2.0, section 6.4.2.8; also ACPI 3.0) + + The QWORD Address Space Descriptor can describe memory, I/O, and bus number + ranges for dynamic or fixed resources. The configuration of a PCI root bridge + is described with one or more QWORD Address Space Descriptors, followed by an + End Tag. See the ACPI Specification for details on the field values. + + @param[in] This Pointer to the EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL + instance. + @param[in] VendorId A unique ID to identify the manufacturer of + the PCI device. See the Conventional PCI + Specification 3.0 for details. + @param[in] DeviceId A unique ID to identify the particular PCI + device. See the Conventional PCI Specification + 3.0 for details. + @param[in] RevisionId A PCI device-specific revision identifier. + See the Conventional PCI Specification 3.0 + for details. + @param[in] SubsystemVendorId Specifies the subsystem vendor ID. See the + Conventional PCI Specification 3.0 for details. + @param[in] SubsystemDeviceId Specifies the subsystem device ID. See the + Conventional PCI Specification 3.0 for details. + @param[out] Configuration A list of ACPI resource descriptors that detail + the configuration requirement. + + @retval EFI_SUCCESS The function always returns EFI_SUCCESS. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_CHECK_DEVICE)( + IN EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL *This, + IN UINTN VendorId, + IN UINTN DeviceId, + IN UINTN RevisionId, + IN UINTN SubsystemVendorId, + IN UINTN SubsystemDeviceId, + OUT VOID **Configuration + ); + +/// +/// Interface structure for the Incompatible PCI Device Support Protocol +/// +struct _EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL { + /// + /// Returns a list of ACPI resource descriptors that detail any special + /// resource configuration requirements if the specified device is a recognized + /// incompatible PCI device. + /// + EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_CHECK_DEVICE CheckDevice; +}; + +extern EFI_GUID gEfiIncompatiblePciDeviceSupportProtocolGuid; + +#endif diff --git a/MdePkg/Include/Protocol/PciHostBridgeResourceAllocation.h b/MdePkg/Include/Protocol/PciHostBridgeResourceAllocation.h new file mode 100644 index 0000000000..792ac0b78a --- /dev/null +++ b/MdePkg/Include/Protocol/PciHostBridgeResourceAllocation.h @@ -0,0 +1,421 @@ +/** @file + This file declares PCI Host Bridge Resource Allocation Protocol which + provides the basic interfaces to abstract a PCI host bridge resource allocation. + This protocol is mandatory if the system includes PCI devices. + + Copyright (c) 2007 - 2009, Intel Corporation + All rights reserved. This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php + + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + + @par Revision Reference: + This Protocol is defined in UEFI Platform Initialization Specification 1.2 + Volume 5: Standards + +**/ + +#ifndef _PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_H_ +#define _PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_H_ + +// +// This file must be included because EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL +// uses EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS +// +#include + +/// +/// Global ID for the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL +/// +#define EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GUID \ + { \ + 0xCF8034BE, 0x6768, 0x4d8b, {0xB7,0x39,0x7C,0xCE,0x68,0x3A,0x9F,0xBE } \ + } + +/// +/// Forward declaration for EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL +/// +typedef struct _EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL; + +/// If this bit is set, then the PCI Root Bridge does not +/// support separate windows for Non-prefetchable and Prefetchable +/// memory. A PCI bus driver needs to include requests for Prefetchable +/// memory in the Non-prefetchable memory pool. +/// +#define EFI_PCI_HOST_BRIDGE_COMBINE_MEM_PMEM 1 + +/// +/// If this bit is set, then the PCI Root Bridge supports +/// 64 bit memory windows. If this bit is not set, +/// the PCI bus driver needs to include requests for 64 bit +/// memory address in the corresponding 32 bit memory pool. +/// +#define EFI_PCI_HOST_BRIDGE_MEM64_DECODE 2 + +/// +/// A UINT64 value that contains the status of a PCI resource requested +/// in the Configuration parameter returned by GetProposedResources() +/// The legal values are EFI_RESOURCE_SATISFIED and EFI_RESOURCE_NOT_SATISFIED +/// +typedef UINT64 EFI_RESOURCE_ALLOCATION_STATUS; + +/// +/// The request of this resource type could be fulfilled. Used in the +/// Configuration parameter returned by GetProposedResources() to identify +/// a PCI resources request that can be satisfied. +/// +#define EFI_RESOURCE_SATISFIED 0x0000000000000000ULL + +/// +/// The request of this resource type could not be fulfilled for its +/// absence in the host bridge resource pool. Used in the Configuration parameter +/// returned by GetProposedResources() to identify a PCI resources request that +/// can not be satisfied. +/// +#define EFI_RESOURCE_NOT_SATISFIED 0xFFFFFFFFFFFFFFFFULL + +/// +/// This enum is used to specify the phase of the PCI enumaeration process +/// +typedef enum { + /// + /// Reset the host bridge PCI apertures and internal data structures. + /// PCI enumerator should issue this notification before starting fresh + /// enumeration process. Enumeration cannot be restarted after sending + /// any other notification such as EfiPciHostBridgeBeginBusAllocation. + /// + EfiPciHostBridgeBeginEnumeration, + + /// + /// The bus allocation phase is about to begin. No specific action + /// is required here. This notification can be used to perform any + /// chipset specific programming. + /// + EfiPciHostBridgeBeginBusAllocation, + + /// + /// The bus allocation and bus programming phase is complete. No specific + /// action is required here. This notification can be used to perform any + /// chipset specific programming. + /// + EfiPciHostBridgeEndBusAllocation, + + /// + /// The resource allocation phase is about to begin.No specific action is + /// required here. This notification can be used to perform any chipset specific programming. + /// + EfiPciHostBridgeBeginResourceAllocation, + + /// + /// Allocate resources per previously submitted requests for all the PCI Root + /// Bridges. These resource settings are returned on the next call to + /// GetProposedResources(). + /// + EfiPciHostBridgeAllocateResources, + + /// + /// Program the Host Bridge hardware to decode previously allocated resources + /// (proposed resources) for all the PCI Root Bridges. + /// + EfiPciHostBridgeSetResources, + + /// + /// De-allocate previously allocated resources previously for all the PCI + /// Root Bridges and reset the I/O and memory apertures to initial state. + /// + EfiPciHostBridgeFreeResources, + + /// + /// The resource allocation phase is completed. No specific action is required + /// here. This notification can be used to perform any chipset specific programming. + /// + EfiPciHostBridgeEndResourceAllocation +} EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE; + +/// +/// Definitions of 2 notification points. +/// +typedef enum { + /// + /// This notification is only applicable to PCI-PCI bridges and + /// indicates that the PCI enumerator is about to begin enumerating + /// the bus behind the PCI-PCI Bridge. This notification is sent after + /// the primary bus number, the secondary bus number and the subordinate + /// bus number registers in the PCI-PCI Bridge are programmed to valid + /// (not necessary final) values + /// + EfiPciBeforeChildBusEnumeration, + + /// + /// This notification is sent before the PCI enumerator probes BAR registers + /// for every valid PCI function. + /// + EfiPciBeforeResourceCollection +} EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE; + +/** + These are the notifications from the PCI bus driver that it is about to enter a certain phase of the PCI + enumeration process. + + @param[in] This Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL + instance. + @param[in] Phase The phase during enumeration + + @retval EFI_SUCCESS The notification was accepted without any errors. + @retval EFI_INVALID_PARAMETER The Phase is invalid. + @retval EFI_NOT_READY This phase cannot be entered at this time. For example, this error + is valid for a Phase of EfiPciHostBridgeAllocateResources if + SubmitResources() has not been called for one or more + PCI root bridges before this call. + @retval EFI_DEVICE_ERROR Programming failed due to a hardware error. This error is valid for + a Phase of EfiPciHostBridgeSetResources. + @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. + This error is valid for a Phase of EfiPciHostBridgeAllocateResources + if the previously submitted resource requests cannot be fulfilled or were only + partially fulfilled + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_NOTIFY_PHASE)( + IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This, + IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE Phase + ); + +/** + Returns the device handle of the next PCI root bridge that is associated with this host bridge. + + @param[in] This Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL + instance. + @param[in,out] RootBridgeHandle Returns the device handle of the next PCI root bridge. On input, it holds the + RootBridgeHandle that was returned by the most recent call to + GetNextRootBridge(). If RootBridgeHandle is NULL on input, the handle + for the first PCI root bridge is returned. + + @retval EFI_SUCCESS The requested attribute information was returned. + @retval EFI_INVALID_PARAMETER RootBridgeHandle is not an EFI_HANDLE that was returned + on a previous call to GetNextRootBridge(). + @retval EFI_NOT_FOUND There are no more PCI root bridge device handles. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_NEXT_ROOT_BRIDGE)( + IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This, + IN OUT EFI_HANDLE *RootBridgeHandle + ); + +/** + Returns the allocation attributes of a PCI root bridge. + + @param[in] This Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL + instance. + @param[in] RootBridgeHandle The device handle of the PCI root bridge in which the caller is interested. + @param[out] Attribute The pointer to attributes of the PCI root bridge. + + @retval EFI_SUCCESS The requested attribute information was returned. + @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle. + @retval EFI_INVALID_PARAMETER Attributes is NULL. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_ATTRIBUTES)( + IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This, + IN EFI_HANDLE RootBridgeHandle, + OUT UINT64 *Attributes + ); + +/** + Sets up the specified PCI root bridge for the bus enumeration process. + + @param[in] This Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL + instance. + @param[in] RootBridgeHandle The PCI root bridge to be set up. + @param[out] Configuration Pointer to the pointer to the PCI bus resource descriptor. + + @retval EFI_SUCCESS The PCI root bridge was set up and the bus range was returned in + Configuration. + @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle. + @retval EFI_DEVICE_ERROR Programming failed due to a hardware error. + @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_START_BUS_ENUMERATION)( + IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This, + IN EFI_HANDLE RootBridgeHandle, + OUT VOID **Configuration + ); + +/** + Programs the PCI root bridge hardware so that it decodes the specified PCI bus range. + + @param[in] This Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL + instance. + @param[in] RootBridgeHandle The PCI root bridge whose bus range is to be programmed. + @param[in] Configuration The pointer to the PCI bus resource descriptor.. + + @retval EFI_SUCCESS The bus range for the PCI root bridge was programmed. + @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle. + @retval EFI_INVALID_PARAMETER Configuration is NULL + @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI (2.0 & 3.0) + resource descriptor. + @retval EFI_INVALID_PARAMETER Configuration does not include a valid ACPI 2.0 bus resource + descriptor. + @retval EFI_INVALID_PARAMETER Configuration includes valid ACPI (2.0 & 3.0) resource + descriptors other than bus descriptors. + @retval EFI_INVALID_PARAMETER Configuration contains one or more invalid ACPI resource + descriptors. + @retval EFI_INVALID_PARAMETER "Address Range Minimum" is invalid for this root bridge. + @retval EFI_INVALID_PARAMETER "Address Range Length" is invalid for this root bridge. + @retval EFI_DEVICE_ERROR Programming failed due to a hardware error. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SET_BUS_NUMBERS)( + IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This, + IN EFI_HANDLE RootBridgeHandle, + IN VOID *Configuration + ); + +/** + Submits the I/O and memory resource requirements for the specified PCI root bridge. + + @param[in] This Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL + instance. + @param[in] RootBridgeHandle The PCI root bridge whose I/O and memory resource requirements are being + submitted. + @param[in] Configuration The pointer to the PCI I/O and PCI memory resource descriptor. + + @retval EFI_SUCCESS The I/O and memory resource requests for a PCI root bridge were + accepted. + @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle. + @retval EFI_INVALID_PARAMETER Configuration is NULL. + @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI (2.0 & 3.0) + resource descriptor. + @retval EFI_INVALID_PARAMETER Configuration includes requests for one or more resource + types that are not supported by this PCI root bridge. This error will + happen if the caller did not combine resources according to + Attributes that were returned by GetAllocAttributes(). + @retval EFI_INVALID_PARAMETER "Address Range Maximum" is invalid. + @retval EFI_INVALID_PARAMETER "Address Range Length" is invalid for this PCI root bridge. + @retval EFI_INVALID_PARAMETER "Address Space Granularity" is invalid for this PCI root bridge. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SUBMIT_RESOURCES)( + IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This, + IN EFI_HANDLE RootBridgeHandle, + IN VOID *Configuration + ); + +/** + Returns the proposed resource settings for the specified PCI root bridge. + + @param[in] This Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL + instance. + @param[in] RootBridgeHandle The PCI root bridge handle. + @param[out] Configuration The pointer to the pointer to the PCI I/O and memory resource descriptor. + + @retval EFI_SUCCESS The requested parameters were returned. + @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle. + @retval EFI_DEVICE_ERROR Programming failed due to a hardware error. + @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_PROPOSED_RESOURCES)( + IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This, + IN EFI_HANDLE RootBridgeHandle, + OUT VOID **Configuration + ); + +/** + Provides the hooks from the PCI bus driver to every PCI controller (device/function) at various + stages of the PCI enumeration process that allow the host bridge driver to preinitialize individual + PCI controllers before enumeration. + + @param[in] This Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance. + @param[in] RootBridgeHandle The associated PCI root bridge handle. + @param[in] PciAddress The address of the PCI device on the PCI bus. + @param[in] Phase The phase of the PCI device enumeration. + + @retval EFI_SUCCESS The requested parameters were returned. + @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle. + @retval EFI_INVALID_PARAMETER Phase is not a valid phase that is defined in + EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE. + @retval EFI_DEVICE_ERROR Programming failed due to a hardware error. The PCI enumerator + should not enumerate this device, including its child devices if it is + a PCI-to-PCI bridge. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_PREPROCESS_CONTROLLER)( + IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This, + IN EFI_HANDLE RootBridgeHandle, + IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS PciAddress, + IN EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE Phase + ); + +/// +/// Provides the basic interfaces to abstract a PCI host bridge resource allocation. +/// +struct _EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL { + /// + /// The notification from the PCI bus enumerator that it is about to enter + /// a certain phase during the enumeration process. + /// + EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_NOTIFY_PHASE NotifyPhase; + + /// + /// Retrieves the device handle for the next PCI root bridge that is produced by the + /// host bridge to which this instance of the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL is attached. + /// + EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_NEXT_ROOT_BRIDGE GetNextRootBridge; + + /// + /// Retrieves the allocation-related attributes of a PCI root bridge. + /// + EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_ATTRIBUTES GetAllocAttributes; + + /// + /// Sets up a PCI root bridge for bus enumeration. + /// + EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_START_BUS_ENUMERATION StartBusEnumeration; + + /// + /// Sets up the PCI root bridge so that it decodes a specific range of bus numbers. + /// + EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SET_BUS_NUMBERS SetBusNumbers; + + /// + /// Submits the resource requirements for the specified PCI root bridge. + /// + EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SUBMIT_RESOURCES SubmitResources; + + /// + /// Returns the proposed resource assignment for the specified PCI root bridges. + /// + EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_PROPOSED_RESOURCES GetProposedResources; + + /// + /// Provides hooks from the PCI bus driver to every PCI controller + /// (device/function) at various stages of the PCI enumeration process that + /// allow the host bridge driver to preinitialize individual PCI controllers + /// before enumeration. + /// + EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_PREPROCESS_CONTROLLER PreprocessController; +}; + +extern EFI_GUID gEfiPciHostBridgeResourceAllocationProtocolGuid; + +#endif diff --git a/MdePkg/Include/Protocol/PciHotPlugInit.h b/MdePkg/Include/Protocol/PciHotPlugInit.h new file mode 100644 index 0000000000..1892a4854b --- /dev/null +++ b/MdePkg/Include/Protocol/PciHotPlugInit.h @@ -0,0 +1,278 @@ +/** @file + This file declares EFI PCI Hot Plug Init Protocol. + + This protocol provides the necessary functionality to initialize the Hot Plug + Controllers (HPCs) and the buses that they control. This protocol also provides + information regarding resource padding. + + @par Note: + This protocol is required only on platforms that support one or more PCI Hot + Plug* slots or CardBus sockets. + + The EFI_PCI_HOT_PLUG_INIT_PROTOCOL provides a mechanism for the PCI bus enumerator + to properly initialize the HPCs and CardBus sockets that require initialization. + The HPC initialization takes place before the PCI enumeration process is complete. + There cannot be more than one instance of this protocol in a system. This protocol + is installed on its own separate handle. + + Because the system may include multiple HPCs, one instance of this protocol + should represent all of them. The protocol functions use the device path of + the HPC to identify the HPC. When the PCI bus enumerator finds a root HPC, it + will call EFI_PCI_HOT_PLUG_INIT_PROTOCOL.InitializeRootHpc(). If InitializeRootHpc() + is unable to initialize a root HPC, the PCI enumerator will ignore that root HPC + and continue the enumeration process. If the HPC is not initialized, the devices + that it controls may not be initialized, and no resource padding will be provided. + + From the standpoint of the PCI bus enumerator, HPCs are divided into the following + two classes: + + - Root HPC: + These HPCs must be initialized by calling InitializeRootHpc() during the + enumeration process. These HPCs will also require resource padding. The + platform code must have a priori knowledge of these devices and must know + how to initialize them. There may not be any way to access their PCI + configuration space before the PCI enumerator programs all the upstream + bridges and thus enables the path to these devices. The PCI bus enumerator + is responsible for determining the PCI bus address of the HPC before it + calls InitializeRootHpc(). + - Nonroot HPC: + These HPCs will not need explicit initialization during enumeration process. + These HPCs will require resource padding. The platform code does not have + to have a priori knowledge of these devices. + + Copyright (c) 2007 - 2009, Intel Corporation + All rights reserved. This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php + + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + + @par Revision Reference: + This Protocol is defined in UEFI Platform Initialization Specification 1.2 + Volume 5: Standards + +**/ + +#ifndef _EFI_PCI_HOT_PLUG_INIT_H_ +#define _EFI_PCI_HOT_PLUG_INIT_H_ + +/// +/// Global ID for the EFI_PCI_HOT_PLUG_INIT_PROTOCOL +/// +#define EFI_PCI_HOT_PLUG_INIT_PROTOCOL_GUID \ + { \ + 0xaa0e8bc1, 0xdabc, 0x46b0, {0xa8, 0x44, 0x37, 0xb8, 0x16, 0x9b, 0x2b, 0xea } \ + } + +/// +/// Forward declaration for EFI_PCI_HOT_PLUG_INIT_PROTOCOL +/// +typedef struct _EFI_PCI_HOT_PLUG_INIT_PROTOCOL EFI_PCI_HOT_PLUG_INIT_PROTOCOL; + +/// +/// Describes the current state of an HPC +/// +typedef UINT16 EFI_HPC_STATE; + +/// +/// The HPC initialization function was called and the HPC completed +/// initialization, but it was not enabled for some reason. The HPC may be +/// disabled in hardware, or it may be disabled due to user preferences, +/// hardware failure, or other reasons. No resource padding is required. +/// +#define EFI_HPC_STATE_INITIALIZED 0x01 + +/// +/// The HPC initialization function was called, the HPC completed +/// initialization, and it was enabled. Resource padding is required. +/// +#define EFI_HPC_STATE_ENABLED 0x02 + +/// +/// Location definition for PCI Hot Plug Controller +/// +typedef struct{ + /// + /// + /// The device path to the root HPC. An HPC cannot control its parent buses. + /// The PCI bus driver requires this information so that it can pass the + /// correct HpcPciAddress to the InitializeRootHpc() and GetResourcePadding() + /// functions. + /// + EFI_DEVICE_PATH_PROTOCOL *HpcDevicePath; + /// + /// The device path to the Hot Plug Bus (HPB) that is controlled by the root + /// HPC. The PCI bus driver uses this information to check if a particular PCI + /// bus has hot-plug slots. The device path of a PCI bus is the same as the + /// device path of its parent. For Standard(PCI) Hot Plug Controllers (SHPCs) + /// and PCI Express*, HpbDevicePath is the same as HpcDevicePath. + /// + EFI_DEVICE_PATH_PROTOCOL *HpbDevicePath; +} EFI_HPC_LOCATION; + +/// +/// Describes how resource padding should be applied +/// +typedef enum { + /// + /// Apply the padding at a PCI bus level. In other words, the resources + /// that are allocated to the bus containing hot-plug slots are padded by + /// the specified amount. If the hot-plug bus is behind a PCI-to-PCI + /// bridge, the PCI-to-PCI bridge apertures will indicate the padding + /// + EfiPaddingPciBus, + /// + /// Apply the padding at a PCI root bridge level. If a PCI root bridge + /// includes more than one hot-plug bus, the resource padding requests + /// for these buses are added together and the resources that are + /// allocated to the root bridge are padded by the specified amount. This + /// strategy may reduce the total amount of padding, but requires + /// reprogramming of PCI-to-PCI bridges in a hot-add event. If the hotplug + /// bus is behind a PCI-to-PCI bridge, the PCI-to-PCI bridge + /// apertures do not indicate the padding for that bus. + /// + EfiPaddingPciRootBridge +} EFI_HPC_PADDING_ATTRIBUTES; + +/** + Returns a list of root Hot Plug Controllers (HPCs) that require initialization + during the boot process. + + This procedure returns a list of root HPCs. The PCI bus driver must initialize + these controllers during the boot process. The PCI bus driver may or may not be + able to detect these HPCs. If the platform includes a PCI-to-CardBus bridge, it + can be included in this list if it requires initialization. The HpcList must be + self consistent. An HPC cannot control any of its parent buses. Only one HPC can + control a PCI bus. Because this list includes only root HPCs, no HPC in the list + can be a child of another HPC. This policy must be enforced by the + EFI_PCI_HOT_PLUG_INIT_PROTOCOL. The PCI bus driver may not check for such + invalid conditions. The callee allocates the buffer HpcList + + @param[in] This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance. + @param[out] HpcCount The number of root HPCs that were returned. + @param[out] HpcList The list of root HPCs. HpcCount defines the number of + elements in this list. + + @retval EFI_SUCCESS HpcList was returned. + @retval EFI_OUT_OF_RESOURCES HpcList was not returned due to insufficient + resources. + @retval EFI_INVALID_PARAMETER HpcCount is NULL or HpcList is NULL. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_GET_ROOT_HPC_LIST)( + IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL *This, + OUT UINTN *HpcCount, + OUT EFI_HPC_LOCATION **HpcList + ); + +/** + Initializes one root Hot Plug Controller (HPC). This process may causes + initialization of its subordinate buses. + + This function initializes the specified HPC. At the end of initialization, + the hot-plug slots or sockets (controlled by this HPC) are powered and are + connected to the bus. All the necessary registers in the HPC are set up. For + a Standard (PCI) Hot Plug Controller (SHPC), the registers that must be set + up are defined in the PCI Standard Hot Plug Controller and Subsystem + Specification. + + @param[in] This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance. + @param[in] HpcDevicePath The device path to the HPC that is being initialized. + @param[in] HpcPciAddress The address of the HPC function on the PCI bus. + @param[in] Event The event that should be signaled when the HPC + initialization is complete. Set to NULL if the + caller wants to wait until the entire initialization + process is complete. + @param[out] HpcState The state of the HPC hardware. The state is + EFI_HPC_STATE_INITIALIZED or EFI_HPC_STATE_ENABLED. + + @retval EFI_SUCCESS If Event is NULL, the specific HPC was successfully + initialized. If Event is not NULL, Event will be + signaled at a later time when initialization is complete. + @retval EFI_UNSUPPORTED This instance of EFI_PCI_HOT_PLUG_INIT_PROTOCOL + does not support the specified HPC. + @retval EFI_OUT_OF_RESOURCES Initialization failed due to insufficient + resources. + @retval EFI_INVALID_PARAMETER HpcState is NULL. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_INITIALIZE_ROOT_HPC)( + IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL *This, + IN EFI_DEVICE_PATH_PROTOCOL *HpcDevicePath, + IN UINT64 HpcPciAddress, + IN EFI_EVENT Event, OPTIONAL + OUT EFI_HPC_STATE *HpcState + ); + +/** + Returns the resource padding that is required by the PCI bus that is controlled + by the specified Hot Plug Controller (HPC). + + This function returns the resource padding that is required by the PCI bus that + is controlled by the specified HPC. This member function is called for all the + root HPCs and nonroot HPCs that are detected by the PCI bus enumerator. This + function will be called before PCI resource allocation is completed. This function + must be called after all the root HPCs, with the possible exception of a + PCI-to-CardBus bridge, have completed initialization. + + @param[in] This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance. + @param[in] HpcDevicePath The device path to the HPC. + @param[in] HpcPciAddress The address of the HPC function on the PCI bus. + @param[in] HpcState The state of the HPC hardware. + @param[out] Padding The amount of resource padding that is required by the + PCI bus under the control of the specified HPC. + @param[out] Attributes Describes how padding is accounted for. The padding + is returned in the form of ACPI 2.0 resource descriptors. + + @retval EFI_SUCCESS The resource padding was successfully returned. + @retval EFI_UNSUPPORTED This instance of the EFI_PCI_HOT_PLUG_INIT_PROTOCOL + does not support the specified HPC. + @retval EFI_NOT_READY This function was called before HPC initialization + is complete. + @retval EFI_INVALID_PARAMETER HpcState or Padding or Attributes is NULL. + @retval EFI_OUT_OF_RESOURCES ACPI 2.0 resource descriptors for Padding + cannot be allocated due to insufficient resources. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_GET_HOT_PLUG_PADDING)( + IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL *This, + IN EFI_DEVICE_PATH_PROTOCOL *HpcDevicePath, + IN UINT64 HpcPciAddress, + OUT EFI_HPC_STATE *HpcState, + OUT VOID **Padding, + OUT EFI_HPC_PADDING_ATTRIBUTES *Attributes + ); + +/// +/// This protocol provides the necessary functionality to initialize the +/// Hot Plug Controllers (HPCs) and the buses that they control. This protocol +/// also provides information regarding resource padding. +/// +struct _EFI_PCI_HOT_PLUG_INIT_PROTOCOL { + /// + /// Returns a list of root HPCs and the buses that they control. + /// + EFI_GET_ROOT_HPC_LIST GetRootHpcList; + + /// + /// Initializes the specified root HPC. + /// + EFI_INITIALIZE_ROOT_HPC InitializeRootHpc; + + /// + /// Returns the resource padding that is required by the HPC. + /// + EFI_GET_HOT_PLUG_PADDING GetResourcePadding; +}; + +extern EFI_GUID gEfiPciHotPlugInitProtocolGuid; + +#endif diff --git a/MdePkg/Include/Protocol/PciPlatform.h b/MdePkg/Include/Protocol/PciPlatform.h new file mode 100644 index 0000000000..123309b8b1 --- /dev/null +++ b/MdePkg/Include/Protocol/PciPlatform.h @@ -0,0 +1,344 @@ +/** @file + This file declares PlatfromOpRom protocols which provides the interface between + the PCI bus driver/PCI Host Bridge Resource Allocation driver and a platform-specific + driver to describe the unique features of a platform. This + protocol is optional. + + Copyright (c) 2007 - 2009, Intel Corporation + All rights reserved. This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php + + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + + @par Revision Reference: + This Protocol is defined in UEFI Platform Initialization Specification 1.2 + Volume 5: Standards + +**/ + +#ifndef _PCI_PLATFORM_H_ +#define _PCI_PLATFORM_H_ + +/// +/// This file must be included because the EFI_PCI_PLATFORM_PROTOCOL uses +/// EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE +/// +#include + +/// +/// Global ID for the EFI_PCI_PLATFORM_PROTOCOL +/// +#define EFI_PCI_PLATFORM_PROTOCOL_GUID \ + { \ + 0x7d75280, 0x27d4, 0x4d69, {0x90, 0xd0, 0x56, 0x43, 0xe2, 0x38, 0xb3, 0x41} \ + } + +/// +/// Forward declaration for EFI_PCI_PLATFORM_PROTOCOL +/// +typedef struct _EFI_PCI_PLATFORM_PROTOCOL EFI_PCI_PLATFORM_PROTOCOL; + +/// +/// EFI_PCI_PLATYFORM_POLICY that is a bitmask with the following legal combinations: +/// - EFI_RESERVE_NONE_IO_ALIAS:
+/// Does not set aside either ISA or VGA I/O resources during PCI +/// enumeration. By using this selection, the platform indicates that it does +/// not want to support a PCI device that requires ISA or legacy VGA +/// resources. If a PCI device driver asks for these resources, the request +/// will be turned down. +/// - EFI_RESERVE_ISA_IO_ALIAS | EFI_RESERVE_VGA_IO_ALIAS:
+/// Sets aside the ISA I/O range and all the aliases during PCI +/// enumeration. VGA I/O ranges and aliases are included in ISA alias +/// ranges. In this scheme, 75 percent of the I/O space remains unused. +/// By using this selection, the platform indicates that it wants to support +/// PCI devices that require the following, at the cost of wasted I/O space: +/// ISA range and its aliases +/// Legacy VGA range and its aliases +/// The PCI bus driver will not allocate I/O addresses out of the ISA I/O +/// range and its aliases. The following are the ISA I/O ranges: +/// - n100..n3FF +/// - n500..n7FF +/// - n900..nBFF +/// - nD00..nFFF +/// +/// In this case, the PCI bus driver will ask the PCI host bridge driver for +/// larger I/O ranges. The PCI host bridge driver is not aware of the ISA +/// aliasing policy and merely attempts to allocate the requested ranges. +/// The first device that requests the legacy VGA range will get all the +/// legacy VGA range plus its aliased addresses forwarded to it. The first +/// device that requests the legacy ISA range will get all the legacy ISA +/// range plus its aliased addresses forwarded to it. +/// - EFI_RESERVE_ISA_IO_NO_ALIAS | EFI_RESERVE_VGA_IO_ALIAS:
+/// Sets aside the ISA I/O range (0x100–0x3FF) during PCI enumeration +/// and the aliases of the VGA I/O ranges. By using this selection, the +/// platform indicates that it will support VGA devices that require VGA +/// ranges, including those that require VGA aliases. The platform further +/// wants to support non-VGA devices that ask for the ISA range (0x100– +/// 3FF), but not if it also asks for the ISA aliases. The PCI bus driver will +/// not allocate I/O addresses out of the legacy ISA I/O range (0x100– +/// 0x3FF) range or the aliases of the VGA I/O range. If a PCI device +/// driver asks for the ISA I/O ranges, including aliases, the request will be +/// turned down. The first device that requests the legacy VGA range will +/// get all the legacy VGA range plus its aliased addresses forwarded to +/// it. When the legacy VGA device asks for legacy VGA ranges and its +/// aliases, all the upstream PCI-to-PCI bridges must be set up to perform +/// 10-bit decode on legacy VGA ranges. To prevent two bridges from +/// positively decoding the same address, all PCI-to-PCI bridges that are +/// peers to this bridge will have to be set up to not decode ISA aliased +/// ranges. In that case, all the devices behind the peer bridges can +/// occupy only I/O addresses that are not ISA aliases. This is a limitation +/// of PCI-to-PCI bridges and is described in the white paper PCI-to-PCI +/// Bridges and Card Bus Controllers on Windows 2000, Windows XP, +/// and Windows Server 2003. The PCI enumeration process must be +/// cognizant of this restriction. +/// - EFI_RESERVE_ISA_IO_NO_ALIAS | EFI_RESERVE_VGA_IO_NO_ALIAS:
+/// Sets aside the ISA I/O range (0x100–0x3FF) during PCI enumeration. +/// VGA I/O ranges are included in the ISA range. By using this selection, +/// the platform indicates that it wants to support PCI devices that require +/// the ISA range and legacy VGA range, but it does not want to support +/// devices that require ISA alias ranges or VGA alias ranges. The PCI +/// bus driver will not allocate I/O addresses out of the legacy ISA I/O +/// range (0x100–0x3FF). If a PCI device driver asks for the ISA I/O +/// ranges, including aliases, the request will be turned down. By using +/// this selection, the platform indicates that it will support VGA devices +/// that require VGA ranges, but it will not support VGA devices that +/// require VGA aliases. To truly support 16-bit VGA decode, all the PCIto- +/// PCI bridges that are upstream to a VGA device, as well as +/// upstream to the parent PCI root bridge, must support 16-bit VGA I/O +/// decode. See the PCI-to-PCI Bridge Architecture Specification for +/// information regarding the 16-bit VGA decode support. This +/// requirement must hold true for every VGA device in the system. If any +/// of these bridges does not support 16-bit VGA decode, it will positively +/// decode all the aliases of the VGA I/O ranges and this selection must +/// be treated like EFI_RESERVE_ISA_IO_NO_ALIAS | +/// EFI_RESERVE_VGA_IO_ALIAS. +/// +typedef UINT32 EFI_PCI_PLATFORM_POLICY; + +/// +/// Does not set aside either ISA or VGA I/O resources during PCI +/// enumeration. +/// +#define EFI_RESERVE_NONE_IO_ALIAS 0x0000 + +/// +/// Sets aside ISA I/O range and all aliases +/// - n100..n3FF +/// - n500..n7FF +/// - n900..nBFF +/// - nD00..nFFF +/// +#define EFI_RESERVE_ISA_IO_ALIAS 0x0001 + +/// +/// Sets aside ISA I/O range 0x100-0x3FF +/// +#define EFI_RESERVE_ISA_IO_NO_ALIAS 0x0002 + +/// +/// Sets aside VGA I/O ranges and all aliases +/// +#define EFI_RESERVE_VGA_IO_ALIAS 0x0004 + +/// +/// Sets aside VGA I/O rangess +/// +#define EFI_RESERVE_VGA_IO_NO_ALIAS 0x0008 + +/// +/// EFI_PCI_EXECUTION_PHASE is used to call a platform protocol and execute +/// platform-specific code. +/// +typedef enum { + /// + /// The phase that indicates the entry point to the PCI Bus Notify phase. This + /// platform hook is called before the PCI bus driver calls the + /// EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL driver. + /// + BeforePciHostBridge = 0, + /// + /// The phase that indicates the entry point to the PCI Bus Notify phase. This + /// platform hook is called before the PCI bus driver calls the + /// EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL driver. + /// + ChipsetEntry = 0, + /// + /// The phase that indicates the exit point to the Chipset Notify phase before + /// returning to the PCI Bus Driver Notify phase. This platform hook is called after + /// the PCI bus driver calls the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL + /// driver. + /// + AfterPciHostBridge = 1, + /// + /// The phase that indicates the exit point to the Chipset Notify phase before + /// returning to the PCI Bus Driver Notify phase. This platform hook is called after + /// the PCI bus driver calls the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL + /// driver. + /// + ChipsetExit = 1, + MaximumChipsetPhase +} EFI_PCI_EXECUTION_PHASE; + +typedef EFI_PCI_EXECUTION_PHASE EFI_PCI_CHIPSET_EXECUTION_PHASE; + +/** + The notification from the PCI bus enumerator to the platform that it is + about to enter a certain phase during the enumeration process. + + The PlatformNotify() function can be used to notify the platform driver so that + it can perform platform-specific actions. No specific actions are required. + Eight notification points are defined at this time. More synchronization points + may be added as required in the future. The PCI bus driver calls the platform driver + twice for every Phase-once before the PCI Host Bridge Resource Allocation Protocol + driver is notified, and once after the PCI Host Bridge Resource Allocation Protocol + driver has been notified. + This member function may not perform any error checking on the input parameters. It + also does not return any error codes. If this member function detects any error condition, + it needs to handle those errors on its own because there is no way to surface any + errors to the caller. + + @param[in] This Pointer to the EFI_PCI_PLATFORM_PROTOCOL instance. + @param[in] HostBridge The handle of the host bridge controller. + @param[in] Phase The phase of the PCI bus enumeration. + @param[in] ChipsetPhase Defines the execution phase of the PCI chipset driver. + + @retval EFI_SUCCESS The function completed successfully. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_PCI_PLATFORM_PHASE_NOTIFY)( + IN EFI_PCI_PLATFORM_PROTOCOL *This, + IN EFI_HANDLE HostBridge, + IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE Phase, + IN EFI_PCI_CHIPSET_EXECUTION_PHASE ChipsetPhase + ); + +/** + The notification from the PCI bus enumerator to the platform for each PCI + controller at several predefined points during PCI controller initialization. + + The PlatformPrepController() function can be used to notify the platform driver so that + it can perform platform-specific actions. No specific actions are required. + Several notification points are defined at this time. More synchronization points may be + added as required in the future. The PCI bus driver calls the platform driver twice for + every PCI controller-once before the PCI Host Bridge Resource Allocation Protocol driver + is notified, and once after the PCI Host Bridge Resource Allocation Protocol driver has + been notified. + This member function may not perform any error checking on the input parameters. It also + does not return any error codes. If this member function detects any error condition, it + needs to handle those errors on its own because there is no way to surface any errors to + the caller. + + @param[in] This Pointer to the EFI_PCI_PLATFORM_PROTOCOL instance. + @param[in] HostBridge The associated PCI host bridge handle. + @param[in] RootBridge The associated PCI root bridge handle. + @param[in] PciAddress The address of the PCI device on the PCI bus. + @param[in] Phase The phase of the PCI controller enumeration. + @param[in] ChipsetPhase Defines the execution phase of the PCI chipset driver. + + @retval EFI_SUCCESS The function completed successfully. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_PCI_PLATFORM_PREPROCESS_CONTROLLER)( + IN EFI_PCI_PLATFORM_PROTOCOL *This, + IN EFI_HANDLE HostBridge, + IN EFI_HANDLE RootBridge, + IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS PciAddress, + IN EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE Phase, + IN EFI_PCI_CHIPSET_EXECUTION_PHASE ChipsetPhase + ); + +/** + Retrieves the platform policy regarding enumeration. + + The GetPlatformPolicy() function retrieves the platform policy regarding PCI + enumeration. The PCI bus driver and the PCI Host Bridge Resource Allocation Protocol + driver can call this member function to retrieve the policy. + + @param[in] This Pointer to the EFI_PCI_PLATFORM_PROTOCOL instance. + @param[out] PciPolicy The platform policy with respect to VGA and ISA aliasing. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER PciPolicy is NULL. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_PCI_PLATFORM_GET_PLATFORM_POLICY)( + IN EFI_PCI_PLATFORM_PROTOCOL *This, + OUT EFI_PCI_PLATFORM_POLICY *PciPolicy + ); + +/** + Gets the PCI device's option ROM from a platform-specific location. + + The GetPciRom() function gets the PCI device's option ROM from a platform-specific location. + The option ROM will be loaded into memory. This member function is used to return an image + that is packaged as a PCI 2.2 option ROM. The image may contain both legacy and EFI option + ROMs. See the UEFI 2.0 Specification for details. This member function can be used to return + option ROM images for embedded controllers. Option ROMs for embedded controllers are typically + stored in platform-specific storage, and this member function can retrieve it from that storage + and return it to the PCI bus driver. The PCI bus driver will call this member function before + scanning the ROM that is attached to any controller, which allows a platform to specify a ROM + image that is different from the ROM image on a PCI card. + + @param[in] This Pointer to the EFI_PCI_PLATFORM_PROTOCOL instance. + @param[in] PciHandle The handle of the PCI device. + @param[out] RomImage If the call succeeds, the pointer to the pointer to the option ROM image. + Otherwise, this field is undefined. The memory for RomImage is allocated + by EFI_PCI_PLATFORM_PROTOCOL.GetPciRom() using the EFI Boot Service AllocatePool(). + It is the caller's responsibility to free the memory using the EFI Boot Service + FreePool(), when the caller is done with the option ROM. + @param[out] RomSize If the call succeeds, a pointer to the size of the option ROM size. Otherwise, + this field is undefined. + + @retval EFI_SUCCESS The option ROM was available for this device and loaded into memory. + @retval EFI_NOT_FOUND No option ROM was available for this device. + @retval EFI_OUT_OF_RESOURCES No memory was available to load the option ROM. + @retval EFI_DEVICE_ERROR An error occurred in getting the option ROM. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_PCI_PLATFORM_GET_PCI_ROM)( + IN EFI_PCI_PLATFORM_PROTOCOL *This, + IN EFI_HANDLE PciHandle, + OUT VOID **RomImage, + OUT UINTN *RomSize + ); + +/// +/// This protocol provides the interface between the PCI bus driver/PCI Host +/// Bridge Resource Allocation driver and a platform-specific driver to describe +/// the unique features of a platform. +/// +struct _EFI_PCI_PLATFORM_PROTOCOL { + /// + /// The notification from the PCI bus enumerator to the platform that it is about to + /// enter a certain phase during the enumeration process. + /// + EFI_PCI_PLATFORM_PHASE_NOTIFY PlatformNotify; + /// + /// The notification from the PCI bus enumerator to the platform for each PCI + /// controller at several predefined points during PCI controller initialization. + /// + EFI_PCI_PLATFORM_PREPROCESS_CONTROLLER PlatformPrepController; + /// + /// Retrieves the platform policy regarding enumeration. + /// + EFI_PCI_PLATFORM_GET_PLATFORM_POLICY GetPlatformPolicy; + /// + /// Gets the PCI device’s option ROM from a platform-specific location. + /// + EFI_PCI_PLATFORM_GET_PCI_ROM GetPciRom; +}; + +extern EFI_GUID gEfiPciPlatformProtocolGuid; + +#endif diff --git a/MdePkg/MdePkg.dec b/MdePkg/MdePkg.dec index 7b03e77308..a03f67f2e3 100644 --- a/MdePkg/MdePkg.dec +++ b/MdePkg/MdePkg.dec @@ -515,10 +515,25 @@ ## Include/Protocol/MpService.h gEfiMpServiceProtocolGuid = { 0x3fdda605, 0xa76e, 0x4f46, { 0xad, 0x29, 0x12, 0xf4, 0x53, 0x1b, 0x3d, 0x08 }} + ## Include/Protocol/PciHostBridgeResourceAllocation.h + gEfiPciHostBridgeResourceAllocationProtocolGuid = { 0xCF8034BE, 0x6768, 0x4d8b, { 0xb7, 0x39, 0x7c, 0xce, 0x68, 0x3a, 0x9f, 0xbe }} + + ## Include/Protocol/PciPlatform.h + gEfiPciPlatformProtocolGuid = { 0x07d75280, 0x27d4, 0x4d69, { 0x90, 0xd0, 0x56, 0x43, 0xe2, 0x38, 0xb3, 0x41 }} + + ## Include/Protocol/IncompatiblePciDeviceSupport.h + gEfiIncompatiblePciDeviceSupportProtocolGuid = { 0xeb23f55a, 0x7863, 0x4ac2, { 0x8d, 0x3d, 0x95, 0x65, 0x35, 0xde, 0x03, 0x75 }} + + ## Include/Protocol/PciHotPlugInit.h + gEfiPciHotPlugInitProtocolGuid = { 0xaa0e8bc1, 0xdabc, 0x46b0, { 0xa8, 0x44, 0x37, 0xb8, 0x16, 0x9b, 0x2b, 0xea }} + ## This protocol is used to add or remove all PCI child devices on the PCI root bridge. ## Include/Protocol/PciHotPlugRequest.h gEfiPciHotPlugRequestProtocolGuid = { 0x19CB87AB, 0x2CB9, 0x4665, { 0x83, 0x60, 0xDD, 0xCF, 0x60, 0x54, 0xF7, 0x9D }} - + + ## Include/Protocol/IdeControllerInit.h + gEfiIdeControllerInitProtocolGuid = { 0xa1e37052, 0x80d9, 0x4e65, { 0xa3, 0x17, 0x3e, 0x9a, 0x55, 0xc4, 0x3e, 0xc9 }} + ## Disk Info protocol is used to export Inquiry Data for a drive. ## Include/Protocol/DiskInfo.h gEfiDiskInfoProtocolGuid = { 0xD432A67F, 0x14DC, 0x484B, { 0xB3, 0xBB, 0x3F, 0x02, 0x91, 0x84, 0x93, 0x27 }} -- 2.39.2