share/man/man8/pcitool.8

   1 .\"
   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.
   5 .\"
   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.
  10 .\"
  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]
  16 .\"
  17 .\"
  18 .\" Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
  19 .\" Copyright 2018 Nexenta Systems, Inc.
  20 .\"
  21 .Dd February 12, 2018
  22 .Dt PCITOOL 88888888
  23 .Os
  24 .Sh NAME
  25 .Nm pcitool
  26 .Nd interrupt routing tool
  27 .Sh SYNOPSIS
  28 .Ss Sy x86
  29 .Nm
  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
  32 .Op Fl qv
  33 .Op Fl r Oo Fl c Oc Ns | Ns Fl w Ar cpu# Oo Fl g Oc
  34 .Ss SPARC
  35 .Nm
  36 .Cm pci@ Ns Ar unit-address Ns | Ns Cm niu@ Ns Ar unit-address
  37 .Fl i Ar ino# Ns | Ns Cm all
  38 .Op Fl qv
  39 .Op Fl r Oo Fl c Oc Ns | Ns Fl w Ar cpu# Oo Fl g Oc
  40 .Nm
  41 .Cm pci@ Ns Ar unit-address
  42 .Fl m Ar msi# Ns | Ns Cm all
  43 .Op Fl qv
  44 .Op Fl r Oo Fl c Oc Ns | Ns Fl w Ar cpu# Oo Fl g Oc
  45 .Sh DESCRIPTION
  46 .Nm
  47 is a low-level tool which provides a facility for getting and setting interrupt
  48 routing information.
  49 .Ss Interrupt Routing
  50 On x86 platforms, both INOs and MSI/Xs are mapped to the same interrupt vectors.
  51 Use
  52 .Nm Fl i
  53 option to retrieve and reroute any interrupt vectors (both INO and MSI/Xs).
  54 .Pp
  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.
  58 Use
  59 .Nm Fl i
  60 option to retrieve or reroute a given INO, where as use
  61 .Nm Fl m
  62 option for MSI/Xs.
  63 .Pp
  64 The following options are supported by
  65 .Nm
  66 for interrupt routing:
  67 .Bl -tag -width Ds
  68 .It Fl c
  69 .Pq Used with Fl r .
  70 Dump interrupt controller information.
  71 .It Fl g
  72 .Pq Used with Fl w .
  73 On some platforms (such as x86) multiple MSI interrupts of a single function
  74 need to be rerouted together.
  75 Use
  76 .Fl g
  77 to do this.
  78 .Fl g
  79 works only on supported platforms and only for groups of MSI interrupts.
  80 (A "group" of 1 is accepted).
  81 When
  82 .Fl g
  83 is used, the vector provided must be the lowest-numbered vector of the group.
  84 The size of the group is determined internally.
  85 .It Fl i
  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.
  88 .It Fl m
  89 .Pq SPARC only
  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.
  92 .It Fl q
  93 No errors reported as messages.
  94 Unix error status still returned by program, however.
  95 .It Fl r
  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
  98 be shown.
  99 On some platforms, interrupts dedicated to the root complex are indicated with
 100 .Ql (Internal)
 101 appended to their pathname.
 102 Default if neither
 103 .Fl r
 104 nor
 105 .Fl w
 106 are specified.
 107 .It Fl v
 108 Verbose output.
 109 .It Fl w
 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.
 113 .El
 114 .Sh EXIT STATUS
 115 The following error statuses are returned to the shell:
 116 .Bl -tag -width Er
 117 .It Er 0
 118 No error
 119 .It Er EINVAL
 120 Out-of-range, misaligned or otherwise invalid argument has been passed in.
 121 .It Er ETIME
 122 Timeout waiting for pending interrupt to settle before changing interrupts to
 123 a new CPU.
 124 .It Er EIO
 125 An IO error occurred.
 126 .El
 127 .Sh EXAMPLES
 128 .Bl -tag -width Ds
 129 .It Sy Example 1 No Showing INOs or MSI/Xs
 130 The command for showing all INOs on /pci@0,0 is:
 131 .Bd -literal
 132 # pcitool /pci@0,0 -i all
 133 .Ed
 134 .Pp
 135 The command for showing ino <0x0,0x21> on the same root nexus, along with sample
 136 output, is:
 137 .Pp
 138 On x86 platform:
 139 .Bd -literal
 140 # pcitool /pci@0,0 -i 0,21
 141 0x0,0x21: mpt       0    /pci@7b,0/pci1022,7458@11/pci1000,3060@2
 142 .Ed
 143 .Pp
 144 On SPARC platform:
 145 .Bd -literal
 146 # pcitool /pci@0,0 -i 21
 147 0x0,0x21: mpt       0    /pci@7b,0/pci1022,7458@11/pci1000,3060@2
 148 .Ed
 149 .Pp
 150 The command for showing MSI 0x1 on the same root nexus, along with sample
 151 output, is:
 152 .Bd -literal
 153 # pcitool /pci@0,0 -m 0x1
 154 0x0,0x1: pcieb     0    /pci@7b,0/pci10de,5d@e
 155 .Ed
 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
 158 output:
 159 .Pp
 160 On x86 platform:
 161 .Bd -literal
 162 # pcitool /pci@0,0 -i 0,21 -w 1
 163 0x0,0x21 -> 0x1,0x20
 164 .Ed
 165 .Pp
 166 On SPARC platform:
 167 .Bd -literal
 168 # pcitool /pci@0,0 -i 21 -w 1
 169 0x0,0x21 -> 0x1,0x21
 170 .Ed
 171 .Pp
 172 Successful rerouting msi 1 above from cpu 1 to cpu 0 gives the following
 173 output:
 174 .Bd -literal
 175 # pcitool /pci@0,0 -m 1 -w 0
 176 0x1,0x1 -> 0x0,0x1
 177 .Ed
 178 .Pp
 179 Successful rerouting a group of INOs starting at 24 from cpu 0 to cpu 1 gives
 180 the following output:
 181 .Pp
 182 On x86 platform:
 183 .Bd -literal
 184 # pcitool /pci@0,0 -i 3,24 -w 1 -g
 185 0x3,0x24 => 0x1,0x22
 186 .Ed
 187 .Pp
 188 On SPARC platform:
 189 .Bd -literal
 190 # pcitool /pci@0,0 -i 24 -w 1 -g
 191 0x3,0x24 => 0x1,0x22
 192 .Ed
 193 .El
 194 .Sh ARCHITECTURE
 195 .Sy PCI-based systems
 196 .Sh INTERFACE STABILITY
 197 .Sy Volatile
 198 .Sh SEE ALSO
 199 .Xr su 8 ,
 200 .Xr pci 4 ,
 201 .Xr user_attr 4 ,
 202 .Xr rbac 5
 203 .Pp
 204 PCI specification
 205 .Po available from
 206 .Lk https://pcisig.com
 207 .Pc
 208 .Sh NOTES
 209 All values are entered in hex.
 210 .Pp
 211 Not all commands are applicable to all platforms.
 212 .Pp
 213 The user must have all privileges in order to access interrupt information.
 214 A regular user can access interrupt information when
 215 .Xr su 8
 216 to root or granted the
 217 .Qq Maintenance and Repair
 218 rights profile in the
 219 .Pa user_attr
 220 file.
 221 See
 222 .Xr user_attr 4
 223 and
 224 .Xr rbac 5 .