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.

share/man/man4/Makefile

@@ -14,6 +14,7 @@ MLINKS+=ipfirewall.4 ipacct.4 ipfirewall.4 ipfw.4 ipfirewall.4 ipaccounting.4
 MLINKS+=fpa.4 fea.4
 MLINKS+=yp.4 YP.4 yp.4 nis.4 yp.4 NIS.4
 MLINKS+=smp.4 SMP.4
+MLINKS+=scsi.4 cam.4
 
 # XXX NOT IMPORTED:	man4.hp300 man4.sparc man4.tahoe man4.vax
 SUBDIR=	 man4.i386 

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
+.Dd October 15, 1998
-.Dt SD 4
+.Dt SCSI 4
-.Os FreeBSD
+.Os FreeBSD 3.0
 .Sh NAME
-.Nm scsi
+.Nm SCSI ,
-.Nd scsi system
+.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 "device da0"
-.Cd "tape st0"
+.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
+The CAM
-.Em scsi
+.Tn SCSI
-system provides a uniform and modular system for the implementation
+subsystem provides a uniform and modular system for the implementation
-of drivers to control various scsi devices, and to utilize different
+of drivers to control various
-scsi host adapters through host adapter drivers. When the system probes the 
+.Tn SCSI
-.Em 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
+drivers.  The
-uk (unknown) driver so that user level scsi ioctls may
+.Xr pass 4
-still be performed against the device.
+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 .
+.Em da2 .
-.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.
 .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
+operations initiated by another system. Target mode is supported for
-some adapters, but is not yet complete for this version of the scsi system.
+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 
+When the kernel is compiled with options CAMDEBUG, an XPT_DEBUG CCB can be
-can be used to enable various amounts of tracing information on any 
+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
+There are currently four debugging flags that may be turned on:
-of debugging information. 
+.Bl -tag -width CAM_DEBUG_SUBTRACE
-.Bl -tag -width THIS_WIDE_PLEASE
+.It Dv CAM_DEBUG_INFO
-.It Dv Bit 0
+This debugging flag enables general informational printfs for the device
-Bit 0  shows all scsi bus operations including scsi commands,
+or devices in question.
-error information and the first 48 bytes of any data transferred.
+.It Dv CAM_DEBUG_TRACE
-.It Dv Bit 1
+This debugging flag enables function-level command flow tracing.  i.e.
-Bit 1 shows routines called.
+kernel printfs will happen at the entrance and exit of various functions.
-.It Dv Bit 2
+.It Dv CAM_DEBUG_SUBTRACE
-Bit 2 shows information about what branches are taken and often some
+This debugging flag enables debugging output internal to various functions.
-of the return values of functions.
+.It Dv CAM_DEBUG_CDB
-.It Dv Bit 3
+This debugging flag will cause the kernel to print out all
-Bit 3 shows more detailed information including DMA scatter-gather logs.
+.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 da 4 ,
-.Xr st 4 ,
+.Xr pass 4 ,
-.Xr su 4 ,
+.Xr pt 4 ,
-.Xr uha 4 ,
+.Xr sa 4 ,
-.Xr uk 4
+.Xr xpt 4 ,
+.Xr camcontrol 8
 .Sh HISTORY
-This
+The CAM
-.Nm
+.Tn SCSI
-system appeared in MACH 2.5 at TRW.
+subsystem first appeared in
+.Fx 3.0 .
+.Sh AUTHORS
+The CAM
+.Tn SCSI
+subsystem was written by Justin Gibbs and Kenneth Merry.
+