cfgadm_sata(1M) 					  System Administration Commands					   cfgadm_sata(1M)

NAME

       cfgadm_sata - SATA hardware-specific commands for cfgadm

SYNOPSIS

       /usr/sbin/cfgadm [-f] [-y | -n] [-v] [-o hardware_options]
	    -c function ap_id...

       /usr/sbin/cfgadm [-f] [-y | -n] [-v] [-o hardware_options]
	    -x hardware_function ap_id...

       /usr/sbin/cfgadm [-v] [-a] [-s listing_options]
	    [-o hardware_options] [-l [ap_id | ap_type]...]

       /usr/sbin/cfgadm [-v] [-o harware_options] -t ap_id...

       /usr/sbin/cfgadm [-v] [-o hardware_options] -h [ap_id]...

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	reconfigured.  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 inter-
       changeably in the following description.

       Attachment points are named through ap_ids. All the SATA attachment points ap_id consist of a string in the following form:

	 sataX/P[.M][::dsk/cXtYd0]

       where

       X	     is the SATA controller number

       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 ap_id 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 ap_id 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
	 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

       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 communication 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 established.

       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 configured. To configure it, run the com-
		       mand "cfgadm -c configure ap_id".

       The attachment point (SATA port) condition have the following 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) condi-
       tion. 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 established.

       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.

       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 configuration 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  con-
	   figuration state change operations are supported:

	   connect

	       Enable  (activate)  the	SATA  port and establish the communication with an attached device. This operation 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 unconfigured.

	   The configure and unconfigure operations cannot be used for an attachment point where the port multiplier is connected. Port  multipli-
	   ers	are  configured  and  unconfigured  automatically  by  the system. However, configure and unconfigure operations apply to all SATA
	   devices connected to the port multiplier's device ports.

       -f

	   Not supported.

       -h ap_id

	   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 contains  the  following  SATA-
	   specific information:

	       o      Mfg: manufacturer string

	       o      Product: product string

	       o      No: product Serial Number

       -o hardware_options

	   No hardware specific options are currently defined.

       -s listing_options

	   Attachment points of class SATA can be listed by using the select suboption. See cfgadm(1M).

       -t ap_id

	   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 hardware_function

	   Perform hardware specific function.

	   Some of the following commands used on the SATA ports or the SATA controller may affect any SATA devices that have  been  attached,	as
	   noted.  ap_id refers to SATA port or the entire SATA controller, as noted. If the operation implies unconfiguring a device, but it can-
	   not 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 SATA controller does not support specified operation.

	   sata_reset_device ap_id

	       Reset the SATA device attached to ap_id SATA port. The SATA port state does not change.

	   sata_reset_port ap_id

	       Reset the SATA port specified by ap_id. If a SATA device is attached to the port, it is also reset. This operation may be also per-
	       formed on the port to which a port multiplier is connected. If a port multiplier is connected to the SATA controller port, the SATA
	       devices attached to the port multiplier may not be reset

	   sata_reset_all ap_id

	       Reset  SATA  controller	specified  by  the controller number part in ap_id and all attached devices and re-enumerate all connected
	       devices, including port multipliers and devices connected to port multipliers' device ports.

	       This operations implies unconfiguring all attached devices prior to the operation. Any newly enumerated devices will be left uncon-
	       figured.

	   sata_port_deactivate ap_id

	       Force the deactivation of the port when all else fails. This is meant as an emergency step; use with caution.

	   sata_port_activate ap_id

	       Force the activation of a port. This is meant for emergency situations on a port which was deactivated to recover from errors.

	   sata_port_self_test ap_id

	       Perform	self-test  operation  on the SATA controller. This operation implies unconfiguring all devices and resetting the SATA con-
	       troller.

       -v

	   Execute in verbose mode.

	   The following Transitions table reports the state transitions 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/
	     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

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

       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 Unconfiguring 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.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWcsl			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       cfgadm(1M), config_admin(3CFGADM), libcfgadm(3LIB), attributes(5)

NOTES

       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.

       Hotplugging operations are not supported by all SATA controllers.

       If SATA connectors are the hot-pluggable type and the SATA controller supports hotplugging, a SATA 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 "cfgadm -c
       configure ap_id" 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							    27 Aug 2007 						   cfgadm_sata(1M)