Manual Pages for UNIX Operating System command usage for man hotplug
System Administration Commands hotplug(1M)
NAME
hotplug - configure hotplug connectors and ports
SYNOPSIS
hotplug 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 -?
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 hot-
plug connectors 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 sup-
ported in the future.
SunOS 5.11 Last change: 10 Mar 2010 1
System Administration Commands hotplug(1M)
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 dev-
ice 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 connec-
tor 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 loca-
tion 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.
SunOS 5.11 Last change: 10 Mar 2010 2
System Administration Commands hotplug(1M)
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
SunOS 5.11 Last change: 10 Mar 2010 3
System Administration Commands hotplug(1M)
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 associated devices. Hotplug connectors and hotplug
ports are integrated into the Solaris device tree
hierarchy. The list subcommand therefore displays the
hierarchy of device nodes with additional information
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
SunOS 5.11 Last change: 10 Mar 2010 4
System Administration Commands hotplug(1M)
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 transi-
tioned 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 proper-
ties should be returned. The current values of each
named property will then be displayed.
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.
SunOS 5.11 Last change: 10 Mar 2010 5
System Administration Commands hotplug(1M)
-v, --verbose
Show verbose usage details. By default, the list subcom-
mand shows only hotplug connectors, ports, and devices.
This option enables the display of more detailed infor-
mation 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 warn-
ing. A forced operation 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 opera-
tion had really been attempted.
It is not possible to predict every failure. An opera-
tion that succeeds during a query could still fail for
another reason when actually attempted.
This option will not actually change the state of the
system.
-o options, --=options
Specify bus-specific properties for a set or get com-
mand. 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
SunOS 5.11 Last change: 10 Mar 2010 6
System Administration Commands hotplug(1M)
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
controllers.
-?, --help
Display a brief help message on proper use of the com-
mand.
EXAMPLES
Example 1 Showing All Hotplug Connections
The following command shows all hotplug connections:
# hotplug list -v
pci@0,0
(ONLINE)
pci108e,534a@2,1
[pci30] (EMPTY)
(ONLINE)
pci10de,5d@e
(ONLINE)
display@b
[NEM0] (ENABLED)
(ONLINE)
pci108e,534a@a,0
{ Network interface nge0 }
{ nge0: hosts IP addresses: 10.0.0.1 }
(MAINTENANCE)
pci108e,534a@a,1
[NEM1] (EMPTY)
(OFFLINE)
pci108e,534a@4
To show the full paths of hotplug connections and devices,
enter the following command:
# hotplug list -l
/pci@0,0 (ONLINE)
/pci@0,0/pci108e,534a@2,1 [pci30] (EMPTY)
/pci@0,0 pci.e,0> (ONLINE)
SunOS 5.11 Last change: 10 Mar 2010 7
System Administration Commands hotplug(1M)
/pci@0,0/pci10de,5d@e (ONLINE)
/pci@0,0/pci10de,5d@e/display@b
/pci@0,0/pci10de,5d@e [NEM0] (ENABLED)
/pci@0,0/pci10de,5d@e (ONLINE)
/pci@0,0/pci10de,5d@e/pci108e,534a@a,0
/pci@0,0/pci10de,5d@e (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=
fault_led=
active_led=
attn_led=
card_type=
board_type=
Example 4 Displaying Bus-Specific Options
SunOS 5.11 Last change: 10 Mar 2010 8
System Administration Commands hotplug(1M)
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
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 attri-
butes:
SunOS 5.11 Last change: 10 Mar 2010 9
System Administration Commands hotplug(1M)
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWcs |
|_____________________________|_____________________________|
| Interface Stability | Committed |
|_____________________________|_____________________________|
SEE ALSO
cfgadm(1M), hotplugd(1M), getsubopt(3C), attributes(5)
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(1m) 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(1M) command 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. Alternatively,
the rights profile "Hotplug Management" can be granted,
which includes that authorization.
Verbose usage information is gathered from the RCM frame-
work. 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 pro-
perty attn_led can be used with set subcommand.
SunOS 5.11 Last change: 10 Mar 2010 10
System Administration Commands hotplug(1M)
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.11 Last change: 10 Mar 2010 11