9101 bring back pcitool man page

Reviewed by: Toomas Soome <tsoome@me.com>
Approved by: Dan McDonald <danmcd@joyent.com>

3 files changed, 230 insertions, 1 deletions

diff --git a/usr/src/man/man1m/Makefile b/usr/src/man/man1m/Makefile
index 409095162d..f83b395683 100644
--- a/usr/src/man/man1m/Makefile
+++ b/usr/src/man/man1m/Makefile
@@ -15,7 +15,7 @@
 # Copyright 2015 Nexenta Systems, Inc.  All rights reserved.
 # Copyright (c) 2013, 2016 by Delphix. All rights reserved.
 # Copyright 2016 Toomas Soome <tsoome@me.com>
-# Copyright 2017 Nexenta Systems, Inc.
+# Copyright 2018 Nexenta Systems, Inc.
 # Copyright (c) 2017, Chris Fraire <cfraire@me.com>.
 #
 
@@ -341,6 +341,7 @@ _MANFILES=	6to4relay.1m		\
 		nwamd.1m		\
 		passmgmt.1m		\
 		pbind.1m		\
+		pcitool.1m		\
 		picld.1m		\
 		ping.1m			\
 		pkgadd.1m		\
diff --git a/usr/src/man/man1m/pcitool.1m b/usr/src/man/man1m/pcitool.1m
new file mode 100644
index 0000000000..e0c1891a0a
--- /dev/null
+++ b/usr/src/man/man1m/pcitool.1m
@@ -0,0 +1,224 @@
+.\"
+.\" 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]
+.\"
+.\"
+.\" Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
+.\" Copyright 2018 Nexenta Systems, Inc.
+.\"
+.Dd February 12, 2018
+.Dt PCITOOL 1M
+.Os
+.Sh NAME
+.Nm pcitool
+.Nd interrupt routing tool
+.Sh SYNOPSIS
+.Ss Sy x86
+.Nm
+.Cm pci@ Ns Ar unit-address Ns | Ns Cm niu@ Ns Ar unit-address
+.Fl i Ar cpu# Ns \&, Ns Ar ino# Ns | Ns Cm all
+.Op Fl qv
+.Op Fl r Oo Fl c Oc Ns | Ns Fl w Ar cpu# Oo Fl g Oc
+.Ss SPARC
+.Nm
+.Cm pci@ Ns Ar unit-address Ns | Ns Cm niu@ Ns Ar unit-address
+.Fl i Ar ino# Ns | Ns Cm all
+.Op Fl qv
+.Op Fl r Oo Fl c Oc Ns | Ns Fl w Ar cpu# Oo Fl g Oc
+.Nm
+.Cm pci@ Ns Ar unit-address
+.Fl m Ar msi# Ns | Ns Cm all
+.Op Fl qv
+.Op Fl r Oo Fl c Oc Ns | Ns Fl w Ar cpu# Oo Fl g Oc
+.Sh DESCRIPTION
+.Nm
+is a low-level tool which provides a facility for getting and setting interrupt
+routing information.
+.Ss Interrupt Routing
+On x86 platforms, both INOs and MSI/Xs are mapped to the same interrupt vectors.
+Use
+.Nm Fl i
+option to retrieve and reroute any interrupt vectors (both INO and MSI/Xs).
+.Pp
+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
+.Nm Fl i
+option to retrieve or reroute a given INO, where as use
+.Nm Fl m
+option for MSI/Xs.
+.Pp
+The following options are supported by
+.Nm
+for interrupt routing:
+.Bl -tag -width Ds
+.It Fl c
+.Pq Used with Fl r .
+Dump interrupt controller information.
+.It Fl g
+.Pq Used with Fl w .
+On some platforms (such as x86) multiple MSI interrupts of a single function
+need to be rerouted together.
+Use
+.Fl g
+to do this.
+.Fl g
+works only on supported platforms and only for groups of MSI interrupts.
+(A "group" of 1 is accepted).
+When
+.Fl g
+is used, the vector provided must be the lowest-numbered vector of the group.
+The size of the group is determined internally.
+.It Fl i
+Display device and CPU routing information for INOs on a given nexus,
+or reroute the given INO or INO group to a specific CPU.
+.It Fl m
+.Pq SPARC only
+Display device and CPU routing information for MSI/Xs on a given nexus,
+or reroute the given MSI/X or MSI/X group to a specific CPU.
+.It Fl q
+No errors reported as messages.
+Unix error status still returned by program, however.
+.It Fl r
+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
+.Ql (Internal)
+appended to their pathname.
+Default if neither
+.Fl r
+nor
+.Fl w
+are specified.
+.It Fl v
+Verbose output.
+.It Fl w
+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.
+.El
+.Sh EXIT STATUS
+The following error statuses are returned to the shell:
+.Bl -tag -width Er
+.It Er 0
+No error
+.It Er EINVAL
+Out-of-range, misaligned or otherwise invalid argument has been passed in.
+.It Er ETIME
+Timeout waiting for pending interrupt to settle before changing interrupts to
+a new CPU.
+.It Er EIO
+An IO error occurred.
+.El
+.Sh EXAMPLES
+.Bl -tag -width Ds
+.It Sy Example 1 No Showing INOs or MSI/Xs
+The command for showing all INOs on /pci@0,0 is:
+.Bd -literal
+# pcitool /pci@0,0 -i all
+.Ed
+.Pp
+The command for showing ino <0x0,0x21> on the same root nexus, along with sample
+output, is:
+.Pp
+On x86 platform:
+.Bd -literal
+# pcitool /pci@0,0 -i 0,21
+0x0,0x21: mpt       0    /pci@7b,0/pci1022,7458@11/pci1000,3060@2
+.Ed
+.Pp
+On SPARC platform:
+.Bd -literal
+# pcitool /pci@0,0 -i 21
+0x0,0x21: mpt       0    /pci@7b,0/pci1022,7458@11/pci1000,3060@2
+.Ed
+.Pp
+The command for showing MSI 0x1 on the same root nexus, along with sample
+output, is:
+.Bd -literal
+# pcitool /pci@0,0 -m 0x1
+0x0,0x1: pcieb     0    /pci@7b,0/pci10de,5d@e
+.Ed
+.It Sy Example 2 No Rerouting INOs or MSI/Xs
+Successful rerouting ino 21 above from cpu 0 to cpu 1 gives the following
+output:
+.Pp
+On x86 platform:
+.Bd -literal
+# pcitool /pci@0,0 -i 0,21 -w 1
+0x0,0x21 -> 0x1,0x20
+.Ed
+.Pp
+On SPARC platform:
+.Bd -literal
+# pcitool /pci@0,0 -i 21 -w 1
+0x0,0x21 -> 0x1,0x21
+.Ed
+.Pp
+Successful rerouting msi 1 above from cpu 1 to cpu 0 gives the following
+output:
+.Bd -literal
+# pcitool /pci@0,0 -m 1 -w 0
+0x1,0x1 -> 0x0,0x1
+.Ed
+.Pp
+Successful rerouting a group of INOs starting at 24 from cpu 0 to cpu 1 gives
+the following output:
+.Pp
+On x86 platform:
+.Bd -literal
+# pcitool /pci@0,0 -i 3,24 -w 1 -g
+0x3,0x24 => 0x1,0x22
+.Ed
+.Pp
+On SPARC platform:
+.Bd -literal
+# pcitool /pci@0,0 -i 24 -w 1 -g
+0x3,0x24 => 0x1,0x22
+.Ed
+.El
+.Sh ARCHITECTURE
+.Sy PCI-based systems
+.Sh INTERFACE STABILITY
+.Sy Volatile
+.Sh SEE ALSO
+.Xr su 1M ,
+.Xr pci 4 ,
+.Xr user_attr 4 ,
+.Xr rbac 5
+.Pp
+PCI specification
+.Po available from
+.Lk https://pcisig.com
+.Pc
+.Sh NOTES
+All values are entered in hex.
+.Pp
+Not all commands are applicable to all platforms.
+.Pp
+The user must have all privileges in order to access interrupt information.
+A regular user can access interrupt information when
+.Xr su 1M
+to root or granted the
+.Qq Maintenance and Repair
+rights profile in the
+.Pa user_attr
+file.
+See
+.Xr user_attr 4
+and
+.Xr rbac 5 .
diff --git a/usr/src/pkg/manifests/system-management-pcitool.mf b/usr/src/pkg/manifests/system-management-pcitool.mf
index cfafa2b001..cd892ee277 100644
--- a/usr/src/pkg/manifests/system-management-pcitool.mf
+++ b/usr/src/pkg/manifests/system-management-pcitool.mf
@@ -39,7 +39,11 @@ set name=info.classification \
 set name=variant.arch value=$(ARCH)
 dir path=usr group=sys
 dir path=usr/sbin
+dir path=usr/share
+dir path=usr/share/man
+dir path=usr/share/man/man1m
 file path=usr/sbin/pcitool mode=0555
+file path=usr/share/man/man1m/pcitool.1m
 legacy pkg=SUNWio-tools \
     desc="Administrative tools to modify the pci/pcie fabric" \
     name="Administrative tools to modify the pci/pcie fabric"