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.
This commit is contained in:
Kenneth D. Merry
parent
00347c3f1e
commit
89045423f1
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user