Tribblix: manual page: pcitool.8

PCITOOL(8) Maintenance Commands and Procedures PCITOOL(8)

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

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

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(8) to root or granted the "Maintenance and Repair" rights profile in
the user_attr file. See user_attr(5) and rbac(7).

illumos February 12, 2018 illumos