Complete Guide to lspci: Viewing and Managing PCI Devices in Linux

Table of Contents

1. [Introduction](#introduction) 2. [Understanding PCI Architecture](#understanding-pci-architecture) 3. [Basic lspci Usage](#basic-lspci-usage) 4. [Command Syntax and Options](#command-syntax-and-options) 5. [Output Formats and Interpretation](#output-formats-and-interpretation) 6. [Advanced Usage Examples](#advanced-usage-examples) 7. [Troubleshooting with lspci](#troubleshooting-with-lspci) 8. [Related Files and Directories](#related-files-and-directories) 9. [Best Practices](#best-practices) 10. [Common Use Cases](#common-use-cases)

Introduction

The lspci command is a fundamental Linux utility used to display information about all PCI (Peripheral Component Interconnect) devices connected to the system. This powerful tool provides detailed hardware information that is essential for system administration, troubleshooting, driver installation, and hardware inventory management.

PCI devices include graphics cards, network adapters, sound cards, storage controllers, USB controllers, and many other hardware components. Understanding how to effectively use lspci is crucial for Linux system administrators, developers, and power users who need to interact with hardware at a low level.

Understanding PCI Architecture

PCI Bus Structure

The PCI architecture follows a hierarchical structure that can be understood through several key concepts:

| Component | Description | Function | |-----------|-------------|----------| | PCI Bus | Main communication pathway | Connects multiple PCI devices to the CPU and memory | | PCI Bridge | Connection between buses | Allows multiple PCI buses to be connected | | PCI Device | Individual hardware component | Graphics cards, network cards, storage controllers | | PCI Function | Logical unit within device | Multiple functions can exist on single device |

PCI Addressing Scheme

PCI devices are identified using a standardized addressing scheme:

` Domain:Bus:Device.Function `

| Field | Range | Description | |-------|-------|-------------| | Domain | 0000-FFFF | PCI domain (usually 0000 for single-domain systems) | | Bus | 00-FF | PCI bus number within domain | | Device | 00-1F | Device number on specific bus | | Function | 0-7 | Function number within device |

PCI Device Classes

PCI devices are categorized into classes that define their primary function:

| Class Code | Class Name | Common Devices | |------------|------------|----------------| | 01 | Mass Storage Controller | SATA, SCSI, NVMe controllers | | 02 | Network Controller | Ethernet, WiFi adapters | | 03 | Display Controller | Graphics cards, VGA adapters | | 04 | Multimedia Controller | Audio devices, video capture | | 06 | Bridge Device | PCI-to-PCI bridges, host bridges | | 0C | Serial Bus Controller | USB, FireWire controllers |

Basic lspci Usage

Simple Device Listing

The most basic usage of lspci displays all PCI devices in a simple format:

`bash lspci `

Example output: ` 00:00.0 Host bridge: Intel Corporation 8th Gen Core Processor Host Bridge/DRAM Registers 00:02.0 VGA compatible controller: Intel Corporation UHD Graphics 620 00:14.0 USB controller: Intel Corporation Sunrise Point-LP USB 3.0 xHCI Controller 00:16.0 Communication controller: Intel Corporation Sunrise Point-LP CSME HECI #1 00:1c.0 PCI bridge: Intel Corporation Sunrise Point-LP PCI Express Root Port #1 00:1f.0 ISA bridge: Intel Corporation Sunrise Point-LP LPC Controller 00:1f.3 Audio device: Intel Corporation Sunrise Point-LP HD Audio 02:00.0 Network controller: Intel Corporation Wireless-AC 9260 `

Understanding Basic Output Format

Each line in the basic output follows this structure:

` [Domain:]Bus:Device.Function Device_Class: Vendor Device_Description `

For example, analyzing the line: ` 00:02.0 VGA compatible controller: Intel Corporation UHD Graphics 620 `

| Component | Value | Meaning | |-----------|-------|---------| | Bus | 00 | Bus number 0 | | Device | 02 | Device number 2 | | Function | 0 | Function number 0 | | Class | VGA compatible controller | Device type | | Vendor | Intel Corporation | Manufacturer | | Description | UHD Graphics 620 | Specific device model |

Command Syntax and Options

General Syntax

`bash lspci [options] [device] `

Essential Command Options

| Option | Long Form | Description | Use Case | |--------|-----------|-------------|----------| | -v | --verbose | Verbose output with detailed information | Hardware troubleshooting | | -vv | --very-verbose | Very verbose output | Driver development | | -vvv | --extremely-verbose | Extremely verbose output | Low-level debugging | | -n | --numeric | Show numeric IDs instead of names | Scripting and automation | | -nn | --numeric-names | Show both numeric IDs and names | Complete device identification | | -k | --kernel | Show kernel drivers and modules | Driver management | | -t | --tree | Show devices in tree format | Understanding topology | | -s | --slot | Show specific device by slot | Targeted device inspection |

Output Format Options

| Option | Description | Example Usage | |--------|-------------|---------------| | -m | Machine readable format | lspci -m | | -mm | Enhanced machine readable | lspci -mm | | -x | Hexadecimal dump of config space | lspci -x | | -xxx | Full hexadecimal dump | lspci -xxx |

Filtering Options

| Option | Description | Syntax | |--------|-------------|--------| | -d | Filter by vendor/device ID | lspci -d vendor:device | | -s | Filter by slot | lspci -s bus:device.function |

Output Formats and Interpretation

Verbose Output Analysis

Using the -v option provides extensive device information:

`bash lspci -v -s 00:02.0 `

Example output: ` 00:02.0 VGA compatible controller: Intel Corporation UHD Graphics 620 (rev 07) (prog-if 00 [VGA controller]) Subsystem: Lenovo ThinkPad T480 Flags: bus master, fast devsel, latency 0, IRQ 127 Memory at eb000000 (64-bit, non-prefetchable) [size=16M] Memory at 60000000 (64-bit, prefetchable) [size=256M] I/O ports at e000 [size=64] Expansion ROM at 000c0000 [virtual] [disabled] [size=128K] Capabilities: [40] Vendor Specific Information: Len=0c Capabilities: [70] Express Root Complex Integrated Endpoint, MSI 00 Capabilities: [ac] MSI: Enable+ Count=1/1 Maskable- 64bit- Kernel driver in use: i915 Kernel modules: i915 `

Interpreting Verbose Output

| Field | Description | Significance | |-------|-------------|--------------| | Subsystem | OEM-specific implementation | Identifies exact system/motherboard | | Flags | Device capabilities and status | Shows operational characteristics | | Memory regions | Physical memory mappings | Important for driver configuration | | I/O ports | Input/output port ranges | Legacy device communication | | Capabilities | Advanced PCI features | Modern PCI functionality | | Kernel driver | Currently loaded driver | Shows active driver binding |

Numeric ID Format

Using -nn shows both names and numeric identifiers:

`bash lspci -nn `

Example output: ` 00:02.0 VGA compatible controller [0300]: Intel Corporation UHD Graphics 620 [8086:5917] (rev 07) 00:14.0 USB controller [0c03]: Intel Corporation Sunrise Point-LP USB 3.0 xHCI Controller [8086:9d2f] (rev 21) `

The numeric format [vendor_id:device_id] is crucial for: - Driver development and matching - Hardware database lookups - Automated system inventory - Cross-reference with manufacturer specifications

Advanced Usage Examples

Displaying Device Tree Structure

The tree format shows the hierarchical relationship between PCI devices:

`bash lspci -t `

Example output: ` -[0000:00]-+-00.0 +-02.0 +-14.0 +-16.0 +-1c.0-[01]-- +-1c.4-[02]----00.0 +-1f.0 +-1f.3 \-1f.6 `

This tree structure reveals: - Root complex at 00:00.0 - Direct connections to root - PCI bridges creating secondary buses - Devices connected through bridges

Verbose Tree Output

Combining tree and verbose options:

`bash lspci -tv `

Example output: ` -[0000:00]-+-00.0 Intel Corporation 8th Gen Core Processor Host Bridge/DRAM Registers +-02.0 Intel Corporation UHD Graphics 620 +-14.0 Intel Corporation Sunrise Point-LP USB 3.0 xHCI Controller +-16.0 Intel Corporation Sunrise Point-LP CSME HECI #1 +-1c.0-[01]-- +-1c.4-[02]----00.0 Intel Corporation Wireless-AC 9260 +-1f.0 Intel Corporation Sunrise Point-LP LPC Controller +-1f.3 Intel Corporation Sunrise Point-LP HD Audio \-1f.6 Intel Corporation Ethernet Connection (4) I219-LM `

Kernel Driver Information

To see which kernel drivers are associated with PCI devices:

`bash lspci -k `

Example output: ` 00:02.0 VGA compatible controller: Intel Corporation UHD Graphics 620 (rev 07) Subsystem: Lenovo ThinkPad T480 Kernel driver in use: i915 Kernel modules: i915

00:14.0 USB controller: Intel Corporation Sunrise Point-LP USB 3.0 xHCI Controller (rev 21) Subsystem: Lenovo ThinkPad T480 Kernel driver in use: xhci_hcd

02:00.0 Network controller: Intel Corporation Wireless-AC 9260 (rev 29) Subsystem: Intel Corporation Wireless-AC 9260 Kernel driver in use: iwlwifi Kernel modules: iwlwifi `

Filtering by Device Type

Filter devices by vendor ID:

`bash lspci -d 8086: `

This shows only Intel devices (vendor ID 8086).

Filter by specific device:

`bash lspci -d 8086:5917 `

This shows only Intel UHD Graphics 620 devices.

Machine-Readable Output

For scripting and automation:

`bash lspci -mm `

Example output: ` "00:00.0" "Host bridge" "Intel Corporation" "8th Gen Core Processor Host Bridge/DRAM Registers" -r07 "Lenovo" "ThinkPad T480" "00:02.0" "VGA compatible controller" "Intel Corporation" "UHD Graphics 620" -r07 "Lenovo" "ThinkPad T480" `

Configuration Space Examination

View the first 64 bytes of PCI configuration space:

`bash lspci -x -s 00:02.0 `

Example output: ` 00:02.0 VGA compatible controller: Intel Corporation UHD Graphics 620 (rev 07) 00: 86 80 17 59 07 04 10 00 07 00 00 03 00 00 00 00 10: 04 00 00 eb 0c 00 00 60 01 e0 00 00 00 00 00 00 20: 00 00 00 00 00 00 00 00 00 00 00 00 aa 17 80 22 30: 00 00 0c 00 40 00 00 00 00 00 00 00 ff 01 00 00 `

Troubleshooting with lspci

Common Troubleshooting Scenarios

| Issue | lspci Command | What to Look For | |-------|---------------|------------------| | Missing device | lspci \| grep -i device_name | Device absence in listing | | Driver problems | lspci -k -s slot | Missing or incorrect driver | | Hardware conflicts | lspci -vv -s slot | IRQ conflicts, memory overlaps | | Performance issues | lspci -vv | Link speed, capabilities |

Diagnosing Missing Devices

If a device is not appearing in lspci output:

1. Check physical connection 2. Verify power supply 3. Check BIOS/UEFI settings 4. Rescan PCI bus:

`bash echo 1 > /sys/bus/pci/rescan `

Driver Troubleshooting

To identify driver issues:

`bash lspci -k | grep -A 3 "Device_Name" `

Look for: - Missing "Kernel driver in use" line - Incorrect driver loaded - Available modules not being used

Hardware Capability Analysis

Check if devices support advanced features:

`bash lspci -vv -s 00:02.0 | grep -i "express\|msi\|power" `

This reveals: - PCIe version and link speed - MSI/MSI-X interrupt capabilities - Power management features

Related Files and Directories

PCI Database Files

| File Path | Description | Usage | |-----------|-------------|-------| | /usr/share/misc/pci.ids | PCI device database | Device name resolution | | /sys/bus/pci/devices/ | Sysfs PCI device tree | Runtime device information | | /proc/bus/pci/ | Legacy PCI interface | Deprecated, use sysfs |

Configuration Files

| Location | Purpose | Contents | |----------|---------|----------| | /etc/modprobe.d/ | Module configuration | Driver parameters and blacklists | | /lib/modules/$(uname -r)/modules.alias | Module aliases | Device ID to module mapping |

Sysfs PCI Interface

The /sys/bus/pci/devices/ directory contains detailed information for each PCI device:

`bash ls /sys/bus/pci/devices/0000:00:02.0/ `

Common files in device directories:

| File | Description | Example Usage | |------|-------------|---------------| | vendor | Vendor ID | cat vendor | | device | Device ID | cat device | | class | Device class | cat class | | config | Configuration space | hexdump -C config | | resource | Memory/IO resources | cat resource |

Best Practices

Regular System Monitoring

Create scripts for regular PCI device monitoring:

`bash #!/bin/bash

Save PCI device list for comparison

Documentation and Inventory

Maintain hardware inventory using lspci:

`bash

Generate comprehensive hardware report

Automated Driver Checking

Script to identify devices without drivers:

`bash #!/bin/bash lspci -k | grep -B 2 -A 1 "Kernel driver in use:" | grep -B 3 "Kernel modules:" | grep "^[0-9]" | while read line; do if ! echo "$line" | grep -q "Kernel driver in use:"; then echo "No driver: $line" fi done `

Performance Monitoring

Monitor PCI device performance characteristics:

`bash

Check PCIe link speeds

Common Use Cases

System Administration

| Task | Command | Purpose | |------|---------|---------| | Hardware inventory | lspci -nn > inventory.txt | Document system hardware | | Driver audit | lspci -k | Verify driver assignments | | Troubleshoot hardware | lspci -vv -s slot | Detailed device analysis | | Check new hardware | lspci \| diff - previous_scan.txt | Identify changes |

Development and Debugging

| Scenario | Command | Application | |----------|---------|-------------| | Driver development | lspci -xxx -s slot | Access full config space | | Vendor/device lookup | lspci -nn -d vendor: | Find specific hardware | | Capability analysis | lspci -vv \| grep -i capability | Feature identification | | Bus topology | lspci -tv | Understand connections |

Security and Compliance

| Purpose | Command | Benefit | |---------|---------|---------| | Hardware verification | lspci -nn | Confirm expected devices | | Unauthorized device detection | Compare lspci output over time | Security monitoring | | Compliance reporting | lspci -mm | Machine-readable format |

Performance Optimization

Understanding PCI device capabilities helps optimize system performance:

`bash

Check PCIe generations and lane counts

This information is crucial for: - Graphics card performance tuning - Storage controller optimization - Network adapter configuration - Memory bandwidth planning

The lspci command is an indispensable tool for Linux system administration, providing comprehensive insights into system hardware. Mastering its various options and output formats enables effective hardware management, troubleshooting, and system optimization. Regular use of lspci helps maintain system health and ensures optimal hardware utilization.