2 .\" Copyright (c) 2007 Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH CFGADM_SATA 1M "Aug 27, 2007"
8 cfgadm_sata \- SATA hardware-specific commands for cfgadm
12 \fB/usr/sbin/cfgadm\fR [\fB-f\fR] [\fB-y\fR | \fB-n\fR] [\fB-v\fR] [\fB-o\fR \fIhardware_options\fR]
13 \fB-c\fR \fIfunction\fR \fIap_id\fR...
18 \fB/usr/sbin/cfgadm\fR [\fB-f\fR] [\fB-y\fR | \fB-n\fR] [\fB-v\fR] [\fB-o\fR \fIhardware_options\fR]
19 \fB-x\fR \fIhardware_function\fR \fIap_id\fR...
24 \fB/usr/sbin/cfgadm\fR [\fB-v\fR] [\fB-a\fR] [\fB-s\fR \fIlisting_options\fR]
25 [\fB-o\fR \fIhardware_options\fR] [\fB-l\fR [\fIap_id\fR | \fIap_type\fR]...]
30 \fB/usr/sbin/cfgadm\fR [\fB-v\fR] [\fB-o\fR \fIharware_options\fR] \fB-t\fR \fIap_id\fR...
35 \fB/usr/sbin/cfgadm\fR [\fB-v\fR] [\fB-o\fR \fIhardware_options\fR] \fB-h\fR [\fIap_id\fR]...
41 The \fBSATA\fR hardware specific library, \fB/usr/lib/cfgadm/sata.so.1\fR,
42 provides the functionality for \fBSATA\fR hot plugging through the \fBcfgadm\fR
43 command. \fBcfgadm\fR operates on attachment points, which are locations in the
44 system where hardware resources can be dynamically reconfigured. See
45 \fBcfgadm\fR(1M) for information regarding attachment points.
48 Each \fBSATA\fR controller's and port multiplier's device port is represented
49 by an attachment point in the device tree. \fBSATA\fR devices, connected and
50 configured in the system are shown as the attachment point name extension. The
51 terms "attachment point" and "\fBSATA\fR port" are used interchangeably in the
52 following description.
55 Attachment points are named through \fBap_id\fRs. All the \fBSATA\fR attachment
56 points \fBap_id\fR consist of a string in the following form:
60 sataX/P[.M][::dsk/cXtYd0]
73 is the \fBSATA\fR controller number
82 is the \fBSATA\fR controller's device port number (0 to 31)
91 is the port multiplier's device port number (0 to 14) the port multiplier host
92 port number (15). It is used only when the port multiplier is attached to the
93 \fBSATA\fR controller's device port.
102 identifies the attached \fBSATA\fR device
116 In general, the device identifier is derived from the corresponding logical
117 link for the device in /\fIdev\fR. Because only one \fBLUN\fR (\fBLUN\fR 0) is
118 supported by the \fBSATA\fR device, the "d" component of the device string will
119 always have number 0 (zero).
122 For example, the logical \fBap_id\fR of the device port 4 of the port
123 multiplier connected to the device port 5 of the \fBSATA\fR controller 2 would
134 If the \fBSATA\fR disk or \fBCD\fR/\fBDVD\fR device is connected to this
135 attachment point, and the device is configured, the \fIap_id\fR would be:
139 sata2/5.4::dsk/c2t645d0
145 The \fIcXtYd0\fR string identifying a device has one-to-one correspondence to
146 the device attachment point.
149 A simple listing of attachment points in the system will include all \fBSATA\fR
150 device ports and attached devices. For example:
155 Ap_Id Type Receptacle Occupant Condition
156 sata0/0::dev/c0t0d0 disk connected configured ok
157 sata0/1::dev/c0t1d0 disk connected configured ok
158 sata0/2::dev/c0t2d0 cd-dvd connected configured ok
159 sata0/3 sata-port empty unconfigured ok
160 sata1/0 sata-port disconnected unconfigured unknown
161 sata1/1 sata port disconnected unconfigured unknown
162 sata1/2 sata port empty unconfigured ok
163 sata1/3.15 sata-pmult connected configured ok
164 sata1/3.0::dev/c0t512d0 disk connected configured ok
165 sata1/3.1 sata-port empty unconfigured ok
166 sata1/3.2 sata-port empty unconfigured ok
167 sata1/3.3 sata-port empty unconfigured ok
168 usb0/1 unknown empty unconfigured ok
169 usb0/2 unknown empty unconfigured ok
176 See \fBcfgadm\fR(1M)for more information regarding listing of attachment
180 The receptacle state for attachment point at the \fBSATA\fR port have the
188 The \fBSATA\fR port is powered-on and enabled. No device presence was detected
198 The \fBSATA\fR port is not enabled or the \fBSATA\fR device presence was
199 detected but no communication with the device was established, or the port has
209 The \fBSATA\fR device is detected on the port the communication with the device
215 The occupant (device attached to the \fBSATA\fR port) state have the following
223 The attached \fBSATA\fR device is configured and ready to use by the operating
233 No device is attached, or the \fBSATA\fR device attached to the \fBSATA\fR port
234 was not yet configured. To configure it, run the command "\fBcfgadm -c
240 The attachment point (\fBSATA\fR port) condition have the following meanings:
247 The \fBSATA\fR port is powered-on and enabled, and is ready for use.
256 The \fBSATA\fR port failed. It may be disabled and/or powered-off by the
257 system. It is unusable and its condition is unknown. It may be due to the
267 The \fBSATA\fR port is disabled and its condition is unknown.
272 A "state table" is the combination of an attachment point receptacle state, an
273 occupant state, and an attachment point (\fBSATA\fR port) condition. The valid
278 \fBempty/unconfigured/ok\fR
282 The \fBSATA\fR port is enabled and active. No device presence was detected.
288 \fBdisconnected/unconfigured/ok\fR
292 The \fBSATA\fR port is enabled and a device presence was detected but no
293 communications with the device was established.
299 \fBdisconnected/unconfigured/unknown\fR
303 The \fBSATA\fR Port is disabled and its condition is unknown.
309 \fBdisconnected/unconfigured/failed\fR
313 The \fBSATA\fR Port is disabled and unusable. The port was disabled by the
314 system due to a system-detected failure.
320 \fBconnected/unconfigured/ok\fR
324 The \fBSATA\fR Port is enabled and active. A device presence was detected and
325 the communication with a device was established. The device is not configured
326 to be used by the \fBOS\fR.
332 \fBconnected/configured/ok\fR
336 The device is present and configured, and is ready to use by the \fBOS\fR.
342 \fBcfgadm\fR defines several types of operations besides listing (\fB-l\fR).
343 These operations include testing, (\fB-t\fR), invoking configuration state
344 changes, (\fB-c\fR), invoking hardware specific functions (\fB-x\fR), and
345 obtaining configuration administration help messages (\fB-h\fR).
349 \fB\fB-c\fR \fIfunction\fR\fR
353 The following generic \fIfunction\fRs are defined for the \fBSATA\fR hardware
354 specific library. For \fBSATA\fR port attachment point, the following
355 configuration state change operations are supported:
363 Enable (activate) the \fBSATA\fR port and establish the communication with an
364 attached device. This operation implies powering-on the port if necessary.
374 Unconfigure the attached device, if it is not already unconfigured, and disable
375 (deactivate) the \fBSATA\fR port. A subsequent "\fBconnect\fR" command enables
376 \fBSATA\fR port operation but does not bring a device to the "configured"
380 For a \fBSATA\fR device attached to the \fBSATA\fR port following state change
381 operations are supported:
388 Configure new device for use by the operating system if it is not already
389 configured. This command also implies connect operation, if necessary.
398 Unconfigure the device connected to the \fBSATA\fR port if it is not already
402 The \fBconfigure\fR and \fBunconfigure\fR operations cannot be used for an
403 attachment point where the port multiplier is connected. Port multipliers are
404 configured and unconfigured automatically by the system. However, configure and
405 unconfigure operations apply to all \fBSATA\fR devices connected to the port
406 multiplier's device ports.
422 \fB\fB-h\fR \fIap_id\fR\fR
426 \fBSATA\fR specific help can be obtained by using the help option with any
427 \fBSATA\fR attachment point.
433 \fB\fB-l\fR [\fB-v\fR]\fR
437 The \fB-l\fR option works as described in \fBcfgadm\fR(1M). When paired with
438 the \fB-v\fR option, the "Information" field contains the following
439 \fBSATA\fR-specific information:
444 Mfg: manufacturer string
450 Product: product string
456 No: product Serial Number
463 \fB\fB-o\fR \fIhardware_options\fR\fR
467 No hardware specific options are currently defined.
473 \fB\fB-s\fR \fIlisting_options\fR\fR
477 Attachment points of class \fBSATA\fR can be listed by using the select
478 suboption. See \fBcfgadm\fR(1M).
484 \fB\fB-t\fR \fIap_id\fR\fR
488 Perform self-test of the \fBSATA\fR port, if supported by the \fBSATA\fR
489 controller. If a port self-test operation is not supported by the \fBSATA\fR
490 controller, an error message is issued.
496 \fB\fB-x\fR \fIhardware_function\fR\fR
500 Perform hardware specific function.
502 Some of the following commands used on the \fBSATA\fR ports or the \fBSATA\fR
503 controller may affect any \fBSATA\fR devices that have been attached, as noted.
504 \fBap_id\fR refers to \fBSATA\fR port or the entire \fBSATA\fR controller, as
505 noted. If the operation implies unconfiguring a device, but it cannot be
506 unconfigured (that is, the device contains a mounted filesystem), an error
507 message is issued and the operation is not performed. An error message will be
508 also issued if the \fBSATA\fR controller does not support specified operation.
512 \fBsata_reset_device ap_id\fR
516 Reset the \fBSATA\fR device attached to \fBap_id\fR \fBSATA\fR port. The
517 \fBSATA\fR port state does not change.
523 \fBsata_reset_port ap_id\fR
527 Reset the \fBSATA\fR port specified by \fBap_id\fR. If a \fBSATA\fR device is
528 attached to the port, it is also reset. This operation may be also performed on
529 the port to which a port multiplier is connected. If a port multiplier is
530 connected to the \fBSATA\fR controller port, the \fBSATA\fR devices attached to
531 the port multiplier may not be reset
537 \fBsata_reset_all ap_id\fR
541 Reset \fBSATA\fR controller specified by the controller number part in
542 \fBap_id\fR and all attached devices and re-enumerate all connected devices,
543 including port multipliers and devices connected to port multipliers' device
546 This operations implies unconfiguring all attached devices prior to the
547 operation. Any newly enumerated devices will be left unconfigured.
553 \fBsata_port_deactivate ap_id\fR
557 Force the deactivation of the port when all else fails. This is meant as an
558 emergency step; use with caution.
564 \fBsata_port_activate ap_id\fR
568 Force the activation of a port. This is meant for emergency situations on a
569 port which was deactivated to recover from errors.
575 \fBsata_port_self_test ap_id\fR
579 Perform self-test operation on the \fBSATA\fR controller. This operation
580 implies unconfiguring all devices and resetting the \fBSATA\fR controller.
592 Execute in verbose mode.
594 The following Transitions table reports the state transitions resulting from
595 the \fB-c\fR operations and hotplugging actions:
599 current state operation possible new state
600 ------------- --------- ------------------
602 unconfigured/ok device plug-in connected/unconfigured/ok, or
603 disconnected/unconfigured/ok, or
604 disconnected/unconfigured/failed
607 unconfigured/ok -c unconfigure error message, no state change
610 unconfigured/ok -c configure error message, no state change
613 unconfigured/ok -c connect error message, no state change
616 unconfigured/ok -c disconnect disconnected/unconfigured/unknown, or
617 disconnected/unconfigured/failed
620 unconfigured/ok device unplug no state change
623 unconfigured/ok -c unconfigure error message, no state change
626 unconfigured/ok -c configure error message, no state change
629 unconfigured/ok -c connect error message, no state change
632 unconfigured/ok -c disconnect error message, no state change
637 (no disk plugged) -c configure error message, state change to
638 empty/unconfigured/ok, or
639 disconnected/unconfigured/failed
643 unknown -c configure state change to
644 (disk plugged) connected/configured/ok or,
645 connected/unconfigured/ok, or
646 disconnected/unconfigured/failed and
647 possible error message
651 unknown -c connect empty/unconfigured/ok, or
652 connected/unconfigured/ok, or
653 disconnected/unconfigured/ok, or
654 disconnected/unconfigured/unknown, or
655 disconnected/unconfigured/failed
659 unknown -c disconnect error message, no state change
663 failed any command error message, no state change
668 unconfigured/ok disk unplug error message and state:
669 empty/unconfigured/ok, or
670 disconnected/unconfigured/failed
673 unconfigured/ok -c configure connected/unconfigured/ok, or
674 connected/configured/ok, or
675 disconnected/unconfigured/ok, or
676 disconnected/unconfigured/failed
679 unconfigured/ok -c unconfigure error message, no state change
682 unconfigured/ok -c connect error message, no state change
685 unconfigured/ok -c disconnect disconnected/unconfigured/unknown, or
686 disconnected/unconfigured/failed
689 configured/ok disk unplug error message and state:
690 empty/unconfigured/ok, or
691 disconnected/unconfigured/failed
694 configured/ok -c configure error message, no state change
697 configured/ok -c unconfigure error message, if device cannot be
698 unconfigured, no state change, or
699 connected/unconfigured/ok, or
700 disconnected/unconfigured/ok, or
701 disconnected/unconfigured/failed
704 configured/ok -c connect error message, no state change
707 configured/ok -c disconnect error message, if device cannot be
708 unconfigured, no state change, or
709 disconnected/unconfigured/unknown, or
710 disconnected/unconfigured/failed
719 \fBExample 1 \fRConfiguring a Disk
722 The following command configures a disk attached to \fBSATA\fR controller 0,
728 example# \fBcfgadm -c configure sata0/0\fR
735 This command should be issued only when there is a device connected to the
739 \fBExample 2 \fRUnconfiguring a Disk
742 The following command unconfigures a disk attached to \fBSATA\fR controller 0,
748 example# \fBcfgadm -c unconfigure sata0/3::dsk/c0t3d0\fR
755 The device identifying string is shown when the attachment point receptacle
756 state is "connected" and occupant state is "configured".
759 \fBExample 3 \fREncountering a Mounted File System While Unconfiguring a Disk
762 The following command illustrates encountering a mounted file system while
763 unconfiguring a disk:
768 example# \fBcfgadm -c unconfigure sata1/5::dsk/c01t35d0\fR
775 The system responds with the following:
780 cfgadm: Component system is busy, try again: failed to offline:
781 /devices/pci@0,0/pci8086,244e@1e/pci1095,3124@1/sd@5,0
783 ------------------ --------------------------
784 /dev/dsk/c1t5d0s0 mounted filesystem "/mnt"
793 \fB/usr/lib/cfgadm/sata.so.1\fR
796 Hardware specific library for generic \fBSATA\fR hot plugging.
802 \fBcfgadm\fR(1M), \fBconfig_admin\fR(3CFGADM), \fBlibcfgadm\fR(3LIB),
807 The emergency "sata_port_deactivate" operation is not supported on ports with
808 attached disks containing critical partitions such as root (/), /usr, swap, or
809 /var. The deactivate operation should not be attempted on such ports. Incorrect
810 usage can result in a system hang and require a reboot.
813 Hotplugging operations are not supported by all \fBSATA\fR controllers.
816 If \fBSATA\fR connectors are the hot-pluggable type and the \fBSATA\fR
817 controller supports hotplugging, a \fBSATA\fR device can be hotplugged at any
818 time. The system detects the event and establishes the communication with the
819 device. The device has to be configured by the explicit "\fBcfgadm -c configure
823 If the \fBSATA\fR connectors are the hot-pluggable type and the \fBSATA\fR
824 controller supports hotplugging, unplugging a device without unconfiguring it
825 may result in system hang or data loss. If a device is unconfigured but
826 receptacle state is not in a disconnected state, unplugging a device from the
827 \fBSATA\fR port will result in error message.
831 The connectors on some \fBSATA\fR devices do not conform to \fBSATA\fR hotplug
832 specifications. Performing hotplug operations on such devices can cause damage
833 to the \fBSATA\fR controller and/or the \fBSATA\fR device.