284 lines
9.6 KiB
Groff
284 lines
9.6 KiB
Groff
.\" Copyright (c) 1996
|
|
.\" Julian Elischer <julian@FreeBSD.org>. 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.
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.Dd October 15, 1998
|
|
.Dt SCSI 4
|
|
.Os FreeBSD
|
|
.Sh NAME
|
|
.Nm SCSI ,
|
|
.Nm CAM
|
|
.Nd CAM SCSI subsystem
|
|
.Sh SYNOPSIS
|
|
.Cd "device scbus"
|
|
.Cd "device scbus1 at ahc0"
|
|
.Cd "device scbus3 at ahc1 bus 0"
|
|
.Cd "device scbus2 at ahc1 bus 1"
|
|
.Cd "device cd"
|
|
.Cd "device ch"
|
|
.Cd "device da"
|
|
.Cd "device pass"
|
|
.Cd "device pt"
|
|
.Cd "device sa"
|
|
.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 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. The
|
|
.Xr pass 4
|
|
driver, if it is configured in the kernel, will attach to all
|
|
.Tn SCSI
|
|
devices.
|
|
.Sh KERNEL CONFIGURATION
|
|
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;
|
|
.Cd "device da0"
|
|
will suffice for any number of disk drivers.
|
|
.Pp
|
|
The devices are either
|
|
.Em wired
|
|
so they appear as a particular device unit or
|
|
.Em counted
|
|
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
|
|
.Cd "device ch0"
|
|
to include the changer driver.
|
|
.Pp
|
|
To wire down a unit use a config line similar to
|
|
.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
|
|
.Cd "device 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
|
|
.Cd "device 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 "device da1" ,
|
|
then the first non-wired disk shall come on line as
|
|
.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
|
|
all IO between the
|
|
.Em SCSI
|
|
bus and the system.
|
|
The maximum size of a transfer is governed by the
|
|
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
|
|
in which the system is capable of operating as a device, responding to
|
|
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 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.
|
|
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 da 4 ,
|
|
.Xr pass 4 ,
|
|
.Xr pt 4 ,
|
|
.Xr sa 4 ,
|
|
.Xr xpt 4 ,
|
|
.Xr camcontrol 8
|
|
.Sh HISTORY
|
|
The CAM
|
|
.Tn SCSI
|
|
subsystem first appeared in
|
|
.Fx 3.0 .
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
The CAM
|
|
.Tn SCSI
|
|
subsystem was written by
|
|
.An Justin Gibbs
|
|
and
|
|
.An Kenneth Merry .
|