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