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