Update the scsi(4) man page for CAM, and add in links so that it appears

as cam(4) as well.

This includes a description of all the generic CAM kernel options, as
well as a description of some of the CAM debugging printf options.

1 files changed, 185 insertions, 95 deletions

diff --git a/share/man/man4/scsi.4 b/share/man/man4/scsi.4
index 8ebd5b0..99a2ee54 100644
--- a/share/man/man4/scsi.4
+++ b/share/man/man4/scsi.4
@@ -1,4 +1,4 @@
-.\"	$Id$
+.\"	$Id: scsi.4,v 1.11 1997/02/22 13:24:41 peter Exp $
 .\" Copyright (c) 1996
 .\"	Julian Elischer <julian@freebsd.org>.  All rights reserved.
 .\"
@@ -24,12 +24,13 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd August 27, 1993
-.Dt SD 4
-.Os FreeBSD
+.Dd October 15, 1998
+.Dt SCSI 4
+.Os FreeBSD 3.0
 .Sh NAME
-.Nm scsi
-.Nd scsi system
+.Nm SCSI ,
+.Nm CAM
+.Nd CAM SCSI subsystem
 .Sh SYNOPSIS
 .Cd "controller scbus0"
 .Cd "controller scbus1 at ahc0"
@@ -37,26 +38,106 @@
 .Cd "controller scbus2 at ahc1 bus 1"
 .Cd "device cd0"
 .Cd "device ch0"
-.Cd "disk sd0"
-.Cd "tape st0"
+.Cd "device da0"
+.Cd "device pass0"
+.Cd "device pt0"
+.Cd "device sa0"
 .Cd "device ch1 at scbus0 target 4 unit 0"
+.Cd options		CAMDEBUG
+.Cd options		"CAM_DEBUG_BUS=-1"
+.Cd options		"CAM_DEBUG_TARGET=-1"
+.Cd options		"CAM_DEBUG_LUN=-1"
+.Cd options		"CAM_DEBUG_FLAGS=CAM_DEBUG_INFO|CAM_DEBUG_CDB"
+.Cd options		"CAM_MAX_HIGHPOWER=4"
+.Cd options		SCSI_NO_SENSE_STRINGS
+.Cd options		SCSI_NO_OP_STRINGS
+.Cd options		SCSI_DELAY=8000
 .Sh DESCRIPTION
-The
-.Em scsi
-system provides a uniform and modular system for the implementation
-of drivers to control various scsi devices, and to utilize different
-scsi host adapters through host adapter drivers. When the system probes the 
-.Em SCSI
+The CAM
+.Tn SCSI
+subsystem provides a uniform and modular system for the implementation
+of drivers to control various
+.Tn SCSI
+devices, and to utilize different
+.Tn SCSI
+host adapters through host adapter drivers. When the system probes the 
+.Tn SCSI
 busses, it attaches any devices it finds to the appropriate
-drivers. If no driver seems appropriate, then it attaches the device to the
-uk (unknown) driver so that user level scsi ioctls may
-still be performed against the device.
+drivers.  The
+.Xr pass 4
+driver, if it is configured in the kernel, will attach to all
+.Tn SCSI
+devices.
 .Sh KERNEL CONFIGURATION
-The option SCSIDEBUG enables the debug ioctl.
+There are a number of generic kernel configuration options for the
+CAM
+.Tn SCSI
+subsystem:
+.Bl -tag -width SCSI_NO_SENSE_STRINGS
+.It Dv CAMDEBUG
+This option enables the CAM debugging printf code.  This won't actually
+cause any debugging information to be printed out when included by itself.
+Enabling printouts requires additional configuration.  See below for
+details.
+.It Dv "CAM_MAX_HIGHPOWER=4"
+This sets the maximum allowable number of concurrent "high power" commands.
+A "high power" command is a command that takes more electrical power than
+most to complete.  An example of this (and the only command currently
+tagged as "high power") is the
+.Tn SCSI
+START UNIT command.  Starting a SCSI disk often takes significantly more
+electrical power than normal operation of the disk.  This option allows the
+user to specify how many concurrent high power commands may be outstanding
+without overloading the power supply on his computer.
+.It Dv SCSI_NO_SENSE_STRINGS
+This eliminates text descriptions of each
+.Tn SCSI
+Additional Sense Code and Additional Sense Code Qualifier pair.  Since this
+is a fairly large text database, eliminating it reduces the size of the
+kernel somewhat.  This is primarily necessary for boot floppies and other
+low disk space or low memory space environments.  In most cases, though,
+this should be enabled, since it speeds the interpretation of
+.Tn SCSI
+error messages.  Don't let the "kernel bloat" zealots get to you -- leave
+the sense descriptions in your kernel!
+.It Dv SCSI_NO_OP_STRINGS
+This disables text descriptions of each
+.Tn SCSI
+opcode.  This option, like the sense string option above, is primarily
+useful for environments like a boot floppy where kernel size is critical.
+Enabling this option for normal use isn't recommended, since it slows
+debugging of
+.Tn SCSI
+problems.
+.It Dv SCSI_DELAY=8000
+This is the
+.Tn SCSI
+"bus settle delay."  In CAM, it is specified in
+.Em milliseconds ,
+not seconds like the old
+.Tn SCSI
+layer used to do.  When the kernel boots, it sends a bus reset to each
+.Tn SCSI
+bus to tell each device to reset itself to a default set of transfer
+negotiations and other settings.  Most
+.Tn SCSI
+devices need some amount of time to recover from a bus reset.  Newer disks
+may need as little as 100ms, while old, slow devices may need much longer.
+If the
+.Dv SCSI_DELAY
+isn't specified, it defaults to 2 seconds.  The minimum allowable value for
+.Dv SCSI_DELAY
+is "100", or 100ms.  One special case is that if the
+.Dv SCSI_DELAY
+is set to 0, that will be taken to mean the "lowest possible value."  In
+that case, the
+.Dv SCSI_DELAY
+will be reset to 100ms.
+.El
 .Pp
 All devices and the SCSI busses support boot time allocation so that
 an upper number of devices and controllers does not need to be configured;
-.Em "device sd0"
+.Cd "device da0"
 will suffice for any number of disk drivers.
 .Pp
 The devices are either
@@ -67,72 +148,28 @@ so that they appear as the next available unused unit.
 .Pp
 To configure a driver in the kernel without wiring down the device use a
 config line similar to
-.Em "device ch0"
+.Cd "device ch0"
 to include the changer driver.
 .Pp
 To wire down a unit use a config line similar to
-.Em "device ch1 at scbus0 target 4 unit 0"
+.Cd "device ch1 at scbus0 target 4 unit 0"
 to assign changer 1 as the changer with SCSI ID 4,
 SCSI logical unit 0 on SCSI bus 0.
 Individual scbuses can be wired down to specific controllers with
 a config line similar to
-.Em "controller scbus0 at ahc0"
+.Cd "controller scbus0 at ahc0"
 which assigns scsi bus 0 to the first unit using the ahc driver.
 For controllers supporting more than one bus,
 the particular bus can be specified as in
-.Em "controller scbus3 at ahc1 bus 1"
+.Cd "controller scbus3 at ahc1 bus 1"
 which assigns scbus 1 to the second bus probed on the ahc1 device.
 .Pp
 When you have a mixture of wired down and counted devices then the
 counting begins with the first non-wired down unit for a particular
 type.  That is, if you have a disk wired down as
-.Em "disk sd1" ,
+.Em "device da1" ,
 then the first non-wired disk shall come on line as
-.Em sd2 .
-.Sh IOCTLS
-There are a number of ioctls that work on any 
-.Em SCSI
-device. They are defined in
-.Em sys/scsiio.h
-and can be applied against any scsi device that permits them.
-For the tape, it must be applied against the control
-device. See the manual page for each device type for more information about
-how generic scsi ioctls may be applied to a specific device.
-.Bl -tag -width DIOCSDINFO____
-.It Dv SCIOCRESET*
-reset a device.
-.It Dv SCIOCDEBUG
-Turn on debugging.. All scsi operations originating from this device's driver
-will be traced to the console, along with other information. Debugging is
-controlled by four bits, described in the header file. If no debugging is
-configured into the kernel, debugging will have no effect. 
-.Em SCSI
-debugging is controlled by the configuration option
-.Em SCSIDEBUG.
-.It Dv SCIOCCOMMAND
-Take a scsi command and data from a user process and apply them to the scsi
-device. Return all status information and return data to the process. The 
-ioctl will return a successful status even if the device rejected the
-command. As all status is returned to the user, it is up to the user
-process to examine this information to decide the success of the command.
-.It Dv SCIOCREPROBE
-Ask the system to probe the scsi busses for any new devices. If it finds
-any, they will be attached to the appropriate drivers. The search can be
-narrowed to a specific bus, target or lun. The new device may or may not
-be related to the device on which the ioctl was performed.
-.It Dv SCIOCIDENTIFY
-Ask the driver what it's bus, target and lun are.
-.It Dv SCIOCDECONFIG
-Ask the device to disappear. This may not happen if the device is in use.
-.El
-.Sh NOTES
-the generic scsi part of the system is still being mapped out.
-Watch this space for changes.
-.Pp
- A device by the name of su (scsi_user)
-(e.g  su0-0-0) will map bus, target and lun to  minor numbers. I have not
-yet decided yet whether this device will be able to open a device that is
-already controlled by an explicit driver.
+.Em da2 .
 .Sh ADAPTERS
 The system allows common device drivers to work through many different
 types of adapters. The adapters take requests from the upper layers and do
@@ -143,42 +180,95 @@ adapter. Most adapters can transfer 64KB in a single operation, however
 many can transfer larger amounts.
 .Sh TARGET MODE
 Some adapters support 
-.Em Target mode
+.Em target mode
 in which the system is capable of operating as a device, responding to
-operations initiated by another system. Target mode will be supported for
-some adapters, but is not yet complete for this version of the scsi system.
+operations initiated by another system. Target mode is supported for
+some adapters, but is not yet complete for this version of the CAM
+.Tn SCSI
+subsystem.
 .Sh FILES
 see other scsi device entries.
 .Sh DIAGNOSTICS
-When the kernel is compiled with option SCSIDEBUG, the SCIOCDEBUG ioctl 
-can be used to enable various amounts of tracing information on any 
+When the kernel is compiled with options CAMDEBUG, an XPT_DEBUG CCB can be
+used to enable various amounts of tracing information on any 
 specific device. Devices not being traced will not produce trace information.
-The four bits that make up the debug level, each control certain types
-of debugging information. 
-.Bl -tag -width THIS_WIDE_PLEASE
-.It Dv Bit 0
-Bit 0  shows all scsi bus operations including scsi commands,
-error information and the first 48 bytes of any data transferred.
-.It Dv Bit 1
-Bit 1 shows routines called.
-.It Dv Bit 2
-Bit 2 shows information about what branches are taken and often some
-of the return values of functions.
-.It Dv Bit 3
-Bit 3 shows more detailed information including DMA scatter-gather logs.
+There are currently four debugging flags that may be turned on:
+.Bl -tag -width CAM_DEBUG_SUBTRACE
+.It Dv CAM_DEBUG_INFO
+This debugging flag enables general informational printfs for the device
+or devices in question.
+.It Dv CAM_DEBUG_TRACE
+This debugging flag enables function-level command flow tracing.  i.e.
+kernel printfs will happen at the entrance and exit of various functions.
+.It Dv CAM_DEBUG_SUBTRACE
+This debugging flag enables debugging output internal to various functions.
+.It Dv CAM_DEBUG_CDB
+This debugging flag will cause the kernel to print out all
+.Tn SCSI
+commands sent to a particular device or devices.
+.El
+.Pp
+Some of these flags, most notably
+.Dv CAM_DEBUG_TRACE
+and
+.Dv CAM_DEBUG_SUBTRACE
+will produce kernel printfs in EXTREME numbers.  Because of that, they
+aren't especially useful.  There aren't many things logged at the
+.Dv CAM_DEBUG_INFO
+level, so it isn't especially useful.  The most useful debugging flag is
+the
+.Dv CAM_DEBUG_CDB
+flag.  Users can enable debugging from their kernel config file, by using
+the following kernel config options:
+.Bl -tag -width CAM_DEBUG_TARGET
+.It Dv CAMDEBUG
+This enables CAM debugging.  Without this option, users will not even be able
+to turn on debugging from userland via
+.Xr camcontrol 8 .
+.It Dv CAM_DEBUG_FLAGS
+This allows the user to set the various debugging flags described above
+in a kernel config file.  Flags may be ORed together if the user wishes to
+see printfs for multiple debugging levels.
+.It Dv CAM_DEBUG_BUS
+Specify a bus to debug.  To debug all busses, set this to -1.
+.It Dv CAM_DEBUG_TARGET
+Specify a target to debug.  To debug all targets, set this to -1.
+.It Dv CAM_DEBUG_LUN
+Specify a lun to debug.  To debug all luns, set this to -1.
 .El
+.Pp
+When specifying a bus, target or lun to debug, you
+.Em MUST
+specify all three bus/target/lun options above.  Using wildcards, you
+should be able to enable debugging on most anything.
+.Pp
+Users may also enable debugging printfs on the fly, if the
+.Dv CAMDEBUG
+option is their config file, by using the
+.Xr camcontrol 8
+utility.  See
+.Xr camcontrol 8
+for details.
 .Sh SEE ALSO
 .Xr aha 4 ,
 .Xr ahb 4 ,
+.Xr ahc 4 ,
 .Xr bt 4 ,
 .Xr cd 4 ,
 .Xr ch 4 ,
-.Xr sd 4 ,
-.Xr st 4 ,
-.Xr su 4 ,
-.Xr uha 4 ,
-.Xr uk 4
+.Xr da 4 ,
+.Xr pass 4 ,
+.Xr pt 4 ,
+.Xr sa 4 ,
+.Xr xpt 4 ,
+.Xr camcontrol 8
 .Sh HISTORY
-This
-.Nm
-system appeared in MACH 2.5 at TRW.
+The CAM
+.Tn SCSI
+subsystem first appeared in
+.Fx 3.0 .
+.Sh AUTHORS
+The CAM
+.Tn SCSI
+subsystem was written by Justin Gibbs and Kenneth Merry.
+