Bug #15313


document pcitool register peek/poke mode

Added by Hans Rosenfeld 3 months ago. Updated 9 days ago.

cmd - userland programs
Start date:
Due date:
% Done:


Estimated time:
Gerrit CR:
External Bug:


There is some documentation for the pcitool register peek/poke mode hidden in the source which isn't printed in 'pcitool -h'.

Actions #1

Updated by Electric Monk 3 months ago

  • Gerrit CR set to 2595
Actions #2

Updated by Hans Rosenfeld 9 days ago

Sample output:

# pcitool -h
Probe mode:
 pcitool [ <PCI nexus node> ] [ -a ] [ -p ] [ -v ] [ -q ]

 pcitool <PCI nexus node> [ -p [ bus=<bus>,dev=<dev>,func=<func> ] [ -v ] [ -q ]
 pcitool <PCI nexus node> [ -p [ bdf=<bus>.<dev>.<func> ] [ -v ] [-q ]

Register peek/poke mode:
 pcitool <PCI nexus node>
  [   -n bank=<register bank>
         where register bank is 0 for mapped jbus space and 1 for pcie space
         (only on applicable platforms)

      -n base=<base address>
         where base address is a physical base address of a register bank
         (only on applicable platforms (e.g. sun4v) where bank info is unavailable)

      -d bus=<bus>,dev=<dev>,func=<func>,bank=<register bank>
      -d bdf=<bus>.<dev>.<func>,bank=<register bank>

      -d bus=<bus>,dev=<dev>,func=<func> | bdf=<bus>.<dev>.<func> ,
          [ config | bar0 | bar1 | bar2 | bar3 | bar4 | bar5 | rom ]
          (spaces added for clarity but are not allowed in the command)

  -n and -d options may also include:

  [ -w <value to write> ] [ -r ]
  [ -o <offset> ]   
  [ -s 1 | 2 | 4 | 8 ]
  [ -e b | l ]
  [ -l ]
  [ -b <number bytes to dump> [ -c ] [ -x ] ]
  [ -v ]
  [ -q ]

  -n may also include:

  [ -y ]

Interrupt mode:
 pcitool pci@<unit-address> -i <cpu#,ino#> | all
       [ -r [ -c ] |  -w <cpu#> [ -g ] ] [ -v ] [ -q ]
 pcitool pci@<unit-address> -i <ino#> | all
       [ -r [ -c ] |  -w <cpu#> [ -g ] ] [ -v ] [ -q ]
 pcitool pci@<unit-address> -m <msi#> | all
       [ -r [ -c ] |  -w <cpu#> [ -g ] ] [ -v ] [ -q ]


pci@<unit-address> is a node from /devices, with "/devices" stripped off.
For example: /pci@0,0

-v gives verbose output for all modes.

-q suppresses error output (except for commandline parsing errors) for all modes
   (Note that errno status is returned to the shell upon termination.)

Online help mode:   
 pcitool -h
   Prints this message.

Probe mode

-p [ bus=<bus>,dev=<dev>,func=<func> | bdf=<bus>.<dev>.<func> ]
     Specify bus, device and/or function of devices to search for and dump.

-a Probe all buses.  By default, pcitool checks the PCI nexus node's
bus-range property to restrict which buses are probed.  This option
cannot be combined with an explicit bus specification.

If a PCI nexus node is specified, pcitool looks only for devices
under that node.  If no PCI nexus node is specified, pcitool looks
for devices under all PCI nexus nodes.  PCI nexus nodes, which can
be used for other pcitool commands, are printed at the top of each tree.

Non-verbose probe mode prints config register data as follows:
  aa bb c dddd eeee ffff gggg hh iiiiii jj kk ll mm
    a = pci bus number
    b = pci device number
    c = pci function number
    d = vendor ID   
    e = device ID   
    f = command register
    g = status register
    h = revision ID 
    i = class code  
    j = cache line size
    k = latency timer
    l = header type 
    m = built in self test register (bist)

Register peek/poke mode
-n requests nexus node info.
   Specify desired nexus register using -o <register offset>

-d requests device (leaf) node info.
   Specify bus, dev, function bits (from probe mode) as hex numbers.
   Bank is specified in one of the following ways:
     By value: 0 == config space, 1 == BAR0, 2 == BAR1, ..., 6 == BAR5, 7 == ROM
     By BAR (bus addr reg): config, bar0, bar1, bar2, bar3, bar4, bar5, rom

Above peek/poke mode selections take the following options:

-r for reading (default)
-w <value> for writing
-w <value> -r for writing a value followed by a readback

-o <offset> to specify an offset within the requested address space

-s <size specifier>: 1, 2, 4 or 8 bytes, default 4
   (8-byte transfers on supported platforms only)

-e <endian specifier>: b or l (ell), default is l for little endian>

-l to do repetitious accesses to/from the same location(s)

-b <number of bytes to dump> [ -c ] to get a formatted multiple register dump
   starting at the offset given.  Hex bytes are always dumped.
   -c dumps characters as well.  Non-printable characters are dumped as "@".
   -x keeps going on errors, and prints err characters as X

Above nexus peek/poke mode selections take the following additional option:

-y to confirm a base_addr without being prompted interactively

NOTE: Some platforms (i.e. SPARC) return peek/poke errors as failed ioctls;
    Other platforms (i.e. X86) return peek/poke errors as FF values.

All numeric values are in HEX

Interrupt mode

-i <[cpu#],ino#> changes or retrieves current interrupts information of given
   nexus and given INO. The special value of 'all' can be used to select all

-m <[cpu#],msi#> changes or retrieves current interrupts information of given
   nexus and given MSI/X. The special value of 'all' can be used to select
   all MSI/Xs.

   Note: [cpu#] is available on x86 platform, is to identify exclusive vector
   with ino# at the same time. [cpu#] is not supported on SPARC platform.

   Note: On x86 platforms, both INOs and MSI/Xs are mapped to the same
   interrupt vectors. Use -i option to retrieve and reroute any interrupt
   vectors (both INO and MSI/Xs).  So, -m option is not required on x86
   platforms. Hence it is not supported.

   A specific INO or MSI/X must be selected if -w specified.

-w <cpu#> [ -g ] to change an INO or MSI/X <->CPU binding.

   Note: On certain platforms (e.g. X86), multiple MSI interrupts of a single
   function need to be moved together.  Use -g to do this.  -g works only on
   supported platforms and only for groups of MSI interrupts.  When -g is
   used, INO must be the lowest-numbered vector of the group.  (Use the mdb
   ::interrupts dcmd to discover groups of MSI vectors.)  The size of the
   group is determined internally.  ("Groups" of size 1 are accepted.)

-r [ -c ] for displaying ino or msi <->CPU bindings of all selected INO/MSIs
   on a given nexus.  -c optionally dumps controller information.

   All relevant enabled INO/MSI/Xs supporting non-nexus device interrupts
   will be printed.  For each printed INO/MSI/X, all supported devices and
   their CPU binding will be displayed.  On some platforms, INOs dedicated
   to the root nexus will be shown and marked with "(Internal)".

When neither -r nor -w are specified, -r is the default.
Actions #3

Updated by Electric Monk 9 days ago

  • Status changed from New to Closed
  • % Done changed from 0 to 100

git commit b02947bf393d39f68e6c7fa8ccb98688f7f9c407

commit  b02947bf393d39f68e6c7fa8ccb98688f7f9c407
Author: Hans Rosenfeld <>
Date:   2023-03-20T18:43:06.000Z

    15313 document pcitool register peek/poke mode
    Reviewed by: Toomas Soome <>
    Reviewed by: Igor Kozhukhov <>
    Approved by: Dan McDonald <>


Also available in: Atom PDF