1 files changed, 340 insertions, 0 deletions
diff --git a/share/man/man4/scsi.4 b/share/man/man4/scsi.4
new file mode 100644
index 000000000000..484932260e14
--- /dev/null
+++ b/share/man/man4/scsi.4
@@ -0,0 +1,340 @@
+.\" 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
+.Sh NAME
+.Nm SCSI ,
+.Nm CAM
+.Nd CAM SCSI subsystem
+.Sh SYNOPSIS
+.Cd "device scbus"
+.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_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 will not 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.
+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 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
+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 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
+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="ahd1"
+.Ed
+.Pp
+This assigns
+.Nm
+bus number 0 to the
+.Em ahd1
+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="ahc1"
+hint.scbus.0.bus="1"
+.Ed
+.Pp
+This assigns
+.Nm
+bus 0 to the bus 1 instance on
+.Em ahc0 .
+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.unit="0"
+.Ed
+.Pp
+This assigns
+.Em da0
+to target 0, unit (lun) 0 of scbus 0.
+Omitting the target or unit hints will instruct CAM 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
+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
+.Nm
+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,
+and because of that, they are not especially useful.
+There are not many things logged at the
+.Dv CAM_DEBUG_INFO
+level, so it is not 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 .