/share/man/man4/scsi.4
https://bitbucket.org/freebsd/freebsd-head/ · Forth · 354 lines · 354 code · 0 blank · 0 comment · 19 complexity · e17140fefd071f5ec9d680c8a295ac71 MD5 · raw file
- .\" 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 June 7, 2012
- .Dt CAM 4
- .Os
- .Sh NAME
- .Nm CAM
- .Nd Common Access Method SCSI/ATA 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
- and
- .Tn ATA
- devices, and to utilize different
- .Tn SCSI
- and
- .Tn ATA
- host adapters through host adapter drivers.
- When the system probes 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 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 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 busses 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="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
- .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
- 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
- .Tn SCSI
- or
- .Tn ATA
- 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
- .Nm
- .Tn SCSI
- subsystem.
- .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 allows to specify 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 allows to set the various debugging flags from a kernel config file.
- .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
- 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
- .Xr ada 4 ,
- .Xr aha 4 ,
- .Xr ahb 4 ,
- .Xr ahc 4 ,
- .Xr ahci 4 ,
- .Xr ata 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
- .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 mav@FreeBSD.org .