'\" te
.\" Copyright (c) 2007 Sun Microsystems, Inc. All Rights Reserved.
.\" 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.
.\" 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.
.\" 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]
.TH CFGADM_SATA 1M "Aug 27, 2007"
.SH NAME
cfgadm_sata \- SATA hardware-specific commands for cfgadm
.SH SYNOPSIS
.LP
.nf
\fB/usr/sbin/cfgadm\fR [\fB-f\fR] [\fB-y\fR | \fB-n\fR] [\fB-v\fR] [\fB-o\fR \fIhardware_options\fR]
     \fB-c\fR \fIfunction\fR \fIap_id\fR...
.fi

.LP
.nf
\fB/usr/sbin/cfgadm\fR [\fB-f\fR] [\fB-y\fR | \fB-n\fR] [\fB-v\fR] [\fB-o\fR \fIhardware_options\fR]
     \fB-x\fR \fIhardware_function\fR \fIap_id\fR...
.fi

.LP
.nf
\fB/usr/sbin/cfgadm\fR [\fB-v\fR] [\fB-a\fR] [\fB-s\fR \fIlisting_options\fR]
     [\fB-o\fR \fIhardware_options\fR] [\fB-l\fR [\fIap_id\fR | \fIap_type\fR]...]
.fi

.LP
.nf
\fB/usr/sbin/cfgadm\fR [\fB-v\fR] [\fB-o\fR \fIharware_options\fR] \fB-t\fR \fIap_id\fR...
.fi

.LP
.nf
\fB/usr/sbin/cfgadm\fR [\fB-v\fR] [\fB-o\fR \fIhardware_options\fR] \fB-h\fR [\fIap_id\fR]...
.fi

.SH DESCRIPTION
.sp
.LP
The \fBSATA\fR hardware specific library, \fB/usr/lib/cfgadm/sata.so.1\fR,
provides the functionality for \fBSATA\fR hot plugging through the \fBcfgadm\fR
command. \fBcfgadm\fR operates on attachment points, which are locations in the
system where hardware resources can be dynamically reconfigured. See
\fBcfgadm\fR(1M) for information regarding attachment points.
.sp
.LP
Each \fBSATA\fR controller's and port multiplier's device port is represented
by an attachment point in the device tree. \fBSATA\fR devices, connected and
configured in the system are shown as the attachment point name extension. The
terms "attachment point" and "\fBSATA\fR port" are used interchangeably in the
following description.
.sp
.LP
Attachment points are named through \fBap_id\fRs. All the \fBSATA\fR attachment
points \fBap_id\fR consist of a string in the following form:
.sp
.in +2
.nf
sataX/P[.M][::dsk/cXtYd0]
.fi
.in -2

.sp
.LP
where
.sp
.ne 2
.na
\fBX\fR
.ad
.RS 14n
is the \fBSATA\fR controller number
.RE

.sp
.ne 2
.na
\fBP\fR
.ad
.RS 14n
is the \fBSATA\fR controller's device port number (0 to 31)
.RE

.sp
.ne 2
.na
\fBM\fR
.ad
.RS 14n
is the port multiplier's device port number (0 to 14) the port multiplier host
port number (15). It is used only when the port multiplier is attached to the
\fBSATA\fR controller's device port.
.RE

.sp
.ne 2
.na
\fBdev/cXtYd0\fR
.ad
.RS 14n
identifies the attached \fBSATA\fR device
.RE

.sp
.ne 2
.na
\fBY\fR
.ad
.RS 14n
is a target number
.RE

.sp
.LP
In general, the device identifier is derived from the corresponding logical
link for the device in /\fIdev\fR. Because only one \fBLUN\fR (\fBLUN\fR 0) is
supported by the \fBSATA\fR device, the "d" component of the device string will
always have number 0 (zero).
.sp
.LP
For example, the logical \fBap_id\fR of the device port 4 of the port
multiplier connected to the device port 5 of the \fBSATA\fR controller 2 would
be:
.sp
.in +2
.nf
sata2/5.4
.fi
.in -2

.sp
.LP
If the \fBSATA\fR disk or \fBCD\fR/\fBDVD\fR device is connected to this
attachment point, and the device is configured, the \fIap_id\fR would be:
.sp
.in +2
.nf
sata2/5.4::dsk/c2t645d0
.fi
.in -2

.sp
.LP
The \fIcXtYd0\fR string identifying a device has one-to-one correspondence to
the device attachment point.
.sp
.LP
A simple listing of attachment points in the system will include all \fBSATA\fR
device ports and attached devices. For example:
.sp
.in +2
.nf
#\fBcfgadm -l\fR
Ap_Id                     Type        Receptacle   Occupant     Condition
  sata0/0::dev/c0t0d0     disk        connected    configured   ok
  sata0/1::dev/c0t1d0     disk        connected    configured   ok
  sata0/2::dev/c0t2d0     cd-dvd      connected    configured   ok
  sata0/3                 sata-port   empty        unconfigured ok
  sata1/0                 sata-port   disconnected unconfigured unknown
  sata1/1                 sata port   disconnected unconfigured unknown
  sata1/2                 sata port   empty        unconfigured ok
  sata1/3.15              sata-pmult  connected    configured   ok
  sata1/3.0::dev/c0t512d0 disk        connected    configured   ok
  sata1/3.1               sata-port   empty        unconfigured ok
  sata1/3.2               sata-port   empty        unconfigured ok
  sata1/3.3               sata-port   empty        unconfigured ok
  usb0/1                  unknown     empty        unconfigured ok
  usb0/2                  unknown     empty        unconfigured ok
.fi
.in -2
.sp

.sp
.LP
See \fBcfgadm\fR(1M)for more information regarding listing of attachment
points.
.sp
.LP
The receptacle state for attachment point at the \fBSATA\fR port have the
following meanings:
.sp
.ne 2
.na
\fBempty\fR
.ad
.RS 16n
The \fBSATA\fR port is powered-on and enabled. No device presence was detected
on this port.
.RE

.sp
.ne 2
.na
\fBdisconnected\fR
.ad
.RS 16n
The \fBSATA\fR port is not enabled or the \fBSATA\fR device presence was
detected but no communication with the device was established, or the port has
failed.
.RE

.sp
.ne 2
.na
\fBconnected\fR
.ad
.RS 16n
The \fBSATA\fR device is detected on the port the communication with the device
is established.
.RE

.sp
.LP
The occupant (device attached to the \fBSATA\fR port) state have the following
meanings:
.sp
.ne 2
.na
\fBconfigured\fR
.ad
.RS 16n
The attached \fBSATA\fR device is configured and ready to use by the operating
system.
.RE

.sp
.ne 2
.na
\fBunconfigured\fR
.ad
.RS 16n
No device is attached, or the \fBSATA\fR device attached to the \fBSATA\fR port
was not yet configured. To configure it, run the command "\fBcfgadm -c
configure ap_id\fR".
.RE

.sp
.LP
The attachment point (\fBSATA\fR port) condition have the following meanings:
.sp
.ne 2
.na
\fBok\fR
.ad
.RS 11n
The \fBSATA\fR port is powered-on and enabled, and is ready for use.
.RE

.sp
.ne 2
.na
\fBfailed\fR
.ad
.RS 11n
The \fBSATA\fR port failed. It may be disabled and/or powered-off by the
system. It is unusable and its condition is unknown. It may be due to the
device plugged-in.
.RE

.sp
.ne 2
.na
\fBunknown\fR
.ad
.RS 11n
The \fBSATA\fR port is disabled and its condition is unknown.
.RE

.sp
.LP
A "state table" is the combination of an attachment point receptacle state, an
occupant state, and an attachment point (\fBSATA\fR port) condition. The valid
states are:
.sp
.ne 2
.na
\fBempty/unconfigured/ok\fR
.ad
.sp .6
.RS 4n
The \fBSATA\fR port is enabled and active. No device presence was detected.
.RE

.sp
.ne 2
.na
\fBdisconnected/unconfigured/ok\fR
.ad
.sp .6
.RS 4n
The \fBSATA\fR port is enabled and a device presence was detected but no
communications with the device was established.
.RE

.sp
.ne 2
.na
\fBdisconnected/unconfigured/unknown\fR
.ad
.sp .6
.RS 4n
The \fBSATA\fR Port is disabled and its condition is unknown.
.RE

.sp
.ne 2
.na
\fBdisconnected/unconfigured/failed\fR
.ad
.sp .6
.RS 4n
The \fBSATA\fR Port is disabled and unusable. The port was disabled by the
system due to a system-detected failure.
.RE

.sp
.ne 2
.na
\fBconnected/unconfigured/ok\fR
.ad
.sp .6
.RS 4n
The \fBSATA\fR Port is enabled and active. A device presence was detected and
the communication with a device was established. The device is not configured
to be used by the \fBOS\fR.
.RE

.sp
.ne 2
.na
\fBconnected/configured/ok\fR
.ad
.sp .6
.RS 4n
The device is present and configured, and is ready to use by the \fBOS\fR.
.RE

.SH OPTIONS
.sp
.LP
\fBcfgadm\fR defines several types of operations besides listing (\fB-l\fR).
These operations include testing, (\fB-t\fR), invoking configuration state
changes, (\fB-c\fR), invoking hardware specific functions (\fB-x\fR), and
obtaining configuration administration help messages (\fB-h\fR).
.sp
.ne 2
.na
\fB\fB-c\fR \fIfunction\fR\fR
.ad
.sp .6
.RS 4n
The following generic \fIfunction\fRs are defined for the \fBSATA\fR hardware
specific library. For \fBSATA\fR port attachment point, the following
configuration state change operations are supported:
.sp
.ne 2
.na
\fBconnect\fR
.ad
.sp .6
.RS 4n
Enable (activate) the \fBSATA\fR port and establish the communication with an
attached device. This operation implies powering-on the port if necessary.
.RE

.sp
.ne 2
.na
\fBdisconnect\fR
.ad
.sp .6
.RS 4n
Unconfigure the attached device, if it is not already unconfigured, and disable
(deactivate) the \fBSATA\fR port. A subsequent "\fBconnect\fR" command enables
\fBSATA\fR port operation but does not bring a device to the "configured"
state.
.RE

For a \fBSATA\fR device attached to the \fBSATA\fR port following state change
operations are supported:
.sp
.ne 2
.na
\fBconfigure\fR
.ad
.RS 15n
Configure new device for use by the operating system if it is not already
configured. This command also implies connect operation, if necessary.
.RE

.sp
.ne 2
.na
\fBunconfigure\fR
.ad
.RS 15n
Unconfigure the device connected to the \fBSATA\fR port if it is not already
unconfigured.
.RE

The \fBconfigure\fR and \fBunconfigure\fR operations cannot be used for an
attachment point where the port multiplier is connected. Port multipliers are
configured and unconfigured automatically by the system. However, configure and
unconfigure operations apply to all \fBSATA\fR devices connected to the port
multiplier's device ports.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.sp .6
.RS 4n
Not supported.
.RE

.sp
.ne 2
.na
\fB\fB-h\fR \fIap_id\fR\fR
.ad
.sp .6
.RS 4n
\fBSATA\fR specific help can be obtained by using the help option with any
\fBSATA\fR attachment point.
.RE

.sp
.ne 2
.na
\fB\fB-l\fR [\fB-v\fR]\fR
.ad
.sp .6
.RS 4n
The \fB-l\fR option works as described in \fBcfgadm\fR(1M). When paired with
the \fB-v\fR option, the "Information" field contains the following
\fBSATA\fR-specific information:
.RS +4
.TP
.ie t \(bu
.el o
Mfg: manufacturer string
.RE
.RS +4
.TP
.ie t \(bu
.el o
Product: product string
.RE
.RS +4
.TP
.ie t \(bu
.el o
No: product Serial Number
.RE
.RE

.sp
.ne 2
.na
\fB\fB-o\fR \fIhardware_options\fR\fR
.ad
.sp .6
.RS 4n
No hardware specific options are currently defined.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR \fIlisting_options\fR\fR
.ad
.sp .6
.RS 4n
Attachment points of class \fBSATA\fR can be listed by using the select
suboption. See \fBcfgadm\fR(1M).
.RE

.sp
.ne 2
.na
\fB\fB-t\fR \fIap_id\fR\fR
.ad
.sp .6
.RS 4n
Perform self-test of the \fBSATA\fR port, if supported by the \fBSATA\fR
controller. If a port self-test operation is not supported by the \fBSATA\fR
controller, an error message is issued.
.RE

.sp
.ne 2
.na
\fB\fB-x\fR \fIhardware_function\fR\fR
.ad
.sp .6
.RS 4n
Perform hardware specific function.
.sp
Some of the following commands used on the \fBSATA\fR ports or the \fBSATA\fR
controller may affect any \fBSATA\fR devices that have been attached, as noted.
\fBap_id\fR refers to \fBSATA\fR port or the entire \fBSATA\fR controller, as
noted. If the operation implies unconfiguring a device, but it cannot be
unconfigured (that is, the device contains a mounted filesystem), an error
message is issued and the operation is not performed. An error message will be
also issued if the \fBSATA\fR controller does not support specified operation.
.sp
.ne 2
.na
\fBsata_reset_device ap_id\fR
.ad
.sp .6
.RS 4n
Reset the \fBSATA\fR device attached to \fBap_id\fR \fBSATA\fR port. The
\fBSATA\fR port state does not change.
.RE

.sp
.ne 2
.na
\fBsata_reset_port ap_id\fR
.ad
.sp .6
.RS 4n
Reset the \fBSATA\fR port specified by \fBap_id\fR. If a \fBSATA\fR device is
attached to the port, it is also reset. This operation may be also performed on
the port to which a port multiplier is connected. If a port multiplier is
connected to the \fBSATA\fR controller port, the \fBSATA\fR devices attached to
the port multiplier may not be reset
.RE

.sp
.ne 2
.na
\fBsata_reset_all ap_id\fR
.ad
.sp .6
.RS 4n
Reset \fBSATA\fR controller specified by the controller number part in
\fBap_id\fR and all attached devices and re-enumerate all connected devices,
including port multipliers and devices connected to port multipliers' device
ports.
.sp
This operations implies unconfiguring all attached devices prior to the
operation. Any newly enumerated devices will be left unconfigured.
.RE

.sp
.ne 2
.na
\fBsata_port_deactivate ap_id\fR
.ad
.sp .6
.RS 4n
Force the deactivation of the port when all else fails. This is meant as an
emergency step; use with caution.
.RE

.sp
.ne 2
.na
\fBsata_port_activate ap_id\fR
.ad
.sp .6
.RS 4n
Force the activation of a port. This is meant for emergency situations on a
port which was deactivated to recover from errors.
.RE

.sp
.ne 2
.na
\fBsata_port_self_test ap_id\fR
.ad
.sp .6
.RS 4n
Perform self-test operation on the \fBSATA\fR controller. This operation
implies unconfiguring all devices and resetting the \fBSATA\fR controller.
.RE

.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.sp .6
.RS 4n
Execute in verbose mode.
.sp
The following Transitions table reports the state transitions resulting from
the \fB-c\fR operations and hotplugging actions:
.sp
.in +2
.nf
current state     operation       possible new state
-------------     ---------       ------------------
empty/
unconfigured/ok   device plug-in  connected/unconfigured/ok, or
                                  disconnected/unconfigured/ok, or
                                  disconnected/unconfigured/failed

empty/
unconfigured/ok   -c unconfigure  error message, no state change

empty/
unconfigured/ok   -c configure    error message, no state change

empty/
unconfigured/ok   -c connect      error message, no state change

empty/
unconfigured/ok   -c disconnect   disconnected/unconfigured/unknown, or
                                  disconnected/unconfigured/failed

disconnected/
unconfigured/ok   device unplug   no state change

disconnected/
unconfigured/ok   -c unconfigure  error message, no state change

disconnected/
unconfigured/ok   -c configure    error message, no state change

disconnected/
unconfigured/ok   -c connect      error message, no state change

disconnected/
unconfigured/ok   -c disconnect   error message, no state change

disconnected/
unconfigured/
unknown
(no disk plugged) -c configure    error message, state change to
                                  empty/unconfigured/ok, or
                                  disconnected/unconfigured/failed

disconnected/
unconfigured/
unknown           -c configure    state change to
(disk plugged)                    connected/configured/ok or,
                                  connected/unconfigured/ok, or
                                  disconnected/unconfigured/failed and
                                  possible error message

disconnected/
unconfigured/
unknown           -c connect      empty/unconfigured/ok, or
                                  connected/unconfigured/ok, or
                                  disconnected/unconfigured/ok, or
                                  disconnected/unconfigured/unknown, or
                                  disconnected/unconfigured/failed

disconnected/
unconfigured/
unknown           -c disconnect   error message, no state change

disconnected/
unconfigured/
failed            any command     error message, no state change
                  other than
                  -x commands

connected/
unconfigured/ok   disk unplug     error message and state:
                                  empty/unconfigured/ok, or
                                  disconnected/unconfigured/failed

connected/
unconfigured/ok   -c configure    connected/unconfigured/ok, or
                                  connected/configured/ok, or
                                  disconnected/unconfigured/ok, or
                                  disconnected/unconfigured/failed

connected/
unconfigured/ok   -c unconfigure  error message, no state change

connected/
unconfigured/ok   -c connect      error message, no state change

connected/
unconfigured/ok   -c disconnect   disconnected/unconfigured/unknown, or
                                  disconnected/unconfigured/failed

connected/
configured/ok     disk unplug     error message and state:
                                  empty/unconfigured/ok, or
                                  disconnected/unconfigured/failed

connected/
configured/ok     -c configure    error message, no state change

connected/
configured/ok     -c unconfigure  error message, if device cannot be
                                  unconfigured, no state change, or
                                  connected/unconfigured/ok, or
                                  disconnected/unconfigured/ok, or
                                  disconnected/unconfigured/failed

connected/
configured/ok     -c connect      error message, no state change

connected/
configured/ok     -c disconnect   error message, if device cannot be
                                  unconfigured, no state change, or
                                  disconnected/unconfigured/unknown, or
                                  disconnected/unconfigured/failed
.fi
.in -2
.sp

.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRConfiguring a Disk
.sp
.LP
The following command configures a disk attached to \fBSATA\fR controller 0,
port 0:

.sp
.in +2
.nf
example# \fBcfgadm -c configure sata0/0\fR
.fi
.in -2
.sp

.sp
.LP
This command should be issued only when there is a device connected to the
\fBSATA\fR port.

.LP
\fBExample 2 \fRUnconfiguring a Disk
.sp
.LP
The following command unconfigures a disk attached to \fBSATA\fR controller 0,
port 3:

.sp
.in +2
.nf
example# \fBcfgadm -c unconfigure sata0/3::dsk/c0t3d0\fR
.fi
.in -2
.sp

.sp
.LP
The device identifying string is shown when the attachment point receptacle
state is "connected" and occupant state is "configured".

.LP
\fBExample 3 \fREncountering a Mounted File System While Unconfiguring a Disk
.sp
.LP
The following command illustrates encountering a mounted file system while
unconfiguring a disk:

.sp
.in +2
.nf
example# \fBcfgadm -c unconfigure sata1/5::dsk/c01t35d0\fR
.fi
.in -2
.sp

.sp
.LP
The system responds with the following:

.sp
.in +2
.nf
cfgadm: Component system is busy, try again: failed to offline:
/devices/pci@0,0/pci8086,244e@1e/pci1095,3124@1/sd@5,0
     Resource              Information
------------------  --------------------------
/dev/dsk/c1t5d0s0   mounted filesystem "/mnt"
.fi
.in -2
.sp

.SH FILES
.sp
.ne 2
.na
\fB/usr/lib/cfgadm/sata.so.1\fR
.ad
.RS 29n
Hardware specific library for generic \fBSATA\fR hot plugging.
.RE

.SH SEE ALSO
.sp
.LP
\fBcfgadm\fR(1M), \fBconfig_admin\fR(3CFGADM), \fBlibcfgadm\fR(3LIB),
\fBattributes\fR(5)
.SH NOTES
.sp
.LP
The emergency "sata_port_deactivate" operation is not supported on ports with
attached disks containing critical partitions such as root (/), /usr, swap, or
/var. The deactivate operation should not be attempted on such ports. Incorrect
usage can result in a system hang and require a reboot.
.sp
.LP
Hotplugging operations are not supported by all \fBSATA\fR controllers.
.sp
.LP
If \fBSATA\fR connectors are the hot-pluggable type and the \fBSATA\fR
controller supports hotplugging, a \fBSATA\fR device can be hotplugged at any
time. The system detects the event and establishes the communication with the
device. The device has to be configured by the explicit "\fBcfgadm -c configure
ap_id\fR" command.
.sp
.LP
If the \fBSATA\fR connectors are the hot-pluggable type and the \fBSATA\fR
controller supports hotplugging, unplugging a device without unconfiguring it
may result in system hang or data loss. If a device is unconfigured but
receptacle state is not in a disconnected state, unplugging a device from the
\fBSATA\fR port will result in error message.
.SH WARNINGS
.sp
.LP
The connectors on some \fBSATA\fR devices do not conform to \fBSATA\fR hotplug
specifications. Performing hotplug operations on such devices can cause damage
to the \fBSATA\fR controller and/or the \fBSATA\fR device.