summaryrefslogtreecommitdiffstats
path: root/share/man/man4/scsi.4
blob: ad52663c070d12bdec90969fe1bc74036ab4be6a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
.\" 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 March 4, 2010
.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_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 enables the
.Nm
debugging printf code.
This will not actually
cause any debugging information to be printed out when included by itself.
Enabling printouts requires additional configuration.
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
When the kernel is compiled with options CAMDEBUG, an XPT_DEBUG CCB can be
used to enable various amounts of tracing information on any
specific device.
Devices not being traced will not produce trace information.
There are currently four debugging flags that may be turned on:
.Bl -tag -width CAM_DEBUG_SUBTRACE
.It Dv CAM_DEBUG_INFO
This debugging flag enables general informational printfs for the device
or devices in question.
.It Dv CAM_DEBUG_TRACE
This debugging 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 debugging flag enables debugging output internal to various functions.
.It Dv CAM_DEBUG_CDB
This debugging flag will cause the kernel to print out all
.Tn SCSI
commands sent to a particular device or devices.
.El
.Pp
Some of these flags, most notably
.Dv CAM_DEBUG_TRACE
and
.Dv CAM_DEBUG_SUBTRACE
will produce kernel printfs in EXTREME numbers,
and because of that, they are not especially useful.
There are not many things logged at the
.Dv CAM_DEBUG_INFO
level, so it is not especially useful.
The most useful debugging flag is the
.Dv CAM_DEBUG_CDB
flag.
Users can enable debugging from their kernel config file, by using
the following kernel config options:
.Bl -tag -width CAM_DEBUG_TARGET
.It Dv CAMDEBUG
This enables
.Nm
debugging.
Without this option, users will not even be able
to turn on debugging from userland via
.Xr camcontrol 8 .
.It Dv CAM_DEBUG_FLAGS
This allows the user to set the various debugging flags described above
in a kernel config file.
Flags may be ORed together if the user wishes to
see printfs for multiple debugging levels.
.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
When specifying a bus, target or lun to debug, you
.Em MUST
specify all three bus/target/lun options above.
Using wildcards, you
should be able to enable debugging on most anything.
.Pp
Users may also enable debugging printfs on the fly, if the
.Dv CAMDEBUG
option is their config file, by using the
.Xr camcontrol 8
utility.
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 .
OpenPOWER on IntegriCloud