2 .\" The contents of this file are subject to the terms of the
3 .\" Common Development and Distribution License (the "License").
4 .\" You may not use this file except in compliance with the License.
6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
7 .\" or http://www.opensolaris.org/os/licensing.
8 .\" See the License for the specific language governing permissions
9 .\" and limitations under the License.
11 .\" When distributing Covered Code, include this CDDL HEADER in each
12 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
13 .\" If applicable, add the following below this CDDL HEADER, with the
14 .\" fields enclosed by brackets "[]" replaced with your own identifying
15 .\" information: Portions Copyright [yyyy] [name of copyright owner]
18 .\" Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
19 .\" Copyright 2018 Nexenta Systems, Inc.
26 .Nd interrupt routing tool
30 .Cm pci@ Ns Ar unit-address Ns | Ns Cm niu@ Ns Ar unit-address
31 .Fl i Ar cpu# Ns \&, Ns Ar ino# Ns | Ns Cm all
33 .Op Fl r Oo Fl c Oc Ns | Ns Fl w Ar cpu# Oo Fl g Oc
36 .Cm pci@ Ns Ar unit-address Ns | Ns Cm niu@ Ns Ar unit-address
37 .Fl i Ar ino# Ns | Ns Cm all
39 .Op Fl r Oo Fl c Oc Ns | Ns Fl w Ar cpu# Oo Fl g Oc
41 .Cm pci@ Ns Ar unit-address
42 .Fl m Ar msi# Ns | Ns Cm all
44 .Op Fl r Oo Fl c Oc Ns | Ns Fl w Ar cpu# Oo Fl g Oc
47 is a low-level tool which provides a facility for getting and setting interrupt
50 On x86 platforms, both INOs and MSI/Xs are mapped to the same interrupt vectors.
53 option to retrieve and reroute any interrupt vectors (both INO and MSI/Xs).
55 On SPARC platforms, the INO is mapped to an interrupt mondo, where as one or
56 more MSI/Xs are mapped to an INO.
57 So, INO and MSI/Xs are individually retargetable.
60 option to retrieve or reroute a given INO, where as use
64 The following options are supported by
66 for interrupt routing:
70 Dump interrupt controller information.
73 On some platforms (such as x86) multiple MSI interrupts of a single function
74 need to be rerouted together.
79 works only on supported platforms and only for groups of MSI interrupts.
80 (A "group" of 1 is accepted).
83 is used, the vector provided must be the lowest-numbered vector of the group.
84 The size of the group is determined internally.
86 Display device and CPU routing information for INOs on a given nexus,
87 or reroute the given INO or INO group to a specific CPU.
90 Display device and CPU routing information for MSI/Xs on a given nexus,
91 or reroute the given MSI/X or MSI/X group to a specific CPU.
93 No errors reported as messages.
94 Unix error status still returned by program, however.
96 Display device and CPU routing information for INOs on a given nexus.
97 The device path and instance number of each device for each displayed INO will
99 On some platforms, interrupts dedicated to the root complex are indicated with
101 appended to their pathname.
110 Route the given INO or MSI/X to the given CPU.
111 Display the new and original routing information.
112 The INO or MSI/X must be specified.
115 The following error statuses are returned to the shell:
120 Out-of-range, misaligned or otherwise invalid argument has been passed in.
122 Timeout waiting for pending interrupt to settle before changing interrupts to
125 An IO error occurred.
129 .It Sy Example 1 No Showing INOs or MSI/Xs
130 The command for showing all INOs on /pci@0,0 is:
132 # pcitool /pci@0,0 -i all
135 The command for showing ino <0x0,0x21> on the same root nexus, along with sample
140 # pcitool /pci@0,0 -i 0,21
141 0x0,0x21: mpt 0 /pci@7b,0/pci1022,7458@11/pci1000,3060@2
146 # pcitool /pci@0,0 -i 21
147 0x0,0x21: mpt 0 /pci@7b,0/pci1022,7458@11/pci1000,3060@2
150 The command for showing MSI 0x1 on the same root nexus, along with sample
153 # pcitool /pci@0,0 -m 0x1
154 0x0,0x1: pcieb 0 /pci@7b,0/pci10de,5d@e
156 .It Sy Example 2 No Rerouting INOs or MSI/Xs
157 Successful rerouting ino 21 above from cpu 0 to cpu 1 gives the following
162 # pcitool /pci@0,0 -i 0,21 -w 1
168 # pcitool /pci@0,0 -i 21 -w 1
172 Successful rerouting msi 1 above from cpu 1 to cpu 0 gives the following
175 # pcitool /pci@0,0 -m 1 -w 0
179 Successful rerouting a group of INOs starting at 24 from cpu 0 to cpu 1 gives
180 the following output:
184 # pcitool /pci@0,0 -i 3,24 -w 1 -g
190 # pcitool /pci@0,0 -i 24 -w 1 -g
195 .Sy PCI-based systems
196 .Sh INTERFACE STABILITY
206 .Lk https://pcisig.com
209 All values are entered in hex.
211 Not all commands are applicable to all platforms.
213 The user must have all privileges in order to access interrupt information.
214 A regular user can access interrupt information when
216 to root or granted the
217 .Qq Maintenance and Repair
218 rights profile in the