'\" te
.\" Copyright (c) 2003 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_scsi 1M "6 Jun 2006" "SunOS 5.11" "System Administration Commands"
.SH NAME
cfgadm_scsi \- SCSI 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_option\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_option\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\fI listing_option\fR] [\fB-o\fR \fIhardware_option\fR]
     [\fB-l\fR [\fIap_id\fR | \fIap_type ...\fR ]]
.fi

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

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

.SH DESCRIPTION
.sp
.LP
The \fBSCSI\fR hardware specific library \fB/usr/lib/cfgadm/scsi.so.1\fR
provides the functionality for \fBSCSI\fR hot-plugging through the
\fBcfgadm\fR(1M) command. \fBcfgadm\fR operates on attachment points, which are
locations in the system where hardware resources can be dynamically
reconfigured. Refer to \fBcfgadm\fR(1M) for information regarding attachment
points.
.sp
.LP
For \fBSCSI\fR hot-plugging, each \fBSCSI\fR controller is represented by an
attachment point in the device tree. In addition, each \fBSCSI \fRdevice is
represented by a dynamic attachment point. Attachment points are named through
\fBap_ids\fR. Two types of \fBap_ids\fR are defined: logical and physical. The
physical \fBap_id\fR is based on the physical pathname, whereas the logical
\fBap_id\fR is a shorter more user-friendly name. For \fBSCSI \fRcontrollers,
the logical \fBap_id\fR is usually the corresponding disk controller number.
For example, a typical logical \fBap_id\fR would be \fBc0\fR.
.sp
.LP
\fBSCSI\fR devices are named relative to the controller \fBap_id\fR. Thus if a
disk device is attached to controller \fBc0\fR, its \fBap_id\fR can be:
.sp
.in +2
.nf
c0::dsk/c0t0d0
.fi
.in -2
.sp

.sp
.LP
where \fBdsk/c0t0d0\fR identifies the specific device. In general, the device
identifier is derived from the corresponding logical link for the device in
\fB/dev\fR. For example, a \fBSCSI\fR tape drive logical \fBap_id\fR could be
\fBc0::rmt/0\fR. Here \fBc0\fR is the logical \fBap_id\fR for the \fBSCSI\fR
controller and \fBrmt/0\fR is derived from the logical link for the tape drive
in \fB/dev/rmt\fR. If an identifier can not be derived from the link in
\fB/dev\fR, a unique identifier will be assigned to it. For example, if the
tape device has no link in \fB/dev\fR, it can be assigned an \fBap_id\fR of the
form \fBc0::st3\fR where \fBst3\fR is a unique internally generated identifier.
.sp
.LP
A simple listing of attachment points in the system will include attachment
points at \fBSCSI \fRcontrollers but not \fBSCSI\fR devices. Use the \fB-a\fR
flag to the list option (\fB-l\fR) to list \fBSCSI\fR devices as well. For
example:
.sp
.in +2
.nf
# cfgadm -l
  Ap_Id             Type        Receptacle     Occupant     Condition
  c0                scsi-bus    connected      configured   unknown
  sysctrl0:slot0    cpu/mem     connected      configured   ok
  sysctrl0:slot1    sbus-upa    connected      configured   ok
.fi
.in -2
.sp

.sp
.LP
To list \fBSCSI\fR devices in addition to \fBSCSI\fR controllers:
.sp
.in +2
.nf
# cfgadm -al

Ap_Id                Type         Receptacle   Occupant     Condition
c0                   scsi-bus     connected    configured   unknown
c0::dsk/c0t14d0      disk         connected    configured   unknown
c0::dsk/c0t11d0      disk         connected    configured   unknown
c0::dsk/c0t8d0       disk         connected    configured   unknown
c0::dsk/c0t0d0       disk         connected    configured   unknown
c0::rmt/0            tape         connected    configured   unknown
sysctrl0:slot0       cpu/mem      connected    configured   ok
sysctrl0:slot1       sbus-upa     connected    configured   ok
.fi
.in -2
.sp

.sp
.LP
Refer to \fBcfgadm\fR(1M) for more information regarding listing attachment
points. The receptacle and occupant state for attachment points at the
\fBSCSI\fR controller have the following meanings:
.sp
.ne 2
.mk
.na
\fBempty\fR
.ad
.RS 16n
.rt  
not applicable
.RE

.sp
.ne 2
.mk
.na
\fBdisconnected\fR
.ad
.RS 16n
.rt  
bus quiesced (\fBI/O\fR activity on bus is suspended)
.RE

.sp
.ne 2
.mk
.na
\fBconnected\fR
.ad
.RS 16n
.rt  
bus active
.RE

.sp
.ne 2
.mk
.na
\fBconfigured\fR
.ad
.RS 16n
.rt  
one or more devices on the bus is configured
.RE

.sp
.ne 2
.mk
.na
\fBunconfigured\fR
.ad
.RS 16n
.rt  
no device on the bus is configured
.RE

.sp
.LP
The corresponding states for individual \fBSCSI\fR devices are:
.sp
.ne 2
.mk
.na
\fBempty\fR
.ad
.RS 16n
.rt  
not applicable
.RE

.sp
.ne 2
.mk
.na
\fBdisconnected\fR
.ad
.RS 16n
.rt  
bus to which the device is attached is quiesced
.RE

.sp
.ne 2
.mk
.na
\fBconnected\fR
.ad
.RS 16n
.rt  
bus to which device is attached is active
.RE

.sp
.ne 2
.mk
.na
\fBconfigured\fR
.ad
.RS 16n
.rt  
device is configured
.RE

.sp
.ne 2
.mk
.na
\fBunconfigured\fR
.ad
.RS 16n
.rt  
device is not configured
.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
.mk
.na
\fB\fB-c\fR \fIfunction\fR\fR
.ad
.RS 24n
.rt  
The following generic commands are defined for the \fBSCSI \fRhardware specific
library:
.sp
For \fBSCSI\fR controller attachment points, the following configuration state
change operations are supported:
.sp
.ne 2
.mk
.na
\fBconnect\fR
.ad
.RS 15n
.rt  
Unquiesce the \fBSCSI\fR bus.
.RE

.sp
.ne 2
.mk
.na
\fBdisconnect\fR
.ad
.RS 15n
.rt  
Quiesce the bus (suspend \fBI/O\fR activity on bus).
.sp
Incorrect use of this command can cause the system to hang. See \fBNOTES\fR.
.RE

.sp
.ne 2
.mk
.na
\fBconfigure\fR
.ad
.RS 15n
.rt  
Configure new devices on \fBSCSI\fR bus.
.RE

.sp
.ne 2
.mk
.na
\fBunconfigure\fR
.ad
.RS 15n
.rt  
Unconfigure all devices connected to bus.
.RE

The following generic commands are defined for \fBSCSI\fR devices:
.sp
.ne 2
.mk
.na
\fBconfigure\fR
.ad
.RS 15n
.rt  
configure a specific device
.RE

.sp
.ne 2
.mk
.na
\fBunconfigure\fR
.ad
.RS 15n
.rt  
unconfigure a specific device
.RE

.RE

.sp
.ne 2
.mk
.na
\fB\fB-f\fR\fR
.ad
.RS 24n
.rt  
When used with the \fBdisconnect\fR command, forces a quiesce of the \fBSCSI\fR
bus, if supported by hardware.
.sp
Incorrect use of this command can cause the system to hang. See \fBNOTES\fR.
.RE

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

.sp
.ne 2
.mk
.na
\fB\fB-o\fR \fIhardware_option\fR\fR
.ad
.RS 24n
.rt  
No hardware specific options are currently defined.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-s\fR \fIlisting_option\fR\fR
.ad
.RS 24n
.rt  
Attachment points of class \fBscsi\fR can be listed by using the \fBselect\fR
sub-option. Refer to the \fBcfgadm\fR(1M) man page for additional information.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-t\fR \fIap_id\fR\fR
.ad
.RS 24n
.rt  
No test commands are available at present.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-x\fR \fIhardware_function\fR\fR
.ad
.RS 24n
.rt  
Some of the following commands can only be used with SCSI controllers and some
only with SCSI devices.
.sp
In the following, \fIcontroller_ap_id\fR refers to an \fBap_id\fR for a SCSI
controller, for example, \fBc0\fR. \fIdevice_ap_id\fR refers to an \fBap_id\fR
for a \fBSCSI\fR device, for example: \fBc0::dsk/c0dt3d0\fR.
.sp
The following hardware specific functions are defined:
.sp
.ne 2
.mk
.na
\fBinsert_device \fIcontroller_ap_id\fR\fR
.ad
.sp .6
.RS 4n
Add a new device to the SCSI controller, \fIcontroller_ap_id\fR.
.sp
This command is intended for interactive use only.
.RE

.sp
.ne 2
.mk
.na
\fBremove_device \fIdevice_ap_id\fR\fR
.ad
.sp .6
.RS 4n
Remove device \fIdevice_ap_id\fR.
.sp
This command is intended for interactive use only.
.RE

.sp
.ne 2
.mk
.na
\fBreplace_device \fIdevice_ap_id\fR\fR
.ad
.sp .6
.RS 4n
Remove device \fIdevice_ap_id\fR and replace it with another device of the same
kind.
.sp
This command is intended for interactive use only.
.RE

.sp
.ne 2
.mk
.na
\fBreset_device \fIdevice_ap_id\fR\fR
.ad
.sp .6
.RS 4n
Reset \fIdevice_ap_id\fR.
.RE

.sp
.ne 2
.mk
.na
\fBreset_bus \fIcontroller_ap_id\fR\fR
.ad
.sp .6
.RS 4n
Reset bus \fIcontroller_ap_id\fR without resetting any devices attached to the
bus.
.RE

.sp
.ne 2
.mk
.na
\fBreset_all \fIcontroller_ap_id\fR\fR
.ad
.sp .6
.RS 4n
Reset bus \fIcontroller_ap_id\fR and all devices on the bus.
.RE

.sp
.ne 2
.mk
.na
\fBlocator [=on|off] \fIdevice_ap_id\fR\fR
.ad
.sp .6
.RS 4n
Sets or gets the hard disk locator \fBLED\fR, if it is provided by the
platform. If the [on|off] suboption is not set, the state of the hard disk
locator is printed.
.RE

.sp
.ne 2
.mk
.na
\fBled[=LED,mode=on|off|blink] \fIdevice_ap_id\fR\fR
.ad
.sp .6
.RS 4n
If no sub-arguments are set, this function print a list of the current
\fBLED\fR settings. If sub-arguments are set, this function sets the mode of a
specific \fBLED\fR for a slot.
.RE

.RE

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

.sp
.in +2
.nf
# \fBcfgadm -c configure c0::dsk/c0t3d0\fR
.fi
.in -2
.sp

.LP
\fBExample 2 \fRUnconfiguring a Disk
.sp
.LP
The following command unconfigures a disk attached to controller \fBc0\fR:

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

.LP
\fBExample 3 \fRAdding a New Device
.sp
.LP
The following command adds a new device to controller \fBc0\fR:

.sp
.in +2
.nf
# \fBcfgadm -x insert_device c0\fR
.fi
.in -2
.sp

.sp
.LP
The system responds with the following:

.sp
.in +2
.nf
Adding device to SCSI HBA: /devices/sbus@1f,0/SUNW,fas@e,8800000
This operation will suspend activity on SCSI bus c0
Continue (yes/no)? 
.fi
.in -2
.sp

.sp
.LP
Enter:

.sp
.in +2
.nf
\fBy\fR
.fi
.in -2
.sp

.sp
.LP
The system responds with the following:

.sp
.in +2
.nf
SCSI bus quiesced successfully. 
It is now safe to proceed with hotplug operation.
Enter y if operation is complete or n to abort (yes/no)?
.fi
.in -2
.sp

.sp
.LP
Enter:

.sp
.in +2
.nf
\fBy\fR
.fi
.in -2
.sp

.LP
\fBExample 4 \fRReplacing a Device
.sp
.LP
The following command replaces a device attached to controller \fBc0\fR:

.sp
.in +2
.nf
# \fBcfgadm \fR\fB-x\fR\fB replace_device c0::dsk/c0t3d0\fR
.fi
.in -2
.sp

.sp
.LP
The system responds with the following:

.sp
.in +2
.nf
Replacing SCSI device: /devices/sbus@1f,0/SUNW,fas@e,8800000/sd@3,0
This operation will suspend activity on SCSI bus: c0
Continue (yes/no)?
.fi
.in -2
.sp

.sp
.LP
Enter:

.sp
.in +2
.nf
\fBy\fR
.fi
.in -2
.sp

.sp
.LP
The system responds with the following:

.sp
.in +2
.nf
SCSI bus quiesced successfully. 
It is now safe to proceed with hotplug operation.
Enter y if operation is complete or n to abort (yes/no)?
.fi
.in -2
.sp

.sp
.LP
Enter:

.sp
.in +2
.nf
\fBy\fR
.fi
.in -2
.sp

.LP
\fBExample 5 \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
# \fBcfgadm -c unconfigure c1::dsk/c1t0d0\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@1f,4000/scsi@3,1/sd@1,0
     Resource              Information
------------------  --------------------------
/dev/dsk/c1t0d0s0   mounted filesystem "/mnt"
.fi
.in -2
.sp

.LP
\fBExample 6 \fRDisplay the Value of the Locator for a Disk
.sp
.LP
The following command displays the value of the locator for a disk. This
example is specific to the \fBSPARC\fR Enterprise Server family:

.sp
.in +2
.nf
# \fBcfgadm -x locator c0::dsk/c0t6d0\fR
.fi
.in -2
.sp

.sp
.LP
The system responds with the following:

.sp
.in +2
.nf
Disk                    Led
c0t6d0                  locator=on
.fi
.in -2
.sp

.LP
\fBExample 7 \fRSet the Value of the Locator for a Disk
.sp
.LP
The following command sets the value of the locator for a disk. This example is
specific to the \fBSPARC\fR Enterprise Server family:

.sp
.in +2
.nf
# \fBcfgadm -x locator=off c0::dsk/c0t6d0\fR
.fi
.in -2
.sp

.sp
.LP
The system does not print anything in response.

.SH FILES
.sp
.ne 2
.mk
.na
\fB\fB/usr/lib/cfgadm/scsi.so.1\fR\fR
.ad
.sp .6
.RS 4n
hardware-specific library for generic \fBSCSI\fR hot-plugging
.RE

.sp
.ne 2
.mk
.na
\fB\fB/usr/platform/SPARC-Enterprise/lib/cfgadm/scsi.so.1\fR\fR
.ad
.sp .6
.RS 4n
platform-specific library for generic \fBSCSI\fR hot-plugging
.RE

.SH SEE ALSO
.sp
.LP
\fBcfgadm\fR(1M), \fBluxadm\fR(1M), \fBconfig_admin\fR(3CFGADM),
\fBlibcfgadm\fR(3LIB), \fBattributes\fR(5)
.SH NOTES
.sp
.LP
The \fBdisconnect\fR (quiesce) operation is not supported on controllers which
control disks containing critical partitions such as \fBroot\fR (\fB/\fR),
\fB/usr\fR, \fBswap\fR, or \fB/var\fR. The \fBdisconnect\fR operation should
not be attempted on such controllers. Incorrect usage can result in a system
hang and require a reboot.
.sp
.LP
When a controller is in the disconnected (quiesced) state, there is a potential
for deadlocks occurring in the system. The \fBdisconnect\fR operation should be
used with caution. A controller should be kept in the disconnected state for
the minimum period of time required to accomplish the \fBDR\fR operation. The
\fBdisconnect\fR command is provided only to allow the replacement of  the
\fBSCSI\fR cables while the system is running. It should not be used for any
other purpose. The only fix for a deadlock (if it occurs) is to reboot the
system.
.sp
.LP
Hotplugging operations are not supported by all \fBSCSI\fR controllers.
.SH WARNINGS
.sp
.LP
The connectors on some \fBSCSI\fR devices do not conform to \fBSCSI\fR hotplug
specifications. Performing hotplug operations on such devices can cause damage
to the hardware on the \fBSCSI\fR bus. Refer to your hardware manual for
additional information.