Troubleshooting PCI Devices with PCIList: Common Issues SolvedPeripheral Component Interconnect (PCI) devices are the backbone of many system components — network adapters, storage controllers, GPUs, USB controllers, and more. When a PCI device fails to initialize or behave correctly, it can be hard to pinpoint the root cause. PCIList is a useful tool for enumerating PCI devices and their properties; combined with methodical troubleshooting steps, it can help you identify and resolve many common PCI-related issues.
This article provides a detailed, practical guide that walks through how to use PCIList for troubleshooting, how to interpret its output, and step-by-step solutions for frequent problems such as missing devices, driver mismatches, resource conflicts, and firmware/BIOS issues.
Table of contents
- What PCIList shows and why it’s useful
- How to run PCIList and common command options
- Interpreting PCIList output: vendor/device IDs, classes, BARs, IRQs, and driver bindings
- Common problems and how PCIList helps diagnose them
- Device not listed at all
- Device listed but driver not bound
- Resource conflicts and missing BARs
- Incorrect device class or vendor ID (hardware/firmware issues)
- Devices that work intermittently or fail under load
- Step-by-step troubleshooting workflow with examples
- Advanced checks: firmware, bridge devices, and hot-plug systems
- Preventive measures and best practices
- Quick reference checklist
What PCIList shows and why it’s useful
PCIList enumerates PCI, PCI-X, and PCIe devices on a system and reports information such as:
- PCI bus/device/function addresses (e.g., 0000:00:1f.2)
- Vendor and device IDs (e.g., 8086:2929)
- Human-readable vendor/device names (when available)
- Class and subclass (e.g., mass storage controller, network controller)
- Base Address Registers (BARs) and their sizes/addresses (I/O and memory mappings)
- Interrupt line and routing information (if available)
- Driver binding (which kernel driver is attached) and kernel module info
Why that matters: many PCI issues are caused by missing drivers, incorrect resources (memory or I/O ranges), BIOS/firmware misconfiguration, or hardware faults. PCIList gives a clear snapshot of how the system sees each physical device.
How to run PCIList and common command options
Common usage patterns (replace with the actual PCIList invocation on your platform if different):
- Basic listing:
piclistorpcilist(depending on your distribution/tool) — shows all devices. - Verbose:
pcilist -v— displays extra details such as BAR sizes, IRQs, and driver module. - Filter by bus/device:
pcilist 0000:03:*orpcilist -s 03— narrow to specific segments. - Show vendor/device IDs:
pcilist -n— numeric-only IDs for scripting. - JSON output (if supported):
pcilist --json— useful for automation.
If your system uses another tool (lspci, sysfs, or Windows Device Manager), you can map the same checks — PCIList is just one way to gather the data.
Interpreting PCIList output: key fields
- Address (domain:bus:device.function): the unique location of the device on the PCI bus. Use this for targeted commands (e.g., driver binding or BIOS hotplug).
- Vendor:Device ID: two 16-bit hex fields identifying the hardware (useful to lookup drivers and known issues).
- Class/Subclass: shows what the device is supposed to be (e.g., 02:00 — network controller).
- BARs: Base Address Registers describe memory or I/O ranges the device uses. BAR absence or zero-sized BARs can indicate firmware/bridge problems.
- IRQ/INTx/MSI: how the device raises interrupts. Missing or conflicting IRQs can cause non-functional devices.
- Driver/Module: which driver (if any) is bound. A missing driver means either kernel lacks support or driver failed to bind due to resource or firmware issues.
Common problems and how to use PCIList to diagnose them
1) Device not listed at all
Symptoms: The device is not shown by PCIList but is physically present (you can see it on the motherboard or connected externally).
Diagnosis steps:
- Confirm hardware: reseat the card, check connectors, ensure power where applicable.
- Verify BIOS/UEFI settings: check if the slot is disabled or if the device is behind a disabled bridge (some boards let you disable onboard devices).
- Check for hotplug: if the device is in a hot-pluggable slot, ensure the slot is powered and initialized.
- Use lower-level bus scans: check dmesg/kernel logs for PCI enumeration errors (e.g., “PCI: failed to read configuration space”).
- Try another slot or system: isolates board vs. device fault.
What PCIList shows when useful: absence from PCIList confirms bus-level enumeration failure; coupled with kernel logs, you can tell if enumeration failed due to a physical connection, firmware, or chipset problem.
2) Device listed but driver not bound
Symptoms: Device appears in PCIList, but the driver/module column is empty or shows “unknown”.
Diagnosis steps:
- Check vendor:device ID against kernel driver bindings (modinfo, drivers’ id tables).
- Confirm kernel module presence:
modinfo <module>orlsmod. - Attempt manual binding: echo the device address or vendor:device ID into sysfs driver_override or bind to the driver using the driver’s bind path:
- echo vendor:device > /sys/bus/pci/drivers_probe (example pattern varies)
- echo 0000:03:00.0 > /sys/bus/pci/drivers/
/bind
- Inspect dmesg after binding attempt; look for firmware requests or errors like “firmware: failed to load”.
- If binding fails with firmware error, obtain the required firmware blob and place it in /lib/firmware (or appropriate location) then reload the driver.
How PCIList helps: confirms device ID and current driver binding state so you know whether the issue is driver absence, mismatch, or firmware.
3) Resource conflicts and missing BARs
Symptoms: Driver reports I/O or memory allocation failures; device behaves unpredictably. PCIList shows BARs of size 0 or overlapping addresses.
Diagnosis steps:
- Inspect BARs in PCIList: zero-sized BARs often mean the host bridge or BIOS didn’t assign resources.
- Check for conflicts: compare BAR ranges of other devices.
- Reboot with BIOS settings defaulted or update BIOS — sometimes resource allocation logic changes.
- For PCI-to-PCI bridges, ensure the bridge has been assigned a window large enough to contain downstream devices. PCIList can show bridge windows and help confirm this.
- Kernel boot parameters (e.g., pci=noacpi, pci=realloc) can change resource allocation; test these to see whether the kernel reallocates conflicting resources.
When PCIList shows overlapping/zero BARs: indicates host-side allocation problem or firmware not enabling the device’s resources.
4) Incorrect device class or vendor ID (hardware/firmware issues)
Symptoms: PCIList reports odd vendor/device IDs (e.g., 0000:0000 or generic class), or a device shows the wrong class.
Diagnosis steps:
- A 0000:0000 or unusually generic ID can indicate a device that’s failing to reply to configuration space reads — a hardware fault or power issue.
- For devices behind an bridge or switch, ensure proper power and link training (especially on PCIe).
- Update device firmware or BIOS for known quirks; check vendor documentation for required BIOS settings (e.g., SR-IOV enable/disable).
- Test the device in another system to rule out board-specific issues.
How PCIList helps: shows the config-space values that help differentiate between device firmware returning garbage vs. actual misidentification by software.
5) Devices that work intermittently or fail under load
Symptoms: Device works initially but disconnects or hangs under stress.
Diagnosis steps:
- Check dmesg for link resets, AER (Advanced Error Reporting) messages, or driver errors.
- Use PCIList to monitor changes in device state (presence, link speed, or BARs) before and after stress.
- For PCIe: verify link speed/width (if available) and check for downshifts or link training failures.
- Update drivers and firmware; enable AER and examine logs for specific error codes.
- Consider thermal or power issues: measure voltages and temperatures if possible.
PCIList’s role: periodic snapshots show whether the device disappears from the bus or only driver-level errors occur.
Step-by-step troubleshooting workflow (example)
-
Gather baseline:
- Run PCIList verbose: note address, vendor:device ID, class, BARs, IRQ, and driver.
- Save output:
pcilist --json > pcilist-before.json(or text file).
-
Inspect kernel logs:
- Check dmesg/journalctl for PCI-related messages. Look for configuration space read failures, firmware requests, or driver probe errors.
-
Verify driver:
- If driver missing, lookup module that supports vendor:device ID. Try manual bind and watch logs.
-
Check BIOS/UEFI:
- Confirm slot/bridge enabled, update BIOS, reset to defaults if needed.
-
Test hardware:
- Reseat card, swap slots/cables, or test in another machine.
-
Advanced: resource reallocation
- Try kernel parameters like pci=realloc=on or pci=assign-busses to force reallocation (test in controlled environment).
-
Reproduce and collect data:
- Run stress tests while logging kernel messages and taking repeated PCIList snapshots for before/after comparison.
Example: Network card not binding
- PCIList shows 0000:03:00.0 8086:10fb class 02:00 driver: (none)
- modinfo e1000e shows it supports 8086:10fb — attempt:
- echo 0000:03:00.0 > /sys/bus/pci/drivers/e1000e/bind
- Check dmesg — firmware missing? then fetch firmware or update kernel module.
Advanced checks: firmware, bridges, and hot-plug
- Firmware blobs: many modern NICs and storage controllers require firmware loaded by the kernel driver. dmesg will show missing firmware names; place them in /lib/firmware and reload.
- PCIe bridges and switches: ensure upstream bridges have adequate memory windows; use PCIList to inspect bridge window sizes. Misconfigured bridge windows can cause downstream devices to be invisible or show truncated BARs.
- Hot-plug and runtime power management: devices behind hot-pluggable slots may need explicit enablement by the platform; check /sys/bus/pci/slots and related files.
- AER and correct error handling: enable AER in BIOS and kernel logs to get actionable error codes for PCIe errors.
Preventive measures and best practices
- Keep BIOS/UEFI and device firmware updated for known PCI quirks.
- Use supported kernels/drivers or vendor-supplied drivers when devices have specialized firmware needs.
- When adding multiple expansion cards, check motherboard manual for lane-sharing and slot priorities.
- Reserve time for resource reallocation testing when adding unusual hardware; consider using kernel boot parameters in test environments first.
- Keep a repository of known vendor:device ID mappings and firmware names for your common devices.
Quick reference checklist
- Is the device listed in PCIList? If no: check physical connection and BIOS.
- If listed, is a driver bound? If no: find driver, attempt manual bind, check firmware.
- Are BARs nonzero and non-overlapping? If no: check bridge windows and BIOS resource allocation.
- Any kernel log errors? Search dmesg for firmware, AER, or probe failures.
- Test card in another slot/system to isolate hardware vs platform problem.
Troubleshooting PCI devices is often a process of elimination: PCIList provides a reliable, consistent snapshot of how the system sees hardware, which you can combine with kernel logs, firmware updates, and hardware checks to find and fix problems.
Leave a Reply