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