/share/man/man4/scsi.4

  1.\" Copyright (c) 1996
  2.\"	Julian Elischer <julian@FreeBSD.org>.  All rights reserved.
  3.\"
  4.\" Redistribution and use in source and binary forms, with or without
  5.\" modification, are permitted provided that the following conditions
  6.\" are met:
  7.\" 1. Redistributions of source code must retain the above copyright
  8.\"    notice, this list of conditions and the following disclaimer.
  9.\"
 10.\" 2. Redistributions in binary form must reproduce the above copyright
 11.\"    notice, this list of conditions and the following disclaimer in the
 12.\"    documentation and/or other materials provided with the distribution.
 13.\"
 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 17.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 24.\" SUCH DAMAGE.
 25.\"
 26.\" $FreeBSD$
 27.Dd June 7, 2012
 28.Dt CAM 4
 29.Os
 30.Sh NAME
 31.Nm CAM
 32.Nd Common Access Method SCSI/ATA subsystem
 33.Sh SYNOPSIS
 34.Cd "device scbus"
 35.Cd "device ada"
 36.Cd "device cd"
 37.Cd "device ch"
 38.Cd "device da"
 39.Cd "device pass"
 40.Cd "device pt"
 41.Cd "device sa"
 42.Cd "options CAMDEBUG"
 43.Cd "options CAM_DEBUG_BUS=-1"
 44.Cd "options CAM_DEBUG_TARGET=-1"
 45.Cd "options CAM_DEBUG_LUN=-1"
 46.Cd "options CAM_DEBUG_COMPILE=CAM_DEBUG_INFO|CAM_DEBUG_CDB|CAM_DEBUG_PROBE"
 47.Cd "options CAM_DEBUG_FLAGS=CAM_DEBUG_INFO|CAM_DEBUG_CDB"
 48.Cd "options CAM_MAX_HIGHPOWER=4"
 49.Cd "options SCSI_NO_SENSE_STRINGS"
 50.Cd "options SCSI_NO_OP_STRINGS"
 51.Cd "options SCSI_DELAY=8000"
 52.Sh DESCRIPTION
 53The
 54.Nm
 55subsystem provides a uniform and modular system for the implementation
 56of drivers to control various
 57.Tn SCSI
 58and
 59.Tn ATA
 60devices, and to utilize different
 61.Tn SCSI
 62and
 63.Tn ATA
 64host adapters through host adapter drivers.
 65When the system probes busses, it attaches any devices it finds to the
 66appropriate drivers.
 67The
 68.Xr pass 4
 69driver, if it is configured in the kernel, will attach to all devices.
 70.Sh KERNEL CONFIGURATION
 71There are a number of generic kernel configuration options for the
 72.Nm
 73subsystem:
 74.Bl -tag -width SCSI_NO_SENSE_STRINGS
 75.It Dv CAMDEBUG
 76This option compiles in all the
 77.Nm
 78debugging printf code.
 79This will not actually
 80cause any debugging information to be printed out when included by itself.
 81See below for details.
 82.It Dv "CAM_MAX_HIGHPOWER=4"
 83This sets the maximum allowable number of concurrent "high power" commands.
 84A "high power" command is a command that takes more electrical power than
 85most to complete.
 86An example of this is the
 87.Tn SCSI
 88START UNIT command.
 89Starting a disk often takes significantly more electrical power than normal
 90operation.
 91This option allows the
 92user to specify how many concurrent high power commands may be outstanding
 93without overloading the power supply on his computer.
 94.It Dv SCSI_NO_SENSE_STRINGS
 95This eliminates text descriptions of each
 96.Tn SCSI
 97Additional Sense Code and Additional Sense Code Qualifier pair.
 98Since this
 99is a fairly large text database, eliminating it reduces the size of the
100kernel somewhat.
101This is primarily necessary for boot floppies and other
102low disk space or low memory space environments.
103In most cases, though,
104this should be enabled, since it speeds the interpretation of
105.Tn SCSI
106error messages.
107Do not let the "kernel bloat" zealots get to you -- leave
108the sense descriptions in your kernel!
109.It Dv SCSI_NO_OP_STRINGS
110This disables text descriptions of each
111.Tn SCSI
112opcode.
113This option, like the sense string option above, is primarily
114useful for environments like a boot floppy where kernel size is critical.
115Enabling this option for normal use is not recommended, since it slows
116debugging of
117.Tn SCSI
118problems.
119.It Dv SCSI_DELAY=8000
120This is the
121.Tn SCSI
122"bus settle delay."
123In
124.Nm ,
125it is specified in
126.Em milliseconds ,
127not seconds like the old
128.Tn SCSI
129layer used to do.
130When the kernel boots, it sends a bus reset to each
131.Tn SCSI
132bus to tell each device to reset itself to a default set of transfer
133negotiations and other settings.
134Most
135.Tn SCSI
136devices need some amount of time to recover from a bus reset.
137Newer disks
138may need as little as 100ms, while old, slow devices may need much longer.
139If the
140.Dv SCSI_DELAY
141is not specified, it defaults to 2 seconds.
142The minimum allowable value for
143.Dv SCSI_DELAY
144is "100", or 100ms.
145One special case is that if the
146.Dv SCSI_DELAY
147is set to 0, that will be taken to mean the "lowest possible value."
148In that case, the
149.Dv SCSI_DELAY
150will be reset to 100ms.
151.El
152.Pp
153All devices and busses support dynamic allocation so that
154an upper number of devices and controllers does not need to be configured;
155.Cd "device da"
156will suffice for any number of disk drivers.
157.Pp
158The devices are either
159.Em wired
160so they appear as a particular device unit or
161.Em counted
162so that they appear as the next available unused unit.
163.Pp
164Units are wired down by setting kernel environment hints.
165This is usually done either interactively from the
166.Xr loader 8 ,
167or automatically via the
168.Pa /boot/device.hints
169file.
170The basic syntax is:
171.Bd -literal -offset indent
172hint.device.unit.property="value"
173.Ed
174.Pp
175Individual
176.Nm
177bus numbers can be wired down to specific controllers with
178a config line similar to the following:
179.Bd -literal -offset indent
180hint.scbus.0.at="ahd1"
181.Ed
182.Pp
183This assigns
184.Nm
185bus number 0 to the
186.Em ahd1
187driver instance.
188For controllers supporting more than one bus, a particular bus can be assigned
189as follows:
190.Bd -literal -offset indent
191hint.scbus.0.at="ahc1"
192hint.scbus.0.bus="1"
193.Ed
194.Pp
195This assigns
196.Nm
197bus 0 to the bus 1 instance on
198.Em ahc0 .
199Peripheral drivers can be wired to a specific bus, target, and lun as so:
200.Bd -literal -offset indent
201hint.da.0.at="scbus0"
202hint.da.0.target="0"
203hint.da.0.unit="0"
204.Ed
205.Pp
206This assigns
207.Em da0
208to target 0, unit (lun) 0 of scbus 0.
209Omitting the target or unit hints will instruct
210.Nm
211to treat them as wildcards
212and use the first respective counted instances.
213These examples can be combined together to allow a peripheral device to be
214wired to any particular controller, bus, target, and/or unit instance.
215.Pp
216When you have a mixture of wired down and counted devices then the
217counting begins with the first non-wired down unit for a particular
218type.
219That is, if you have a disk wired down as
220.Em "device da1" ,
221then the first non-wired disk shall come on line as
222.Em da2 .
223.Sh ADAPTERS
224The system allows common device drivers to work through many different
225types of adapters.
226The adapters take requests from the upper layers and do
227all IO between the
228.Tn SCSI
229or
230.Tn ATA
231bus and the system.
232The maximum size of a transfer is governed by the
233adapter.
234Most adapters can transfer 64KB in a single operation, however
235many can transfer larger amounts.
236.Sh TARGET MODE
237Some adapters support
238.Em target mode
239in which the system is capable of operating as a device, responding to
240operations initiated by another system.
241Target mode is supported for
242some adapters, but is not yet complete for this version of the
243.Nm
244.Tn SCSI
245subsystem.
246.Sh FILES
247see other
248.Nm
249device entries.
250.Sh DIAGNOSTICS
251An XPT_DEBUG CCB can be used to enable various amounts of tracing information
252on any specific bus/device from the list of options compiled into the kernel.
253There are currently seven debugging flags that may be compiled in and used:
254.Bl -tag -width CAM_DEBUG_SUBTRACE
255.It Dv CAM_DEBUG_INFO
256This flag enables general informational printfs for the device
257or devices in question.
258.It Dv CAM_DEBUG_TRACE
259This flag enables function-level command flow tracing.
260i.e.\&
261kernel printfs will happen at the entrance and exit of various functions.
262.It Dv CAM_DEBUG_SUBTRACE
263This flag enables debugging output internal to various functions.
264.It Dv CAM_DEBUG_CDB
265This flag will cause the kernel to print out all
266.Tn ATA
267and
268.Tn SCSI
269commands sent to a particular device or devices.
270.It Dv CAM_DEBUG_XPT
271This flag will enable command scheduler tracing.
272.It Dv CAM_DEBUG_PERIPH
273This flag will enable peripheral drivers messages.
274.It Dv CAM_DEBUG_PROBE
275This flag will enable devices probe process tracing.
276.El
277.Pp
278Some of these flags, most notably
279.Dv CAM_DEBUG_TRACE
280and
281.Dv CAM_DEBUG_SUBTRACE ,
282will produce kernel printfs in EXTREME numbers.
283.Pp
284Users can enable debugging from their kernel config file, by using
285the following kernel config options:
286.Bl -tag -width CAM_DEBUG_COMPILE
287.It Dv CAMDEBUG
288This builds into the kernel all possible
289.Nm
290debugging.
291.It Dv CAM_DEBUG_COMPILE
292This allows to specify support for which debugging flags described above
293should be built into the kernel.
294Flags may be ORed together if the user wishes to
295see printfs for multiple debugging levels.
296.It Dv CAM_DEBUG_FLAGS
297This allows to set the various debugging flags from a kernel config file.
298.It Dv CAM_DEBUG_BUS
299Specify a bus to debug.
300To debug all busses, set this to -1.
301.It Dv CAM_DEBUG_TARGET
302Specify a target to debug.
303To debug all targets, set this to -1.
304.It Dv CAM_DEBUG_LUN
305Specify a lun to debug.
306To debug all luns, set this to -1.
307.El
308.Pp
309Users may also enable debugging on the fly by using the
310.Xr camcontrol 8
311utility, if wanted options built into the kernel.
312See
313.Xr camcontrol 8
314for details.
315.Sh SEE ALSO
316.Xr ada 4 ,
317.Xr aha 4 ,
318.Xr ahb 4 ,
319.Xr ahc 4 ,
320.Xr ahci 4 ,
321.Xr ata 4 ,
322.Xr bt 4 ,
323.Xr cd 4 ,
324.Xr ch 4 ,
325.Xr da 4 ,
326.Xr pass 4 ,
327.Xr pt 4 ,
328.Xr sa 4 ,
329.Xr xpt 4 ,
330.Xr camcontrol 8
331.Sh HISTORY
332The
333.Nm
334.Tn SCSI
335subsystem first appeared in
336.Fx 3.0 .
337The
338.Nm
339ATA support was added in
340.Fx 8.0 .
341.Sh AUTHORS
342.An -nosplit
343The
344.Nm
345.Tn SCSI
346subsystem was written by
347.An Justin Gibbs
348and
349.An Kenneth Merry .
350The
351.Nm
352.Tn ATA
353support was added by
354.An Alexander Motin Aq mav@FreeBSD.org .