X-Git-Url: http://mj.ucw.cz/gitweb/?a=blobdiff_plain;f=setpci.man;h=c35b9968af50d4abc5fad26ff60e742f723d1b8e;hb=8ad3c8cfcf002557a8302156b79be4c54d4e22d1;hp=b9b044699bca32f6d13fdad026bbe1fc8182ec3c;hpb=d4798a32c44f8e8b98a6da1ed97e4b82c0e071aa;p=pciutils.git diff --git a/setpci.man b/setpci.man index b9b0446..c35b996 100644 --- a/setpci.man +++ b/setpci.man @@ -1,4 +1,4 @@ -.TH setpci 8 "@TODAY@" "@VERSION@" "Linux PCI Utilities" +.TH setpci 8 "@TODAY@" "@VERSION@" "The PCI Utilities" .IX setpci .SH NAME setpci \- configure PCI devices @@ -13,14 +13,17 @@ setpci \- configure PCI devices .B setpci is a utility for querying and configuring PCI devices. -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. - All numbers are entered in hexadecimal notation. +Root privileges are necessary for almost all operations, excluding reads +of the standard header of the configuration space on some operating systems. +Please see +.BR lspci(8) +for details on access rights. + .SH OPTIONS + +.SS General options .TP .B -v Tells @@ -36,167 +39,143 @@ where it's uncertain whether the device in question is present in the machine or not. .TP .B -D -`Demo mode' -- simulate configuration space accesses instead of really doing them. +`Demo mode' -- don't write anything to the configuration registers. It's useful to try .B setpci -vD -to see what your complex sequence of +to verify that your complex sequence of .B setpci -operations does before you actually execute it. +operations does what you think it should do. +.TP +.B --version +Show +.I setpci +version. This option should be used stand-alone. +.TP +.B --help +Show detailed help on available options. This option should be used stand-alone. +.TP +.B --dumpregs +Show a list of all known PCI registers and capabilities. 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 operation to affect. .TP -.B -s [[]:][][.[]] -Select 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 -s [[[[]:]]:][][.[]] +Consider 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), slot (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 busses and ".4" selects only -fourth function of each device. +on any bus, "0.3" selects third function of device 0 on all buses and ".4" matches only +the fourth function of each device. .TP .B -d []:[] Select devices with specified vendor and device ID. Both ID's are given in -hexadecimal and may be omitted or given as "*" meaning "any value". +hexadecimal and may be omitted or given as "*", both meaning "any value". +.PP +When +.B -s +and +.B -d +are combined, only devices that match both criteria are selected. When multiple +options of the same kind are specified, the rightmost one overrides the others. .SH OPERATIONS .PP -To query value of a configuration register, just name it (either by typing its name or -by typing register address with optional -.BR .B , -.B .W -or -.B .L -suffix specifying register width as byte, word or longword). -.PP -To set a register, write -.BR reg = values -where -.B reg -is the same you would use to query the register and -.B values -is a comma-separated list of values you want to write starting with the given -address. +There are two kinds of operations: reads and writes. To read a register, just specify +its name. Writes have the form +.IR name = value , value ... +where each +.I value +is either a hexadecimal number or an expression of type +.IR data : mask +where both +.I data +and +.I mask +are hexadecimal numbers. In the latter case, only the bits corresponding to binary +ones in the \fImask\fP are changed (technically, this is a read-modify-write operation). -.SH REGISTER NAMES .PP -.B setpci -knows the following configuration register names. See PCI bus specs for their precise -meaning or consult -.B /usr/include/linux/pci.h -for few comments. +There are several ways how to identity a register: +.IP \(bu +Tell its address in hexadecimal. +.IP \(bu +Spell its name. Setpci knows the names of all registers in the standard configuration +headers. Use `\fBsetpci --dumpregs\fP' to get the complete list. +See PCI bus specifications for the precise meaning of these registers or consult +\fBheader.h\fP or \fB/usr/include/pci/pci.h\fP for a brief sketch. +.IP \(bu +If the register is a part of a PCI capability, you can specify the name of the +capability to get the address of its first register. See the names starting with +`CAP_' or `ECAP_' in the \fB--dumpregs\fP output. +.IP \(bu +If the name of the capability is not known to \fBsetpci\fP, you can refer to it +by its number in the form CAP\fBid\fP or ECAP\fBid\fP, where \fBid\fP is the numeric +identifier of the capability in hexadecimal. +.IP \(bu +Each of the previous formats can be followed by \fB+offset\fP to add an offset +(a hex number) to the address. This feature can be useful for addressing of registers +living within a capability, or to modify parts of standard registers. +.IP \(bu +Finally, you should append a width specifier \fB.B\fP, \fB.W\fP, or \fB.L\fP to choose +how many bytes (1, 2, or 4) should be transferred. The width can be omitted if you are +referring to a register by its name and the width of the register is well known. + .PP -.nf -VENDOR_ID -DEVICE_ID -COMMAND -STATUS -REVISION -CLASS_PROG -CLASS_DEVICE -CACHE_LINE_SIZE -LATENCY_TIMER -HEADER_TYPE -BIST -BASE_ADDRESS_0 -BASE_ADDRESS_1 -BASE_ADDRESS_2 -BASE_ADDRESS_3 -BASE_ADDRESS_4 -BASE_ADDRESS_5 -CARDBUS_CIS -SUBSYSTEM_VENDOR_ID -SUBSYSTEM_ID -ROM_ADDRESS -INTERRUPT_LINE -INTERRUPT_PIN -MIN_GNT -MAX_LAT -PRIMARY_BUS -SECONDARY_BUS -SUBORDINATE_BUS -SEC_LATENCY_TIMER -IO_BASE -IO_LIMIT -SEC_STATUS -MEMORY_BASE -MEMORY_LIMIT -PREF_MEMORY_BASE -PREF_MEMORY_LIMIT -PREF_BASE_UPPER32 -PREF_LIMIT_UPPER32 -IO_BASE_UPPER16 -IO_LIMIT_UPPER16 -BRIDGE_ROM_ADDRESS -BRIDGE_CONTROL -CB_CARDBUS_BASE -CB_CAPABILITIES -CB_SEC_STATUS -CB_BUS_NUMBER -CB_CARDBUS_NUMBER -CB_SUBORDINATE_BUS -CB_CARDBUS_LATENCY -CB_MEMORY_BASE_0 -CB_MEMORY_LIMIT_0 -CB_MEMORY_BASE_1 -CB_MEMORY_LIMIT_1 -CB_IO_BASE_0 -CB_IO_BASE_0_HI -CB_IO_LIMIT_0 -CB_IO_LIMIT_0_HI -CB_IO_BASE_1 -CB_IO_BASE_1_HI -CB_IO_LIMIT_1 -CB_IO_LIMIT_1_HI -CB_SUBSYSTEM_VENDOR_ID -CB_SUBSYSTEM_ID -CB_LEGACY_MODE_BASE +All names of registers and width specifiers are case-insensitive. -.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. +.SH +EXAMPLES -.TP -.B -P -Use Linux 2.1 style configuration access to directory -.B -instead of /proc/bus/pci. (Linux 2.1 or newer only) -.TP -.B -H1 -Use direct hardware access via Intel configuration mechanism 1. (i386 and compatible only) -.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) -.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) -.TP -.B -G -Increase debug level of the library. (All systems) - -.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 busses. -.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. +.IP COMMAND +asks for the word-sized command register. +.IP 4.w +is a numeric address of the same register. +.IP COMMAND.l +asks for a 32-bit word starting at the location of the command register, +i.e., the command and status registers together. +.IP VENDOR_ID+1.b +specifies the upper byte of the vendor ID register (remember, PCI is little-endian). +.IP CAP_PM+2.w +corresponds to the second word of the power management capability. +.IP ECAP108.l +asks for the first 32-bit word of the extended capability with ID 0x108. .SH SEE ALSO -.BR lspci (8) +.BR lspci (8), +.BR pcilib (7) .SH AUTHOR -The Linux PCI Utilities are maintained by Martin Mares . +The PCI Utilities are maintained by Martin Mares .