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