HOTPLUG(8) Maintenance Commands and Procedures HOTPLUG(8)

NAME

hotplug - configure hotplug connectors and ports

SYNOPSIS

hotplug -?
hotplug list [-lv] [path] [connection]
hotplug online path port
hotplug offline [-fq] path port
hotplug enable path connector
hotplug disable [-fq] path connector
hotplug poweron path connector
hotplug poweroff [-fq] path connector
hotplug set -o options path connector
hotplug get -o options path connector

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
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.

The hotplug command operates on the following kinds of objects:

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.

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
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.

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
component is powered off. The component is not in use.

powered A component is physically inserted in the connector, and the
component 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.

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.

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
dependent devices that are currently in use by the system might fail
as follows:

# 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
connector:

# hotplug set -o attn_led=on /pci@0,0 pci.2,1

DIAGNOSTICS

The following error message is displayed on systems that do not have
any supported I/O buses:

ERROR: there are no connections to display.
(See hotplug(8) for more information.)

If this error message is seen, note that the system might still have
other I/O devices that support hotplugging, through the cfgadm(8)
command instead of hotplug.

INTERFACE STABILITY

Committed

SEE ALSO

getsubopt(3C), rcmscript(5), attributes(7), cfgadm(8), hotplugd(8)

NOTES

The hotplug service (FMRI svc:/system/hotplug) must be enabled as a
prerequisite for using the hotplug command. See hotplugd(8).

The authorization solaris.hotplug.modify must be granted in order to
perform change-of-state operations. Alternatively, the rights profile
"Hotplug Management" can be granted, which includes that authorization.

Verbose usage information is gathered from the RCM framework. Its
format and content is subject to change.

The following bus specific properties are supported in PCI bus
controllers:

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.

illumos March 2, 2020 illumos