hotplug(1M) System Administration Commands hotplug(1M)NAMEhotplug - configure hotplug connectors and ports
SYNOPSIShotplug list [-l] [-v] [path [connection]]
hotplug online path port
hotplug offline [-f] [-q] path port
hotplug enable path connector
hotplug disable [-f] [-q] path connector
hotplug poweron path connector
hotplug poweroff [-f] [-q] path connector
hotplug set -o options path connector
hotplug get -o options path connector
hotplug install path port
hotplug uninstall [-f] [-q] path port
hotplug -?
DESCRIPTION
The hotplug 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.
The hotplug command only supports hotplug operations on hotplug connec‐
tors for PCI Express buses and PCI buses that implement the Standard
PCI Hotplug feature. Hotplug ports on PCI Expresss and PCI buses in
systems with PCI Express fabrics are also supported. Additional buses
may be supported in the future.
The hotplug command operates on the following kinds of objects:
path
Hotplug connectors and ports are integrated into the Solaris device
tree. The names of connectors and ports are unique relative only to
their bus controller. A device path is required to uniquely refer‐
ence a connector or port.
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.
port
All device nodes can be virtually hotplugged, even if their hard‐
ware 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.
connection
A hotplug connection is a generic term to refer to either a hotplug
connector or a hotplug port.
Hotplug connectors and ports are managed according to a state model.
The hotplug command can list information about the hotplug connections
in a system, or it can initiate change of state operations on specific
hotplug connections.
Hotplug connectors can be in the following states:
empty
A component is not physically inserted in the connector.
present
A component is physically inserted in the connector, but the compo‐
nent is powered off. The component is not in use.
powered
A component is physically inserted in the connector, and the compo‐
nent is powered on. The component is disabled and is not in use.
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.
Hotplug ports can be in the following states:
port-empty
No device exists for the hotplug port.
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.
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.
online
A device exists for the hotplug port, and its device driver is
fully attached. The device is in use.
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.
The hotplug 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.
SUB-COMMANDS
The following subcommands are supported:
list
Show information for hotplug connectors, ports, and their associ‐
ated devices. Hotplug connectors and hotplug ports are integrated
into the Solaris device tree hierarchy. The list subcommand there‐
fore displays the hierarchy of device nodes with additional infor‐
mation included to show the locations of hotplug connectors and
hotplug ports. The names of hotplug connectors are enclosed in
square brackets, and the names of hotplug ports are enclosed in
angled brackets. The current state of each hotplug connection is
displayed next to its name.
online
Change the state of a hotplug port to the online state.
offline
Change the state of a hotplug port to the offline state.
enable
Change the state of a hotplug connector to the enabled state. All
of the hotplug connector's dependent ports will be automatically
probed and initialized into the online state.
disable
Change the state of a hotplug connector from the enabled state to
the powered state. All dependent ports that are in the online state
will first be transitioned to the port-present state.
poweron
Change the state of a hotplug connector from the present state to
the powered state.
poweroff
Change the state of a hotplug connector from the powered or enabled
state to the present state. All dependent ports that are in the
online state will first be transitioned to the port-present state,
and will then be removed.
set
Set bus-specific properties for a hotplug connector. The specified
option string is a bus specific string of name and value pairs, as
could be parsed by getsubopt(3C). The names and values will be
passed directly to the bus controller that manages the specified
hotplug connector to perform a bus-specific function.
get
Display the current values of bus specific properties for a hotplug
connector. The specified option string is a bus specific string of
named properties, as could be parsed by getsubopt(3C). The names
will be passed directly to the bus controller to specify which
properties should be returned. The current values of each named
property will then be displayed.
The install and uninstall subcommands install and uninstall services
the drivers of the ports can support.
install
The install subcommand install services the drivers of the hotplug
port's device can support.
For example, this subcommand can be applied to the port of physical
function of PCIe IO virtualization devices. It upgrades the port to
ONLINE state (if it is not yet in that state) and then installs the
virtual functions that the physical function (driver) supports. New
hotplug ports will be created to represent each virtual function as
a dependent of the specified physical function. The newly created
ports will be initiated to OFFLINE state.
uninstall
The uninstall subcommand uninstall services the drivers of the hot‐
plug port's device can support.
This subcommand can be applied to the ports of physical functions
of PCIe IO virtualization devices. If the specified hotplug port
has any dependent ports of virtual functions, the dependent ports
and corresponding virtual function nodes will be removed.
OPTIONS
The following options are supported:
-l, --list-path
Show full paths to connections and device nodes. By default, the
list subcommand shows hotplug connectors, ports, and devices in the
format of a tree. This option enables the display of full paths to
each connection and device node.
-v, --verbose
Show verbose usage details. By default, the list subcommand shows
only hotplug connectors, ports, and devices. This option enables
the display of more detailed information about how the devices are
currently consumed. Examples include mounted filesystems or plumbed
network interfaces associated with individual devices.
Note that the -v option does not display information for disks
under ZFS control.
-f, --force
Force the operation. Some change state operations that impact
resources currently in use will fail with a warning. A forced oper‐
ation will attempt to ignore these warnings and proceed.
This option should be used with extreme caution.
-q, --query
Query the operation. Instead of actually performing a change state
operation, perform a test to predict if the operation would succeed
or fail. If it would fail, show the error messages that would be
expected if the operation had really been attempted.
It is not possible to predict every failure. An operation that suc‐
ceeds during a query could still fail for another reason when actu‐
ally attempted.
This option will not actually change the state of the system.
-o options, --=options
Specify bus-specific properties for a set or get command. The
options string conforms to the getsubopt(3C) syntax convention.
For the get subcommand, there are two special options that can be
used. The special options value of help will display all supported
properties and their possible values. The special options value of
all will display the current value of all supported properties.
For the set subcommand, there is one special option that can be
used. The special options value of help will display all supported
properties which can be set and their possible values.
See "Notes" section for the properties supported by bus con‐
trollers.
-?, --help
Display a brief help message on proper use of the command.
EXAMPLES
Example 1 Showing All Hotplug Connections
The following command shows all hotplug connections:
# 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
To show the full paths of hotplug connections and devices, enter the
following command:
# 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
Example 2 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 depen‐
dent devices that are currently in use by the system might fail as fol‐
lows:
# 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 }
Example 3 Displaying Bus-Specific Properties and Values
The following command displays all supported bus-specific properties
and their possible values:
# 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>
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:
# hotplug get -o card_type,power_led /pci@0,0 pci.2,1
card_type=fibre
power_led=on
Example 5 Setting a Bus-Specific Property
The following command turns on the attention LED of a PCI hotplug con‐
nector:
# hotplug set -o attn_led=on /pci@0,0 pci.2,1
Example 6 Installing Port Dependents
The following commands install dependent ports of an IOV physical func‐
tion and then display the resulting IOV virtual functions that were
probed.
# hotplug install /pci@400/pci@1/pci@0/pci@4 pci.0,1
# hotplug list -v /pci@400/pci@1/pci@0/pci@4 pci.0,1
<pci.0,1> (ONLINE)
{ IOV physical function }
{ IOV virtual function 'pci.0,81' }
{ IOV virtual function 'pci.0,83' }
{ IOV virtual function 'pci.0,85' }
{ IOV virtual function 'pci.0,87' }
<pci.0,81> (OFFLINE)
ethernet@0,81
<pci.0,83> (OFFLINE)
ethernet@0,83
<pci.0,85> (OFFLINE)
ethernet@0,85
<pci.0,87> (OFFLINE)
ethernet@0,87
Example 7 Uninstalling Port Dependents
The following command attempts to uninstall dependent ports of an IOV
physical function, but fails when a dependent IOV virtual function is
busy.
# hotplug uninstall /pci@400/pci@1/pci@0/pci@4 pci.0,0
ERROR: devices or resources are busy.
ethernet@0,81:
{ Network interface igvbf1 }
{ igvbf1: hosts IP addresses: 10.0.0.1 }
{ Plumbed IP Address }
EXIT STATUS
0
Successful completion.
1
Invalid command line options were specified.
2
The specified path or connection does not exist.
3
A fatal error occurred. One or more error messages are displayed on
standard error.
4
The hotplug service is not available.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Availability │SUNWcs │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Committed │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOcfgadm(1M), hotplugd(1M), getsubopt(3C), attributes(5)DIAGNOSTICS
The following error message is displayed on systems that do not have
any supported IO buses:
ERROR: there are no connections to display.
(See hotplug(1m) for more information.)
If this error message is seen, note that the system might still have
other IO devices that support hotplugging, through the cfgadm(1M) com‐
mand instead of hotplug.
NOTES
The hotplug service (FMRI svc:/system/hotplug) must be enabled as a
prerequisite for using the hotplug command. The service is disabled by
default. See hotplugd(1M).
The authorization solaris.hotplug.modify must be granted in order to
perform change-of-state operations, or to install and uninstall depen‐
dent ports. Alternatively, the rights profile "Hotplug Management" can
be granted, which includes that authorization.
Verbose usage information is gathered from the RCM framework. Its for‐
mat and content is subject to change.
The following bus specific properties are supported in PCI bus con‐
trollers:
power_led | fault_led | attn_led | active_led
States of a specific LED of a slot. The value could be on, off, or
blink.
They can all be used with get subcommand, but only property
attn_led can be used with set subcommand.
card_type | board_type
Type of a card or board of a slot.
They can all be used with get subcommand, but neither can be used
with set subcommand.
SunOS 5.10 12 Dec 2011 hotplug(1M)
