UEFI Shell PCI Device Diagnostics Guide

The UEFI Shell allows system administrators, firmware developers, and hardware engineers to inspect, query, and troubleshoot PCI and PCIe devices directly at the firmware layer without an operating system installed. By utilizing native shell commands—primarily the pci utility—users can retrieve extensive diagnostic telemetry, ranging from basic device identification to raw configuration space register dumps, memory allocations, and PCIe link negotiation states. This guide outlines the specific diagnostic data accessible via the UEFI Shell and how to extract it.

PCI Device Identification and Topology

Running the pci command without parameters outputs a complete list of all PCI-compliant devices recognized by the firmware across all buses. This scan provides initial diagnostic identification:

  • Bus, Device, and Function (BDF) Numbers: Pinpoints the exact hardware address of each device within the system topology (e.g., 00:1F.2).
  • Vendor ID (VID) and Device ID (DID): Identifies the silicon manufacturer and the specific product model.
  • Class Codes and Programming Interface: Identifies the device type (such as Mass Storage Controller, Network Controller, or Display Adapter) and its specific programming interface (e.g., NVMe, AHCI, xHCI).

To pause output across long device lists, append the -b flag:

pci -b

Detailed Configuration Header Decoding

Targeting a specific device using its BDF notation (pci <Bus> <Dev> <Func>) decodes the standard 64-byte PCI Configuration Header (Type 0 for endpoints, Type 1 for root ports and bridges). This surfaces key diagnostic fields:

  • Command and Status Registers: Displays the current operational flags, such as Bus Master Enable (BME), Memory Space Enable (MSE), I/O Space Enable, and parity error conditions.
  • Revision ID: Displays the specific silicon stepping or hardware revision.
  • Subsystem Vendor ID and Subsystem ID: Distinguishes between OEM implementations of the same underlying chipset (e.g., a specific graphics board vendor versus the GPU chip designer).
  • Latency Timer and Cache Line Size: Reports system-level bus timing parameters assigned by firmware.

For example, to diagnose a device at Bus 01, Device 00, Function 0:

pci 01 00 00

Base Address Registers (BARs) and Resource Allocation

The decoded configuration space details the device's assigned resources, which is essential for troubleshooting memory mapping conflicts and resource exhaustion:

  • Memory and I/O Ranges: Lists the physical address boundaries assigned to each BAR.
  • BAR Type and Attributes: Indicates whether resources are mapped as 32-bit or 64-bit addresses, and whether the memory regions are marked as prefetchable.
  • Interrupt Line and Pin: Shows the legacy interrupt line assignment (e.g., INTA# mapped to IRQ 11).

On modern systems, the pci utility walks the PCI Express Extended Capabilities structure, exposing real-time link health and operational metrics:

  • Link Speed: Displays both maximum supported speed (e.g., 2.5 GT/s, 5.0 GT/s, 8.0 GT/s, 16.0 GT/s) and current negotiated link speed, revealing whether a card is running below its design speed.
  • Link Width: Shows maximum capabilities versus negotiated lane count (e.g., configured as x4 instead of x16 due to slot limits, physical damage, or poor seating).
  • Active State Power Management (ASPM): Shows the current low-power states (L0s, L1) enabled for the device.
  • Max Payload Size (MPS) and Max Read Request Size (MRRS): Reports configured packet sizes, which directly impact data throughput and interface stability.

Extended Capability and Error Detection

UEFI Shell's verbose output parses advanced PCIe capabilities:

  • Advanced Error Reporting (AER): If supported, reports uncorrectable errors, correctable errors, and bad TLP/DLLP packet counts to pinpoint failing links or faulty signal integrity.
  • Power Management Capabilities: Displays supported D-states (D0, D1, D2, D3hot, D3cold) and current power status.
  • MSI / MSI-X Registers: Shows Message Signaled Interrupt capability, configuration status, and assigned vector limits.

Raw Configuration Space Inspection

When detailed register-level debugging is required beyond decoded text, the UEFI Shell can dump the raw configuration space:

  • Standard Space (First 256 bytes): Displays the raw hexadecimal representation of the legacy configuration space.
  • Extended Configuration Space (Bytes 256 to 4096): Available on PCIe hardware, providing direct access to vendor-specific registers and extended capability registers.

To view the raw hex dump alongside the decoded structure:

pci 01 00 00 -i