1 |
3 |
xianfeng |
Linux Kernel 2.6 series
|
2 |
|
|
SCSI mid_level - lower_level driver interface
|
3 |
|
|
=============================================
|
4 |
|
|
|
5 |
|
|
Introduction
|
6 |
|
|
============
|
7 |
|
|
This document outlines the interface between the Linux SCSI mid level and
|
8 |
|
|
SCSI lower level drivers. Lower level drivers (LLDs) are variously called
|
9 |
|
|
host bus adapter (HBA) drivers and host drivers (HD). A "host" in this
|
10 |
|
|
context is a bridge between a computer IO bus (e.g. PCI or ISA) and a
|
11 |
|
|
single SCSI initiator port on a SCSI transport. An "initiator" port
|
12 |
|
|
(SCSI terminology, see SAM-3 at http://www.t10.org) sends SCSI commands
|
13 |
|
|
to "target" SCSI ports (e.g. disks). There can be many LLDs in a running
|
14 |
|
|
system, but only one per hardware type. Most LLDs can control one or more
|
15 |
|
|
SCSI HBAs. Some HBAs contain multiple hosts.
|
16 |
|
|
|
17 |
|
|
In some cases the SCSI transport is an external bus that already has
|
18 |
|
|
its own subsystem in Linux (e.g. USB and ieee1394). In such cases the
|
19 |
|
|
SCSI subsystem LLD is a software bridge to the other driver subsystem.
|
20 |
|
|
Examples are the usb-storage driver (found in the drivers/usb/storage
|
21 |
|
|
directory) and the ieee1394/sbp2 driver (found in the drivers/ieee1394
|
22 |
|
|
directory).
|
23 |
|
|
|
24 |
|
|
For example, the aic7xxx LLD controls Adaptec SCSI parallel interface
|
25 |
|
|
(SPI) controllers based on that company's 7xxx chip series. The aic7xxx
|
26 |
|
|
LLD can be built into the kernel or loaded as a module. There can only be
|
27 |
|
|
one aic7xxx LLD running in a Linux system but it may be controlling many
|
28 |
|
|
HBAs. These HBAs might be either on PCI daughter-boards or built into
|
29 |
|
|
the motherboard (or both). Some aic7xxx based HBAs are dual controllers
|
30 |
|
|
and thus represent two hosts. Like most modern HBAs, each aic7xxx host
|
31 |
|
|
has its own PCI device address. [The one-to-one correspondence between
|
32 |
|
|
a SCSI host and a PCI device is common but not required (e.g. with
|
33 |
|
|
ISA or MCA adapters).]
|
34 |
|
|
|
35 |
|
|
The SCSI mid level isolates an LLD from other layers such as the SCSI
|
36 |
|
|
upper layer drivers and the block layer.
|
37 |
|
|
|
38 |
|
|
This version of the document roughly matches linux kernel version 2.6.8 .
|
39 |
|
|
|
40 |
|
|
Documentation
|
41 |
|
|
=============
|
42 |
|
|
There is a SCSI documentation directory within the kernel source tree,
|
43 |
|
|
typically Documentation/scsi . Most documents are in plain
|
44 |
|
|
(i.e. ASCII) text. This file is named scsi_mid_low_api.txt and can be
|
45 |
|
|
found in that directory. A more recent copy of this document may be found
|
46 |
|
|
at http://www.torque.net/scsi/scsi_mid_low_api.txt.gz .
|
47 |
|
|
Many LLDs are documented there (e.g. aic7xxx.txt). The SCSI mid-level is
|
48 |
|
|
briefly described in scsi.txt which contains a url to a document
|
49 |
|
|
describing the SCSI subsystem in the lk 2.4 series. Two upper level
|
50 |
|
|
drivers have documents in that directory: st.txt (SCSI tape driver) and
|
51 |
|
|
scsi-generic.txt (for the sg driver).
|
52 |
|
|
|
53 |
|
|
Some documentation (or urls) for LLDs may be found in the C source code
|
54 |
|
|
or in the same directory as the C source code. For example to find a url
|
55 |
|
|
about the USB mass storage driver see the
|
56 |
|
|
/usr/src/linux/drivers/usb/storage directory.
|
57 |
|
|
|
58 |
|
|
The Linux kernel source Documentation/DocBook/scsidrivers.tmpl file
|
59 |
|
|
refers to this file. With the appropriate DocBook tool-set, this permits
|
60 |
|
|
users to generate html, ps and pdf renderings of information within this
|
61 |
|
|
file (e.g. the interface functions).
|
62 |
|
|
|
63 |
|
|
Driver structure
|
64 |
|
|
================
|
65 |
|
|
Traditionally an LLD for the SCSI subsystem has been at least two files in
|
66 |
|
|
the drivers/scsi directory. For example, a driver called "xyz" has a header
|
67 |
|
|
file "xyz.h" and a source file "xyz.c". [Actually there is no good reason
|
68 |
|
|
why this couldn't all be in one file; the header file is superfluous.] Some
|
69 |
|
|
drivers that have been ported to several operating systems have more than
|
70 |
|
|
two files. For example the aic7xxx driver has separate files for generic
|
71 |
|
|
and OS-specific code (e.g. FreeBSD and Linux). Such drivers tend to have
|
72 |
|
|
their own directory under the drivers/scsi directory.
|
73 |
|
|
|
74 |
|
|
When a new LLD is being added to Linux, the following files (found in the
|
75 |
|
|
drivers/scsi directory) will need some attention: Makefile and Kconfig .
|
76 |
|
|
It is probably best to study how existing LLDs are organized.
|
77 |
|
|
|
78 |
|
|
As the 2.5 series development kernels evolve into the 2.6 series
|
79 |
|
|
production series, changes are being introduced into this interface. An
|
80 |
|
|
example of this is driver initialization code where there are now 2 models
|
81 |
|
|
available. The older one, similar to what was found in the lk 2.4 series,
|
82 |
|
|
is based on hosts that are detected at HBA driver load time. This will be
|
83 |
|
|
referred to the "passive" initialization model. The newer model allows HBAs
|
84 |
|
|
to be hot plugged (and unplugged) during the lifetime of the LLD and will
|
85 |
|
|
be referred to as the "hotplug" initialization model. The newer model is
|
86 |
|
|
preferred as it can handle both traditional SCSI equipment that is
|
87 |
|
|
permanently connected as well as modern "SCSI" devices (e.g. USB or
|
88 |
|
|
IEEE 1394 connected digital cameras) that are hotplugged. Both
|
89 |
|
|
initialization models are discussed in the following sections.
|
90 |
|
|
|
91 |
|
|
An LLD interfaces to the SCSI subsystem several ways:
|
92 |
|
|
a) directly invoking functions supplied by the mid level
|
93 |
|
|
b) passing a set of function pointers to a registration function
|
94 |
|
|
supplied by the mid level. The mid level will then invoke these
|
95 |
|
|
functions at some point in the future. The LLD will supply
|
96 |
|
|
implementations of these functions.
|
97 |
|
|
c) direct access to instances of well known data structures maintained
|
98 |
|
|
by the mid level
|
99 |
|
|
|
100 |
|
|
Those functions in group a) are listed in a section entitled "Mid level
|
101 |
|
|
supplied functions" below.
|
102 |
|
|
|
103 |
|
|
Those functions in group b) are listed in a section entitled "Interface
|
104 |
|
|
functions" below. Their function pointers are placed in the members of
|
105 |
|
|
"struct scsi_host_template", an instance of which is passed to
|
106 |
|
|
scsi_host_alloc() ** . Those interface functions that the LLD does not
|
107 |
|
|
wish to supply should have NULL placed in the corresponding member of
|
108 |
|
|
struct scsi_host_template. Defining an instance of struct
|
109 |
|
|
scsi_host_template at file scope will cause NULL to be placed in function
|
110 |
|
|
pointer members not explicitly initialized.
|
111 |
|
|
|
112 |
|
|
Those usages in group c) should be handled with care, especially in a
|
113 |
|
|
"hotplug" environment. LLDs should be aware of the lifetime of instances
|
114 |
|
|
that are shared with the mid level and other layers.
|
115 |
|
|
|
116 |
|
|
All functions defined within an LLD and all data defined at file scope
|
117 |
|
|
should be static. For example the slave_alloc() function in an LLD
|
118 |
|
|
called "xxx" could be defined as
|
119 |
|
|
"static int xxx_slave_alloc(struct scsi_device * sdev) { /* code */ }"
|
120 |
|
|
|
121 |
|
|
** the scsi_host_alloc() function is a replacement for the rather vaguely
|
122 |
|
|
named scsi_register() function in most situations. The scsi_register()
|
123 |
|
|
and scsi_unregister() functions remain to support legacy LLDs that use
|
124 |
|
|
the passive initialization model.
|
125 |
|
|
|
126 |
|
|
|
127 |
|
|
Hotplug initialization model
|
128 |
|
|
============================
|
129 |
|
|
In this model an LLD controls when SCSI hosts are introduced and removed
|
130 |
|
|
from the SCSI subsystem. Hosts can be introduced as early as driver
|
131 |
|
|
initialization and removed as late as driver shutdown. Typically a driver
|
132 |
|
|
will respond to a sysfs probe() callback that indicates an HBA has been
|
133 |
|
|
detected. After confirming that the new device is one that the LLD wants
|
134 |
|
|
to control, the LLD will initialize the HBA and then register a new host
|
135 |
|
|
with the SCSI mid level.
|
136 |
|
|
|
137 |
|
|
During LLD initialization the driver should register itself with the
|
138 |
|
|
appropriate IO bus on which it expects to find HBA(s) (e.g. the PCI bus).
|
139 |
|
|
This can probably be done via sysfs. Any driver parameters (especially
|
140 |
|
|
those that are writable after the driver is loaded) could also be
|
141 |
|
|
registered with sysfs at this point. The SCSI mid level first becomes
|
142 |
|
|
aware of an LLD when that LLD registers its first HBA.
|
143 |
|
|
|
144 |
|
|
At some later time, the LLD becomes aware of an HBA and what follows
|
145 |
|
|
is a typical sequence of calls between the LLD and the mid level.
|
146 |
|
|
This example shows the mid level scanning the newly introduced HBA for 3
|
147 |
|
|
scsi devices of which only the first 2 respond:
|
148 |
|
|
|
149 |
|
|
HBA PROBE: assume 2 SCSI devices found in scan
|
150 |
|
|
LLD mid level LLD
|
151 |
|
|
===-------------------=========--------------------===------
|
152 |
|
|
scsi_host_alloc() -->
|
153 |
|
|
scsi_add_host() ---->
|
154 |
|
|
scsi_scan_host() -------+
|
155 |
|
|
|
|
156 |
|
|
slave_alloc()
|
157 |
|
|
slave_configure() --> scsi_adjust_queue_depth()
|
158 |
|
|
|
|
159 |
|
|
slave_alloc()
|
160 |
|
|
slave_configure()
|
161 |
|
|
|
|
162 |
|
|
slave_alloc() ***
|
163 |
|
|
slave_destroy() ***
|
164 |
|
|
------------------------------------------------------------
|
165 |
|
|
|
166 |
|
|
If the LLD wants to adjust the default queue settings, it can invoke
|
167 |
|
|
scsi_adjust_queue_depth() in its slave_configure() routine.
|
168 |
|
|
|
169 |
|
|
*** For scsi devices that the mid level tries to scan but do not
|
170 |
|
|
respond, a slave_alloc(), slave_destroy() pair is called.
|
171 |
|
|
|
172 |
|
|
When an HBA is being removed it could be as part of an orderly shutdown
|
173 |
|
|
associated with the LLD module being unloaded (e.g. with the "rmmod"
|
174 |
|
|
command) or in response to a "hot unplug" indicated by sysfs()'s
|
175 |
|
|
remove() callback being invoked. In either case, the sequence is the
|
176 |
|
|
same:
|
177 |
|
|
|
178 |
|
|
HBA REMOVE: assume 2 SCSI devices attached
|
179 |
|
|
LLD mid level LLD
|
180 |
|
|
===----------------------=========-----------------===------
|
181 |
|
|
scsi_remove_host() ---------+
|
182 |
|
|
|
|
183 |
|
|
slave_destroy()
|
184 |
|
|
slave_destroy()
|
185 |
|
|
scsi_host_put()
|
186 |
|
|
------------------------------------------------------------
|
187 |
|
|
|
188 |
|
|
It may be useful for a LLD to keep track of struct Scsi_Host instances
|
189 |
|
|
(a pointer is returned by scsi_host_alloc()). Such instances are "owned"
|
190 |
|
|
by the mid-level. struct Scsi_Host instances are freed from
|
191 |
|
|
scsi_host_put() when the reference count hits zero.
|
192 |
|
|
|
193 |
|
|
Hot unplugging an HBA that controls a disk which is processing SCSI
|
194 |
|
|
commands on a mounted file system is an interesting situation. Reference
|
195 |
|
|
counting logic is being introduced into the mid level to cope with many
|
196 |
|
|
of the issues involved. See the section on reference counting below.
|
197 |
|
|
|
198 |
|
|
|
199 |
|
|
The hotplug concept may be extended to SCSI devices. Currently, when an
|
200 |
|
|
HBA is added, the scsi_scan_host() function causes a scan for SCSI devices
|
201 |
|
|
attached to the HBA's SCSI transport. On newer SCSI transports the HBA
|
202 |
|
|
may become aware of a new SCSI device _after_ the scan has completed.
|
203 |
|
|
An LLD can use this sequence to make the mid level aware of a SCSI device:
|
204 |
|
|
|
205 |
|
|
SCSI DEVICE hotplug
|
206 |
|
|
LLD mid level LLD
|
207 |
|
|
===-------------------=========--------------------===------
|
208 |
|
|
scsi_add_device() ------+
|
209 |
|
|
|
|
210 |
|
|
slave_alloc()
|
211 |
|
|
slave_configure() [--> scsi_adjust_queue_depth()]
|
212 |
|
|
------------------------------------------------------------
|
213 |
|
|
|
214 |
|
|
In a similar fashion, an LLD may become aware that a SCSI device has been
|
215 |
|
|
removed (unplugged) or the connection to it has been interrupted. Some
|
216 |
|
|
existing SCSI transports (e.g. SPI) may not become aware that a SCSI
|
217 |
|
|
device has been removed until a subsequent SCSI command fails which will
|
218 |
|
|
probably cause that device to be set offline by the mid level. An LLD that
|
219 |
|
|
detects the removal of a SCSI device can instigate its removal from
|
220 |
|
|
upper layers with this sequence:
|
221 |
|
|
|
222 |
|
|
SCSI DEVICE hot unplug
|
223 |
|
|
LLD mid level LLD
|
224 |
|
|
===----------------------=========-----------------===------
|
225 |
|
|
scsi_remove_device() -------+
|
226 |
|
|
|
|
227 |
|
|
slave_destroy()
|
228 |
|
|
------------------------------------------------------------
|
229 |
|
|
|
230 |
|
|
It may be useful for an LLD to keep track of struct scsi_device instances
|
231 |
|
|
(a pointer is passed as the parameter to slave_alloc() and
|
232 |
|
|
slave_configure() callbacks). Such instances are "owned" by the mid-level.
|
233 |
|
|
struct scsi_device instances are freed after slave_destroy().
|
234 |
|
|
|
235 |
|
|
|
236 |
|
|
Passive initialization model
|
237 |
|
|
============================
|
238 |
|
|
These older LLDs include a file called "scsi_module.c" [yes the ".c" is a
|
239 |
|
|
little surprising] in their source code. For that file to work an
|
240 |
|
|
instance of struct scsi_host_template with the name "driver_template"
|
241 |
|
|
needs to be defined. Here is a typical code sequence used in this model:
|
242 |
|
|
static struct scsi_host_template driver_template = {
|
243 |
|
|
...
|
244 |
|
|
};
|
245 |
|
|
#include "scsi_module.c"
|
246 |
|
|
|
247 |
|
|
The scsi_module.c file contains two functions:
|
248 |
|
|
- init_this_scsi_driver() which is executed when the LLD is
|
249 |
|
|
initialized (i.e. boot time or module load time)
|
250 |
|
|
- exit_this_scsi_driver() which is executed when the LLD is shut
|
251 |
|
|
down (i.e. module unload time)
|
252 |
|
|
Note: since these functions are tagged with __init and __exit qualifiers
|
253 |
|
|
an LLD should not call them explicitly (since the kernel does that).
|
254 |
|
|
|
255 |
|
|
Here is an example of an initialization sequence when two hosts are
|
256 |
|
|
detected (so detect() returns 2) and the SCSI bus scan on each host
|
257 |
|
|
finds 1 SCSI device (and a second device does not respond).
|
258 |
|
|
|
259 |
|
|
LLD mid level LLD
|
260 |
|
|
===----------------------=========-----------------===------
|
261 |
|
|
init_this_scsi_driver() ----+
|
262 |
|
|
|
|
263 |
|
|
detect() -----------------+
|
264 |
|
|
| |
|
265 |
|
|
| scsi_register()
|
266 |
|
|
| scsi_register()
|
267 |
|
|
|
|
268 |
|
|
slave_alloc()
|
269 |
|
|
slave_configure() --> scsi_adjust_queue_depth()
|
270 |
|
|
slave_alloc() ***
|
271 |
|
|
slave_destroy() ***
|
272 |
|
|
|
|
273 |
|
|
slave_alloc()
|
274 |
|
|
slave_configure()
|
275 |
|
|
slave_alloc() ***
|
276 |
|
|
slave_destroy() ***
|
277 |
|
|
------------------------------------------------------------
|
278 |
|
|
|
279 |
|
|
The mid level invokes scsi_adjust_queue_depth() with tagged queuing off and
|
280 |
|
|
"cmd_per_lun" for that host as the queue length. These settings can be
|
281 |
|
|
overridden by a slave_configure() supplied by the LLD.
|
282 |
|
|
|
283 |
|
|
*** For scsi devices that the mid level tries to scan but do not
|
284 |
|
|
respond, a slave_alloc(), slave_destroy() pair is called.
|
285 |
|
|
|
286 |
|
|
Here is an LLD shutdown sequence:
|
287 |
|
|
|
288 |
|
|
LLD mid level LLD
|
289 |
|
|
===----------------------=========-----------------===------
|
290 |
|
|
exit_this_scsi_driver() ----+
|
291 |
|
|
|
|
292 |
|
|
slave_destroy()
|
293 |
|
|
release() --> scsi_unregister()
|
294 |
|
|
|
|
295 |
|
|
slave_destroy()
|
296 |
|
|
release() --> scsi_unregister()
|
297 |
|
|
------------------------------------------------------------
|
298 |
|
|
|
299 |
|
|
An LLD need not define slave_destroy() (i.e. it is optional).
|
300 |
|
|
|
301 |
|
|
The shortcoming of the "passive initialization model" is that host
|
302 |
|
|
registration and de-registration are (typically) tied to LLD initialization
|
303 |
|
|
and shutdown. Once the LLD is initialized then a new host that appears
|
304 |
|
|
(e.g. via hotplugging) cannot easily be added without a redundant
|
305 |
|
|
driver shutdown and re-initialization. It may be possible to write an LLD
|
306 |
|
|
that uses both initialization models.
|
307 |
|
|
|
308 |
|
|
|
309 |
|
|
Reference Counting
|
310 |
|
|
==================
|
311 |
|
|
The Scsi_Host structure has had reference counting infrastructure added.
|
312 |
|
|
This effectively spreads the ownership of struct Scsi_Host instances
|
313 |
|
|
across the various SCSI layers which use them. Previously such instances
|
314 |
|
|
were exclusively owned by the mid level. LLDs would not usually need to
|
315 |
|
|
directly manipulate these reference counts but there may be some cases
|
316 |
|
|
where they do.
|
317 |
|
|
|
318 |
|
|
There are 3 reference counting functions of interest associated with
|
319 |
|
|
struct Scsi_Host:
|
320 |
|
|
- scsi_host_alloc(): returns a pointer to new instance of struct
|
321 |
|
|
Scsi_Host which has its reference count ^^ set to 1
|
322 |
|
|
- scsi_host_get(): adds 1 to the reference count of the given instance
|
323 |
|
|
- scsi_host_put(): decrements 1 from the reference count of the given
|
324 |
|
|
instance. If the reference count reaches 0 then the given instance
|
325 |
|
|
is freed
|
326 |
|
|
|
327 |
|
|
The Scsi_device structure has had reference counting infrastructure added.
|
328 |
|
|
This effectively spreads the ownership of struct Scsi_device instances
|
329 |
|
|
across the various SCSI layers which use them. Previously such instances
|
330 |
|
|
were exclusively owned by the mid level. See the access functions declared
|
331 |
|
|
towards the end of include/scsi/scsi_device.h . If an LLD wants to keep
|
332 |
|
|
a copy of a pointer to a Scsi_device instance it should use scsi_device_get()
|
333 |
|
|
to bump its reference count. When it is finished with the pointer it can
|
334 |
|
|
use scsi_device_put() to decrement its reference count (and potentially
|
335 |
|
|
delete it).
|
336 |
|
|
|
337 |
|
|
^^ struct Scsi_Host actually has 2 reference counts which are manipulated
|
338 |
|
|
in parallel by these functions.
|
339 |
|
|
|
340 |
|
|
|
341 |
|
|
Conventions
|
342 |
|
|
===========
|
343 |
|
|
First, Linus Torvalds's thoughts on C coding style can be found in the
|
344 |
|
|
Documentation/CodingStyle file.
|
345 |
|
|
|
346 |
|
|
Next, there is a movement to "outlaw" typedefs introducing synonyms for
|
347 |
|
|
struct tags. Both can be still found in the SCSI subsystem, but
|
348 |
|
|
the typedefs have been moved to a single file, scsi_typedefs.h to
|
349 |
|
|
make their future removal easier, for example:
|
350 |
|
|
"typedef struct scsi_cmnd Scsi_Cmnd;"
|
351 |
|
|
|
352 |
|
|
Also, most C99 enhancements are encouraged to the extent they are supported
|
353 |
|
|
by the relevant gcc compilers. So C99 style structure and array
|
354 |
|
|
initializers are encouraged where appropriate. Don't go too far,
|
355 |
|
|
VLAs are not properly supported yet. An exception to this is the use of
|
356 |
|
|
"//" style comments; /*...*/ comments are still preferred in Linux.
|
357 |
|
|
|
358 |
|
|
Well written, tested and documented code, need not be re-formatted to
|
359 |
|
|
comply with the above conventions. For example, the aic7xxx driver
|
360 |
|
|
comes to Linux from FreeBSD and Adaptec's own labs. No doubt FreeBSD
|
361 |
|
|
and Adaptec have their own coding conventions.
|
362 |
|
|
|
363 |
|
|
|
364 |
|
|
Mid level supplied functions
|
365 |
|
|
============================
|
366 |
|
|
These functions are supplied by the SCSI mid level for use by LLDs.
|
367 |
|
|
The names (i.e. entry points) of these functions are exported
|
368 |
|
|
so an LLD that is a module can access them. The kernel will
|
369 |
|
|
arrange for the SCSI mid level to be loaded and initialized before any LLD
|
370 |
|
|
is initialized. The functions below are listed alphabetically and their
|
371 |
|
|
names all start with "scsi_".
|
372 |
|
|
|
373 |
|
|
Summary:
|
374 |
|
|
scsi_activate_tcq - turn on tag command queueing
|
375 |
|
|
scsi_add_device - creates new scsi device (lu) instance
|
376 |
|
|
scsi_add_host - perform sysfs registration and set up transport class
|
377 |
|
|
scsi_adjust_queue_depth - change the queue depth on a SCSI device
|
378 |
|
|
scsi_bios_ptable - return copy of block device's partition table
|
379 |
|
|
scsi_block_requests - prevent further commands being queued to given host
|
380 |
|
|
scsi_deactivate_tcq - turn off tag command queueing
|
381 |
|
|
scsi_host_alloc - return a new scsi_host instance whose refcount==1
|
382 |
|
|
scsi_host_get - increments Scsi_Host instance's refcount
|
383 |
|
|
scsi_host_put - decrements Scsi_Host instance's refcount (free if 0)
|
384 |
|
|
scsi_partsize - parse partition table into cylinders, heads + sectors
|
385 |
|
|
scsi_register - create and register a scsi host adapter instance.
|
386 |
|
|
scsi_remove_device - detach and remove a SCSI device
|
387 |
|
|
scsi_remove_host - detach and remove all SCSI devices owned by host
|
388 |
|
|
scsi_report_bus_reset - report scsi _bus_ reset observed
|
389 |
|
|
scsi_scan_host - scan SCSI bus
|
390 |
|
|
scsi_track_queue_full - track successive QUEUE_FULL events
|
391 |
|
|
scsi_unblock_requests - allow further commands to be queued to given host
|
392 |
|
|
scsi_unregister - [calls scsi_host_put()]
|
393 |
|
|
|
394 |
|
|
|
395 |
|
|
Details:
|
396 |
|
|
|
397 |
|
|
/**
|
398 |
|
|
* scsi_activate_tcq - turn on tag command queueing ("ordered" task attribute)
|
399 |
|
|
* @sdev: device to turn on TCQ for
|
400 |
|
|
* @depth: queue depth
|
401 |
|
|
*
|
402 |
|
|
* Returns nothing
|
403 |
|
|
*
|
404 |
|
|
* Might block: no
|
405 |
|
|
*
|
406 |
|
|
* Notes: Eventually, it is hoped depth would be the maximum depth
|
407 |
|
|
* the device could cope with and the real queue depth
|
408 |
|
|
* would be adjustable from 0 to depth.
|
409 |
|
|
*
|
410 |
|
|
* Defined (inline) in: include/scsi/scsi_tcq.h
|
411 |
|
|
**/
|
412 |
|
|
void scsi_activate_tcq(struct scsi_device *sdev, int depth)
|
413 |
|
|
|
414 |
|
|
|
415 |
|
|
/**
|
416 |
|
|
* scsi_add_device - creates new scsi device (lu) instance
|
417 |
|
|
* @shost: pointer to scsi host instance
|
418 |
|
|
* @channel: channel number (rarely other than 0)
|
419 |
|
|
* @id: target id number
|
420 |
|
|
* @lun: logical unit number
|
421 |
|
|
*
|
422 |
|
|
* Returns pointer to new struct scsi_device instance or
|
423 |
|
|
* ERR_PTR(-ENODEV) (or some other bent pointer) if something is
|
424 |
|
|
* wrong (e.g. no lu responds at given address)
|
425 |
|
|
*
|
426 |
|
|
* Might block: yes
|
427 |
|
|
*
|
428 |
|
|
* Notes: This call is usually performed internally during a scsi
|
429 |
|
|
* bus scan when an HBA is added (i.e. scsi_scan_host()). So it
|
430 |
|
|
* should only be called if the HBA becomes aware of a new scsi
|
431 |
|
|
* device (lu) after scsi_scan_host() has completed. If successful
|
432 |
|
|
* this call can lead to slave_alloc() and slave_configure() callbacks
|
433 |
|
|
* into the LLD.
|
434 |
|
|
*
|
435 |
|
|
* Defined in: drivers/scsi/scsi_scan.c
|
436 |
|
|
**/
|
437 |
|
|
struct scsi_device * scsi_add_device(struct Scsi_Host *shost,
|
438 |
|
|
unsigned int channel,
|
439 |
|
|
unsigned int id, unsigned int lun)
|
440 |
|
|
|
441 |
|
|
|
442 |
|
|
/**
|
443 |
|
|
* scsi_add_host - perform sysfs registration and set up transport class
|
444 |
|
|
* @shost: pointer to scsi host instance
|
445 |
|
|
* @dev: pointer to struct device of type scsi class
|
446 |
|
|
*
|
447 |
|
|
* Returns 0 on success, negative errno of failure (e.g. -ENOMEM)
|
448 |
|
|
*
|
449 |
|
|
* Might block: no
|
450 |
|
|
*
|
451 |
|
|
* Notes: Only required in "hotplug initialization model" after a
|
452 |
|
|
* successful call to scsi_host_alloc(). This function does not
|
453 |
|
|
* scan the bus; this can be done by calling scsi_scan_host() or
|
454 |
|
|
* in some other transport-specific way. The LLD must set up
|
455 |
|
|
* the transport template before calling this function and may only
|
456 |
|
|
* access the transport class data after this function has been called.
|
457 |
|
|
*
|
458 |
|
|
* Defined in: drivers/scsi/hosts.c
|
459 |
|
|
**/
|
460 |
|
|
int scsi_add_host(struct Scsi_Host *shost, struct device * dev)
|
461 |
|
|
|
462 |
|
|
|
463 |
|
|
/**
|
464 |
|
|
* scsi_adjust_queue_depth - allow LLD to change queue depth on a SCSI device
|
465 |
|
|
* @sdev: pointer to SCSI device to change queue depth on
|
466 |
|
|
* @tagged: 0 - no tagged queuing
|
467 |
|
|
* MSG_SIMPLE_TAG - simple tagged queuing
|
468 |
|
|
* MSG_ORDERED_TAG - ordered tagged queuing
|
469 |
|
|
* @tags Number of tags allowed if tagged queuing enabled,
|
470 |
|
|
* or number of commands the LLD can queue up
|
471 |
|
|
* in non-tagged mode (as per cmd_per_lun).
|
472 |
|
|
*
|
473 |
|
|
* Returns nothing
|
474 |
|
|
*
|
475 |
|
|
* Might block: no
|
476 |
|
|
*
|
477 |
|
|
* Notes: Can be invoked any time on a SCSI device controlled by this
|
478 |
|
|
* LLD. [Specifically during and after slave_configure() and prior to
|
479 |
|
|
* slave_destroy().] Can safely be invoked from interrupt code. Actual
|
480 |
|
|
* queue depth change may be delayed until the next command is being
|
481 |
|
|
* processed. See also scsi_activate_tcq() and scsi_deactivate_tcq().
|
482 |
|
|
*
|
483 |
|
|
* Defined in: drivers/scsi/scsi.c [see source code for more notes]
|
484 |
|
|
*
|
485 |
|
|
**/
|
486 |
|
|
void scsi_adjust_queue_depth(struct scsi_device * sdev, int tagged,
|
487 |
|
|
int tags)
|
488 |
|
|
|
489 |
|
|
|
490 |
|
|
/**
|
491 |
|
|
* scsi_bios_ptable - return copy of block device's partition table
|
492 |
|
|
* @dev: pointer to block device
|
493 |
|
|
*
|
494 |
|
|
* Returns pointer to partition table, or NULL for failure
|
495 |
|
|
*
|
496 |
|
|
* Might block: yes
|
497 |
|
|
*
|
498 |
|
|
* Notes: Caller owns memory returned (free with kfree() )
|
499 |
|
|
*
|
500 |
|
|
* Defined in: drivers/scsi/scsicam.c
|
501 |
|
|
**/
|
502 |
|
|
unsigned char *scsi_bios_ptable(struct block_device *dev)
|
503 |
|
|
|
504 |
|
|
|
505 |
|
|
/**
|
506 |
|
|
* scsi_block_requests - prevent further commands being queued to given host
|
507 |
|
|
*
|
508 |
|
|
* @shost: pointer to host to block commands on
|
509 |
|
|
*
|
510 |
|
|
* Returns nothing
|
511 |
|
|
*
|
512 |
|
|
* Might block: no
|
513 |
|
|
*
|
514 |
|
|
* Notes: There is no timer nor any other means by which the requests
|
515 |
|
|
* get unblocked other than the LLD calling scsi_unblock_requests().
|
516 |
|
|
*
|
517 |
|
|
* Defined in: drivers/scsi/scsi_lib.c
|
518 |
|
|
**/
|
519 |
|
|
void scsi_block_requests(struct Scsi_Host * shost)
|
520 |
|
|
|
521 |
|
|
|
522 |
|
|
/**
|
523 |
|
|
* scsi_deactivate_tcq - turn off tag command queueing
|
524 |
|
|
* @sdev: device to turn off TCQ for
|
525 |
|
|
* @depth: queue depth (stored in sdev)
|
526 |
|
|
*
|
527 |
|
|
* Returns nothing
|
528 |
|
|
*
|
529 |
|
|
* Might block: no
|
530 |
|
|
*
|
531 |
|
|
* Defined (inline) in: include/scsi/scsi_tcq.h
|
532 |
|
|
**/
|
533 |
|
|
void scsi_deactivate_tcq(struct scsi_device *sdev, int depth)
|
534 |
|
|
|
535 |
|
|
|
536 |
|
|
/**
|
537 |
|
|
* scsi_host_alloc - create a scsi host adapter instance and perform basic
|
538 |
|
|
* initialization.
|
539 |
|
|
* @sht: pointer to scsi host template
|
540 |
|
|
* @privsize: extra bytes to allocate in hostdata array (which is the
|
541 |
|
|
* last member of the returned Scsi_Host instance)
|
542 |
|
|
*
|
543 |
|
|
* Returns pointer to new Scsi_Host instance or NULL on failure
|
544 |
|
|
*
|
545 |
|
|
* Might block: yes
|
546 |
|
|
*
|
547 |
|
|
* Notes: When this call returns to the LLD, the SCSI bus scan on
|
548 |
|
|
* this host has _not_ yet been done.
|
549 |
|
|
* The hostdata array (by default zero length) is a per host scratch
|
550 |
|
|
* area for the LLD's exclusive use.
|
551 |
|
|
* Both associated refcounting objects have their refcount set to 1.
|
552 |
|
|
* Full registration (in sysfs) and a bus scan are performed later when
|
553 |
|
|
* scsi_add_host() and scsi_scan_host() are called.
|
554 |
|
|
*
|
555 |
|
|
* Defined in: drivers/scsi/hosts.c .
|
556 |
|
|
**/
|
557 |
|
|
struct Scsi_Host * scsi_host_alloc(struct scsi_host_template * sht,
|
558 |
|
|
int privsize)
|
559 |
|
|
|
560 |
|
|
|
561 |
|
|
/**
|
562 |
|
|
* scsi_host_get - increment Scsi_Host instance refcount
|
563 |
|
|
* @shost: pointer to struct Scsi_Host instance
|
564 |
|
|
*
|
565 |
|
|
* Returns nothing
|
566 |
|
|
*
|
567 |
|
|
* Might block: currently may block but may be changed to not block
|
568 |
|
|
*
|
569 |
|
|
* Notes: Actually increments the counts in two sub-objects
|
570 |
|
|
*
|
571 |
|
|
* Defined in: drivers/scsi/hosts.c
|
572 |
|
|
**/
|
573 |
|
|
void scsi_host_get(struct Scsi_Host *shost)
|
574 |
|
|
|
575 |
|
|
|
576 |
|
|
/**
|
577 |
|
|
* scsi_host_put - decrement Scsi_Host instance refcount, free if 0
|
578 |
|
|
* @shost: pointer to struct Scsi_Host instance
|
579 |
|
|
*
|
580 |
|
|
* Returns nothing
|
581 |
|
|
*
|
582 |
|
|
* Might block: currently may block but may be changed to not block
|
583 |
|
|
*
|
584 |
|
|
* Notes: Actually decrements the counts in two sub-objects. If the
|
585 |
|
|
* latter refcount reaches 0, the Scsi_Host instance is freed.
|
586 |
|
|
* The LLD need not worry exactly when the Scsi_Host instance is
|
587 |
|
|
* freed, it just shouldn't access the instance after it has balanced
|
588 |
|
|
* out its refcount usage.
|
589 |
|
|
*
|
590 |
|
|
* Defined in: drivers/scsi/hosts.c
|
591 |
|
|
**/
|
592 |
|
|
void scsi_host_put(struct Scsi_Host *shost)
|
593 |
|
|
|
594 |
|
|
|
595 |
|
|
/**
|
596 |
|
|
* scsi_partsize - parse partition table into cylinders, heads + sectors
|
597 |
|
|
* @buf: pointer to partition table
|
598 |
|
|
* @capacity: size of (total) disk in 512 byte sectors
|
599 |
|
|
* @cyls: outputs number of cylinders calculated via this pointer
|
600 |
|
|
* @hds: outputs number of heads calculated via this pointer
|
601 |
|
|
* @secs: outputs number of sectors calculated via this pointer
|
602 |
|
|
*
|
603 |
|
|
* Returns 0 on success, -1 on failure
|
604 |
|
|
*
|
605 |
|
|
* Might block: no
|
606 |
|
|
*
|
607 |
|
|
* Notes: Caller owns memory returned (free with kfree() )
|
608 |
|
|
*
|
609 |
|
|
* Defined in: drivers/scsi/scsicam.c
|
610 |
|
|
**/
|
611 |
|
|
int scsi_partsize(unsigned char *buf, unsigned long capacity,
|
612 |
|
|
unsigned int *cyls, unsigned int *hds, unsigned int *secs)
|
613 |
|
|
|
614 |
|
|
|
615 |
|
|
/**
|
616 |
|
|
* scsi_register - create and register a scsi host adapter instance.
|
617 |
|
|
* @sht: pointer to scsi host template
|
618 |
|
|
* @privsize: extra bytes to allocate in hostdata array (which is the
|
619 |
|
|
* last member of the returned Scsi_Host instance)
|
620 |
|
|
*
|
621 |
|
|
* Returns pointer to new Scsi_Host instance or NULL on failure
|
622 |
|
|
*
|
623 |
|
|
* Might block: yes
|
624 |
|
|
*
|
625 |
|
|
* Notes: When this call returns to the LLD, the SCSI bus scan on
|
626 |
|
|
* this host has _not_ yet been done.
|
627 |
|
|
* The hostdata array (by default zero length) is a per host scratch
|
628 |
|
|
* area for the LLD.
|
629 |
|
|
*
|
630 |
|
|
* Defined in: drivers/scsi/hosts.c .
|
631 |
|
|
**/
|
632 |
|
|
struct Scsi_Host * scsi_register(struct scsi_host_template * sht,
|
633 |
|
|
int privsize)
|
634 |
|
|
|
635 |
|
|
|
636 |
|
|
/**
|
637 |
|
|
* scsi_remove_device - detach and remove a SCSI device
|
638 |
|
|
* @sdev: a pointer to a scsi device instance
|
639 |
|
|
*
|
640 |
|
|
* Returns value: 0 on success, -EINVAL if device not attached
|
641 |
|
|
*
|
642 |
|
|
* Might block: yes
|
643 |
|
|
*
|
644 |
|
|
* Notes: If an LLD becomes aware that a scsi device (lu) has
|
645 |
|
|
* been removed but its host is still present then it can request
|
646 |
|
|
* the removal of that scsi device. If successful this call will
|
647 |
|
|
* lead to the slave_destroy() callback being invoked. sdev is an
|
648 |
|
|
* invalid pointer after this call.
|
649 |
|
|
*
|
650 |
|
|
* Defined in: drivers/scsi/scsi_sysfs.c .
|
651 |
|
|
**/
|
652 |
|
|
int scsi_remove_device(struct scsi_device *sdev)
|
653 |
|
|
|
654 |
|
|
|
655 |
|
|
/**
|
656 |
|
|
* scsi_remove_host - detach and remove all SCSI devices owned by host
|
657 |
|
|
* @shost: a pointer to a scsi host instance
|
658 |
|
|
*
|
659 |
|
|
* Returns value: 0 on success, 1 on failure (e.g. LLD busy ??)
|
660 |
|
|
*
|
661 |
|
|
* Might block: yes
|
662 |
|
|
*
|
663 |
|
|
* Notes: Should only be invoked if the "hotplug initialization
|
664 |
|
|
* model" is being used. It should be called _prior_ to
|
665 |
|
|
* scsi_unregister().
|
666 |
|
|
*
|
667 |
|
|
* Defined in: drivers/scsi/hosts.c .
|
668 |
|
|
**/
|
669 |
|
|
int scsi_remove_host(struct Scsi_Host *shost)
|
670 |
|
|
|
671 |
|
|
|
672 |
|
|
/**
|
673 |
|
|
* scsi_report_bus_reset - report scsi _bus_ reset observed
|
674 |
|
|
* @shost: a pointer to a scsi host involved
|
675 |
|
|
* @channel: channel (within) host on which scsi bus reset occurred
|
676 |
|
|
*
|
677 |
|
|
* Returns nothing
|
678 |
|
|
*
|
679 |
|
|
* Might block: no
|
680 |
|
|
*
|
681 |
|
|
* Notes: This only needs to be called if the reset is one which
|
682 |
|
|
* originates from an unknown location. Resets originated by the
|
683 |
|
|
* mid level itself don't need to call this, but there should be
|
684 |
|
|
* no harm. The main purpose of this is to make sure that a
|
685 |
|
|
* CHECK_CONDITION is properly treated.
|
686 |
|
|
*
|
687 |
|
|
* Defined in: drivers/scsi/scsi_error.c .
|
688 |
|
|
**/
|
689 |
|
|
void scsi_report_bus_reset(struct Scsi_Host * shost, int channel)
|
690 |
|
|
|
691 |
|
|
|
692 |
|
|
/**
|
693 |
|
|
* scsi_scan_host - scan SCSI bus
|
694 |
|
|
* @shost: a pointer to a scsi host instance
|
695 |
|
|
*
|
696 |
|
|
* Might block: yes
|
697 |
|
|
*
|
698 |
|
|
* Notes: Should be called after scsi_add_host()
|
699 |
|
|
*
|
700 |
|
|
* Defined in: drivers/scsi/scsi_scan.c
|
701 |
|
|
**/
|
702 |
|
|
void scsi_scan_host(struct Scsi_Host *shost)
|
703 |
|
|
|
704 |
|
|
|
705 |
|
|
/**
|
706 |
|
|
* scsi_track_queue_full - track successive QUEUE_FULL events on given
|
707 |
|
|
* device to determine if and when there is a need
|
708 |
|
|
* to adjust the queue depth on the device.
|
709 |
|
|
* @sdev: pointer to SCSI device instance
|
710 |
|
|
* @depth: Current number of outstanding SCSI commands on this device,
|
711 |
|
|
* not counting the one returned as QUEUE_FULL.
|
712 |
|
|
*
|
713 |
|
|
* Returns 0 - no change needed
|
714 |
|
|
* >0 - adjust queue depth to this new depth
|
715 |
|
|
* -1 - drop back to untagged operation using host->cmd_per_lun
|
716 |
|
|
* as the untagged command depth
|
717 |
|
|
*
|
718 |
|
|
* Might block: no
|
719 |
|
|
*
|
720 |
|
|
* Notes: LLDs may call this at any time and we will do "The Right
|
721 |
|
|
* Thing"; interrupt context safe.
|
722 |
|
|
*
|
723 |
|
|
* Defined in: drivers/scsi/scsi.c .
|
724 |
|
|
**/
|
725 |
|
|
int scsi_track_queue_full(struct scsi_device *sdev, int depth)
|
726 |
|
|
|
727 |
|
|
|
728 |
|
|
/**
|
729 |
|
|
* scsi_unblock_requests - allow further commands to be queued to given host
|
730 |
|
|
*
|
731 |
|
|
* @shost: pointer to host to unblock commands on
|
732 |
|
|
*
|
733 |
|
|
* Returns nothing
|
734 |
|
|
*
|
735 |
|
|
* Might block: no
|
736 |
|
|
*
|
737 |
|
|
* Defined in: drivers/scsi/scsi_lib.c .
|
738 |
|
|
**/
|
739 |
|
|
void scsi_unblock_requests(struct Scsi_Host * shost)
|
740 |
|
|
|
741 |
|
|
|
742 |
|
|
/**
|
743 |
|
|
* scsi_unregister - unregister and free memory used by host instance
|
744 |
|
|
* @shp: pointer to scsi host instance to unregister.
|
745 |
|
|
*
|
746 |
|
|
* Returns nothing
|
747 |
|
|
*
|
748 |
|
|
* Might block: no
|
749 |
|
|
*
|
750 |
|
|
* Notes: Should not be invoked if the "hotplug initialization
|
751 |
|
|
* model" is being used. Called internally by exit_this_scsi_driver()
|
752 |
|
|
* in the "passive initialization model". Hence a LLD has no need to
|
753 |
|
|
* call this function directly.
|
754 |
|
|
*
|
755 |
|
|
* Defined in: drivers/scsi/hosts.c .
|
756 |
|
|
**/
|
757 |
|
|
void scsi_unregister(struct Scsi_Host * shp)
|
758 |
|
|
|
759 |
|
|
|
760 |
|
|
|
761 |
|
|
|
762 |
|
|
Interface Functions
|
763 |
|
|
===================
|
764 |
|
|
Interface functions are supplied (defined) by LLDs and their function
|
765 |
|
|
pointers are placed in an instance of struct scsi_host_template which
|
766 |
|
|
is passed to scsi_host_alloc() [or scsi_register() / init_this_scsi_driver()].
|
767 |
|
|
Some are mandatory. Interface functions should be declared static. The
|
768 |
|
|
accepted convention is that driver "xyz" will declare its slave_configure()
|
769 |
|
|
function as:
|
770 |
|
|
static int xyz_slave_configure(struct scsi_device * sdev);
|
771 |
|
|
and so forth for all interface functions listed below.
|
772 |
|
|
|
773 |
|
|
A pointer to this function should be placed in the 'slave_configure' member
|
774 |
|
|
of a "struct scsi_host_template" instance. A pointer to such an instance
|
775 |
|
|
should be passed to the mid level's scsi_host_alloc() [or scsi_register() /
|
776 |
|
|
init_this_scsi_driver()].
|
777 |
|
|
|
778 |
|
|
The interface functions are also described in the include/scsi/scsi_host.h
|
779 |
|
|
file immediately above their definition point in "struct scsi_host_template".
|
780 |
|
|
In some cases more detail is given in scsi_host.h than below.
|
781 |
|
|
|
782 |
|
|
The interface functions are listed below in alphabetical order.
|
783 |
|
|
|
784 |
|
|
Summary:
|
785 |
|
|
bios_param - fetch head, sector, cylinder info for a disk
|
786 |
|
|
detect - detects HBAs this driver wants to control
|
787 |
|
|
eh_timed_out - notify the host that a command timer expired
|
788 |
|
|
eh_abort_handler - abort given command
|
789 |
|
|
eh_bus_reset_handler - issue SCSI bus reset
|
790 |
|
|
eh_device_reset_handler - issue SCSI device reset
|
791 |
|
|
eh_host_reset_handler - reset host (host bus adapter)
|
792 |
|
|
info - supply information about given host
|
793 |
|
|
ioctl - driver can respond to ioctls
|
794 |
|
|
proc_info - supports /proc/scsi/{driver_name}/{host_no}
|
795 |
|
|
queuecommand - queue scsi command, invoke 'done' on completion
|
796 |
|
|
release - release all resources associated with given host
|
797 |
|
|
slave_alloc - prior to any commands being sent to a new device
|
798 |
|
|
slave_configure - driver fine tuning for given device after attach
|
799 |
|
|
slave_destroy - given device is about to be shut down
|
800 |
|
|
|
801 |
|
|
|
802 |
|
|
Details:
|
803 |
|
|
|
804 |
|
|
/**
|
805 |
|
|
* bios_param - fetch head, sector, cylinder info for a disk
|
806 |
|
|
* @sdev: pointer to scsi device context (defined in
|
807 |
|
|
* include/scsi/scsi_device.h)
|
808 |
|
|
* @bdev: pointer to block device context (defined in fs.h)
|
809 |
|
|
* @capacity: device size (in 512 byte sectors)
|
810 |
|
|
* @params: three element array to place output:
|
811 |
|
|
* params[0] number of heads (max 255)
|
812 |
|
|
* params[1] number of sectors (max 63)
|
813 |
|
|
* params[2] number of cylinders
|
814 |
|
|
*
|
815 |
|
|
* Return value is ignored
|
816 |
|
|
*
|
817 |
|
|
* Locks: none
|
818 |
|
|
*
|
819 |
|
|
* Calling context: process (sd)
|
820 |
|
|
*
|
821 |
|
|
* Notes: an arbitrary geometry (based on READ CAPACITY) is used
|
822 |
|
|
* if this function is not provided. The params array is
|
823 |
|
|
* pre-initialized with made up values just in case this function
|
824 |
|
|
* doesn't output anything.
|
825 |
|
|
*
|
826 |
|
|
* Optionally defined in: LLD
|
827 |
|
|
**/
|
828 |
|
|
int bios_param(struct scsi_device * sdev, struct block_device *bdev,
|
829 |
|
|
sector_t capacity, int params[3])
|
830 |
|
|
|
831 |
|
|
|
832 |
|
|
/**
|
833 |
|
|
* detect - detects HBAs this driver wants to control
|
834 |
|
|
* @shtp: host template for this driver.
|
835 |
|
|
*
|
836 |
|
|
* Returns number of hosts this driver wants to control. 0 means no
|
837 |
|
|
* suitable hosts found.
|
838 |
|
|
*
|
839 |
|
|
* Locks: none held
|
840 |
|
|
*
|
841 |
|
|
* Calling context: process [invoked from init_this_scsi_driver()]
|
842 |
|
|
*
|
843 |
|
|
* Notes: First function called from the SCSI mid level on this
|
844 |
|
|
* driver. Upper level drivers (e.g. sd) may not (yet) be present.
|
845 |
|
|
* For each host found, this method should call scsi_register()
|
846 |
|
|
* [see hosts.c].
|
847 |
|
|
*
|
848 |
|
|
* Defined in: LLD (required if "passive initialization mode" is used,
|
849 |
|
|
* not invoked in "hotplug initialization mode")
|
850 |
|
|
**/
|
851 |
|
|
int detect(struct scsi_host_template * shtp)
|
852 |
|
|
|
853 |
|
|
|
854 |
|
|
/**
|
855 |
|
|
* eh_timed_out - The timer for the command has just fired
|
856 |
|
|
* @scp: identifies command timing out
|
857 |
|
|
*
|
858 |
|
|
* Returns:
|
859 |
|
|
*
|
860 |
|
|
* EH_HANDLED: I fixed the error, please complete the command
|
861 |
|
|
* EH_RESET_TIMER: I need more time, reset the timer and
|
862 |
|
|
* begin counting again
|
863 |
|
|
* EH_NOT_HANDLED Begin normal error recovery
|
864 |
|
|
*
|
865 |
|
|
*
|
866 |
|
|
* Locks: None held
|
867 |
|
|
*
|
868 |
|
|
* Calling context: interrupt
|
869 |
|
|
*
|
870 |
|
|
* Notes: This is to give the LLD an opportunity to do local recovery.
|
871 |
|
|
* This recovery is limited to determining if the outstanding command
|
872 |
|
|
* will ever complete. You may not abort and restart the command from
|
873 |
|
|
* this callback.
|
874 |
|
|
*
|
875 |
|
|
* Optionally defined in: LLD
|
876 |
|
|
**/
|
877 |
|
|
int eh_timed_out(struct scsi_cmnd * scp)
|
878 |
|
|
|
879 |
|
|
|
880 |
|
|
/**
|
881 |
|
|
* eh_abort_handler - abort command associated with scp
|
882 |
|
|
* @scp: identifies command to be aborted
|
883 |
|
|
*
|
884 |
|
|
* Returns SUCCESS if command aborted else FAILED
|
885 |
|
|
*
|
886 |
|
|
* Locks: None held
|
887 |
|
|
*
|
888 |
|
|
* Calling context: kernel thread
|
889 |
|
|
*
|
890 |
|
|
* Notes: Invoked from scsi_eh thread. No other commands will be
|
891 |
|
|
* queued on current host during eh.
|
892 |
|
|
*
|
893 |
|
|
* Optionally defined in: LLD
|
894 |
|
|
**/
|
895 |
|
|
int eh_abort_handler(struct scsi_cmnd * scp)
|
896 |
|
|
|
897 |
|
|
|
898 |
|
|
/**
|
899 |
|
|
* eh_bus_reset_handler - issue SCSI bus reset
|
900 |
|
|
* @scp: SCSI bus that contains this device should be reset
|
901 |
|
|
*
|
902 |
|
|
* Returns SUCCESS if command aborted else FAILED
|
903 |
|
|
*
|
904 |
|
|
* Locks: None held
|
905 |
|
|
*
|
906 |
|
|
* Calling context: kernel thread
|
907 |
|
|
*
|
908 |
|
|
* Notes: Invoked from scsi_eh thread. No other commands will be
|
909 |
|
|
* queued on current host during eh.
|
910 |
|
|
*
|
911 |
|
|
* Optionally defined in: LLD
|
912 |
|
|
**/
|
913 |
|
|
int eh_bus_reset_handler(struct scsi_cmnd * scp)
|
914 |
|
|
|
915 |
|
|
|
916 |
|
|
/**
|
917 |
|
|
* eh_device_reset_handler - issue SCSI device reset
|
918 |
|
|
* @scp: identifies SCSI device to be reset
|
919 |
|
|
*
|
920 |
|
|
* Returns SUCCESS if command aborted else FAILED
|
921 |
|
|
*
|
922 |
|
|
* Locks: None held
|
923 |
|
|
*
|
924 |
|
|
* Calling context: kernel thread
|
925 |
|
|
*
|
926 |
|
|
* Notes: Invoked from scsi_eh thread. No other commands will be
|
927 |
|
|
* queued on current host during eh.
|
928 |
|
|
*
|
929 |
|
|
* Optionally defined in: LLD
|
930 |
|
|
**/
|
931 |
|
|
int eh_device_reset_handler(struct scsi_cmnd * scp)
|
932 |
|
|
|
933 |
|
|
|
934 |
|
|
/**
|
935 |
|
|
* eh_host_reset_handler - reset host (host bus adapter)
|
936 |
|
|
* @scp: SCSI host that contains this device should be reset
|
937 |
|
|
*
|
938 |
|
|
* Returns SUCCESS if command aborted else FAILED
|
939 |
|
|
*
|
940 |
|
|
* Locks: None held
|
941 |
|
|
*
|
942 |
|
|
* Calling context: kernel thread
|
943 |
|
|
*
|
944 |
|
|
* Notes: Invoked from scsi_eh thread. No other commands will be
|
945 |
|
|
* queued on current host during eh.
|
946 |
|
|
* With the default eh_strategy in place, if none of the _abort_,
|
947 |
|
|
* _device_reset_, _bus_reset_ or this eh handler function are
|
948 |
|
|
* defined (or they all return FAILED) then the device in question
|
949 |
|
|
* will be set offline whenever eh is invoked.
|
950 |
|
|
*
|
951 |
|
|
* Optionally defined in: LLD
|
952 |
|
|
**/
|
953 |
|
|
int eh_host_reset_handler(struct scsi_cmnd * scp)
|
954 |
|
|
|
955 |
|
|
|
956 |
|
|
/**
|
957 |
|
|
* info - supply information about given host: driver name plus data
|
958 |
|
|
* to distinguish given host
|
959 |
|
|
* @shp: host to supply information about
|
960 |
|
|
*
|
961 |
|
|
* Return ASCII null terminated string. [This driver is assumed to
|
962 |
|
|
* manage the memory pointed to and maintain it, typically for the
|
963 |
|
|
* lifetime of this host.]
|
964 |
|
|
*
|
965 |
|
|
* Locks: none
|
966 |
|
|
*
|
967 |
|
|
* Calling context: process
|
968 |
|
|
*
|
969 |
|
|
* Notes: Often supplies PCI or ISA information such as IO addresses
|
970 |
|
|
* and interrupt numbers. If not supplied struct Scsi_Host::name used
|
971 |
|
|
* instead. It is assumed the returned information fits on one line
|
972 |
|
|
* (i.e. does not included embedded newlines).
|
973 |
|
|
* The SCSI_IOCTL_PROBE_HOST ioctl yields the string returned by this
|
974 |
|
|
* function (or struct Scsi_Host::name if this function is not
|
975 |
|
|
* available).
|
976 |
|
|
* In a similar manner, init_this_scsi_driver() outputs to the console
|
977 |
|
|
* each host's "info" (or name) for the driver it is registering.
|
978 |
|
|
* Also if proc_info() is not supplied, the output of this function
|
979 |
|
|
* is used instead.
|
980 |
|
|
*
|
981 |
|
|
* Optionally defined in: LLD
|
982 |
|
|
**/
|
983 |
|
|
const char * info(struct Scsi_Host * shp)
|
984 |
|
|
|
985 |
|
|
|
986 |
|
|
/**
|
987 |
|
|
* ioctl - driver can respond to ioctls
|
988 |
|
|
* @sdp: device that ioctl was issued for
|
989 |
|
|
* @cmd: ioctl number
|
990 |
|
|
* @arg: pointer to read or write data from. Since it points to
|
991 |
|
|
* user space, should use appropriate kernel functions
|
992 |
|
|
* (e.g. copy_from_user() ). In the Unix style this argument
|
993 |
|
|
* can also be viewed as an unsigned long.
|
994 |
|
|
*
|
995 |
|
|
* Returns negative "errno" value when there is a problem. 0 or a
|
996 |
|
|
* positive value indicates success and is returned to the user space.
|
997 |
|
|
*
|
998 |
|
|
* Locks: none
|
999 |
|
|
*
|
1000 |
|
|
* Calling context: process
|
1001 |
|
|
*
|
1002 |
|
|
* Notes: The SCSI subsystem uses a "trickle down" ioctl model.
|
1003 |
|
|
* The user issues an ioctl() against an upper level driver
|
1004 |
|
|
* (e.g. /dev/sdc) and if the upper level driver doesn't recognize
|
1005 |
|
|
* the 'cmd' then it is passed to the SCSI mid level. If the SCSI
|
1006 |
|
|
* mid level does not recognize it, then the LLD that controls
|
1007 |
|
|
* the device receives the ioctl. According to recent Unix standards
|
1008 |
|
|
* unsupported ioctl() 'cmd' numbers should return -ENOTTY.
|
1009 |
|
|
*
|
1010 |
|
|
* Optionally defined in: LLD
|
1011 |
|
|
**/
|
1012 |
|
|
int ioctl(struct scsi_device *sdp, int cmd, void *arg)
|
1013 |
|
|
|
1014 |
|
|
|
1015 |
|
|
/**
|
1016 |
|
|
* proc_info - supports /proc/scsi/{driver_name}/{host_no}
|
1017 |
|
|
* @buffer: anchor point to output to (0==writeto1_read0) or fetch from
|
1018 |
|
|
* (1==writeto1_read0).
|
1019 |
|
|
* @start: where "interesting" data is written to. Ignored when
|
1020 |
|
|
* 1==writeto1_read0.
|
1021 |
|
|
* @offset: offset within buffer 0==writeto1_read0 is actually
|
1022 |
|
|
* interested in. Ignored when 1==writeto1_read0 .
|
1023 |
|
|
* @length: maximum (or actual) extent of buffer
|
1024 |
|
|
* @host_no: host number of interest (struct Scsi_Host::host_no)
|
1025 |
|
|
* @writeto1_read0: 1 -> data coming from user space towards driver
|
1026 |
|
|
* (e.g. "echo some_string > /proc/scsi/xyz/2")
|
1027 |
|
|
* 0 -> user what data from this driver
|
1028 |
|
|
* (e.g. "cat /proc/scsi/xyz/2")
|
1029 |
|
|
*
|
1030 |
|
|
* Returns length when 1==writeto1_read0. Otherwise number of chars
|
1031 |
|
|
* output to buffer past offset.
|
1032 |
|
|
*
|
1033 |
|
|
* Locks: none held
|
1034 |
|
|
*
|
1035 |
|
|
* Calling context: process
|
1036 |
|
|
*
|
1037 |
|
|
* Notes: Driven from scsi_proc.c which interfaces to proc_fs. proc_fs
|
1038 |
|
|
* support can now be configured out of the scsi subsystem.
|
1039 |
|
|
*
|
1040 |
|
|
* Optionally defined in: LLD
|
1041 |
|
|
**/
|
1042 |
|
|
int proc_info(char * buffer, char ** start, off_t offset,
|
1043 |
|
|
int length, int host_no, int writeto1_read0)
|
1044 |
|
|
|
1045 |
|
|
|
1046 |
|
|
/**
|
1047 |
|
|
* queuecommand - queue scsi command, invoke 'done' on completion
|
1048 |
|
|
* @scp: pointer to scsi command object
|
1049 |
|
|
* @done: function pointer to be invoked on completion
|
1050 |
|
|
*
|
1051 |
|
|
* Returns 0 on success.
|
1052 |
|
|
*
|
1053 |
|
|
* If there's a failure, return either:
|
1054 |
|
|
*
|
1055 |
|
|
* SCSI_MLQUEUE_DEVICE_BUSY if the device queue is full, or
|
1056 |
|
|
* SCSI_MLQUEUE_HOST_BUSY if the entire host queue is full
|
1057 |
|
|
*
|
1058 |
|
|
* On both of these returns, the mid-layer will requeue the I/O
|
1059 |
|
|
*
|
1060 |
|
|
* - if the return is SCSI_MLQUEUE_DEVICE_BUSY, only that particular
|
1061 |
|
|
* device will be paused, and it will be unpaused when a command to
|
1062 |
|
|
* the device returns (or after a brief delay if there are no more
|
1063 |
|
|
* outstanding commands to it). Commands to other devices continue
|
1064 |
|
|
* to be processed normally.
|
1065 |
|
|
*
|
1066 |
|
|
* - if the return is SCSI_MLQUEUE_HOST_BUSY, all I/O to the host
|
1067 |
|
|
* is paused and will be unpaused when any command returns from
|
1068 |
|
|
* the host (or after a brief delay if there are no outstanding
|
1069 |
|
|
* commands to the host).
|
1070 |
|
|
*
|
1071 |
|
|
* For compatibility with earlier versions of queuecommand, any
|
1072 |
|
|
* other return value is treated the same as
|
1073 |
|
|
* SCSI_MLQUEUE_HOST_BUSY.
|
1074 |
|
|
*
|
1075 |
|
|
* Other types of errors that are detected immediately may be
|
1076 |
|
|
* flagged by setting scp->result to an appropriate value,
|
1077 |
|
|
* invoking the 'done' callback, and then returning 0 from this
|
1078 |
|
|
* function. If the command is not performed immediately (and the
|
1079 |
|
|
* LLD is starting (or will start) the given command) then this
|
1080 |
|
|
* function should place 0 in scp->result and return 0.
|
1081 |
|
|
*
|
1082 |
|
|
* Command ownership. If the driver returns zero, it owns the
|
1083 |
|
|
* command and must take responsibility for ensuring the 'done'
|
1084 |
|
|
* callback is executed. Note: the driver may call done before
|
1085 |
|
|
* returning zero, but after it has called done, it may not
|
1086 |
|
|
* return any value other than zero. If the driver makes a
|
1087 |
|
|
* non-zero return, it must not execute the command's done
|
1088 |
|
|
* callback at any time.
|
1089 |
|
|
*
|
1090 |
|
|
* Locks: struct Scsi_Host::host_lock held on entry (with "irqsave")
|
1091 |
|
|
* and is expected to be held on return.
|
1092 |
|
|
*
|
1093 |
|
|
* Calling context: in interrupt (soft irq) or process context
|
1094 |
|
|
*
|
1095 |
|
|
* Notes: This function should be relatively fast. Normally it will
|
1096 |
|
|
* not wait for IO to complete. Hence the 'done' callback is invoked
|
1097 |
|
|
* (often directly from an interrupt service routine) some time after
|
1098 |
|
|
* this function has returned. In some cases (e.g. pseudo adapter
|
1099 |
|
|
* drivers that manufacture the response to a SCSI INQUIRY)
|
1100 |
|
|
* the 'done' callback may be invoked before this function returns.
|
1101 |
|
|
* If the 'done' callback is not invoked within a certain period
|
1102 |
|
|
* the SCSI mid level will commence error processing.
|
1103 |
|
|
* If a status of CHECK CONDITION is placed in "result" when the
|
1104 |
|
|
* 'done' callback is invoked, then the LLD driver should
|
1105 |
|
|
* perform autosense and fill in the struct scsi_cmnd::sense_buffer
|
1106 |
|
|
* array. The scsi_cmnd::sense_buffer array is zeroed prior to
|
1107 |
|
|
* the mid level queuing a command to an LLD.
|
1108 |
|
|
*
|
1109 |
|
|
* Defined in: LLD
|
1110 |
|
|
**/
|
1111 |
|
|
int queuecommand(struct scsi_cmnd * scp,
|
1112 |
|
|
void (*done)(struct scsi_cmnd *))
|
1113 |
|
|
|
1114 |
|
|
|
1115 |
|
|
/**
|
1116 |
|
|
* release - release all resources associated with given host
|
1117 |
|
|
* @shp: host to be released.
|
1118 |
|
|
*
|
1119 |
|
|
* Return value ignored (could soon be a function returning void).
|
1120 |
|
|
*
|
1121 |
|
|
* Locks: none held
|
1122 |
|
|
*
|
1123 |
|
|
* Calling context: process
|
1124 |
|
|
*
|
1125 |
|
|
* Notes: Invoked from scsi_module.c's exit_this_scsi_driver().
|
1126 |
|
|
* LLD's implementation of this function should call
|
1127 |
|
|
* scsi_unregister(shp) prior to returning.
|
1128 |
|
|
* Only needed for old-style host templates.
|
1129 |
|
|
*
|
1130 |
|
|
* Defined in: LLD (required in "passive initialization model",
|
1131 |
|
|
* should not be defined in hotplug model)
|
1132 |
|
|
**/
|
1133 |
|
|
int release(struct Scsi_Host * shp)
|
1134 |
|
|
|
1135 |
|
|
|
1136 |
|
|
/**
|
1137 |
|
|
* slave_alloc - prior to any commands being sent to a new device
|
1138 |
|
|
* (i.e. just prior to scan) this call is made
|
1139 |
|
|
* @sdp: pointer to new device (about to be scanned)
|
1140 |
|
|
*
|
1141 |
|
|
* Returns 0 if ok. Any other return is assumed to be an error and
|
1142 |
|
|
* the device is ignored.
|
1143 |
|
|
*
|
1144 |
|
|
* Locks: none
|
1145 |
|
|
*
|
1146 |
|
|
* Calling context: process
|
1147 |
|
|
*
|
1148 |
|
|
* Notes: Allows the driver to allocate any resources for a device
|
1149 |
|
|
* prior to its initial scan. The corresponding scsi device may not
|
1150 |
|
|
* exist but the mid level is just about to scan for it (i.e. send
|
1151 |
|
|
* and INQUIRY command plus ...). If a device is found then
|
1152 |
|
|
* slave_configure() will be called while if a device is not found
|
1153 |
|
|
* slave_destroy() is called.
|
1154 |
|
|
* For more details see the include/scsi/scsi_host.h file.
|
1155 |
|
|
*
|
1156 |
|
|
* Optionally defined in: LLD
|
1157 |
|
|
**/
|
1158 |
|
|
int slave_alloc(struct scsi_device *sdp)
|
1159 |
|
|
|
1160 |
|
|
|
1161 |
|
|
/**
|
1162 |
|
|
* slave_configure - driver fine tuning for given device just after it
|
1163 |
|
|
* has been first scanned (i.e. it responded to an
|
1164 |
|
|
* INQUIRY)
|
1165 |
|
|
* @sdp: device that has just been attached
|
1166 |
|
|
*
|
1167 |
|
|
* Returns 0 if ok. Any other return is assumed to be an error and
|
1168 |
|
|
* the device is taken offline. [offline devices will _not_ have
|
1169 |
|
|
* slave_destroy() called on them so clean up resources.]
|
1170 |
|
|
*
|
1171 |
|
|
* Locks: none
|
1172 |
|
|
*
|
1173 |
|
|
* Calling context: process
|
1174 |
|
|
*
|
1175 |
|
|
* Notes: Allows the driver to inspect the response to the initial
|
1176 |
|
|
* INQUIRY done by the scanning code and take appropriate action.
|
1177 |
|
|
* For more details see the include/scsi/scsi_host.h file.
|
1178 |
|
|
*
|
1179 |
|
|
* Optionally defined in: LLD
|
1180 |
|
|
**/
|
1181 |
|
|
int slave_configure(struct scsi_device *sdp)
|
1182 |
|
|
|
1183 |
|
|
|
1184 |
|
|
/**
|
1185 |
|
|
* slave_destroy - given device is about to be shut down. All
|
1186 |
|
|
* activity has ceased on this device.
|
1187 |
|
|
* @sdp: device that is about to be shut down
|
1188 |
|
|
*
|
1189 |
|
|
* Returns nothing
|
1190 |
|
|
*
|
1191 |
|
|
* Locks: none
|
1192 |
|
|
*
|
1193 |
|
|
* Calling context: process
|
1194 |
|
|
*
|
1195 |
|
|
* Notes: Mid level structures for given device are still in place
|
1196 |
|
|
* but are about to be torn down. Any per device resources allocated
|
1197 |
|
|
* by this driver for given device should be freed now. No further
|
1198 |
|
|
* commands will be sent for this sdp instance. [However the device
|
1199 |
|
|
* could be re-attached in the future in which case a new instance
|
1200 |
|
|
* of struct scsi_device would be supplied by future slave_alloc()
|
1201 |
|
|
* and slave_configure() calls.]
|
1202 |
|
|
*
|
1203 |
|
|
* Optionally defined in: LLD
|
1204 |
|
|
**/
|
1205 |
|
|
void slave_destroy(struct scsi_device *sdp)
|
1206 |
|
|
|
1207 |
|
|
|
1208 |
|
|
|
1209 |
|
|
Data Structures
|
1210 |
|
|
===============
|
1211 |
|
|
struct scsi_host_template
|
1212 |
|
|
-------------------------
|
1213 |
|
|
There is one "struct scsi_host_template" instance per LLD ***. It is
|
1214 |
|
|
typically initialized as a file scope static in a driver's header file. That
|
1215 |
|
|
way members that are not explicitly initialized will be set to 0 or NULL.
|
1216 |
|
|
Member of interest:
|
1217 |
|
|
name - name of driver (may contain spaces, please limit to
|
1218 |
|
|
less than 80 characters)
|
1219 |
|
|
proc_name - name used in "/proc/scsi//" and
|
1220 |
|
|
by sysfs in one of its "drivers" directories. Hence
|
1221 |
|
|
"proc_name" should only contain characters acceptable
|
1222 |
|
|
to a Unix file name.
|
1223 |
|
|
(*queuecommand)() - primary callback that the mid level uses to inject
|
1224 |
|
|
SCSI commands into an LLD.
|
1225 |
|
|
The structure is defined and commented in include/scsi/scsi_host.h
|
1226 |
|
|
|
1227 |
|
|
*** In extreme situations a single driver may have several instances
|
1228 |
|
|
if it controls several different classes of hardware (e.g. an LLD
|
1229 |
|
|
that handles both ISA and PCI cards and has a separate instance of
|
1230 |
|
|
struct scsi_host_template for each class).
|
1231 |
|
|
|
1232 |
|
|
struct Scsi_Host
|
1233 |
|
|
----------------
|
1234 |
|
|
There is one struct Scsi_Host instance per host (HBA) that an LLD
|
1235 |
|
|
controls. The struct Scsi_Host structure has many members in common
|
1236 |
|
|
with "struct scsi_host_template". When a new struct Scsi_Host instance
|
1237 |
|
|
is created (in scsi_host_alloc() in hosts.c) those common members are
|
1238 |
|
|
initialized from the driver's struct scsi_host_template instance. Members
|
1239 |
|
|
of interest:
|
1240 |
|
|
host_no - system wide unique number that is used for identifying
|
1241 |
|
|
this host. Issued in ascending order from 0.
|
1242 |
|
|
can_queue - must be greater than 0; do not send more than can_queue
|
1243 |
|
|
commands to the adapter.
|
1244 |
|
|
this_id - scsi id of host (scsi initiator) or -1 if not known
|
1245 |
|
|
sg_tablesize - maximum scatter gather elements allowed by host.
|
1246 |
|
|
|
1247 |
|
|
max_sectors - maximum number of sectors (usually 512 bytes) allowed
|
1248 |
|
|
in a single SCSI command. The default value of 0 leads
|
1249 |
|
|
to a setting of SCSI_DEFAULT_MAX_SECTORS (defined in
|
1250 |
|
|
scsi_host.h) which is currently set to 1024. So for a
|
1251 |
|
|
disk the maximum transfer size is 512 KB when max_sectors
|
1252 |
|
|
is not defined. Note that this size may not be sufficient
|
1253 |
|
|
for disk firmware uploads.
|
1254 |
|
|
cmd_per_lun - maximum number of commands that can be queued on devices
|
1255 |
|
|
controlled by the host. Overridden by LLD calls to
|
1256 |
|
|
scsi_adjust_queue_depth().
|
1257 |
|
|
unchecked_isa_dma - 1=>only use bottom 16 MB of ram (ISA DMA addressing
|
1258 |
|
|
restriction), 0=>can use full 32 bit (or better) DMA
|
1259 |
|
|
address space
|
1260 |
|
|
use_clustering - 1=>SCSI commands in mid level's queue can be merged,
|
1261 |
|
|
0=>disallow SCSI command merging
|
1262 |
|
|
hostt - pointer to driver's struct scsi_host_template from which
|
1263 |
|
|
this struct Scsi_Host instance was spawned
|
1264 |
|
|
hostt->proc_name - name of LLD. This is the driver name that sysfs uses
|
1265 |
|
|
transportt - pointer to driver's struct scsi_transport_template instance
|
1266 |
|
|
(if any). FC and SPI transports currently supported.
|
1267 |
|
|
sh_list - a double linked list of pointers to all struct Scsi_Host
|
1268 |
|
|
instances (currently ordered by ascending host_no)
|
1269 |
|
|
my_devices - a double linked list of pointers to struct scsi_device
|
1270 |
|
|
instances that belong to this host.
|
1271 |
|
|
hostdata[0] - area reserved for LLD at end of struct Scsi_Host. Size
|
1272 |
|
|
is set by the second argument (named 'xtr_bytes') to
|
1273 |
|
|
scsi_host_alloc() or scsi_register().
|
1274 |
|
|
|
1275 |
|
|
The scsi_host structure is defined in include/scsi/scsi_host.h
|
1276 |
|
|
|
1277 |
|
|
struct scsi_device
|
1278 |
|
|
------------------
|
1279 |
|
|
Generally, there is one instance of this structure for each SCSI logical unit
|
1280 |
|
|
on a host. Scsi devices connected to a host are uniquely identified by a
|
1281 |
|
|
channel number, target id and logical unit number (lun).
|
1282 |
|
|
The structure is defined in include/scsi/scsi_device.h
|
1283 |
|
|
|
1284 |
|
|
struct scsi_cmnd
|
1285 |
|
|
----------------
|
1286 |
|
|
Instances of this structure convey SCSI commands to the LLD and responses
|
1287 |
|
|
back to the mid level. The SCSI mid level will ensure that no more SCSI
|
1288 |
|
|
commands become queued against the LLD than are indicated by
|
1289 |
|
|
scsi_adjust_queue_depth() (or struct Scsi_Host::cmd_per_lun). There will
|
1290 |
|
|
be at least one instance of struct scsi_cmnd available for each SCSI device.
|
1291 |
|
|
Members of interest:
|
1292 |
|
|
cmnd - array containing SCSI command
|
1293 |
|
|
cmnd_len - length (in bytes) of SCSI command
|
1294 |
|
|
sc_data_direction - direction of data transfer in data phase. See
|
1295 |
|
|
"enum dma_data_direction" in include/linux/dma-mapping.h
|
1296 |
|
|
request_bufflen - number of data bytes to transfer (0 if no data phase)
|
1297 |
|
|
use_sg - ==0 -> no scatter gather list, hence transfer data
|
1298 |
|
|
to/from request_buffer
|
1299 |
|
|
- >0 -> scatter gather list (actually an array) in
|
1300 |
|
|
request_buffer with use_sg elements
|
1301 |
|
|
request_buffer - either contains data buffer or scatter gather list
|
1302 |
|
|
depending on the setting of use_sg. Scatter gather
|
1303 |
|
|
elements are defined by 'struct scatterlist' found
|
1304 |
|
|
in include/asm/scatterlist.h .
|
1305 |
|
|
done - function pointer that should be invoked by LLD when the
|
1306 |
|
|
SCSI command is completed (successfully or otherwise).
|
1307 |
|
|
Should only be called by an LLD if the LLD has accepted
|
1308 |
|
|
the command (i.e. queuecommand() returned or will return
|
1309 |
|
|
0). The LLD may invoke 'done' prior to queuecommand()
|
1310 |
|
|
finishing.
|
1311 |
|
|
result - should be set by LLD prior to calling 'done'. A value
|
1312 |
|
|
of 0 implies a successfully completed command (and all
|
1313 |
|
|
data (if any) has been transferred to or from the SCSI
|
1314 |
|
|
target device). 'result' is a 32 bit unsigned integer that
|
1315 |
|
|
can be viewed as 4 related bytes. The SCSI status value is
|
1316 |
|
|
in the LSB. See include/scsi/scsi.h status_byte(),
|
1317 |
|
|
msg_byte(), host_byte() and driver_byte() macros and
|
1318 |
|
|
related constants.
|
1319 |
|
|
sense_buffer - an array (maximum size: SCSI_SENSE_BUFFERSIZE bytes) that
|
1320 |
|
|
should be written when the SCSI status (LSB of 'result')
|
1321 |
|
|
is set to CHECK_CONDITION (2). When CHECK_CONDITION is
|
1322 |
|
|
set, if the top nibble of sense_buffer[0] has the value 7
|
1323 |
|
|
then the mid level will assume the sense_buffer array
|
1324 |
|
|
contains a valid SCSI sense buffer; otherwise the mid
|
1325 |
|
|
level will issue a REQUEST_SENSE SCSI command to
|
1326 |
|
|
retrieve the sense buffer. The latter strategy is error
|
1327 |
|
|
prone in the presence of command queuing so the LLD should
|
1328 |
|
|
always "auto-sense".
|
1329 |
|
|
device - pointer to scsi_device object that this command is
|
1330 |
|
|
associated with.
|
1331 |
|
|
resid - an LLD should set this signed integer to the requested
|
1332 |
|
|
transfer length (i.e. 'request_bufflen') less the number
|
1333 |
|
|
of bytes that are actually transferred. 'resid' is
|
1334 |
|
|
preset to 0 so an LLD can ignore it if it cannot detect
|
1335 |
|
|
underruns (overruns should be rare). If possible an LLD
|
1336 |
|
|
should set 'resid' prior to invoking 'done'. The most
|
1337 |
|
|
interesting case is data transfers from a SCSI target
|
1338 |
|
|
device device (i.e. READs) that underrun.
|
1339 |
|
|
underflow - LLD should place (DID_ERROR << 16) in 'result' if
|
1340 |
|
|
actual number of bytes transferred is less than this
|
1341 |
|
|
figure. Not many LLDs implement this check and some that
|
1342 |
|
|
do just output an error message to the log rather than
|
1343 |
|
|
report a DID_ERROR. Better for an LLD to implement
|
1344 |
|
|
'resid'.
|
1345 |
|
|
|
1346 |
|
|
The scsi_cmnd structure is defined in include/scsi/scsi_cmnd.h
|
1347 |
|
|
|
1348 |
|
|
|
1349 |
|
|
Locks
|
1350 |
|
|
=====
|
1351 |
|
|
Each struct Scsi_Host instance has a spin_lock called struct
|
1352 |
|
|
Scsi_Host::default_lock which is initialized in scsi_host_alloc() [found in
|
1353 |
|
|
hosts.c]. Within the same function the struct Scsi_Host::host_lock pointer
|
1354 |
|
|
is initialized to point at default_lock. Thereafter lock and unlock
|
1355 |
|
|
operations performed by the mid level use the struct Scsi_Host::host_lock
|
1356 |
|
|
pointer. Previously drivers could override the host_lock pointer but
|
1357 |
|
|
this is not allowed anymore.
|
1358 |
|
|
|
1359 |
|
|
|
1360 |
|
|
Autosense
|
1361 |
|
|
=========
|
1362 |
|
|
Autosense (or auto-sense) is defined in the SAM-2 document as "the
|
1363 |
|
|
automatic return of sense data to the application client coincident
|
1364 |
|
|
with the completion of a SCSI command" when a status of CHECK CONDITION
|
1365 |
|
|
occurs. LLDs should perform autosense. This should be done when the LLD
|
1366 |
|
|
detects a CHECK CONDITION status by either:
|
1367 |
|
|
a) instructing the SCSI protocol (e.g. SCSI Parallel Interface (SPI))
|
1368 |
|
|
to perform an extra data in phase on such responses
|
1369 |
|
|
b) or, the LLD issuing a REQUEST SENSE command itself
|
1370 |
|
|
|
1371 |
|
|
Either way, when a status of CHECK CONDITION is detected, the mid level
|
1372 |
|
|
decides whether the LLD has performed autosense by checking struct
|
1373 |
|
|
scsi_cmnd::sense_buffer[0] . If this byte has an upper nibble of 7 (or 0xf)
|
1374 |
|
|
then autosense is assumed to have taken place. If it has another value (and
|
1375 |
|
|
this byte is initialized to 0 before each command) then the mid level will
|
1376 |
|
|
issue a REQUEST SENSE command.
|
1377 |
|
|
|
1378 |
|
|
In the presence of queued commands the "nexus" that maintains sense
|
1379 |
|
|
buffer data from the command that failed until a following REQUEST SENSE
|
1380 |
|
|
may get out of synchronization. This is why it is best for the LLD
|
1381 |
|
|
to perform autosense.
|
1382 |
|
|
|
1383 |
|
|
|
1384 |
|
|
Changes since lk 2.4 series
|
1385 |
|
|
===========================
|
1386 |
|
|
io_request_lock has been replaced by several finer grained locks. The lock
|
1387 |
|
|
relevant to LLDs is struct Scsi_Host::host_lock and there is
|
1388 |
|
|
one per SCSI host.
|
1389 |
|
|
|
1390 |
|
|
The older error handling mechanism has been removed. This means the
|
1391 |
|
|
LLD interface functions abort() and reset() have been removed.
|
1392 |
|
|
The struct scsi_host_template::use_new_eh_code flag has been removed.
|
1393 |
|
|
|
1394 |
|
|
In the 2.4 series the SCSI subsystem configuration descriptions were
|
1395 |
|
|
aggregated with the configuration descriptions from all other Linux
|
1396 |
|
|
subsystems in the Documentation/Configure.help file. In the 2.6 series,
|
1397 |
|
|
the SCSI subsystem now has its own (much smaller) drivers/scsi/Kconfig
|
1398 |
|
|
file that contains both configuration and help information.
|
1399 |
|
|
|
1400 |
|
|
struct SHT has been renamed to struct scsi_host_template.
|
1401 |
|
|
|
1402 |
|
|
Addition of the "hotplug initialization model" and many extra functions
|
1403 |
|
|
to support it.
|
1404 |
|
|
|
1405 |
|
|
|
1406 |
|
|
Credits
|
1407 |
|
|
=======
|
1408 |
|
|
The following people have contributed to this document:
|
1409 |
|
|
Mike Anderson
|
1410 |
|
|
James Bottomley
|
1411 |
|
|
Patrick Mansfield
|
1412 |
|
|
Christoph Hellwig
|
1413 |
|
|
Doug Ledford
|
1414 |
|
|
Andries Brouwer
|
1415 |
|
|
Randy Dunlap
|
1416 |
|
|
Alan Stern
|
1417 |
|
|
|
1418 |
|
|
|
1419 |
|
|
Douglas Gilbert
|
1420 |
|
|
dgilbert at interlog dot com
|
1421 |
|
|
21st September 2004
|