.\" 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.
.Dd December 11, 2023
.Dt CAM 4
.Os
.Sh NAME
.Nm CAM
.Nd Common Access Method Storage subsystem
.Sh SYNOPSIS
.Cd "device scbus"
.Cd "device ada"
.Cd "device cd"
.Cd "device ch"
.Cd "device da"
.Cd "device pass"
.Cd "device pt"
.Cd "device sa"
.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_COMPILE=CAM_DEBUG_INFO|CAM_DEBUG_CDB|CAM_DEBUG_PROBE"
.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
.Nm
subsystem provides a uniform and modular system for the implementation
of drivers to control various
.Tn SCSI ,
.Tn ATA ,
.Tn NVMe ,
and
.Tn MMC / SD
devices, and to utilize different
.Tn SCSI ,
.Tn ATA ,
.Tn NVMe ,
and
.Tn MMC / SD
host adapters through host adapter drivers.
When the system probes buses, 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 devices.
.Sh KERNEL CONFIGURATION
There are a number of generic kernel configuration options for the
.Nm
subsystem:
.Bl -tag -width SCSI_NO_SENSE_STRINGS
.It Dv CAM_BOOT_DELAY
Additional time to wait after the static parts of the kernel have run to allow
for discovery of additional devices which may take time to connect,
such as USB attached storage.
.It Dv CAM_IOSCHED_DYNAMIC
Enable dynamic decisions in the I/O scheduler based on hints and the current
performance of the storage devices.
.It Dv CAM_IO_STATS
Enable collection of statistics for periph devices.
.It Dv CAM_TEST_FAILURE
Enable ability to simulate I/O failures.
.It Dv CAMDEBUG
This option compiles in all the
.Nm
debugging printf code.
This will not actually
cause any debugging information to be printed out when included by itself.
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 is the
.Tn SCSI
START UNIT command.
Starting a disk often takes significantly more electrical power than normal
operation.
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.
Do not 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 is not recommended, since it slows
debugging of
.Tn SCSI
problems.
.It Dv SCSI_DELAY=8000
This is the
.Tn SCSI
"bus settle delay."
In
.Nm ,
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
is not 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 buses support dynamic allocation so that
an upper number of devices and controllers does not need to be configured;
.Cd "device da"
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
Units are wired down by setting kernel environment hints.
This is usually done either interactively from the
.Xr loader 8 ,
or automatically via the
.Pa /boot/device.hints
file.
The basic syntax is:
.Bd -literal -offset indent
hint.device.unit.property="value"
.Ed
.Pp
Individual
.Nm
bus numbers can be wired down to specific controllers with
a config line similar to the following:
.Bd -literal -offset indent
hint.scbus.0.at="mpr1"
.Ed
.Pp
This assigns
.Nm
bus number 0 to the
.Em mpr1
driver instance.
For controllers supporting more than one bus, a particular bus can be assigned
as follows:
.Bd -literal -offset indent
hint.scbus.0.at="ahci1"
hint.scbus.0.bus="1"
.Ed
.Pp
This assigns
.Nm
bus 0 to the bus 1 instance on
.Em ahci1 .
Peripheral drivers can be wired to a specific bus, target, and lun as so:
.Bd -literal -offset indent
hint.da.0.at="scbus0"
hint.da.0.target="0"
hint.da.0.lun="0"
.Ed
.Pp
This assigns
.Em da0
to target 0, unit (lun) 0 of scbus 0.
Omitting the target or unit hints will instruct
.Nm
to treat them as wildcards
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.
.Pp
This also works with
.Xr nvme 4
drives.
.Bd -literal -offset indent
hint.nvme.4.at="pci7:0:0"
hint.scbus.10.at="nvme4"
hint.nda.10.at="scbus10"
hint.nda.10.target="1"
hint.nda.10.lun="12"
hint.nda.11.at="scbus10"
hint.nda.11.target="1"
hint.nda.11.lun="2"
.Ed
.Pp
This assigns the NVMe card at PCI bus 7 slot 0 function 1 to scbus 10.
The target for
.Xr nda 4
devices is always 1.
The unit is the namespace identifier from the drive.
The namespace id 1 is exported as
.Em nda10
and namespace id 2 is exported as
.Em nda11 .
.Pp
For devices that provide a serial number, units may be wired to that serial
number without regard where the drive is attached:
.Bd -literal -offset indent
hint.nda.3.sn="CY0AN07101120B12P"
hint.da.44.sn="143282400011"
hint.ada.2.sn="A065D591"
.Ed
wires
.Em nda3 ,
.Em da44 ,
and
.Em ada2
to drives with the specified serial numbers.
One need not specify an
.Em at
line when serial numbers are used.
.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
.Tn SCSI ,
.Tn ATA ,
.Tn NVMe ,
or
.Tn MMC / SD
bus and the system.
The maximum size of a transfer is governed by the
adapter.
Most adapters can transfer 1MB 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
.Nm
.Tn SCSI
subsystem.
.Sh ARCHITECTURE
The
.Nm
subsystem glues together the upper layers of the system to the storage devices.
PERIPH devices accept storage requests from GEOM and other upper layers of the
system and translates them into protocol requests.
XPT (transport) dispatches these protocol requests to a SIM driver.
A SIM driver takes protocol requests and translates them into hardware commands
the host adapter understands to transfer the protocol requests, and data (if
any) to the storage device.
The CCB transports these requests around as messages.
.Ss CAM
The Common Access Method was a standard defined in the 1990s to talk to disk
drives.
.Fx
is one of the few operating systems to fully implement this model.
The interface between different parts of CAM is the CCB (or CAM Control Block).
Each CCB has a standard header, which contains the type of request and dispatch
information, and a command specific portion.
A CAM Periph generates requests.
The XPT layer dispatches these requests to the appropriate SIM.
Some CCBs are sent directly to the SIM for immediate processing, while others
are queued and complete when the I/O has finished.
A SIM takes CCBs and translates them into hardware specific commands to push the
SCSI CDB or other protocol control block to the peripheral, along with setting
up the DMA for the associated data.
.Ss Periph Devices
A periph driver knows how to translate standard requests into protocol messages
that a SIM can deliver to hardware.
These requests can come from any upper layer source, but primarily come in via
GEOM as a bio request.
They can also come in directly from character device requests for tapes and pass
through commands.
.Pp
Disk devices, or direct access (da) in CAM, are one type of peripheral.
These devices present themselves to the kernel a device ending in
.Dq da .
Each protocol has a unique device name:
.Bl -tag -width 4
.It Xr da 4
SCSI or SAS device, or devices that accept SCSI CDBs for I/O.
.It Xr ada 4
ATA or SATA device
.It Xr nda 4
NVME device
.It Xr sdda 4
An SD or MMC block storage device.
.El
.Pp
Tape devices are called serial access
.Po
.Xr sa 4
.Pc
in CAM.
They interface to the system via a character device and provide
.Xr ioctl 2
control for tape drives.
.Pp
The
.Xr pass 4
device will pass through CCB requests from userland to the SIM directly.
The device is used to send commands other than read, write, trim or flush to a
device.
The
.Xr camcontrol 8
command uses this device.
.Ss XPT drivers
The transport driver connects the periph to the SIM.
It is not configured separately.
It is also responsible for device discovery for those SIM drivers that do not
enumerate themselves.
.Ss SIM driver
SIM used to stand for SCSI Interface Module.
Now it is just SIM because it understands protocols other than SCSI.
There are two types of SIM drivers: virtual and physical.
Physical SIMs are typically called host bus adapters (HBA), but not universally.
Virtual SIM drivers are for communicating with network or virtual machine hosts.
.Sh FILES
see other
.Nm
device entries.
.Sh DIAGNOSTICS
An XPT_DEBUG CCB can be used to enable various amounts of tracing information
on any specific bus/device from the list of options compiled into the kernel.
There are currently seven debugging flags that may be compiled in and used:
.Bl -tag -width CAM_DEBUG_SUBTRACE
.It Dv CAM_DEBUG_INFO
This flag enables general informational printfs for the device
or devices in question.
.It Dv CAM_DEBUG_TRACE
This 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 flag enables debugging output internal to various functions.
.It Dv CAM_DEBUG_CDB
This flag will cause the kernel to print out all
.Tn ATA
and
.Tn SCSI
commands sent to a particular device or devices.
.It Dv CAM_DEBUG_XPT
This flag will enable command scheduler tracing.
.It Dv CAM_DEBUG_PERIPH
This flag will enable peripheral drivers messages.
.It Dv CAM_DEBUG_PROBE
This flag will enable devices probe process tracing.
.El
.Pp
Some of these flags, most notably
.Dv CAM_DEBUG_TRACE
and
.Dv CAM_DEBUG_SUBTRACE ,
will produce kernel printfs in EXTREME numbers.
.Pp
Users can enable debugging from their kernel config file, by using
the following kernel config options:
.Bl -tag -width CAM_DEBUG_COMPILE
.It Dv CAMDEBUG
This builds into the kernel all possible
.Nm
debugging.
.It Dv CAM_DEBUG_COMPILE
This specifies support for which debugging flags described above
should be built into the kernel.
Flags may be ORed together if the user wishes to
see printfs for multiple debugging levels.
.It Dv CAM_DEBUG_FLAGS
This sets the various debugging flags from a kernel config file.
.It Dv CAM_DEBUG_BUS
Specify a bus to debug.
To debug all buses, 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
Users may also enable debugging on the fly by using the
.Xr camcontrol 8
utility, if wanted options built into the kernel.
See
.Xr camcontrol 8
for details.
.Sh SEE ALSO
.Bl -tag -width 20
.It Sy Commands:
.Xr camcontrol 8 ,
.Xr camdd 8
.It Sy Libraries:
.Xr cam 3
.It Sy Periph Drivers:
.Xr ada 4 ,
.Xr da 4 ,
.Xr nda 4 ,
.\" .Xr sdda 4 ,
.Xr pass 4 ,
.Xr sa 4
.It Sy SIM Devices:
.Xr aac 4 ,
.Xr aacraid 4 ,
.Xr ahc 4 ,
.Xr ahci 4 ,
.Xr ata 4 ,
.Xr aw_mmc 4 ,
.Xr ciss 4 ,
.Xr hv_storvsc 4 ,
.Xr isci 4 ,
.Xr iscsi 4 ,
.Xr isp 4 ,
.\" .Xr mmcnull 4 ,
.Xr mpr 4 ,
.Xr mps 4 ,
.Xr mpt 4 ,
.Xr mrsas 4 ,
.Xr mvs 4 ,
.Xr nvme 4 ,
.Xr pms 4 ,
.Xr pvscsi 4 ,
.Xr sdhci 4 ,
.Xr smartpqi 4 ,
.Xr sym 4 ,
.Xr tws 4 ,
.Xr umass 4 ,
.Xr virtio_scsi 4
.It Sy Deprecated or Poorly Supported SIM Devices:
.Xr ahd 4 ,
.Xr amr 4 ,
.Xr arcmsr 4 ,
.Xr esp 4 ,
.\" .Xr fslsata 4 ,
.Xr hpt27xx 4 ,
.Xr hptiop 4 ,
.Xr hptmv 4 ,
.Xr hptnr 4 ,
.\" .Xr htprr 4 ,
.Xr iir 4
.Xr mfi 4 ,
.\" .Xr osc 4 ,
.\" .Xr ps3cdrom 4 ,
.Xr sbp 4 ,
.Xr twa 4
.El
.Sh HISTORY
The
.Nm
.Tn SCSI
subsystem first appeared in
.Fx 3.0 .
The
.Nm
ATA support was added in
.Fx 8.0 .
.Sh AUTHORS
.An -nosplit
The
.Nm
.Tn SCSI
subsystem was written by
.An Justin Gibbs
and
.An Kenneth Merry .
The
.Nm
.Tn ATA
support was added by
.An Alexander Motin Aq Mt mav@FreeBSD.org .
The
.Nm
.Tn NVMe
support was added by
.An Warner Losh Aq Mt imp@FreeBSD.org .