11. PCI Platform¶
11.1. Introduction¶
This section contains the basic definitions of protocols that provide PCI platform support. The following protocols are defined in this section:
This section also contains the definitions for additional data types and structures that are subordinate to the structures in which they are called. The following types or structures can be found in “Related Definitions” of the parent function definition:
11.2. PCI Platform Overview¶
This section defines the core code and services that are required for an implementation of the following protocols in this specification:
PCI Platform Protocol
PCI Override Protocol
Incompatible PCI Device Support Protocol
The PCI Platform Protocol allows a PCI bus driver to obtain the platform policy and call a platform driver at various points in the enumeration phase. The Incompatible PCI Device Support Protocol allows a PCI bus driver to handle resource allocation for some PCI devices that do not comply with the PCI Specification.
This specification does the following:
Describes the basic components of the PCI Platform Protocol
Describes the basic components of the Incompatible PCI Device Support Protocol and how firmware configures incompatible PCI devices
Provides code definitions for the PCI Platform Protocol, the Incompatible PCI Device Support Protocol, and their related type definitions that are architecturally required by this specification.
This document is intended for the following readers:
BIOS developers, either those who create general-purpose BIOS and other firmware products or those who modify these products for use in IntelÆ architecture-based products.
Operating system developers who will be adapting their shrink-wrapped operating system products to run on Intel architecture-based platforms.
Readers of this specification are assumed to have solid knowledge of the UEFI 2.1 Specification.
11.4. PCI Platform Protocol¶
11.4.1. PCI Platform Protocol Overview¶
“PCI Host Bridge Resource Allocation Protocol”, Section 10.3 defines and describes the PCI Host Bridge Resource Allocation Protocol. The PCI Host Bridge Resource Allocation Protocol driver provides chipset-specific functionality that works across processor architectures and unique platform features. It does not address issues where an implementation varies across platforms.
In contrast, the PCI Override Protocol and PCI Platform Protocol provide interfaces allow a platform driver or codebase driver to perform platform-specific actions. For example:
Allow a PCI bus driver to obtain platform policy. The platform can use this protocol to control whether the PCI bus driver reserves I/O ranges for ISA aliases and VGA aliases. The default policy for the PCI bus driver is to reserve I/O ranges for both ISA aliases and VGA aliases, which may result in a large amount of I/O space being unavailable for PCI devices. This protocol allows the platform driver to change this policy.
Call a platform driver at various points in the enumeration phase. The platform driver can use these hooks to perform various platform-specific activities. Examples of such activities include but are not limited to the following:
PlatformPrepController() can be used to program the PCI subsystem vendor ID and device ID into onboard and chipset devices.
PlatformPrepController() and PlatformNotify() can be used for implementing hardware workarounds.
PlatformPrepController() can be used for preprogramming any backside registers that control the Base Address Register (BAR) window sizes.
PlatformPrepController() can be used to set PCI or PCI-X* bus speeds for PCI bridges that support multiple bus speeds.
Allow PCI option ROMs to be stored in local storage. The platform can store PCI option ROMs in local storage (e.g., a firmware volume) and report their existence to the PCI bus driver using the GetPciRom() member function. Option ROMs for embedded PCI controllers are often stored in a platform-specific location. The same member function can be used to override the default PCI ROM on an add-in card with one from platform-specific storage.
A platform should implement this protocol if any of the functionality that is listed above is required.
See Code Definitions for the definition of EFI_PCI_PLATFORM_PROTOCOL and the member functions listed above. See PCI Host Bridge Resource Allocation Protocol for additional PCI-related design discussion.
11.5. Incompatible PCI Device Support Protocol¶
11.5.1. Incompatible PCI Device Support Protocol Overview¶
Some PCI devices do not fully comply with the PCI Specification. For example, a PCI device may request that its I/O Base Address Register (BAR) be placed on a 0x200 boundary even though it is requesting an I/O with a length of 0x100. The Incompatible PCI Device Support Protocol allows a PCI bus driver to handle resource allocation for some PCI devices that do not comply with the PCI Specification.
In the PI Architecture, the platform-specific PCI host bridge driver works with the generic, standard PCI bus driver to configure the entire PCI subsystem. Even though the exact configuration is up to individual incompatible devices, it is a platform choice to support those incompatible PCI devices. For example, one platform may not want to support those incompatible devices while another platform appears more tolerant of those devices.
See Code Definitions for the definition of the EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL .
11.5.2. Usage Model for the Incompatible PCI Device SupportProtocol¶
The following describes the usage model for the Incompatible PCI Device Support Protocol:
The PCI bus driver locates EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL . If the PCI bus driver cannot find this protocol, simply follow the regular PCI enumeration path. Otherwise, go to step 2.
For each PCI device that was detected, the PCI bus driver begins collecting the required PCI resources by probing the Base Address Register (BAR) for each device.
For each device, call EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL.CheckDevice() to check whether this PCI device is an incompatible device. If this device in not an incompatible device, go to step 5.
Use the Configuration that is returned by CheckDevice() to override or modify the original PCI resource requirements.
Follow the normal PCI enumeration process.
11.6. PCI Code Definitions¶
This section contains the basic definitions of protocols that provide PCI platform support. The following protocols are defined in this section:
EFI_PCI_PLATFORM_PROTOCOL
EFI_PCI_OVERRIDE_PROTOCOL
EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL
This section also contains the definitions for additional data types and structures that are subordinate to the structures in which they are called. The following types or structures can be found in “Related Definitions” of the parent function definition:
EFI_PCI_CHIPSET_EXECUTION_PHASE
EFI_PCI_PLATFORM_POLICY
11.6.1. PCI Platform Protocol¶
11.6.2. EFI_PCI_PLATFORM_PROTOCOL¶
Summary
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. This protocol is optional.
GUID
#define EFI_PCI_PLATFORM_PROTOCOL_GUID \
{ 0x7d75280, 0x27d4, 0x4d69, 0x90, 0xd0, 0x56, 0x43, 0xe2, \
0x38, 0xb3, 0x41)
Protocol Interface Structure
typedef struct \_EFI_PCI_PLATFORM_PROTOCOL {
EFI_PCI_PLATFORM_PHASE_NOTIFY PlatformNotify;
EFI_PCI_PLATFORM_PREPROCESS_CONTROLLER PlatformPrepController;
EFI_PCI_PLATFORM_GET_PLATFORM_POLICY GetPlatformPolicy;
EFI_PCI_PLATFORM_GET_PCI_ROM GetPciRom;
} EFI_PCI_PLATFORM_PROTOCOL;
Parameters
- PlatformNotify
The notification from the PCI bus enumerator to the platform that it is about to enter a certain phase during the enumeration process. See the PlatformNotify() function description.
- PlatformPrepController
The notification from the PCI bus enumerator to the platform for each PCI controller at several predefined points during PCI controller initialization. See the PlatformPrepController() function description.
- GetPlatformPolicy
Retrieves the platform policy regarding enumeration. See the GetPlatformPolicy() function description.
- GetPciRom
Gets the PCI device’s option ROM from a platform-specific location. See the GetPciRom() function description.
Description
The EFI_PCI_PLATFORM_PROTOCOL is published by a platform-aware driver. This protocol is optional; see PCI Platform Protocol Overview in Design Discussion for scenarios in which this protocol is required. There cannot be more than one instance of this protocol in the system.
If the PCI bus driver detects the presence of this protocol before enumeration, it will use the PCI Platform Protocol to obtain information about the platform policy. The PCI bus driver will use this protocol to get the PCI device’s option ROM from a platform-specific location in storage. It will also call the various member functions of this protocol at predefined points during PCI bus enumeration. The member functions can be used for performing any platform-specific initialization that is appropriate during the particular phase.
11.6.3. EFI_PCI_PLATFORM_PROTOCOL.PlatformNotify()¶
Prototype
typedef
EFI_STATUS
(EFIAPI \* EFI_PCI_PLATFORM_PHASE_NOTIFY) (
IN CONST EFI_PCI_PLATFORM_PROTOCOL *This,
IN EFI_HANDLE HostBridge,
IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE Phase,
IN EFI_PCI_EXECUTION_PHASE ExecPhase
);
Parameters
- This
Pointer to the EFI_PCI_PLATFORM_PROTOCOL instance.
- HostBridge
The handle of the host bridge controller. Type EFI_HANDLE is defined in InstallProtocolInterface() in the UEFI 2.1 Specification .
- Phase
The phase of the PCI bus enumeration. Type EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE is defined in EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL.NotifyPhase() .
- ExecPhase
Defines the execution phase of the PCI chipset driver. Type EFI_PCI_ EXECUTION_PHASE is defined in “Related Definitions” below.
Description
The PlatformNotify() 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 notification points may be added as required in the future. The function should return EFI_UNSUPPORTED for any value of Phase that that the function does not support.
The PCI bus driver calls this function 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. 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.
//***********************************************************\*
// EFI_PCI_EXECUTION_PHASE
//***********************************************************\*
typedef enum {
BeforePciHostBridge = 0,
ChipsetEntry = 0,
AfterPciHostBridge = 1,
ChipsetExit = 1,
MaximumExecutionPhase
} EFI_PCI_EXECUTION_PHASE;
typedef EFI_PCI_EXECUTION_PHASE EFI_PCI_CHIPSET_EXECUTION_PHASE;
Note
EFI_PCI_EXECUTION_PHASE is used to call a platform protocol and execute platform-specific code. Following is a description of the fields in the above enumeration.
- BeforePciHostBridge
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.
- AfterPciHostBridge
The phase that indicates the exit point to the PCI Bus 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.
Status Codes Returned
EFI_SUCCESS |
The function completed successfully |
EFI_UNSUPPORTED |
The function does not support the phase specified by Phase |
11.6.4. EFI_PCI_PLATFORM_PROTOCOL.PlatformPrepController()¶
Summary
The platform driver receives notifications from the PCI bus enumerator at various phases during PCI controller initialization, just like the PCI host bridge driver.
Prototype
typedef
EFI_STATUS
(EFIAPI \* EFI_PCI_PLATFORM_PREPROCESS_CONTROLLER) (
IN CONST 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_EXECUTION_PHASE ExecPhase
);
Parameters
- This
Pointer to the EFI_PCI_PLATFORM_PROTOCOL instance.
- HostBridge
The associated PCI host bridge handle. Type EFI_HANDLE is defined in InstallProtocolInterface() in the UEFI 2.1 Specification.
- RootBridge
The associated PCI root bridge handle.
- PciAddress
The address of the PCI device on the PCI bus. EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS structure is defined in the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL.PreprocessController() section above.
- Phase
The phase of the PCI controller enumeration. Type EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE is defined in EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL.PreprocessController() .
- ExecPhase
Defines the execution phase of the PCI chipset driver. Type EFI_PCI_CHIPSET_EXECUTION_PHASE is defined in EFI_PCI_PLATFORM_PROTOCOL.PlatformNotify() .
Description
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 function should return EFI_UNSUPPORTED for any value of Phase that that the function does not support.
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.
Status Codes Returned
EFI_SUCCESS |
The function completed successfully. |
11.6.5. EFI_PCI_PLATFORM_PROTOCOL.GetPlatformPolicy()¶
Summary
The PCI bus driver and the PCI Host Bridge Resource Allocation Protocol driver can call this member function to retrieve platform policies regarding PCI enumeration.
Prototype
typedef
EFI_STATUS
(EFIAPI \* EFI_PCI_PLATFORM_GET_PLATFORM_POLICY) (
IN CONST EFI_PCI_PLATFORM_PROTOCOL *This,
OUT EFI_PCI_PLATFORM_POLICY *PciPolicy,
);
Parameters
- This
Pointer to the EFI_PCI_PLATFORM_PROTOCOL instance.
- PciPolicy
The platform policy with respect to VGA and ISA aliasing. Type EFI_PCI_PLATFORM_POLICY is defined in “Related Definitions” below.
Description
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.
The EFI_PCI_IO_PROTOCOL.Attributes() function allows a PCI device driver to ask for various legacy ranges. Because PCI device drivers run after PCI enumeration, a request for legacy allocation comes in after PCI enumeration. The only practical way to guarantee that such a request from a PCI device driver will be fulfilled is to preallocate these ranges during enumeration. The PCI bus enumerator does not know which legacy ranges may be requested and therefore must rely on GetPlatformPolicy() . The data that is returned by GetPlatformPolicy() determines the supported attributes that are returned by the EFI_PCI_IO_PROTOCOL.Attributes() function.
See “Related Definitions” below for a description of the output parameter PciPolicy . For example, the platform can decide if it wishes to support devices that require ISA aliases using this parameter. Note that the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.GetAttributes() function returns the attributes that the root bridge hardware supports and does not depend upon preallocations.
typedef UINT32 EFI_PCI_PLATFORM_POLICY;
EFI_PCI_PLATYFORM_POLICY is a bitmask with the following legal combinations.
#define EFI_RESERVE_NONE_IO_ALIAS 0x0000
#define EFI_RESERVE_ISA_IO_ALIAS 0x0001
#define EFI_RESERVE_ISA_IO_NO_ALIAS 0x0002
#define EFI_RESERVE_VGA_IO_ALIAS 0x0004
#define EFI_RESERVE_VGA_IO_NO_ALIAS 0x0008
Status Codes Returned
EFI_SUCCESS |
The function completed successfully. |
EFI_UNSUPPORTED |
The function is not supported. |
EFI_INVALID_PARAMETER |
PciPolicy is NULL. |
11.6.6. EFI_PCI_PLATFORM_PROTOCOL.GetPciRom()¶
Summary
Gets the PCI device’s option ROM from a platform-specific location.
Prototype
typedef
EFI_STATUS
(EFIAPI \* EFI_PCI_PLATFORM_GET_PCI_ROM) (
IN CONST EFI_PCI_PLATFORM_PROTOCOL *This,
IN EFI_HANDLE PciHandle,
OUT VOID **RomImage,
OUT UINTN *RomSize
);
Parameters
- This
Pointer to the EFI_PCI_PLATFORM_PROTOCOL instance.
- PciHandle
The handle of the PCI device. Type EFI_HANDLE is defined in InstallProtocolInterface() in the UEFI 2.1 Specification .
- 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 UEFI Boot Service AllocatePool() . It is the caller’s responsibility to free the memory using the UEFI Boot Service FreePool() , when the caller is done with the option ROM.
- RomSize
If the call succeeds, a pointer to the size of the option ROM size. Otherwise, this field is undefined.
Description
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 UEFI option ROMs. See the UEFI 2.1 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.
Status Codes Returned
EFI_SUCCESS |
The option ROM was available for this device and loaded into memory |
EFI_NOT_FOUND |
No option ROM was available for this device |
EFI_OUT_OF_RESOURCES |
No memory was available to load the option ROM |
EFI_DEVICE_ERROR |
An error occurred in getting the option ROM |
11.6.7. PCI Override Protocol¶
11.6.8. EFI_PCI_OVERRIDE_PROTOCOL¶
Summary
This protocol provides the interface between the PCI bus driver/PCI Host Bridge Resource Allocation driver and an implementation’s driver to describe the unique features of a platform. This protocol is optional.
GUID
#define EFI_PCI_OVERRIDE_GUID \
{ 0xb5b35764, 0x460c, 0x4a06, { 0x99, 0xfc, 0x77, 0xa1, \
0x7c, 0x1b, 0x5c, 0xeb } }
Protocol Interface Structure
typedef EFI_PCI_PLATFORM_PROTOCOL EFI_PCI_OVERRIDE_PROTOCOL;
Description
The PCI Override Protocol is published by an implementation aware driver. This protocol is optional. But it must be called, if present, during PCI enumeration. There cannot be more than one instance of this protocol in the system.
If the PCI bus driver detects the presence of this protocol before bus enumeration, it will use the PCI Override Protocol to obtain information about the platform policy. If the PCI Platform Protocol does not exist or returns an error, then this protocol is called.
The PCI bus driver will use this protocol to get the PCI device’s option ROM from an implementation-specific location in storage. If the PCI Platform Protocol does not exist or returns an error, then this function is called.
It will also call the various member functions of this protocol at predefined points during PCI bus enumeration. The member functions can be used for performing any implementation-specific initialization that is appropriate during the particular phase.
11.6.9. Incompatible PCI Device Support Protocol¶
11.6.10. EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL¶
Summary
Allows the PCI bus driver to support resource allocation for some PCI devices that do not comply with the PCI Specification.
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.
GUID
#define EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL_GUID \
{0xeb23f55a, 0x7863, 0x4ac2, 0x8d, 0x3d, 0x95, 0x65, 0x35, \
0xde, 0x3, 0x75}
Protocol Interface Structure
typedef struct _EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL {
EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_CHECK_DEVICE CheckDevice;
} EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL;
Parameters
- CheckDevice
Returns a list of ACPI resource descriptors that detail any special resource configuration requirements if the specified device is a recognized incompatible PCI device. See the CheckDevice() function description.
Description
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.
11.6.11. EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL.CheckDevice()¶
Summary
Returns a list of ACPI resource descriptors that detail the special resource configuration requirements for an incompatible PCI device.
Prototype
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
);
Parameters
- This
Pointer to the EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL instance.
- VendorID
A unique ID to identify the manufacturer of the PCI device. See the Conventional PCI Specification 3.0 for details.
- DeviceID
A unique ID to identify the particular PCI device. See the Conventional PCI Specification 3.0 for details.
- RevisionID
A PCI device-specific revision identifier. See the Conventional PCI Specification 3.0 for details.
- SubsystemVendorId
Specifies the subsystem vendor ID. See the Conventional PCI Specification 3.0 for details.
- SubsystemDeviceId
Specifies the subsystem device ID. See the Conventional PCI Specification 3.0 for details.
- Configuration
A list of ACPI resource descriptors that detail the configuration requirement. See ACPI 2.0 & 3.0 QWORD Address Space Descriptor Usage in the “Description” subsection below for the definition.
Description
The CheckDevice() 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. ACPI 2.0 & 3.0 QWORD Address Space Descriptor Usage and ACPI 2.0 & 3.0 End Tag Usage below contain these two descriptor types. See the ACPI Specification for details on the field values.
Byte Offset |
Byte Length |
Data |
Description |
|---|---|---|---|
0x00 |
0x01 |
0x8A |
QWORD Address Space Descriptor |
0x01 |
0x02 |
0x2B |
Length of this descriptor in bytes not including the first two fields |
0x03 |
0x01 |
Resource type 0 Memory range 1 I O range Other values will be ignored |
|
0x04 |
0x01 |
General flags Ignored |
|
0x05 |
0x01 |
Type specific flags Only used when Address Translation Offset 6 Value 0 Skip device option ROM do not probe option rom BAR Other values will be ignored |
|
0x06 |
0x08 |
Address Space Granularity Ignored if the value is 0 Ignored if the PCI BAR is I O Ignored if the PCI BAR is 32 bt memory If PCI BAR is 64 bit memory and this field is 32 then the PCI BAR resource is allocated below 4GB If the PCI BAR is 64 bit memory and this field is 64 then the PCI BAR resource is allocated above 4GB |
|
0x16 |
0x08 |
Address Range Maximum Used to indicate the BAR Index from 0 to 6 where 6 is the Option Rom BAR Specially UINT64 1 in this field means all the PCI BARs on the device except the Option Rom BAR |
|
0x1E |
0x08 |
Address Translation Offset Used to indicate the BAR Index from 0 to 6 where 6 is the Option ROM BAR Specially UINT64 1 in this field means all the PCI BARs are on the device except the Option ROM BAR |
|
0x26 |
0x08 |
Address Range Length Length of the requested resource If the device has no special length request it must be 0 Then the length that was obtained from BAR probing will be applied |
Byte Offset |
Byte Length |
Data |
Description |
|---|---|---|---|
0x00 |
0x01 |
0x79 |
End Tag. |
0x01 |
0x01 |
0x00 |
Checksum. Set to 0 to indicate that checksum is to beignored. |
Status Codes Returned
EFI_SUCCESS |
The function always returns EFI_SUCCESS |