pcitool

- interrupt routing tool

Synopsis

/usr/sbin/pcitool -h

x86:

/usr/sbin/pcitool pci@unit-address -i cpu#,ino# | all [-r [-c] |
     -w cpu# [-g] ] [-v] [-q]

SPARC:

/usr/sbin/pcitool pci@unit-address -i ino# | all [-r [-c] |
     -w cpu# [-g] ] [-v] [-q]

/usr/sbin/pcitool pci@unit-address -m msi# | all [-r [-c] |
     -w cpu# [-g] ] [-v] [-q]

Description

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

Interrupt Routing

The pcitool -i command displays device and CPU routing information for INOs on a given nexus, and allows rerouting of a given INO or INO group to a specific CPU.

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 the -i option to retrieve or reroute a given INO; use the -m option for MSI/Xs.

Specifying cpu# is available on the x86 platform. In combination with ino#, this identifies an exclusive vector. The cpu# argument is not supported on the SPARC platform.

Required Privileges

A user must have all privileges in order to access interrupt information. A regular user can access interrupt information following an su(1M) to root or if he is granted the “Maintenance and Repair” rights profile in the user_attr file. See user_attr(4) and rbac(5).

Options

The following options are supported:

-h

Display command usage.

-q

No errors are displayed as messages. However, pcitool still returns Unix error codes.

-r [-c]

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 is displayed. On some platforms, interrupts dedicated to the root complex are indicated by the string (Internal) appended to their pathnames.

With -c, dump interrupt controller information.

If neither -r nor -w are provided on the command line, -r is assumed. See Examples.

-v

Verbose output.

-w cpu# [-g]

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.

On some platforms (such as x86) multiple MSI interrupts of a single function need to be rerouted together. Use -g to do this. The -g option 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. See Examples.

Examples

Example 1 Displaying All INOs

The command for showing all INOs on /pci@0,0 is:

# pcitool /pci@0,0 -i all

Example 2 Displaying Output for Specific INO

The command for showing INO 0x0,0x21 on the root nexus /pci@0,0 differs slightly between x86 and SPARC platforms.

On an x86 platform:

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

On a SPARC platform:

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

Output shown above is an example and might vary from your output.

Example 3 Displaying Output for Specific MSI

The command for showing MSI 0x1 on the root nexus /pci@0,0, along with sample output, is shown below.

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

Example 4 Rerouting an INO from One CPU to Another

Successful rerouting INO 21 from CPU 0 to CPU 1 produces the output shown below.

On an x86 platform:

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

On a SPARC platform:

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

Example 5 Rerouting an MSI from One CPU to Another

Successful rerouting MSI 1 from CPU 1 to CPU 0 produces the output shown below.

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

Example 6 Rerouting a Group of INOs

Successful rerouting of a group of INOs starting at 24 from CPU 0 to CPU 1 produces the output shown below.

On an x86 platform:

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

On a SPARC platform:

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

Exit Status

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 I/O error occurred.

Attributes

See attributes(5) for descriptions of the following attributes:

See Also

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

PCI specification (available from www.pcisig.org)

Notes

All values are entered in hex.

Not all commands are applicable to all platforms.