-.TH lspci 8 "@TODAY@" "@VERSION@" "Linux PCI Utilities"
-.IX lspci
+.TH lspci 8 "@TODAY@" "@VERSION@" "The PCI Utilities"
.SH NAME
lspci \- list all PCI devices
.SH SYNOPSIS
.RB [ options ]
.SH DESCRIPTION
.B lspci
-is a utility for displaying information about all PCI buses in the system and
-all devices connected to them.
+is a utility for displaying information about PCI buses in the system and
+devices connected to them.
-To make use of all the features of this program, you need to have Linux kernel
-2.1.82 or newer which supports the /proc/bus/pci interface. With older kernels,
-the PCI utilities have to use direct hardware access which is available
-only to root and it suffers from numerous race conditions and other problems.
+By default, it shows a brief list of devices. Use the options described
+below to request either a more verbose output or output intended for
+parsing by other programs.
If you are going to report bugs in PCI device drivers or in
.I lspci
-itself, please include output of "lspci -vvx".
+itself, please include output of "lspci -vvx" or even better "lspci -vvxxx"
+(however, see below for possible caveats).
+
+Some parts of the output, especially in the highly verbose modes, are probably
+intelligible only to experienced PCI hackers. For exact definitions of
+the fields, please consult either the PCI specifications or the
+.B header.h
+and
+.B /usr/include/linux/pci.h
+include files.
+
+Access to some parts of the PCI configuration space is restricted to root
+on many operating systems, so the features of
+.I lspci
+available to normal users are limited. However,
+.I lspci
+tries its best to display as much as available and mark all other
+information with
+.I <access denied>
+text.
.SH OPTIONS
+
+.SS Basic display modes
+.TP
+.B -m
+Dump PCI device data in a backward-compatible machine readable form.
+See below for details.
+.TP
+.B -mm
+Dump PCI device data in a machine readable form for easy parsing by scripts.
+See below for details.
+.TP
+.B -t
+Show a tree-like diagram containing all buses, bridges, devices and connections
+between them.
+
+.SS Display options
.TP
.B -v
-Tells
-.I lspci
-to be verbose and display detailed information about all devices.
+Be verbose and display detailed information about all devices.
.TP
.B -vv
-Tells
-.I lspci
-to be very verbose and display even more information (actually everything the
-PCI device is able to tell). The exact meaning of these data is not explained
-in this manual page, if you want to know more, consult
-.B /usr/include/linux/pci.h
-or the PCI specs.
+Be very verbose and display more details. This level includes everything deemed
+useful.
.TP
-.B -n
-Show PCI vendor and device codes as numbers instead of looking them up in the
-PCI ID database.
+.B -vvv
+Be even more verbose and display everything we are able to parse,
+even if it doesn't look interesting at all (e.g., undefined memory regions).
+.TP
+.B -k
+Show kernel drivers handling each device and also kernel modules capable of handling it.
+Turned on by default when
+.B -v
+is given in the normal mode of output.
+(Currently works only on Linux with kernel 2.6 or newer.)
.TP
.B -x
-Show hexadecimal dump of first 64 bytes of the PCI configuration space (the standard
-header). Useful for debugging of drivers and
-.I lspci
-itself.
+Show hexadecimal dump of the standard part of the configuration space (the first
+64 bytes or 128 bytes for CardBus bridges).
.TP
.B -xxx
-Show hexadecimal dump of whole PCI configuration space. Available only for root
+Show hexadecimal dump of the whole PCI configuration space. It is available only to root
as several PCI devices
.B crash
-when you try to read undefined portions of the config space (this behaviour probably
-doesn't violate the PCI standard, but it's at least very stupid).
+when you try to read some parts of the config space (this behavior probably
+doesn't violate the PCI standard, but it's at least very stupid). However, such
+devices are rare, so you needn't worry much.
+.TP
+.B -xxxx
+Show hexadecimal dump of the extended (4096-byte) PCI configuration space available
+on PCI-X 2.0 and PCI Express buses.
.TP
.B -b
Bus-centric view. Show all IRQ numbers and addresses as seen by the cards on the
PCI bus instead of as seen by the kernel.
.TP
-.B -t
-Show a tree-like diagram containing all buses, bridges, devices and connections
-between them.
+.B -D
+Always show PCI domain numbers. By default, lspci suppresses them on machines which
+have only domain 0.
+.TP
+.B -P
+Identify PCI devices by path through each bridge, instead of by bus number.
+.TP
+.B -PP
+Identify PCI devices by path through each bridge, showing the bus number as
+well as the device number.
+
+.SS Options to control resolving ID's to names
+.TP
+.B -n
+Show PCI vendor and device codes as numbers instead of looking them up in the
+PCI ID list.
+.TP
+.B -nn
+Show PCI vendor and device codes as both numbers and names.
+.TP
+.B -q
+Use DNS to query the central PCI ID database if a device is not found in the local
+.B pci.ids
+file. If the DNS query succeeds, the result is cached in
+.B $XDG_CACHE_HOME/pci-ids
+and it is recognized in subsequent runs even if
+.B -q
+is not given any more. Please use this switch inside automated scripts only
+with caution to avoid overloading the database servers.
+.TP
+.B -qq
+Same as
+.BR -q ,
+but the local cache is reset.
.TP
-.B -s [[<bus>]:][<slot>][.[<func>]]
-Show only devices in specified bus, slot and function. Each component of the device
-address can be omitted or set as "*" meaning "any value". All numbers are
+.B -Q
+Query the central database even for entries which are recognized locally.
+Use this if you suspect that the displayed entry is wrong.
+
+.SS Options for selection of devices
+.TP
+.B -s [[[[<domain>]:]<bus>]:][<device>][.[<func>]]
+Show only devices in the specified domain (in case your machine has several host bridges,
+they can either share a common bus number space or each of them can address a PCI domain
+of its own; domains are numbered from 0 to ffff), bus (0 to ff), device (0 to 1f) and function (0 to 7).
+Each component of the device address can be omitted or set to "*", both meaning "any value". All numbers are
hexadecimal. E.g., "0:" means all devices on bus 0, "0" means all functions of device 0
on any bus, "0.3" selects third function of device 0 on all buses and ".4" shows only
-fourth function of each device.
+the fourth function of each device.
.TP
-.B -d [<vendor>]:[<device>]
-Show only devices with specified vendor and device ID. Both ID's are given in
-hexadecimal and may be omitted or given as "*" meaning "any value".
+.B -d [<vendor>]:[<device>][:<class>[:<prog-if>]]
+Show only devices with specified vendor, device, class ID, and programming interface.
+The ID's are given in hexadecimal and may be omitted or given as "*", both meaning
+"any value". The class ID can contain "x" characters which stand for "any digit".
+
+.SS Other options
.TP
.B -i <file>
Use
.B
<file>
-as PCI ID database instead of /usr/share/pci.ids.
+as the PCI ID list instead of @IDSDIR@/pci.ids.
.TP
-.B -p <dir>
+.B -p <file>
Use
-.B <dir>
-as directory containing PCI bus information instead of /proc/bus/pci.
-.TP
-.B -m
-Dump PCI device data in machine readable form (both normal and verbose format supported)
-for easy parsing by scripts.
+.B
+<file>
+as the map of PCI ID's handled by kernel modules. By default, lspci uses
+.RI /lib/modules/ kernel_version /modules.pcimap.
+Applies only to Linux systems with recent enough module tools.
.TP
.B -M
-Invoke bus mapping mode which scans the bus extensively to find all devices including
-those behind misconfigured bridges etc. Please note that this is intended only for
-debugging and as it can crash the machine (only in case of buggy devices, but
-unfortunately these happen to exist), it's available only to root. Also using
--M on PCI access methods which don't directly touch the hardware has no
-sense since the results are (modulo bugs in lspci) identical to normal listing
-modes.
+Invoke bus mapping mode which performs a thorough scan of all PCI devices, including
+those behind misconfigured bridges, etc. This option gives meaningful results only
+with a direct hardware access mode, which usually requires root privileges.
+By default, the bus mapper scans domain. You can use the
+.B -s
+option to select a different domain.
.TP
.B --version
-Shows
+Shows
.I lspci
-version. This option should be used standalone.
-
-.SH PCILIB OPTIONS
-The PCI utilities use PCILIB (a portable library providing platform-independent
-functions for PCI configuration space access) to talk to the PCI cards. The following
-options control parameters of the library, especially what access method it uses.
-By default, PCILIB uses the first available access method and displays no debugging
-messages. Each switch is accompanied by a list of hardware/software configurations
-it's supported in.
+version. This option should be used stand-alone.
+.SS PCI access options
+.PP
+The PCI utilities use the PCI library to talk to PCI devices (see
+\fBpcilib\fP(7) for details). You can use the following options to
+influence its behavior:
+.TP
+.B -A <method>
+The library supports a variety of methods to access the PCI hardware.
+By default, it uses the first access method available, but you can use
+this option to override this decision. See \fB-A help\fP for a list of
+available methods and their descriptions.
.TP
-.B -P <dir>
-Use Linux 2.1 style configuration access to directory
-.B <dir>
-instead of /proc/bus/pci. (Linux 2.1 or newer only)
+.B -O <param>=<value>
+The behavior of the library is controlled by several named parameters.
+This option allows one to set the value of any of the parameters. Use \fB-O help\fP
+for a list of known parameters and their default values.
.TP
.B -H1
-Use direct hardware access via Intel configuration mechanism 1. (i386 and compatible only)
+Use direct hardware access via Intel configuration mechanism 1.
+(This is a shorthand for \fB-A intel-conf1\fP.)
.TP
.B -H2
-Use direct hardware access via Intel configuration mechanism 2. Warning: This method
-is able to address only first 16 devices on any bus and it seems to be very
-unrealiable in many cases. (i386 and compatible only)
-.TP
-.B -S
-Use PCI access syscalls. (Linux on Alpha and UltraSparc only)
+Use direct hardware access via Intel configuration mechanism 2.
+(This is a shorthand for \fB-A intel-conf2\fP.)
.TP
.B -F <file>
-Extract all information from given file containing output of lspci -x. This is very
-useful for analysis of user-supplied bug reports, because you can display the
-hardware configuration in any way you want without disturbing the user with
-requests for more dumps. (All systems)
+Instead of accessing real hardware, read the list of devices and values of their
+configuration registers from the given file produced by an earlier run of lspci -x.
+This is very useful for analysis of user-supplied bug reports, because you can display
+the hardware configuration in any way you want without disturbing the user with
+requests for more dumps.
.TP
.B -G
-Increase debug level of the library. (All systems)
+Increase debug level of the library.
+
+.SH MACHINE READABLE OUTPUT
+If you intend to process the output of lspci automatically, please use one of the
+machine-readable output formats
+.RB ( -m ,
+.BR -vm ,
+.BR -vmm )
+described in this section. All other formats are likely to change
+between versions of lspci.
+
+.P
+All numbers are always printed in hexadecimal. If you want to process numeric ID's instead of
+names, please add the
+.B -n
+switch.
+
+.SS Simple format (-m)
+
+In the simple format, each device is described on a single line, which is
+formatted as parameters suitable for passing to a shell script, i.e., values
+separated by whitespaces, quoted and escaped if necessary.
+Some of the arguments are positional: slot, class, vendor name, device name,
+subsystem vendor name and subsystem name (the last two are empty if
+the device has no subsystem); the remaining arguments are option-like:
+
+.TP
+.BI -r rev
+Revision number.
+
+.TP
+.BI -p progif
+Programming interface.
+
+.P
+The relative order of positional arguments and options is undefined.
+New options can be added in future versions, but they will always
+have a single argument not separated from the option by any spaces,
+so they can be easily ignored if not recognized.
+
+.SS Verbose format (-vmm)
+
+The verbose output is a sequence of records separated by blank lines.
+Each record describes a single device by a sequence of lines, each line
+containing a single
+.RI ` tag :
+.IR value '
+pair. The
+.I tag
+and the
+.I value
+are separated by a single tab character.
+Neither the records nor the lines within a record are in any particular order.
+Tags are case-sensitive.
+
+.P
+The following tags are defined:
+
+.TP
+.B Slot
+The name of the slot where the device resides
+.RI ([ domain :] bus : device . function ).
+This tag is always the first in a record.
+
+.TP
+.B Class
+Name of the class.
+
+.TP
+.B Vendor
+Name of the vendor.
+
+.TP
+.B Device
+Name of the device.
+
+.TP
+.B SVendor
+Name of the subsystem vendor (optional).
+
+.TP
+.B SDevice
+Name of the subsystem (optional).
+
+.TP
+.B PhySlot
+The physical slot where the device resides (optional, Linux only).
+
+.TP
+.B Rev
+Revision number (optional).
+
+.TP
+.B ProgIf
+Programming interface (optional).
+
+.TP
+.B Driver
+Kernel driver currently handling the device (optional, Linux only).
+
+.TP
+.B Module
+Kernel module reporting that it is capable of handling the device
+(optional, Linux only). Multiple lines with this tag can occur.
+
+.TP
+.B NUMANode
+NUMA node this device is connected to (optional, Linux only).
+
+.TP
+.B IOMMUGroup
+IOMMU group that this device is part of (optional, Linux only).
+
+.P
+New tags can be added in future versions, so you should silently ignore any tags you don't recognize.
+
+.SS Backward-compatible verbose format (-vm)
+
+In this mode, lspci tries to be perfectly compatible with its old versions.
+It's almost the same as the regular verbose format, but the
+.B
+Device
+tag is used for both the slot and the device name, so it occurs twice
+in a single record. Please avoid using this format in any new code.
.SH FILES
.TP
-.B @SHAREDIR@/pci.ids
-A list of all known PCI ID's (vendors, devices, classes and subclasses).
+.B @IDSDIR@/pci.ids
+A list of all known PCI ID's (vendors, devices, classes and subclasses). Maintained
+at https://pci-ids.ucw.cz/, use the
+.B update-pciids
+utility to download the most recent version.
+.TP
+.B @IDSDIR@/pci.ids.gz
+If lspci is compiled with support for compression, this file is tried before pci.ids.
.TP
-.B /proc/bus/pci
-An interface to PCI bus configuration space provided by the post-2.1.82 Linux
-kernels. Contains per-bus subdirectories with per-card config space files and a
-.I devices
-file containing a list of all PCI devices.
+.B $XDG_CACHE_HOME/pci-ids
+All ID's found in the DNS query mode are cached in this file.
+
+.SH BUGS
+
+Sometimes, lspci is not able to decode the configuration registers completely.
+This usually happens when not enough documentation was available to the authors.
+In such cases, it at least prints the
+.B <?>
+mark to signal that there is potentially something more to say. If you know
+the details, patches will be of course welcome.
+
+Access to the extended configuration space is currently supported only by the
+.B linux_sysfs
+back-end.
.SH SEE ALSO
-.BR setpci (8), update-pciids (8)
+.BR setpci (8),
+.BR pci.ids (5),
+.BR update-pciids (8),
+.BR pcilib (7)
.SH AUTHOR
-The Linux PCI Utilities are maintained by Martin Mares <mj@ucw.cz>.
+The PCI Utilities are maintained by Martin Mares <mj@ucw.cz>.
projects / thirdparty / pciutils.git / blobdiff