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.
123 from the SCSI subsystem. Hosts can be introduced as early as driver
128 with the SCSI mid level.
134 registered with sysfs at this point. The SCSI mid level first becomes
138 is a typical sequence of calls between the LLD and the mid level.
139 This example shows the mid level scanning the newly introduced HBA for 3
143 LLD mid level LLD
144 ===-------------------=========--------------------===------
145 scsi_host_alloc() -->
146 scsi_add_host() ---->
147 scsi_scan_host() -------+
150 sdev_configure() --> scsi_change_queue_depth()
159 *** For scsi devices that the mid level tries to scan but do not
172 LLD mid level LLD
173 ===----------------------=========-----------------===------
174 scsi_remove_host() ---------+
182 by the mid-level. struct Scsi_Host instances are freed from
187 counting logic is being introduced into the mid level to cope with many
195 An LLD can use this sequence to make the mid level aware of a SCSI device::
198 LLD mid level LLD
199 ===-------------------=========--------------------===------
200 scsi_add_device() ------+
203 sdev_configure() [--> scsi_change_queue_depth()]
209 probably cause that device to be set offline by the mid level. An LLD that
214 LLD mid level LLD
215 ===----------------------=========-----------------===------
216 scsi_remove_device() -------+
222 sdev_configure() callbacks). Such instances are "owned" by the mid-level.
231 were exclusively owned by the mid level. LLDs would not usually need to
238 - scsi_host_alloc():
242 - scsi_host_get():
245 - scsi_host_put():
253 were exclusively owned by the mid level. See the access functions declared
269 Documentation/process/coding-style.rst file.
277 Well written, tested and documented code, need not be re-formatted to
283 Mid level supplied functions
285 These functions are supplied by the SCSI mid level for use by LLDs.
288 arrange for the SCSI mid level to be loaded and initialized before any LLD
294 - scsi_add_device - creates new scsi device (lu) instance
295 - scsi_add_host - perform sysfs registration and set up transport class
296 - scsi_change_queue_depth - change the queue depth on a SCSI device
297 - scsi_bios_ptable - return copy of block device's partition table
298 - scsi_block_requests - prevent further commands being queued to given host
299 - scsi_host_alloc - return a new scsi_host instance whose refcount==1
300 - scsi_host_get - increments Scsi_Host instance's refcount
301 - scsi_host_put - decrements Scsi_Host instance's refcount (free if 0)
302 - scsi_remove_device - detach and remove a SCSI device
303 - scsi_remove_host - detach and remove all SCSI devices owned by host
304 - scsi_report_bus_reset - report scsi _bus_ reset observed
305 - scsi_scan_host - scan SCSI bus
306 - scsi_track_queue_full - track successive QUEUE_FULL events
307 - scsi_unblock_requests - allow further commands to be queued to given host
313 * scsi_add_device - creates new scsi device (lu) instance
320 * ERR_PTR(-ENODEV) (or some other bent pointer) if something is
340 * scsi_add_host - perform sysfs registration and set up transport class
344 * Returns 0 on success, negative errno of failure (e.g. -ENOMEM)
351 * in some other transport-specific way. The LLD must set up
361 * scsi_change_queue_depth - allow LLD to change queue depth on a SCSI device
365 * in non-tagged mode (as per cmd_per_lun).
382 * scsi_bios_ptable - return copy of block device's partition table
397 * scsi_block_requests - prevent further commands being queued to given host
414 * scsi_host_alloc - create a scsi host adapter instance and perform basic
439 * scsi_host_get - increment Scsi_Host instance refcount
446 * Notes: Actually increments the counts in two sub-objects
454 * scsi_host_put - decrement Scsi_Host instance refcount, free if 0
461 * Notes: Actually decrements the counts in two sub-objects. If the
473 * scsi_remove_device - detach and remove a SCSI device
476 * Returns value: 0 on success, -EINVAL if device not attached
492 * scsi_remove_host - detach and remove all SCSI devices owned by host
509 * scsi_report_bus_reset - report scsi _bus_ reset observed
519 * mid level itself don't need to call this, but there should be
529 * scsi_scan_host - scan SCSI bus
542 * scsi_track_queue_full - track successive QUEUE_FULL events on given
549 * Returns 0 - no change needed
550 * >0 - adjust queue depth to this new depth
551 * -1 - drop back to untagged operation using host->cmd_per_lun
565 * scsi_unblock_requests - allow further commands to be queued to given host
594 should be passed to the mid level's scsi_host_alloc().
605 - bios_param - fetch head, sector, cylinder info for a disk
606 - eh_timed_out - notify the host that a command timer expired
607 - eh_abort_handler - abort given command
608 - eh_bus_reset_handler - issue SCSI bus reset
609 - eh_device_reset_handler - issue SCSI device reset
610 - eh_host_reset_handler - reset host (host bus adapter)
611 - info - supply information about given host
612 - ioctl - driver can respond to ioctls
613 - proc_info - supports /proc/scsi/{driver_name}/{host_no}
614 - queuecommand - queue scsi command, invoke 'done' on completion
615 - sdev_init - prior to any commands being sent to a new device
616 - sdev_configure - driver fine tuning for given device after attach
617 - sdev_destroy - given device is about to be shut down
623 * bios_param - fetch head, sector, cylinder info for a disk
641 * pre-initialized with made up values just in case this function
651 * eh_timed_out - The timer for the command has just fired
677 * eh_abort_handler - abort command associated with scp
694 * eh_bus_reset_handler - issue SCSI bus reset
712 * eh_device_reset_handler - issue SCSI device reset
730 * eh_host_reset_handler - reset host (host bus adapter)
752 * info - supply information about given host: driver name plus data
778 * ioctl - driver can respond to ioctls
793 * Notes: The SCSI subsystem uses a "trickle down" ioctl model.
794 * The user issues an ioctl() against an upper level driver
795 * (e.g. /dev/sdc) and if the upper level driver doesn't recognize
796 * the 'cmd' then it is passed to the SCSI mid level. If the SCSI
797 * mid level does not recognize it, then the LLD that controls
799 * unsupported ioctl() 'cmd' numbers should return -ENOTTY.
807 * proc_info - supports /proc/scsi/{driver_name}/{host_no}
816 * @writeto1_read0: 1 -> data coming from user space towards driver
818 * 0 -> user what data from this driver
829 * support can now be configured out of the scsi subsystem.
838 * queuecommand - queue scsi command, invoke scp->scsi_done on completion
849 * On both of these returns, the mid-layer will requeue the I/O
851 * - if the return is SCSI_MLQUEUE_DEVICE_BUSY, only that particular
857 * - if the return is SCSI_MLQUEUE_HOST_BUSY, all I/O to the host
867 * flagged by setting scp->result to an appropriate value,
868 * invoking the scp->scsi_done callback, and then returning 0
871 * command) then this function should place 0 in scp->result and
876 * scp->scsi_done callback is executed. Note: the driver may
877 * call scp->scsi_done before returning zero, but after it has
878 * called scp->scsi_done, it may not return any value other than
879 * zero. If the driver makes a non-zero return, it must not
890 * will not wait for IO to complete. Hence the scp->scsi_done
894 * response to a SCSI INQUIRY) the scp->scsi_done callback may be
895 * invoked before this function returns. If the scp->scsi_done
897 * level will commence error processing. If a status of CHECK
898 * CONDITION is placed in "result" when the scp->scsi_done
902 * the mid level queuing a command to an LLD.
910 * sdev_init - prior to any commands being sent to a new device
923 * exist but the mid level is just about to scan for it (i.e. send
935 * sdev_configure - driver fine tuning for given device just after it
958 * sdev_destroy - given device is about to be shut down. All
968 * Notes: Mid level structures for given device are still in place
972 * could be re-attached in the future in which case a new instance
985 -------------------------
992 - name of driver (may contain spaces, please limit to
996 - name used in "/proc/scsi/<proc_name>/<host_no>" and
1002 - primary callback that the mid level uses to inject
1006 - a unique value that identifies the vendor supplying
1008 vendor-specific message requests. Value consists of an
1009 identifier type and a vendor-specific value.
1020 ----------------
1029 - system wide unique number that is used for identifying
1032 - must be greater than 0; do not send more than can_queue
1035 - scsi id of host (scsi initiator) or -1 if not known
1037 - maximum scatter gather elements allowed by host.
1041 - maximum number of sectors (usually 512 bytes) allowed
1049 - maximum number of commands that can be queued on devices
1053 - pointer to driver's struct scsi_host_template from which
1055 hostt->proc_name
1056 - name of LLD. This is the driver name that sysfs uses
1058 - pointer to driver's struct scsi_transport_template instance
1061 - area reserved for LLD at end of struct Scsi_Host. Size
1068 ------------------
1075 ----------------
1077 back to the mid level. The SCSI mid level will ensure that no more SCSI
1084 - array containing SCSI command
1086 - length (in bytes) of SCSI command
1088 - direction of data transfer in data phase. See
1089 "enum dma_data_direction" in include/linux/dma-mapping.h
1091 - should be set by LLD prior to calling 'done'. A value
1099 - an array (maximum size: SCSI_SENSE_BUFFERSIZE bytes) that
1103 then the mid level will assume the sense_buffer array
1105 level will issue a REQUEST_SENSE SCSI command to
1108 always "auto-sense".
1110 - pointer to scsi_device object that this command is
1113 - an LLD should set this unsigned integer to the requested
1122 - LLD should place (DID_ERROR << 16) in 'result' if
1142 scsi_set_resid(SCpnt, scsi_bufflen(SCpnt) - (3 * 512));
1153 operations performed by the mid level use the struct Scsi_Host::host_lock
1160 Autosense (or auto-sense) is defined in the SAM-2 document as "the
1170 Either way, when a status of CHECK CONDITION is detected, the mid level
1174 this byte is initialized to 0 before each command) then the mid level will
1193 In the 2.4 series the SCSI subsystem configuration descriptions were
1196 the SCSI subsystem now has its own (much smaller) drivers/scsi/Kconfig
1209 - Mike Anderson <andmike at us dot ibm dot com>
1210 - James Bottomley <James dot Bottomley at hansenpartnership dot com>
1211 - Patrick Mansfield <patmans at us dot ibm dot com>
1212 - Christoph Hellwig <hch at infradead dot org>
1213 - Doug Ledford <dledford at redhat dot com>
1214 - Andries Brouwer <Andries dot Brouwer at cwi dot nl>
1215 - Randy Dunlap <rdunlap at xenotime dot net>
1216 - Alan Stern <stern at rowland dot harvard dot edu>