X-Git-Url: http://mj.ucw.cz/gitweb/?a=blobdiff_plain;f=lspci.man;h=9348cfc54f36d4abfa346269e47a01c6a2543370;hb=c4cf2d1c17594d333ccd819212756e3afb8b9924;hp=18d032c9c7775672cd3212a9f4746fa65d0c41d9;hpb=4063c31c8f8a4110e7dd70d612fb64ef9ec1941c;p=pciutils.git diff --git a/lspci.man b/lspci.man index 18d032c..9348cfc 100644 --- a/lspci.man +++ b/lspci.man @@ -1,5 +1,4 @@ -.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 @@ -7,141 +6,352 @@ lspci \- list all PCI devices .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. + +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 +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. + +.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 ~/.pciids-cache +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 [[]:][][.[]] -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 [[[[]:]]:][][.[]] +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 []:[] -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 []:[][:] +Show only devices with specified vendor, device and class ID. The ID's are +given in hexadecimal and may be omitted or given as "*", both meaning +"any value". + +.SS Other options .TP .B -i Use .B -as PCI ID database instead of @SHAREDIR@/pci.ids. +as the PCI ID list instead of @IDSDIR@/pci.ids. .TP -.B -p +.B -p Use -.B -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 + +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. +Please note that the bus mapper only scans PCI domain 0. .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 +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 -Force use of Linux /proc/bus/pci style configuration access, using -.B -instead of /proc/bus/pci. (Linux 2.1 or newer only) +.B -O = +The behavior of the library is controlled by several named parameters. +This option allows 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 -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). + +.TP +.B NUMANode +NUMA node this device is connected to (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 http://pciids.sourceforge.net/, 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 ~/.pciids-cache +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 update-pciids (8), +.BR pcilib (7) .SH AUTHOR -The Linux PCI Utilities are maintained by Martin Mares . +The PCI Utilities are maintained by Martin Mares .