Lines Matching +full:device +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
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
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
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).
68 and OS-specific code (e.g. FreeBSD and Linux). Such drivers tend to have
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.
129 detected. After confirming that the new device is one that the LLD wants
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
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
201 LLD mid level LLD
202 ===-------------------=========--------------------===------
203 scsi_add_device() ------+
206 slave_configure() [--> scsi_change_queue_depth()]
208 In a similar fashion, an LLD may become aware that a SCSI device has been
211 device has been removed until a subsequent SCSI command fails which will
212 probably cause that device to be set offline by the mid level. An LLD that
213 detects the removal of a SCSI device can instigate its removal from
216 SCSI DEVICE hot unplug
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
333 * device (lu) after scsi_scan_host() has completed. If successful
345 * scsi_add_host - perform sysfs registration and set up transport class
347 * @dev: pointer to struct device of type scsi 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
362 int scsi_add_host(struct Scsi_Host *shost, struct device * dev)
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
370 * in non-tagged mode (as per cmd_per_lun).
376 * Notes: Can be invoked any time on a SCSI device controlled by this
387 * scsi_bios_ptable - return copy of block device's partition table
388 * @dev: pointer to block device
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
500 * @sdev: a pointer to a scsi device instance
502 * Returns value: 0 on success, -EINVAL if device not attached
506 * Notes: If an LLD becomes aware that a scsi device (lu) has
508 * the removal of that scsi device. If successful this call will
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
569 * device to determine if and when there is a need
570 * to adjust the queue depth on the device.
571 * @sdev: pointer to SCSI device instance
572 * @depth: Current number of outstanding SCSI commands on this device,
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
669 * @sdev: pointer to scsi device context (defined in
671 * @bdev: pointer to block device context (defined in fs.h)
672 * @capacity: device size (in 512 byte sectors)
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
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
779 * eh_host_reset_handler - reset host (host bus adapter)
780 * @scp: SCSI host that contains this device should be reset
792 * defined (or they all return FAILED) then the device in question
801 * info - supply information about given host: driver name plus data
831 * ioctl - driver can respond to ioctls
832 * @sdp: device that ioctl was issued for
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
851 * the device receives the ioctl. According to recent Unix standards
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
891 * queuecommand - queue scsi command, invoke scp->scsi_done on completion
899 * SCSI_MLQUEUE_DEVICE_BUSY if the device queue is full, or
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
905 * device will be paused, and it will be unpaused when a command to
906 * the device returns (or after a brief delay if there are no more
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
965 * @sdp: pointer to new device (about to be scanned)
968 * the device is ignored.
974 * Notes: Allows the driver to allocate any resources for a device
975 * prior to its initial scan. The corresponding scsi device may not
976 * exist but the mid level is just about to scan for it (i.e. send
977 * and INQUIRY command plus ...). If a device is found then
978 * slave_configure() will be called while if a device is not found
988 * slave_configure - driver fine tuning for given device just after it
991 * @sdp: device that has just been attached
994 * the device is taken offline. [offline devices will _not_ have
1011 * slave_destroy - given device is about to be shut down. All
1012 * activity has ceased on this device.
1013 * @sdp: device that is about to be shut down
1021 * Notes: Mid level structures for given device are still in place
1022 * but are about to be torn down. Any per device resources allocated
1023 * by this driver for given device should be freed now. No further
1024 * commands will be sent for this sdp instance. [However the device
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
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
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
1174 target device). 'result' is a 32 bit unsigned integer that
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".
1189 device
1190 - pointer to scsi_device object that this command is
1193 - an LLD should set this unsigned integer to the requested
1200 device (e.g. READs) that underrun.
1202 - LLD should place (DID_ERROR << 16) in 'result' if
1210 target device (e.g. READs). It is especially important that 'resid' is set
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
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>