1 HOTPLUG(1M) Maintenance Commands HOTPLUG(1M)
2
3 NAME
4 hotplug - configure hotplug connectors and ports
5
6 SYNOPSIS
7 hotplug -?
8 hotplug list [-lv] [path] [connection]
9 hotplug online path port
10 hotplug offline [-fq] path port
11 hotplug enable path connector
12 hotplug disable [-fq] path connector
13 hotplug poweron path connector
14 hotplug poweroff [-fq] path connector
15 hotplug set -o options path connector
16 hotplug get -o options path connector
17
18 DESCRIPTION
19 The hotplug command is used to manage hotplug connections. A connection
20 can be a connector or port. A hotplug connector is a representation of a
21 physical point in the system where components can be inserted or removed.
22 A hotplug port is a representation of a logical point in the system
23 device tree where the connection of a device to the system is managed.
24
25 The hotplug command only supports hotplug operations on hotplug
26 connectors for PCI Express buses and PCI buses that implement the
27 Standard PCI Hotplug feature. Hotplug ports on PCI Express and PCI buses
28 in systems with PCI Express fabrics are also supported. Additional buses
29 may be supported in the future.
30
31 The hotplug command operates on the following kinds of objects:
32
33 path Hotplug connectors and ports are integrated into the system
34 device tree. The names of connectors and ports are unique
35 relative only to their bus controller. A device path is
36 required to uniquely reference a connector or port.
37
38 connector If a hardware component supports being physically inserted or
39 removed, then a hotplug connector represents the location
40 where this action may occur. When a connector exists, it has
41 a hierarchy of ports and device nodes that depend upon it.
42
43 port All device nodes can be virtually hotplugged, even if their
44 hardware does not support physical hotplugging. A hotplug
45 port exists between a device node and its parent node in the
46 system device tree. It represents the location where the
47 device node and its dependents can be managed.
48
49 connection A hotplug connection is a generic term to refer to either a
50 hotplug connector or a hotplug port.
51
52 Hotplug connectors and ports are managed according to a state model. The
53 hotplug command can list information about the hotplug connections in a
54 system, or it can initiate change of state operations on specific hotplug
55 connections.
56
57 Hotplug connectors can be in the following states:
58
59 empty A component is not physically inserted in the connector.
60
61 present A component is physically inserted in the connector, but the
62 component is powered off. The component is not in use.
63
64 powered A component is physically inserted in the connector, and the
65 component is powered on. The component is disabled and is not
66 in use.
67
68 enabled A component is physically inserted in the connector. The
69 component is powered on and has been probed and tested. The
70 component is enabled and devices that represent its functions
71 can be used.
72
73 Hotplug ports can be in the following states:
74
75 port-empty No device exists for the hotplug port.
76
77 port-present A device exists for the hotplug port, but the device has
78 not been probed and it has no attached device driver. The
79 device is not in use.
80
81 offline A device exists for the hotplug port, and the device has
82 been probed. A device driver is not attached, and the
83 device is not in use.
84
85 online A device exists for the hotplug port, and its device driver
86 is fully attached. The device is in use.
87
88 maintenance A device exists for the hotplug port, and its device driver
89 is fully attached. The device is in use, but not fully
90 operational. A maintenance or fault management operation
91 is affecting the device.
92
93 The hotplug command can also access bus private properties for each
94 hotplug connector. The current values of bus private properties can be
95 displayed. New values for each bus private property can be set directly.
96
97 EXIT STATUS
98 0 Successful completion.
99
100 1 Invalid command line options were specified.
101
102 2 The specified path or connection does not exist.
103
104 3 A fatal error occurred. One or more error messages are displayed on
105 standard error.
106
107 4 The hotplug service is not available.
108
109 EXAMPLES
110 Example 1 Showing All Hotplug Connections
111 The following command shows all hotplug connections:
112
113 # hotplug list -v
114 pci@0,0
115 <pci.2,1> (ONLINE)
116 pci108e,534a@2,1
117 [pci30] (EMPTY)
118 <pci.e,0> (ONLINE)
119 pci10de,5d@e
120 <pci.b,0> (ONLINE)
121 display@b
122 [NEM0] (ENABLED)
123 <pci.a,0> (ONLINE)
124 pci108e,534a@a,0
125 { Network interface nge0 }
126 { nge0: hosts IP addresses: 10.0.0.1 }
127 <pci.a,1> (MAINTENANCE)
128 pci108e,534a@a,1
129 [NEM1] (EMPTY)
130 <pci.c,0> (OFFLINE)
131 pci108e,534a@4
132
133 To show the full paths of hotplug connections and devices, enter the
134 following command:
135
136 # hotplug list -l
137 /pci@0,0 <pci.2,1> (ONLINE)
138 /pci@0,0/pci108e,534a@2,1 [pci30] (EMPTY)
139 /pci@0,0 pci.e,0> (ONLINE)
140 /pci@0,0/pci10de,5d@e <pci.b,0> (ONLINE)
141 /pci@0,0/pci10de,5d@e/display@b
142 /pci@0,0/pci10de,5d@e [NEM0] (ENABLED)
143 /pci@0,0/pci10de,5d@e <pci.a,0> (ONLINE)
144 /pci@0,0/pci10de,5d@e/pci108e,534a@a,0
145 /pci@0,0/pci10de,5d@e <pci.a,1> (MAINTENANCE)
146 /pci@0,0/pci10de,5d@e/pci108e,534a@a,0
147 /pci@0,0/pci10de,5d@e [NEM1] (EMPTY)
148 /pci@0,0 pci.c,0> (OFFLINE)
149 /pci@0,0/pci108e,534a@4
150
151 Example 2 Reporting Failure During State Change Operation
152 If a change of state operation fails, an explanation is displayed to
153 describe the failure. An attempt to offline a hotplug port with
154 dependent devices that are currently in use by the system might fail as
155 follows:
156
157 # hotplug offline /pci@0,0/pci10de,5d@e pci.a,0
158 ERROR: devices or resources are busy.
159 pci108e,534a@a,0:
160 { Network interface nge0 }
161 { nge0: hosts IP addresses: 10.0.0.1 }
162 { Plumbed IP Address }
163
164 Example 3 Displaying Bus-Specific Properties and Values
165 The following command displays all supported bus-specific properties
166 and their possible values:
167
168 # hotplug get -o help /pci@0,0 pci.2,1
169 power_led=<on|off|blink>
170 fault_led=<on|off|blink>
171 active_led=<on|off|blink>
172 attn_led=<on|off|blink>
173 card_type=<type description>
174 board_type=<type description>
175
176 Example 4 Displaying Bus-Specific Options
177 The following command displays the card type and the current state of
178 the Power LED of a PCI hotplug connector:
179
180 # hotplug get -o card_type,power_led /pci@0,0 pci.2,1
181 card_type=fibre
182 power_led=on
183
184 Example 5 Setting a Bus-Specific Property
185 The following command turns on the attention LED of a PCI hotplug
186 connector:
187
188 # hotplug set -o attn_led=on /pci@0,0 pci.2,1
189
190 DIAGNOSTICS
191 The following error message is displayed on systems that do not have any
192 supported I/O buses:
193
194 ERROR: there are no connections to display.
195 (See hotplug(1m) for more information.)
196
197 If this error message is seen, note that the system might still have
198 other I/O devices that support hotplugging, through the cfgadm(1M)
199 command instead of hotplug.
200
201 INTERFACE STABILITY
202 Committed
203
204 SEE ALSO
205 cfgadm(1M), hotplugd(1M), getsubopt(3C), rcmscript(4), attributes(5)
206
207 NOTES
208 The hotplug service (FMRI svc:/system/hotplug) must be enabled as a
209 prerequisite for using the hotplug command. See hotplugd(1M).
210
211 The authorization solaris.hotplug.modify must be granted in order to
212 perform change-of-state operations. Alternatively, the rights profile
213 "Hotplug Management" can be granted, which includes that authorization.
214
215 Verbose usage information is gathered from the RCM framework. Its format
216 and content is subject to change.
217
218 The following bus specific properties are supported in PCI bus
219 controllers:
220
221 power_led | fault_led | attn_led | active_led
222 States of a specific LED of a slot. The value could be on, off,
223 or blink.
224
225 They can all be used with get subcommand, but only property
226 attn_led can be used with set subcommand.
227
228 card_type | board_type
229 Type of a card or board of a slot.
230
231 They can all be used with get subcommand, but neither can be used
232 with set subcommand.
233
234 illumos March 2, 2020 illumos