1cfgadm_sata(1M) System Administration Commands cfgadm_sata(1M)
2
6 cfgadm_sata - SATA hardware-specific commands for cfgadm
7
9 /usr/sbin/cfgadm [-f] [-y | -n] [-v] [-o hardware_options]
10 -c function ap_id...
11 /usr/sbin/cfgadm [-f] [-y | -n] [-v] [-o hardware_options]
14 -x hardware_function ap_id...
15 /usr/sbin/cfgadm [-v] [-a] [-s listing_options]
18 [-o hardware_options] [-l [ap_id | ap_type]...]
19 /usr/sbin/cfgadm [-v] [-o harware_options] -t ap_id...
22 /usr/sbin/cfgadm [-v] [-o hardware_options] -h [ap_id]...
25
28 The SATA hardware specific library, /usr/lib/cfgadm/sata.so.1, provides
29 the functionality for SATA hot plugging through the cfgadm command.
30 cfgadm operates on attachment points, which are locations in the system
31 where hardware resources can be dynamically reconfigured. See
32 cfgadm(1M) for information regarding attachment points.
33 Each SATA controller's and port multiplier's device port is represented
36 by an attachment point in the device tree. SATA devices, connected and
37 configured in the system are shown as the attachment point name exten‐
38 sion. The terms "attachment point" and "SATA port" are used inter‐
39 changeably in the following description.
40 Attachment points are named through ap_ids. All the SATA attachment
43 points ap_id consist of a string in the following form:
44 sataX/P[.M][::dsk/cXtYd0]
46 where
50 X is the SATA controller number
52 P is the SATA controller's device port number (0 to 31)
55 M is the port multiplier's device port number (0 to 14) the
58 port multiplier host port number (15). It is used only
59 when the port multiplier is attached to the SATA con‐
60 troller's device port.
61 dev/cXtYd0 identifies the attached SATA device
64 Y is a target number
67 In general, the device identifier is derived from the corresponding
71 logical link for the device in /dev. Because only one LUN (LUN 0) is
72 supported by the SATA device, the "d" component of the device string
73 will always have number 0 (zero).
74 For example, the logical ap_id of the device port 4 of the port multi‐
77 plier connected to the device port 5 of the SATA controller 2 would be:
78 sata2/5.4
80 If the SATA disk or CD/DVD device is connected to this attachment
84 point, and the device is configured, the ap_id would be:
85 sata2/5.4::dsk/c2t645d0
87 The cXtYd0 string identifying a device has one-to-one correspondence to
91 the device attachment point.
92 A simple listing of attachment points in the system will include all
95 SATA device ports and attached devices. For example:
96 #cfgadm -l
98 Ap_Id Type Receptacle Occupant Condition
99 sata0/0::dev/c0t0d0 disk connected configured ok
100 sata0/1::dev/c0t1d0 disk connected configured ok
101 sata0/2::dev/c0t2d0 cd-dvd connected configured ok
102 sata0/3 sata-port empty unconfigured ok
103 sata1/0 sata-port disconnected unconfigured unknown
104 sata1/1 sata port disconnected unconfigured unknown
105 sata1/2 sata port empty unconfigured ok
106 sata1/3.15 sata-pmult connected configured ok
107 sata1/3.0::dev/c0t512d0 disk connected configured ok
108 sata1/3.1 sata-port empty unconfigured ok
109 sata1/3.2 sata-port empty unconfigured ok
110 sata1/3.3 sata-port empty unconfigured ok
111 usb0/1 unknown empty unconfigured ok
112 usb0/2 unknown empty unconfigured ok
113 See cfgadm(1M)for more information regarding listing of attachment
118 points.
119 The receptacle state for attachment point at the SATA port have the
122 following meanings:
123 empty The SATA port is powered-on and enabled. No device
125 presence was detected on this port.
126 disconnected The SATA port is not enabled or the SATA device pres‐
129 ence was detected but no communication with the device
130 was established, or the port has failed.
131 connected The SATA device is detected on the port the communica‐
134 tion with the device is established.
135 The occupant (device attached to the SATA port) state have the follow‐
139 ing meanings:
140 configured The attached SATA device is configured and ready to use
142 by the operating system.
143 unconfigured No device is attached, or the SATA device attached to
146 the SATA port was not yet configured. To configure it,
147 run the command "cfgadm -c configure ap_id".
148 The attachment point (SATA port) condition have the following meanings:
152 ok The SATA port is powered-on and enabled, and is ready for
154 use.
155 failed The SATA port failed. It may be disabled and/or powered-off
158 by the system. It is unusable and its condition is unknown.
159 It may be due to the device plugged-in.
160 unknown The SATA port is disabled and its condition is unknown.
163 A "state table" is the combination of an attachment point receptacle
167 state, an occupant state, and an attachment point (SATA port) condi‐
168 tion. The valid states are:
169 empty/unconfigured/ok
171 The SATA port is enabled and active. No device presence was
173 detected.
174 disconnected/unconfigured/ok
177 The SATA port is enabled and a device presence was detected but no
179 communications with the device was established.
180 disconnected/unconfigured/unknown
183 The SATA Port is disabled and its condition is unknown.
185 disconnected/unconfigured/failed
188 The SATA Port is disabled and unusable. The port was disabled by
190 the system due to a system-detected failure.
191 connected/unconfigured/ok
194 The SATA Port is enabled and active. A device presence was detected
196 and the communication with a device was established. The device is
197 not configured to be used by the OS.
198 connected/configured/ok
201 The device is present and configured, and is ready to use by the
203 OS.
204
207 cfgadm defines several types of operations besides listing (-l). These
208 operations include testing, (-t), invoking configuration state changes,
209 (-c), invoking hardware specific functions (-x), and obtaining configu‐
210 ration administration help messages (-h).
211 -c function
213 The following generic functions are defined for the SATA hardware
215 specific library. For SATA port attachment point, the following
216 configuration state change operations are supported:
217 connect
219 Enable (activate) the SATA port and establish the communication
221 with an attached device. This operation implies powering-on the
222 port if necessary.
223 disconnect
226 Unconfigure the attached device, if it is not already unconfig‐
228 ured, and disable (deactivate) the SATA port. A subsequent
229 "connect" command enables SATA port operation but does not
230 bring a device to the "configured" state.
231 For a SATA device attached to the SATA port following state change
233 operations are supported:
234 configure Configure new device for use by the operating system
236 if it is not already configured. This command also
237 implies connect operation, if necessary.
238 unconfigure Unconfigure the device connected to the SATA port if
241 it is not already unconfigured.
242 The configure and unconfigure operations cannot be used for an
244 attachment point where the port multiplier is connected. Port mul‐
245 tipliers are configured and unconfigured automatically by the sys‐
246 tem. However, configure and unconfigure operations apply to all
247 SATA devices connected to the port multiplier's device ports.
248 -f
251 Not supported.
253 -h ap_id
256 SATA specific help can be obtained by using the help option with
258 any SATA attachment point.
259 -l [-v]
262 The -l option works as described in cfgadm(1M). When paired with
264 the -v option, the "Information" field contains the following SATA-
265 specific information:
266 o Mfg: manufacturer string
268 o Product: product string
270 o No: product Serial Number
272 -o hardware_options
275 No hardware specific options are currently defined.
277 -s listing_options
280 Attachment points of class SATA can be listed by using the select
282 suboption. See cfgadm(1M).
283 -t ap_id
286 Perform self-test of the SATA port, if supported by the SATA con‐
288 troller. If a port self-test operation is not supported by the SATA
289 controller, an error message is issued.
290 -x hardware_function
293 Perform hardware specific function.
295 Some of the following commands used on the SATA ports or the SATA
297 controller may affect any SATA devices that have been attached, as
298 noted. ap_id refers to SATA port or the entire SATA controller, as
299 noted. If the operation implies unconfiguring a device, but it can‐
300 not be unconfigured (that is, the device contains a mounted
301 filesystem), an error message is issued and the operation is not
302 performed. An error message will be also issued if the SATA con‐
303 troller does not support specified operation.
304 sata_reset_device ap_id
306 Reset the SATA device attached to ap_id SATA port. The SATA
308 port state does not change.
309 sata_reset_port ap_id
312 Reset the SATA port specified by ap_id. If a SATA device is
314 attached to the port, it is also reset. This operation may be
315 also performed on the port to which a port multiplier is con‐
316 nected. If a port multiplier is connected to the SATA con‐
317 troller port, the SATA devices attached to the port multiplier
318 may not be reset
319 sata_reset_all ap_id
322 Reset SATA controller specified by the controller number part
324 in ap_id and all attached devices and re-enumerate all con‐
325 nected devices, including port multipliers and devices con‐
326 nected to port multipliers' device ports.
327 This operations implies unconfiguring all attached devices
329 prior to the operation. Any newly enumerated devices will be
330 left unconfigured.
331 sata_port_deactivate ap_id
334 Force the deactivation of the port when all else fails. This is
336 meant as an emergency step; use with caution.
337 sata_port_activate ap_id
340 Force the activation of a port. This is meant for emergency
342 situations on a port which was deactivated to recover from
343 errors.
344 sata_port_self_test ap_id
347 Perform self-test operation on the SATA controller. This opera‐
349 tion implies unconfiguring all devices and resetting the SATA
350 controller.
351 -v
355 Execute in verbose mode.
357 The following Transitions table reports the state transitions
359 resulting from the -c operations and hotplugging actions:
360 current state operation possible new state
362 ------------- --------- ------------------
363 empty/
364 unconfigured/ok device plug-in connected/unconfigured/ok, or
365 disconnected/unconfigured/ok, or
366 disconnected/unconfigured/failed
367 empty/
369 unconfigured/ok -c unconfigure error message, no state change
370 empty/
372 unconfigured/ok -c configure error message, no state change
373 empty/
375 unconfigured/ok -c connect error message, no state change
376 empty/
378 unconfigured/ok -c disconnect disconnected/unconfigured/unknown, or
379 disconnected/unconfigured/failed
380 disconnected/
382 unconfigured/ok device unplug no state change
383 disconnected/
385 unconfigured/ok -c unconfigure error message, no state change
386 disconnected/
388 unconfigured/ok -c configure error message, no state change
389 disconnected/
391 unconfigured/ok -c connect error message, no state change
392 disconnected/
394 unconfigured/ok -c disconnect error message, no state change
395 disconnected/
397 unconfigured/
398 unknown
399 (no disk plugged) -c configure error message, state change to
400 empty/unconfigured/ok, or
401 disconnected/unconfigured/failed
402 disconnected/
404 unconfigured/
405 unknown -c configure state change to
406 (disk plugged) connected/configured/ok or,
407 connected/unconfigured/ok, or
408 disconnected/unconfigured/failed and
409 possible error message
410 disconnected/
412 unconfigured/
413 unknown -c connect empty/unconfigured/ok, or
414 connected/unconfigured/ok, or
415 disconnected/unconfigured/ok, or
416 disconnected/unconfigured/unknown, or
417 disconnected/unconfigured/failed
418 disconnected/
420 unconfigured/
421 unknown -c disconnect error message, no state change
422 disconnected/
424 unconfigured/
425 failed any command error message, no state change
426 other than
427 -x commands
428 connected/
430 unconfigured/ok disk unplug error message and state:
431 empty/unconfigured/ok, or
432 disconnected/unconfigured/failed
433 connected/
435 unconfigured/ok -c configure connected/unconfigured/ok, or
436 connected/configured/ok, or
437 disconnected/unconfigured/ok, or
438 disconnected/unconfigured/failed
439 connected/
441 unconfigured/ok -c unconfigure error message, no state change
442 connected/
444 unconfigured/ok -c connect error message, no state change
445 connected/
447 unconfigured/ok -c disconnect disconnected/unconfigured/unknown, or
448 disconnected/unconfigured/failed
449 connected/
451 configured/ok disk unplug error message and state:
452 empty/unconfigured/ok, or
453 disconnected/unconfigured/failed
454 connected/
456 configured/ok -c configure error message, no state change
457 connected/
459 configured/ok -c unconfigure error message, if device cannot be
460 unconfigured, no state change, or
461 connected/unconfigured/ok, or
462 disconnected/unconfigured/ok, or
463 disconnected/unconfigured/failed
464 connected/
466 configured/ok -c connect error message, no state change
467 connected/
469 configured/ok -c disconnect error message, if device cannot be
470 unconfigured, no state change, or
471 disconnected/unconfigured/unknown, or
472 disconnected/unconfigured/failed
473
478 Example 1 Configuring a Disk
479 The following command configures a disk attached to SATA controller 0,
482 port 0:
483 example# cfgadm -c configure sata0/0
486 This command should be issued only when there is a device connected to
491 the SATA port.
492 Example 2 Unconfiguring a Disk
495 The following command unconfigures a disk attached to SATA controller
498 0, port 3:
499 example# cfgadm -c unconfigure sata0/3::dsk/c0t3d0
502 The device identifying string is shown when the attachment point recep‐
507 tacle state is "connected" and occupant state is "configured".
508 Example 3 Encountering a Mounted File System While Unconfiguring a Disk
511 The following command illustrates encountering a mounted file system
514 while unconfiguring a disk:
515 example# cfgadm -c unconfigure sata1/5::dsk/c01t35d0
518 The system responds with the following:
523 cfgadm: Component system is busy, try again: failed to offline:
526 /devices/pci@0,0/pci8086,244e@1e/pci1095,3124@1/sd@5,0
527 Resource Information
528 ------------------ --------------------------
529 /dev/dsk/c1t5d0s0 mounted filesystem "/mnt"
530
534 /usr/lib/cfgadm/sata.so.1 Hardware specific library for generic SATA
535 hot plugging.
536
539 See attributes(5) for descriptions of the following attributes:
540 ┌─────────────────────────────┬─────────────────────────────┐
545 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
546 ├─────────────────────────────┼─────────────────────────────┤
547 │Availability │SUNWcsl │
548 └─────────────────────────────┴─────────────────────────────┘
549
551 cfgadm(1M), config_admin(3CFGADM), libcfgadm(3LIB), attributes(5)
552
554 The emergency "sata_port_deactivate" operation is not supported on
555 ports with attached disks containing critical partitions such as root
556 (/), /usr, swap, or /var. The deactivate operation should not be
557 attempted on such ports. Incorrect usage can result in a system hang
558 and require a reboot.
559 Hotplugging operations are not supported by all SATA controllers.
562 If SATA connectors are the hot-pluggable type and the SATA controller
565 supports hotplugging, a SATA device can be hotplugged at any time. The
566 system detects the event and establishes the communication with the
567 device. The device has to be configured by the explicit "cfgadm -c con‐
568 figure ap_id" command.
569 If the SATA connectors are the hot-pluggable type and the SATA con‐
572 troller supports hotplugging, unplugging a device without unconfiguring
573 it may result in system hang or data loss. If a device is unconfigured
574 but receptacle state is not in a disconnected state, unplugging a
575 device from the SATA port will result in error message.
576
578 The connectors on some SATA devices do not conform to SATA hotplug
579 specifications. Performing hotplug operations on such devices can cause
580 damage to the SATA controller and/or the SATA device.
581SunOS 5.11 27 Aug 2007 cfgadm_sata(1M)