1ce5c5d65SMauro Carvalho Chehab.. SPDX-License-Identifier: GPL-2.0 2ce5c5d65SMauro Carvalho Chehab 3ce5c5d65SMauro Carvalho Chehab============================================= 4ce5c5d65SMauro Carvalho ChehabSCSI mid_level - lower_level driver interface 5ce5c5d65SMauro Carvalho Chehab============================================= 6ce5c5d65SMauro Carvalho Chehab 7ce5c5d65SMauro Carvalho ChehabIntroduction 8ce5c5d65SMauro Carvalho Chehab============ 9ce5c5d65SMauro Carvalho ChehabThis document outlines the interface between the Linux SCSI mid level and 10ce5c5d65SMauro Carvalho ChehabSCSI lower level drivers. Lower level drivers (LLDs) are variously called 11ce5c5d65SMauro Carvalho Chehabhost bus adapter (HBA) drivers and host drivers (HD). A "host" in this 12ce5c5d65SMauro Carvalho Chehabcontext is a bridge between a computer IO bus (e.g. PCI or ISA) and a 13ce5c5d65SMauro Carvalho Chehabsingle SCSI initiator port on a SCSI transport. An "initiator" port 14ce5c5d65SMauro Carvalho Chehab(SCSI terminology, see SAM-3 at http://www.t10.org) sends SCSI commands 15ce5c5d65SMauro Carvalho Chehabto "target" SCSI ports (e.g. disks). There can be many LLDs in a running 16ce5c5d65SMauro Carvalho Chehabsystem, but only one per hardware type. Most LLDs can control one or more 17ce5c5d65SMauro Carvalho ChehabSCSI HBAs. Some HBAs contain multiple hosts. 18ce5c5d65SMauro Carvalho Chehab 19ce5c5d65SMauro Carvalho ChehabIn some cases the SCSI transport is an external bus that already has 20ce5c5d65SMauro Carvalho Chehabits own subsystem in Linux (e.g. USB and ieee1394). In such cases the 21ce5c5d65SMauro Carvalho ChehabSCSI subsystem LLD is a software bridge to the other driver subsystem. 22ce5c5d65SMauro Carvalho ChehabExamples are the usb-storage driver (found in the drivers/usb/storage 23ce5c5d65SMauro Carvalho Chehabdirectory) and the ieee1394/sbp2 driver (found in the drivers/ieee1394 24ce5c5d65SMauro Carvalho Chehabdirectory). 25ce5c5d65SMauro Carvalho Chehab 26ce5c5d65SMauro Carvalho ChehabFor example, the aic7xxx LLD controls Adaptec SCSI parallel interface 27ce5c5d65SMauro Carvalho Chehab(SPI) controllers based on that company's 7xxx chip series. The aic7xxx 28ce5c5d65SMauro Carvalho ChehabLLD can be built into the kernel or loaded as a module. There can only be 29ce5c5d65SMauro Carvalho Chehabone aic7xxx LLD running in a Linux system but it may be controlling many 30ce5c5d65SMauro Carvalho ChehabHBAs. These HBAs might be either on PCI daughter-boards or built into 31ce5c5d65SMauro Carvalho Chehabthe motherboard (or both). Some aic7xxx based HBAs are dual controllers 32ce5c5d65SMauro Carvalho Chehaband thus represent two hosts. Like most modern HBAs, each aic7xxx host 33ce5c5d65SMauro Carvalho Chehabhas its own PCI device address. [The one-to-one correspondence between 34ce5c5d65SMauro Carvalho Chehaba SCSI host and a PCI device is common but not required (e.g. with 35ce5c5d65SMauro Carvalho ChehabISA adapters).] 36ce5c5d65SMauro Carvalho Chehab 37ce5c5d65SMauro Carvalho ChehabThe SCSI mid level isolates an LLD from other layers such as the SCSI 38ce5c5d65SMauro Carvalho Chehabupper layer drivers and the block layer. 39ce5c5d65SMauro Carvalho Chehab 40ce5c5d65SMauro Carvalho ChehabThis version of the document roughly matches linux kernel version 2.6.8 . 41ce5c5d65SMauro Carvalho Chehab 42ce5c5d65SMauro Carvalho ChehabDocumentation 43ce5c5d65SMauro Carvalho Chehab============= 44ce5c5d65SMauro Carvalho ChehabThere is a SCSI documentation directory within the kernel source tree, 45*c3bf7774SRandy Dunlaptypically Documentation/scsi . Most documents are in reStructuredText 46*c3bf7774SRandy Dunlapformat. This file is named scsi_mid_low_api.rst and can be 47ce5c5d65SMauro Carvalho Chehabfound in that directory. A more recent copy of this document may be found 48*c3bf7774SRandy Dunlapat https://docs.kernel.org/scsi/scsi_mid_low_api.html. Many LLDs are 49*c3bf7774SRandy Dunlapdocumented in Documentation/scsi (e.g. aic7xxx.rst). The SCSI mid-level is 50*c3bf7774SRandy Dunlapbriefly described in scsi.rst which contains a URL to a document describing 51*c3bf7774SRandy Dunlapthe SCSI subsystem in the Linux Kernel 2.4 series. Two upper level 52*c3bf7774SRandy Dunlapdrivers have documents in that directory: st.rst (SCSI tape driver) and 53*c3bf7774SRandy Dunlapscsi-generic.rst (for the sg driver). 54ce5c5d65SMauro Carvalho Chehab 55*c3bf7774SRandy DunlapSome documentation (or URLs) for LLDs may be found in the C source code 56*c3bf7774SRandy Dunlapor in the same directory as the C source code. For example to find a URL 57ce5c5d65SMauro Carvalho Chehababout the USB mass storage driver see the 58ce5c5d65SMauro Carvalho Chehab/usr/src/linux/drivers/usb/storage directory. 59ce5c5d65SMauro Carvalho Chehab 60ce5c5d65SMauro Carvalho ChehabDriver structure 61ce5c5d65SMauro Carvalho Chehab================ 62ce5c5d65SMauro Carvalho ChehabTraditionally an LLD for the SCSI subsystem has been at least two files in 63ce5c5d65SMauro Carvalho Chehabthe drivers/scsi directory. For example, a driver called "xyz" has a header 64ce5c5d65SMauro Carvalho Chehabfile "xyz.h" and a source file "xyz.c". [Actually there is no good reason 65ce5c5d65SMauro Carvalho Chehabwhy this couldn't all be in one file; the header file is superfluous.] Some 66ce5c5d65SMauro Carvalho Chehabdrivers that have been ported to several operating systems have more than 67ce5c5d65SMauro Carvalho Chehabtwo files. For example the aic7xxx driver has separate files for generic 68ce5c5d65SMauro Carvalho Chehaband OS-specific code (e.g. FreeBSD and Linux). Such drivers tend to have 69ce5c5d65SMauro Carvalho Chehabtheir own directory under the drivers/scsi directory. 70ce5c5d65SMauro Carvalho Chehab 71ce5c5d65SMauro Carvalho ChehabWhen a new LLD is being added to Linux, the following files (found in the 72ce5c5d65SMauro Carvalho Chehabdrivers/scsi directory) will need some attention: Makefile and Kconfig . 73ce5c5d65SMauro Carvalho ChehabIt is probably best to study how existing LLDs are organized. 74ce5c5d65SMauro Carvalho Chehab 75ce5c5d65SMauro Carvalho ChehabAs the 2.5 series development kernels evolve into the 2.6 series 76ce5c5d65SMauro Carvalho Chehabproduction series, changes are being introduced into this interface. An 77ce5c5d65SMauro Carvalho Chehabexample of this is driver initialization code where there are now 2 models 78ce5c5d65SMauro Carvalho Chehabavailable. The older one, similar to what was found in the lk 2.4 series, 79ce5c5d65SMauro Carvalho Chehabis based on hosts that are detected at HBA driver load time. This will be 80ce5c5d65SMauro Carvalho Chehabreferred to the "passive" initialization model. The newer model allows HBAs 81ce5c5d65SMauro Carvalho Chehabto be hot plugged (and unplugged) during the lifetime of the LLD and will 82ce5c5d65SMauro Carvalho Chehabbe referred to as the "hotplug" initialization model. The newer model is 83ce5c5d65SMauro Carvalho Chehabpreferred as it can handle both traditional SCSI equipment that is 84ce5c5d65SMauro Carvalho Chehabpermanently connected as well as modern "SCSI" devices (e.g. USB or 85ce5c5d65SMauro Carvalho ChehabIEEE 1394 connected digital cameras) that are hotplugged. Both 86ce5c5d65SMauro Carvalho Chehabinitialization models are discussed in the following sections. 87ce5c5d65SMauro Carvalho Chehab 88ce5c5d65SMauro Carvalho ChehabAn LLD interfaces to the SCSI subsystem several ways: 89ce5c5d65SMauro Carvalho Chehab 90ce5c5d65SMauro Carvalho Chehab a) directly invoking functions supplied by the mid level 91ce5c5d65SMauro Carvalho Chehab b) passing a set of function pointers to a registration function 92ce5c5d65SMauro Carvalho Chehab supplied by the mid level. The mid level will then invoke these 93ce5c5d65SMauro Carvalho Chehab functions at some point in the future. The LLD will supply 94ce5c5d65SMauro Carvalho Chehab implementations of these functions. 95ce5c5d65SMauro Carvalho Chehab c) direct access to instances of well known data structures maintained 96ce5c5d65SMauro Carvalho Chehab by the mid level 97ce5c5d65SMauro Carvalho Chehab 98ce5c5d65SMauro Carvalho ChehabThose functions in group a) are listed in a section entitled "Mid level 99ce5c5d65SMauro Carvalho Chehabsupplied functions" below. 100ce5c5d65SMauro Carvalho Chehab 101ce5c5d65SMauro Carvalho ChehabThose functions in group b) are listed in a section entitled "Interface 102ce5c5d65SMauro Carvalho Chehabfunctions" below. Their function pointers are placed in the members of 103ce5c5d65SMauro Carvalho Chehab"struct scsi_host_template", an instance of which is passed to 104ce5c5d65SMauro Carvalho Chehabscsi_host_alloc() [#]_. Those interface functions that the LLD does not 105ce5c5d65SMauro Carvalho Chehabwish to supply should have NULL placed in the corresponding member of 106ce5c5d65SMauro Carvalho Chehabstruct scsi_host_template. Defining an instance of struct 107ce5c5d65SMauro Carvalho Chehabscsi_host_template at file scope will cause NULL to be placed in function 108ce5c5d65SMauro Carvalho Chehabpointer members not explicitly initialized. 109ce5c5d65SMauro Carvalho Chehab 110ce5c5d65SMauro Carvalho ChehabThose usages in group c) should be handled with care, especially in a 111ce5c5d65SMauro Carvalho Chehab"hotplug" environment. LLDs should be aware of the lifetime of instances 112ce5c5d65SMauro Carvalho Chehabthat are shared with the mid level and other layers. 113ce5c5d65SMauro Carvalho Chehab 114ce5c5d65SMauro Carvalho ChehabAll functions defined within an LLD and all data defined at file scope 115ce5c5d65SMauro Carvalho Chehabshould be static. For example the slave_alloc() function in an LLD 116ce5c5d65SMauro Carvalho Chehabcalled "xxx" could be defined as 117ce5c5d65SMauro Carvalho Chehab``static int xxx_slave_alloc(struct scsi_device * sdev) { /* code */ }`` 118ce5c5d65SMauro Carvalho Chehab 119ce5c5d65SMauro Carvalho Chehab.. [#] the scsi_host_alloc() function is a replacement for the rather vaguely 120ce5c5d65SMauro Carvalho Chehab named scsi_register() function in most situations. 121ce5c5d65SMauro Carvalho Chehab 122ce5c5d65SMauro Carvalho Chehab 123ce5c5d65SMauro Carvalho ChehabHotplug initialization model 124ce5c5d65SMauro Carvalho Chehab============================ 125ce5c5d65SMauro Carvalho ChehabIn this model an LLD controls when SCSI hosts are introduced and removed 126ce5c5d65SMauro Carvalho Chehabfrom the SCSI subsystem. Hosts can be introduced as early as driver 127ce5c5d65SMauro Carvalho Chehabinitialization and removed as late as driver shutdown. Typically a driver 128ce5c5d65SMauro Carvalho Chehabwill respond to a sysfs probe() callback that indicates an HBA has been 129ce5c5d65SMauro Carvalho Chehabdetected. After confirming that the new device is one that the LLD wants 130ce5c5d65SMauro Carvalho Chehabto control, the LLD will initialize the HBA and then register a new host 131ce5c5d65SMauro Carvalho Chehabwith the SCSI mid level. 132ce5c5d65SMauro Carvalho Chehab 133ce5c5d65SMauro Carvalho ChehabDuring LLD initialization the driver should register itself with the 134ce5c5d65SMauro Carvalho Chehabappropriate IO bus on which it expects to find HBA(s) (e.g. the PCI bus). 135ce5c5d65SMauro Carvalho ChehabThis can probably be done via sysfs. Any driver parameters (especially 136ce5c5d65SMauro Carvalho Chehabthose that are writable after the driver is loaded) could also be 137ce5c5d65SMauro Carvalho Chehabregistered with sysfs at this point. The SCSI mid level first becomes 138ce5c5d65SMauro Carvalho Chehabaware of an LLD when that LLD registers its first HBA. 139ce5c5d65SMauro Carvalho Chehab 140ce5c5d65SMauro Carvalho ChehabAt some later time, the LLD becomes aware of an HBA and what follows 141ce5c5d65SMauro Carvalho Chehabis a typical sequence of calls between the LLD and the mid level. 142ce5c5d65SMauro Carvalho ChehabThis example shows the mid level scanning the newly introduced HBA for 3 143ce5c5d65SMauro Carvalho Chehabscsi devices of which only the first 2 respond:: 144ce5c5d65SMauro Carvalho Chehab 145ce5c5d65SMauro Carvalho Chehab HBA PROBE: assume 2 SCSI devices found in scan 146ce5c5d65SMauro Carvalho Chehab LLD mid level LLD 147ce5c5d65SMauro Carvalho Chehab ===-------------------=========--------------------===------ 148ce5c5d65SMauro Carvalho Chehab scsi_host_alloc() --> 149ce5c5d65SMauro Carvalho Chehab scsi_add_host() ----> 150ce5c5d65SMauro Carvalho Chehab scsi_scan_host() -------+ 151ce5c5d65SMauro Carvalho Chehab | 152ce5c5d65SMauro Carvalho Chehab slave_alloc() 153ce5c5d65SMauro Carvalho Chehab slave_configure() --> scsi_change_queue_depth() 154ce5c5d65SMauro Carvalho Chehab | 155ce5c5d65SMauro Carvalho Chehab slave_alloc() 156ce5c5d65SMauro Carvalho Chehab slave_configure() 157ce5c5d65SMauro Carvalho Chehab | 158ce5c5d65SMauro Carvalho Chehab slave_alloc() *** 159ce5c5d65SMauro Carvalho Chehab slave_destroy() *** 160ce5c5d65SMauro Carvalho Chehab 161ce5c5d65SMauro Carvalho Chehab 162ce5c5d65SMauro Carvalho Chehab *** For scsi devices that the mid level tries to scan but do not 163ce5c5d65SMauro Carvalho Chehab respond, a slave_alloc(), slave_destroy() pair is called. 164ce5c5d65SMauro Carvalho Chehab 165ce5c5d65SMauro Carvalho ChehabIf the LLD wants to adjust the default queue settings, it can invoke 166ce5c5d65SMauro Carvalho Chehabscsi_change_queue_depth() in its slave_configure() routine. 167ce5c5d65SMauro Carvalho Chehab 168ce5c5d65SMauro Carvalho ChehabWhen an HBA is being removed it could be as part of an orderly shutdown 169ce5c5d65SMauro Carvalho Chehabassociated with the LLD module being unloaded (e.g. with the "rmmod" 170ce5c5d65SMauro Carvalho Chehabcommand) or in response to a "hot unplug" indicated by sysfs()'s 171ce5c5d65SMauro Carvalho Chehabremove() callback being invoked. In either case, the sequence is the 172ce5c5d65SMauro Carvalho Chehabsame:: 173ce5c5d65SMauro Carvalho Chehab 174ce5c5d65SMauro Carvalho Chehab HBA REMOVE: assume 2 SCSI devices attached 175ce5c5d65SMauro Carvalho Chehab LLD mid level LLD 176ce5c5d65SMauro Carvalho Chehab ===----------------------=========-----------------===------ 177ce5c5d65SMauro Carvalho Chehab scsi_remove_host() ---------+ 178ce5c5d65SMauro Carvalho Chehab | 179ce5c5d65SMauro Carvalho Chehab slave_destroy() 180ce5c5d65SMauro Carvalho Chehab slave_destroy() 181ce5c5d65SMauro Carvalho Chehab scsi_host_put() 182ce5c5d65SMauro Carvalho Chehab 183ce5c5d65SMauro Carvalho ChehabIt may be useful for a LLD to keep track of struct Scsi_Host instances 184ce5c5d65SMauro Carvalho Chehab(a pointer is returned by scsi_host_alloc()). Such instances are "owned" 185ce5c5d65SMauro Carvalho Chehabby the mid-level. struct Scsi_Host instances are freed from 186ce5c5d65SMauro Carvalho Chehabscsi_host_put() when the reference count hits zero. 187ce5c5d65SMauro Carvalho Chehab 188ce5c5d65SMauro Carvalho ChehabHot unplugging an HBA that controls a disk which is processing SCSI 189ce5c5d65SMauro Carvalho Chehabcommands on a mounted file system is an interesting situation. Reference 190ce5c5d65SMauro Carvalho Chehabcounting logic is being introduced into the mid level to cope with many 191ce5c5d65SMauro Carvalho Chehabof the issues involved. See the section on reference counting below. 192ce5c5d65SMauro Carvalho Chehab 193ce5c5d65SMauro Carvalho Chehab 194ce5c5d65SMauro Carvalho ChehabThe hotplug concept may be extended to SCSI devices. Currently, when an 195ce5c5d65SMauro Carvalho ChehabHBA is added, the scsi_scan_host() function causes a scan for SCSI devices 196ce5c5d65SMauro Carvalho Chehabattached to the HBA's SCSI transport. On newer SCSI transports the HBA 197ce5c5d65SMauro Carvalho Chehabmay become aware of a new SCSI device _after_ the scan has completed. 198ce5c5d65SMauro Carvalho ChehabAn LLD can use this sequence to make the mid level aware of a SCSI device:: 199ce5c5d65SMauro Carvalho Chehab 200ce5c5d65SMauro Carvalho Chehab SCSI DEVICE hotplug 201ce5c5d65SMauro Carvalho Chehab LLD mid level LLD 202ce5c5d65SMauro Carvalho Chehab ===-------------------=========--------------------===------ 203ce5c5d65SMauro Carvalho Chehab scsi_add_device() ------+ 204ce5c5d65SMauro Carvalho Chehab | 205ce5c5d65SMauro Carvalho Chehab slave_alloc() 206ce5c5d65SMauro Carvalho Chehab slave_configure() [--> scsi_change_queue_depth()] 207ce5c5d65SMauro Carvalho Chehab 208ce5c5d65SMauro Carvalho ChehabIn a similar fashion, an LLD may become aware that a SCSI device has been 209ce5c5d65SMauro Carvalho Chehabremoved (unplugged) or the connection to it has been interrupted. Some 210ce5c5d65SMauro Carvalho Chehabexisting SCSI transports (e.g. SPI) may not become aware that a SCSI 211ce5c5d65SMauro Carvalho Chehabdevice has been removed until a subsequent SCSI command fails which will 212ce5c5d65SMauro Carvalho Chehabprobably cause that device to be set offline by the mid level. An LLD that 213ce5c5d65SMauro Carvalho Chehabdetects the removal of a SCSI device can instigate its removal from 214ce5c5d65SMauro Carvalho Chehabupper layers with this sequence:: 215ce5c5d65SMauro Carvalho Chehab 216ce5c5d65SMauro Carvalho Chehab SCSI DEVICE hot unplug 217ce5c5d65SMauro Carvalho Chehab LLD mid level LLD 218ce5c5d65SMauro Carvalho Chehab ===----------------------=========-----------------===------ 219ce5c5d65SMauro Carvalho Chehab scsi_remove_device() -------+ 220ce5c5d65SMauro Carvalho Chehab | 221ce5c5d65SMauro Carvalho Chehab slave_destroy() 222ce5c5d65SMauro Carvalho Chehab 223ce5c5d65SMauro Carvalho ChehabIt may be useful for an LLD to keep track of struct scsi_device instances 224ce5c5d65SMauro Carvalho Chehab(a pointer is passed as the parameter to slave_alloc() and 225ce5c5d65SMauro Carvalho Chehabslave_configure() callbacks). Such instances are "owned" by the mid-level. 226ce5c5d65SMauro Carvalho Chehabstruct scsi_device instances are freed after slave_destroy(). 227ce5c5d65SMauro Carvalho Chehab 228ce5c5d65SMauro Carvalho Chehab 229ce5c5d65SMauro Carvalho ChehabReference Counting 230ce5c5d65SMauro Carvalho Chehab================== 231ce5c5d65SMauro Carvalho ChehabThe Scsi_Host structure has had reference counting infrastructure added. 232ce5c5d65SMauro Carvalho ChehabThis effectively spreads the ownership of struct Scsi_Host instances 233ce5c5d65SMauro Carvalho Chehabacross the various SCSI layers which use them. Previously such instances 234ce5c5d65SMauro Carvalho Chehabwere exclusively owned by the mid level. LLDs would not usually need to 235ce5c5d65SMauro Carvalho Chehabdirectly manipulate these reference counts but there may be some cases 236ce5c5d65SMauro Carvalho Chehabwhere they do. 237ce5c5d65SMauro Carvalho Chehab 238ce5c5d65SMauro Carvalho ChehabThere are 3 reference counting functions of interest associated with 239ce5c5d65SMauro Carvalho Chehabstruct Scsi_Host: 240ce5c5d65SMauro Carvalho Chehab 241ce5c5d65SMauro Carvalho Chehab - scsi_host_alloc(): 242ce5c5d65SMauro Carvalho Chehab returns a pointer to new instance of struct 243ce5c5d65SMauro Carvalho Chehab Scsi_Host which has its reference count ^^ set to 1 244ce5c5d65SMauro Carvalho Chehab 245ce5c5d65SMauro Carvalho Chehab - scsi_host_get(): 246ce5c5d65SMauro Carvalho Chehab adds 1 to the reference count of the given instance 247ce5c5d65SMauro Carvalho Chehab 248ce5c5d65SMauro Carvalho Chehab - scsi_host_put(): 249ce5c5d65SMauro Carvalho Chehab decrements 1 from the reference count of the given 250ce5c5d65SMauro Carvalho Chehab instance. If the reference count reaches 0 then the given instance 251ce5c5d65SMauro Carvalho Chehab is freed 252ce5c5d65SMauro Carvalho Chehab 253ce5c5d65SMauro Carvalho ChehabThe scsi_device structure has had reference counting infrastructure added. 254ce5c5d65SMauro Carvalho ChehabThis effectively spreads the ownership of struct scsi_device instances 255ce5c5d65SMauro Carvalho Chehabacross the various SCSI layers which use them. Previously such instances 256ce5c5d65SMauro Carvalho Chehabwere exclusively owned by the mid level. See the access functions declared 257ce5c5d65SMauro Carvalho Chehabtowards the end of include/scsi/scsi_device.h . If an LLD wants to keep 258ce5c5d65SMauro Carvalho Chehaba copy of a pointer to a scsi_device instance it should use scsi_device_get() 259ce5c5d65SMauro Carvalho Chehabto bump its reference count. When it is finished with the pointer it can 260ce5c5d65SMauro Carvalho Chehabuse scsi_device_put() to decrement its reference count (and potentially 261ce5c5d65SMauro Carvalho Chehabdelete it). 262ce5c5d65SMauro Carvalho Chehab 263ce5c5d65SMauro Carvalho Chehab.. Note:: 264ce5c5d65SMauro Carvalho Chehab 265ce5c5d65SMauro Carvalho Chehab struct Scsi_Host actually has 2 reference counts which are manipulated 266ce5c5d65SMauro Carvalho Chehab in parallel by these functions. 267ce5c5d65SMauro Carvalho Chehab 268ce5c5d65SMauro Carvalho Chehab 269ce5c5d65SMauro Carvalho ChehabConventions 270ce5c5d65SMauro Carvalho Chehab=========== 271ce5c5d65SMauro Carvalho ChehabFirst, Linus Torvalds's thoughts on C coding style can be found in the 272ce5c5d65SMauro Carvalho ChehabDocumentation/process/coding-style.rst file. 273ce5c5d65SMauro Carvalho Chehab 274ce5c5d65SMauro Carvalho ChehabAlso, most C99 enhancements are encouraged to the extent they are supported 275ce5c5d65SMauro Carvalho Chehabby the relevant gcc compilers. So C99 style structure and array 276ce5c5d65SMauro Carvalho Chehabinitializers are encouraged where appropriate. Don't go too far, 277ce5c5d65SMauro Carvalho ChehabVLAs are not properly supported yet. An exception to this is the use of 278ce5c5d65SMauro Carvalho Chehab``//`` style comments; ``/*...*/`` comments are still preferred in Linux. 279ce5c5d65SMauro Carvalho Chehab 280ce5c5d65SMauro Carvalho ChehabWell written, tested and documented code, need not be re-formatted to 281ce5c5d65SMauro Carvalho Chehabcomply with the above conventions. For example, the aic7xxx driver 282ce5c5d65SMauro Carvalho Chehabcomes to Linux from FreeBSD and Adaptec's own labs. No doubt FreeBSD 283ce5c5d65SMauro Carvalho Chehaband Adaptec have their own coding conventions. 284ce5c5d65SMauro Carvalho Chehab 285ce5c5d65SMauro Carvalho Chehab 286ce5c5d65SMauro Carvalho ChehabMid level supplied functions 287ce5c5d65SMauro Carvalho Chehab============================ 288ce5c5d65SMauro Carvalho ChehabThese functions are supplied by the SCSI mid level for use by LLDs. 289ce5c5d65SMauro Carvalho ChehabThe names (i.e. entry points) of these functions are exported 290ce5c5d65SMauro Carvalho Chehabso an LLD that is a module can access them. The kernel will 291ce5c5d65SMauro Carvalho Chehabarrange for the SCSI mid level to be loaded and initialized before any LLD 292ce5c5d65SMauro Carvalho Chehabis initialized. The functions below are listed alphabetically and their 293ce5c5d65SMauro Carvalho Chehabnames all start with ``scsi_``. 294ce5c5d65SMauro Carvalho Chehab 295ce5c5d65SMauro Carvalho ChehabSummary: 296ce5c5d65SMauro Carvalho Chehab 297ce5c5d65SMauro Carvalho Chehab - scsi_add_device - creates new scsi device (lu) instance 298ce5c5d65SMauro Carvalho Chehab - scsi_add_host - perform sysfs registration and set up transport class 299ce5c5d65SMauro Carvalho Chehab - scsi_change_queue_depth - change the queue depth on a SCSI device 300ce5c5d65SMauro Carvalho Chehab - scsi_bios_ptable - return copy of block device's partition table 301ce5c5d65SMauro Carvalho Chehab - scsi_block_requests - prevent further commands being queued to given host 302ce5c5d65SMauro Carvalho Chehab - scsi_host_alloc - return a new scsi_host instance whose refcount==1 303ce5c5d65SMauro Carvalho Chehab - scsi_host_get - increments Scsi_Host instance's refcount 304ce5c5d65SMauro Carvalho Chehab - scsi_host_put - decrements Scsi_Host instance's refcount (free if 0) 305ce5c5d65SMauro Carvalho Chehab - scsi_register - create and register a scsi host adapter instance. 306ce5c5d65SMauro Carvalho Chehab - scsi_remove_device - detach and remove a SCSI device 307ce5c5d65SMauro Carvalho Chehab - scsi_remove_host - detach and remove all SCSI devices owned by host 308ce5c5d65SMauro Carvalho Chehab - scsi_report_bus_reset - report scsi _bus_ reset observed 309ce5c5d65SMauro Carvalho Chehab - scsi_scan_host - scan SCSI bus 310ce5c5d65SMauro Carvalho Chehab - scsi_track_queue_full - track successive QUEUE_FULL events 311ce5c5d65SMauro Carvalho Chehab - scsi_unblock_requests - allow further commands to be queued to given host 312ce5c5d65SMauro Carvalho Chehab - scsi_unregister - [calls scsi_host_put()] 313ce5c5d65SMauro Carvalho Chehab 314ce5c5d65SMauro Carvalho Chehab 315ce5c5d65SMauro Carvalho ChehabDetails:: 316ce5c5d65SMauro Carvalho Chehab 317ce5c5d65SMauro Carvalho Chehab /** 318ce5c5d65SMauro Carvalho Chehab * scsi_add_device - creates new scsi device (lu) instance 319ce5c5d65SMauro Carvalho Chehab * @shost: pointer to scsi host instance 320ce5c5d65SMauro Carvalho Chehab * @channel: channel number (rarely other than 0) 321ce5c5d65SMauro Carvalho Chehab * @id: target id number 322ce5c5d65SMauro Carvalho Chehab * @lun: logical unit number 323ce5c5d65SMauro Carvalho Chehab * 324ce5c5d65SMauro Carvalho Chehab * Returns pointer to new struct scsi_device instance or 325ce5c5d65SMauro Carvalho Chehab * ERR_PTR(-ENODEV) (or some other bent pointer) if something is 326ce5c5d65SMauro Carvalho Chehab * wrong (e.g. no lu responds at given address) 327ce5c5d65SMauro Carvalho Chehab * 328ce5c5d65SMauro Carvalho Chehab * Might block: yes 329ce5c5d65SMauro Carvalho Chehab * 330ce5c5d65SMauro Carvalho Chehab * Notes: This call is usually performed internally during a scsi 331ce5c5d65SMauro Carvalho Chehab * bus scan when an HBA is added (i.e. scsi_scan_host()). So it 332ce5c5d65SMauro Carvalho Chehab * should only be called if the HBA becomes aware of a new scsi 333ce5c5d65SMauro Carvalho Chehab * device (lu) after scsi_scan_host() has completed. If successful 334ce5c5d65SMauro Carvalho Chehab * this call can lead to slave_alloc() and slave_configure() callbacks 335ce5c5d65SMauro Carvalho Chehab * into the LLD. 336ce5c5d65SMauro Carvalho Chehab * 337ce5c5d65SMauro Carvalho Chehab * Defined in: drivers/scsi/scsi_scan.c 338ce5c5d65SMauro Carvalho Chehab **/ 339ce5c5d65SMauro Carvalho Chehab struct scsi_device * scsi_add_device(struct Scsi_Host *shost, 340ce5c5d65SMauro Carvalho Chehab unsigned int channel, 341ce5c5d65SMauro Carvalho Chehab unsigned int id, unsigned int lun) 342ce5c5d65SMauro Carvalho Chehab 343ce5c5d65SMauro Carvalho Chehab 344ce5c5d65SMauro Carvalho Chehab /** 345ce5c5d65SMauro Carvalho Chehab * scsi_add_host - perform sysfs registration and set up transport class 346ce5c5d65SMauro Carvalho Chehab * @shost: pointer to scsi host instance 347ce5c5d65SMauro Carvalho Chehab * @dev: pointer to struct device of type scsi class 348ce5c5d65SMauro Carvalho Chehab * 349ce5c5d65SMauro Carvalho Chehab * Returns 0 on success, negative errno of failure (e.g. -ENOMEM) 350ce5c5d65SMauro Carvalho Chehab * 351ce5c5d65SMauro Carvalho Chehab * Might block: no 352ce5c5d65SMauro Carvalho Chehab * 353ce5c5d65SMauro Carvalho Chehab * Notes: Only required in "hotplug initialization model" after a 354ce5c5d65SMauro Carvalho Chehab * successful call to scsi_host_alloc(). This function does not 355ce5c5d65SMauro Carvalho Chehab * scan the bus; this can be done by calling scsi_scan_host() or 356ce5c5d65SMauro Carvalho Chehab * in some other transport-specific way. The LLD must set up 357ce5c5d65SMauro Carvalho Chehab * the transport template before calling this function and may only 358ce5c5d65SMauro Carvalho Chehab * access the transport class data after this function has been called. 359ce5c5d65SMauro Carvalho Chehab * 360ce5c5d65SMauro Carvalho Chehab * Defined in: drivers/scsi/hosts.c 361ce5c5d65SMauro Carvalho Chehab **/ 362ce5c5d65SMauro Carvalho Chehab int scsi_add_host(struct Scsi_Host *shost, struct device * dev) 363ce5c5d65SMauro Carvalho Chehab 364ce5c5d65SMauro Carvalho Chehab 365ce5c5d65SMauro Carvalho Chehab /** 366ce5c5d65SMauro Carvalho Chehab * scsi_change_queue_depth - allow LLD to change queue depth on a SCSI device 367ce5c5d65SMauro Carvalho Chehab * @sdev: pointer to SCSI device to change queue depth on 368ce5c5d65SMauro Carvalho Chehab * @tags Number of tags allowed if tagged queuing enabled, 369ce5c5d65SMauro Carvalho Chehab * or number of commands the LLD can queue up 370ce5c5d65SMauro Carvalho Chehab * in non-tagged mode (as per cmd_per_lun). 371ce5c5d65SMauro Carvalho Chehab * 372ce5c5d65SMauro Carvalho Chehab * Returns nothing 373ce5c5d65SMauro Carvalho Chehab * 374ce5c5d65SMauro Carvalho Chehab * Might block: no 375ce5c5d65SMauro Carvalho Chehab * 376ce5c5d65SMauro Carvalho Chehab * Notes: Can be invoked any time on a SCSI device controlled by this 377ce5c5d65SMauro Carvalho Chehab * LLD. [Specifically during and after slave_configure() and prior to 378ce5c5d65SMauro Carvalho Chehab * slave_destroy().] Can safely be invoked from interrupt code. 379ce5c5d65SMauro Carvalho Chehab * 380ce5c5d65SMauro Carvalho Chehab * Defined in: drivers/scsi/scsi.c [see source code for more notes] 381ce5c5d65SMauro Carvalho Chehab * 382ce5c5d65SMauro Carvalho Chehab **/ 383ce5c5d65SMauro Carvalho Chehab int scsi_change_queue_depth(struct scsi_device *sdev, int tags) 384ce5c5d65SMauro Carvalho Chehab 385ce5c5d65SMauro Carvalho Chehab 386ce5c5d65SMauro Carvalho Chehab /** 387ce5c5d65SMauro Carvalho Chehab * scsi_bios_ptable - return copy of block device's partition table 388ce5c5d65SMauro Carvalho Chehab * @dev: pointer to block device 389ce5c5d65SMauro Carvalho Chehab * 390ce5c5d65SMauro Carvalho Chehab * Returns pointer to partition table, or NULL for failure 391ce5c5d65SMauro Carvalho Chehab * 392ce5c5d65SMauro Carvalho Chehab * Might block: yes 393ce5c5d65SMauro Carvalho Chehab * 394ce5c5d65SMauro Carvalho Chehab * Notes: Caller owns memory returned (free with kfree() ) 395ce5c5d65SMauro Carvalho Chehab * 396ce5c5d65SMauro Carvalho Chehab * Defined in: drivers/scsi/scsicam.c 397ce5c5d65SMauro Carvalho Chehab **/ 398ce5c5d65SMauro Carvalho Chehab unsigned char *scsi_bios_ptable(struct block_device *dev) 399ce5c5d65SMauro Carvalho Chehab 400ce5c5d65SMauro Carvalho Chehab 401ce5c5d65SMauro Carvalho Chehab /** 402ce5c5d65SMauro Carvalho Chehab * scsi_block_requests - prevent further commands being queued to given host 403ce5c5d65SMauro Carvalho Chehab * 404ce5c5d65SMauro Carvalho Chehab * @shost: pointer to host to block commands on 405ce5c5d65SMauro Carvalho Chehab * 406ce5c5d65SMauro Carvalho Chehab * Returns nothing 407ce5c5d65SMauro Carvalho Chehab * 408ce5c5d65SMauro Carvalho Chehab * Might block: no 409ce5c5d65SMauro Carvalho Chehab * 410ce5c5d65SMauro Carvalho Chehab * Notes: There is no timer nor any other means by which the requests 411ce5c5d65SMauro Carvalho Chehab * get unblocked other than the LLD calling scsi_unblock_requests(). 412ce5c5d65SMauro Carvalho Chehab * 413ce5c5d65SMauro Carvalho Chehab * Defined in: drivers/scsi/scsi_lib.c 414ce5c5d65SMauro Carvalho Chehab **/ 415ce5c5d65SMauro Carvalho Chehab void scsi_block_requests(struct Scsi_Host * shost) 416ce5c5d65SMauro Carvalho Chehab 417ce5c5d65SMauro Carvalho Chehab 418ce5c5d65SMauro Carvalho Chehab /** 419ce5c5d65SMauro Carvalho Chehab * scsi_host_alloc - create a scsi host adapter instance and perform basic 420ce5c5d65SMauro Carvalho Chehab * initialization. 421ce5c5d65SMauro Carvalho Chehab * @sht: pointer to scsi host template 422ce5c5d65SMauro Carvalho Chehab * @privsize: extra bytes to allocate in hostdata array (which is the 423ce5c5d65SMauro Carvalho Chehab * last member of the returned Scsi_Host instance) 424ce5c5d65SMauro Carvalho Chehab * 425ce5c5d65SMauro Carvalho Chehab * Returns pointer to new Scsi_Host instance or NULL on failure 426ce5c5d65SMauro Carvalho Chehab * 427ce5c5d65SMauro Carvalho Chehab * Might block: yes 428ce5c5d65SMauro Carvalho Chehab * 429ce5c5d65SMauro Carvalho Chehab * Notes: When this call returns to the LLD, the SCSI bus scan on 430ce5c5d65SMauro Carvalho Chehab * this host has _not_ yet been done. 431ce5c5d65SMauro Carvalho Chehab * The hostdata array (by default zero length) is a per host scratch 432ce5c5d65SMauro Carvalho Chehab * area for the LLD's exclusive use. 433ce5c5d65SMauro Carvalho Chehab * Both associated refcounting objects have their refcount set to 1. 434ce5c5d65SMauro Carvalho Chehab * Full registration (in sysfs) and a bus scan are performed later when 435ce5c5d65SMauro Carvalho Chehab * scsi_add_host() and scsi_scan_host() are called. 436ce5c5d65SMauro Carvalho Chehab * 437ce5c5d65SMauro Carvalho Chehab * Defined in: drivers/scsi/hosts.c . 438ce5c5d65SMauro Carvalho Chehab **/ 439e0d3f2c6SBart Van Assche struct Scsi_Host * scsi_host_alloc(const struct scsi_host_template * sht, 440ce5c5d65SMauro Carvalho Chehab int privsize) 441ce5c5d65SMauro Carvalho Chehab 442ce5c5d65SMauro Carvalho Chehab 443ce5c5d65SMauro Carvalho Chehab /** 444ce5c5d65SMauro Carvalho Chehab * scsi_host_get - increment Scsi_Host instance refcount 445ce5c5d65SMauro Carvalho Chehab * @shost: pointer to struct Scsi_Host instance 446ce5c5d65SMauro Carvalho Chehab * 447ce5c5d65SMauro Carvalho Chehab * Returns nothing 448ce5c5d65SMauro Carvalho Chehab * 449ce5c5d65SMauro Carvalho Chehab * Might block: currently may block but may be changed to not block 450ce5c5d65SMauro Carvalho Chehab * 451ce5c5d65SMauro Carvalho Chehab * Notes: Actually increments the counts in two sub-objects 452ce5c5d65SMauro Carvalho Chehab * 453ce5c5d65SMauro Carvalho Chehab * Defined in: drivers/scsi/hosts.c 454ce5c5d65SMauro Carvalho Chehab **/ 455ce5c5d65SMauro Carvalho Chehab void scsi_host_get(struct Scsi_Host *shost) 456ce5c5d65SMauro Carvalho Chehab 457ce5c5d65SMauro Carvalho Chehab 458ce5c5d65SMauro Carvalho Chehab /** 459ce5c5d65SMauro Carvalho Chehab * scsi_host_put - decrement Scsi_Host instance refcount, free if 0 460ce5c5d65SMauro Carvalho Chehab * @shost: pointer to struct Scsi_Host instance 461ce5c5d65SMauro Carvalho Chehab * 462ce5c5d65SMauro Carvalho Chehab * Returns nothing 463ce5c5d65SMauro Carvalho Chehab * 464ce5c5d65SMauro Carvalho Chehab * Might block: currently may block but may be changed to not block 465ce5c5d65SMauro Carvalho Chehab * 466ce5c5d65SMauro Carvalho Chehab * Notes: Actually decrements the counts in two sub-objects. If the 467ce5c5d65SMauro Carvalho Chehab * latter refcount reaches 0, the Scsi_Host instance is freed. 468ce5c5d65SMauro Carvalho Chehab * The LLD need not worry exactly when the Scsi_Host instance is 469ce5c5d65SMauro Carvalho Chehab * freed, it just shouldn't access the instance after it has balanced 470ce5c5d65SMauro Carvalho Chehab * out its refcount usage. 471ce5c5d65SMauro Carvalho Chehab * 472ce5c5d65SMauro Carvalho Chehab * Defined in: drivers/scsi/hosts.c 473ce5c5d65SMauro Carvalho Chehab **/ 474ce5c5d65SMauro Carvalho Chehab void scsi_host_put(struct Scsi_Host *shost) 475ce5c5d65SMauro Carvalho Chehab 476ce5c5d65SMauro Carvalho Chehab 477ce5c5d65SMauro Carvalho Chehab /** 478ce5c5d65SMauro Carvalho Chehab * scsi_register - create and register a scsi host adapter instance. 479ce5c5d65SMauro Carvalho Chehab * @sht: pointer to scsi host template 480ce5c5d65SMauro Carvalho Chehab * @privsize: extra bytes to allocate in hostdata array (which is the 481ce5c5d65SMauro Carvalho Chehab * last member of the returned Scsi_Host instance) 482ce5c5d65SMauro Carvalho Chehab * 483ce5c5d65SMauro Carvalho Chehab * Returns pointer to new Scsi_Host instance or NULL on failure 484ce5c5d65SMauro Carvalho Chehab * 485ce5c5d65SMauro Carvalho Chehab * Might block: yes 486ce5c5d65SMauro Carvalho Chehab * 487ce5c5d65SMauro Carvalho Chehab * Notes: When this call returns to the LLD, the SCSI bus scan on 488ce5c5d65SMauro Carvalho Chehab * this host has _not_ yet been done. 489ce5c5d65SMauro Carvalho Chehab * The hostdata array (by default zero length) is a per host scratch 490ce5c5d65SMauro Carvalho Chehab * area for the LLD. 491ce5c5d65SMauro Carvalho Chehab * 492ce5c5d65SMauro Carvalho Chehab * Defined in: drivers/scsi/hosts.c . 493ce5c5d65SMauro Carvalho Chehab **/ 494ce5c5d65SMauro Carvalho Chehab struct Scsi_Host * scsi_register(struct scsi_host_template * sht, 495ce5c5d65SMauro Carvalho Chehab int privsize) 496ce5c5d65SMauro Carvalho Chehab 497ce5c5d65SMauro Carvalho Chehab 498ce5c5d65SMauro Carvalho Chehab /** 499ce5c5d65SMauro Carvalho Chehab * scsi_remove_device - detach and remove a SCSI device 500ce5c5d65SMauro Carvalho Chehab * @sdev: a pointer to a scsi device instance 501ce5c5d65SMauro Carvalho Chehab * 502ce5c5d65SMauro Carvalho Chehab * Returns value: 0 on success, -EINVAL if device not attached 503ce5c5d65SMauro Carvalho Chehab * 504ce5c5d65SMauro Carvalho Chehab * Might block: yes 505ce5c5d65SMauro Carvalho Chehab * 506ce5c5d65SMauro Carvalho Chehab * Notes: If an LLD becomes aware that a scsi device (lu) has 507ce5c5d65SMauro Carvalho Chehab * been removed but its host is still present then it can request 508ce5c5d65SMauro Carvalho Chehab * the removal of that scsi device. If successful this call will 509ce5c5d65SMauro Carvalho Chehab * lead to the slave_destroy() callback being invoked. sdev is an 510ce5c5d65SMauro Carvalho Chehab * invalid pointer after this call. 511ce5c5d65SMauro Carvalho Chehab * 512ce5c5d65SMauro Carvalho Chehab * Defined in: drivers/scsi/scsi_sysfs.c . 513ce5c5d65SMauro Carvalho Chehab **/ 514ce5c5d65SMauro Carvalho Chehab int scsi_remove_device(struct scsi_device *sdev) 515ce5c5d65SMauro Carvalho Chehab 516ce5c5d65SMauro Carvalho Chehab 517ce5c5d65SMauro Carvalho Chehab /** 518ce5c5d65SMauro Carvalho Chehab * scsi_remove_host - detach and remove all SCSI devices owned by host 519ce5c5d65SMauro Carvalho Chehab * @shost: a pointer to a scsi host instance 520ce5c5d65SMauro Carvalho Chehab * 521ce5c5d65SMauro Carvalho Chehab * Returns value: 0 on success, 1 on failure (e.g. LLD busy ??) 522ce5c5d65SMauro Carvalho Chehab * 523ce5c5d65SMauro Carvalho Chehab * Might block: yes 524ce5c5d65SMauro Carvalho Chehab * 525ce5c5d65SMauro Carvalho Chehab * Notes: Should only be invoked if the "hotplug initialization 526ce5c5d65SMauro Carvalho Chehab * model" is being used. It should be called _prior_ to 527ce5c5d65SMauro Carvalho Chehab * scsi_unregister(). 528ce5c5d65SMauro Carvalho Chehab * 529ce5c5d65SMauro Carvalho Chehab * Defined in: drivers/scsi/hosts.c . 530ce5c5d65SMauro Carvalho Chehab **/ 531ce5c5d65SMauro Carvalho Chehab int scsi_remove_host(struct Scsi_Host *shost) 532ce5c5d65SMauro Carvalho Chehab 533ce5c5d65SMauro Carvalho Chehab 534ce5c5d65SMauro Carvalho Chehab /** 535ce5c5d65SMauro Carvalho Chehab * scsi_report_bus_reset - report scsi _bus_ reset observed 536ce5c5d65SMauro Carvalho Chehab * @shost: a pointer to a scsi host involved 537ce5c5d65SMauro Carvalho Chehab * @channel: channel (within) host on which scsi bus reset occurred 538ce5c5d65SMauro Carvalho Chehab * 539ce5c5d65SMauro Carvalho Chehab * Returns nothing 540ce5c5d65SMauro Carvalho Chehab * 541ce5c5d65SMauro Carvalho Chehab * Might block: no 542ce5c5d65SMauro Carvalho Chehab * 543ce5c5d65SMauro Carvalho Chehab * Notes: This only needs to be called if the reset is one which 544ce5c5d65SMauro Carvalho Chehab * originates from an unknown location. Resets originated by the 545ce5c5d65SMauro Carvalho Chehab * mid level itself don't need to call this, but there should be 546ce5c5d65SMauro Carvalho Chehab * no harm. The main purpose of this is to make sure that a 547ce5c5d65SMauro Carvalho Chehab * CHECK_CONDITION is properly treated. 548ce5c5d65SMauro Carvalho Chehab * 549ce5c5d65SMauro Carvalho Chehab * Defined in: drivers/scsi/scsi_error.c . 550ce5c5d65SMauro Carvalho Chehab **/ 551ce5c5d65SMauro Carvalho Chehab void scsi_report_bus_reset(struct Scsi_Host * shost, int channel) 552ce5c5d65SMauro Carvalho Chehab 553ce5c5d65SMauro Carvalho Chehab 554ce5c5d65SMauro Carvalho Chehab /** 555ce5c5d65SMauro Carvalho Chehab * scsi_scan_host - scan SCSI bus 556ce5c5d65SMauro Carvalho Chehab * @shost: a pointer to a scsi host instance 557ce5c5d65SMauro Carvalho Chehab * 558ce5c5d65SMauro Carvalho Chehab * Might block: yes 559ce5c5d65SMauro Carvalho Chehab * 560ce5c5d65SMauro Carvalho Chehab * Notes: Should be called after scsi_add_host() 561ce5c5d65SMauro Carvalho Chehab * 562ce5c5d65SMauro Carvalho Chehab * Defined in: drivers/scsi/scsi_scan.c 563ce5c5d65SMauro Carvalho Chehab **/ 564ce5c5d65SMauro Carvalho Chehab void scsi_scan_host(struct Scsi_Host *shost) 565ce5c5d65SMauro Carvalho Chehab 566ce5c5d65SMauro Carvalho Chehab 567ce5c5d65SMauro Carvalho Chehab /** 568ce5c5d65SMauro Carvalho Chehab * scsi_track_queue_full - track successive QUEUE_FULL events on given 569ce5c5d65SMauro Carvalho Chehab * device to determine if and when there is a need 570ce5c5d65SMauro Carvalho Chehab * to adjust the queue depth on the device. 571ce5c5d65SMauro Carvalho Chehab * @sdev: pointer to SCSI device instance 572ce5c5d65SMauro Carvalho Chehab * @depth: Current number of outstanding SCSI commands on this device, 573ce5c5d65SMauro Carvalho Chehab * not counting the one returned as QUEUE_FULL. 574ce5c5d65SMauro Carvalho Chehab * 575ce5c5d65SMauro Carvalho Chehab * Returns 0 - no change needed 576ce5c5d65SMauro Carvalho Chehab * >0 - adjust queue depth to this new depth 577ce5c5d65SMauro Carvalho Chehab * -1 - drop back to untagged operation using host->cmd_per_lun 578ce5c5d65SMauro Carvalho Chehab * as the untagged command depth 579ce5c5d65SMauro Carvalho Chehab * 580ce5c5d65SMauro Carvalho Chehab * Might block: no 581ce5c5d65SMauro Carvalho Chehab * 582ce5c5d65SMauro Carvalho Chehab * Notes: LLDs may call this at any time and we will do "The Right 583ce5c5d65SMauro Carvalho Chehab * Thing"; interrupt context safe. 584ce5c5d65SMauro Carvalho Chehab * 585ce5c5d65SMauro Carvalho Chehab * Defined in: drivers/scsi/scsi.c . 586ce5c5d65SMauro Carvalho Chehab **/ 587ce5c5d65SMauro Carvalho Chehab int scsi_track_queue_full(struct scsi_device *sdev, int depth) 588ce5c5d65SMauro Carvalho Chehab 589ce5c5d65SMauro Carvalho Chehab 590ce5c5d65SMauro Carvalho Chehab /** 591ce5c5d65SMauro Carvalho Chehab * scsi_unblock_requests - allow further commands to be queued to given host 592ce5c5d65SMauro Carvalho Chehab * 593ce5c5d65SMauro Carvalho Chehab * @shost: pointer to host to unblock commands on 594ce5c5d65SMauro Carvalho Chehab * 595ce5c5d65SMauro Carvalho Chehab * Returns nothing 596ce5c5d65SMauro Carvalho Chehab * 597ce5c5d65SMauro Carvalho Chehab * Might block: no 598ce5c5d65SMauro Carvalho Chehab * 599ce5c5d65SMauro Carvalho Chehab * Defined in: drivers/scsi/scsi_lib.c . 600ce5c5d65SMauro Carvalho Chehab **/ 601ce5c5d65SMauro Carvalho Chehab void scsi_unblock_requests(struct Scsi_Host * shost) 602ce5c5d65SMauro Carvalho Chehab 603ce5c5d65SMauro Carvalho Chehab 604ce5c5d65SMauro Carvalho Chehab /** 605ce5c5d65SMauro Carvalho Chehab * scsi_unregister - unregister and free memory used by host instance 606ce5c5d65SMauro Carvalho Chehab * @shp: pointer to scsi host instance to unregister. 607ce5c5d65SMauro Carvalho Chehab * 608ce5c5d65SMauro Carvalho Chehab * Returns nothing 609ce5c5d65SMauro Carvalho Chehab * 610ce5c5d65SMauro Carvalho Chehab * Might block: no 611ce5c5d65SMauro Carvalho Chehab * 612ce5c5d65SMauro Carvalho Chehab * Notes: Should not be invoked if the "hotplug initialization 613ce5c5d65SMauro Carvalho Chehab * model" is being used. Called internally by exit_this_scsi_driver() 614ce5c5d65SMauro Carvalho Chehab * in the "passive initialization model". Hence a LLD has no need to 615ce5c5d65SMauro Carvalho Chehab * call this function directly. 616ce5c5d65SMauro Carvalho Chehab * 617ce5c5d65SMauro Carvalho Chehab * Defined in: drivers/scsi/hosts.c . 618ce5c5d65SMauro Carvalho Chehab **/ 619ce5c5d65SMauro Carvalho Chehab void scsi_unregister(struct Scsi_Host * shp) 620ce5c5d65SMauro Carvalho Chehab 621ce5c5d65SMauro Carvalho Chehab 622ce5c5d65SMauro Carvalho Chehab 623ce5c5d65SMauro Carvalho Chehab 624ce5c5d65SMauro Carvalho ChehabInterface Functions 625ce5c5d65SMauro Carvalho Chehab=================== 626ce5c5d65SMauro Carvalho ChehabInterface functions are supplied (defined) by LLDs and their function 627ce5c5d65SMauro Carvalho Chehabpointers are placed in an instance of struct scsi_host_template which 628ce5c5d65SMauro Carvalho Chehabis passed to scsi_host_alloc() [or scsi_register() / init_this_scsi_driver()]. 629ce5c5d65SMauro Carvalho ChehabSome are mandatory. Interface functions should be declared static. The 630ce5c5d65SMauro Carvalho Chehabaccepted convention is that driver "xyz" will declare its slave_configure() 631ce5c5d65SMauro Carvalho Chehabfunction as:: 632ce5c5d65SMauro Carvalho Chehab 633ce5c5d65SMauro Carvalho Chehab static int xyz_slave_configure(struct scsi_device * sdev); 634ce5c5d65SMauro Carvalho Chehab 635ce5c5d65SMauro Carvalho Chehaband so forth for all interface functions listed below. 636ce5c5d65SMauro Carvalho Chehab 637ce5c5d65SMauro Carvalho ChehabA pointer to this function should be placed in the 'slave_configure' member 638ce5c5d65SMauro Carvalho Chehabof a "struct scsi_host_template" instance. A pointer to such an instance 639ce5c5d65SMauro Carvalho Chehabshould be passed to the mid level's scsi_host_alloc() [or scsi_register() / 640ce5c5d65SMauro Carvalho Chehabinit_this_scsi_driver()]. 641ce5c5d65SMauro Carvalho Chehab 642ce5c5d65SMauro Carvalho ChehabThe interface functions are also described in the include/scsi/scsi_host.h 643ce5c5d65SMauro Carvalho Chehabfile immediately above their definition point in "struct scsi_host_template". 644ce5c5d65SMauro Carvalho ChehabIn some cases more detail is given in scsi_host.h than below. 645ce5c5d65SMauro Carvalho Chehab 646ce5c5d65SMauro Carvalho ChehabThe interface functions are listed below in alphabetical order. 647ce5c5d65SMauro Carvalho Chehab 648ce5c5d65SMauro Carvalho ChehabSummary: 649ce5c5d65SMauro Carvalho Chehab 650ce5c5d65SMauro Carvalho Chehab - bios_param - fetch head, sector, cylinder info for a disk 651ce5c5d65SMauro Carvalho Chehab - eh_timed_out - notify the host that a command timer expired 652ce5c5d65SMauro Carvalho Chehab - eh_abort_handler - abort given command 653ce5c5d65SMauro Carvalho Chehab - eh_bus_reset_handler - issue SCSI bus reset 654ce5c5d65SMauro Carvalho Chehab - eh_device_reset_handler - issue SCSI device reset 655ce5c5d65SMauro Carvalho Chehab - eh_host_reset_handler - reset host (host bus adapter) 656ce5c5d65SMauro Carvalho Chehab - info - supply information about given host 657ce5c5d65SMauro Carvalho Chehab - ioctl - driver can respond to ioctls 658ce5c5d65SMauro Carvalho Chehab - proc_info - supports /proc/scsi/{driver_name}/{host_no} 659ce5c5d65SMauro Carvalho Chehab - queuecommand - queue scsi command, invoke 'done' on completion 660ce5c5d65SMauro Carvalho Chehab - slave_alloc - prior to any commands being sent to a new device 661ce5c5d65SMauro Carvalho Chehab - slave_configure - driver fine tuning for given device after attach 662ce5c5d65SMauro Carvalho Chehab - slave_destroy - given device is about to be shut down 663ce5c5d65SMauro Carvalho Chehab 664ce5c5d65SMauro Carvalho Chehab 665ce5c5d65SMauro Carvalho ChehabDetails:: 666ce5c5d65SMauro Carvalho Chehab 667ce5c5d65SMauro Carvalho Chehab /** 668ce5c5d65SMauro Carvalho Chehab * bios_param - fetch head, sector, cylinder info for a disk 669ce5c5d65SMauro Carvalho Chehab * @sdev: pointer to scsi device context (defined in 670ce5c5d65SMauro Carvalho Chehab * include/scsi/scsi_device.h) 671ce5c5d65SMauro Carvalho Chehab * @bdev: pointer to block device context (defined in fs.h) 672ce5c5d65SMauro Carvalho Chehab * @capacity: device size (in 512 byte sectors) 673ce5c5d65SMauro Carvalho Chehab * @params: three element array to place output: 674ce5c5d65SMauro Carvalho Chehab * params[0] number of heads (max 255) 675ce5c5d65SMauro Carvalho Chehab * params[1] number of sectors (max 63) 676ce5c5d65SMauro Carvalho Chehab * params[2] number of cylinders 677ce5c5d65SMauro Carvalho Chehab * 678ce5c5d65SMauro Carvalho Chehab * Return value is ignored 679ce5c5d65SMauro Carvalho Chehab * 680ce5c5d65SMauro Carvalho Chehab * Locks: none 681ce5c5d65SMauro Carvalho Chehab * 682ce5c5d65SMauro Carvalho Chehab * Calling context: process (sd) 683ce5c5d65SMauro Carvalho Chehab * 684ce5c5d65SMauro Carvalho Chehab * Notes: an arbitrary geometry (based on READ CAPACITY) is used 685ce5c5d65SMauro Carvalho Chehab * if this function is not provided. The params array is 686ce5c5d65SMauro Carvalho Chehab * pre-initialized with made up values just in case this function 687ce5c5d65SMauro Carvalho Chehab * doesn't output anything. 688ce5c5d65SMauro Carvalho Chehab * 689ce5c5d65SMauro Carvalho Chehab * Optionally defined in: LLD 690ce5c5d65SMauro Carvalho Chehab **/ 691ce5c5d65SMauro Carvalho Chehab int bios_param(struct scsi_device * sdev, struct block_device *bdev, 692ce5c5d65SMauro Carvalho Chehab sector_t capacity, int params[3]) 693ce5c5d65SMauro Carvalho Chehab 694ce5c5d65SMauro Carvalho Chehab 695ce5c5d65SMauro Carvalho Chehab /** 696ce5c5d65SMauro Carvalho Chehab * eh_timed_out - The timer for the command has just fired 697ce5c5d65SMauro Carvalho Chehab * @scp: identifies command timing out 698ce5c5d65SMauro Carvalho Chehab * 699ce5c5d65SMauro Carvalho Chehab * Returns: 700ce5c5d65SMauro Carvalho Chehab * 701ce5c5d65SMauro Carvalho Chehab * EH_HANDLED: I fixed the error, please complete the command 702ce5c5d65SMauro Carvalho Chehab * EH_RESET_TIMER: I need more time, reset the timer and 703ce5c5d65SMauro Carvalho Chehab * begin counting again 704ce5c5d65SMauro Carvalho Chehab * EH_NOT_HANDLED Begin normal error recovery 705ce5c5d65SMauro Carvalho Chehab * 706ce5c5d65SMauro Carvalho Chehab * 707ce5c5d65SMauro Carvalho Chehab * Locks: None held 708ce5c5d65SMauro Carvalho Chehab * 709ce5c5d65SMauro Carvalho Chehab * Calling context: interrupt 710ce5c5d65SMauro Carvalho Chehab * 711ce5c5d65SMauro Carvalho Chehab * Notes: This is to give the LLD an opportunity to do local recovery. 712ce5c5d65SMauro Carvalho Chehab * This recovery is limited to determining if the outstanding command 713ce5c5d65SMauro Carvalho Chehab * will ever complete. You may not abort and restart the command from 714ce5c5d65SMauro Carvalho Chehab * this callback. 715ce5c5d65SMauro Carvalho Chehab * 716ce5c5d65SMauro Carvalho Chehab * Optionally defined in: LLD 717ce5c5d65SMauro Carvalho Chehab **/ 718ce5c5d65SMauro Carvalho Chehab int eh_timed_out(struct scsi_cmnd * scp) 719ce5c5d65SMauro Carvalho Chehab 720ce5c5d65SMauro Carvalho Chehab 721ce5c5d65SMauro Carvalho Chehab /** 722ce5c5d65SMauro Carvalho Chehab * eh_abort_handler - abort command associated with scp 723ce5c5d65SMauro Carvalho Chehab * @scp: identifies command to be aborted 724ce5c5d65SMauro Carvalho Chehab * 725ce5c5d65SMauro Carvalho Chehab * Returns SUCCESS if command aborted else FAILED 726ce5c5d65SMauro Carvalho Chehab * 727ce5c5d65SMauro Carvalho Chehab * Locks: None held 728ce5c5d65SMauro Carvalho Chehab * 729ce5c5d65SMauro Carvalho Chehab * Calling context: kernel thread 730ce5c5d65SMauro Carvalho Chehab * 731ce5c5d65SMauro Carvalho Chehab * Notes: If 'no_async_abort' is defined this callback 732ce5c5d65SMauro Carvalho Chehab * will be invoked from scsi_eh thread. No other commands 733ce5c5d65SMauro Carvalho Chehab * will then be queued on current host during eh. 734deef1be1SJohn Garry * Otherwise it will be called whenever scsi_timeout() 735ce5c5d65SMauro Carvalho Chehab * is called due to a command timeout. 736ce5c5d65SMauro Carvalho Chehab * 737ce5c5d65SMauro Carvalho Chehab * Optionally defined in: LLD 738ce5c5d65SMauro Carvalho Chehab **/ 739ce5c5d65SMauro Carvalho Chehab int eh_abort_handler(struct scsi_cmnd * scp) 740ce5c5d65SMauro Carvalho Chehab 741ce5c5d65SMauro Carvalho Chehab 742ce5c5d65SMauro Carvalho Chehab /** 743ce5c5d65SMauro Carvalho Chehab * eh_bus_reset_handler - issue SCSI bus reset 744ce5c5d65SMauro Carvalho Chehab * @scp: SCSI bus that contains this device should be reset 745ce5c5d65SMauro Carvalho Chehab * 746ce5c5d65SMauro Carvalho Chehab * Returns SUCCESS if command aborted else FAILED 747ce5c5d65SMauro Carvalho Chehab * 748ce5c5d65SMauro Carvalho Chehab * Locks: None held 749ce5c5d65SMauro Carvalho Chehab * 750ce5c5d65SMauro Carvalho Chehab * Calling context: kernel thread 751ce5c5d65SMauro Carvalho Chehab * 752ce5c5d65SMauro Carvalho Chehab * Notes: Invoked from scsi_eh thread. No other commands will be 753ce5c5d65SMauro Carvalho Chehab * queued on current host during eh. 754ce5c5d65SMauro Carvalho Chehab * 755ce5c5d65SMauro Carvalho Chehab * Optionally defined in: LLD 756ce5c5d65SMauro Carvalho Chehab **/ 757ce5c5d65SMauro Carvalho Chehab int eh_bus_reset_handler(struct scsi_cmnd * scp) 758ce5c5d65SMauro Carvalho Chehab 759ce5c5d65SMauro Carvalho Chehab 760ce5c5d65SMauro Carvalho Chehab /** 761ce5c5d65SMauro Carvalho Chehab * eh_device_reset_handler - issue SCSI device reset 762ce5c5d65SMauro Carvalho Chehab * @scp: identifies SCSI device to be reset 763ce5c5d65SMauro Carvalho Chehab * 764ce5c5d65SMauro Carvalho Chehab * Returns SUCCESS if command aborted else FAILED 765ce5c5d65SMauro Carvalho Chehab * 766ce5c5d65SMauro Carvalho Chehab * Locks: None held 767ce5c5d65SMauro Carvalho Chehab * 768ce5c5d65SMauro Carvalho Chehab * Calling context: kernel thread 769ce5c5d65SMauro Carvalho Chehab * 770ce5c5d65SMauro Carvalho Chehab * Notes: Invoked from scsi_eh thread. No other commands will be 771ce5c5d65SMauro Carvalho Chehab * queued on current host during eh. 772ce5c5d65SMauro Carvalho Chehab * 773ce5c5d65SMauro Carvalho Chehab * Optionally defined in: LLD 774ce5c5d65SMauro Carvalho Chehab **/ 775ce5c5d65SMauro Carvalho Chehab int eh_device_reset_handler(struct scsi_cmnd * scp) 776ce5c5d65SMauro Carvalho Chehab 777ce5c5d65SMauro Carvalho Chehab 778ce5c5d65SMauro Carvalho Chehab /** 779ce5c5d65SMauro Carvalho Chehab * eh_host_reset_handler - reset host (host bus adapter) 780ce5c5d65SMauro Carvalho Chehab * @scp: SCSI host that contains this device should be reset 781ce5c5d65SMauro Carvalho Chehab * 782ce5c5d65SMauro Carvalho Chehab * Returns SUCCESS if command aborted else FAILED 783ce5c5d65SMauro Carvalho Chehab * 784ce5c5d65SMauro Carvalho Chehab * Locks: None held 785ce5c5d65SMauro Carvalho Chehab * 786ce5c5d65SMauro Carvalho Chehab * Calling context: kernel thread 787ce5c5d65SMauro Carvalho Chehab * 788ce5c5d65SMauro Carvalho Chehab * Notes: Invoked from scsi_eh thread. No other commands will be 789ce5c5d65SMauro Carvalho Chehab * queued on current host during eh. 790ce5c5d65SMauro Carvalho Chehab * With the default eh_strategy in place, if none of the _abort_, 791ce5c5d65SMauro Carvalho Chehab * _device_reset_, _bus_reset_ or this eh handler function are 792ce5c5d65SMauro Carvalho Chehab * defined (or they all return FAILED) then the device in question 793ce5c5d65SMauro Carvalho Chehab * will be set offline whenever eh is invoked. 794ce5c5d65SMauro Carvalho Chehab * 795ce5c5d65SMauro Carvalho Chehab * Optionally defined in: LLD 796ce5c5d65SMauro Carvalho Chehab **/ 797ce5c5d65SMauro Carvalho Chehab int eh_host_reset_handler(struct scsi_cmnd * scp) 798ce5c5d65SMauro Carvalho Chehab 799ce5c5d65SMauro Carvalho Chehab 800ce5c5d65SMauro Carvalho Chehab /** 801ce5c5d65SMauro Carvalho Chehab * info - supply information about given host: driver name plus data 802ce5c5d65SMauro Carvalho Chehab * to distinguish given host 803ce5c5d65SMauro Carvalho Chehab * @shp: host to supply information about 804ce5c5d65SMauro Carvalho Chehab * 805ce5c5d65SMauro Carvalho Chehab * Return ASCII null terminated string. [This driver is assumed to 806ce5c5d65SMauro Carvalho Chehab * manage the memory pointed to and maintain it, typically for the 807ce5c5d65SMauro Carvalho Chehab * lifetime of this host.] 808ce5c5d65SMauro Carvalho Chehab * 809ce5c5d65SMauro Carvalho Chehab * Locks: none 810ce5c5d65SMauro Carvalho Chehab * 811ce5c5d65SMauro Carvalho Chehab * Calling context: process 812ce5c5d65SMauro Carvalho Chehab * 813ce5c5d65SMauro Carvalho Chehab * Notes: Often supplies PCI or ISA information such as IO addresses 814ce5c5d65SMauro Carvalho Chehab * and interrupt numbers. If not supplied struct Scsi_Host::name used 815ce5c5d65SMauro Carvalho Chehab * instead. It is assumed the returned information fits on one line 816ce5c5d65SMauro Carvalho Chehab * (i.e. does not included embedded newlines). 817ce5c5d65SMauro Carvalho Chehab * The SCSI_IOCTL_PROBE_HOST ioctl yields the string returned by this 818ce5c5d65SMauro Carvalho Chehab * function (or struct Scsi_Host::name if this function is not 819ce5c5d65SMauro Carvalho Chehab * available). 820ce5c5d65SMauro Carvalho Chehab * In a similar manner, init_this_scsi_driver() outputs to the console 821ce5c5d65SMauro Carvalho Chehab * each host's "info" (or name) for the driver it is registering. 822ce5c5d65SMauro Carvalho Chehab * Also if proc_info() is not supplied, the output of this function 823ce5c5d65SMauro Carvalho Chehab * is used instead. 824ce5c5d65SMauro Carvalho Chehab * 825ce5c5d65SMauro Carvalho Chehab * Optionally defined in: LLD 826ce5c5d65SMauro Carvalho Chehab **/ 827ce5c5d65SMauro Carvalho Chehab const char * info(struct Scsi_Host * shp) 828ce5c5d65SMauro Carvalho Chehab 829ce5c5d65SMauro Carvalho Chehab 830ce5c5d65SMauro Carvalho Chehab /** 831ce5c5d65SMauro Carvalho Chehab * ioctl - driver can respond to ioctls 832ce5c5d65SMauro Carvalho Chehab * @sdp: device that ioctl was issued for 833ce5c5d65SMauro Carvalho Chehab * @cmd: ioctl number 834ce5c5d65SMauro Carvalho Chehab * @arg: pointer to read or write data from. Since it points to 835ce5c5d65SMauro Carvalho Chehab * user space, should use appropriate kernel functions 836ce5c5d65SMauro Carvalho Chehab * (e.g. copy_from_user() ). In the Unix style this argument 837ce5c5d65SMauro Carvalho Chehab * can also be viewed as an unsigned long. 838ce5c5d65SMauro Carvalho Chehab * 839ce5c5d65SMauro Carvalho Chehab * Returns negative "errno" value when there is a problem. 0 or a 840ce5c5d65SMauro Carvalho Chehab * positive value indicates success and is returned to the user space. 841ce5c5d65SMauro Carvalho Chehab * 842ce5c5d65SMauro Carvalho Chehab * Locks: none 843ce5c5d65SMauro Carvalho Chehab * 844ce5c5d65SMauro Carvalho Chehab * Calling context: process 845ce5c5d65SMauro Carvalho Chehab * 846ce5c5d65SMauro Carvalho Chehab * Notes: The SCSI subsystem uses a "trickle down" ioctl model. 847ce5c5d65SMauro Carvalho Chehab * The user issues an ioctl() against an upper level driver 848ce5c5d65SMauro Carvalho Chehab * (e.g. /dev/sdc) and if the upper level driver doesn't recognize 849ce5c5d65SMauro Carvalho Chehab * the 'cmd' then it is passed to the SCSI mid level. If the SCSI 850ce5c5d65SMauro Carvalho Chehab * mid level does not recognize it, then the LLD that controls 851ce5c5d65SMauro Carvalho Chehab * the device receives the ioctl. According to recent Unix standards 852ce5c5d65SMauro Carvalho Chehab * unsupported ioctl() 'cmd' numbers should return -ENOTTY. 853ce5c5d65SMauro Carvalho Chehab * 854ce5c5d65SMauro Carvalho Chehab * Optionally defined in: LLD 855ce5c5d65SMauro Carvalho Chehab **/ 856ce5c5d65SMauro Carvalho Chehab int ioctl(struct scsi_device *sdp, int cmd, void *arg) 857ce5c5d65SMauro Carvalho Chehab 858ce5c5d65SMauro Carvalho Chehab 859ce5c5d65SMauro Carvalho Chehab /** 860ce5c5d65SMauro Carvalho Chehab * proc_info - supports /proc/scsi/{driver_name}/{host_no} 861ce5c5d65SMauro Carvalho Chehab * @buffer: anchor point to output to (0==writeto1_read0) or fetch from 862ce5c5d65SMauro Carvalho Chehab * (1==writeto1_read0). 863ce5c5d65SMauro Carvalho Chehab * @start: where "interesting" data is written to. Ignored when 864ce5c5d65SMauro Carvalho Chehab * 1==writeto1_read0. 865ce5c5d65SMauro Carvalho Chehab * @offset: offset within buffer 0==writeto1_read0 is actually 866ce5c5d65SMauro Carvalho Chehab * interested in. Ignored when 1==writeto1_read0 . 867ce5c5d65SMauro Carvalho Chehab * @length: maximum (or actual) extent of buffer 868ce5c5d65SMauro Carvalho Chehab * @host_no: host number of interest (struct Scsi_Host::host_no) 869ce5c5d65SMauro Carvalho Chehab * @writeto1_read0: 1 -> data coming from user space towards driver 870ce5c5d65SMauro Carvalho Chehab * (e.g. "echo some_string > /proc/scsi/xyz/2") 871ce5c5d65SMauro Carvalho Chehab * 0 -> user what data from this driver 872ce5c5d65SMauro Carvalho Chehab * (e.g. "cat /proc/scsi/xyz/2") 873ce5c5d65SMauro Carvalho Chehab * 874ce5c5d65SMauro Carvalho Chehab * Returns length when 1==writeto1_read0. Otherwise number of chars 875ce5c5d65SMauro Carvalho Chehab * output to buffer past offset. 876ce5c5d65SMauro Carvalho Chehab * 877ce5c5d65SMauro Carvalho Chehab * Locks: none held 878ce5c5d65SMauro Carvalho Chehab * 879ce5c5d65SMauro Carvalho Chehab * Calling context: process 880ce5c5d65SMauro Carvalho Chehab * 881ce5c5d65SMauro Carvalho Chehab * Notes: Driven from scsi_proc.c which interfaces to proc_fs. proc_fs 882ce5c5d65SMauro Carvalho Chehab * support can now be configured out of the scsi subsystem. 883ce5c5d65SMauro Carvalho Chehab * 884ce5c5d65SMauro Carvalho Chehab * Optionally defined in: LLD 885ce5c5d65SMauro Carvalho Chehab **/ 886ce5c5d65SMauro Carvalho Chehab int proc_info(char * buffer, char ** start, off_t offset, 887ce5c5d65SMauro Carvalho Chehab int length, int host_no, int writeto1_read0) 888ce5c5d65SMauro Carvalho Chehab 889ce5c5d65SMauro Carvalho Chehab 890ce5c5d65SMauro Carvalho Chehab /** 891ce5c5d65SMauro Carvalho Chehab * queuecommand - queue scsi command, invoke scp->scsi_done on completion 892ce5c5d65SMauro Carvalho Chehab * @shost: pointer to the scsi host object 893ce5c5d65SMauro Carvalho Chehab * @scp: pointer to scsi command object 894ce5c5d65SMauro Carvalho Chehab * 895ce5c5d65SMauro Carvalho Chehab * Returns 0 on success. 896ce5c5d65SMauro Carvalho Chehab * 897ce5c5d65SMauro Carvalho Chehab * If there's a failure, return either: 898ce5c5d65SMauro Carvalho Chehab * 899ce5c5d65SMauro Carvalho Chehab * SCSI_MLQUEUE_DEVICE_BUSY if the device queue is full, or 900ce5c5d65SMauro Carvalho Chehab * SCSI_MLQUEUE_HOST_BUSY if the entire host queue is full 901ce5c5d65SMauro Carvalho Chehab * 902ce5c5d65SMauro Carvalho Chehab * On both of these returns, the mid-layer will requeue the I/O 903ce5c5d65SMauro Carvalho Chehab * 904ce5c5d65SMauro Carvalho Chehab * - if the return is SCSI_MLQUEUE_DEVICE_BUSY, only that particular 905ce5c5d65SMauro Carvalho Chehab * device will be paused, and it will be unpaused when a command to 906ce5c5d65SMauro Carvalho Chehab * the device returns (or after a brief delay if there are no more 907ce5c5d65SMauro Carvalho Chehab * outstanding commands to it). Commands to other devices continue 908ce5c5d65SMauro Carvalho Chehab * to be processed normally. 909ce5c5d65SMauro Carvalho Chehab * 910ce5c5d65SMauro Carvalho Chehab * - if the return is SCSI_MLQUEUE_HOST_BUSY, all I/O to the host 911ce5c5d65SMauro Carvalho Chehab * is paused and will be unpaused when any command returns from 912ce5c5d65SMauro Carvalho Chehab * the host (or after a brief delay if there are no outstanding 913ce5c5d65SMauro Carvalho Chehab * commands to the host). 914ce5c5d65SMauro Carvalho Chehab * 915ce5c5d65SMauro Carvalho Chehab * For compatibility with earlier versions of queuecommand, any 916ce5c5d65SMauro Carvalho Chehab * other return value is treated the same as 917ce5c5d65SMauro Carvalho Chehab * SCSI_MLQUEUE_HOST_BUSY. 918ce5c5d65SMauro Carvalho Chehab * 919ce5c5d65SMauro Carvalho Chehab * Other types of errors that are detected immediately may be 920ce5c5d65SMauro Carvalho Chehab * flagged by setting scp->result to an appropriate value, 921ce5c5d65SMauro Carvalho Chehab * invoking the scp->scsi_done callback, and then returning 0 922ce5c5d65SMauro Carvalho Chehab * from this function. If the command is not performed 923ce5c5d65SMauro Carvalho Chehab * immediately (and the LLD is starting (or will start) the given 924ce5c5d65SMauro Carvalho Chehab * command) then this function should place 0 in scp->result and 925ce5c5d65SMauro Carvalho Chehab * return 0. 926ce5c5d65SMauro Carvalho Chehab * 927ce5c5d65SMauro Carvalho Chehab * Command ownership. If the driver returns zero, it owns the 928ce5c5d65SMauro Carvalho Chehab * command and must take responsibility for ensuring the 929ce5c5d65SMauro Carvalho Chehab * scp->scsi_done callback is executed. Note: the driver may 930ce5c5d65SMauro Carvalho Chehab * call scp->scsi_done before returning zero, but after it has 931ce5c5d65SMauro Carvalho Chehab * called scp->scsi_done, it may not return any value other than 932ce5c5d65SMauro Carvalho Chehab * zero. If the driver makes a non-zero return, it must not 933ce5c5d65SMauro Carvalho Chehab * execute the command's scsi_done callback at any time. 934ce5c5d65SMauro Carvalho Chehab * 935ce5c5d65SMauro Carvalho Chehab * Locks: up to and including 2.6.36, struct Scsi_Host::host_lock 936ce5c5d65SMauro Carvalho Chehab * held on entry (with "irqsave") and is expected to be 937ce5c5d65SMauro Carvalho Chehab * held on return. From 2.6.37 onwards, queuecommand is 938ce5c5d65SMauro Carvalho Chehab * called without any locks held. 939ce5c5d65SMauro Carvalho Chehab * 940ce5c5d65SMauro Carvalho Chehab * Calling context: in interrupt (soft irq) or process context 941ce5c5d65SMauro Carvalho Chehab * 942ce5c5d65SMauro Carvalho Chehab * Notes: This function should be relatively fast. Normally it 943ce5c5d65SMauro Carvalho Chehab * will not wait for IO to complete. Hence the scp->scsi_done 944ce5c5d65SMauro Carvalho Chehab * callback is invoked (often directly from an interrupt service 945ce5c5d65SMauro Carvalho Chehab * routine) some time after this function has returned. In some 946ce5c5d65SMauro Carvalho Chehab * cases (e.g. pseudo adapter drivers that manufacture the 947ce5c5d65SMauro Carvalho Chehab * response to a SCSI INQUIRY) the scp->scsi_done callback may be 948ce5c5d65SMauro Carvalho Chehab * invoked before this function returns. If the scp->scsi_done 949ce5c5d65SMauro Carvalho Chehab * callback is not invoked within a certain period the SCSI mid 950ce5c5d65SMauro Carvalho Chehab * level will commence error processing. If a status of CHECK 951ce5c5d65SMauro Carvalho Chehab * CONDITION is placed in "result" when the scp->scsi_done 952ce5c5d65SMauro Carvalho Chehab * callback is invoked, then the LLD driver should perform 953ce5c5d65SMauro Carvalho Chehab * autosense and fill in the struct scsi_cmnd::sense_buffer 954ce5c5d65SMauro Carvalho Chehab * array. The scsi_cmnd::sense_buffer array is zeroed prior to 955ce5c5d65SMauro Carvalho Chehab * the mid level queuing a command to an LLD. 956ce5c5d65SMauro Carvalho Chehab * 957ce5c5d65SMauro Carvalho Chehab * Defined in: LLD 958ce5c5d65SMauro Carvalho Chehab **/ 959ce5c5d65SMauro Carvalho Chehab int queuecommand(struct Scsi_Host *shost, struct scsi_cmnd * scp) 960ce5c5d65SMauro Carvalho Chehab 961ce5c5d65SMauro Carvalho Chehab 962ce5c5d65SMauro Carvalho Chehab /** 963ce5c5d65SMauro Carvalho Chehab * slave_alloc - prior to any commands being sent to a new device 964ce5c5d65SMauro Carvalho Chehab * (i.e. just prior to scan) this call is made 965ce5c5d65SMauro Carvalho Chehab * @sdp: pointer to new device (about to be scanned) 966ce5c5d65SMauro Carvalho Chehab * 967ce5c5d65SMauro Carvalho Chehab * Returns 0 if ok. Any other return is assumed to be an error and 968ce5c5d65SMauro Carvalho Chehab * the device is ignored. 969ce5c5d65SMauro Carvalho Chehab * 970ce5c5d65SMauro Carvalho Chehab * Locks: none 971ce5c5d65SMauro Carvalho Chehab * 972ce5c5d65SMauro Carvalho Chehab * Calling context: process 973ce5c5d65SMauro Carvalho Chehab * 974ce5c5d65SMauro Carvalho Chehab * Notes: Allows the driver to allocate any resources for a device 975ce5c5d65SMauro Carvalho Chehab * prior to its initial scan. The corresponding scsi device may not 976ce5c5d65SMauro Carvalho Chehab * exist but the mid level is just about to scan for it (i.e. send 977ce5c5d65SMauro Carvalho Chehab * and INQUIRY command plus ...). If a device is found then 978ce5c5d65SMauro Carvalho Chehab * slave_configure() will be called while if a device is not found 979ce5c5d65SMauro Carvalho Chehab * slave_destroy() is called. 980ce5c5d65SMauro Carvalho Chehab * For more details see the include/scsi/scsi_host.h file. 981ce5c5d65SMauro Carvalho Chehab * 982ce5c5d65SMauro Carvalho Chehab * Optionally defined in: LLD 983ce5c5d65SMauro Carvalho Chehab **/ 984ce5c5d65SMauro Carvalho Chehab int slave_alloc(struct scsi_device *sdp) 985ce5c5d65SMauro Carvalho Chehab 986ce5c5d65SMauro Carvalho Chehab 987ce5c5d65SMauro Carvalho Chehab /** 988ce5c5d65SMauro Carvalho Chehab * slave_configure - driver fine tuning for given device just after it 989ce5c5d65SMauro Carvalho Chehab * has been first scanned (i.e. it responded to an 990ce5c5d65SMauro Carvalho Chehab * INQUIRY) 991ce5c5d65SMauro Carvalho Chehab * @sdp: device that has just been attached 992ce5c5d65SMauro Carvalho Chehab * 993ce5c5d65SMauro Carvalho Chehab * Returns 0 if ok. Any other return is assumed to be an error and 994ce5c5d65SMauro Carvalho Chehab * the device is taken offline. [offline devices will _not_ have 995ce5c5d65SMauro Carvalho Chehab * slave_destroy() called on them so clean up resources.] 996ce5c5d65SMauro Carvalho Chehab * 997ce5c5d65SMauro Carvalho Chehab * Locks: none 998ce5c5d65SMauro Carvalho Chehab * 999ce5c5d65SMauro Carvalho Chehab * Calling context: process 1000ce5c5d65SMauro Carvalho Chehab * 1001ce5c5d65SMauro Carvalho Chehab * Notes: Allows the driver to inspect the response to the initial 1002ce5c5d65SMauro Carvalho Chehab * INQUIRY done by the scanning code and take appropriate action. 1003ce5c5d65SMauro Carvalho Chehab * For more details see the include/scsi/scsi_host.h file. 1004ce5c5d65SMauro Carvalho Chehab * 1005ce5c5d65SMauro Carvalho Chehab * Optionally defined in: LLD 1006ce5c5d65SMauro Carvalho Chehab **/ 1007ce5c5d65SMauro Carvalho Chehab int slave_configure(struct scsi_device *sdp) 1008ce5c5d65SMauro Carvalho Chehab 1009ce5c5d65SMauro Carvalho Chehab 1010ce5c5d65SMauro Carvalho Chehab /** 1011ce5c5d65SMauro Carvalho Chehab * slave_destroy - given device is about to be shut down. All 1012ce5c5d65SMauro Carvalho Chehab * activity has ceased on this device. 1013ce5c5d65SMauro Carvalho Chehab * @sdp: device that is about to be shut down 1014ce5c5d65SMauro Carvalho Chehab * 1015ce5c5d65SMauro Carvalho Chehab * Returns nothing 1016ce5c5d65SMauro Carvalho Chehab * 1017ce5c5d65SMauro Carvalho Chehab * Locks: none 1018ce5c5d65SMauro Carvalho Chehab * 1019ce5c5d65SMauro Carvalho Chehab * Calling context: process 1020ce5c5d65SMauro Carvalho Chehab * 1021ce5c5d65SMauro Carvalho Chehab * Notes: Mid level structures for given device are still in place 1022ce5c5d65SMauro Carvalho Chehab * but are about to be torn down. Any per device resources allocated 1023ce5c5d65SMauro Carvalho Chehab * by this driver for given device should be freed now. No further 1024ce5c5d65SMauro Carvalho Chehab * commands will be sent for this sdp instance. [However the device 1025ce5c5d65SMauro Carvalho Chehab * could be re-attached in the future in which case a new instance 1026ce5c5d65SMauro Carvalho Chehab * of struct scsi_device would be supplied by future slave_alloc() 1027ce5c5d65SMauro Carvalho Chehab * and slave_configure() calls.] 1028ce5c5d65SMauro Carvalho Chehab * 1029ce5c5d65SMauro Carvalho Chehab * Optionally defined in: LLD 1030ce5c5d65SMauro Carvalho Chehab **/ 1031ce5c5d65SMauro Carvalho Chehab void slave_destroy(struct scsi_device *sdp) 1032ce5c5d65SMauro Carvalho Chehab 1033ce5c5d65SMauro Carvalho Chehab 1034ce5c5d65SMauro Carvalho Chehab 1035ce5c5d65SMauro Carvalho ChehabData Structures 1036ce5c5d65SMauro Carvalho Chehab=============== 1037ce5c5d65SMauro Carvalho Chehabstruct scsi_host_template 1038ce5c5d65SMauro Carvalho Chehab------------------------- 1039ce5c5d65SMauro Carvalho ChehabThere is one "struct scsi_host_template" instance per LLD [#]_. It is 1040ce5c5d65SMauro Carvalho Chehabtypically initialized as a file scope static in a driver's header file. That 1041ce5c5d65SMauro Carvalho Chehabway members that are not explicitly initialized will be set to 0 or NULL. 1042ce5c5d65SMauro Carvalho ChehabMember of interest: 1043ce5c5d65SMauro Carvalho Chehab 1044ce5c5d65SMauro Carvalho Chehab name 1045ce5c5d65SMauro Carvalho Chehab - name of driver (may contain spaces, please limit to 1046ce5c5d65SMauro Carvalho Chehab less than 80 characters) 1047ce5c5d65SMauro Carvalho Chehab 1048ce5c5d65SMauro Carvalho Chehab proc_name 1049ce5c5d65SMauro Carvalho Chehab - name used in "/proc/scsi/<proc_name>/<host_no>" and 1050ce5c5d65SMauro Carvalho Chehab by sysfs in one of its "drivers" directories. Hence 1051ce5c5d65SMauro Carvalho Chehab "proc_name" should only contain characters acceptable 1052ce5c5d65SMauro Carvalho Chehab to a Unix file name. 1053ce5c5d65SMauro Carvalho Chehab 1054ce5c5d65SMauro Carvalho Chehab ``(*queuecommand)()`` 1055ce5c5d65SMauro Carvalho Chehab - primary callback that the mid level uses to inject 1056ce5c5d65SMauro Carvalho Chehab SCSI commands into an LLD. 1057ce5c5d65SMauro Carvalho Chehab 1058ce5c5d65SMauro Carvalho ChehabThe structure is defined and commented in include/scsi/scsi_host.h 1059ce5c5d65SMauro Carvalho Chehab 1060ce5c5d65SMauro Carvalho Chehab.. [#] In extreme situations a single driver may have several instances 1061ce5c5d65SMauro Carvalho Chehab if it controls several different classes of hardware (e.g. an LLD 1062ce5c5d65SMauro Carvalho Chehab that handles both ISA and PCI cards and has a separate instance of 1063ce5c5d65SMauro Carvalho Chehab struct scsi_host_template for each class). 1064ce5c5d65SMauro Carvalho Chehab 1065ce5c5d65SMauro Carvalho Chehabstruct Scsi_Host 1066ce5c5d65SMauro Carvalho Chehab---------------- 1067ce5c5d65SMauro Carvalho ChehabThere is one struct Scsi_Host instance per host (HBA) that an LLD 1068ce5c5d65SMauro Carvalho Chehabcontrols. The struct Scsi_Host structure has many members in common 1069ce5c5d65SMauro Carvalho Chehabwith "struct scsi_host_template". When a new struct Scsi_Host instance 1070ce5c5d65SMauro Carvalho Chehabis created (in scsi_host_alloc() in hosts.c) those common members are 1071ce5c5d65SMauro Carvalho Chehabinitialized from the driver's struct scsi_host_template instance. Members 1072ce5c5d65SMauro Carvalho Chehabof interest: 1073ce5c5d65SMauro Carvalho Chehab 1074ce5c5d65SMauro Carvalho Chehab host_no 1075ce5c5d65SMauro Carvalho Chehab - system wide unique number that is used for identifying 1076ce5c5d65SMauro Carvalho Chehab this host. Issued in ascending order from 0. 1077ce5c5d65SMauro Carvalho Chehab can_queue 1078ce5c5d65SMauro Carvalho Chehab - must be greater than 0; do not send more than can_queue 1079ce5c5d65SMauro Carvalho Chehab commands to the adapter. 1080ce5c5d65SMauro Carvalho Chehab this_id 1081ce5c5d65SMauro Carvalho Chehab - scsi id of host (scsi initiator) or -1 if not known 1082ce5c5d65SMauro Carvalho Chehab sg_tablesize 1083ce5c5d65SMauro Carvalho Chehab - maximum scatter gather elements allowed by host. 1084ce5c5d65SMauro Carvalho Chehab Set this to SG_ALL or less to avoid chained SG lists. 1085ce5c5d65SMauro Carvalho Chehab Must be at least 1. 1086ce5c5d65SMauro Carvalho Chehab max_sectors 1087ce5c5d65SMauro Carvalho Chehab - maximum number of sectors (usually 512 bytes) allowed 1088ce5c5d65SMauro Carvalho Chehab in a single SCSI command. The default value of 0 leads 1089ce5c5d65SMauro Carvalho Chehab to a setting of SCSI_DEFAULT_MAX_SECTORS (defined in 1090ce5c5d65SMauro Carvalho Chehab scsi_host.h) which is currently set to 1024. So for a 1091ce5c5d65SMauro Carvalho Chehab disk the maximum transfer size is 512 KB when max_sectors 1092ce5c5d65SMauro Carvalho Chehab is not defined. Note that this size may not be sufficient 1093ce5c5d65SMauro Carvalho Chehab for disk firmware uploads. 1094ce5c5d65SMauro Carvalho Chehab cmd_per_lun 1095ce5c5d65SMauro Carvalho Chehab - maximum number of commands that can be queued on devices 1096ce5c5d65SMauro Carvalho Chehab controlled by the host. Overridden by LLD calls to 1097ce5c5d65SMauro Carvalho Chehab scsi_change_queue_depth(). 1098ce5c5d65SMauro Carvalho Chehab no_async_abort 1099ce5c5d65SMauro Carvalho Chehab - 1=>Asynchronous aborts are not supported 1100ce5c5d65SMauro Carvalho Chehab - 0=>Timed-out commands will be aborted asynchronously 1101ce5c5d65SMauro Carvalho Chehab hostt 1102ce5c5d65SMauro Carvalho Chehab - pointer to driver's struct scsi_host_template from which 1103ce5c5d65SMauro Carvalho Chehab this struct Scsi_Host instance was spawned 1104ce5c5d65SMauro Carvalho Chehab hostt->proc_name 1105ce5c5d65SMauro Carvalho Chehab - name of LLD. This is the driver name that sysfs uses 1106ce5c5d65SMauro Carvalho Chehab transportt 1107ce5c5d65SMauro Carvalho Chehab - pointer to driver's struct scsi_transport_template instance 1108ce5c5d65SMauro Carvalho Chehab (if any). FC and SPI transports currently supported. 1109ce5c5d65SMauro Carvalho Chehab sh_list 1110ce5c5d65SMauro Carvalho Chehab - a double linked list of pointers to all struct Scsi_Host 1111ce5c5d65SMauro Carvalho Chehab instances (currently ordered by ascending host_no) 1112ce5c5d65SMauro Carvalho Chehab my_devices 1113ce5c5d65SMauro Carvalho Chehab - a double linked list of pointers to struct scsi_device 1114ce5c5d65SMauro Carvalho Chehab instances that belong to this host. 1115ce5c5d65SMauro Carvalho Chehab hostdata[0] 1116ce5c5d65SMauro Carvalho Chehab - area reserved for LLD at end of struct Scsi_Host. Size 1117ce5c5d65SMauro Carvalho Chehab is set by the second argument (named 'xtr_bytes') to 1118ce5c5d65SMauro Carvalho Chehab scsi_host_alloc() or scsi_register(). 1119ce5c5d65SMauro Carvalho Chehab vendor_id 1120ce5c5d65SMauro Carvalho Chehab - a unique value that identifies the vendor supplying 1121ce5c5d65SMauro Carvalho Chehab the LLD for the Scsi_Host. Used most often in validating 1122ce5c5d65SMauro Carvalho Chehab vendor-specific message requests. Value consists of an 1123ce5c5d65SMauro Carvalho Chehab identifier type and a vendor-specific value. 1124ce5c5d65SMauro Carvalho Chehab See scsi_netlink.h for a description of valid formats. 1125ce5c5d65SMauro Carvalho Chehab 1126ce5c5d65SMauro Carvalho ChehabThe scsi_host structure is defined in include/scsi/scsi_host.h 1127ce5c5d65SMauro Carvalho Chehab 1128ce5c5d65SMauro Carvalho Chehabstruct scsi_device 1129ce5c5d65SMauro Carvalho Chehab------------------ 1130ce5c5d65SMauro Carvalho ChehabGenerally, there is one instance of this structure for each SCSI logical unit 1131ce5c5d65SMauro Carvalho Chehabon a host. Scsi devices connected to a host are uniquely identified by a 1132ce5c5d65SMauro Carvalho Chehabchannel number, target id and logical unit number (lun). 1133ce5c5d65SMauro Carvalho ChehabThe structure is defined in include/scsi/scsi_device.h 1134ce5c5d65SMauro Carvalho Chehab 1135ce5c5d65SMauro Carvalho Chehabstruct scsi_cmnd 1136ce5c5d65SMauro Carvalho Chehab---------------- 1137ce5c5d65SMauro Carvalho ChehabInstances of this structure convey SCSI commands to the LLD and responses 1138ce5c5d65SMauro Carvalho Chehabback to the mid level. The SCSI mid level will ensure that no more SCSI 1139ce5c5d65SMauro Carvalho Chehabcommands become queued against the LLD than are indicated by 1140ce5c5d65SMauro Carvalho Chehabscsi_change_queue_depth() (or struct Scsi_Host::cmd_per_lun). There will 1141ce5c5d65SMauro Carvalho Chehabbe at least one instance of struct scsi_cmnd available for each SCSI device. 1142ce5c5d65SMauro Carvalho ChehabMembers of interest: 1143ce5c5d65SMauro Carvalho Chehab 1144ce5c5d65SMauro Carvalho Chehab cmnd 1145ce5c5d65SMauro Carvalho Chehab - array containing SCSI command 1146ce5c5d65SMauro Carvalho Chehab cmnd_len 1147ce5c5d65SMauro Carvalho Chehab - length (in bytes) of SCSI command 1148ce5c5d65SMauro Carvalho Chehab sc_data_direction 1149ce5c5d65SMauro Carvalho Chehab - direction of data transfer in data phase. See 1150ce5c5d65SMauro Carvalho Chehab "enum dma_data_direction" in include/linux/dma-mapping.h 1151ce5c5d65SMauro Carvalho Chehab request_bufflen 1152ce5c5d65SMauro Carvalho Chehab - number of data bytes to transfer (0 if no data phase) 1153ce5c5d65SMauro Carvalho Chehab use_sg 1154ce5c5d65SMauro Carvalho Chehab - ==0 -> no scatter gather list, hence transfer data 1155ce5c5d65SMauro Carvalho Chehab to/from request_buffer 1156ce5c5d65SMauro Carvalho Chehab - >0 -> scatter gather list (actually an array) in 1157ce5c5d65SMauro Carvalho Chehab request_buffer with use_sg elements 1158ce5c5d65SMauro Carvalho Chehab request_buffer 1159ce5c5d65SMauro Carvalho Chehab - either contains data buffer or scatter gather list 1160ce5c5d65SMauro Carvalho Chehab depending on the setting of use_sg. Scatter gather 1161ce5c5d65SMauro Carvalho Chehab elements are defined by 'struct scatterlist' found 1162ce5c5d65SMauro Carvalho Chehab in include/linux/scatterlist.h . 1163ce5c5d65SMauro Carvalho Chehab done 1164ce5c5d65SMauro Carvalho Chehab - function pointer that should be invoked by LLD when the 1165ce5c5d65SMauro Carvalho Chehab SCSI command is completed (successfully or otherwise). 1166ce5c5d65SMauro Carvalho Chehab Should only be called by an LLD if the LLD has accepted 1167ce5c5d65SMauro Carvalho Chehab the command (i.e. queuecommand() returned or will return 1168ce5c5d65SMauro Carvalho Chehab 0). The LLD may invoke 'done' prior to queuecommand() 1169ce5c5d65SMauro Carvalho Chehab finishing. 1170ce5c5d65SMauro Carvalho Chehab result 1171ce5c5d65SMauro Carvalho Chehab - should be set by LLD prior to calling 'done'. A value 1172ce5c5d65SMauro Carvalho Chehab of 0 implies a successfully completed command (and all 1173ce5c5d65SMauro Carvalho Chehab data (if any) has been transferred to or from the SCSI 1174ce5c5d65SMauro Carvalho Chehab target device). 'result' is a 32 bit unsigned integer that 1175a7479a84SHannes Reinecke can be viewed as 2 related bytes. The SCSI status value is 1176a7479a84SHannes Reinecke in the LSB. See include/scsi/scsi.h status_byte() and 1177a7479a84SHannes Reinecke host_byte() macros and related constants. 1178ce5c5d65SMauro Carvalho Chehab sense_buffer 1179ce5c5d65SMauro Carvalho Chehab - an array (maximum size: SCSI_SENSE_BUFFERSIZE bytes) that 1180ce5c5d65SMauro Carvalho Chehab should be written when the SCSI status (LSB of 'result') 1181ce5c5d65SMauro Carvalho Chehab is set to CHECK_CONDITION (2). When CHECK_CONDITION is 1182ce5c5d65SMauro Carvalho Chehab set, if the top nibble of sense_buffer[0] has the value 7 1183ce5c5d65SMauro Carvalho Chehab then the mid level will assume the sense_buffer array 1184ce5c5d65SMauro Carvalho Chehab contains a valid SCSI sense buffer; otherwise the mid 1185ce5c5d65SMauro Carvalho Chehab level will issue a REQUEST_SENSE SCSI command to 1186ce5c5d65SMauro Carvalho Chehab retrieve the sense buffer. The latter strategy is error 1187ce5c5d65SMauro Carvalho Chehab prone in the presence of command queuing so the LLD should 1188ce5c5d65SMauro Carvalho Chehab always "auto-sense". 1189ce5c5d65SMauro Carvalho Chehab device 1190ce5c5d65SMauro Carvalho Chehab - pointer to scsi_device object that this command is 1191ce5c5d65SMauro Carvalho Chehab associated with. 1192ce5c5d65SMauro Carvalho Chehab resid 1193f669b8a6SBart Van Assche - an LLD should set this unsigned integer to the requested 1194ce5c5d65SMauro Carvalho Chehab transfer length (i.e. 'request_bufflen') less the number 1195ce5c5d65SMauro Carvalho Chehab of bytes that are actually transferred. 'resid' is 1196ce5c5d65SMauro Carvalho Chehab preset to 0 so an LLD can ignore it if it cannot detect 1197f669b8a6SBart Van Assche underruns (overruns should not be reported). An LLD 1198ce5c5d65SMauro Carvalho Chehab should set 'resid' prior to invoking 'done'. The most 1199ce5c5d65SMauro Carvalho Chehab interesting case is data transfers from a SCSI target 1200ce5c5d65SMauro Carvalho Chehab device (e.g. READs) that underrun. 1201ce5c5d65SMauro Carvalho Chehab underflow 1202ce5c5d65SMauro Carvalho Chehab - LLD should place (DID_ERROR << 16) in 'result' if 1203ce5c5d65SMauro Carvalho Chehab actual number of bytes transferred is less than this 1204ce5c5d65SMauro Carvalho Chehab figure. Not many LLDs implement this check and some that 1205ce5c5d65SMauro Carvalho Chehab do just output an error message to the log rather than 1206ce5c5d65SMauro Carvalho Chehab report a DID_ERROR. Better for an LLD to implement 1207ce5c5d65SMauro Carvalho Chehab 'resid'. 1208ce5c5d65SMauro Carvalho Chehab 1209ce5c5d65SMauro Carvalho ChehabIt is recommended that a LLD set 'resid' on data transfers from a SCSI 1210ce5c5d65SMauro Carvalho Chehabtarget device (e.g. READs). It is especially important that 'resid' is set 1211ce5c5d65SMauro Carvalho Chehabwhen such data transfers have sense keys of MEDIUM ERROR and HARDWARE ERROR 1212ce5c5d65SMauro Carvalho Chehab(and possibly RECOVERED ERROR). In these cases if a LLD is in doubt how much 1213ce5c5d65SMauro Carvalho Chehabdata has been received then the safest approach is to indicate no bytes have 1214ce5c5d65SMauro Carvalho Chehabbeen received. For example: to indicate that no valid data has been received 1215ce5c5d65SMauro Carvalho Chehaba LLD might use these helpers:: 1216ce5c5d65SMauro Carvalho Chehab 1217ce5c5d65SMauro Carvalho Chehab scsi_set_resid(SCpnt, scsi_bufflen(SCpnt)); 1218ce5c5d65SMauro Carvalho Chehab 1219ce5c5d65SMauro Carvalho Chehabwhere 'SCpnt' is a pointer to a scsi_cmnd object. To indicate only three 512 1220ce5c5d65SMauro Carvalho Chehabbytes blocks has been received 'resid' could be set like this:: 1221ce5c5d65SMauro Carvalho Chehab 1222ce5c5d65SMauro Carvalho Chehab scsi_set_resid(SCpnt, scsi_bufflen(SCpnt) - (3 * 512)); 1223ce5c5d65SMauro Carvalho Chehab 1224ce5c5d65SMauro Carvalho ChehabThe scsi_cmnd structure is defined in include/scsi/scsi_cmnd.h 1225ce5c5d65SMauro Carvalho Chehab 1226ce5c5d65SMauro Carvalho Chehab 1227ce5c5d65SMauro Carvalho ChehabLocks 1228ce5c5d65SMauro Carvalho Chehab===== 1229ce5c5d65SMauro Carvalho ChehabEach struct Scsi_Host instance has a spin_lock called struct 1230ce5c5d65SMauro Carvalho ChehabScsi_Host::default_lock which is initialized in scsi_host_alloc() [found in 1231ce5c5d65SMauro Carvalho Chehabhosts.c]. Within the same function the struct Scsi_Host::host_lock pointer 1232ce5c5d65SMauro Carvalho Chehabis initialized to point at default_lock. Thereafter lock and unlock 1233ce5c5d65SMauro Carvalho Chehaboperations performed by the mid level use the struct Scsi_Host::host_lock 1234ce5c5d65SMauro Carvalho Chehabpointer. Previously drivers could override the host_lock pointer but 1235ce5c5d65SMauro Carvalho Chehabthis is not allowed anymore. 1236ce5c5d65SMauro Carvalho Chehab 1237ce5c5d65SMauro Carvalho Chehab 1238ce5c5d65SMauro Carvalho ChehabAutosense 1239ce5c5d65SMauro Carvalho Chehab========= 1240ce5c5d65SMauro Carvalho ChehabAutosense (or auto-sense) is defined in the SAM-2 document as "the 1241ce5c5d65SMauro Carvalho Chehabautomatic return of sense data to the application client coincident 1242ce5c5d65SMauro Carvalho Chehabwith the completion of a SCSI command" when a status of CHECK CONDITION 1243ce5c5d65SMauro Carvalho Chehaboccurs. LLDs should perform autosense. This should be done when the LLD 1244ce5c5d65SMauro Carvalho Chehabdetects a CHECK CONDITION status by either: 1245ce5c5d65SMauro Carvalho Chehab 1246ce5c5d65SMauro Carvalho Chehab a) instructing the SCSI protocol (e.g. SCSI Parallel Interface (SPI)) 1247ce5c5d65SMauro Carvalho Chehab to perform an extra data in phase on such responses 1248ce5c5d65SMauro Carvalho Chehab b) or, the LLD issuing a REQUEST SENSE command itself 1249ce5c5d65SMauro Carvalho Chehab 1250ce5c5d65SMauro Carvalho ChehabEither way, when a status of CHECK CONDITION is detected, the mid level 1251ce5c5d65SMauro Carvalho Chehabdecides whether the LLD has performed autosense by checking struct 1252ce5c5d65SMauro Carvalho Chehabscsi_cmnd::sense_buffer[0] . If this byte has an upper nibble of 7 (or 0xf) 1253ce5c5d65SMauro Carvalho Chehabthen autosense is assumed to have taken place. If it has another value (and 1254ce5c5d65SMauro Carvalho Chehabthis byte is initialized to 0 before each command) then the mid level will 1255ce5c5d65SMauro Carvalho Chehabissue a REQUEST SENSE command. 1256ce5c5d65SMauro Carvalho Chehab 1257ce5c5d65SMauro Carvalho ChehabIn the presence of queued commands the "nexus" that maintains sense 1258ce5c5d65SMauro Carvalho Chehabbuffer data from the command that failed until a following REQUEST SENSE 1259ce5c5d65SMauro Carvalho Chehabmay get out of synchronization. This is why it is best for the LLD 1260ce5c5d65SMauro Carvalho Chehabto perform autosense. 1261ce5c5d65SMauro Carvalho Chehab 1262ce5c5d65SMauro Carvalho Chehab 1263ce5c5d65SMauro Carvalho ChehabChanges since lk 2.4 series 1264ce5c5d65SMauro Carvalho Chehab=========================== 1265ce5c5d65SMauro Carvalho Chehabio_request_lock has been replaced by several finer grained locks. The lock 1266ce5c5d65SMauro Carvalho Chehabrelevant to LLDs is struct Scsi_Host::host_lock and there is 1267ce5c5d65SMauro Carvalho Chehabone per SCSI host. 1268ce5c5d65SMauro Carvalho Chehab 1269ce5c5d65SMauro Carvalho ChehabThe older error handling mechanism has been removed. This means the 1270ce5c5d65SMauro Carvalho ChehabLLD interface functions abort() and reset() have been removed. 1271ce5c5d65SMauro Carvalho ChehabThe struct scsi_host_template::use_new_eh_code flag has been removed. 1272ce5c5d65SMauro Carvalho Chehab 1273ce5c5d65SMauro Carvalho ChehabIn the 2.4 series the SCSI subsystem configuration descriptions were 1274ce5c5d65SMauro Carvalho Chehabaggregated with the configuration descriptions from all other Linux 1275ce5c5d65SMauro Carvalho Chehabsubsystems in the Documentation/Configure.help file. In the 2.6 series, 1276ce5c5d65SMauro Carvalho Chehabthe SCSI subsystem now has its own (much smaller) drivers/scsi/Kconfig 1277ce5c5d65SMauro Carvalho Chehabfile that contains both configuration and help information. 1278ce5c5d65SMauro Carvalho Chehab 1279ce5c5d65SMauro Carvalho Chehabstruct SHT has been renamed to struct scsi_host_template. 1280ce5c5d65SMauro Carvalho Chehab 1281ce5c5d65SMauro Carvalho ChehabAddition of the "hotplug initialization model" and many extra functions 1282ce5c5d65SMauro Carvalho Chehabto support it. 1283ce5c5d65SMauro Carvalho Chehab 1284ce5c5d65SMauro Carvalho Chehab 1285ce5c5d65SMauro Carvalho ChehabCredits 1286ce5c5d65SMauro Carvalho Chehab======= 1287ce5c5d65SMauro Carvalho ChehabThe following people have contributed to this document: 1288ce5c5d65SMauro Carvalho Chehab 1289ce5c5d65SMauro Carvalho Chehab - Mike Anderson <andmike at us dot ibm dot com> 1290ce5c5d65SMauro Carvalho Chehab - James Bottomley <James dot Bottomley at hansenpartnership dot com> 1291ce5c5d65SMauro Carvalho Chehab - Patrick Mansfield <patmans at us dot ibm dot com> 1292ce5c5d65SMauro Carvalho Chehab - Christoph Hellwig <hch at infradead dot org> 1293ce5c5d65SMauro Carvalho Chehab - Doug Ledford <dledford at redhat dot com> 1294ce5c5d65SMauro Carvalho Chehab - Andries Brouwer <Andries dot Brouwer at cwi dot nl> 1295ce5c5d65SMauro Carvalho Chehab - Randy Dunlap <rdunlap at xenotime dot net> 1296ce5c5d65SMauro Carvalho Chehab - Alan Stern <stern at rowland dot harvard dot edu> 1297ce5c5d65SMauro Carvalho Chehab 1298ce5c5d65SMauro Carvalho Chehab 1299ce5c5d65SMauro Carvalho ChehabDouglas Gilbert 1300ce5c5d65SMauro Carvalho Chehabdgilbert at interlog dot com 1301ce5c5d65SMauro Carvalho Chehab 1302ce5c5d65SMauro Carvalho Chehab21st September 2004 1303