pcitool(1M) System Administration Commands pcitool(1M)NAMEpcitool - 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 | niu@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 indi‐
vidually 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 informa‐
tion. 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 vec‐
tor 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:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Architecture │PCI-based systems │
├─────────────────────────────┼─────────────────────────────┤
│Availability │SUNWio-tools │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Volatile │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOsu(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.
SunOS 5.10 28 Oct 2010 pcitool(1M)
