2 .\" Julian Elischer <julian@FreeBSD.org>. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
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.
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
32 .Nd Common Access Method SCSI/ATA subsystem
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_FLAGS=CAM_DEBUG_INFO|CAM_DEBUG_CDB"
47 .Cd "options CAM_MAX_HIGHPOWER=4"
48 .Cd "options SCSI_NO_SENSE_STRINGS"
49 .Cd "options SCSI_NO_OP_STRINGS"
50 .Cd "options SCSI_DELAY=8000"
54 subsystem provides a uniform and modular system for the implementation
55 of drivers to control various
59 devices, and to utilize different
63 host adapters through host adapter drivers.
64 When the system probes busses, it attaches any devices it finds to the
68 driver, if it is configured in the kernel, will attach to all devices.
69 .Sh KERNEL CONFIGURATION
70 There are a number of generic kernel configuration options for the
73 .Bl -tag -width SCSI_NO_SENSE_STRINGS
75 This option enables the
77 debugging printf code.
78 This will not actually
79 cause any debugging information to be printed out when included by itself.
80 Enabling printouts requires additional configuration.
81 See below for details.
82 .It Dv "CAM_MAX_HIGHPOWER=4"
83 This sets the maximum allowable number of concurrent "high power" commands.
84 A "high power" command is a command that takes more electrical power than
86 An example of this is the
89 Starting a disk often takes significantly more electrical power than normal
91 This option allows the
92 user to specify how many concurrent high power commands may be outstanding
93 without overloading the power supply on his computer.
94 .It Dv SCSI_NO_SENSE_STRINGS
95 This eliminates text descriptions of each
97 Additional Sense Code and Additional Sense Code Qualifier pair.
99 is a fairly large text database, eliminating it reduces the size of the
101 This is primarily necessary for boot floppies and other
102 low disk space or low memory space environments.
103 In most cases, though,
104 this should be enabled, since it speeds the interpretation of
107 Do not let the "kernel bloat" zealots get to you -- leave
108 the sense descriptions in your kernel!
109 .It Dv SCSI_NO_OP_STRINGS
110 This disables text descriptions of each
113 This option, like the sense string option above, is primarily
114 useful for environments like a boot floppy where kernel size is critical.
115 Enabling this option for normal use is not recommended, since it slows
119 .It Dv SCSI_DELAY=8000
127 not seconds like the old
130 When the kernel boots, it sends a bus reset to each
132 bus to tell each device to reset itself to a default set of transfer
133 negotiations and other settings.
136 devices need some amount of time to recover from a bus reset.
138 may need as little as 100ms, while old, slow devices may need much longer.
141 is not specified, it defaults to 2 seconds.
142 The minimum allowable value for
145 One special case is that if the
147 is set to 0, that will be taken to mean the "lowest possible value."
150 will be reset to 100ms.
153 All devices and busses support dynamic allocation so that
154 an upper number of devices and controllers does not need to be configured;
156 will suffice for any number of disk drivers.
158 The devices are either
160 so they appear as a particular device unit or
162 so that they appear as the next available unused unit.
164 Units are wired down by setting kernel environment hints.
165 This is usually done either interactively from the
167 or automatically via the
168 .Pa /boot/device.hints
171 .Bd -literal -offset indent
172 hint.device.unit.property="value"
177 bus numbers can be wired down to specific controllers with
178 a config line similar to the following:
179 .Bd -literal -offset indent
180 hint.scbus.0.at="ahd1"
188 For controllers supporting more than one bus, a particular bus can be assigned
190 .Bd -literal -offset indent
191 hint.scbus.0.at="ahc1"
197 bus 0 to the bus 1 instance on
199 Peripheral drivers can be wired to a specific bus, target, and lun as so:
200 .Bd -literal -offset indent
201 hint.da.0.at="scbus0"
208 to target 0, unit (lun) 0 of scbus 0.
209 Omitting the target or unit hints will instruct
211 to treat them as wildcards
212 and use the first respective counted instances.
213 These examples can be combined together to allow a peripheral device to be
214 wired to any particular controller, bus, target, and/or unit instance.
216 When you have a mixture of wired down and counted devices then the
217 counting begins with the first non-wired down unit for a particular
219 That is, if you have a disk wired down as
221 then the first non-wired disk shall come on line as
224 The system allows common device drivers to work through many different
226 The adapters take requests from the upper layers and do
232 The maximum size of a transfer is governed by the
234 Most adapters can transfer 64KB in a single operation, however
235 many can transfer larger amounts.
237 Some adapters support
239 in which the system is capable of operating as a device, responding to
240 operations initiated by another system.
241 Target mode is supported for
242 some adapters, but is not yet complete for this version of the
251 When the kernel is compiled with options CAMDEBUG, an XPT_DEBUG CCB can be
252 used to enable various amounts of tracing information on any
254 Devices not being traced will not produce trace information.
255 There are currently four debugging flags that may be turned on:
256 .Bl -tag -width CAM_DEBUG_SUBTRACE
257 .It Dv CAM_DEBUG_INFO
258 This debugging flag enables general informational printfs for the device
259 or devices in question.
260 .It Dv CAM_DEBUG_TRACE
261 This debugging flag enables function-level command flow tracing.
263 kernel printfs will happen at the entrance and exit of various functions.
264 .It Dv CAM_DEBUG_SUBTRACE
265 This debugging flag enables debugging output internal to various functions.
267 This debugging flag will cause the kernel to print out all
269 commands sent to a particular device or devices.
272 Some of these flags, most notably
275 .Dv CAM_DEBUG_SUBTRACE
276 will produce kernel printfs in EXTREME numbers,
277 and because of that, they are not especially useful.
278 There are not many things logged at the
280 level, so it is not especially useful.
281 The most useful debugging flag is the
284 Users can enable debugging from their kernel config file, by using
285 the following kernel config options:
286 .Bl -tag -width CAM_DEBUG_TARGET
291 Without this option, users will not even be able
292 to turn on debugging from userland via
294 .It Dv CAM_DEBUG_FLAGS
295 This allows the user to set the various debugging flags described above
296 in a kernel config file.
297 Flags may be ORed together if the user wishes to
298 see printfs for multiple debugging levels.
300 Specify a bus to debug.
301 To debug all busses, set this to -1.
302 .It Dv CAM_DEBUG_TARGET
303 Specify a target to debug.
304 To debug all targets, set this to -1.
306 Specify a lun to debug.
307 To debug all luns, set this to -1.
310 When specifying a bus, target or lun to debug, you
312 specify all three bus/target/lun options above.
314 should be able to enable debugging on most anything.
316 Users may also enable debugging printfs on the fly, if the
318 option is their config file, by using the
344 subsystem first appeared in
348 ATA support was added in
355 subsystem was written by
363 .An Alexander Motin Aq mav@FreeBSD.org .