setpci(8)                 (31 May 2020)                 setpci(8)

     NAME
          setpci - configure PCI devices

     SYNOPSIS
          setpci [options] devices operations...

     DESCRIPTION
          setpci 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 lspci(8) for
          details on access rights.

     OPTIONS
        General options
          -v   Tells setpci to be verbose and display detailed infor-
               mation about configuration space accesses.

          -f   Tells setpci not to complain when there's nothing to do
               (when no devices are selected).  This option is
               intended for use in widely-distributed configuration
               scripts where it's uncertain whether the device in
               question is present in the machine or not.

          -D   `Demo mode' -- don't write anything to the configura-
               tion registers.  It's useful to try setpci -vD to ver-
               ify that your complex sequence of setpci operations
               does what you think it should do.

          -r   Avoids bus scan if each operation selects a specific
               device (uses the -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.

          --version
               Show setpci version. This option should be used stand-
               alone.

          --help
               Show detailed help on available options. This option
               should be used stand-alone.

          --dumpregs

     Page 1                   pciutils-3.7.0         (printed 5/24/22)

     setpci(8)                 (31 May 2020)                 setpci(8)

               Show a list of all known PCI registers and capabili-
               ties. This option should be used stand-alone.

        PCI access options
          The PCI utilities use the PCI library to talk to PCI devices
          (see pcilib(7) for details). You can use the following
          options to influence its behavior:

          -A <method>
               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 over-
               ride this decision. See -A help for a list of available
               methods and their descriptions.

          -O <param>=<value>
               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 -O help for a list
               of known parameters and their default values.

          -H1  Use direct hardware access via Intel configuration
               mechanism 1.  (This is a shorthand for -A intel-conf1.)

          -H2  Use direct hardware access via Intel configuration
               mechanism 2.  (This is a shorthand for -A intel-conf2.)

          -G   Increase debug level of the library.

     DEVICE SELECTION
          Before each sequence of operations you need to select which
          devices you wish that operation to affect.

          -s [[[[<domain>]:]<bus>]:][<slot>][.[<func>]]
               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" matches only the fourth function
               of each device.

          -d [<vendor>]:[<device>]
               Select devices with specified vendor and device ID.
               Both ID's are given in hexadecimal and may be omitted

     Page 2                   pciutils-3.7.0         (printed 5/24/22)

     setpci(8)                 (31 May 2020)                 setpci(8)

               or given as "*", both meaning "any value".

          When -s and -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.

     OPERATIONS
          There are two kinds of operations: reads and writes. To read
          a register, just specify its name. Writes have the form
          name=value,value... where each value is either a hexadecimal
          number or an expression of type data:mask where both data
          and mask are hexadecimal numbers. In the latter case, only
          the bits corresponding to binary ones in the mask are
          changed (technically, this is a read-modify-write opera-
          tion).

          There are several ways how to identity a register:

          +o    Tell its address in hexadecimal.

          +o    Spell its name. Setpci knows the names of all registers
               in the standard configuration headers. Use `setpci --
               dumpregs' to get the complete list.  See PCI bus speci-
               fications for the precise meaning of these registers or
               consult header.h or /usr/include/pci/pci.h for a brief
               sketch.

          +o    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 --dumpregs output.

          +o    If the name of the capability is not known to setpci,
               you can refer to it by its number in the form CAPid or
               ECAPid, where id is the numeric identifier of the capa-
               bility in hexadecimal.

          +o    Each of the previous formats can be followed by +offset
               to add an offset (a hex number) to the address. This
               feature can be useful for addressing of registers liv-
               ing within a capability, or to modify parts of standard
               registers.

          +o    To choose how many bytes (1, 2, or 4) should be trans-
               ferred, you should append a width specifier .B, .W, or
               .L. The width can be omitted if you are referring to a
               register by its name and the width of the register is
               well known.

          +o    Finally, if a capability exists multiple times you can

     Page 3                   pciutils-3.7.0         (printed 5/24/22)

     setpci(8)                 (31 May 2020)                 setpci(8)

               choose which one to target using @number. Indexing
               starts at 0.

          All names of registers and width specifiers are case-
          insensitive.

          EXAMPLES

          COMMAND
               asks for the word-sized command register.

          4.w  is a numeric address of the same register.

          COMMAND.l
               asks for a 32-bit word starting at the location of the
               command register, i.e., the command and status regis-
               ters together.

          VENDOR_ID+1.b
               specifies the upper byte of the vendor ID register
               (remember, PCI is little-endian).

          CAP_PM+2.w
               corresponds to the second word of the power management
               capability.

          ECAP108.l
               asks for the first 32-bit word of the extended capabil-
               ity with ID 0x108.

     SEE ALSO
          lspci(8), pcilib(7)

     AUTHOR
          The PCI Utilities are maintained by Martin Mares
          <mj@ucw.cz>.

     Page 4                   pciutils-3.7.0         (printed 5/24/22)