scsi(4)

NAME

SCSI, CAM - CAM SCSI subsystem

SYNOPSIS

device scbus
device cd
device ch
device da
device pass
device pt
device sa
options CAMDEBUG
options CAM_DEBUG_BUS=-1
options CAM_DEBUG_TARGET=-1
options CAM_DEBUG_LUN=-1
options CAM_DEBUG_FLAGS=CAM_DEBUG_INFO|CAM_DEBUG_CDB
options CAM_MAX_HIGHPOWER=4
options SCSI_NO_SENSE_STRINGS
options SCSI_NO_OP_STRINGS
options SCSI_DELAY=8000

DESCRIPTION

The CAM SCSI subsystem 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 SCSI busses, it attaches any devices it finds

to the
appropriate drivers. The pass(4) driver, if it is config

ured in the kernel, will attach to all SCSI devices.

KERNEL CONFIGURATION

There are a number of generic kernel configuration options

for the CAM
SCSI subsystem:

CAMDEBUG This option enables the CAM debugging

printf code.

This will not actually cause any de

bugging information to be printed out when includ

ed by itself.
Enabling printouts requires addition

al configuration. See below for details.

CAM_MAX_HIGHPOWER=4 This sets the maximum allowable num

ber of concur

rent "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 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 out

standing without overloading the power supply on

his computer.

SCSI_NO_SENSE_STRINGS This eliminates text descriptions of

each 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 cas

es, though,
this should be enabled, since it

speeds the interpretation of SCSI error messages. Do

not let the
"kernel bloat" zealots get to you -

leave the
sense descriptions in your kernel!

SCSI_NO_OP_STRINGS This disables text descriptions of

each SCSI

opcode. This option, like the sense

string option
above, is primarily useful for envi

ronments like a
boot floppy where kernel size is

critical.
Enabling this option for normal use

is not recommended, since it slows debugging of

SCSI problems.

SCSI_DELAY=8000 This is the SCSI "bus settle delay."

In CAM, it

is specified in milliseconds, not

seconds like the
old SCSI layer used to do. When the

kernel boots,
it sends a bus reset to each SCSI bus

to tell each
device to reset itself to a default

set of transfer negotiations and other settings.

Most 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 SCSI_DELAY is not

specified, it
defaults to 2 seconds. The minimum

allowable
value for SCSI_DELAY is "100", or

100ms. One special case is that if the SCSI_DELAY

is set to 0,
that will be taken to mean the "low

est possible
value." In that case, the SCSI_DELAY

will be
reset to 100ms.

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;
device da0 will suffice for any number of disk drivers.

The devices are either wired so they appear as a particular

device unit
or counted so that they appear as the next available unused

unit.

Units are wired down by setting kernel environment hints.

This is usually done either interactively from the loader(8), or auto

matically via
the /boot/device.hints file. The basic syntax is:

hint.device.unit.property="value"

Individual SCSI bus numbers can be wired down to specific

controllers
with a config line similar to the following:

hint.scbus.0.at="ahd1"

This assigns SCSI bus number 0 to the ahd1 driver instance.

For controllers supporting more than one bus, a particular bus can

be assigned
as follows:

hint.scbus.0.at="ahc1"
hint.scbus.0.bus="1"

This assigns SCSI bus 0 to the bus 1 instance on ahc0. Pe

ripheral
drivers can be wired to a specific bus, target, and lun as

so:

hint.da.0.at="scbus0"
hint.da.0.target="0"
hint.da.0.unit="0"

This assigns da0 to target 0, unit (lun) 0 of scbus 0.

Omitting the target or unit hints will instruct CAM to treat them as wild

cards and use
the first respective counted instances. These examples can

be combined
together to allow a peripheral device to be wired to any

particular controller, bus, target, and/or unit instance.

When you have a mixture of wired down and counted devices

then the counting begins with the first non-wired down unit for a particu

lar type.
That is, if you have a disk wired down as device da1, then

the first nonwired disk shall come on line as da2.

ADAPTERS

The system allows common device drivers to work through many

different
types of adapters. The adapters take requests from the up

per layers and
do all IO between the 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.

TARGET MODE

Some adapters support target mode in which the system is ca

pable of operating as a device, responding to operations initiated by an

other system.
Target mode is supported for some adapters, but is not yet

complete for
this version of the CAM SCSI subsystem.

FILES

see other SCSI device entries.

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 in

formation.
There are currently four debugging flags that may be turned

on:

CAM_DEBUG_INFO This debugging flag enables general in

formational

printfs for the device or devices in

question.

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.

CAM_DEBUG_SUBTRACE This debugging flag enables debugging

output internal

to various functions.

CAM_DEBUG_CDB This debugging flag will cause the ker

nel to print

out all SCSI commands sent to a particu

lar device or
devices.

Some of these flags, most notably CAM_DEBUG_TRACE and

CAM_DEBUG_SUBTRACE
will produce kernel printfs in EXTREME numbers, and because

of that, they
are not especially useful. There are not many things logged

at the
CAM_DEBUG_INFO level, so it is not especially useful. The

most useful
debugging flag is the CAM_DEBUG_CDB flag. Users can enable

debugging
from their kernel config file, by using the following kernel

config
options:

CAMDEBUG This enables CAM debugging. Without this

option, users

will not even be able to turn on debugging

from userland via camcontrol(8).

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.

CAM_DEBUG_BUS Specify a bus to debug. To debug all

busses, set this

to -1.

CAM_DEBUG_TARGET Specify a target to debug. To debug all

targets, set

this to -1.

CAM_DEBUG_LUN Specify a lun to debug. To debug all

luns, set this to

-1.

When specifying a bus, target or lun to debug, you MUST

specify all three
bus/target/lun options above. Using wildcards, you should

be able to
enable debugging on most anything.

Users may also enable debugging printfs on the fly, if the

CAMDEBUG
option is their config file, by using the camcontrol(8)

utility. See
camcontrol(8) for details.

SEE ALSO

aha(4), ahb(4), ahc(4), bt(4), cd(4), ch(4), da(4), pass(4),

pt(4),
sa(4), xpt(4), camcontrol(8)

HISTORY

The CAM SCSI subsystem first appeared in FreeBSD 3.0.

AUTHORS

The CAM SCSI subsystem was written by Justin Gibbs and Ken

neth Merry.

BSD October 15, 1998

BSD