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