| /** @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 - 2018, Intel Corporation. All rights reserved.<BR> |
| SPDX-License-Identifier: BSD-2-Clause-Patent |
| |
| @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 |