freebsd-nq/sbin/scsi/scsi.8

.\"
.\" Written By Julian ELischer
.\" Copyright julian Elischer 1993.
.\" Permission is granted to use or redistribute this file in any way as long
.\" as this notice remains. Julian Elischer does not guarantee that this file 
.\" is totally correct for any given task and users of this file must 
.\" accept responsibility for any damage that occurs from the application of this
.\" file.
.\" 
.\" (julian@tfs.com julian@dialix.oz.au)
.\" User SCSI hooks added by Peter Dufault:
.\" 
.\" Copyright (c) 1994 HD Associates
.\" (contact: dufault@hda.com)
.\" All rights reserved.
.\" 
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. The name of HD Associates
.\"    may not be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY HD ASSOCIATES ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL HD ASSOCIATES BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\" 
.\"
.\"	$Id: scsi.8,v 1.16 1998/01/03 10:11:38 brian Exp $
.\"
.Dd October 11, 1993
.Dt SCSI 8
.Os BSD 4
.Sh NAME
.Nm scsi
.Nd program to assist with scsi devices
.Sh SYNOPSIS
.Nm scsi
.Fl f Ar device
.Fl d Ar debug_level
.Nm scsi
.Fl f Ar device
.Fl z Ar seconds
.Op Fl v
.Nm scsi
.Fl f Ar device
.Fl m Ar page
.Op Fl P Ar pc
.Op Fl e
.Nm scsi
.Fl f Ar device
.Fl p
.Op Fl b Ar bus
.Op Fl l Ar lun
.Nm scsi
.Fl f Ar device
.Fl r
.Op Fl b Ar bus
.Op Fl t Ar targ
.Op Fl l Ar lun
.Nm scsi
.Fl f Ar device
.Fl c Ar cmd_fmt
.Op Ar arg0 ... argn
.Op Fl s Ar seconds
.Op Fl v
.Fl o Ar count out_fmt
.Op Ar arg0 ... argn
.Fl i Ar count in_fmt
.Sh DESCRIPTION
The
.Nm scsi
program is used to send commands to a scsi device. It is also
a sample usage of the user level SCSI commands.
.Pp
The
.Fl f
option must be specified, and
.Ar device
must be the name of a functional SCSI device.  If the device is a
disk device, it should be the control device,
.Pq for example Pa /dev/rsd0.ctl .
Use the
.Fl p
option with the
.Sq super scsi
device to reprobe a bus where there are currently no valid devices
attached.
.Pp
The
.Fl d
option sets the SCSI kernel debug level.  The kernel must have been compiled
with the
.Dv SCSIDEBUG
option.  See
.Pa /sys/scsi/scsi_debug.h
to figure out what to set the kernel debug level to.
.Pp
The
.Fl z
option freezes all activity on all SCSI busses for a given number of
seconds.  If
.Fl v
is also specified then a BEL character is sent to the standard
output at the start and finish of the bus freeze.
This requires that the kernel be built with the
.Dv SCSI_FREEZE
kernel option.
This kernel code is not committed yet.
.Pp
The
.Fl m
option is used to read a device mode page.  The file
.Pa /usr/share/misc/scsi_modes
is read to look at for how to interpret the mode data.  The environment
variable
.Ev SCSI_MODES
can specify a different file to use.
.Pp
The
.Fl P
option can be used to specify a page control field.  The page control
fields are:
.Pp
.Bl -tag -width xxxx -indent offset -compact
.It 0
Current Values
.It 1
Changeable Values
.It 2
Default Values
.It 3
Saved Values
.El
.Pp
The
.Fl e
option permits you to edit the fields.  It will use the editor specified
by your
.Ev EDITOR
environment variable.  To store changes permanently, 
edit page control 3 using the
.Fl P
option.
.Pp
The
.Fl p
option can be used against the
.Sq super scsi
device
.Pa /dev/ssc
to probe all devices with a given SCSI lun on a given SCSI bus.
The bus can be selected with the
.Fl b
option and the default is 0.
The lun can be selected with the
.Fl l
option and the default is 0.
.Pp
The
.Fl r
option can be used to reprobe all SCSI devices on all SCSI busses that
were present at boot-time.  See
.Xr scsi 4
for a description of fixed scsi devices.
.Pp
The
.Fl c
option permits you to send user level SCSI commands specified on
the command line to a
device.  The command is sent using the
.Dv SCIOCCOMMAND
ioctl, so the
device you are accessing must permit this ioctl. See
.Xr scsi 4
for full details of which minor devices permit the ioctl, and
.Xr scsi 3
for the full details on how to build up the commands and data phases
using the format arguments.
.Pp
.Fl v
turns on more verbose information.
.Pp
.Fl s
sets the command timeout in seconds.  The default is two seconds.
.Pp
.Fl c Ar cmd_fmt
specifies the command as described in
.Xr scsi 3 "."
The additional arguments provide values for any variables
specified in the command format.  Note that the arguments to the
.Fl c
option are hexadecimal numbers, while all normal arguments on the
command-line are subject to the common
.Dq C
number notation.
.Pp
.Fl o 
.Ar count
.Ar out_fmt
.Op Ar arg0 ... argn
indicates that this is a data out command (i.e., data will be sent from
the system to the device) with
.Fr count
bytes of data. The data out is built up using the facilities described in
.Xr scsi 3
using the provided arguments to fill in any integer variables.
.Ar out_fmt
can be specified as a hyphen ("-") to indicate that the
.Ar count
bytes of data should be read from the standard input.
.Pp
.Fl i Ar count Ar in_fmt
indicates that this is a data in command (i.e., data will be read from
the device into the system) with
.Ar count
bytes of data read in.  The information is extracted according to
.Ar in_fmt
using the facilities described in
.Xr scsi 3
and displayed on the standard output.
.Ar in_fmt
can be specified as a hyphen ("-") to indicate that the
.Ar count
bytes of data input should be written to the standard output.
.Sh EXAMPLES
To verify that the device type for the disk
.Pa /dev/rsd0c
is 0 (direct access device):
.Bd -literal -offset indent
root# scsi -f /dev/rsd0c -c "12 0 0 0 40 0" -i 64 "*b3 b5" 0
.Ed
.Pp
To do an inquiry to
.Pa /dev/rsd2c :
.Bd -literal -offset indent
root# scsi -f /dev/rsd2c -c "12 0 0 0 v 0" 0x40 -i 64 \e
      "s8 z8 z16 z4" 
.Ed
.Pp
To edit mode page 1 (the Read-Write Error Recovery Page)
on
.Pa /dev/rsd2c ,
and store it permanently on the
drive:
.Bd -literal -offset indent
root# scsi -f /dev/rsd2c -m 1 -e -P 3
.Ed
.Pp
To simply re-probe the first scsi bus:
.Bd -literal -offset indent
root# scsi -f /dev/ssc -p
.Ed
.Pp
.Sh ENVIRONMENT
The
.Ev SU_DEBUG_OUTPUT
variable can be set to a file to send debugging
output to that file.
.Pp
The
.Ev SU_DEBUG_LEVEL
variable can be set to a non-zero integer to increase
the level of debugging.  Currently this is a on or off thing; it should
perhaps use the ioctl to set the debug level in the kernel and then set
it back to zero at program exit.
.Pp
The
.Ev SU_DEBUG_TRUNCATE
variable can be set to an integer to limit the
amount of data phase output sent to the debugging file.
.Pp
The
.Ev EDITOR
variable determines the editor to use for the mode editor.
.Sh SEE ALSO
.Xr scsi 3 ,
.Xr scsi 4 ,
.Xr ssc 4
.Sh BUGS
.Pp
Some devices respond to an inquiry for all LUNS.  This will cause them
to come on line to 8 times during reprobe to different logical units.
.Pp
The
.Fl i
option to do an inquiry went away in
.Fx 2.1 .
The new facilities
provided by
.Fl c
supercede that.
.Pp
Check your permissions carefully.
.Ql scsi -f /dev/rsd0c -c "4 0 0 0 0 0
permits anyone who can open
.Pa /dev/rsd0c
to format the disk drive.  This must be changed to
at least require write access to the drive.
.Sh HISTORY
The
.Nm scsi
command appeared in 386BSD 0.1.2.4 to support the new reprobe
and user SCSI commands.  It first appeared in 
.Tn FreeBSD
in
.Fx 2.0.5 .