CDDL HEADER START

The contents of this file are subject to the terms of the
Common Development and Distribution License (the "License").
You may not use this file except in compliance with the License.

You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
or http://www.opensolaris.org/os/licensing.
See the License for the specific language governing permissions
and limitations under the License.

When distributing Covered Code, include this CDDL HEADER in each
file and include the License file at usr/src/OPENSOLARIS.LICENSE.
If applicable, add the following below this CDDL HEADER, with the
fields enclosed by brackets "[]" replaced with your own identifying
information: Portions Copyright [yyyy] [name of copyright owner]

CDDL HEADER END

Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.

pcitool - interrupt routing tool

/usr/sbin/pcitool pci@<unit-address>|\f I niu@<unit-address> -i <[cpu#],ino#> | all [ -r [ -c ] | -w <cpu#> [ -g ] ] [ -v ] [ -q ] /usr/sbin/pcitool pci@<unit-address> -m <[cpu#],msi#> | all [ -r [ -c ] | -w <cpu#> [ -g ] ] [ -v ] [ -q ] /usr/sbin/pcitool [ -h ]

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

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. Use the pcitool -m command to retrieve and reroute 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 "-i" option to retrieve or reroute a given INO, where as use "-m" option for MSI/Xs. 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. [cpu#] is available on x86 platform, is to identify exclusive vector with ino# at the same time. [cpu#] is not supported on SPARC platform. Required privileges 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). Commandline options -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 will be shown. On some platforms, interrupts dedicated to the root complex are indicated with "(Internal)" appended to their pathname. Dump interrupt controller information with -c. If neither -r nor -w are provided on the commandline, -r is assumed. 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 -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. 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 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. 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 -v Verbose output. -q No errors reported as messages. Unix error status still returned by program, however. 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.

/usr/sbin/pcitool

See attributes(5) for descriptions of the following attributes: _________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |______________________|__________________________________| | Architecture | PCI-based systems | |______________________|__________________________________| | Availability | SUNWio-tools | |______________________|__________________________________| | Interface Stability | Volatile | |______________________|__________________________________|

pci(4), su(1M), user_attr(4), rbac(5) All values are entered in hex. Not all commands are applicable to all platforms. REFERENCES PCI specification (available from www.pcisig.org)