Commit | Line | Data |
---|---|---|
984263bc MD |
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: src/share/man/man4/scsi.4,v 1.18.2.7 2001/08/17 13:08:39 ru Exp $ | |
27 | .Dd October 15, 1998 | |
28 | .Dt SCSI 4 | |
29 | .Os | |
30 | .Sh NAME | |
31 | .Nm SCSI , | |
32 | .Nm CAM | |
33 | .Nd CAM SCSI subsystem | |
34 | .Sh SYNOPSIS | |
35 | .Cd "device scbus" | |
7efec73e SW |
36 | .Cd "device scbus1 at ahci0" |
37 | .Cd "device scbus3 at ahci1 bus 0" | |
38 | .Cd "device scbus2 at ahci1 bus 1" | |
984263bc MD |
39 | .Cd "device cd" |
40 | .Cd "device ch" | |
41 | .Cd "device da" | |
42 | .Cd "device pass" | |
43 | .Cd "device pt" | |
44 | .Cd "device sa" | |
45 | .Cd "device ch1 at scbus0 target 4 unit 0" | |
46 | .Cd "options CAMDEBUG" | |
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" | |
55 | .Sh DESCRIPTION | |
56 | The CAM | |
57 | .Tn SCSI | |
58 | subsystem provides a uniform and modular system for the implementation | |
59 | of drivers to control various | |
60 | .Tn SCSI | |
61 | devices, and to utilize different | |
62 | .Tn SCSI | |
63 | host adapters through host adapter drivers. | |
64 | When the system probes the | |
65 | .Tn SCSI | |
66 | busses, it attaches any devices it finds to the appropriate | |
67 | drivers. The | |
68 | .Xr pass 4 | |
69 | driver, if it is configured in the kernel, will attach to all | |
70 | .Tn SCSI | |
71 | devices. | |
72 | .Sh KERNEL CONFIGURATION | |
73 | There are a number of generic kernel configuration options for the | |
74 | CAM | |
75 | .Tn SCSI | |
76 | subsystem: | |
77 | .Bl -tag -width SCSI_NO_SENSE_STRINGS | |
78 | .It Dv CAMDEBUG | |
79 | This option enables the CAM debugging printf code. This won't actually | |
80 | cause any debugging information to be printed out when included by itself. | |
81 | Enabling printouts requires additional configuration. See below for | |
82 | details. | |
83 | .It Dv "CAM_MAX_HIGHPOWER=4" | |
84 | This sets the maximum allowable number of concurrent "high power" commands. | |
85 | A "high power" command is a command that takes more electrical power than | |
86 | most to complete. An example of this (and the only command currently | |
87 | tagged as "high power") is the | |
88 | .Tn SCSI | |
89 | START UNIT command. Starting a SCSI disk often takes significantly more | |
90 | electrical power than normal operation of the disk. This option allows the | |
91 | user to specify how many concurrent high power commands may be outstanding | |
92 | without overloading the power supply on his computer. | |
93 | .It Dv SCSI_NO_SENSE_STRINGS | |
94 | This eliminates text descriptions of each | |
95 | .Tn SCSI | |
96 | Additional Sense Code and Additional Sense Code Qualifier pair. Since this | |
97 | is a fairly large text database, eliminating it reduces the size of the | |
98 | kernel somewhat. This is primarily necessary for boot floppies and other | |
99 | low disk space or low memory space environments. In most cases, though, | |
100 | this should be enabled, since it speeds the interpretation of | |
101 | .Tn SCSI | |
102 | error messages. Don't let the "kernel bloat" zealots get to you -- leave | |
103 | the sense descriptions in your kernel! | |
104 | .It Dv SCSI_NO_OP_STRINGS | |
105 | This disables text descriptions of each | |
106 | .Tn SCSI | |
107 | opcode. This option, like the sense string option above, is primarily | |
108 | useful for environments like a boot floppy where kernel size is critical. | |
109 | Enabling this option for normal use isn't recommended, since it slows | |
110 | debugging of | |
111 | .Tn SCSI | |
112 | problems. | |
113 | .It Dv SCSI_DELAY=8000 | |
114 | This is the | |
115 | .Tn SCSI | |
116 | "bus settle delay." In CAM, it is specified in | |
117 | .Em milliseconds , | |
118 | not seconds like the old | |
119 | .Tn SCSI | |
120 | layer used to do. When the kernel boots, it sends a bus reset to each | |
121 | .Tn SCSI | |
122 | bus to tell each device to reset itself to a default set of transfer | |
123 | negotiations and other settings. Most | |
124 | .Tn SCSI | |
125 | devices need some amount of time to recover from a bus reset. Newer disks | |
126 | may need as little as 100ms, while old, slow devices may need much longer. | |
127 | If the | |
128 | .Dv SCSI_DELAY | |
129 | isn't specified, it defaults to 2 seconds. The minimum allowable value for | |
130 | .Dv SCSI_DELAY | |
131 | is "100", or 100ms. One special case is that if the | |
132 | .Dv SCSI_DELAY | |
133 | is set to 0, that will be taken to mean the "lowest possible value." In | |
134 | that case, the | |
135 | .Dv SCSI_DELAY | |
136 | will be reset to 100ms. | |
137 | .El | |
138 | .Pp | |
139 | All devices and the SCSI busses support boot time allocation so that | |
140 | an upper number of devices and controllers does not need to be configured; | |
141 | .Cd "device da0" | |
142 | will suffice for any number of disk drivers. | |
143 | .Pp | |
144 | The devices are either | |
145 | .Em wired | |
146 | so they appear as a particular device unit or | |
147 | .Em counted | |
148 | so that they appear as the next available unused unit. | |
149 | .Pp | |
150 | To configure a driver in the kernel without wiring down the device use a | |
151 | config line similar to | |
152 | .Cd "device ch0" | |
153 | to include the changer driver. | |
154 | .Pp | |
155 | To wire down a unit use a config line similar to | |
156 | .Cd "device ch1 at scbus0 target 4 unit 0" | |
157 | to assign changer 1 as the changer with SCSI ID 4, | |
158 | SCSI logical unit 0 on SCSI bus 0. | |
159 | Individual scbuses can be wired down to specific controllers with | |
160 | a config line similar to | |
7efec73e SW |
161 | .Cd "device scbus0 at ahci0" |
162 | which assigns scsi bus 0 to the first unit using the ahci driver. | |
984263bc MD |
163 | For controllers supporting more than one bus, |
164 | the particular bus can be specified as in | |
7efec73e SW |
165 | .Cd "device scbus3 at ahci1 bus 1" |
166 | which assigns scbus 1 to the second bus probed on the ahci1 device. | |
984263bc MD |
167 | .Pp |
168 | When you have a mixture of wired down and counted devices then the | |
169 | counting begins with the first non-wired down unit for a particular | |
170 | type. That is, if you have a disk wired down as | |
171 | .Em "device da1" , | |
172 | then the first non-wired disk shall come on line as | |
173 | .Em da2 . | |
174 | .Sh ADAPTERS | |
175 | The system allows common device drivers to work through many different | |
176 | types of adapters. | |
177 | The adapters take requests from the upper layers and do | |
178 | all IO between the | |
179 | .Em SCSI | |
180 | bus and the system. | |
181 | The maximum size of a transfer is governed by the | |
182 | adapter. | |
183 | Most adapters can transfer 64KB in a single operation, however | |
184 | many can transfer larger amounts. | |
185 | .Sh TARGET MODE | |
186 | Some adapters support | |
187 | .Em target mode | |
188 | in which the system is capable of operating as a device, responding to | |
189 | operations initiated by another system. | |
190 | Target mode is supported for | |
191 | some adapters, but is not yet complete for this version of the CAM | |
192 | .Tn SCSI | |
193 | subsystem. | |
194 | .Sh FILES | |
195 | see other scsi device entries. | |
196 | .Sh DIAGNOSTICS | |
a156c807 SW |
197 | When the kernel is compiled with |
198 | .Cd "options CAMDEBUG" , | |
199 | an XPT_DEBUG CCB can be | |
984263bc MD |
200 | used to enable various amounts of tracing information on any |
201 | specific device. | |
202 | Devices not being traced will not produce trace information. | |
203 | There are currently four debugging flags that may be turned on: | |
204 | .Bl -tag -width CAM_DEBUG_SUBTRACE | |
205 | .It Dv CAM_DEBUG_INFO | |
206 | This debugging flag enables general informational printfs for the device | |
207 | or devices in question. | |
208 | .It Dv CAM_DEBUG_TRACE | |
209 | This debugging flag enables function-level command flow tracing. i.e.\& | |
210 | kernel printfs will happen at the entrance and exit of various functions. | |
211 | .It Dv CAM_DEBUG_SUBTRACE | |
212 | This debugging flag enables debugging output internal to various functions. | |
213 | .It Dv CAM_DEBUG_CDB | |
214 | This debugging flag will cause the kernel to print out all | |
215 | .Tn SCSI | |
216 | commands sent to a particular device or devices. | |
217 | .El | |
218 | .Pp | |
219 | Some of these flags, most notably | |
220 | .Dv CAM_DEBUG_TRACE | |
221 | and | |
222 | .Dv CAM_DEBUG_SUBTRACE | |
223 | will produce kernel printfs in EXTREME numbers. Because of that, they | |
224 | aren't especially useful. There aren't many things logged at the | |
225 | .Dv CAM_DEBUG_INFO | |
226 | level, so it isn't especially useful. The most useful debugging flag is | |
227 | the | |
228 | .Dv CAM_DEBUG_CDB | |
229 | flag. Users can enable debugging from their kernel config file, by using | |
230 | the following kernel config options: | |
231 | .Bl -tag -width CAM_DEBUG_TARGET | |
232 | .It Dv CAMDEBUG | |
233 | This enables CAM debugging. Without this option, users will not even be able | |
234 | to turn on debugging from userland via | |
235 | .Xr camcontrol 8 . | |
236 | .It Dv CAM_DEBUG_FLAGS | |
237 | This allows the user to set the various debugging flags described above | |
238 | in a kernel config file. Flags may be ORed together if the user wishes to | |
239 | see printfs for multiple debugging levels. | |
240 | .It Dv CAM_DEBUG_BUS | |
241 | Specify a bus to debug. To debug all busses, set this to -1. | |
242 | .It Dv CAM_DEBUG_TARGET | |
243 | Specify a target to debug. To debug all targets, set this to -1. | |
244 | .It Dv CAM_DEBUG_LUN | |
245 | Specify a lun to debug. To debug all luns, set this to -1. | |
246 | .El | |
247 | .Pp | |
248 | When specifying a bus, target or lun to debug, you | |
249 | .Em MUST | |
250 | specify all three bus/target/lun options above. Using wildcards, you | |
251 | should be able to enable debugging on most anything. | |
252 | .Pp | |
253 | Users may also enable debugging printfs on the fly, if the | |
254 | .Dv CAMDEBUG | |
255 | option is their config file, by using the | |
256 | .Xr camcontrol 8 | |
257 | utility. See | |
258 | .Xr camcontrol 8 | |
259 | for details. | |
260 | .Sh SEE ALSO | |
7efec73e | 261 | .Xr ahci 4 , |
984263bc MD |
262 | .Xr bt 4 , |
263 | .Xr cd 4 , | |
264 | .Xr ch 4 , | |
265 | .Xr da 4 , | |
266 | .Xr pass 4 , | |
267 | .Xr pt 4 , | |
268 | .Xr sa 4 , | |
269 | .Xr xpt 4 , | |
270 | .Xr camcontrol 8 | |
271 | .Sh HISTORY | |
272 | The CAM | |
273 | .Tn SCSI | |
274 | subsystem first appeared in | |
275 | .Fx 3.0 . | |
276 | .Sh AUTHORS | |
277 | .An -nosplit | |
278 | The CAM | |
279 | .Tn SCSI | |
280 | subsystem was written by | |
281 | .An Justin Gibbs | |
282 | and | |
283 | .An Kenneth Merry . |