1 /** @file 2 This file declares Incompatible PCI Device Support Protocol 3 4 Allows the PCI bus driver to support resource allocation for some PCI devices 5 that do not comply with the PCI Specification. 6 7 @par Note: 8 This protocol is optional. Only those platforms that implement this protocol 9 will have the capability to support incompatible PCI devices. The absence of 10 this protocol can cause the PCI bus driver to configure these incompatible 11 PCI devices incorrectly. As a result, these devices may not work properly. 12 13 The EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL is used by the PCI bus driver 14 to support resource allocation for some PCI devices that do not comply with the 15 PCI Specification. This protocol can find some incompatible PCI devices and 16 report their special resource requirements to the PCI bus driver. The generic 17 PCI bus driver does not have prior knowledge of any incompatible PCI devices. 18 It interfaces with the EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL to find out 19 if a device is incompatible and to obtain the special configuration requirements 20 for a specific incompatible PCI device. 21 22 This protocol is optional, and only one instance of this protocol can be present 23 in the system. If a platform supports this protocol, this protocol is produced 24 by a Driver Execution Environment (DXE) driver and must be made available before 25 the Boot Device Selection (BDS) phase. The PCI bus driver will look for the 26 presence of this protocol before it begins PCI enumeration. If this protocol 27 exists in a platform, it indicates that the platform has the capability to support 28 those incompatible PCI devices. However, final support for incompatible PCI 29 devices still depends on the implementation of the PCI bus driver. The PCI bus 30 driver may fully, partially, or not even support these incompatible devices. 31 32 During PCI bus enumeration, the PCI bus driver will probe the PCI Base Address 33 Registers (BARs) for each PCI device regardless of whether the PCI device is 34 incompatible or not to determine the resource requirements so that the PCI bus 35 driver can invoke the proper PCI resources for them. Generally, this resource 36 information includes the following: 37 - Resource type 38 - Resource length 39 - Alignment 40 41 However, some incompatible PCI devices may have special requirements. As a result, 42 the length or the alignment that is derived through BAR probing may not be exactly 43 the same as the actual resource requirement of the device. For example, there 44 are some devices that request I/O resources at a length of 0x100 from their I/O 45 BAR, but these incompatible devices will never work correctly if an odd I/O base 46 address, such as 0x100, 0x300, or 0x500, is assigned to the BAR. Instead, these 47 devices request an even base address, such as 0x200 or 0x400. The Incompatible 48 PCI Device Support Protocol can then be used to obtain these special resource 49 requirements for these incompatible PCI devices. In this way, the PCI bus driver 50 will take special consideration for these devices during PCI resource allocation 51 to ensure that they can work correctly. 52 53 This protocol may support the following incompatible PCI BAR types: 54 - I/O or memory length that is different from what the BAR reports 55 - I/O or memory alignment that is different from what the BAR reports 56 - Fixed I/O or memory base address 57 58 See the Conventional PCI Specification 3.0 for the details of how a PCI BAR 59 reports the resource length and the alignment that it requires. 60 61 Copyright (c) 2007 - 2009, Intel Corporation. All rights reserved.<BR> 62 This program and the accompanying materials 63 are licensed and made available under the terms and conditions of the BSD License 64 which accompanies this distribution. The full text of the license may be found at 65 http://opensource.org/licenses/bsd-license.php 66 67 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 68 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 69 70 @par Revision Reference: 71 This Protocol is defined in UEFI Platform Initialization Specification 1.2 72 Volume 5: Standards 73 74 **/ 75 76 #ifndef _INCOMPATIBLE_PCI_DEVICE_SUPPORT_H_ 77 #define _INCOMPATIBLE_PCI_DEVICE_SUPPORT_H_ 78 79 /// 80 /// Global ID for EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL 81 /// 82 #define EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL_GUID \ 83 { \ 84 0xeb23f55a, 0x7863, 0x4ac2, {0x8d, 0x3d, 0x95, 0x65, 0x35, 0xde, 0x03, 0x75} \ 85 } 86 87 /// 88 /// Forward declaration for EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL 89 /// 90 typedef struct _EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL; 91 92 /** 93 Returns a list of ACPI resource descriptors that detail the special resource 94 configuration requirements for an incompatible PCI device. 95 96 This function returns a list of ACPI resource descriptors that detail the 97 special resource configuration requirements for an incompatible PCI device. 98 99 Prior to bus enumeration, the PCI bus driver will look for the presence 100 of the EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL. Only one instance of this 101 protocol can be present in the system. For each PCI device that the PCI bus 102 driver discovers, the PCI bus driver calls this function with the device's vendor 103 ID, device ID, revision ID, subsystem vendor ID, and subsystem device ID. If the 104 VendorId, DeviceId, RevisionId, SubsystemVendorId, or SubsystemDeviceId value is 105 set to (UINTN)-1, that field will be ignored. The ID values that are not (UINTN)-1 106 will be used to identify the current device. 107 108 This function will only return EFI_SUCCESS. However, if the device is an 109 incompatible PCI device, a list of ACPI resource descriptors will be returned 110 in Configuration. Otherwise, NULL will be returned in Configuration instead. 111 The PCI bus driver does not need to allocate memory for Configuration. However, 112 it is the PCI bus driver's responsibility to free it. The PCI bus driver then 113 can configure this device with the information that is derived from this list 114 of resource nodes, rather than the result of BAR probing. 115 116 Only the following two resource descriptor types from the ACPI Specification 117 may be used to describe the incompatible PCI device resource requirements: 118 - QWORD Address Space Descriptor (ACPI 2.0, section 6.4.3.5.1; also ACPI 3.0) 119 - End Tag (ACPI 2.0, section 6.4.2.8; also ACPI 3.0) 120 121 The QWORD Address Space Descriptor can describe memory, I/O, and bus number 122 ranges for dynamic or fixed resources. The configuration of a PCI root bridge 123 is described with one or more QWORD Address Space Descriptors, followed by an 124 End Tag. See the ACPI Specification for details on the field values. 125 126 @param[in] This Pointer to the EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL 127 instance. 128 @param[in] VendorId A unique ID to identify the manufacturer of 129 the PCI device. See the Conventional PCI 130 Specification 3.0 for details. 131 @param[in] DeviceId A unique ID to identify the particular PCI 132 device. See the Conventional PCI Specification 133 3.0 for details. 134 @param[in] RevisionId A PCI device-specific revision identifier. 135 See the Conventional PCI Specification 3.0 136 for details. 137 @param[in] SubsystemVendorId Specifies the subsystem vendor ID. See the 138 Conventional PCI Specification 3.0 for details. 139 @param[in] SubsystemDeviceId Specifies the subsystem device ID. See the 140 Conventional PCI Specification 3.0 for details. 141 @param[out] Configuration A list of ACPI resource descriptors that detail 142 the configuration requirement. 143 144 @retval EFI_SUCCESS The function always returns EFI_SUCCESS. 145 146 **/ 147 typedef 148 EFI_STATUS 149 (EFIAPI *EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_CHECK_DEVICE)( 150 IN EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL *This, 151 IN UINTN VendorId, 152 IN UINTN DeviceId, 153 IN UINTN RevisionId, 154 IN UINTN SubsystemVendorId, 155 IN UINTN SubsystemDeviceId, 156 OUT VOID **Configuration 157 ); 158 159 /// 160 /// Interface structure for the Incompatible PCI Device Support Protocol 161 /// 162 struct _EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL { 163 /// 164 /// Returns a list of ACPI resource descriptors that detail any special 165 /// resource configuration requirements if the specified device is a recognized 166 /// incompatible PCI device. 167 /// 168 EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_CHECK_DEVICE CheckDevice; 169 }; 170 171 extern EFI_GUID gEfiIncompatiblePciDeviceSupportProtocolGuid; 172 173 #endif 174