Return to setpci.man CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / pciutils

pciutils

    1: .TH setpci 8 "@TODAY@" "@VERSION@" "The PCI Utilities"
    2: .IX setpci
    3: .SH NAME
    4: setpci \- configure PCI devices
    5: .SH SYNOPSIS
    6: .B setpci
    7: .RB [ options ]
    8: .B devices
    9: .BR operations ...
   10: 
   11: .SH DESCRIPTION
   12: .PP
   13: .B setpci
   14: is a utility for querying and configuring PCI devices.
   15: 
   16: All numbers are entered in hexadecimal notation.
   17: 
   18: Root privileges are necessary for almost all operations, excluding reads
   19: of the standard header of the configuration space on some operating systems.
   20: Please see
   21: .BR lspci(8)
   22: for details on access rights.
   23: 
   24: .SH OPTIONS
   25: 
   26: .SS General options
   27: .TP
   28: .B -v
   29: Tells
   30: .I setpci
   31: to be verbose and display detailed information about configuration space accesses.
   32: .TP
   33: .B -f
   34: Tells
   35: .I setpci
   36: not to complain when there's nothing to do (when no devices are selected).
   37: This option is intended for use in widely-distributed configuration scripts
   38: where it's uncertain whether the device in question is present in the machine
   39: or not.
   40: .TP
   41: .B -D
   42: `Demo mode' -- don't write anything to the configuration registers.
   43: It's useful to try
   44: .B setpci -vD
   45: to verify that your complex sequence of
   46: .B setpci
   47: operations does what you think it should do.
   48: .TP
   49: .B --version
   50: Show
   51: .I setpci
   52: version. This option should be used stand-alone.
   53: .TP
   54: .B --help
   55: Show detailed help on available options. This option should be used stand-alone.
   56: .TP
   57: .B --dumpregs
   58: Show a list of all known PCI registers and capabilities. This option should be
   59: used stand-alone.
   60: 
   61: .SS PCI access options
   62: .PP
   63: The PCI utilities use the PCI library to talk to PCI devices (see
   64: \fBpcilib\fP(7) for details). You can use the following options to
   65: influence its behavior:
   66: .TP
   67: .B -A <method>
   68: The library supports a variety of methods to access the PCI hardware.
   69: By default, it uses the first access method available, but you can use
   70: this option to override this decision. See \fB-A help\fP for a list of
   71: available methods and their descriptions.
   72: .TP
   73: .B -O <param>=<value>
   74: The behavior of the library is controlled by several named parameters.
   75: This option allows to set the value of any of the parameters. Use \fB-O help\fP
   76: for a list of known parameters and their default values.
   77: .TP
   78: .B -H1
   79: Use direct hardware access via Intel configuration mechanism 1.
   80: (This is a shorthand for \fB-A intel-conf1\fP.)
   81: .TP
   82: .B -H2
   83: Use direct hardware access via Intel configuration mechanism 2.
   84: (This is a shorthand for \fB-A intel-conf2\fP.)
   85: .TP
   86: .B -G
   87: Increase debug level of the library.
   88: 
   89: .SH DEVICE SELECTION
   90: .PP
   91: Before each sequence of operations you need to select which devices you wish that
   92: operation to affect.
   93: .TP
   94: .B -s [[[[<domain>]:]<bus>]:][<slot>][.[<func>]]
   95: Consider only devices in the specified domain (in case your machine has several host bridges,
   96: they can either share a common bus number space or each of them can address a PCI domain
   97: of its own; domains are numbered from 0 to ffff), bus (0 to ff), slot (0 to 1f) and function (0 to 7).
   98: Each component of the device address can be omitted or set to "*", both meaning "any value". All numbers are
   99: hexadecimal.  E.g., "0:" means all devices on bus 0, "0" means all functions of device 0
  100: on any bus, "0.3" selects third function of device 0 on all buses and ".4" matches only
  101: the fourth function of each device.
  102: .TP
  103: .B -d [<vendor>]:[<device>]
  104: Select devices with specified vendor and device ID. Both ID's are given in
  105: hexadecimal and may be omitted or given as "*", both meaning "any value".
  106: .PP
  107: When
  108: .B -s
  109: and
  110: .B -d
  111: are combined, only devices that match both criteria are selected. When multiple
  112: options of the same kind are specified, the rightmost one overrides the others.
  113: 
  114: .SH OPERATIONS
  115: .PP
  116: There are two kinds of operations: reads and writes. To read a register, just specify
  117: its name. Writes have the form
  118: .IR name = value , value ...
  119: where each
  120: .I value
  121: is either a hexadecimal number or an expression of type
  122: .IR data : mask
  123: where both
  124: .I data
  125: and
  126: .I mask
  127: are hexadecimal numbers. In the latter case, only the bits corresponding to binary
  128: ones in the \fImask\fP are changed (technically, this is a read-modify-write operation).
  129: 
  130: .PP
  131: There are several ways how to identity a register:
  132: .IP \(bu
  133: Tell its address in hexadecimal.
  134: .IP \(bu
  135: Spell its name. Setpci knows the names of all registers in the standard configuration
  136: headers. Use `\fBsetpci --dumpregs\fP' to get the complete list.
  137: See PCI bus specifications for the precise meaning of these registers or consult
  138: \fBheader.h\fP or \fB/usr/include/pci/pci.h\fP for a brief sketch.
  139: .IP \(bu
  140: If the register is a part of a PCI capability, you can specify the name of the
  141: capability to get the address of its first register. See the names starting with
  142: `CAP_' or `ECAP_' in the \fB--dumpregs\fP output.
  143: .IP \(bu
  144: If the name of the capability is not known to \fBsetpci\fP, you can refer to it
  145: by its number in the form CAP\fBid\fP or ECAP\fBid\fP, where \fBid\fP is the numeric
  146: identifier of the capability in hexadecimal.
  147: .IP \(bu
  148: Each of the previous formats can be followed by \fB+offset\fP to add an offset
  149: (a hex number) to the address. This feature can be useful for addressing of registers
  150: living within a capability, or to modify parts of standard registers.
  151: .IP \(bu
  152: Finally, you should append a width specifier \fB.B\fP, \fB.W\fP, or \fB.L\fP to choose
  153: how many bytes (1, 2, or 4) should be transferred. The width can be omitted if you are
  154: referring to a register by its name and the width of the register is well known.
  155: 
  156: .PP
  157: All names of registers and width specifiers are case-insensitive.
  158: 
  159: .SH
  160: EXAMPLES
  161: 
  162: .IP COMMAND
  163: asks for the word-sized command register.
  164: .IP 4.w
  165: is a numeric address of the same register.
  166: .IP COMMAND.l
  167: asks for a 32-bit word starting at the location of the command register,
  168: i.e., the command and status registers together.
  169: .IP VENDOR_ID+1.b
  170: specifies the upper byte of the vendor ID register (remember, PCI is little-endian).
  171: .IP CAP_PM+2.w
  172: corresponds to the second word of the power management capability.
  173: .IP ECAP108.l
  174: asks for the first 32-bit word of the extended capability with ID 0x108.
  175: 
  176: .SH SEE ALSO
  177: .BR lspci (8),
  178: .BR pcilib (7)
  179: 
  180: .SH AUTHOR
  181: The PCI Utilities are maintained by Martin Mares <mj@ucw.cz>.