Lines Matching +full:subsystem +full:- +full:level
1 .. SPDX-License-Identifier: GPL-2.0
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
14 (SCSI terminology, see SAM-3 at http://www.t10.org) sends SCSI commands
20 its own subsystem in Linux (e.g. USB and ieee1394). In such cases the
21 SCSI subsystem LLD is a software bridge to the other driver subsystem.
22 Examples are the usb-storage driver (found in the drivers/usb/storage
30 HBAs. These HBAs might be either on PCI daughter-boards or built into
33 has its own PCI device address. [The one-to-one correspondence between
37 The SCSI mid level isolates an LLD from other layers such as the SCSI
49 documented in Documentation/scsi (e.g. aic7xxx.rst). The SCSI mid-level is
51 the SCSI subsystem in the Linux Kernel 2.4 series. Two upper level
53 scsi-generic.rst (for the sg driver).
62 Traditionally an LLD for the SCSI subsystem has been at least two files in
68 and OS-specific code (e.g. FreeBSD and Linux). Such drivers tend to have
88 An LLD interfaces to the SCSI subsystem several ways:
90 a) directly invoking functions supplied by the mid level
92 supplied by the mid level. The mid level will then invoke these
96 by the mid level
98 Those functions in group a) are listed in a section entitled "Mid level
112 that are shared with the mid level and other layers.
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
141 is a typical sequence of calls between the LLD and the mid level.
142 This example shows the mid level scanning the newly introduced HBA for 3
146 LLD mid level LLD
147 ===-------------------=========--------------------===------
148 scsi_host_alloc() -->
149 scsi_add_host() ---->
150 scsi_scan_host() -------+
153 slave_configure() --> scsi_change_queue_depth()
162 *** For scsi devices that the mid level tries to scan but do not
175 LLD mid level LLD
176 ===----------------------=========-----------------===------
177 scsi_remove_host() ---------+
185 by the mid-level. struct Scsi_Host instances are freed from
190 counting logic is being introduced into the mid level to cope with many
198 An LLD can use this sequence to make the mid level aware of a SCSI device::
201 LLD mid level LLD
202 ===-------------------=========--------------------===------
203 scsi_add_device() ------+
206 slave_configure() [--> scsi_change_queue_depth()]
212 probably cause that device to be set offline by the mid level. An LLD that
217 LLD mid level LLD
218 ===----------------------=========-----------------===------
219 scsi_remove_device() -------+
225 slave_configure() callbacks). Such instances are "owned" by the mid-level.
234 were exclusively owned by the mid level. LLDs would not usually need to
241 - scsi_host_alloc():
245 - scsi_host_get():
248 - scsi_host_put():
256 were exclusively owned by the mid level. See the access functions declared
272 Documentation/process/coding-style.rst file.
280 Well written, tested and documented code, need not be re-formatted to
286 Mid level supplied functions
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
297 - scsi_add_device - creates new scsi device (lu) instance
298 - scsi_add_host - perform sysfs registration and set up transport class
299 - scsi_change_queue_depth - change the queue depth on a SCSI device
300 - scsi_bios_ptable - return copy of block device's partition table
301 - scsi_block_requests - prevent further commands being queued to given host
302 - scsi_host_alloc - return a new scsi_host instance whose refcount==1
303 - scsi_host_get - increments Scsi_Host instance's refcount
304 - scsi_host_put - decrements Scsi_Host instance's refcount (free if 0)
305 - scsi_register - create and register a scsi host adapter instance.
306 - scsi_remove_device - detach and remove a SCSI device
307 - scsi_remove_host - detach and remove all SCSI devices owned by host
308 - scsi_report_bus_reset - report scsi _bus_ reset observed
309 - scsi_scan_host - scan SCSI bus
310 - scsi_track_queue_full - track successive QUEUE_FULL events
311 - scsi_unblock_requests - allow further commands to be queued to given host
312 - scsi_unregister - [calls scsi_host_put()]
318 * scsi_add_device - creates new scsi device (lu) instance
325 * ERR_PTR(-ENODEV) (or some other bent pointer) if something is
345 * scsi_add_host - perform sysfs registration and set up transport class
349 * Returns 0 on success, negative errno of failure (e.g. -ENOMEM)
356 * in some other transport-specific way. The LLD must set up
366 * scsi_change_queue_depth - allow LLD to change queue depth on a SCSI device
370 * in non-tagged mode (as per cmd_per_lun).
387 * scsi_bios_ptable - return copy of block device's partition table
402 * scsi_block_requests - prevent further commands being queued to given host
419 * scsi_host_alloc - create a scsi host adapter instance and perform basic
444 * scsi_host_get - increment Scsi_Host instance refcount
451 * Notes: Actually increments the counts in two sub-objects
459 * scsi_host_put - decrement Scsi_Host instance refcount, free if 0
466 * Notes: Actually decrements the counts in two sub-objects. If the
478 * scsi_register - create and register a scsi host adapter instance.
499 * scsi_remove_device - detach and remove a SCSI device
502 * Returns value: 0 on success, -EINVAL if device not attached
518 * scsi_remove_host - detach and remove all SCSI devices owned by host
535 * scsi_report_bus_reset - report scsi _bus_ reset observed
545 * mid level itself don't need to call this, but there should be
555 * scsi_scan_host - scan SCSI bus
568 * scsi_track_queue_full - track successive QUEUE_FULL events on given
575 * Returns 0 - no change needed
576 * >0 - adjust queue depth to this new depth
577 * -1 - drop back to untagged operation using host->cmd_per_lun
591 * scsi_unblock_requests - allow further commands to be queued to given host
605 * scsi_unregister - unregister and free memory used by host instance
639 should be passed to the mid level's scsi_host_alloc() [or scsi_register() /
650 - bios_param - fetch head, sector, cylinder info for a disk
651 - eh_timed_out - notify the host that a command timer expired
652 - eh_abort_handler - abort given command
653 - eh_bus_reset_handler - issue SCSI bus reset
654 - eh_device_reset_handler - issue SCSI device reset
655 - eh_host_reset_handler - reset host (host bus adapter)
656 - info - supply information about given host
657 - ioctl - driver can respond to ioctls
658 - proc_info - supports /proc/scsi/{driver_name}/{host_no}
659 - queuecommand - queue scsi command, invoke 'done' on completion
660 - slave_alloc - prior to any commands being sent to a new device
661 - slave_configure - driver fine tuning for given device after attach
662 - slave_destroy - given device is about to be shut down
668 * bios_param - fetch head, sector, cylinder info for a disk
686 * pre-initialized with made up values just in case this function
696 * eh_timed_out - The timer for the command has just fired
722 * eh_abort_handler - abort command associated with scp
743 * eh_bus_reset_handler - issue SCSI bus reset
761 * eh_device_reset_handler - issue SCSI device reset
779 * eh_host_reset_handler - reset host (host bus adapter)
801 * info - supply information about given host: driver name plus data
831 * ioctl - driver can respond to ioctls
846 * Notes: The SCSI subsystem uses a "trickle down" ioctl model.
847 * The user issues an ioctl() against an upper level driver
848 * (e.g. /dev/sdc) and if the upper level driver doesn't recognize
849 * the 'cmd' then it is passed to the SCSI mid level. If the SCSI
850 * mid level does not recognize it, then the LLD that controls
852 * unsupported ioctl() 'cmd' numbers should return -ENOTTY.
860 * proc_info - supports /proc/scsi/{driver_name}/{host_no}
869 * @writeto1_read0: 1 -> data coming from user space towards driver
871 * 0 -> user what data from this driver
882 * support can now be configured out of the scsi subsystem.
891 * queuecommand - queue scsi command, invoke scp->scsi_done on completion
902 * On both of these returns, the mid-layer will requeue the I/O
904 * - if the return is SCSI_MLQUEUE_DEVICE_BUSY, only that particular
910 * - if the return is SCSI_MLQUEUE_HOST_BUSY, all I/O to the host
920 * flagged by setting scp->result to an appropriate value,
921 * invoking the scp->scsi_done callback, and then returning 0
924 * command) then this function should place 0 in scp->result and
929 * scp->scsi_done callback is executed. Note: the driver may
930 * call scp->scsi_done before returning zero, but after it has
931 * called scp->scsi_done, it may not return any value other than
932 * zero. If the driver makes a non-zero return, it must not
943 * will not wait for IO to complete. Hence the scp->scsi_done
947 * response to a SCSI INQUIRY) the scp->scsi_done callback may be
948 * invoked before this function returns. If the scp->scsi_done
950 * level will commence error processing. If a status of CHECK
951 * CONDITION is placed in "result" when the scp->scsi_done
955 * the mid level queuing a command to an LLD.
963 * slave_alloc - prior to any commands being sent to a new device
976 * exist but the mid level is just about to scan for it (i.e. send
988 * slave_configure - driver fine tuning for given device just after it
1011 * slave_destroy - given device is about to be shut down. All
1021 * Notes: Mid level structures for given device are still in place
1025 * could be re-attached in the future in which case a new instance
1038 -------------------------
1045 - name of driver (may contain spaces, please limit to
1049 - name used in "/proc/scsi/<proc_name>/<host_no>" and
1055 - primary callback that the mid level uses to inject
1066 ----------------
1075 - system wide unique number that is used for identifying
1078 - must be greater than 0; do not send more than can_queue
1081 - scsi id of host (scsi initiator) or -1 if not known
1083 - maximum scatter gather elements allowed by host.
1087 - maximum number of sectors (usually 512 bytes) allowed
1095 - maximum number of commands that can be queued on devices
1099 - 1=>Asynchronous aborts are not supported
1100 - 0=>Timed-out commands will be aborted asynchronously
1102 - pointer to driver's struct scsi_host_template from which
1104 hostt->proc_name
1105 - name of LLD. This is the driver name that sysfs uses
1107 - pointer to driver's struct scsi_transport_template instance
1110 - a double linked list of pointers to all struct Scsi_Host
1113 - a double linked list of pointers to struct scsi_device
1116 - area reserved for LLD at end of struct Scsi_Host. Size
1120 - a unique value that identifies the vendor supplying
1122 vendor-specific message requests. Value consists of an
1123 identifier type and a vendor-specific value.
1129 ------------------
1136 ----------------
1138 back to the mid level. The SCSI mid level will ensure that no more SCSI
1145 - array containing SCSI command
1147 - length (in bytes) of SCSI command
1149 - direction of data transfer in data phase. See
1150 "enum dma_data_direction" in include/linux/dma-mapping.h
1152 - number of data bytes to transfer (0 if no data phase)
1154 - ==0 -> no scatter gather list, hence transfer data
1156 - >0 -> scatter gather list (actually an array) in
1159 - either contains data buffer or scatter gather list
1164 - function pointer that should be invoked by LLD when the
1171 - should be set by LLD prior to calling 'done'. A value
1179 - an array (maximum size: SCSI_SENSE_BUFFERSIZE bytes) that
1183 then the mid level will assume the sense_buffer array
1185 level will issue a REQUEST_SENSE SCSI command to
1188 always "auto-sense".
1190 - pointer to scsi_device object that this command is
1193 - an LLD should set this unsigned integer to the requested
1202 - LLD should place (DID_ERROR << 16) in 'result' if
1222 scsi_set_resid(SCpnt, scsi_bufflen(SCpnt) - (3 * 512));
1233 operations performed by the mid level use the struct Scsi_Host::host_lock
1240 Autosense (or auto-sense) is defined in the SAM-2 document as "the
1250 Either way, when a status of CHECK CONDITION is detected, the mid level
1254 this byte is initialized to 0 before each command) then the mid level will
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
1289 - Mike Anderson <andmike at us dot ibm dot com>
1290 - James Bottomley <James dot Bottomley at hansenpartnership dot com>
1291 - Patrick Mansfield <patmans at us dot ibm dot com>
1292 - Christoph Hellwig <hch at infradead dot org>
1293 - Doug Ledford <dledford at redhat dot com>
1294 - Andries Brouwer <Andries dot Brouwer at cwi dot nl>
1295 - Randy Dunlap <rdunlap at xenotime dot net>
1296 - Alan Stern <stern at rowland dot harvard dot edu>