PCITOOL(1M) Maintenance Commands PCITOOL(1M)

NAME


pcitool - interrupt routing tool

SYNOPSIS


x86
pcitool pci@unit-address|niu@unit-address -i cpu#,ino#|all [-qv]
[-r [-c]|-w cpu# [-g]]

SPARC


pcitool pci@unit-address|niu@unit-address -i ino#|all [-qv]
[-r [-c]|-w cpu# [-g]]
pcitool pci@unit-address -m msi#|all [-qv] [-r [-c]|-w cpu# [-g]]

DESCRIPTION


pcitool is a low-level tool which provides a facility for getting and
setting interrupt routing information.

Interrupt Routing


On x86 platforms, both INOs and MSI/Xs are mapped to the same interrupt
vectors. Use pcitool -i option to retrieve and reroute any interrupt
vectors (both INO and MSI/Xs).

On SPARC platforms, the INO is mapped to an interrupt mondo, where as one
or more MSI/Xs are mapped to an INO. So, INO and MSI/Xs are individually
retargetable. Use pcitool -i option to retrieve or reroute a given INO,
where as use pcitool -m option for MSI/Xs.

The following options are supported by pcitool for interrupt routing:

-c (Used with -r). Dump interrupt controller information.

-g (Used with -w). On some platforms (such as x86) multiple MSI
interrupts of a single function need to be rerouted together. Use
-g to do this. -g works only on supported platforms and only for
groups of MSI interrupts. (A "group" of 1 is accepted). When -g
is used, the vector provided must be the lowest-numbered vector of
the group. The size of the group is determined internally.

-i Display device and CPU routing information for INOs on a given
nexus, or reroute the given INO or INO group to a specific CPU.

-m (SPARC only) Display device and CPU routing information for MSI/Xs
on a given nexus, or reroute the given MSI/X or MSI/X group to a
specific CPU.

-q No errors reported as messages. Unix error status still returned
by program, however.

-r Display device and CPU routing information for INOs on a given
nexus. The device path and instance number of each device for each
displayed INO will be shown. On some platforms, interrupts
dedicated to the root complex are indicated with `(Internal)'
appended to their pathname. Default if neither -r nor -w are
specified.

-v Verbose output.

-w Route the given INO or MSI/X to the given CPU. Display the new and
original routing information. The INO or MSI/X must be specified.

EXIT STATUS


The following error statuses are returned to the shell:

0 No error

EINVAL Out-of-range, misaligned or otherwise invalid argument
has been passed in.

ETIME Timeout waiting for pending interrupt to settle before
changing interrupts to a new CPU.

EIO An IO error occurred.

EXAMPLES


Example 1 Showing INOs or MSI/Xs
The command for showing all INOs on /pci@0,0 is:

# pcitool /pci@0,0 -i all

The command for showing ino <0x0,0x21> on the same root nexus,
along with sample output, is:

On x86 platform:

# pcitool /pci@0,0 -i 0,21
0x0,0x21: mpt 0 /pci@7b,0/pci1022,7458@11/pci1000,3060@2

On SPARC platform:

# pcitool /pci@0,0 -i 21
0x0,0x21: mpt 0 /pci@7b,0/pci1022,7458@11/pci1000,3060@2

The command for showing MSI 0x1 on the same root nexus, along with
sample output, is:

# pcitool /pci@0,0 -m 0x1
0x0,0x1: pcieb 0 /pci@7b,0/pci10de,5d@e

Example 2 Rerouting INOs or MSI/Xs
Successful rerouting ino 21 above from cpu 0 to cpu 1 gives the
following output:

On x86 platform:

# pcitool /pci@0,0 -i 0,21 -w 1
0x0,0x21 -> 0x1,0x20

On SPARC platform:

# pcitool /pci@0,0 -i 21 -w 1
0x0,0x21 -> 0x1,0x21

Successful rerouting msi 1 above from cpu 1 to cpu 0 gives the
following output:

# pcitool /pci@0,0 -m 1 -w 0
0x1,0x1 -> 0x0,0x1

Successful rerouting a group of INOs starting at 24 from cpu 0 to
cpu 1 gives the following output:

On x86 platform:

# pcitool /pci@0,0 -i 3,24 -w 1 -g
0x3,0x24 => 0x1,0x22

On SPARC platform:

# pcitool /pci@0,0 -i 24 -w 1 -g
0x3,0x24 => 0x1,0x22

ARCHITECTURE


PCI-based systems

INTERFACE STABILITY


Volatile

SEE ALSO


su(1M), pci(4), user_attr(4), rbac(5)

PCI specification (available from https://pcisig.com)

NOTES


All values are entered in hex.

Not all commands are applicable to all platforms.

The user must have all privileges in order to access interrupt information.
A regular user can access interrupt information when su(1M) to root or
granted the "Maintenance and Repair" rights profile in the user_attr file.
See user_attr(4) and rbac(5).

illumos February 12, 2018 illumos