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