Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | 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() --> | |
dc25fcfb MW |
153 | scsi_add_host() ----> |
154 | scsi_scan_host() -------+ | |
1da177e4 LT |
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 | |
dc25fcfb | 200 | HBA is added, the scsi_scan_host() function causes a scan for SCSI devices |
1da177e4 LT |
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: | |
d0be4a7d | 350 | "typedef struct scsi_cmnd Scsi_Cmnd;" |
1da177e4 LT |
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 | |
dc25fcfb | 376 | scsi_add_host - perform sysfs registration and set up transport class |
1da177e4 | 377 | scsi_adjust_queue_depth - change the queue depth on a SCSI device |
1da177e4 LT |
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 | |
1da177e4 LT |
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 | |
dc25fcfb | 389 | scsi_scan_host - scan SCSI bus |
1da177e4 LT |
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 | |
dc25fcfb | 429 | * bus scan when an HBA is added (i.e. scsi_scan_host()). So it |
1da177e4 | 430 | * should only be called if the HBA becomes aware of a new scsi |
dc25fcfb MW |
431 | * device (lu) after scsi_scan_host() has completed. If successful |
432 | * this call can lead to slave_alloc() and slave_configure() callbacks | |
1da177e4 LT |
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 | /** | |
dc25fcfb | 443 | * scsi_add_host - perform sysfs registration and set up transport class |
1da177e4 LT |
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 | |
dc25fcfb MW |
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. | |
1da177e4 LT |
457 | * |
458 | * Defined in: drivers/scsi/hosts.c | |
459 | **/ | |
460 | int scsi_add_host(struct Scsi_Host *shost, struct device * dev) | |
461 | ||
462 | ||
1da177e4 LT |
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 | ||
1da177e4 LT |
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 | ||
1da177e4 LT |
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 | |
dc25fcfb | 553 | * scsi_add_host() and scsi_scan_host() are called. |
1da177e4 LT |
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 | ||
dc25fcfb MW |
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 | ||
1da177e4 LT |
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 | **/ | |
f64a181d | 725 | int scsi_track_queue_full(struct scsi_device *sdev, int depth) |
1da177e4 LT |
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) | |
1da177e4 LT |
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 | * | |
8fa728a2 | 886 | * Locks: None held |
1da177e4 LT |
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 | * | |
68b3aa7c | 904 | * Locks: None held |
1da177e4 LT |
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 | * | |
94d0e7b8 | 922 | * Locks: None held |
1da177e4 LT |
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 | * | |
df0ae249 | 940 | * Locks: None held |
1da177e4 LT |
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 | ||
1da177e4 LT |
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/<proc_name>/<host_no>" 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 | 0 implies scatter gather not supported by host | |
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 | |
4f777ed2 CH |
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 | ||
1da177e4 LT |
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 <andmike at us dot ibm dot com> | |
99cb8137 | 1410 | James Bottomley <James dot Bottomley at hansenpartnership dot com> |
1da177e4 LT |
1411 | Patrick Mansfield <patmans at us dot ibm dot com> |
1412 | Christoph Hellwig <hch at infradead dot org> | |
1413 | Doug Ledford <dledford at redhat dot com> | |
1414 | Andries Brouwer <Andries dot Brouwer at cwi dot nl> | |
f4b09ebc | 1415 | Randy Dunlap <rdunlap at xenotime dot net> |
1da177e4 LT |
1416 | Alan Stern <stern at rowland dot harvard dot edu> |
1417 | ||
1418 | ||
1419 | Douglas Gilbert | |
1420 | dgilbert at interlog dot com | |
1421 | 21st September 2004 |