'\" te .\" Copyright 2023 Peter Tribble .\" 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 8 "August 2, 2023" .SH NAME cfgadm_scsi \- SCSI hardware specific commands for cfgadm .SH SYNOPSIS .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 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(8) command. \fBcfgadm\fR operates on attachment points, which are locations in the system where hardware resources can be dynamically reconfigured. Refer to \fBcfgadm\fR(8) 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(8) 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 .na \fBempty\fR .ad .RS 16n not applicable .RE .sp .ne 2 .na \fBdisconnected\fR .ad .RS 16n bus quiesced (\fBI/O\fR activity on bus is suspended) .RE .sp .ne 2 .na \fBconnected\fR .ad .RS 16n bus active .RE .sp .ne 2 .na \fBconfigured\fR .ad .RS 16n one or more devices on the bus is configured .RE .sp .ne 2 .na \fBunconfigured\fR .ad .RS 16n no device on the bus is configured .RE .sp .LP The corresponding states for individual \fBSCSI\fR devices are: .sp .ne 2 .na \fBempty\fR .ad .RS 16n not applicable .RE .sp .ne 2 .na \fBdisconnected\fR .ad .RS 16n bus to which the device is attached is quiesced .RE .sp .ne 2 .na \fBconnected\fR .ad .RS 16n bus to which device is attached is active .RE .sp .ne 2 .na \fBconfigured\fR .ad .RS 16n device is configured .RE .sp .ne 2 .na \fBunconfigured\fR .ad .RS 16n device is not configured .RE .SH OPTIONS \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 .RS 24n 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 .na \fBconnect\fR .ad .RS 15n Unquiesce the \fBSCSI\fR bus. .RE .sp .ne 2 .na \fBdisconnect\fR .ad .RS 15n 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 .na \fBconfigure\fR .ad .RS 15n Configure new devices on \fBSCSI\fR bus. .RE .sp .ne 2 .na \fBunconfigure\fR .ad .RS 15n Unconfigure all devices connected to bus. .RE The following generic commands are defined for \fBSCSI\fR devices: .sp .ne 2 .na \fBconfigure\fR .ad .RS 15n configure a specific device .RE .sp .ne 2 .na \fBunconfigure\fR .ad .RS 15n unconfigure a specific device .RE .RE .sp .ne 2 .na \fB\fB-f\fR\fR .ad .RS 24n 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 .na \fB\fB-h\fR \fIap_id\fR\fR .ad .RS 24n SCSI specific help can be obtained by using the help option with any SCSI attachment point. .RE .sp .ne 2 .na \fB\fB-o\fR \fIhardware_option\fR\fR .ad .RS 24n No hardware specific options are currently defined. .RE .sp .ne 2 .na \fB\fB-s\fR \fIlisting_option\fR\fR .ad .RS 24n Attachment points of class \fBscsi\fR can be listed by using the \fBselect\fR sub-option. Refer to the \fBcfgadm\fR(8) man page for additional information. .RE .sp .ne 2 .na \fB\fB-t\fR \fIap_id\fR\fR .ad .RS 24n No test commands are available at present. .RE .sp .ne 2 .na \fB\fB-x\fR \fIhardware_function\fR\fR .ad .RS 24n 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 .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 .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 .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 .na \fBreset_device \fIdevice_ap_id\fR\fR .ad .sp .6 .RS 4n Reset \fIdevice_ap_id\fR. .RE .sp .ne 2 .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 .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 .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 .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 \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 .SH FILES .ne 2 .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 .SH SEE ALSO .BR config_admin (3CFGADM), .BR libcfgadm (3LIB), .BR attributes (7), .BR cfgadm (8), .BR luxadm (8) .SH NOTES 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 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.