Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   1) =====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   2) SCSI Interfaces Guide
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   3) =====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   4) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   5) :Author: James Bottomley
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   6) :Author: Rob Landley
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   7) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   8) Introduction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   9) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  10) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  11) Protocol vs bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  12) ---------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  13) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  14) Once upon a time, the Small Computer Systems Interface defined both a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  15) parallel I/O bus and a data protocol to connect a wide variety of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  16) peripherals (disk drives, tape drives, modems, printers, scanners,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  17) optical drives, test equipment, and medical devices) to a host computer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  18) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  19) Although the old parallel (fast/wide/ultra) SCSI bus has largely fallen
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  20) out of use, the SCSI command set is more widely used than ever to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  21) communicate with devices over a number of different busses.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  22) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  23) The `SCSI protocol <http://www.t10.org/scsi-3.htm>`__ is a big-endian
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  24) peer-to-peer packet based protocol. SCSI commands are 6, 10, 12, or 16
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  25) bytes long, often followed by an associated data payload.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  26) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  27) SCSI commands can be transported over just about any kind of bus, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  28) are the default protocol for storage devices attached to USB, SATA, SAS,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  29) Fibre Channel, FireWire, and ATAPI devices. SCSI packets are also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  30) commonly exchanged over Infiniband,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  31) `I2O <http://i2o.shadowconnect.com/faq.php>`__, TCP/IP
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  32) (`iSCSI <https://en.wikipedia.org/wiki/ISCSI>`__), even `Parallel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  33) ports <http://cyberelk.net/tim/parport/parscsi.html>`__.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  34) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  35) Design of the Linux SCSI subsystem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  36) ----------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  37) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  38) The SCSI subsystem uses a three layer design, with upper, mid, and low
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  39) layers. Every operation involving the SCSI subsystem (such as reading a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  40) sector from a disk) uses one driver at each of the 3 levels: one upper
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  41) layer driver, one lower layer driver, and the SCSI midlayer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  42) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  43) The SCSI upper layer provides the interface between userspace and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  44) kernel, in the form of block and char device nodes for I/O and ioctl().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  45) The SCSI lower layer contains drivers for specific hardware devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  46) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  47) In between is the SCSI mid-layer, analogous to a network routing layer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  48) such as the IPv4 stack. The SCSI mid-layer routes a packet based data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  49) protocol between the upper layer's /dev nodes and the corresponding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  50) devices in the lower layer. It manages command queues, provides error
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  51) handling and power management functions, and responds to ioctl()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  52) requests.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  53) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  54) SCSI upper layer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  55) ================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  56) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  57) The upper layer supports the user-kernel interface by providing device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  58) nodes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  59) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  60) sd (SCSI Disk)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  61) --------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  62) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  63) sd (sd_mod.o)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  64) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  65) sr (SCSI CD-ROM)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  66) ----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  67) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  68) sr (sr_mod.o)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  69) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  70) st (SCSI Tape)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  71) --------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  72) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  73) st (st.o)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  74) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  75) sg (SCSI Generic)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  76) -----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  77) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  78) sg (sg.o)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  79) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  80) ch (SCSI Media Changer)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  81) -----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  82) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  83) ch (ch.c)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  84) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  85) SCSI mid layer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  86) ==============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  87) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  88) SCSI midlayer implementation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  89) ----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  90) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  91) include/scsi/scsi_device.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  92) ~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  93) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  94) .. kernel-doc:: include/scsi/scsi_device.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  95)    :internal:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  96) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  97) drivers/scsi/scsi.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  98) ~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  99) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) Main file for the SCSI midlayer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) .. kernel-doc:: drivers/scsi/scsi.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103)    :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) drivers/scsi/scsicam.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) ~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) `SCSI Common Access
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) Method <http://www.t10.org/ftp/t10/drafts/cam/cam-r12b.pdf>`__ support
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) functions, for use with HDIO_GETGEO, etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) .. kernel-doc:: drivers/scsi/scsicam.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)    :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) drivers/scsi/scsi_error.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) ~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) Common SCSI error/timeout handling routines.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) .. kernel-doc:: drivers/scsi/scsi_error.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)    :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) drivers/scsi/scsi_devinfo.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) Manage scsi_dev_info_list, which tracks blacklisted and whitelisted
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) .. kernel-doc:: drivers/scsi/scsi_devinfo.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130)    :internal:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) drivers/scsi/scsi_ioctl.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) ~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) Handle ioctl() calls for SCSI devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) .. kernel-doc:: drivers/scsi/scsi_ioctl.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)    :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) drivers/scsi/scsi_lib.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) ~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) SCSI queuing library.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) .. kernel-doc:: drivers/scsi/scsi_lib.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146)    :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) drivers/scsi/scsi_lib_dma.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) SCSI library functions depending on DMA (map and unmap scatter-gather
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) lists).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) .. kernel-doc:: drivers/scsi/scsi_lib_dma.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155)    :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) drivers/scsi/scsi_proc.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) ~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) The functions in this file provide an interface between the PROC file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) system and the SCSI device drivers It is mainly used for debugging,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) statistics and to pass information directly to the lowlevel driver. I.E.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) plumbing to manage /proc/scsi/\*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) .. kernel-doc:: drivers/scsi/scsi_proc.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166)    :internal:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) drivers/scsi/scsi_netlink.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) Infrastructure to provide async events from transports to userspace via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) netlink, using a single NETLINK_SCSITRANSPORT protocol for all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) transports. See `the original patch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) submission <http://marc.info/?l=linux-scsi&m=115507374832500&w=2>`__ for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) more details.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) .. kernel-doc:: drivers/scsi/scsi_netlink.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178)    :internal:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) drivers/scsi/scsi_scan.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) ~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) Scan a host to determine which (if any) devices are attached. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) general scanning/probing algorithm is as follows, exceptions are made to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) it depending on device specific flags, compilation options, and global
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) variable (boot or module load time) settings. A specific LUN is scanned
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) via an INQUIRY command; if the LUN has a device attached, a scsi_device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) is allocated and setup for it. For every id of every channel on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) given host, start by scanning LUN 0. Skip hosts that don't respond at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) all to a scan of LUN 0. Otherwise, if LUN 0 has a device attached,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) allocate and setup a scsi_device for it. If target is SCSI-3 or up,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) issue a REPORT LUN, and scan all of the LUNs returned by the REPORT LUN;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) else, sequentially scan LUNs up until some maximum is reached, or a LUN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) is seen that cannot have a device attached to it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) .. kernel-doc:: drivers/scsi/scsi_scan.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197)    :internal:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) drivers/scsi/scsi_sysctl.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) ~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) Set up the sysctl entry: "/dev/scsi/logging_level"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) (DEV_SCSI_LOGGING_LEVEL) which sets/returns scsi_logging_level.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) drivers/scsi/scsi_sysfs.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) ~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) SCSI sysfs interface routines.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) .. kernel-doc:: drivers/scsi/scsi_sysfs.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211)    :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) drivers/scsi/hosts.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) ~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) mid to lowlevel SCSI driver interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) .. kernel-doc:: drivers/scsi/hosts.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219)    :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) drivers/scsi/scsi_common.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) ~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) general support functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) .. kernel-doc:: drivers/scsi/scsi_common.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227)    :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) Transport classes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) -----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) Transport classes are service libraries for drivers in the SCSI lower
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) layer, which expose transport attributes in sysfs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) Fibre Channel transport
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) ~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) The file drivers/scsi/scsi_transport_fc.c defines transport attributes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) for Fibre Channel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) .. kernel-doc:: drivers/scsi/scsi_transport_fc.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242)    :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) iSCSI transport class
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) ~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) The file drivers/scsi/scsi_transport_iscsi.c defines transport
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) attributes for the iSCSI class, which sends SCSI packets over TCP/IP
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) connections.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) .. kernel-doc:: drivers/scsi/scsi_transport_iscsi.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252)    :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) Serial Attached SCSI (SAS) transport class
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) The file drivers/scsi/scsi_transport_sas.c defines transport
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) attributes for Serial Attached SCSI, a variant of SATA aimed at large
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) high-end systems.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) The SAS transport class contains common code to deal with SAS HBAs, an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) aproximated representation of SAS topologies in the driver model, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) various sysfs attributes to expose these topologies and management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) interfaces to userspace.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) In addition to the basic SCSI core objects this transport class
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) introduces two additional intermediate objects: The SAS PHY as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) represented by struct sas_phy defines an "outgoing" PHY on a SAS HBA or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) Expander, and the SAS remote PHY represented by struct sas_rphy defines
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) an "incoming" PHY on a SAS Expander or end device. Note that this is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) purely a software concept, the underlying hardware for a PHY and a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) remote PHY is the exactly the same.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) There is no concept of a SAS port in this code, users can see what PHYs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) form a wide port based on the port_identifier attribute, which is the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) same for all PHYs in a port.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) .. kernel-doc:: drivers/scsi/scsi_transport_sas.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279)    :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) SATA transport class
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) ~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) The SATA transport is handled by libata, which has its own book of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) documentation in this directory.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) Parallel SCSI (SPI) transport class
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) The file drivers/scsi/scsi_transport_spi.c defines transport
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) attributes for traditional (fast/wide/ultra) SCSI busses.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) .. kernel-doc:: drivers/scsi/scsi_transport_spi.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294)    :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) SCSI RDMA (SRP) transport class
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) The file drivers/scsi/scsi_transport_srp.c defines transport
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) attributes for SCSI over Remote Direct Memory Access.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) .. kernel-doc:: drivers/scsi/scsi_transport_srp.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303)    :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) SCSI lower layer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) ================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) Host Bus Adapter transport types
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) --------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) Many modern device controllers use the SCSI command set as a protocol to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) communicate with their devices through many different types of physical
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) connections.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) In SCSI language a bus capable of carrying SCSI commands is called a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) "transport", and a controller connecting to such a bus is called a "host
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) bus adapter" (HBA).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) Debug transport
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) ~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) The file drivers/scsi/scsi_debug.c simulates a host adapter with a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) variable number of disks (or disk like devices) attached, sharing a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) common amount of RAM. Does a lot of checking to make sure that we are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) not getting blocks mixed up, and panics the kernel if anything out of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) the ordinary is seen.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) To be more realistic, the simulated devices have the transport
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) attributes of SAS disks.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) For documentation see http://sg.danny.cz/sg/sdebug26.html
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) todo
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) ~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) Parallel (fast/wide/ultra) SCSI, USB, SATA, SAS, Fibre Channel,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) FireWire, ATAPI devices, Infiniband, I2O, Parallel ports,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) netlink...