1 .\"
2 .\" The contents of this file are subject to the terms of the
3 .\" Common Development and Distribution License (the "License").
4 .\" You may not use this file except in compliance with the License.
5 .\"
6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
7 .\" or http://www.opensolaris.org/os/licensing.
8 .\" See the License for the specific language governing permissions
9 .\" and limitations under the License.
10 .\"
11 .\" When distributing Covered Code, include this CDDL HEADER in each
12 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
13 .\" If applicable, add the following below this CDDL HEADER, with the
14 .\" fields enclosed by brackets "[]" replaced with your own identifying
15 .\" information: Portions Copyright [yyyy] [name of copyright owner]
16 .\"
17 .\"
18 .\" Copyright (c) 2010, Sun Microsystems, Inc. All Rights Reserved
19 .\" Copyright 2020 Joyent, Inc.
20 .\"
21 .Dd March 2, 2020
22 .Dt HOTPLUG 1M
23 .Os
24 .Sh NAME
25 .Nm hotplug
26 .Nd configure hotplug connectors and ports
27 .Sh SYNOPSIS
28 .Nm
29 .Fl \&?
30 .Nm
31 .Cm list
32 .Op Fl lv
33 .Op Ar path
34 .Op Ar connection
35 .Nm
36 .Cm online
37 .Ar path
38 .Ar port
39 .Nm
40 .Cm offline
41 .Op Fl fq
42 .Ar path
43 .Ar port
44 .Nm
45 .Cm enable
46 .Ar path
47 .Ar connector
48 .Nm
49 .Cm disable
50 .Op Fl fq
51 .Ar path
52 .Ar connector
53 .Nm
54 .Cm poweron
55 .Ar path
56 .Ar connector
57 .Nm
58 .Cm poweroff
59 .Op Fl fq
60 .Ar path
61 .Ar connector
62 .Nm
63 .Cm set
64 .Fl o Ar options
65 .Ar path
66 .Ar connector
67 .Nm
68 .Cm get
69 .Fl o Ar options
70 .Ar path
71 .Ar connector
72 .Sh DESCRIPTION
73 The
74 .Nm
75 command is used to manage hotplug connections.
76 A connection can be a connector or port.
77 A hotplug connector is a representation of a physical point in the system where
78 components can be inserted or removed.
79 A hotplug port is a representation of a logical point in the system device tree
80 where the connection of a device to the system is managed.
81 .Pp
82 The
83 .Nm
84 command only supports hotplug operations on hotplug connectors for PCI Express
85 buses and PCI buses that implement the Standard PCI Hotplug feature.
86 Hotplug ports on PCI Express and PCI buses in systems with PCI Express fabrics
87 are also supported.
88 Additional buses may be supported in the future.
89 .Pp
90 The
91 .Nm
92 command operates on the following kinds of objects:
93 .Bl -tag -width "connection"
94 .It Cm path
95 Hotplug connectors and ports are integrated into the system device tree.
96 The names of connectors and ports are unique relative only to their bus
97 controller.
98 A device path is required to uniquely reference a connector or port.
99 .It Cm connector
100 If a hardware component supports being physically inserted or removed, then a
101 hotplug connector represents the location where this action may occur.
102 When a connector exists, it has a hierarchy of ports and device nodes that
103 depend upon it.
104 .It Cm port
105 All device nodes can be virtually hotplugged, even if their hardware does not
106 support physical hotplugging.
107 A hotplug port exists between a device node and its parent node in the system
108 device tree.
109 It represents the location where the device node and its dependents can be
110 managed.
111 .It Cm connection
112 A hotplug connection is a generic term to refer to either a hotplug connector or
113 a hotplug port.
114 .El
115 .Pp
116 Hotplug connectors and ports are managed according to a state model.
117 The
118 .Nm
119 command can list information about the hotplug connections in a system, or it
120 can initiate change of state operations on specific hotplug connections.
121 .Pp
122 Hotplug connectors can be in the following states:
123 .Bl -tag -width "present"
124 .It Cm empty
125 A component is not physically inserted in the connector.
126 .It Cm present
127 A component is physically inserted in the connector, but the component is
128 powered off.
129 The component is not in use.
130 .It Cm powered
131 A component is physically inserted in the connector, and the component is
132 powered on.
133 The component is disabled and is not in use.
134 .It Cm enabled
135 A component is physically inserted in the connector.
136 The component is powered on and has been probed and tested.
137 The component is enabled and devices that represent its functions can be used.
138 .El
139 .Pp
140 Hotplug ports can be in the following states:
141 .Bl -tag -width "port-present"
142 .It Cm port-empty
143 No device exists for the hotplug port.
144 .It Cm port-present
145 A device exists for the hotplug port, but the device has not been probed and it
146 has no attached device driver.
147 The device is not in use.
148 .It Cm offline
149 A device exists for the hotplug port, and the device has been probed.
150 A device driver is not attached, and the device is not in use.
151 .It Cm online
152 A device exists for the hotplug port, and its device driver is fully attached.
153 The device is in use.
154 .It Cm maintenance
155 A device exists for the hotplug port, and its device driver is fully attached.
156 The device is in use, but not fully operational.
157 A maintenance or fault management operation is affecting the device.
158 .El
159 .Pp
160 The
161 .Nm
162 command can also access bus private properties for each hotplug connector.
163 The current values of bus private properties can be displayed.
164 New values for each bus private property can be set directly.
165 .Sh EXIT STATUS
166 .Bl -diag
167 .It 0
168 Successful completion.
169 .It 1
170 Invalid command line options were specified.
171 .It 2
172 The specified path or connection does not exist.
173 .It 3
174 A fatal error occurred.
175 One or more error messages are displayed on standard error.
176 .It 4
177 The hotplug service is not available.
178 .El
179 .Sh EXAMPLES
180 .Bl -tag -width 0n
181 .It Sy Example 1 No Showing All Hotplug Connections
182 The following command shows all hotplug connections:
183 .Bd -literal
184 # hotplug list -v
185 pci@0,0
186 <pci.2,1> (ONLINE)
187 pci108e,534a@2,1
188 [pci30] (EMPTY)
189 <pci.e,0> (ONLINE)
190 pci10de,5d@e
191 <pci.b,0> (ONLINE)
192 display@b
193 [NEM0] (ENABLED)
194 <pci.a,0> (ONLINE)
195 pci108e,534a@a,0
196 { Network interface nge0 }
197 { nge0: hosts IP addresses: 10.0.0.1 }
198 <pci.a,1> (MAINTENANCE)
199 pci108e,534a@a,1
200 [NEM1] (EMPTY)
201 <pci.c,0> (OFFLINE)
202 pci108e,534a@4
203 .Ed
204 .Pp
205 To show the full paths of hotplug connections and devices, enter the following
206 command:
207 .Bd -literal
208 # hotplug list -l
209 /pci@0,0 <pci.2,1> (ONLINE)
210 /pci@0,0/pci108e,534a@2,1 [pci30] (EMPTY)
211 /pci@0,0 pci.e,0> (ONLINE)
212 /pci@0,0/pci10de,5d@e <pci.b,0> (ONLINE)
213 /pci@0,0/pci10de,5d@e/display@b
214 /pci@0,0/pci10de,5d@e [NEM0] (ENABLED)
215 /pci@0,0/pci10de,5d@e <pci.a,0> (ONLINE)
216 /pci@0,0/pci10de,5d@e/pci108e,534a@a,0
217 /pci@0,0/pci10de,5d@e <pci.a,1> (MAINTENANCE)
218 /pci@0,0/pci10de,5d@e/pci108e,534a@a,0
219 /pci@0,0/pci10de,5d@e [NEM1] (EMPTY)
220 /pci@0,0 pci.c,0> (OFFLINE)
221 /pci@0,0/pci108e,534a@4
222 .Ed
223 .It Sy Example 2 No Reporting Failure During State Change Operation
224 If a change of state operation fails, an explanation is displayed to describe
225 the failure.
226 An attempt to offline a hotplug port with dependent devices that are currently
227 in use by the system might fail as follows:
228 .Bd -literal
229 # hotplug offline /pci@0,0/pci10de,5d@e pci.a,0
230 ERROR: devices or resources are busy.
231 pci108e,534a@a,0:
232 { Network interface nge0 }
233 { nge0: hosts IP addresses: 10.0.0.1 }
234 { Plumbed IP Address }
235 .Ed
236 .It Sy Example 3 No Displaying Bus-Specific Properties and Values
237 The following command displays all supported bus-specific properties and their
238 possible values:
239 .Bd -literal
240 # hotplug get -o help /pci@0,0 pci.2,1
241 power_led=<on|off|blink>
242 fault_led=<on|off|blink>
243 active_led=<on|off|blink>
244 attn_led=<on|off|blink>
245 card_type=<type description>
246 board_type=<type description>
247 .Ed
248 .It Sy Example 4 Displaying Bus-Specific Options
249 The following command displays the card type and the current state of the Power
250 LED of a PCI hotplug connector:
251 .Bd -literal
252 # hotplug get -o card_type,power_led /pci@0,0 pci.2,1
253 card_type=fibre
254 power_led=on
255 .Ed
256 .It Sy Example 5 No Setting a Bus-Specific Property
257 The following command turns on the attention LED of a PCI hotplug connector:
258 .Bd -literal
259 # hotplug set -o attn_led=on /pci@0,0 pci.2,1
260 .Ed
261 .El
262 .Sh DIAGNOSTICS
263 The following error message is displayed on systems that do not have any
264 supported I/O buses:
265 .Bd -literal
266 ERROR: there are no connections to display.
267 (See hotplug(1m) for more information.)
268 .Ed
269 .Pp
270 If this error message is seen, note that the system might still have other I/O
271 devices that support hotplugging, through the
272 .Xr cfgadm 1M
273 command instead of
274 .Nm .
275 .Sh INTERFACE STABILITY
276 .Sy Committed
277 .Sh SEE ALSO
278 .Xr cfgadm 1M ,
279 .Xr hotplugd 1M ,
280 .Xr getsubopt 3C ,
281 .Xr rcmscript 4 ,
282 .Xr attributes 5
283 .Sh NOTES
284 The
285 .Nm
286 service
287 .Po FMRI
288 .Pa svc:/system/hotplug
289 .Pc
290 must be enabled as a prerequisite for using the
291 .Nm
292 command.
293 See
294 .Xr hotplugd 1M .
295 .Pp
296 The authorization
297 .Pa solaris.hotplug.modify
298 must be granted in order to perform change-of-state operations.
299 Alternatively, the rights profile
300 .Qq Hotplug Management
301 can be granted, which includes that authorization.
302 .Pp
303 Verbose usage information is gathered from the RCM framework.
304 Its format and content is subject to change.
305 .Pp
306 The following bus specific properties are supported in PCI bus controllers:
307 .Bl -tag -width Ds
308 .It Cm power_led No \&| Cm fault_led No \&| Cm attn_led No \&| Cm active_led
309 States of a specific LED of a slot.
310 The value could be
311 .Cm on , off ,
312 or
313 .Cm blink .
314 .Pp
315 They can all be used with
316 .Cm get
317 subcommand, but only property
318 .Cm attn_led
319 can be used with
320 .Cm set
321 subcommand.
322 .It Cm card_type No \&| Cm board_type
323 Type of a card or board of a slot.
324 .Pp
325 They can all be used with
326 .Cm get
327 subcommand, but neither can be used with
328 .Cm set
329 subcommand.
330 .El