3 .\" Julian Elischer <julian@freebsd.org>. All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 .Nd CAM SCSI subsystem
35 .Cd "controller scbus0"
36 .Cd "controller scbus1 at ahc0"
37 .Cd "controller scbus3 at ahc1 bus 0"
38 .Cd "controller scbus2 at ahc1 bus 1"
45 .Cd "device ch1 at scbus0 target 4 unit 0"
47 .Cd options CAM_DEBUG_BUS=-1
48 .Cd options CAM_DEBUG_TARGET=-1
49 .Cd options CAM_DEBUG_LUN=-1
50 .Cd options CAM_DEBUG_FLAGS=CAM_DEBUG_INFO|CAM_DEBUG_CDB
51 .Cd options CAM_MAX_HIGHPOWER=4
52 .Cd options SCSI_NO_SENSE_STRINGS
53 .Cd options SCSI_NO_OP_STRINGS
54 .Cd options SCSI_DELAY=8000
58 subsystem provides a uniform and modular system for the implementation
59 of drivers to control various
61 devices, and to utilize different
63 host adapters through host adapter drivers. When the system probes the
65 busses, it attaches any devices it finds to the appropriate
68 driver, if it is configured in the kernel, will attach to all
71 .Sh KERNEL CONFIGURATION
72 There are a number of generic kernel configuration options for the
76 .Bl -tag -width SCSI_NO_SENSE_STRINGS
78 This option enables the CAM debugging printf code. This won't actually
79 cause any debugging information to be printed out when included by itself.
80 Enabling printouts requires additional configuration. See below for
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
85 most to complete. An example of this (and the only command currently
86 tagged as "high power") is the
88 START UNIT command. Starting a SCSI disk often takes significantly more
89 electrical power than normal operation of the disk. This option allows the
90 user to specify how many concurrent high power commands may be outstanding
91 without overloading the power supply on his computer.
92 .It Dv SCSI_NO_SENSE_STRINGS
93 This eliminates text descriptions of each
95 Additional Sense Code and Additional Sense Code Qualifier pair. Since this
96 is a fairly large text database, eliminating it reduces the size of the
97 kernel somewhat. This is primarily necessary for boot floppies and other
98 low disk space or low memory space environments. In most cases, though,
99 this should be enabled, since it speeds the interpretation of
101 error messages. Don't let the "kernel bloat" zealots get to you -- leave
102 the sense descriptions in your kernel!
103 .It Dv SCSI_NO_OP_STRINGS
104 This disables text descriptions of each
106 opcode. This option, like the sense string option above, is primarily
107 useful for environments like a boot floppy where kernel size is critical.
108 Enabling this option for normal use isn't recommended, since it slows
112 .It Dv SCSI_DELAY=8000
115 "bus settle delay." In CAM, it is specified in
117 not seconds like the old
119 layer used to do. When the kernel boots, it sends a bus reset to each
121 bus to tell each device to reset itself to a default set of transfer
122 negotiations and other settings. Most
124 devices need some amount of time to recover from a bus reset. Newer disks
125 may need as little as 100ms, while old, slow devices may need much longer.
128 isn't specified, it defaults to 2 seconds. The minimum allowable value for
130 is "100", or 100ms. One special case is that if the
132 is set to 0, that will be taken to mean the "lowest possible value." In
135 will be reset to 100ms.
138 All devices and the SCSI busses support boot time allocation so that
139 an upper number of devices and controllers does not need to be configured;
141 will suffice for any number of disk drivers.
143 The devices are either
145 so they appear as a particular device unit or
147 so that they appear as the next available unused unit.
149 To configure a driver in the kernel without wiring down the device use a
150 config line similar to
152 to include the changer driver.
154 To wire down a unit use a config line similar to
155 .Cd "device ch1 at scbus0 target 4 unit 0"
156 to assign changer 1 as the changer with SCSI ID 4,
157 SCSI logical unit 0 on SCSI bus 0.
158 Individual scbuses can be wired down to specific controllers with
159 a config line similar to
160 .Cd "controller scbus0 at ahc0"
161 which assigns scsi bus 0 to the first unit using the ahc driver.
162 For controllers supporting more than one bus,
163 the particular bus can be specified as in
164 .Cd "controller scbus3 at ahc1 bus 1"
165 which assigns scbus 1 to the second bus probed on the ahc1 device.
167 When you have a mixture of wired down and counted devices then the
168 counting begins with the first non-wired down unit for a particular
169 type. That is, if you have a disk wired down as
171 then the first non-wired disk shall come on line as
174 The system allows common device drivers to work through many different
175 types of adapters. The adapters take requests from the upper layers and do
178 bus and the system. The maximum size of a transfer is governed by the
179 adapter. Most adapters can transfer 64KB in a single operation, however
180 many can transfer larger amounts.
182 Some adapters support
184 in which the system is capable of operating as a device, responding to
185 operations initiated by another system. Target mode is supported for
186 some adapters, but is not yet complete for this version of the CAM
190 see other scsi device entries.
192 When the kernel is compiled with options CAMDEBUG, an XPT_DEBUG CCB can be
193 used to enable various amounts of tracing information on any
194 specific device. Devices not being traced will not produce trace information.
195 There are currently four debugging flags that may be turned on:
196 .Bl -tag -width CAM_DEBUG_SUBTRACE
197 .It Dv CAM_DEBUG_INFO
198 This debugging flag enables general informational printfs for the device
199 or devices in question.
200 .It Dv CAM_DEBUG_TRACE
201 This debugging flag enables function-level command flow tracing. i.e.
202 kernel printfs will happen at the entrance and exit of various functions.
203 .It Dv CAM_DEBUG_SUBTRACE
204 This debugging flag enables debugging output internal to various functions.
206 This debugging flag will cause the kernel to print out all
208 commands sent to a particular device or devices.
211 Some of these flags, most notably
214 .Dv CAM_DEBUG_SUBTRACE
215 will produce kernel printfs in EXTREME numbers. Because of that, they
216 aren't especially useful. There aren't many things logged at the
218 level, so it isn't especially useful. The most useful debugging flag is
221 flag. Users can enable debugging from their kernel config file, by using
222 the following kernel config options:
223 .Bl -tag -width CAM_DEBUG_TARGET
225 This enables CAM debugging. Without this option, users will not even be able
226 to turn on debugging from userland via
228 .It Dv CAM_DEBUG_FLAGS
229 This allows the user to set the various debugging flags described above
230 in a kernel config file. Flags may be ORed together if the user wishes to
231 see printfs for multiple debugging levels.
233 Specify a bus to debug. To debug all busses, set this to -1.
234 .It Dv CAM_DEBUG_TARGET
235 Specify a target to debug. To debug all targets, set this to -1.
237 Specify a lun to debug. To debug all luns, set this to -1.
240 When specifying a bus, target or lun to debug, you
242 specify all three bus/target/lun options above. Using wildcards, you
243 should be able to enable debugging on most anything.
245 Users may also enable debugging printfs on the fly, if the
247 option is their config file, by using the
268 subsystem first appeared in
273 subsystem was written by
projects / FreeBSD / FreeBSD.git / blob