NAME

scu − SCSI CAM Utility Program

SYNOPSIS

/sbin/scu [ −f device-name-path ] [ command [ argument ... ] ]

DESCRIPTION

The SCSI utility program, scu, interfaces with the CAM I/O subsystem and the peripherals attached to the SCSI buses.  This utility implements the SCSI commands necessary for normal maintenance and diagnostics of SCSI peripherals and the CAM I/O subsystem. 

General Arguments

There are some general arguments that you can use with some of the scu commands:

nexus-information

The nexus-information argument allows you to specify values to override the bus, target, and logical unit number (LUN) values that are taken from the specified SCSI device.  The nexus-information argument can have the following syntaxes:

bus nThe previous syntax specifies the SCSI device bus number (path ID).  The n variable can have a range of values from 0 (zero) to 3. 

target n
The previous syntax specifies the target number (target ID). The n variable can have a range of values from 0 (zero) to 7. 

lun nThe previous syntax specifies the LUN.  The n variable can have a range of values from 0 (zero) to 7. 

test-parameter

The test-parameter argument specifies the physical limits of the media on which the command can operate.  For example, these limits can be the starting and ending logical block numbers on a disk.  You can specify variables that control the media being tested and variables that control elements of the test operation. 

The following variables for the test-parameter argument control the media that is being tested:

lbn n

length n

starting n

ending n

size nSpecifies the block size per I/O request.  The default is 512. 

limit n

records n

The following variables for the test-parameter argument control elements of the test operation:

align align-offset
Specifies the data buffer alignment offset.  The default is 0 (zero).

compare { on | off}
Specifies if compare data during read operations is enabled.  The default is enabled.

errors error-limit
Specifies the error limit.  The default is 10.

passes pass-limit
Specifies the number of passes to perform.  The default is 1.

pattern data-pattern
Specifies the data pattern to use on the first pass.  The default is 0x39c39c39.

recovery {on | off}

The following expressions are accepted for the test-parameter argument variables that accept numeric values:

Character

Meaning

Special Characters:

b	blocks (512 bytes)
k	kilobytes (1024 bytes)
g	gigabytes (1073741824 bytes)
m	megabytes (1048576 bytes)
p	page size (usually 4096 bytes)
w	word size (2, 4, or 8 bytes)

Arithmetic Characters:

+	addition
-	subtraction
∗ or x	multiplication
/	division
%	remainder

Bitwise Characters:

~	complement of value
>>	shift bits right
<<	shift bits left
&	bitwise "and" operation
|	bitwise "or" operation
^	bitwise exclusive "or"

The following conditions apply to the characters used in expressions:

       •If value is omitted, the value defaults to one. 

       •Both upper and lower case characters are accepted. 

       •Spaces and tabs are ignored between operands. 

       •Expressions are evaluated from right to left without precedence. 

       •Parentheses grouping is not supported. 

General Commands

The following scu commands are used for general purposes:

evaluate expression
The evaluate command evaluates the specified expression and displays values in decimal, hexadecimal, blocks, kilobytes, megabytes, and gigabytes.  The output depends on whether the set verbose flag is set. 

exitThe exit command is used to exit from the scu program.  You can also type Ctrl/D.  The scu quit command is the equivalent of the exit command. 

help [command]
The help command displays information on all scu commands.  If you do not specify a command, a list of possible topics is displayed. 

scan {edt [nexus-information] [{full \

| summary}] | media [test-parameters]}
The scan edt command allows you to scan the SCSI bus and update the CAM Equipment Device Table (EDT) to reflect the devices found.  If the nexus-information argument is not specified, the selected device is scanned.  You can specify full to display the inquiry data associated with each nexus, or summary (the default) to display a single line of output for each nexus found.  The scan media command allows you to scan the device media.  This involves writing a data pattern to the media and then reading and verifying the data.  The test-parameters argument specifies the media area to be scanned. 

set parameters
The set command sets parameters for a device or sets environment parameters for the scu program.  The formats of the set parameters are as follows:

set audio {address format {lba | msf} \

| volume [{ch0 | ch1}] level n}
The address format parameter specifies the default address format associated with CD-ROM audio commands.  The volume parameter sets the audio volume control levels.  You can change the right or the left channel individually or simultaneously. 

set cam {debug debug-flags | flags ccb-flags}
The cam debug parameter allows you to set the CAM debug flags that are used by the user-level SCSI/CAM special I/O interface.   You can specify the following debug-flags variables:

Debug Flag	Hex Value	Description
CAMD_INOUT	0x00000001	Routine entry and exit
CAMD_FLOW	0X00000002	Code flow through the modules
CAMD_ERRORS	0x00000010	Error handling
CAMD_CMD_EXP	0x00000020	Expansion of commands and responses

The cam flags parameter allows you to specify CAM flags to be set in CCBs that are sent to the CAM subsystem.  You can specify the following ccb-flags variables:

CAM CCB Flag	Hex Value	Description
CAM_DIS_DISCONNECT	0x00008000	Disable disconnect
CAM_INITIATE_SYNC	0x00004000	Attempt synchronous data transfer
CAM_DIS_SYNC	0x00002000	Disable synchronous data transfer
CAM_SIM_QHEAD	0x00001000	Place the CCB at the head of the SIM queue
CAM_SIM_QFREEZE	0x00000800	Return the SIM queue to the frozen state
CAM_SIM_QFRZDIS	0x00000400	Disable the SIM queue (freeze on errors)
CAM_ENG_SYNC	0x00000200	Flush residual bytes before completion

set debug {on | off}
The debug parameter enables or disables the scu program debug flag. 

set default {savable {on | off} | test-parameter}
The default parameter allows you to change some program defaults.  The savable argument allows you to specify if the mode page parameters are saved.  By default, if the mode page is savable, then the mode parameters that are set by the "set" or "change" page will be saved.  You can only specify the align, compare, errors, passes, pattern, and size test-parameter arguments. 

set device device-type [nexus-information]
The device parameter issues a CAM Set Device Type CCB to change the device type in the EDT.  You can also use this parameter to set up the device type of to overwrite the existing device type.  Use the nexus-information argument to specify the device.  You can specify the following device-type values:

Device Type	CAM definition	Value
direct-access	ALL_DTYPE_DIRECT	0
sequential-access	ALL_DTYPE_SEQUENTIAL	1
printer	ALL_DTYPE_PRINTER	2
processor	ALL_DTYPE_PROCESSOR	3
worm	ALL_DTYPE_WORM	4
rodirect	ALL_DTYPE_RODIRECT	5
scanner	ALL_DTYPE_SCANNER	6
optical	ALL_DTYPE_OPTICAL	7
changer	ALL_DTYPE_CHANGER	8
communication	ALL_DTYPE_COMM	9

set dump {on | off}
Enables or disables the dump buffer flag.  If enabled and if the CAM debug flag (CAMD_CMD_EXP) is set during a data-in operation, the entire data buffer, up to the value of the dump-limit parameter, is dumped instead of the number of bytes indicated by the CCB fields.  The default is disabled. 

set dump-limit
Limits the number of bytes dumped during debugging.  The default is 512 bytes.

set log log-file-path
Enables logging and writes standard output and error text to the specified file.  You can disbale logging and close a log file by specifying a null file name string.

set paging {on | off}
Controls paging if output is sent to a terminal device.

set recovery {on | off}
Enables (the default) or disables the error-control parameters for the specified device.

show parameter
Displays parameters for a device or program.  You can specify parameter as follows:

show audio argument [address format {lba | msf}]
Displays information about a CD-ROM device.  The address format parameter specifies the default address format associated with CD-ROM audio commands.  The argument can be the following:

channelShow the audio channel. 

catalogDisplays the media catalog number, if any. 

isrcDisplays the International Standard Recording Code (ISRC) information, if any. 

header lba n
Displays the logical block address associated with the current position.

positionDisplays the current play position information. 

status lba nDisplays the current playback status information. 

toc [{entry n | header}] [{full | summary}]
Displays the table of contents (TOC) for the current audio disc. You can display the TOC header, a single TOC entry, or the entire table of contents in either a full or summary report format. The default is to display the entire TOC in summary format.

show capacity
Displays disk capacity in blocks.

show defects [[defect-list [defect-format]]
Displays the disk defect list or lists.  The defect-list can be all, primary, or grown.  The defect-format can be block, bfi, or sector. 

show device [nexus-information]
Displays information returned by the CAM Get Device Type CCB. If you do not specify nexus-information,  the selected device is used. 

show edt [nexus-information] [{full | summary}]
Displays the CAM EDT entries.  If you do not specify nexus-information, all EDT entries are displayed.  You can specify full to display the inquiry data associated with each nexus, or summary (the default) to display a single line of output for each nexus found. 

show nexus
Displays the current nexus information and device type for the selected device.

show pages [mode-page [pcf page-control-field]]
Displays the mode pages for the selected device.  The page-control-field variable specifies the following page-control fields: current, changeable, default, or saved.  The mode-page variable describes the mode page on which to operate and can be the following:

Mode Page	Page Code	Description
error-recovery	0x01	Error recovery page
disconnect	0x02	Disconnect/reconnect page
direct-access	0x03	Direct access format page
geometry	0x04	Disk geometry page
flexible	0x05	Flexible disk page
cache-control	0x08	Cache control page
cdrom	0x0D	CD-ROM device page
audio-control	0x0E	Audio control page
device-configuration	0x10	Device configuration page
medium-partition-1	0x11	Medium partition page 1
dec-specific	0x25	DEC specific page
readahead-control	0x38	Read-ahead control page

show path-inquiry [nexus-information]
Displays the CAM Path Inquiry information.  If you do not specify nexus-information, the selected device is used. 

source input-file
Allows you to use the input-file as source input. 

switch [device-name]
Accesses a different device or, if a device-name is not specified, to a previous device. 

Device and Bus Subsystem Commands

You can use the following scu commands to manage SCSI devices and the CAM I/O subsystem:

allow
Allows you to remove the media from the selected device.

eject
Used with a CD-ROM device to stop play and eject the caddy.

mt parameter
You can specify the following mt parameters:

bsf [count]Used to backward space count file marks.  The default is 1. 

bsr [count]Use to backward space count file records.  The default is 1. 

eraseUsed to erase the tape. 

fsf [count]Used to forward space count file marks. 

fsr [count]Used to forward space count file records. 

loadUsed to load the tape. 

offlineUsed to take a tape off line (unload operation). 

onlineUsed to bring a tape online (load operation). 

rewindUsed to rewind the tape. 

retensionUsed to retension the tape, which moves the tape one complete pass between EOT and BOT. 

seodUsed to space to the end of data (end of recorded media). 

unloadUsed to unload the tape. 

weof [count]Used to write tape file marks.  The default count is 1. 

pause
Used to pause the playing of a CD-ROM audio disc.

play [parameters] [starting [n]] [ending [n]]
Used to play audio tracks on a CD-ROM audio disc. If parameters are not specified, then all audio tracks are played.  It the starting track number is omitted, the default is first audio track in the disc.  If the ending track number is omitted, the default is the last track on the audio disc.  You can specify the following parameters:

track nPlays the specified audio track number.Plays the specified audio track number. 

audio lba n length n
Plays audio using the logical block addressing (LBA) format.  Audio play starts at the logical block address specified and continues through the length (in blocks) specified.

msf starting mu n su n fu n ending mu n su n fu n
Plays audio using the minute/second/frame (MSF) unit addressing format. Audio play starts at the specified MSF address and continues through the specified ending MSF address.

prevent
Prevents media removal from the selected device.

release {device | simqueue [nexus-information]}
Releases a reserved SCSI device or a frozen SIM queue, which occurs after an error.  The device parameter releases a reserved SCSI device by issuing a release unit command.  Extent release for direct access device is not implemented.  The simqueue parameter issues a Release SIMQ CCB to release a frozen SIM queue.  If nexus-information is not specified, the SIM queue for the selected SCSI device is released. 

reserve device
Reserves a SCSI device by issuing a reserve unit command.

reset {bus | device} [nexus-information]
Resets the SCSI bus or the selected SCSI device.  The bus parameter issues a CAM Bus Reset CCB.  The device parameter issues a CAM Bus Device Reset CCB. 

resume
Used with a CD-ROM to resume play after being paused.

start
Starts a unit that has been stopped.

stop
Stops a unit.  This usually involves spinning the disk down and keeping the heads at the landing cylinder.

turIssues a Test Unit Ready command to determine if a device is ready.  If a failure occurs, the sense data is automatically reported. 

verify media [test-parameters]
Verifies the data written on the device media.  This usually involves reading and performing an ECC check of the data.  If test-parameters are not specified, the entire device media is verified. 

Device and Bus Maintenance Commands

The following device and bus maintenance commands are used to maintain SCSI devices and the CAM I/O subsystem:

change pages [mode-page [pcf page-control-field]]
Changes mode pages for a device.  The program prompts you with those page fields that are marked changeable.  If mode-page is not specified, all pages supported by the device will be requested to be changed.  The page-control-field variable specifies the following page-control fields: current, changeable, default, or saved.  Refer to the description of the show pages command for a list of the mode-page variables. 

download filename [save]
Used with any device that supports the downloading of operating software via the Write Buffer command. The save parameter directs the device to save the new operating software in non-volatile memory if the command successfully completes. 

format [density density-type] [defects defect-list]
Formats both hard and flexible disk media. The density-type variable an be either RX50, LD, DD, HD/HD5, ED, or other.  The defect-list can be either all, primary, or none. 

read media test-parameters
Reads the device media and performs a data comparison of the data read.

reassign lba n
Reassigns a defective block on a disk device.

test [{controller | drive | memory [test-parameters] | selftest}]
Performs tests on a controller.  This involves issuing send and receive diagnostic commands or write and read buffer commands (for a memory test) to the selected device.  The default is to perform the self test, which is supported by most controllers.

write media test-parameters
Writes to the device media using various data patterns.  You must specify transfer parameters which specifies the media area to be written.

FLAGS

-fSpecifies the raw device pathname.  You must specify a character device special file, for example, /dev/rrz3c.  If the device name is not specified on the command line, the program checks the environment variable SCU_DEVICE to define the device name.

RESTRICTIONS

Commands that modify device data or device parameters require write access to the device entry.  Applications that change the volume level of the CDROM must open the device for write access since a SCSI Mode Select command is used to modify the volume level. 

EXAMPLES

To format an RX26 diskette at extra density, enter:

scu> format density ED

To verify 1024 blocks starting at block 1000, enter:

scu> verify media starting 1000 length 1024

To display all changeable mode pages for a device, enter:

scu> show page pcf changeable

To display inquiry information for all devices on the first SCSI bus at lun 0 in the Equipment Device Table (EDT), enter:

scu> show edt bus 0 lun 0 full

To reassign logical block address ???, enter:

scu> reassign lba ???

RETURN VALUES

For all commands, scu runs and exits with 0 for success, 1 for warning, or -1 for failure status. 

ERRORS

When a SCSI device error occurs, both the sense key and the addition sense code or qualifier are decoded and displayed as follows:

scu: Sense Key = 0x5 = ILLEGAL REQUEST - Illegal request or CDB parameter,
     Sense Code/Qualifier = (0x20, 0) = Invalid command operation code

This error indicates that you have issued a command that is not supported by the selected device.  This can happen for optional commands that are not supported by all devices. 

FILES

/sbin/scuThe SCSI Utility executable file. 

/dev/camThe device entry for the CAM User Agent driver. 

/sbin/scu.hlpContains the scu help information. 

RELATED INFORMATION

Commands:  file(1), more(1). 

Functions:  open(2), close(2), ioctl(2), fopen(3), fgets(3), fputs(3), popen(3), pclose(3), malloc(3), printf(3), fprintf(3). 

American National Standard for Information Systems, Small Computer Systems Interface - 2 (SCSI - 2), X3.131-199X

American National Standard for Information Systems, SCSI-2 Common Access Method: Transport and SCSI Interface Module, working draft, X3T9.2/90-186