From f2bf13dc3261bdd761dd18067a2c2c91339f4d5c Mon Sep 17 00:00:00 2001 From: Martin Mares Date: Tue, 12 Feb 2008 12:17:20 +0100 Subject: [PATCH] Improved man pages. Parts related to the library moved to pcilib(7). --- Makefile | 7 +- lspci.man | 190 ++++++++++++++++++++++------------------------------- pcilib.man | 109 ++++++++++++++++++++++++++++++ setpci.man | 54 ++++++++------- 4 files changed, 224 insertions(+), 136 deletions(-) create mode 100644 pcilib.man diff --git a/Makefile b/Makefile index 3706917..35bc7a8 100644 --- a/Makefile +++ b/Makefile @@ -31,7 +31,7 @@ RELEASE= export -all: $(PCILIB) lspci setpci lspci.8 setpci.8 update-pciids update-pciids.8 $(PCI_IDS) +all: $(PCILIB) lspci setpci lspci.8 setpci.8 pcilib.7 update-pciids update-pciids.8 $(PCI_IDS) $(PCILIB): $(PCIINC) force $(MAKE) -C lib all @@ -55,12 +55,12 @@ update-pciids: update-pciids.sh %: %.o $(CC) $(LDFLAGS) $(TARGET_ARCH) $^ $(LDLIBS) -o $@ -%.8: %.man +%.8 %.7: %.man M=`echo $(DATE) | sed 's/-01-/-January-/;s/-02-/-February-/;s/-03-/-March-/;s/-04-/-April-/;s/-05-/-May-/;s/-06-/-June-/;s/-07-/-July-/;s/-08-/-August-/;s/-09-/-September-/;s/-10-/-October-/;s/-11-/-November-/;s/-12-/-December-/;s/\(.*\)-\(.*\)-\(.*\)/\3 \2 \1/'` ; sed <$< >$@ "s/@TODAY@/$$M/;s/@VERSION@/pciutils-$(VERSION)/;s#@IDSDIR@#$(IDSDIR)#" clean: rm -f `find . -name "*~" -o -name "*.[oa]" -o -name "\#*\#" -o -name TAGS -o -name core -o -name "*.orig"` - rm -f update-pciids lspci setpci lib/config.* lib/example *.8 pci.ids.* lib/*.pc + rm -f update-pciids lspci setpci lib/config.* lib/example *.[78] pci.ids.* lib/*.pc rm -rf maint/dist distclean: clean @@ -72,6 +72,7 @@ install: all $(INSTALL) -c -m 755 update-pciids $(DESTDIR)$(SBINDIR) $(INSTALL) -c -m 644 $(PCI_IDS) $(DESTDIR)$(IDSDIR) $(INSTALL) -c -m 644 lspci.8 setpci.8 update-pciids.8 $(DESTDIR)$(MANDIR)/man8 + $(INSTALL) -c -m 644 pcilib.7 $(DESTDIR)$(MANDIR)/man7 install-lib: $(PCIINC_INS) $(PCILIB) $(PCILIBPC) $(DIRINSTALL) -m 755 $(DESTDIR)$(INCDIR)/pci $(DESTDIR)$(LIBDIR) $(DESTDIR)$(PKGCFDIR) diff --git a/lspci.man b/lspci.man index e3b1c05..dfddacd 100644 --- a/lspci.man +++ b/lspci.man @@ -7,8 +7,8 @@ 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 @@ -19,8 +19,8 @@ If you are going to report bugs in PCI device drivers or in 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, is probably -intelligible only to experienced PCI hackers. For the exact definitions of +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 @@ -38,6 +38,22 @@ information with 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 Be verbose and display detailed information about all devices. @@ -50,6 +66,39 @@ useful. 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 the standard part of the configuration space (the first +64 bytes or 128 bytes for CardBus bridges). +.TP +.B -xxx +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 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 -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. @@ -75,37 +124,8 @@ but the local cache is reset. .B -Q Query the central database even for entries which are recognized locally. Use this if you suspect that the displayed entry is wrong. -.TP -.B -x -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 the whole PCI configuration space. It is available only to root -as several PCI devices -.B crash -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 -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 -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. + +.SS Options for selection of devices .TP .B -s [[[[]:]]:][][.[]] Show only devices in the specified domain (in case your machine has several host bridges, @@ -119,6 +139,8 @@ the fourth function of each device. .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 "*", both meaning "any value". + +.SS Other options .TP .B -i Use @@ -134,18 +156,6 @@ 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 -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 -D -Always show PCI domain numbers. By default, lspci suppresses them on machines which -have only domain 0. -.TP .B -M Invoke bus mapping mode which performs a thorough scan of all PCI devices, including those behind misconfigured bridges etc. This option is available only to root and it @@ -158,73 +168,36 @@ Shows .I lspci version. This option should be used stand-alone. -.SH PCILIB AND ITS OPTIONS -The PCI utilities use PCILIB (a portable library providing platform-independent -functions for PCI configuration space access) to talk to the PCI cards. It supports -the following access methods: - +.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 linux_sysfs -The -.B /sys -filesystem on Linux 2.6 and newer. The standard header of the config space is available -to all users, the rest only to root. Supports extended configuration space, PCI domains -and information on attached kernel drivers. -.TP -.B linux_proc -The -.B /proc/bus/pci -interface supported by Linux 2.1 and newer. The standard header of the config space is available -to all users, the rest only to root. -.TP -.B intel_conf1 -Direct hardware access via Intel configuration mechanism 1. Available on i386 and compatibles -on Linux, Solaris/x86, GNU Hurd and Windows. Requires root privileges. -.TP -.B intel_conf2 -Direct hardware access via Intel configuration mechanism 2. Available on i386 and compatibles -on Linux, Solaris/x86 and GNU Hurd. Requires root privileges. Warning: This method -is able to address only first 16 devices on any bus and it seems to be very -unreliable in many cases. -.TP -.B fbsd_device -The -.B /dev/pci -device on FreeBSD. Requires root privileges. -.TP -.B obsd_device -The -.B /dev/pci -device on OpenBSD. Requires root privileges. -.TP -.B nbsd_libpci -The -.B /dev/pci0 -device on NetBSD accessed using the local libpci library. -.TP -.B aix_device -Access method used on AIX. Requires root privileges. - -.P -By default, PCILIB uses the first available access method and displays no debugging -messages, but you can use the following switches to control its behavior: - +.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 the linux_proc access method, using -.B -instead of /proc/bus/pci. +.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. +(This is a shorthand for \fB-A intel-conf1\fP.) .TP .B -H2 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 +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 @@ -354,12 +327,6 @@ If lspci is compiled with support for compression, this file is tried before pci .TP .B ~/.pciids-cache All ID's found in the DNS query mode are cached in this file. -.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. .SH BUGS @@ -376,7 +343,8 @@ back-end. .SH SEE ALSO .BR setpci (8), -.BR update-pciids (8) +.BR update-pciids (8), +.BR pcilib (7) .SH AUTHOR The PCI Utilities are maintained by Martin Mares . diff --git a/pcilib.man b/pcilib.man new file mode 100644 index 0000000..6cf5682 --- /dev/null +++ b/pcilib.man @@ -0,0 +1,109 @@ +.TH pcilib 7 "@TODAY@" "@VERSION@" "The PCI Utilities" +.IX pcilib +.SH NAME +pcilib \- a library for accessing PCI devices + +.SH DESCRIPTION + +The PCI library (also known as \fIpcilib\fP and \fIlibpci\fP) is a portable library +for accessing PCI devices and their configuration space. + +.SH ACCESS METHODS + +.PP +The library supports a variety of methods to access the configuration space +on different operating systems. By default, the first matching method in this +list is used, but you can specify override the decision (see the \fB-A\fP switch +of \fIlspci\fP). + +.TP +.B linux-sysfs +The +.B /sys +filesystem on Linux 2.6 and newer. The standard header of the config space is available +to all users, the rest only to root. Supports extended configuration space, PCI domains +and information on attached kernel drivers. +.TP +.B linux-proc +The +.B /proc/bus/pci +interface supported by Linux 2.1 and newer. The standard header of the config space is available +to all users, the rest only to root. +.TP +.B intel-conf1 +Direct hardware access via Intel configuration mechanism 1. Available on i386 and compatibles +on Linux, Solaris/x86, GNU Hurd and Windows. Requires root privileges. +.TP +.B intel-conf2 +Direct hardware access via Intel configuration mechanism 2. Available on i386 and compatibles +on Linux, Solaris/x86, GNU Hurd and Windows. Requires root privileges. Warning: This method +is able to address only the first 16 devices on any bus and it seems to be very +unreliable in many cases. +.TP +.B fbsd-device +The +.B /dev/pci +device on FreeBSD. Requires root privileges. +.TP +.B aix-device +Access method used on AIX. Requires root privileges. +.TP +.B nbsd-libpci +The +.B /dev/pci0 +device on NetBSD accessed using the local libpci library. +.TP +.B obsd-device +The +.B /dev/pci +device on OpenBSD. Requires root privileges. +.TP +.B dump +Read the contents of configuration registers from a file specified in the +.B dump.name +parameter. The format corresponds to the output of \fIlspci\fP \fB-x\fP. + +.SH PARAMETERS + +.PP +The library is controlled by several parameters. They should have sensible default +values, but in case you want to do something unusual (or even something weird), +you can override them (see the \fB-O\fP switch of \fIlspci\fP). + +.SS Parameters of specific access methods + +.TP +.B dump.name +Name of the bus dump file to read from. +.TP +.B fbsd.path +Path to the FreeBSD PCI device. +.TP +.B nbsd.path +Path to the NetBSD PCI device. +.TP +.B obsd.path +Path to the OpenBSD PCI device. +.TP +.B proc.path +Path to the procfs bus tree. +.TP +.B sysfs.path +Path to the sysfs device tree. + +.SS Parameters for resolving of ID's via DNS +.TP +.B net.domain +DNS domain containing the ID database. +.TP +.B net.cache_name +Name of the file used for caching of resolved ID's. + +.SH SEE ALSO + +.BR lspci (8), +.BR setpci (8), +.BR update-pciids (8) + +.SH AUTHOR +The PCI Utilities are maintained by Martin Mares . diff --git a/setpci.man b/setpci.man index 80f1a68..d682c37 100644 --- a/setpci.man +++ b/setpci.man @@ -22,6 +22,8 @@ Please see for details on access rights. .SH OPTIONS + +.SS General options .TP .B -v Tells @@ -49,6 +51,34 @@ Shows .I setpci 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 -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. +(This is a shorthand for \fB-A intel-conf1\fP.) +.TP +.B -H2 +Use direct hardware access via Intel configuration mechanism 2. +(This is a shorthand for \fB-A intel-conf2\fP.) +.TP +.B -G +Increase debug level of the library. + .SH DEVICE SELECTION .PP Before each sequence of operations you need to select which devices you wish that @@ -169,29 +199,9 @@ CB_SUBSYSTEM_VENDOR_ID CB_SUBSYSTEM_ID CB_LEGACY_MODE_BASE -.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. Please -see -.BR lspci(8) -for a list of switches controlling behavior of the library. - -.SH EXAMPLES -.PP -`setpci -d *:* latency_timer=40' sets the latency timer to 64 (40 hexadecimal). -.PP -`setpci -s 0 device_id vendor_id' lists ID's of devices in slot 0 in all buses. -.PP -`setpci -s 12:3.4 3c.l=1,2,3' writes longword 1 to register 3c, 2 to register 3d -and 3 to register 3e of device at bus 12, slot 3, function 4. -.PP -`setpci -s 13:8.4 40.b=50:d0,04:0c,ff' works on bus 13, device 8, function -4: turns bit 7 off and bits 6 and 4 on in the byte register 40; turns -bit 3 off and bit 2 on in the byte register 41; sets byte register -42 to ff. - .SH SEE ALSO -.BR lspci (8) +.BR lspci (8), +.BR pcilib (7) .SH AUTHOR The PCI Utilities are maintained by Martin Mares . -- 2.39.2