| 1 |
.TH pcilib 7 "05 April 2026" "pciutils-3.15.0" "The PCI Utilities" |
| 2 |
.SH NAME |
| 3 |
pcilib \- a library for accessing PCI devices |
| 4 |
|
| 5 |
.SH DESCRIPTION |
| 6 |
|
| 7 |
The PCI library (also known as \fIpcilib\fP and \fIlibpci\fP) is a portable library |
| 8 |
for accessing PCI devices and their configuration space. |
| 9 |
|
| 10 |
.SH ACCESS METHODS |
| 11 |
|
| 12 |
.PP |
| 13 |
The library supports a variety of methods to access the configuration space |
| 14 |
on different operating systems. By default, the first matching method in this |
| 15 |
list is used, but you can specify override the decision (see the \fB-A\fP switch |
| 16 |
of \fIlspci\fP). |
| 17 |
|
| 18 |
.TP |
| 19 |
.B linux-sysfs |
| 20 |
The |
| 21 |
.B /sys |
| 22 |
filesystem on Linux 2.6 and newer. The standard header of the config space is available |
| 23 |
to all users, the rest only to root. Supports extended configuration space, PCI domains, |
| 24 |
VPD (from Linux 2.6.26), physical slots (also since Linux 2.6.26) and information on attached |
| 25 |
kernel drivers. |
| 26 |
.TP |
| 27 |
.B linux-proc |
| 28 |
The |
| 29 |
.B /proc/bus/pci |
| 30 |
interface supported by Linux 2.1 and newer. The standard header of the config space is available |
| 31 |
to all users, the rest only to root. |
| 32 |
.TP |
| 33 |
.B intel-conf1 |
| 34 |
Direct hardware access via Intel configuration mechanism 1. Available on i386 and compatibles |
| 35 |
on Linux, Solaris/x86, GNU Hurd, Windows, BeOS and Haiku. Requires root privileges. |
| 36 |
.TP |
| 37 |
.B intel-conf2 |
| 38 |
Direct hardware access via Intel configuration mechanism 2. Available on i386 and compatibles |
| 39 |
on Linux, Solaris/x86, GNU Hurd, Windows, BeOS and Haiku. Requires root privileges. Warning: This method |
| 40 |
is able to address only the first 16 devices on any bus and it seems to be very |
| 41 |
unreliable in many cases. |
| 42 |
.TP |
| 43 |
.B mmio-conf1 |
| 44 |
Direct hardware access via Intel configuration mechanism 1 via memory-mapped I/O. |
| 45 |
Mostly used on non-i386 platforms. Requires root privileges. Warning: This method |
| 46 |
needs to be properly configured via the |
| 47 |
.B mmio-conf1.addrs |
| 48 |
parameter. |
| 49 |
.TP |
| 50 |
.B mmio-conf1-ext |
| 51 |
Direct hardware access via Extended PCIe Intel configuration mechanism 1 via memory-mapped I/O. |
| 52 |
Mostly used on non-i386 platforms. Requires root privileges. Warning: This method |
| 53 |
needs to be properly configured via the |
| 54 |
.B mmio-conf1-ext.addrs |
| 55 |
parameter. |
| 56 |
.TP |
| 57 |
.B ecam |
| 58 |
Direct hardware access via PCIe ECAM (Enhanced Configuration Access Mechanism). |
| 59 |
Available on all PCIe-compliant hardware. Requires root privileges and access |
| 60 |
to physical memory (on Linux systems disabled CONFIG_STRICT_DEVMEM option). On |
| 61 |
ACPI compatible systems is ECAM mapping read from the MCFG table specified by the |
| 62 |
.B ecam.acpimcfg |
| 63 |
parameter. On EFI compatible systems, ACPI MCFG table can be located in physical |
| 64 |
memory via EFI system table specified by the |
| 65 |
.B ecam.efisystab |
| 66 |
parameter. On FreeBSD/NetBSD systems, physical address of ACPI MCFG table can be |
| 67 |
located by kenv or sysctl interface when the |
| 68 |
.B ecam.bsd |
| 69 |
parameter is not disabled. On x86 BIOS compatible systems, ACPI MCFG table can |
| 70 |
be located in physical memory by scanning x86 BIOS memory when the |
| 71 |
.B ecam.x86bios |
| 72 |
parameter is not disabled. Alternatively ECAM mappings can be specified by the |
| 73 |
.B ecam.addrs |
| 74 |
parameter which takes precedence over ACPI MCFG table. This option is required |
| 75 |
on systems without ACPI and also on systems without EFI or x86 BIOS. |
| 76 |
.TP |
| 77 |
.B fbsd-device |
| 78 |
The |
| 79 |
.B /dev/pci |
| 80 |
device on FreeBSD. Requires root privileges. |
| 81 |
.TP |
| 82 |
.B aix-device |
| 83 |
Access method used on AIX. Requires root privileges. |
| 84 |
.TP |
| 85 |
.B nbsd-libpci |
| 86 |
The |
| 87 |
.B /dev/pci0 |
| 88 |
device on NetBSD accessed using the local libpci library. |
| 89 |
.TP |
| 90 |
.B obsd-device |
| 91 |
The |
| 92 |
.B /dev/pci |
| 93 |
device on OpenBSD. Requires root privileges. |
| 94 |
.TP |
| 95 |
.B dump |
| 96 |
Read the contents of configuration registers from a file specified in the |
| 97 |
.B dump.name |
| 98 |
parameter. The format corresponds to the output of \fIlspci\fP \fB-x\fP. |
| 99 |
.TP |
| 100 |
.B darwin |
| 101 |
Access method used on Mac OS X / Darwin. Must be run as root and the system |
| 102 |
must have been booted with debug=0x144. |
| 103 |
.TP |
| 104 |
.B win32-cfgmgr32 |
| 105 |
Device listing on Windows systems using the Windows Configuration Manager |
| 106 |
via cfgmgr32.dll system library. This method does not require any special |
| 107 |
Administrator rights or privileges. Configuration Manager provides only basic |
| 108 |
information about devices, assigned resources and device tree structure. There |
| 109 |
is no access to the PCI configuration space but libpci either tries to use |
| 110 |
other access method to access configuration space or it provides read-only |
| 111 |
virtual emulation based on information from Configuration Manager. Other |
| 112 |
access method can be chosen by the |
| 113 |
.B win32.cfgmethod |
| 114 |
parameter. By default the first working one is selected (if any). Starting |
| 115 |
with Windows 8 (NT 6.2) it is not possible to retrieve resources from 32-bit |
| 116 |
application or library on 64-bit system. |
| 117 |
.TP |
| 118 |
.B win32-sysdbg |
| 119 |
Access to the PCI configuration space via NT SysDbg interface on Windows |
| 120 |
systems. Process needs to have Debug privilege, which local Administrators |
| 121 |
have by default. Not available on 64-bit systems and neither on recent 32-bit |
| 122 |
systems. Only devices from the first domain are accessible and only first |
| 123 |
256 bytes of the PCI configuration space is accessible via this method. |
| 124 |
.TP |
| 125 |
.B win32-kldbg |
| 126 |
Access to the PCI configuration space via Kernel Local Debugging Driver |
| 127 |
kldbgdrv.sys. This driver is not part of the Windows system but is part of |
| 128 |
the Microsoft WinDbg tool. It is required to have kldbgdrv.sys driver installed |
| 129 |
in the system32 directory or to have windbg.exe or kd.exe binary in PATH. |
| 130 |
windbg.exe or kd.exe binary contains embedded kldbgdrv.sys driver which libpci |
| 131 |
can automatically unpack and register. Because of embedded driver usage, it is |
| 132 |
required that architecture of windbg.exe or kd.exe binary matches the system |
| 133 |
architecture, and not the libpci application architecture. Therefore for running |
| 134 |
i386 libpci application on AMD64 system, it is required to have AMD64 version of |
| 135 |
kldbgdrv.sys driver in the native system32 directory or AMD64 version of |
| 136 |
windbg.exe or kd.exe binary in the PATH. i386 versions of these binaries would |
| 137 |
not work. win32-kldbg access method compiled for 32-bit applications supports |
| 138 |
both 32-bit and also 64-bit OS host systems, therefore i386 libpci application |
| 139 |
with win32-kldbg method can access PCI config space also on AMD64 host system. |
| 140 |
kldbgdrv.sys driver has some restrictions. Process needs to have Debug privilege |
| 141 |
and Windows system has to be booted with Debugging option. Debugging option can |
| 142 |
be enabled by calling (takes effect after next boot): |
| 143 |
.B bcdedit /debug on |
| 144 |
.IP |
| 145 |
Download links for WinDbg 6.12.2.633 standalone installer from Microsoft Windows |
| 146 |
SDK for Windows 7 and .NET Framework 4: |
| 147 |
.br |
| 148 |
amd64: https://download.microsoft.com/download/A/6/A/A6AC035D-DA3F-4F0C-ADA4-37C8E5D34E3D/setup/WinSDKDebuggingTools_amd64/dbg_amd64.msi |
| 149 |
.br |
| 150 |
ia64: https://download.microsoft.com/download/A/6/A/A6AC035D-DA3F-4F0C-ADA4-37C8E5D34E3D/setup/WinSDKDebuggingTools_ia64/dbg_ia64.msi |
| 151 |
.br |
| 152 |
x86: https://download.microsoft.com/download/A/6/A/A6AC035D-DA3F-4F0C-ADA4-37C8E5D34E3D/setup/WinSDKDebuggingTools/dbg_x86.msi |
| 153 |
.IP |
| 154 |
Archived download links of previous WinDbg versions: |
| 155 |
.br |
| 156 |
https://web.archive.org/web/20110221133326/https://www.microsoft.com/whdc/devtools/debugging/installx86.mspx |
| 157 |
.br |
| 158 |
https://web.archive.org/web/20110214012715/https://www.microsoft.com/whdc/devtools/debugging/install64bit.mspx |
| 159 |
.TP |
| 160 |
.B aos-expansion |
| 161 |
Access method used on PowerPC Amiga running OS4+. Access is made through Expansion.library. It offers read and write access to configuration space. |
| 162 |
.TP |
| 163 |
.B rt-thread-smart |
| 164 |
The |
| 165 |
.B /proc/pci |
| 166 |
filesystem provided by RT-Thread Smart OS. This method requires PCI support |
| 167 |
(with the procfs feature enabled) to be available in the driver subsystem, |
| 168 |
and the DFS v2-based procfs must be mounted in a rootfs-enabled environment. |
| 169 |
It provides access to the standard PCI configuration space, with limited |
| 170 |
information available. |
| 171 |
|
| 172 |
.SH PARAMETERS |
| 173 |
|
| 174 |
.PP |
| 175 |
The library is controlled by several parameters. They should have sensible default |
| 176 |
values, but in case you want to do something unusual (or even something weird), |
| 177 |
you can override them (see the \fB-O\fP switch of \fIlspci\fP). |
| 178 |
|
| 179 |
.SS Parameters of specific access methods |
| 180 |
|
| 181 |
.TP |
| 182 |
.B dump.name |
| 183 |
Name of the bus dump file to read from. |
| 184 |
.TP |
| 185 |
.B fbsd.path |
| 186 |
Path to the FreeBSD PCI device. |
| 187 |
.TP |
| 188 |
.B nbsd.path |
| 189 |
Path to the NetBSD PCI device. |
| 190 |
.TP |
| 191 |
.B obsd.path |
| 192 |
Path to the OpenBSD PCI device. |
| 193 |
.TP |
| 194 |
.B proc.path |
| 195 |
Path to the procfs bus tree. |
| 196 |
.TP |
| 197 |
.B sysfs.path |
| 198 |
Path to the sysfs device tree. |
| 199 |
.TP |
| 200 |
.B rt-thread-smart-dm.path |
| 201 |
Path to the rt-thread smart DM procfs device tree. |
| 202 |
.TP |
| 203 |
.B devmem.path |
| 204 |
Path to the /dev/mem device or path to the \\Device\\PhysicalMemory NT section |
| 205 |
or name of the platform specific physical address access method. Generally on |
| 206 |
POSIX systems it is path to memory device and on Windows systems it is path to |
| 207 |
memory NT section. Additionally on 32-bit Windows systems are recognized also |
| 208 |
platform methods: \fIvxdcall\fP, \fIw32skrnl\fP. On DOS/DJGPP systems are |
| 209 |
recognized only platform methods: \fIauto\fP, \fIdevmap\fP, \fIphysmap\fP. |
| 210 |
DJGPP's \fIdevmap\fP method uses DPMI 1.0 functions 0508H (Map Device in Memory |
| 211 |
Block) and 0509H (Map Conventional Memory in Memory Block). DJGPP's \fIphysmap\fP |
| 212 |
method uses DPMI 0.9 function 0800H (Physical Address Mapping). DJGPP's \fIauto\fP |
| 213 |
parameter automatically chooses one of the mentioned method supported by the system. |
| 214 |
.TP |
| 215 |
.B mmio-conf1.addrs |
| 216 |
Physical addresses of memory-mapped I/O ports for Intel configuration mechanism 1. |
| 217 |
CF8 (address) and CFC (data) I/O port addresses are separated by slash and |
| 218 |
multiple addresses for different PCI domains are separated by commas. |
| 219 |
Format: 0xaddr1/0xdata1,0xaddr2/0xdata2,... |
| 220 |
.TP |
| 221 |
.B mmio-conf1-ext.addrs |
| 222 |
Physical addresses of memory-mapped I/O ports for Extended PCIe Intel configuration mechanism 1. |
| 223 |
It has same format as |
| 224 |
.B mmio-conf1.addrs |
| 225 |
parameter. |
| 226 |
.TP |
| 227 |
.B ecam.addrs |
| 228 |
Physical addresses of PCIe ECAM mappings. Each mapping must contains first PCI |
| 229 |
bus number and physical address where mapping starts. And then it may contain |
| 230 |
the length of the mapping, the last PCI bus number and PCI domain number. When |
| 231 |
the last PCI bus number is not provided then it is calculated from the length |
| 232 |
of the mapping or it is assumed 0xff. When length of the mapping is provided |
| 233 |
then it is calculated from the last PCI bus number. And when PCI domain is not |
| 234 |
provided then 0x0 is assumed. All numbers must be supplied in hexadecimal form |
| 235 |
(leading prefix 0x is not required). Multiple mappings are separated by commas. |
| 236 |
Format: [domain:]start_bus[-end_bus]:start_addr[+length],... |
| 237 |
.TP |
| 238 |
.B ecam.acpimcfg |
| 239 |
Path to the ACPI MCFG table. Processed by the |
| 240 |
.BR glob (3) |
| 241 |
function, so it may contain wildcards (*). |
| 242 |
.TP |
| 243 |
.B ecam.efisystab |
| 244 |
Path to the EFI system table. |
| 245 |
.TP |
| 246 |
.B ecam.bsd |
| 247 |
When not set to 0 then use BSD kenv or sysctl to find ACPI MCFG table. Default |
| 248 |
value is 1 on BSD systems. |
| 249 |
.TP |
| 250 |
.B ecam.x86bios |
| 251 |
When not set to 0 then scan x86 BIOS memory for ACPI MCFG table. Default value |
| 252 |
is 1 on x86 systems. |
| 253 |
.TP |
| 254 |
.B win32.cfgmethod |
| 255 |
Config space access method to use with win32-cfgmgr32 on Windows systems. Value |
| 256 |
.I auto |
| 257 |
or an empty string selects the first access method which supports access |
| 258 |
to the config space on Windows. Value |
| 259 |
.I win32-cfgmgr32 |
| 260 |
or |
| 261 |
.I none |
| 262 |
only builds a read-only virtual emulated config space with information from the |
| 263 |
Configuration Manager. |
| 264 |
|
| 265 |
.SS Parameters for resolving of IDs via DNS |
| 266 |
.TP |
| 267 |
.B net.domain |
| 268 |
DNS domain containing the ID database. |
| 269 |
.TP |
| 270 |
.B net.cache_name |
| 271 |
Name of the file used for caching of resolved IDs. An initial |
| 272 |
.B ~/ |
| 273 |
is expanded to the user's home directory. |
| 274 |
|
| 275 |
.SS Parameters for resolving of IDs via UDEV's HWDB |
| 276 |
.TP |
| 277 |
.B hwdb.disable |
| 278 |
Disable use of HWDB if set to a non-zero value. |
| 279 |
|
| 280 |
.SH SEE ALSO |
| 281 |
|
| 282 |
.BR lspci (8), |
| 283 |
.BR setpci (8), |
| 284 |
.BR pci.ids (5), |
| 285 |
.BR update-pciids (8) |
| 286 |
|
| 287 |
.SH AUTHOR |
| 288 |
The PCI Utilities are maintained by Martin Mares <[email protected]>. |