Camcontrol - A utility for configuring/manipulating the CAM subsystem

Submitted by:	"Kenneth D. Merry" <ken@plutotech.com>

1 files changed, 437 insertions, 0 deletions

diff --git a/sbin/camcontrol/camcontrol.8 b/sbin/camcontrol/camcontrol.8
new file mode 100644
index 0000000..43eee6c
--- /dev/null
+++ b/sbin/camcontrol/camcontrol.8
@@ -0,0 +1,437 @@
+.\"
+.\" Copyright (c) 1998 Kenneth D. Merry.
+.\" 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 the author may not be used to endorse or promote products
+.\"    derived from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``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 THE AUTHOR OR CONTRIBUTORS 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$
+.\"
+.Dd September 14, 1998
+.Dt CAMCONTROL 8
+.Os FreeBSD 3.0
+.Sh NAME
+.Nm camcontrol
+.Nd CAM control program
+.Sh SYNOPSIS
+.Nm camcontrol
+.Aq command
+.Op generic args
+.Op command args
+.Nm camcontrol
+devlist
+.Op Fl v
+.Nm camcontrol
+periphlist
+.Op Fl n Ar dev_name
+.Op Fl u Ar unit_number
+.Nm camcontrol
+tur
+.Op generic args
+.Nm camcontrol
+inquiry 
+.Op generic args
+.Op Fl D
+.Op Fl S
+.Op Fl R
+.Nm camcontrol
+start
+.Op generic args
+.Nm camcontrol
+stop
+.Op generic args
+.Nm camcontrol
+eject
+.Op generic args
+.Nm camcontrol
+rescan
+.Aq bus Ns Op :target:lun
+.Nm camcontrol
+defects
+.Op generic args
+.Aq Fl f Ar format
+.Op Fl P
+.Op Fl G
+.Nm camcontrol
+modepage
+.Op generic args
+.Aq Fl m Ar page
+.Op Fl P Ar pagectl
+.Op Fl e
+.Op Fl d
+.Nm camcontrol
+cmd
+.Op generic args
+.Aq Fl c Ar cmd Op args
+.Op Fl i Ar len Ar fmt
+.Bk -words
+.Op Fl o Ar len Ar fmt Op args
+.Ek
+.Nm camcontrol
+debug
+.Op Fl I
+.Op Fl T
+.Op Fl S
+.Aq all|off|bus Ns Op :target Ns Op :lun
+.Sh DESCRIPTION
+.Nm camcontrol
+is a utility designed to provide a way for users to access and control the
+.Tn FreeBSD
+CAM subsystem.
+.Pp
+.Nm camcontrol
+can cause a loss of data and/or system crashes if used improperly.  Even
+expert users are encouraged to excercise caution when using this command.
+Novice users should stay away from this utility.
+.Pp
+.Nm camcontrol
+has a number of primary functions, most of which take some generic
+arguments:
+.Bl -tag -width 01234567890123
+.It Fl C Ar count
+SCSI command retry count.  In order for this to work, error recovery
+.Po
+.Fl E
+.Pc
+must be turned on.
+.It Fl E
+Instruct the kernel to perform generic SCSI error recovery for the given
+command.  This is needed in order for the retry count
+.Po
+.Fl C
+.Pc
+to be honored.  Other than retrying commands, the generic error recovery in
+the code will generally attempt to spin up drives that are not spinning.
+It may take some other actions, depending upon the sense code returned from
+the command.
+.It Fl n Ar dev_name
+Specify the device type to operate on.  The default is
+.Em da .
+.It Fl t Ar timeout
+SCSI command timeout in seconds.  This overrides the default timeout for
+any given command.
+.It Fl u Ar unit_number
+Specify the device unit number.  The default is 0.
+.It Fl v
+Be verbose, print out sense information for failed SCSI commands.
+.El
+.Pp
+Primay command functions:
+.Bl -tag -width periphlist
+.It devlist
+List all physical devices (logical units) attached to the CAM subsystem.
+This also includes a list of peripheral drivers attached to each device.
+With the
+.Fl v
+argument, SCSI bus number, adapter name and unit numbers are printed as
+well.
+.It periphlist
+List all peripheral drivers attached to a given physical device (logical
+unit).
+.It tur
+Send the SCSI test unit ready (0x00) command to the given device.
+.Nm camcontrol
+will report whether the device is ready or not.
+.It inquiry
+Send a SCSI inquiry command (0x12) to a device.  By default,
+.Nm camcontrol
+will print out the standard inquiry data, device serial number, and
+transfer rate information.  The user can specify that only certain types of
+inquiry data be printed:
+.Bl -tag -width 1234
+.It Fl D
+Get the standard inquiry data.
+.It Fl S
+Print out the serial number.  If this flag is the only one specified,
+.Nm camcontrol
+will not print out "Serial Number" before the value returned by the drive.
+This is to aid in script writing.
+.It Fl R
+Print out transfer rate information.
+.El
+.It start
+Send the SCSI Start/Stop Unit (0x1B) command to the given device with the
+start bit set.
+.It stop
+Send the SCSI Start/Stop Unit (0x1B) command to the given device with the
+start bit cleared.
+.It eject
+Send the SCSI Start/Stop Unit (0x1B) command to the given device with the
+start bit cleared and the eject bit set.
+.It rescan
+Tell the kernel to scan the given bus (XPT_SCAN_BUS), or bus:target:lun
+(XPT_SCAN_LUN) for new devices or devices that have gone away.  The user
+may only specify a bus to scan, or a lun.  Scanning all luns on a target
+isn't supported.
+.It defects
+Send the SCSI READ DEFECT DATA (10) command (0x37) to the given device, and
+print out any combination of: the total number of defects, the primary
+defect list (PLIST), and the grown defect list (GLIST).
+.Bl -tag -width 01234567890
+.It Fl f Ar format
+The three format options are:
+.Em block ,
+to print out the list as logical blocks,
+.Em bfi ,
+to print out the list in bytes from index format, and
+.Em phys ,
+to print out the list in physical sector format.  The format argument is
+required.  Most drives support the physical sector format.  Some drives
+support the logical block format.  Many drives, if they don't support the
+requested format, return the data in an alternate format, along with sense
+information indicating that the requested data format isn't supported.
+.Nm camcontrol
+attempts to detect this, and print out whatever format the drive returns.
+If the drive uses a non-standard sense code to report that it doesn't
+support the requested format,
+.Nm camcontrol
+will probably see the error as a failure to complete the request.
+.It Fl G
+Print out the grown defect list.  This is a list of bad blocks that have
+been remapped since the disk left the factory.
+.It Fl P
+Print out the primary defect list.
+.El
+.Pp
+If neither
+.Fl P
+nor
+.Fl G
+is specified,
+.Nm camcontrol
+will print out the number of defects given in the READ DEFECT DATA header
+returned from the drive.
+.It modepage
+Allows the user to display and optionally edit a SCSI mode page.  The mode
+page formats are located in
+.Pa /usr/share/misc/scsi_modes .
+This can be overridden by specifying a different file in the
+.Ev SCSI_MODES
+environment variable.  The modepage command takes several arguments:
+.Bl -tag -width 012345678901
+.It Fl B
+Disable block descriptors for mode sense.
+.It Fl e
+This flag allows the user to edit values in the mode page.
+.It Fl m Ar mode_page
+This specifies the number of the mode page the user would like to view
+and/or edit.  This argument is mandatory.
+.It Fl P page_ctl
+This allows the user to specify the page control field.  Possible values are:
+.Bl -tag -width xxx -compact
+.It 1
+Current values
+.It 2
+Changeable values
+.It 3
+Default values
+.It 4
+Saved values
+.El
+.El
+.It cmd
+Allows the user to send an arbitrary SCSI CDB to any device.  The cmd
+function requires the
+.Fl c
+argument to specify the CDB.  Other arguments are optional, depending on
+the command type.  The command and data specification syntax is documented
+in
+.Xr cam 3 .
+NOTE:  If the CDB specified causes data to be transfered to or from the
+SCSI device in question, you MUST specify either
+.Fl i
+or
+.Fl o .
+.Bl -tag -width 01234567890123456
+.It Fl c Ar cmd Op args
+This specifies the SCSI CDB.  CDBs may be 6, 10, 12 or 16 bytes.
+.It Fl i Ar len Ar fmt
+This specifies the amount of data to read, and how it should be displayed.
+If the format is
+.Sq - ,
+.Ar len
+bytes of data will be read from the device and written to standard output.
+.It Fl o Ar len Ar fmt Op args
+This specifies the amount of data to be written to a device, and the data
+that is to be written.  If the format is
+.Sq - ,
+.Ar len
+bytes of data will be read from standard input and written to the device.
+.El
+.It debug
+Turn on CAM debugging printfs in the kernel.  This requires options CAMDEBUG 
+in your kernel config file.  WARNING:  enabling debugging printfs currently
+causes an EXTREME number of kernel printfs.  You may have difficulty
+turning off the debugging printfs once they start, since the kernel will be
+busy printing messages and unable to service other requests quickly.
+The debug function takes a number of arguments:
+.Bl -tag -width 012345678901234567
+.It Fl I
+Enable CAM_DEBUG_INFO printfs.
+.It Fl T
+Enable CAM_DEBUG_TRACE printfs.
+.It Fl S
+Enable CAM_DEBUG_SUBTRACE printfs.
+.It all
+Enable debugging for all devices.
+.It off
+Turn off debugging for all devices
+.It bus Ns Op :target Ns Op :lun
+Turn on debugging for the given bus, target or lun.  If the lun or target
+and lun are not specified, they are wildcarded.  (i.e., just specifying a
+bus turns on debugging printfs for all devices on that bus.)
+.El
+.El
+.Sh ENVIRONMENT
+The
+.Ev SCSI_MODES
+variable allows the user to specify an alternate mode page format file.
+.Pp
+The
+.Ev EDITOR
+variable determines which text editor 
+.Nm camcontrol
+starts when editing mode pages.
+.Sh FILES
+.Bl -tag -width /usr/share/misc/scsi_modes -compact
+.It Pa /usr/share/misc/scsi_modes
+is the SCSI mode format database.
+.It Pa /dev/xpt0 
+is the transport layer device.
+.It Pa /dev/pass*
+are the CAM application passthrough devices.
+.El
+.Sh EXAMPLES
+.Dl camcontrol eject -n cd -u 1 -v
+.Pp
+Eject the CD from cd1, and print SCSI sense information if the command
+fails.
+.Pp
+.Dl camcontrol tur
+.Pp
+Send the SCSI test unit ready command to da0.
+.Nm camcontrol
+will report whether the disk is ready, but will not display sense
+information if the command fails since the
+.Fl v
+switch was not specified.
+.Pp
+.Bd -literal -offset foobar
+camcontrol tur -n da -u 1 -E -C 4 -t 50 -v
+.Ed
+.Pp
+Send a test unit ready command to da1.  Enable kernel error recovery.
+Specify a retry count of 4, and a timeout of 50 seconds.  Enable sense
+printing (with the
+.Fl v
+flag) if the command fails.  Since error recovery is turned on, the
+disk will be spun up if it is not currently spinning.
+.Nm camcontrol
+will report whether or the disk is ready.
+.Bd -literal -offset foobar
+camcontrol cmd -n cd -u 1 -v -c "3C 00 00 00 00 00 00 00 0e 00" \e
+	-i 0xe "s1 i3 i1 i1 i1 i1 i1 i1 i1 i1 i1 i1"
+.Ed
+.Pp
+Issue a READ BUFFER command (0x3C) to cd1.  Display the buffer size of cd1,
+and display the first 10 bytes from the cache on cd1.  Display SCSI sense
+information if the command fails.
+.Pp
+.Bd -literal -offset foobar
+camcontrol cmd -n cd -u u -v -c "3B 00 00 00 00 00 00 00 0e 00" \e
+	-o 14 "00 00 00 00 1 2 3 4 5 6 v v v v" 7 8 9 8
+.Ed
+.Pp
+Issue a WRITE BUFFER (0x3B) command to cd1.  Write out 10 bytes of data,
+not including the (reserved) 4 byte header.  Print out sense information if
+the command fails.  Be very careful with this command, improper use may
+cause data corruption.
+.Pp
+.Dl camcontrol modepage -n da -u 3 -m 1 -e -P 3
+.Pp
+Edit mode page 1 (the Read-Write Error Recover page) for da3, and save the
+settings on the drive.  Mode page 1 contains a disk drive's auto read and
+write reallocation settings, among other things.
+.Pp
+.Dl camcontrol rescan 0
+.Pp
+Rescan SCSI bus 0 for devices that have been added, removed or changed.
+.Pp
+.Dl camcontrol rescan 0:1:0
+.Pp
+Rescan SCSI bus 0, target 1, lun 0 to see if it has been added, removed, or
+changed.
+.Sh SEE ALSO
+.Xr cam 3 ,
+.Xr pass 4 ,
+.Xr cam 9 ,
+.Xr xpt 9
+.Sh HISTORY
+The
+.Nm camcontrol
+command first appeared in
+.Fx 3.0 .
+.Pp
+The mode page editing code and arbitrary SCSI command code are based upon
+code in the old
+.Xr scsi 8
+utility and
+.Xr scsi 3
+library, written by Julian Ellischer and Peter Dufault.  The
+.Xr scsi 8
+first appeared in 386BSD 0.1.2.4, and first appeared in 
+.Tn FreeBSD
+in
+.Fx 2.0.5 .
+.Sh AUTHORS
+.An Kenneth Merry Aq ken@FreeBSD.ORG
+.Sh BUGS
+Most of the man page cross references don't exist yet.  This will be fixed
+soon.
+.Pp
+The code that parses the generic command line arguments doesn't know that
+some of the subcommands take multiple arguments.  So if, for instance, you
+tried something like this:
+.Bd -literal -offset foobar
+camcontrol -n da -u 1 -c "00 00 00 00 00 v" 0x00 -v
+.Ed
+.Pp
+The sense information from the test unit ready command would not get
+printed out, since the first
+.Xr getopt 3
+call in 
+.Nm camcontrol
+bails out when it sees the second argument to
+.Fl c
+.Po
+0x00
+.Pc ,
+above.  Fixing this behavior would take some gross code, or changes to the
+.Xr getopt 3
+interface.  The best way to circumvent this problem is to always make sure
+to specify generic
+.Nm camcontrol
+arguments before any command-specific arguments.
+.Pp
+It might be nice to add a way to allow users to specify devices by
+bus/target/lun or by device string (e.g. "da1").