Maintenance Commands pcitool(1M) NAME pcitool - interrupt routing tool SYNOPSIS /usr/sbin/pcitool pci@ -i <[cpu#],ino#> | all [ -r [ -c ] | -w [ -g ] ] [ -v ] [ -q ] /usr/sbin/pcitool pci@ -m <[cpu#],msi#> | all [ -r [ -c ] | -w [ -g ] ] [ -v ] [ -q ] /usr/sbin/pcitool [ -h ] DESCRIPTION PCItool is a low-level tool which 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. Use the pci- tool -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. On x86 platforms cpu# must be specified along with ino# when specifying an interrupt, as ino# itself is not unique in a x86 system with multiple cpus. And ino could change after an interrupt is rerouted to a different cpu. Required privileges The user must have all privileges in order to access inter- rupt 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 SunOS 5.10 Last change: 1 Maintenance Commands pcitool(1M) 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@1e,600000 is: # pcitool /pci@1e,600000 -i all The command for showing ino 0x19 on the same root nexus, along with sample output, is: # pcitool /pci@1e,600000 -i 19 0x0,0x19: mpt0 /pci@1e,600000/pci@0/pci@9/pci@0/scsi@1 0x0,0x19: bge0 /pci@1e,600000/pci@0/pci@2/pci@0/network@4 On x86 systems, the cpu which owns the ino must be specified as well: # pcitool /pci@1e,600000 -i 0,19 The command for showing MSI 0x1 on the same root nexus, along with sample output, is: # pcitool /pci@1e,600000 -m 1 0x0,0x1: mpt0 /pci@1e,600000/pci@0/pci@9/pci@0/scsi@1 -w [ -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 19 above from cpu 0 to cpu 1 gives the following output: # pcitool /pci@1e,600000 -i 19 -w 1 0x0,0x19 -> 0x1,0x19 On x86 systems the original cpu is also needed, and the ino could change after rerouting to a different cpu: # pcitool /pci@1e,600000 -i 0,19 -w 1 0x0,0x19 -> 0x1,0x21 Successful rerouting msi 1 above from cpu 1 to cpu 0 gives the following output: # pcitool /pci@1e,600000 -m 1 -w 0 SunOS 5.10 Last change: 2 Maintenance Commands pcitool(1M) 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. The command for showing ino 0x19 of cpu 0 on /pci@1e,600000, along with sample output, is: # pcitool /pci@1e,600000 -i 19 0x0,0x19: mpt0 /pci@1e,600000/pci@0/pci@9/pci@0/scsi@1 0x0,0x19: bge0 /pci@1e,600000/pci@0/pci@2/pci@0/network@4 Successful rerouting a group of INOs starting at 60 from cpu 0 to cpu 1 gives the following output: # pcitool /pci@0,0 -i 60 -w 1 -g 0x0,0x60 => 0x1,0x60 Note on x86 systems cpu number is needed as well, and the group of INOs could start from a different ino after rerout- ing to a different cpu: # pcitool /pci@0,0 -i 0,60 -w 1 -g 0x0,0x60 => 0x1,0x61 -v Verbose output. -q No errors reported as messages. Unix error status still returned by program, however. EXIT STATUS The following error statuses are returned to the shell: 0 No error EINVAL Out-of-range, misaligned or other- wise invalid argument has been passed in. ETIME Timeout waiting for pending inter- rupt to settle before changing interrupts to a new CPU. EIO An IO error occurred. SunOS 5.10 Last change: 3 Maintenance Commands pcitool(1M) FILES /usr/sbin/pcitool ATTRIBUTES See attributes(5) for descriptions of the following attri- butes: _________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |______________________|__________________________________| | Architecture | PCI-based systems | |______________________|__________________________________| | Availability | SUNWio-tools | |______________________|__________________________________| | Interface Stability | Volatile | |______________________|__________________________________| SEE ALSO pci(4), su(1M), user_attr(4), rbac(5) NOTES All values are entered in hex. Not all commands are applicable to all platforms. REFERENCES PCI specification (available from www.pcisig.org) SunOS 5.10 Last change: 4