X-Git-Url: http://mj.ucw.cz/gitweb/?a=blobdiff_plain;ds=sidebyside;f=setpci.man;h=9e4e1d8a6c44c2963b33449cd1c8ee4dddb191ea;hb=9535c7aa0f64591428e8c436b9dc4dffebb27665;hp=5dda2480c96bf7b3eb5d2b0807a659ea2ede8846;hpb=1f7c91ccc8a51398e91834a75a6ac08dde68550b;p=pciutils.git diff --git a/setpci.man b/setpci.man index 5dda248..9e4e1d8 100644 --- a/setpci.man +++ b/setpci.man @@ -1,5 +1,4 @@ .TH setpci 8 "@TODAY@" "@VERSION@" "The PCI Utilities" -.IX setpci .SH NAME setpci \- configure PCI devices .SH SYNOPSIS @@ -15,7 +14,15 @@ is a utility for querying and configuring PCI devices. 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 @@ -34,15 +41,56 @@ or not. `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 -r +Avoids bus scan if each operation selects a specific device (uses the +.B -s +selector with specific domain, bus, slot, and function). This is faster, +but if the device does not exist, it fails instead of matching an empty +set of devices. .TP .B --version -Shows +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 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. +(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 @@ -50,165 +98,94 @@ Before each sequence of operations you need to select which devices you wish tha operation to affect. .TP .B -s [[[[]:]]:][][.[]] -Show only devices in the specified domain (in case your machine has several host bridges, +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 buses and ".4" shows only +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 "*", both meaning "any value". +.B -d []:[][:[:]] +Select 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". +.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 as 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. Each value to be written can be specified either as a hexadecimal number -or as a -.BR bits : mask -pair which causes the bits corresponding to binary ones in the -.B mask -to be changed to values of the corresponding bits in the -.B bits -. +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 +To choose how many bytes (1, 2, or 4) should be transferred, you should append a width +specifier \fB.B\fP, \fB.W\fP, or \fB.L\fP. The width can be omitted if you are +referring to a register by its name and the width of the register is well known. +.IP \(bu +Finally, if a capability exists multiple times you can choose which one to target using +\fB@number\fP. Indexing starts at 0. + .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 -Force use of Linux /proc/bus/pci style configuration access, using -.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 -unreliable in many cases. (i386 and compatible 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. -.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. +.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 PCI Utilities are maintained by Martin Mares .