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