System Administration Commands cfgadmsata(1M)
NAME
cfgadmsata - SATA hardware-specific commands for cfgadm
SYNOPSIS
/usr/sbin/cfgadm [-f] [-y -n] [-v] [-o hardwareoptions]
-c function apid...
/usr/sbin/cfgadm [-f] [-y -n] [-v] [-o hardwareoptions]
-x hardwarefunction apid...
/usr/sbin/cfgadm [-v] [-a] [-s listingoptions]
[-o hardwareoptions] [-l [apid aptype]...]
/usr/sbin/cfgadm [-v] [-o harwareoptions] -t apid...
/usr/sbin/cfgadm [-v] [-o hardwareoptions] -h [apid]...
DESCRIPTION
The SATA hardware specific library,
/usr/lib/cfgadm/sata.so.1, provides the functionality for
SATA hot plugging through the cfgadm command. cfgadm
operates on attachment points, which are locations in the
system where hardware resources can be dynamically reconfig-
ured. See cfgadm(1M) for information regarding attachment
points.
Each SATA controller's and port multiplier's device port is
represented by an attachment point in the device tree. SATA
devices, connected and configured in the system are shown as
the attachment point name extension. The terms "attachment
point" and "SATA port" are used interchangeably in the fol-
lowing description.
Attachment points are named through apids. All the SATA
attachment points apid consist of a string in the following
form:
sataX/P[.M][::dsk/cXtYd0]
where
X is the SATA controller number
SunOS 5.11 Last change: 27 Aug 2007 1
System Administration Commands cfgadmsata(1M)
P is the SATA controller's device port number (0
to 31)
M 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 SATA controller's device
port.
dev/cXtYd0 identifies the attached SATA device
Y is a target number
In general, the device identifier is derived from the
corresponding logical link for the device in /dev. Because
only one LUN (LUN 0) is supported by the SATA device, the
"d" component of the device string will always have number 0
(zero).
For example, the logical apid of the device port 4 of the
port multiplier connected to the device port 5 of the SATA
controller 2 would be:
sata2/5.4
If the SATA disk or CD/DVD device is connected to this
attachment point, and the device is configured, the apid
would be:
sata2/5.4::dsk/c2t645d0
The cXtYd0 string identifying a device has one-to-one
correspondence to the device attachment point.
A simple listing of attachment points in the system will
include all SATA device ports and attached devices. For
example:
#cfgadm -l
ApId Type Receptacle Occupant Condition
sata0/0::dev/c0t0d0 disk connected configured ok
SunOS 5.11 Last change: 27 Aug 2007 2
System Administration Commands cfgadmsata(1M)
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
See cfgadm(1M)for more information regarding listing of
attachment points.
The receptacle state for attachment point at the SATA port
have the following meanings:
empty The SATA port is powered-on and enabled. No
device presence was detected on this port.
disconnected The SATA port is not enabled or the SATA
device presence was detected but no communi-
cation with the device was established, or
the port has failed.
connected The SATA device is detected on the port the
communication with the device is esta-
blished.
The occupant (device attached to the SATA port) state have
the following meanings:
configured The attached SATA device is configured and
ready to use by the operating system.
unconfigured No device is attached, or the SATA device
attached to the SATA port was not yet con-
figured. To configure it, run the command
"cfgadm -c configure apid".
SunOS 5.11 Last change: 27 Aug 2007 3
System Administration Commands cfgadmsata(1M)
The attachment point (SATA port) condition have the follow-
ing meanings:
ok The SATA port is powered-on and enabled, and is
ready for use.
failed The SATA 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.
unknown The SATA port is disabled and its condition is
unknown.
A "state table" is the combination of an attachment point
receptacle state, an occupant state, and an attachment point
(SATA port) condition. The valid states are:
empty/unconfigured/ok
The SATA port is enabled and active. No device presence
was detected.
disconnected/unconfigured/ok
The SATA port is enabled and a device presence was
detected but no communications with the device was esta-
blished.
disconnected/unconfigured/unknown
The SATA Port is disabled and its condition is unknown.
disconnected/unconfigured/failed
The SATA Port is disabled and unusable. The port was
disabled by the system due to a system-detected failure.
connected/unconfigured/ok
The SATA 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 OS.
SunOS 5.11 Last change: 27 Aug 2007 4
System Administration Commands cfgadmsata(1M)
connected/configured/ok
The device is present and configured, and is ready to
use by the OS.
OPTIONS
cfgadm defines several types of operations besides listing
(-l). These operations include testing, (-t), invoking con-
figuration state changes, (-c), invoking hardware specific
functions (-x), and obtaining configuration administration
help messages (-h).
-c function
The following generic functions are defined for the SATA
hardware specific library. For SATA port attachment
point, the following configuration state change opera-
tions are supported:
connect
Enable (activate) the SATA port and establish the
communication with an attached device. This opera-
tion implies powering-on the port if necessary.
disconnect
Unconfigure the attached device, if it is not
already unconfigured, and disable (deactivate) the
SATA port. A subsequent "connect" command enables
SATA port operation but does not bring a device to
the "configured" state.
For a SATA device attached to the SATA port following
state change operations are supported:
configure Configure new device for use by the
operating system if it is not already
configured. This command also implies
connect operation, if necessary.
unconfigure Unconfigure the device connected to the
SATA port if it is not already unconfig-
ured.
The configure and unconfigure operations cannot be used
for an attachment point where the port multiplier is
connected. Port multipliers are configured and unconfig-
ured automatically by the system. However, configure and
SunOS 5.11 Last change: 27 Aug 2007 5
System Administration Commands cfgadmsata(1M)
unconfigure operations apply to all SATA devices con-
nected to the port multiplier's device ports.
-f
Not supported.
-h apid
SATA specific help can be obtained by using the help
option with any SATA attachment point.
-l [-v]
The -l option works as described in cfgadm(1M). When
paired with the -v option, the "Information" field con-
tains the following SATA-specific information:
o Mfg: manufacturer string
o Product: product string
o No: product Serial Number
-o hardwareoptions
No hardware specific options are currently defined.
-s listingoptions
Attachment points of class SATA can be listed by using
the select suboption. See cfgadm(1M).
-t apid
Perform self-test of the SATA port, if supported by the
SATA controller. If a port self-test operation is not
supported by the SATA controller, an error message is
issued.
-x hardwarefunction
Perform hardware specific function.
Some of the following commands used on the SATA ports or
SunOS 5.11 Last change: 27 Aug 2007 6
System Administration Commands cfgadmsata(1M)
the SATA controller may affect any SATA devices that
have been attached, as noted. apid refers to SATA port
or the entire SATA controller, as noted. If the opera-
tion implies unconfiguring a device, but it cannot be
unconfigured (that is, the device contains a mounted
filesystem), an error message is issued and the opera-
tion is not performed. An error message will be also
issued if the SATA controller does not support specified
operation.
sataresetdevice apid
Reset the SATA device attached to apid SATA port.
The SATA port state does not change.
sataresetport apid
Reset the SATA port specified by apid. If a SATA
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 mul-
tiplier is connected to the SATA controller port,
the SATA devices attached to the port multiplier may
not be reset
sataresetall apid
Reset SATA controller specified by the controller
number part in apid and all attached devices and
re-enumerate all connected devices, including port
multipliers and devices connected to port multi-
pliers' device ports.
This operations implies unconfiguring all attached
devices prior to the operation. Any newly enumerated
devices will be left unconfigured.
sataportdeactivate apid
Force the deactivation of the port when all else
fails. This is meant as an emergency step; use with
caution.
sataportactivate apid
Force the activation of a port. This is meant for
emergency situations on a port which was deactivated
to recover from errors.
SunOS 5.11 Last change: 27 Aug 2007 7
System Administration Commands cfgadmsata(1M)
sataportselftest apid
Perform self-test operation on the SATA controller.
This operation implies unconfiguring all devices and
resetting the SATA controller.
-v
Execute in verbose mode.
The following Transitions table reports the state tran-
sitions resulting from the -c operations and hotplugging
actions:
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/
SunOS 5.11 Last change: 27 Aug 2007 8
System Administration Commands cfgadmsata(1M)
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
SunOS 5.11 Last change: 27 Aug 2007 9
System Administration Commands cfgadmsata(1M)
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
EXAMPLES
Example 1 Configuring a Disk
The following command configures a disk attached to SATA
controller 0, port 0:
example# cfgadm -c configure sata0/0
This command should be issued only when there is a device
connected to the SATA port.
Example 2 Unconfiguring a Disk
The following command unconfigures a disk attached to SATA
controller 0, port 3:
example# cfgadm -c unconfigure sata0/3::dsk/c0t3d0
SunOS 5.11 Last change: 27 Aug 2007 10
System Administration Commands cfgadmsata(1M)
The device identifying string is shown when the attachment
point receptacle state is "connected" and occupant state is
"configured".
Example 3 Encountering a Mounted File System While Unconfi-
guring a Disk
The following command illustrates encountering a mounted
file system while unconfiguring a disk:
example# cfgadm -c unconfigure sata1/5::dsk/c01t35d0
The system responds with the following:
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"
FILES
/usr/lib/cfgadm/sata.so.1 Hardware specific library for
generic SATA hot plugging.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWcsl
SEE ALSO
cfgadm(1M), configadmin(3CFGADM), libcfgadm(3LIB), attri-
butes(5)
SunOS 5.11 Last change: 27 Aug 2007 11
System Administration Commands cfgadmsata(1M)
NOTES
The emergency "sataportdeactivate" operation is not sup-
ported on ports with attached disks containing critical par-
titions such as root (/), /usr, swap, or /var. The deac-
tivate operation should not be attempted on such ports.
Incorrect usage can result in a system hang and require a
reboot.
Hotplugging operations are not supported by all SATA con-
trollers.
If SATA connectors are the hot-pluggable type and the SATA
controller supports hotplugging, a SATA device can be hot-
plugged at any time. The system detects the event and estab-
lishes the communication with the device. The device has to
be configured by the explicit "cfgadm -c configure apid"
command.
If the SATA connectors are the hot-pluggable type and the
SATA 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
SATA port will result in error message.
WARNINGS
The connectors on some SATA devices do not conform to SATA
hotplug specifications. Performing hotplug operations on
such devices can cause damage to the SATA controller and/or
the SATA device.
SunOS 5.11 Last change: 27 Aug 2007 12
|
