12347 need hotplug(1m) manpage

Reviewed by: Gergő Doma <domag02@gmail.com>
Approved by: Dan McDonald <danmcd@joyent.com>

3 files changed, 332 insertions, 0 deletions

diff --git a/usr/src/man/man1m/Makefile b/usr/src/man/man1m/Makefile
index 478ec1251d..53be64fca8 100644
--- a/usr/src/man/man1m/Makefile
+++ b/usr/src/man/man1m/Makefile
@@ -169,6 +169,7 @@ _MANFILES=	6to4relay.1m		\
 		halt.1m			\
 		hextoalabel.1m		\
 		hostconfig.1m		\
+		hotplug.1m		\
 		id.1m			\
 		idmap.1m		\
 		idmapd.1m		\
diff --git a/usr/src/man/man1m/hotplug.1m b/usr/src/man/man1m/hotplug.1m
new file mode 100644
index 0000000000..0c5c8266fc
--- /dev/null
+++ b/usr/src/man/man1m/hotplug.1m
@@ -0,0 +1,330 @@
+.\"
+.\" 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, Sun Microsystems, Inc. All Rights Reserved
+.\" Copyright 2020 Joyent, Inc.
+.\"
+.Dd March 2, 2020
+.Dt HOTPLUG 1M
+.Os
+.Sh NAME
+.Nm hotplug
+.Nd configure hotplug connectors and ports
+.Sh SYNOPSIS
+.Nm
+.Fl \&?
+.Nm
+.Cm list
+.Op Fl lv
+.Op Ar path
+.Op Ar connection
+.Nm
+.Cm online
+.Ar path
+.Ar port
+.Nm
+.Cm offline
+.Op Fl fq
+.Ar path
+.Ar port
+.Nm
+.Cm enable
+.Ar path
+.Ar connector
+.Nm
+.Cm disable
+.Op Fl fq
+.Ar path
+.Ar connector
+.Nm
+.Cm poweron
+.Ar path
+.Ar connector
+.Nm
+.Cm poweroff
+.Op Fl fq
+.Ar path
+.Ar connector
+.Nm
+.Cm set
+.Fl o Ar options
+.Ar path
+.Ar connector
+.Nm
+.Cm get
+.Fl o Ar options
+.Ar path
+.Ar connector
+.Sh DESCRIPTION
+The
+.Nm
+command is used to manage hotplug connections.
+A connection can be a connector or port.
+A hotplug connector is a representation of a physical point in the system where
+components can be inserted or removed.
+A hotplug port is a representation of a logical point in the system device tree
+where the connection of a device to the system is managed.
+.Pp
+The
+.Nm
+command only supports hotplug operations on hotplug connectors for PCI Express
+buses and PCI buses that implement the Standard PCI Hotplug feature.
+Hotplug ports on PCI Express and PCI buses in systems with PCI Express fabrics
+are also supported.
+Additional buses may be supported in the future.
+.Pp
+The
+.Nm
+command operates on the following kinds of objects:
+.Bl -tag -width "connection"
+.It Cm path
+Hotplug connectors and ports are integrated into the system device tree.
+The names of connectors and ports are unique relative only to their bus
+controller.
+A device path is required to uniquely reference a connector or port.
+.It Cm connector
+If a hardware component supports being physically inserted or removed, then a
+hotplug connector represents the location where this action may occur.
+When a connector exists, it has a hierarchy of ports and device nodes that
+depend upon it.
+.It Cm port
+All device nodes can be virtually hotplugged, even if their hardware does not
+support physical hotplugging.
+A hotplug port exists between a device node and its parent node in the system
+device tree.
+It represents the location where the device node and its dependents can be
+managed.
+.It Cm connection
+A hotplug connection is a generic term to refer to either a hotplug connector or
+a hotplug port.
+.El
+.Pp
+Hotplug connectors and ports are managed according to a state model.
+The
+.Nm
+command can list information about the hotplug connections in a system, or it
+can initiate change of state operations on specific hotplug connections.
+.Pp
+Hotplug connectors can be in the following states:
+.Bl -tag -width "present"
+.It Cm empty
+A component is not physically inserted in the connector.
+.It Cm present
+A component is physically inserted in the connector, but the component is
+powered off.
+The component is not in use.
+.It Cm powered
+A component is physically inserted in the connector, and the component is
+powered on.
+The component is disabled and is not in use.
+.It Cm enabled
+A component is physically inserted in the connector.
+The component is powered on and has been probed and tested.
+The component is enabled and devices that represent its functions can be used.
+.El
+.Pp
+Hotplug ports can be in the following states:
+.Bl -tag -width "port-present"
+.It Cm port-empty
+No device exists for the hotplug port.
+.It Cm port-present
+A device exists for the hotplug port, but the device has not been probed and it
+has no attached device driver.
+The device is not in use.
+.It Cm offline
+A device exists for the hotplug port, and the device has been probed.
+A device driver is not attached, and the device is not in use.
+.It Cm online
+A device exists for the hotplug port, and its device driver is fully attached.
+The device is in use.
+.It Cm maintenance
+A device exists for the hotplug port, and its device driver is fully attached.
+The device is in use, but not fully operational.
+A maintenance or fault management operation is affecting the device.
+.El
+.Pp
+The
+.Nm
+command can also access bus private properties for each hotplug connector.
+The current values of bus private properties can be displayed.
+New values for each bus private property can be set directly.
+.Sh EXIT STATUS
+.Bl -diag
+.It 0
+Successful completion.
+.It 1
+Invalid command line options were specified.
+.It 2
+The specified path or connection does not exist.
+.It 3
+A fatal error occurred.
+One or more error messages are displayed on standard error.
+.It 4
+The hotplug service is not available.
+.El
+.Sh EXAMPLES
+.Bl -tag -width 0n
+.It Sy Example 1 No Showing All Hotplug Connections
+The following command shows all hotplug connections:
+.Bd -literal
+# hotplug list -v
+pci@0,0
+        <pci.2,1> (ONLINE)
+         pci108e,534a@2,1
+                 [pci30] (EMPTY)
+        <pci.e,0> (ONLINE)
+         pci10de,5d@e
+                 <pci.b,0> (ONLINE)
+                 display@b
+                 [NEM0] (ENABLED)
+                 <pci.a,0> (ONLINE)
+                 pci108e,534a@a,0
+                         { Network interface nge0 }
+                         { nge0: hosts IP addresses: 10.0.0.1 }
+                 <pci.a,1> (MAINTENANCE)
+                 pci108e,534a@a,1
+                 [NEM1] (EMPTY)
+         <pci.c,0> (OFFLINE)
+                pci108e,534a@4
+.Ed
+.Pp
+To show the full paths of hotplug connections and devices, enter the following
+command:
+.Bd -literal
+# hotplug list -l
+/pci@0,0 <pci.2,1> (ONLINE)
+/pci@0,0/pci108e,534a@2,1 [pci30] (EMPTY)
+/pci@0,0 pci.e,0> (ONLINE)
+/pci@0,0/pci10de,5d@e <pci.b,0> (ONLINE)
+/pci@0,0/pci10de,5d@e/display@b
+/pci@0,0/pci10de,5d@e [NEM0] (ENABLED)
+/pci@0,0/pci10de,5d@e <pci.a,0> (ONLINE)
+/pci@0,0/pci10de,5d@e/pci108e,534a@a,0
+/pci@0,0/pci10de,5d@e <pci.a,1> (MAINTENANCE)
+/pci@0,0/pci10de,5d@e/pci108e,534a@a,0
+/pci@0,0/pci10de,5d@e [NEM1] (EMPTY)
+/pci@0,0 pci.c,0> (OFFLINE)
+/pci@0,0/pci108e,534a@4
+.Ed
+.It Sy Example 2 No Reporting Failure During State Change Operation
+If a change of state operation fails, an explanation is displayed to describe
+the failure.
+An attempt to offline a hotplug port with dependent devices that are currently
+in use by the system might fail as follows:
+.Bd -literal
+# hotplug offline /pci@0,0/pci10de,5d@e pci.a,0
+ERROR: devices or resources are busy.
+pci108e,534a@a,0:
+    { Network interface nge0 }
+    { nge0: hosts IP addresses: 10.0.0.1 }
+    { Plumbed IP Address }
+.Ed
+.It Sy Example 3 No Displaying Bus-Specific Properties and Values
+The following command displays all supported bus-specific properties and their
+possible values:
+.Bd -literal
+# hotplug get -o help /pci@0,0 pci.2,1
+power_led=<on|off|blink>
+fault_led=<on|off|blink>
+active_led=<on|off|blink>
+attn_led=<on|off|blink>
+card_type=<type description>
+board_type=<type description>
+.Ed
+.It Sy Example 4 Displaying Bus-Specific Options
+The following command displays the card type and the current state of the Power
+LED of a PCI hotplug connector:
+.Bd -literal
+# hotplug get -o card_type,power_led /pci@0,0 pci.2,1
+card_type=fibre
+power_led=on
+.Ed
+.It Sy Example 5 No Setting a Bus-Specific Property
+The following command turns on the attention LED of a PCI hotplug connector:
+.Bd -literal
+# hotplug set -o attn_led=on /pci@0,0 pci.2,1
+.Ed
+.El
+.Sh DIAGNOSTICS
+The following error message is displayed on systems that do not have any
+supported I/O buses:
+.Bd -literal
+ERROR: there are no connections to display.
+(See hotplug(1m) for more information.)
+.Ed
+.Pp
+If this error message is seen, note that the system might still have other I/O
+devices that support hotplugging, through the
+.Xr cfgadm 1M
+command instead of
+.Nm .
+.Sh INTERFACE STABILITY
+.Sy Committed
+.Sh SEE ALSO
+.Xr cfgadm 1M ,
+.Xr hotplugd 1M ,
+.Xr getsubopt 3C ,
+.Xr rcmscript 4 ,
+.Xr attributes 5
+.Sh NOTES
+The
+.Nm
+service
+.Po FMRI
+.Pa svc:/system/hotplug
+.Pc
+must be enabled as a prerequisite for using the
+.Nm
+command.
+See
+.Xr hotplugd 1M .
+.Pp
+The authorization
+.Pa solaris.hotplug.modify
+must be granted in order to perform change-of-state operations.
+Alternatively, the rights profile
+.Qq Hotplug Management
+can be granted, which includes that authorization.
+.Pp
+Verbose usage information is gathered from the RCM framework.
+Its format and content is subject to change.
+.Pp
+The following bus specific properties are supported in PCI bus controllers:
+.Bl -tag -width Ds
+.It Cm power_led No \&| Cm fault_led No \&| Cm attn_led No \&| Cm active_led
+States of a specific LED of a slot.
+The value could be
+.Cm on , off ,
+or
+.Cm blink .
+.Pp
+They can all be used with
+.Cm get
+subcommand, but only property
+.Cm attn_led
+can be used with
+.Cm set
+subcommand.
+.It Cm card_type No \&| Cm board_type
+Type of a card or board of a slot.
+.Pp
+They can all be used with
+.Cm get
+subcommand, but neither can be used with
+.Cm set
+subcommand.
+.El
diff --git a/usr/src/pkg/manifests/SUNWcs.man1m.inc b/usr/src/pkg/manifests/SUNWcs.man1m.inc
index b4168f298b..f4331d110f 100644
--- a/usr/src/pkg/manifests/SUNWcs.man1m.inc
+++ b/usr/src/pkg/manifests/SUNWcs.man1m.inc
@@ -110,6 +110,7 @@ file path=usr/share/man/man1m/groupmod.1m
 file path=usr/share/man/man1m/growfs.1m
 file path=usr/share/man/man1m/halt.1m
 file path=usr/share/man/man1m/hostconfig.1m
+file path=usr/share/man/man1m/hotplug.1m
 file path=usr/share/man/man1m/id.1m
 file path=usr/share/man/man1m/idmap.1m
 file path=usr/share/man/man1m/idmapd.1m