B SCSI/CAM Utility Program

B.1 Introduction

The SCSI/CAM Utility Program, scu, interfaces with the Common Access Method (CAM) I/O subsystem and the peripheral devices attached to Small Computer System Interface (SCSI) busses. This utility implements the SCSI commands necessary for normal maintenance and diagnostics of SCSI peripheral devices and the CAM I/O subsystem.

The format of a SCU command is as follows:

scu> [-f device-name-path] [command[keyword]...]

If a device name is not specified in one of the options on the command line, the program checks the SCU_DEVICE environment variable to determine the device name. If SCU_DEVICE is not set, you must use the set nexus command to select the device and operation or some commands may be restricted.

For example, if you do not specify a device name and SCU_DEVICE is not set, you cannot format a disk because the scu utility cannot perform a mounted file system check. See Section B.3 for a description of the set command and its arguments.

If a command is not entered on the command line, the program prompts for commands until you terminate the program. In most cases, you can abbreviate commands to the lowest unambiguous number of characters.

This appendix contains an overview of the scu functions that system administrators use. Detailed information, including examples of use, is available through the online help for the scu utility. To use the help facility once you are in the scu utility, issue the help command at the scu> prompt.

B.2 SCU Utility Conventions

The following conventions describe the scu utility syntax:

Convention	Meaning
`keyword` `(` `alias` `)`	Use a keyword or the specified alias.
`address-format`	Optionally accepts an address format.
`nexus-information`	Optionally accepts nexus information.
`test-parameters`	Optionally accepts test parameters.
`D:` `value` or `string`	The value or string shown is the default.
`R:` `minimum-maximum`	Enter a value within the range specified.

The address-format parameter is optional. It is available for use with most CD-ROM Show Audio commands that specify the address format of information returned by the drive. The possible address formats are as follows:

Format	Description
`lba`	Logical block address
`msf`	Minute, second, and frame

The syntax of a command that uses the address-format parameter is as follows:

scu> [command] [address-format { lba | msf } ]

The nexus-information parameter lets users specify values to override the bus, target, and LUN values normally taken from the selected SCSI device. The nexus-information keywords are as follows:

Parameter	Description
`bus (pid) R:0-3`	SCSI bus number (path ID)
`target (tid) R:0-7`	SCSI target number (target ID)
`lun R:0-7`	SCSI Logical Unit Number (LUN)

You use the test-parameter variables to specify the physical limits of the media on which the command can operate. For example, these may be the starting and ending logical block numbers on a disk. The test parameters for a command use the following syntax:

scu> command [media-limits] [test-control]

The media-limits parameter, which controls the media tested, has the following syntax:

                                                  { lb n }   { length n }
scu> command [{ starting n }] [{ endingn }] [size n]
                                                  { limit  n }
                                                  { records n }

The alias bs (block size) is accepted for the size keyword.

The test-control parameters control aspects of the test operation. The test-control parameters supported are:

                                                   { align Align-Offset }
                                                   { compare { on | off }  }
scu> command [ { errors Error-Limit  } ]
                                                   { passes Pass-Limit     }
                                                   { pattern Data-Pattern  }
                                                   { recovery { on | off } }

B.3 General SCU Commands

This section describes the general-purpose scu utility commands. For more information on each command, see the online help that is part of the scu utility.

evaluate expression

This command evaluates the given expression and displays values in decimal, hexadecimal, blocks, kilobytes, megabytes, and gigabytes. The expression argument is the same as that described for test parameter values. The output depends on whether the verbose display flag is set.

The following examples show the output of the evaluate command. Verbose mode is turned on for the first two evaluate commands and turned off for the last one.

scu>set verbose on
scu>evaluate 0xffff
Expression Values:
            Decimal: 65535
        Hexadecimal: 0xffff
    512 byte Blocks: 128.00
          Kilobytes: 64.00
          Megabytes: 0.06
          Gigabytes: 0.00
scu>evaluate 64k*512
Expression Values:
             Decimal: 33554432
         Hexadecimal: 0x2000000
     512 byte Blocks: 65536.00
           Kilobytes: 32768.00
           Megabytes: 32.00
           Gigabytes: 0.03
scu>set verbose off
scu>evaluate 0xffff
Dec: 65525 Hex: 0xffff Blks: 128.00 Kb: 64.00 Mb: 0.06 Gb: 0.00

exit

You use this command to exit from the program. You can use quit as an alias for exit. You can terminate the program in interactive mode by entering the end-of-file character (usually Ctrl/d).

help [topic]

This command displays help information on topics. You can use a question mark (?) as an alias. If you issue the help command without specifying a topic, a list of all available topics is displayed.

scan [edt, nexus-information, report-format] scan [media test-parameters]

This command scans either device media or the CAM Equipment Device Table (EDT).

The following examples use the scan edt command. The first example illustrates the command followed by the show device command to display the information resulting from the scan.

scu> scan edt
Scanning bus 1, target 6, lun 0, please be patient...
scu> show device
Scanning bus 1, target 6, lun 0, please be patient...
Inquiry Information:
                      SCSI Bus ID: 1
                   SCSI Target ID: 6
                  SCSI Target LUN: 0
           Peripheral Device Type: Direct Access
             Peripheral Qualifier: Peripheral Device Connected
            Device Type Qualifier: 0
                  Removable Media: No
                     ANSI Version: SCSI-1 Compliant
                     ECMA Version: 0
                      ISO Version: 0
             Response Data Format: CCS
                Additional Length: 31
            Vendor Identification: DEC
           Product Identification: RZ55     (C) DEC
          Firmware Revision Level: 0700
scu> scan edt bus 1
Scanning bus 1, target 6, lun 0, please be patient...

The media argument causes the device media to be scanned. This involves writing a data pattern to the media and then reading and verifying the data written. You must include test parameters that specify the media area to be scanned.

The following examples use the scan media command with different test-parameters:

scu> media 
scu: No defaults, please specify test parameters for transfer
scu> scan media length 100 recovery off
Scanning 100 blocks on /dev/rrz10c (RX23) with pattern
                                         0x39c39c39...
scu> scan media lba 200 limit 25k align 'lp-1'
Scanning 50 blocks on /dev/rrz10c (RX23) with pattern
                                        0x39c39c39...
scu> scan media starting 0 bs 32k records 10
Scanning 640 blocks on /dev/rrz10c (RX23) with pattern
                                         0x39c39c39...
Scanning blocks [ 0 through 63 ]...
Scanning blocks [ 64 through 127 ]...
Scanning blocks [ 128 through 191 ]...
Scanning blocks [ 192 through 255 ]...
Scanning blocks [ 256 through 319 ]...
Scanning blocks [ 320 through 383 ]...
Scanning blocks [ 384 through 447 ]...
Scanning blocks [ 448 through 511 ]...
Scanning blocks [ 512 through 575 ]...
Scanning blocks [ 576 through 639 ]...

set

The set command sets parameters for a device or sets environment parameters for the scu program. See the on-line help text that is part of the scu utility for an explanation of each parameter.

            { audio keywords }
            { cam debug hex-flags }
            { debug { on | off } }
            { default parameter }
   set    { device device-type }
            { dump { on | off } }
            { dump-limit value }
            { log file-name-path }
            { nexus nexus-information }
            { pages [ mode-page [ pcf page-control-field ] }
            { pager paging-filter }
            { paging { on | off } }
            { recovery { on | off } }
            { tape keywords ... }
            { verbose { on | off } }
            { watch { on | off } }

show

You use this command to display parameters for a device or the program. See the scu online help for more information.

          { audio keywords }
          { capacity }
          { defects }
          { device }
show  { edt }
          { memory }
          { mode-pages }
          { nexus }
          { pages }
          { path-inquiry }

sourceinput-file

This command allows you to source input from an external command file. If any errors occur during command parsing or execution, the command file is closed at that point. The default file name extension .scu is appended to the name of the input file if no extension is supplied. If the scu utility cannot find a file with the .scu extension, it attempts to locate the original input file.

switch [device-name]

This command accesses a new device or a previous device. If no device name is specified, the command acts as a toggle and simply switches to the previous device, if one exists. If a device is specified, it is validated and becomes the active device.

B.4 Device and Bus Management Commands

This section describes the following scu utility commands for managing SCSI devices and the CAM I/O subsystem:

allow

This command allows media to be removed from the selected device.

eject

You use this command with CD-ROMs to stop play and eject the caddy.

mt command [count]

This command issues one of the supported mt commands. See the online help text that is part of the scu utility for information on the mt commands.

pause

You use this command to pause the playing of a CD-ROM audio disc.

play

You use this command to play audio tracks on a CD-ROM audio disc. If no keywords are specified, all audio tracks are played by default. You can specify a track number, a range of audio tracks, a logical block address, or a time address. See the online help that is part of the scu utility for information on the play command.

prevent

This command prevents media removal from the selected device.

release {device | simqueue} [nexus-information]

This command releases a reserved SCSI device or releases a frozen SIM queue after an error. The device argument specifies a reserved SCSI device to be released. The extent release capability for direct access devices is not implemented.

The simqueue argument issues a release SIMQ CCB to thaw a frozen SIM queue. Ordinarily, this command is not necessary because the SIM queue is automatically released after errors occur. If the nexus information is omitted, the SIM queue for the selected SCSI device is released.

The following example shows the release command:


scu> release simqueue bus 1 target 6 lun 0

reserve device

This command issues a SCSI Reserve command to the selected device. The entire logical unit is reserved for the exclusive use of the initiator. Extent reservation for direct access devices is not implemented.

reset {bus | device} [nexus-information]

This command resets the SCSI bus or the selected SCSI device.

The bus argument issues a CAM Bus Reset CCB. If the nexus information is omitted, the bus associated with the selected SCSI device is reset. The reset bus command is restricted to superuser (root) access because it can cause loss of data to some devices.

The device argument issues a CAM Bus Device Reset CCB. If the nexus information is omitted, the selected device is reset. The reset device command requires write access to the selected device because the command can cause loss of data to some devices.

If nexus information is specified, this command is restricted to the superuser.

resume

This command causes a CD-ROM audio disc to resume play after it has been paused with the pause command.

start

This command issues a SCSI Start Unit command to the selected device. This action enables the selected device to allow media access operations.

stop

This command issues a SCSI Stop Unit command to the selected device. This action disables the selected device from allowing media access operations.

tur

This command issues a Test Unit Ready command to determine the readiness of a device. If the command detects a failure, it automatically reports the sense data.

verify media [test-parameters]

This command performs verify operations on the selected device.

The media argument verifies the data written on the device media. This activity involves reading and performing an ECC check of the data. If the test parameters are omitted, the entire device media is verified.

If the device does not support the verify command, the following error message appears:

scu>verify media starting 1000 length 1024
Verifying 1024 blocks on /dev/rrz10c (RX23),
                         please be patient...
Verifying blocks [ 1000 through 2023 ] ...
scu: Sense Key = 0x5 = ILLEGAL REQUEST -
                         Illegal request or CDB parameter,
     Sense Code/Qualifier = (0x20, 0) =
                         Invalid command operation code

When an error occurs, the sense key is examined. The expected sense keys are Recovered Error (0x01) or Medium Error (0x03). When these errors are detected, the following error message is displayed and verification continues with the block following the failing block:

scu: Verify error at logical block number 464392 (0x71608).
scu: Sense Key = 0x1 = RECOVERED ERROR -
                              Recovery action performed,
     Sense Code/Qualifier = (0x17, 0) = Recovered data with no
                              error correction applied

If any other sense key error occurs, the full sense data is displayed and the verification process is aborted.

The following conditions apply to the verify command:

On failure, the failing logical block number (LBN) is reported and verification continues with the block following the failing block.

By default, verification is performed using the current parameters in the Error Recovery mode page. You can disable drive recovery by using the set recovery off command.

For example:

scu> verify media lba 464388
Verifying 1 blocks on /dev/rrz14c (RZ55),
                           please be patient...
Verifying blocks [ 464388 through 464388 ] ...
scu> verify media starting 640000
Verifying 9040 blocks on /dev/rrz14c (RZ55),
                              please be patient...
Verifying blocks [ 640000 through 649039 ] ...
scu> verify media starting 1000 length 250
Verifying 250 blocks on /dev/rrz14c (RZ55),
                             please be patient...
Verifying blocks [ 1000 through 1249 ] ...
scu> verify media starting 1000 ending 2000
Verifying 1001 blocks on /dev/rrz14c (RZ55),
                              please be patient...
Verifying blocks [ 1000 through 2000 ] ...

B.5 Device and Bus Maintenance Commands

This section describes scu utility commands for maintaining SCSI devices and the CAM I/O subsystem.

The following command changes the mode pages for a device:

change pages [mode-pages...] [pcf page-control-field]

The program prompts you with a list of the page fields that are marked as changeable. If you do not specify a mode page, all pages supported by the device are requested for changing. After you enter the new fields for each page, you use a mode select command to set the new page parameters.

The mode-page argument describes the mode page to change. The mode pages are as follows:

scu Keyword	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	Digital-specific page
`readahead-control`	0x38	Read-ahead control page

Notes on the change pages command:

Only fields that are marked changeable in the changeable mode page are prompted for.

The default page control field is "current" values.

Selecting a "pcf" is sticky (for example, sets new "pcf" default).

Changing page values always affects the current page values.

The default is to save page values if the page saveable bit in the page header is set and the program savable flag is set. Use the set default savable command to alter this flag.

Some pages, such as those that affect the physical media, do not actually get saved until the media is formatted.

For mode pages that are unknown to the program, you can specify a hex page code for the page to change. In this mode, mode page fields are displayed and changed by hex byte values. You can also use this format to override the known formatted page change functions. For example:

change page code hex-code [pcf[page-control-field]]

The following example shows the change page command with the code parameter:


scu> change page code 0x21
Changing Unknown Page Parameters (Page 21 - current values):
Byte 2 [R:0-0xff D:0x2]: 3
Byte 3 [R:0-0xff D:0x8]:
Byte 4 [R:0-0xff D:0]:
Byte 5 [R:0-0xff D:0]:
Byte 6 [R:0-0xff D:0x3]:
Byte 7 [R:0-0xff D:0xe8]:
Byte 8 [R:0-0xff D:0x2]:
Byte 9 [R:0-0xff D:0x96]:
Byte 10 [R:0-0xff D:0x5]:
scu>

The page-control-field argument specifies the type of mode pages to obtain from the device. The page control fields that you can specify are as follows:

changeable

current

default

saved

The following example changes the error recovery parameters:

scu> change pages error
Changing Error Recovery Parameters (Page 1 - current values):
Disable Correction (DCR) [R:0-1 D:0]:
Disable Transfer on Error (DTE) [R:0-1 D:0]:
Post Recoverable Error (PER) [R:0-1 D:0]:
Transfer Block (TB) [R:0-1 D:0]:
Automatic Write Allocation (AWRE) [R:0-1 D:1]:
Read Retry Count [R:0-255 D:8]: 25
Write Retry Count [R:0-255 D:2]: 5
scu>

download filename [save] [ { id buffer-id | offset offset-value | segment | [ size] } ]

You can use the preceding command with any device that supports the downloading of operating software through the Write Buffer command.

The save keyword directs the device to save the new operating software in nonvolatile memory if the download command is completed successfully. With save specified, the downloaded code remains in effect after each power cycle and reset. If the save keyword is not specified, the downloaded software is placed in the control memory of the device. After a power cycle or reset, the device operation would revert to a vendor-specific condition.

If the save parameter is omitted, a Download microcode (mode 4) command is issued. Specifying save performs a Download microcode and save operation (mode 5). Not all devices accept both modes.

You can specify various parameters to control the download operation. Most devices do not require these optional parameters, but since each vendor may implement the download command differently, these parameters provide the capability to override program defaults.

The following notes apply to the download parameters:

The default buffer ID is 0.

The default offset value is 0.

The default segment size is 8 KB. If this parameter is not specified, the default is to download the entire image at once.

Refer to the vendor's SCSI programming manual for information on buffer ID's and buffer modes supported.

The following notes apply to the download command:

If you enter scu using the default device /dev/cam and then set the device to download using the set nexus command, the code associated with checking for mounted file systems will fail. This was done purposely to prevent accidental downloading of disks with mounted file systems.

Some devices, such as many disks, require additional time after the download operation to program the flash memory (save the firmware) to recalibrate or perform other necessary setup before the device can be accessed. In most cases, waiting 1 to 3 minutes is advised before accessing the device. Most devices will not respond to a selection immediately after a download operation.

If a disk device determines that a recalibration is necessary, the drive may be unavailable for up to 10 minutes. During this sequence, you can usually issue the Test Unit Ready ( tur ) command to determine if the calibration has completed. If the calibration sequence is interrupted, for example by a bus reset, device reset, or by power cycling, the recalibration will be restarted when the drive is powered up.

Do not power cycle devices during the download operation. Doing so may render your drive useless.

The following examples show the download command:

scu> download ???.fup save
Downloading & Saving Firmware File '???.fup' of 131076 bytes...
scu> download ???.fup save segment 
Downloading File '???.fup' of 131076 bytes in 8192 byte
                                                   segments...
Download completed successfully, now saving the microcode...
scu> download ???.fup save segment 32k 
Downloading File '???.fup' of 131076 bytes in 32768 byte
                                                    segments...
Download completed successfully, now saving the microcode...

format [density density-type] [defects defect-list]

This command formats both hard and flexible disk media. Since this command modifies the disk media, the full command name must be entered to be recognized.

The density-type parameter specifies the density type for flexible disk media.

The defect-list parameter can be all, primary, or none. The default is to format with all known defects. If you use the default device /dev/cam to enter the scu utility and then use the set nexus command to set the device to format, the code associated with checking for mounted file systems fails. This failure avoids the possibility of accidentally formatting disks with mounted file systems.

read media [test-parameters]

This command performs read operations from the selected device. The command reads the device media and performs a data comparison of the data read. You must include test parameters that specify the media area to be read.

The examples that follow illustrate the use of the read command with several test-parameters:

scu> read media
scu: No defaults, please specify test parameters for
transfer...
scu> read media lba 100
Reading 1 block on /dev/rrz10c (RX23) using pattern
0x39c39c39...
scu> read media lba 100 pattern 0x12345678
Reading 1 block on /dev/rrz10c (RX23) using pattern
0x12345678...
scu: Data compare error at byte position 0
scu: Data expected = 0x78, data found = 0x39
scu> read media ending 100 compare off bs 10k
Reading 101 blocks on /dev/rrz10c (RX23)...
Reading blocks [ 0 through 19 ]...
Reading blocks [ 20 through 39 ]...
Reading blocks [ 40 through 59 ]...
Reading blocks [ 60 through 79 ]...
Reading blocks [ 80 through 99 ]...

reassign lba logical-block

This command allows you to reassign a defective block on a disk device. Since this command modifies the disk media, the full command name must be entered to be recognized.

test [ controller | drive | memory | selftest ]

This command performs tests on a controller by issuing send and receive diagnostic commands or write buffer and read buffer commands for memory testing to the selected device. If you issue the test command with no arguments, the utility performs a self test, which is supported by most controllers.

This command verifies the controller memory by using the SCSI Read and Write Buffer commands. Since most controllers accept only the Combined Header and Data Mode with a buffer ID and buffer offset of zero, these are the defaults, but may be overridden. By default, the full memory size returned in the Read Buffer header is written/read/verified, but this too may be overridden by specifying a smaller data limit or size.

You can use various parameters to control the test memory operation. Most devices do not require these optional parameters, but newer devices may require different parameters to access the controller data buffer.

The following notes apply to the parameters used with the test memory command:

The default buffer ID is restricted to 0, since this ID normally selects the controller data buffer.

The default buffer mode is 0 (selects Combined Header and Data Mode).

The default offset value is 0. The program automatically adjusts the memory data bytes being tested when this parameter is nonzero.

Because writing to the controller data buffer destroys data that may be valid for active I/O requests, do not use this command for disk devices with mounted file systems.

Refer to the vendor's SCSI programming manual for information on buffer IDs and buffer modes supported.

If the device does not support a Read Buffer command and/or the default parameters, an error message similar to the following is displayed:

scu> test memory
      Performing Controller Memory Diagnostics...
      Testing Controller Memory of 245760 bytes (Mode 0,
Offset 0)
      Testing 245760 bytes on [1/2/0] (TZK11) using pattern
0x39c39c39...
      scu: 'SCMD_WRITE_BUFFER' failed, EIO (5) - I/O error
      scu: Sense Key = 0x5 = ILLEGAL REQUEST -
                                    Illegal request or CDB
parameter,
           Sense Code/Qualifier = (0x24, 0) =
                                      Invalid field in cdb

The following examples show the test memory command:

% scu -f /dev/rrz11c
scu> test memory
Performing Controller Memory Diagnostics...
      Testing Controller Memory of 61376 bytes (Mode 0,
Offset 0)
      Testing 61376 bytes on /dev/rrz11c (RZ56) using pattern
0x39c39c39...
scu> test memory pattern 0x12345678 size 50k
      Performing Controller Memory Diagnostics...
      Testing Controller Memory of 61376 bytes (Mode 0,
Offset 0)
      Testing 51200 bytes on /dev/rrz11c (RZ56) using pattern
0x12345678...scu> test memory passes 5
 Performing Controller Memory Diagnostics...
      Testing Controller Memory of 61376 bytes (Mode 0,
Offset 0)
      Testing 61376 bytes on /dev/rrz11c (RZ56) using pattern
0x39c39c39...
      Testing 61376 bytes on /dev/rrz11c (RZ56) using pattern
0x00ff00ff...
      Testing 61376 bytes on /dev/rrz11c (RZ56) using pattern
0x0f0f0f0f...
      Testing 61376 bytes on /dev/rrz11c (RZ56) using pattern
0xc6dec6de...
      Testing 61376 bytes on /dev/rrz11c (RZ56) using pattern
0x6db6db6d...
scu> show memory
The Controller Memory Size is 245760 (0x3c000) bytes.
scu> test memory mode 2
Performing Controller Memory Diagnostics...
      Testing Controller Memory of 245760 bytes (Mode 2,
Offset 0)
      Testing 245760 bytes on [1/2/0] (TZK11) using pattern
0x39c39c39...

write [media test-parameters]

The media argument writes to the device media by using various data patterns. The patterns default to 0x39c39c39 for the first pass, 0xc6dec6de for the second, and so on as shown in the last example. You must specify transfer parameters that specify the media area to be written.

The following examples show the write media command:

scu> write media
 No defaults, please specify test parameters for
transfer...

scu> write media lba 100
Writing 1 block on /dev/rrz10c (RX23) with pattern
0x39c39c39...
scu> write media starting 100 ending 250
Writing 151 blocks on /dev/rrz10c (RX23) with pattern
0x39c39c39...
scu> write media starting 2800 limit 1m bs 10k
Writing 80 blocks on /dev/rrz10c (RX23) with pattern
0x39c39c39...
Writing blocks [ 2800 through 2819 ]...
Writing blocks [ 2820 through 2839 ]...
Writing blocks [ 2840 through 2859 ]...
Writing blocks [ 2860 through 2879 ]...
scu> write media lba 2879 passes 5
Writing 1 block on /dev/rrz10c (RX23) with pattern
0x39c39c39...
Writing 1 block on /dev/rrz10c (RX23) with pattern
0xc6dec6de...
Writing 1 block on /dev/rrz10c (RX23) with pattern
0x6db6db6d...
Writing 1 block on /dev/rrz10c (RX23) with pattern
0x00000000...
Writing 1 block on /dev/rrz10c (RX23) with pattern
0xffffffff...