SCSICMD(8) BSD System Manager's Manual SCSICMD(8)
NAME
scsicmd - SCSI disk labeller and diagnostic
SYNOPSIS
scsicmd [-f device] -l
scsicmd -a asc/ascq
scsicmd [-f device] -c command [-P parameter=value,...] [-d] [-p
parameter,...] [-v parameter,...] [-x]
DESCRIPTION
The first form of the scsicmd command is used to generate a default disk
label for a SCSI disk, sending requests to the drive to determine its ge-
ometry. The second form provides a convenient translation service for
ASC and ASCQ codes produced by the SCSI driver. The last form is used to
run SCSI commands on a specified device as a diagnostic. With the second
form, options may be repeated and their order is significant. The op-
tions are as follows:
-f Open the named device file for SCSI operations. When repeated,
the current device is closed and the new one is opened. If the
environment variable SCSI is set, the program performs an implic-
it -f $SCSI when it starts up.
-l Probe a SCSI disk for its geometry parameters and send an ASCII
version of a disk label to the standard output. Scsicmd is gen-
erally very conservative in its assumptions, especially when
dealing with cylinder and sector/track counts. Commentary on the
progress of probing appears on the standard error. If scsicmd
can't elucidate particular drive parameters, it will prompt for
them.
-a For a given ASC or ASC/ASCQ code, print an English translation
from the SCSI-2 standard. The ASC should be a number in C nota-
tion (decimal, octal or hex); if an ASCQ is provided, it should
be appended to the ASC after a slash.
-c Set the current SCSI command. Parameter lists which follow are
interpreted in the context of this command. The special command
all lists all of the available commands (in parentheses following
their descriptions); it does not set the command context. The -c
flag may be repeated to change the command context.
-P Set parameters to values. Parameters are named fields in SCSI da-
ta structures. A parameter=value pair sets a field in a SCSI da-
ta structure to the specified value, given in decimal, hex or oc-
tal using C notation. Values wider than a byte are translated to
big-endian byte order. High bits are truncated to make values
fit. If the =value is omitted, a value of 1 is assumed. Multi-
ple parameter/value pairs may be entered separated by commas.
Certain fields are specified in the SCSI standard as containing
strings rather than numbers; the value for such a parameter is
treated as a string.
-d Print numeric parameters in decimal (the default).
-p Execute a command and print the resulting parameters using the
comma-separated parameter list. The special parameter all prints
all of the named fields associated with the current command. The
special parameter none inhibits printing; this is useful for com-
mands which don't return any data. A parameter which matches the
name of a buffer page (see below) will cause parameters in that
page to be printed. If no -p or -v flag is given, scsicmd per-
forms an implicit -p none after processing all its arguments.
-v Verify fields without executing a command. This is useful for
getting lists of parameter or buffer page names. The special pa-
rameter all prints all of the named fields associated with the
current command. The special parameter pages prints just the
names of the individual buffer pages. A parameter which matches
the name of a buffer page will cause parameters in that page to
be printed.
-x Print numeric fields in hexadecimal. This flag may be alternated
with -d to change printing format dynamically.
When scsicmd is used as a diagnostic, its arguments are treated as a
small interpreted language. A -c flag sets the context, then subsequent
-P and -p flags set and obtain values, respectively. More than one -c
flag may be used so that more than one SCSI command can be issued with a
single invocation of scsicmd. Arguments are processed sequentially from
left to right.
Each command is associated with one or more named buffer pages. Buffer
pages contain the bits which are sent to and retrieved from the SCSI de-
vice. The SCSI CDB is always the first buffer page and always has the
name cdb. Other pages are specific to the command. Some pages have a
variable length that depends on an internal field returned from the de-
vice; scsicmd will not print fields which are outside the page length.
Each buffer page contains a number of named fields. Scsicmd inserts and
extracts values from these fields and provides names and descriptions.
Most fields contain numbers; these are printed in decimal or hex. Some
fields contain strings, which are stripped of trailing blanks and other-
wise printed literally. Some numeric fields are translated into English
phrases for clarity; for example, sense keys are looked up in a table so
that a value of ``5'' is printed as ``illegal request''. Field names and
page names are generally constructed by using either the abbreviation
chosen by the SCSI standard or an acronym built from the first letters of
a multi-word description in the standard. Internally, scsicmd represents
pages and parameters as large tables of offsets, sizes and names. To add
support for new commands, it is necessary to install a new table and
sometimes add some code for printing fields specially.
Scsicmd handles one pair of SCSI commands specially. The mode sense
(msen) and mode select (msel) commands share buffer pages, to make it
easy to get a page, modify it, and write it back out.
The underlying mechanism used by scsicmd is a set of SCSI driver ioctl(2)
calls. The program places the driver in ``format mode'', submits a com-
mand descriptor block using ioctl(), performs a read(2) or write(2) to
execute the command and transfer any data, then terminates format mode.
ENVIRONMENT
SCSI The default device filename. It may be overridden with -f.
EXAMPLES
How to label a SCSI disk:
# scsicmd -f /dev/rsd0c -l > /etc/label.sd0
Scanning for logical cylinder sizes...
Zone 1: 1626 cylinders, 427 sectors per cylinder
Total number of logical cylinders found in scan (1626)
differs from reported drive parameters (1629+3);
assuming 1626+6 cylinders for disk label.
# disklabel -R -r sd0 /etc/label.sd0 \
/usr/mdec/ahaboot /usr/mdec/bootaha
How to translate ASC/ASCQ codes:
# scsicmd -a 0x11/0xc
unrecovered read error, recommend rewrite the data
How to read the disk format device page:
# scsicmd -f /dev/rsd0c -c msen -P pcode=3 -p dfdp
parameters saveable (ps): 1
mode page code (mpcode): 3
mode page length (mpl): 22
tracks per zone (tpz): 8
alternate sectors per zone (aspz): 5
alternate tracks per zone (atpz): 0
alternate tracks per logical unit (atplu): 24
sectors per track (spt): 54
data bytes per physical sector (dbpps): 512
interleave (il): 1
track skew factor (tsf): 0
cylinder skew factor (csf): 16
soft sectoring enable control (ssec): 0
hard sectoring enable control (hsec): 1
removable media (rmb): 0
surfaces instead of cylinders (surf): 0
DIAGNOSTICS
Among its many messages about consistency of arguments and so on, scsicmd
will print ``can't enable SCSI command mode'' when it isn't run as root,
and will print a message beginning ``scsi status:'' if a command fails
for some reason.
SEE ALSO
sd(4), st(4), disklabel(8)
STANDARDS
American National Standard X3.131-1986, Small Computer System Interface
(SCSI-1)
American National Standard X3.131-1991 (SCSI-2)
HISTORY
Inspired by the scsiinfo program by Van Jacobson of Lawrence Berkeley
Laboratories.
AUTHORS
Donn Seeley, BSDI
BUGS
A live, busy disk can run into trouble if scsicmd is executed on it. Try
to run scsicmd only when the system is single-user or quiescent.
Currently there is no way to select a target independently from a device.
This means that it is impossible to access unconfigured targets.
If you want to use the diagnostic mode, you generally must start with a
copy of the SCSI standard. The meanings of the various fields are de-
scribed only in that document.
Tape devices in diagnostic mode don't always do what you expect. You
must have a tape loaded when you run scsicmd, and the driver can execute
a couple of mode sense and/or mode select commands before turning over
control to scsicmd.
Command and parameter abbreviations are ugly. The rules are inconsistent
because of the need to reduce ambiguity. It was felt that acronyms were
less awkward than using minimal string abbreviations of multi-word field
names.
There is no way to access host adapter commands, hence it isn't possible
to alter the DMA burst rate and other host adapter parameters.
The parameter tables are compiled in, rather than read in from a file.
The driver permits only a certain small subset of all the SCSI commands.
String values in -P can't contain commas.
-p none is kinda clumsy.
BSD/386 March 27, 1993 4