SCSICMD(8) BSD System Manager's Manual SCSICMD(8)NAMEscsicmd - SCSI disk labeller and diagnostic
SYNOPSISscsicmd [-f device] -l [-Z]
scsicmd-a asc/ascq
scsicmd [-T command-table] [-f device] -c command [-P
parameter=value,...] [-p parameter,...] [-v parameter,...] [-dx]
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. The last form is used to run SCSI commands on a
specified device as a diagnostic. With the last form, options may be re-
peated and their order is significant. The options are as follows:
-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. This service is now pro-
vided by the system, so ASC translation is probably unneeded now.
-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.
-d Print numeric parameters in decimal (the default). This flag may
be repeated to change the output radix between -p operations.
-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.
-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.
-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.
-T Choose a different command table file. The default is
/usr/share/misc/scsicmdtab. Scsicmd reads this table to get its
list of SCSI commands and associated structures. A detailed de-
scription of this file appears below.
-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.
-Z By default on zone recorded disks, scsicmd generates labels that
use only a single (huge) track per cylinder. Since the system
can't optimize the rotational layout of these disks, these labels
do the next best thing and take advantage of the buffering in
most modern disks. It is not necessary for the geometry in the
label to bear a direct relationship to the physical geometry of
the disk, although this is desirable on disks with a fixed geome-
try (not zone recorded). The -Z flag causes scsicmd to generate
labels using the median cylinder size, well as print the sizes of
each zone. The scanning process that scsicmd uses with -Z has
been known to hang disks, and using the median cylinder size can
produce unreasonable rotational layouts on most cylinders of a
zone recorded disk, so the -Z flag is not recommended.
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.
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 MODE SELECT
code reprograms a few fields in the MODE SENSE buffer to make them appro-
priate for MODE SELECT. Specifically, the operation code in the CDB is
set to MODE SELECT, and the dbd, pc, pcode and mdl fields are cleared,
while the pf field is set to 1 if pcode was previously set, and the
length field is set to the previous value of the mdl field plus 1. What
this means is that you can use MODE SENSE (msen) to read a mode page,
then use MODE SELECT (msel) to alter the mode page parameter(s) that you
want to change, without worrying about the other differences between a
MODE SENSE buffer and a MODE SELECT buffer.
SCSI COMMAND TABLE
The SCSI command table file /usr/share/misc/scsicmdtab tells scsicmd how
to initialize and display SCSI data. The table describes each SCSI com-
mand that scsicmd knows about and tells how to interpret the buffers that
are associated with it. The table is written using a simple descriptive
programming language.
The language is oriented around keywords. Keywords are fixed strings
consisting of upper-case letters and underscores. Keywords like COMMAND
begin every description of every unit. Some keywords are attribute or
type keywords and appear later in a unit.
Keywords are sometimes followed by numeric parameters. Numbers have C
syntax: hexadecimal numbers are prefixed with `0x', octal numbers are
prefixed with `0', and other numbers are treated as decimal numbers.
Some numeric parameters may be ranges of numbers, consisting of a low
value, a hyphen `-', and a high value. White space (spaces or tabs) may
appear in ranges.
Some keywords may be followed by strings. Strings are any non-keyword,
non-numeric text that runs to a delimiter character, where delimiters are
colons `:', parentheses `()', line breaks or comments. Delimiters are
just `syntactic sugar'; all delimiters are equivalent, and sequences of
delimiters and white space are treated as a single delimiter. Delimiters
only differ from white space in their ability to break strings.
Comments start with a hash-mark `#' character and run to the end of a
line.
Each SCSI command is defined by a COMMAND description followed by BUFFER
descriptions. The BUFFER descriptions are broken down into BYTE and (if
necessary) BIT descriptions. Following the SCSI standard, bytes have
big-endian order while bits have little-endian order -- the most signifi-
cant bit is the highest numbered bit in a field, while the most signifi-
cant byte is the lowest numbered byte in a field. When bit fields cross
byte boundaries, they wrap at the 0 bit. Here is the syntax:
COMMAND: description (abbreviation) [: command-type]
This directive begins a unit that describes a command. The
description and abbreviation are the text that gets printed with -c
all; the abbreviation is used to select the command with -c
abbreviation. The command-type is optional and tells scsicmd what
sort of operation to perform:
CMD_READ Read a fixed-length buffer (or no data at all).
This operation is the default.
CMD_WRITE Write a buffer.
CMD_READ_VAR Read a variable length buffer. Some SCSI commands
like INQUIRY have variable length buffers. Scsicmd
will limit the number of bytes of buffer that it
prints on output to the value of addlen plus the
offset of the byte following the addlen field.
CMD_READ_DATA Read unstructured data and write it to standard out-
put. Scsicmd can execute SCSI READ commands to dump
data. The amount of data dumped is controlled by
the `tl' or transfer length field in the CDB.
CMD_SELECT Tell scsicmd to share buffers with the MODE SENSE
command. Scsicmd uses a few tricks to make it pos-
sible to use data from a MODE SENSE command as input
to a MODE SELECT command.
CMD_SENSE Tell scsicmd to share buffers with the MODE SELECT
command.
CMD_RS Use a special ioctl(2) to recover REQUEST SENSE data
from the last command that failed on this logical
unit.
CDB: description (abbreviation) [: size]
The CDB directive is exactly the same as the BUFFER directive, but
the explicit name makes that buffer's function more obvious. The
first buffer of a command is always used for the CDB; subsequent
buffers are controlled by the command type.
BUFFER [+ offset]: description (abbreviation) [: size]
There is at least one and possibly two pieces of memory associated
with each SCSI command. These pieces of memory are broken down in-
to `buffers', which are descriptions of the bytes and bits con-
tained at a particular offset in a chunk of memory.
The obligatory piece of memory is the CDB or command descriptor
block. The CDB is always described by exactly one buffer, and that
buffer must be listed first.
If a command reads or writes memory, then the second and subsequent
BUFFER directives tell how to break that memory down. Buffers are
assumed to start at offset zero in the memory chunk, but the offset
may be provided explicitly. The size of the memory chunk is the
explicit size of the first buffer, or if no size is given, 256
bytes. Non-described bits are assumed to be 0 when writing, and
they can't be printed on reading. More than one buffer may be pro-
vided for decomposing a given chunk of memory at the same offset;
this has the effect of providing alternative views of the same mem-
ory.
BYTE[S] range [: description (abbreviation) [: format] [: value]]
This directive describes a byte or byte range in a buffer. The
mandatory argument may be a single number or a range, describing
the offset of the byte or bytes within the buffer. If a descrip-
tion for a byte or byte range is provided, scsicmd assumes that the
description covers all of the bits in the entire range of bytes.
A format key may be provided to cause the output for the field to
be processed specially:
FORMAT_DEFAULT Print the value of the field as a number (decimal
or hexadecimal).
FORMAT_STRING Print the value of the field as a string. Trailing
blanks are stripped.
FORMAT_CODE Print the value of the field as a special field-de-
pendent code. Scsicmd uses this format key as a
clue to check command dependent and field name de-
pendent routines to print certain values in a spe-
cial way. Currently three fields in INQUIRY and
two fields in REQUEST SENSE are translated this
way.
(The directives BYTE and BYTES are treated exactly the same; use
the one that looks best.)
If there is no description, then scsicmd assumes that subsequent
BIT directives will cover bits in the given byte.
BIT[S] range: description (abbreviation) [: format] [: value]
The BIT or BITS directive is just like the BYTE directive, but it
covers bits or ranges of bits in a given byte. One or more BIT di-
rectives must be preceded by a BYTE directive giving the offset of
the byte that contains the bits.
BITLENGTH number: description (abbreviation) [: format] [: value]
This directive is much like the BIT directive, but it is used to
describe bit fields that cross byte boundaries. The SCSI standard
defines such bitfields in a very restrictive way. The bitfield
fills the low bits of the first byte, then fills whole subsequent
bytes. For example, a field of `BITLENGTH 21' will occupy the low
5 bits (21 mod 8) of the given byte, plus the next 2 bytes (21 div
8).
ENVIRONMENT
SCSI The default device filename. It may be overridden with -f.
FILES
/usr/share/misc/scsicmdtab
Default command table file.
EXAMPLES
How to label a SCSI disk using scsicmd directly:
# 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.
# disksetup -R sd0 /etc/label.sd0 \
/usr/bootstraps/ahaboot /usr/bootstraps/bootaha
How to format a disk:
# scsicmd-f /dev/rsd0c -c fu
How to list all the supported SCSI commands:
# scsicmd-c all
...
How to list all the supported MODE SENSE pages:
# scsicmd-c msen -v all
...
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
How to turn automatic compression off on tape drives that support it:
# scsicmd-f /dev/nrst0 -c msen -P pcode=0x0f -p none \
-c msel -P dce=0 -p none
SEE ALSOsd(4), sg(4), st(4), disksetup(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.
BUGS
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 driver permits only a certain small subset of all the SCSI commands.
String values in -P can't contain commas.
-p none is clumsy.
BSD/OS November 10, 1997 6
