LearnLinux › cmds › commands

setpci

Read from and write to PCI configuration space registers.

Category: Hardware PCI low-level diagnostics advanced

Install

# Provided by pciutils package

# RHEL / Alma / Rocky
sudo dnf install pciutils

# Debian / Ubuntu
sudo apt install pciutils

# openSUSE
sudo zypper install pciutils

# Arch
sudo pacman -S pciutils

What it does

setpci allows direct reading and writing of PCI device configuration registers. It is primarily used for low-level hardware debugging, tuning, or driver troubleshooting.

How it works (mechanical)

  • Accesses PCI configuration space via /proc or sysfs interfaces.
  • Identifies devices by bus:device.function address.
  • Can read register values or write new ones.
  • Requires root privileges for write operations.
  • Improper writes can destabilize the system.

Quick Start

# List PCI devices
lspci

# Read register 0x04 (Command register) from device
sudo setpci -s 00:1f.2 04.w

10 Practical Examples

# 1) Read a full config register
sudo setpci -s 00:1f.2 04.w
# 2) Read a byte
sudo setpci -s 00:1f.2 3c.b
# 3) Write to a register (use extreme caution)
sudo setpci -s 00:1f.2 04.w=0007
# 4) Specify device by vendor:device ID
sudo setpci -d 8086:1234 04.w
# 5) Dump multiple registers
sudo setpci -s 00:1f.2 00.l 04.w 10.l
# 6) Compare with lspci verbose output
lspci -vv -s 00:1f.2
# 7) Identify device address
lspci | grep SATA
# 8) Read status register
sudo setpci -s 00:1f.2 06.w
# 9) Debug power management capability
sudo setpci -s 00:1f.2 CAP_PM+2.w
# 10) Show help
setpci --help

Notes & Gotchas

  • Dangerous if misused — incorrect values can crash system.
  • Always inspect with lspci -vv before writing.
  • Primarily for debugging or advanced hardware tuning.
  • May require kernel support for specific registers.
  • Use carefully on production systems.

Historical Context

As PCI became standard for hardware communication, tools like setpci emerged to give administrators low-level control over device configuration space.

Modern Equivalent

Modern driver frameworks and kernel modules handle most configuration automatically. setpci remains useful for diagnostics, firmware debugging, and specialized hardware tuning.

Related Commands

  • lspci — list PCI devices.
  • lsusb — list USB devices.
  • setpci — modify PCI configuration registers.
  • dmesg — view kernel hardware messages.
  • hwinfo — detailed hardware information.