/** @file\r
- This file declares EFI Incompatible PCI Device Support Protocol\r
-\r
- Copyright (c) 2006, Intel Corporation \r
- All rights reserved. This program and the accompanying materials \r
- are licensed and made available under the terms and conditions of the BSD License \r
- which accompanies this distribution. The full text of the license may be found at \r
- http://opensource.org/licenses/bsd-license.php \r
-\r
- THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
- WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
-\r
- Module Name: IncompatiblePciDeviceSupport.h\r
+ This file declares Incompatible PCI Device Support Protocol\r
+ \r
+ Allows the PCI bus driver to support resource allocation for some PCI devices \r
+ that do not comply with the PCI Specification.\r
+ \r
+ @par Note: \r
+ This protocol is optional. Only those platforms that implement this protocol \r
+ will have the capability to support incompatible PCI devices. The absence of \r
+ this protocol can cause the PCI bus driver to configure these incompatible \r
+ PCI devices incorrectly. As a result, these devices may not work properly. \r
+ \r
+ The EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL is used by the PCI bus driver\r
+ to support resource allocation for some PCI devices that do not comply with the \r
+ PCI Specification. This protocol can find some incompatible PCI devices and \r
+ report their special resource requirements to the PCI bus driver. The generic \r
+ PCI bus driver does not have prior knowledge of any incompatible PCI devices. \r
+ It interfaces with the EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL to find out \r
+ if a device is incompatible and to obtain the special configuration requirements \r
+ for a specific incompatible PCI device.\r
+\r
+ This protocol is optional, and only one instance of this protocol can be present\r
+ in the system. If a platform supports this protocol, this protocol is produced \r
+ by a Driver Execution Environment (DXE) driver and must be made available before \r
+ the Boot Device Selection (BDS) phase. The PCI bus driver will look for the \r
+ presence of this protocol before it begins PCI enumeration. If this protocol \r
+ exists in a platform, it indicates that the platform has the capability to support\r
+ those incompatible PCI devices. However, final support for incompatible PCI \r
+ devices still depends on the implementation of the PCI bus driver. The PCI bus \r
+ driver may fully, partially, or not even support these incompatible devices. \r
+\r
+ During PCI bus enumeration, the PCI bus driver will probe the PCI Base Address \r
+ Registers (BARs) for each PCI device regardless of whether the PCI device is \r
+ incompatible or not to determine the resource requirements so that the PCI bus \r
+ driver can invoke the proper PCI resources for them. Generally, this resource \r
+ information includes the following:\r
+ - Resource type\r
+ - Resource length\r
+ - Alignment\r
+ \r
+ However, some incompatible PCI devices may have special requirements. As a result,\r
+ the length or the alignment that is derived through BAR probing may not be exactly \r
+ the same as the actual resource requirement of the device. For example, there \r
+ are some devices that request I/O resources at a length of 0x100 from their I/O\r
+ BAR, but these incompatible devices will never work correctly if an odd I/O base \r
+ address, such as 0x100, 0x300, or 0x500, is assigned to the BAR. Instead, these \r
+ devices request an even base address, such as 0x200 or 0x400. The Incompatible \r
+ PCI Device Support Protocol can then be used to obtain these special resource \r
+ requirements for these incompatible PCI devices. In this way, the PCI bus driver \r
+ will take special consideration for these devices during PCI resource allocation \r
+ to ensure that they can work correctly.\r
+ \r
+ This protocol may support the following incompatible PCI BAR types:\r
+ - I/O or memory length that is different from what the BAR reports\r
+ - I/O or memory alignment that is different from what the BAR reports\r
+ - Fixed I/O or memory base address\r
+ \r
+ See the Conventional PCI Specification 3.0 for the details of how a PCI BAR \r
+ reports the resource length and the alignment that it requires.\r
+\r
+ Copyright (c) 2007 - 2009, Intel Corporation. All rights reserved.<BR>\r
+ This program and the accompanying materials\r
+ are licensed and made available under the terms and conditions of the BSD License\r
+ which accompanies this distribution. The full text of the license may be found at\r
+ http://opensource.org/licenses/bsd-license.php\r
+\r
+ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
@par Revision Reference:\r
- This protocol is defined in Framework of EFI PCI Platform Support Specification.\r
- Version0.9\r
+ This Protocol is defined in UEFI Platform Initialization Specification 1.2 \r
+ Volume 5: Standards\r
\r
**/\r
\r
#ifndef _INCOMPATIBLE_PCI_DEVICE_SUPPORT_H_\r
#define _INCOMPATIBLE_PCI_DEVICE_SUPPORT_H_\r
\r
+///\r
+/// Global ID for EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL\r
+///\r
#define EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL_GUID \\r
- {0xeb23f55a, 0x7863, 0x4ac2, {0x8d, 0x3d, 0x95, 0x65, 0x35, 0xde, 0x03, 0x75} }\r
+ { \\r
+ 0xeb23f55a, 0x7863, 0x4ac2, {0x8d, 0x3d, 0x95, 0x65, 0x35, 0xde, 0x03, 0x75} \\r
+ }\r
\r
+///\r
+/// Forward declaration for EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL\r
+///\r
typedef struct _EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL;\r
\r
/**\r
- Returns a list of ACPI resource descriptors that detail the special \r
- resource configuration requirements for an incompatible PCI device.\r
-\r
- @param This Pointer to the EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL instance.\r
- @param VendorID A unique ID to identify the manufacturer of the PCI device.\r
- @param DeviceID A unique ID to identify the particular PCI device.\r
- @param RevisionID A PCI device-specific revision identifier.\r
- @param SubsystemVendorId Specifies the subsystem vendor ID.\r
- @param SubsystemDeviceId Specifies the subsystem device ID.\r
- @param Configuration A list of ACPI resource descriptors that detail\r
- the configuration requirement.\r
-\r
- @retval EFI_SUCCESS The function always returns EFI_SUCCESS.\r
+ Returns a list of ACPI resource descriptors that detail the special resource\r
+ configuration requirements for an incompatible PCI device.\r
+ \r
+ This function returns a list of ACPI resource descriptors that detail the \r
+ special resource configuration requirements for an incompatible PCI device. \r
+ \r
+ Prior to bus enumeration, the PCI bus driver will look for the presence\r
+ of the EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL. Only one instance of this\r
+ protocol can be present in the system. For each PCI device that the PCI bus \r
+ driver discovers, the PCI bus driver calls this function with the device's vendor\r
+ ID, device ID, revision ID, subsystem vendor ID, and subsystem device ID. If the\r
+ VendorId, DeviceId, RevisionId, SubsystemVendorId, or SubsystemDeviceId value is\r
+ set to (UINTN)-1, that field will be ignored. The ID values that are not (UINTN)-1\r
+ will be used to identify the current device. \r
+ \r
+ This function will only return EFI_SUCCESS. However, if the device is an \r
+ incompatible PCI device, a list of ACPI resource descriptors will be returned \r
+ in Configuration. Otherwise, NULL will be returned in Configuration instead. \r
+ The PCI bus driver does not need to allocate memory for Configuration. However, \r
+ it is the PCI bus driver's responsibility to free it. The PCI bus driver then \r
+ can configure this device with the information that is derived from this list \r
+ of resource nodes, rather than the result of BAR probing.\r
+\r
+ Only the following two resource descriptor types from the ACPI Specification \r
+ may be used to describe the incompatible PCI device resource requirements:\r
+ - QWORD Address Space Descriptor (ACPI 2.0, section 6.4.3.5.1; also ACPI 3.0)\r
+ - End Tag (ACPI 2.0, section 6.4.2.8; also ACPI 3.0)\r
+\r
+ The QWORD Address Space Descriptor can describe memory, I/O, and bus number \r
+ ranges for dynamic or fixed resources. The configuration of a PCI root bridge \r
+ is described with one or more QWORD Address Space Descriptors, followed by an \r
+ End Tag. See the ACPI Specification for details on the field values.\r
+ \r
+ @param[in] This Pointer to the EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL \r
+ instance.\r
+ @param[in] VendorId A unique ID to identify the manufacturer of \r
+ the PCI device. See the Conventional PCI\r
+ Specification 3.0 for details.\r
+ @param[in] DeviceId A unique ID to identify the particular PCI \r
+ device. See the Conventional PCI Specification \r
+ 3.0 for details.\r
+ @param[in] RevisionId A PCI device-specific revision identifier. \r
+ See the Conventional PCI Specification 3.0\r
+ for details.\r
+ @param[in] SubsystemVendorId Specifies the subsystem vendor ID. See the \r
+ Conventional PCI Specification 3.0 for details.\r
+ @param[in] SubsystemDeviceId Specifies the subsystem device ID. See the \r
+ Conventional PCI Specification 3.0 for details.\r
+ @param[out] Configuration A list of ACPI resource descriptors that detail\r
+ the configuration requirement.\r
+\r
+ @retval EFI_SUCCESS The function always returns EFI_SUCCESS.\r
\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_CHECK_DEVICE) (\r
- IN EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL *This,\r
+(EFIAPI *EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_CHECK_DEVICE)(\r
+ IN EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL *This,\r
IN UINTN VendorId,\r
IN UINTN DeviceId,\r
- IN UINTN Revision,\r
- IN UINTN SubVendorId,OPTIONAL\r
- IN UINTN SubDeviceId,OPTIONAL\r
+ IN UINTN RevisionId,\r
+ IN UINTN SubsystemVendorId,\r
+ IN UINTN SubsystemDeviceId,\r
OUT VOID **Configuration\r
-); \r
-\r
-\r
-//\r
-// Interface structure for the Incompatible PCI Device Support Protocol\r
-//\r
-/**\r
- @par Protocol Description:\r
- This protocol can find some incompatible PCI devices and report their \r
- special resource requirements to the PCI bus driver.\r
-\r
- @param CheckDevice\r
- Returns a list of ACPI resource descriptors that detail any special \r
- resource configuration requirements if the specified device is a recognized \r
- incompatible PCI device. \r
+ );\r
\r
-**/\r
+///\r
+/// Interface structure for the Incompatible PCI Device Support Protocol\r
+///\r
struct _EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL {\r
- EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_CHECK_DEVICE CheckDevice; \r
+ ///\r
+ /// Returns a list of ACPI resource descriptors that detail any special\r
+ /// resource configuration requirements if the specified device is a recognized\r
+ /// incompatible PCI device.\r
+ ///\r
+ EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_CHECK_DEVICE CheckDevice;\r
};\r
\r
extern EFI_GUID gEfiIncompatiblePciDeviceSupportProtocolGuid;\r
- \r
+\r
#endif\r
projects / mirror_edk2.git / blobdiff