Documentation/scsi/scsi_mid_low_api.rst

4 SCSI mid_level - lower_level driver interface
9 This document outlines the interface between the Linux SCSI mid level and
10 SCSI lower level drivers. Lower level drivers (LLDs) are variously called
13 single SCSI initiator port on a SCSI transport. An "initiator" port
14 (SCSI terminology, see SAM-3 at http://www.t10.org) sends SCSI commands
15 to "target" SCSI ports (e.g. disks). There can be many LLDs in a running
17 SCSI HBAs. Some HBAs contain multiple hosts.
19 In some cases the SCSI transport is an external bus that already has
21 SCSI subsystem LLD is a software bridge to the other driver subsystem.
26 For example, the aic7xxx LLD controls Adaptec SCSI parallel interface
34 a SCSI host and a PCI device is common but not required (e.g. with
37 The SCSI mid level isolates an LLD from other layers such as the SCSI
44 There is a SCSI documentation directory within the kernel source tree,
49 Many LLDs are documented there (e.g. aic7xxx.txt). The SCSI mid-level is
51 describing the SCSI subsystem in the lk 2.4 series. Two upper level
52 drivers have documents in that directory: st.txt (SCSI tape driver) and
62 Traditionally an LLD for the SCSI subsystem has been at least two files in
83 preferred as it can handle both traditional SCSI equipment that is
84 permanently connected as well as modern "SCSI" devices (e.g. USB or
88 An LLD interfaces to the SCSI subsystem several ways:
125 In this model an LLD controls when SCSI hosts are introduced and removed
126 from the SCSI subsystem. Hosts can be introduced as early as driver
131 with the SCSI mid level.
137 registered with sysfs at this point. The SCSI mid level first becomes
145 	HBA PROBE: assume 2 SCSI devices found in scan
174 	    HBA REMOVE: assume 2 SCSI devices attached
188 Hot unplugging an HBA that controls a disk which is processing SCSI
194 The hotplug concept may be extended to SCSI devices. Currently, when an
195 HBA is added, the scsi_scan_host() function causes a scan for SCSI devices
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::
200 		    SCSI DEVICE hotplug
208 In a similar fashion, an LLD may become aware that a SCSI device has been
210 existing SCSI transports (e.g. SPI) may not become aware that a SCSI
211 device has been removed until a subsequent SCSI command fails which will
213 detects the removal of a SCSI device can instigate its removal from
216 		    SCSI DEVICE hot unplug
233 across the various SCSI layers which use them. Previously such instances
255 across the various SCSI layers which use them. Previously such instances
288 These functions are supplied by the SCSI mid level for use by LLDs.
291 arrange for the SCSI mid level to be loaded and initialized before any LLD
299   - scsi_change_queue_depth - change the queue depth on a SCSI device
306   - scsi_remove_device - detach and remove a SCSI device
307   - scsi_remove_host - detach and remove all SCSI devices owned by host
309   - scsi_scan_host - scan SCSI bus
366     * scsi_change_queue_depth - allow LLD to change queue depth on a SCSI device
367     * @sdev:       pointer to SCSI device to change queue depth on
376     *      Notes: Can be invoked any time on a SCSI device controlled by this
429     *      Notes: When this call returns to the LLD, the SCSI bus scan on
487     *      Notes: When this call returns to the LLD, the SCSI bus scan on
499     * scsi_remove_device - detach and remove a SCSI device
518     * scsi_remove_host - detach and remove all SCSI devices owned by host
555     * scsi_scan_host - scan SCSI bus
571     * @sdev:  pointer to SCSI device instance
572     * @depth: Current number of outstanding SCSI commands on this device,
653   - eh_bus_reset_handler - issue SCSI bus reset
654   - eh_device_reset_handler - issue SCSI device reset
743     *      eh_bus_reset_handler - issue SCSI bus reset
744     *      @scp: SCSI bus that contains this device should be reset
761     *      eh_device_reset_handler - issue SCSI device reset
762     *      @scp: identifies SCSI device to be reset
780     *      @scp: SCSI host that contains this device should be reset
846     *      Notes: The SCSI subsystem uses a "trickle down" ioctl model.
849     *      the 'cmd' then it is passed to the SCSI mid level. If the SCSI
947     *      response to a SCSI INQUIRY) the scp->scsi_done callback may be
949     *      callback is not invoked within a certain period the SCSI mid
1056                    SCSI commands into an LLD.
1088                    in a single SCSI command. The default value of 0 leads
1130 Generally, there is one instance of this structure for each SCSI logical unit
1137 Instances of this structure convey SCSI commands to the LLD and responses
1138 back to the mid level. The SCSI mid level will ensure that no more SCSI
1141 be at least one instance of struct scsi_cmnd available for each SCSI device.
1145 		 - array containing SCSI command
1147 		 - length (in bytes) of SCSI command
1165                    SCSI command is completed (successfully or otherwise).
1173                    data (if any) has been transferred to or from the SCSI
1175                    can be viewed as 2 related bytes. The SCSI status value is
1180                    should be written when the SCSI status (LSB of 'result')
1184                    contains a valid SCSI sense buffer; otherwise the mid
1185                    level will issue a REQUEST_SENSE SCSI command to
1199                    interesting case is data transfers from a SCSI target
1209 It is recommended that a LLD set 'resid' on data transfers from a SCSI
1242 with the completion of a SCSI command" when a status of CHECK CONDITION
1246     a) instructing the SCSI protocol (e.g. SCSI Parallel Interface (SPI))
1267 one per SCSI host.
1273 In the 2.4 series the SCSI subsystem configuration descriptions were
1276 the SCSI subsystem now has its own (much smaller) drivers/scsi/Kconfig