From 89045423f1d86b30a03c90c35964f518a3e4ce4d Mon Sep 17 00:00:00 2001 From: "Kenneth D. Merry" Date: Fri, 16 Oct 1998 04:28:39 +0000 Subject: [PATCH] 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 | 1 + share/man/man4/scsi.4 | 280 ++++++++++++++++++++++++++-------------- 2 files changed, 186 insertions(+), 95 deletions(-) diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile index 632c9f41182d..888dfcbfa25e 100644 --- a/share/man/man4/Makefile +++ b/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 diff --git a/share/man/man4/scsi.4 b/share/man/man4/scsi.4 index 8ebd5b08ca33..99a2ee541552 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 . 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. +