338 lines · plain
1=====================2SCSI Interfaces Guide3=====================4 5:Author: James Bottomley6:Author: Rob Landley7 8Introduction9============10 11Protocol vs bus12---------------13 14Once upon a time, the Small Computer Systems Interface defined both a15parallel I/O bus and a data protocol to connect a wide variety of16peripherals (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 fallen20out of use, the SCSI command set is more widely used than ever to21communicate with devices over a number of different busses.22 23The `SCSI protocol <https://www.t10.org/scsi-3.htm>`__ is a big-endian24peer-to-peer packet based protocol. SCSI commands are 6, 10, 12, or 1625bytes long, often followed by an associated data payload.26 27SCSI commands can be transported over just about any kind of bus, and28are the default protocol for storage devices attached to USB, SATA, SAS,29Fibre Channel, FireWire, and ATAPI devices. SCSI packets are also30commonly exchanged over Infiniband,31TCP/IP (`iSCSI <https://en.wikipedia.org/wiki/ISCSI>`__), even `Parallel32ports <http://cyberelk.net/tim/parport/parscsi.html>`__.33 34Design of the Linux SCSI subsystem35----------------------------------36 37The SCSI subsystem uses a three layer design, with upper, mid, and low38layers. Every operation involving the SCSI subsystem (such as reading a39sector from a disk) uses one driver at each of the 3 levels: one upper40layer driver, one lower layer driver, and the SCSI midlayer.41 42The SCSI upper layer provides the interface between userspace and the43kernel, 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 layer47such as the IPv4 stack. The SCSI mid-layer routes a packet based data48protocol between the upper layer's /dev nodes and the corresponding49devices in the lower layer. It manages command queues, provides error50handling and power management functions, and responds to ioctl()51requests.52 53SCSI upper layer54================55 56The upper layer supports the user-kernel interface by providing device57nodes.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 layer85==============86 87SCSI midlayer implementation88----------------------------89 90include/scsi/scsi_device.h91~~~~~~~~~~~~~~~~~~~~~~~~~~~92 93.. kernel-doc:: include/scsi/scsi_device.h94 :internal:95 96drivers/scsi/scsi.c97~~~~~~~~~~~~~~~~~~~98 99Main file for the SCSI midlayer.100 101.. kernel-doc:: drivers/scsi/scsi.c102 :export:103 104drivers/scsi/scsicam.c105~~~~~~~~~~~~~~~~~~~~~~106 107`SCSI Common Access108Method <http://www.t10.org/ftp/t10/drafts/cam/cam-r12b.pdf>`__ support109functions, for use with HDIO_GETGEO, etc.110 111.. kernel-doc:: drivers/scsi/scsicam.c112 :export:113 114drivers/scsi/scsi_error.c115~~~~~~~~~~~~~~~~~~~~~~~~~~116 117Common SCSI error/timeout handling routines.118 119.. kernel-doc:: drivers/scsi/scsi_error.c120 :export:121 122drivers/scsi/scsi_devinfo.c123~~~~~~~~~~~~~~~~~~~~~~~~~~~~124 125Manage scsi_dev_info_list, which tracks blacklisted and whitelisted126devices.127 128.. kernel-doc:: drivers/scsi/scsi_devinfo.c129 :internal:130 131drivers/scsi/scsi_ioctl.c132~~~~~~~~~~~~~~~~~~~~~~~~~~133 134Handle ioctl() calls for SCSI devices.135 136.. kernel-doc:: drivers/scsi/scsi_ioctl.c137 :export:138 139drivers/scsi/scsi_lib.c140~~~~~~~~~~~~~~~~~~~~~~~~141 142SCSI queuing library.143 144.. kernel-doc:: drivers/scsi/scsi_lib.c145 :export:146 147drivers/scsi/scsi_lib_dma.c148~~~~~~~~~~~~~~~~~~~~~~~~~~~~~149 150SCSI library functions depending on DMA (map and unmap scatter-gather151lists).152 153.. kernel-doc:: drivers/scsi/scsi_lib_dma.c154 :export:155 156drivers/scsi/scsi_proc.c157~~~~~~~~~~~~~~~~~~~~~~~~~158 159The functions in this file provide an interface between the PROC file160system 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.c165 :internal:166 167drivers/scsi/scsi_netlink.c168~~~~~~~~~~~~~~~~~~~~~~~~~~~~169 170Infrastructure to provide async events from transports to userspace via171netlink, using a single NETLINK_SCSITRANSPORT protocol for all172transports. See `the original patch submission173<https://lore.kernel.org/linux-scsi/1155070439.6275.5.camel@localhost.localdomain/>`__174for more details.175 176.. kernel-doc:: drivers/scsi/scsi_netlink.c177 :internal:178 179drivers/scsi/scsi_scan.c180~~~~~~~~~~~~~~~~~~~~~~~~~181 182Scan a host to determine which (if any) devices are attached. The183general scanning/probing algorithm is as follows, exceptions are made to184it depending on device specific flags, compilation options, and global185variable (boot or module load time) settings. A specific LUN is scanned186via an INQUIRY command; if the LUN has a device attached, a scsi_device187is allocated and setup for it. For every id of every channel on the188given host, start by scanning LUN 0. Skip hosts that don't respond at189all 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 LUN193is seen that cannot have a device attached to it.194 195.. kernel-doc:: drivers/scsi/scsi_scan.c196 :internal:197 198drivers/scsi/scsi_sysctl.c199~~~~~~~~~~~~~~~~~~~~~~~~~~~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.c205~~~~~~~~~~~~~~~~~~~~~~~~~~206 207SCSI sysfs interface routines.208 209.. kernel-doc:: drivers/scsi/scsi_sysfs.c210 :export:211 212drivers/scsi/hosts.c213~~~~~~~~~~~~~~~~~~~~214 215mid to lowlevel SCSI driver interface216 217.. kernel-doc:: drivers/scsi/hosts.c218 :export:219 220drivers/scsi/scsi_common.c221~~~~~~~~~~~~~~~~~~~~~~~~~~222 223general support functions224 225.. kernel-doc:: drivers/scsi/scsi_common.c226 :export:227 228Transport classes229-----------------230 231Transport classes are service libraries for drivers in the SCSI lower232layer, which expose transport attributes in sysfs.233 234Fibre Channel transport235~~~~~~~~~~~~~~~~~~~~~~~236 237The file drivers/scsi/scsi_transport_fc.c defines transport attributes238for Fibre Channel.239 240.. kernel-doc:: drivers/scsi/scsi_transport_fc.c241 :export:242 243iSCSI transport class244~~~~~~~~~~~~~~~~~~~~~245 246The file drivers/scsi/scsi_transport_iscsi.c defines transport247attributes for the iSCSI class, which sends SCSI packets over TCP/IP248connections.249 250.. kernel-doc:: drivers/scsi/scsi_transport_iscsi.c251 :export:252 253Serial Attached SCSI (SAS) transport class254~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~255 256The file drivers/scsi/scsi_transport_sas.c defines transport257attributes for Serial Attached SCSI, a variant of SATA aimed at large258high-end systems.259 260The SAS transport class contains common code to deal with SAS HBAs, an261approximated representation of SAS topologies in the driver model, and262various sysfs attributes to expose these topologies and management263interfaces to userspace.264 265In addition to the basic SCSI core objects this transport class266introduces two additional intermediate objects: The SAS PHY as267represented by struct sas_phy defines an "outgoing" PHY on a SAS HBA or268Expander, and the SAS remote PHY represented by struct sas_rphy defines269an "incoming" PHY on a SAS Expander or end device. Note that this is270purely a software concept, the underlying hardware for a PHY and a271remote PHY is the exactly the same.272 273There is no concept of a SAS port in this code, users can see what PHYs274form a wide port based on the port_identifier attribute, which is the275same for all PHYs in a port.276 277.. kernel-doc:: drivers/scsi/scsi_transport_sas.c278 :export:279 280SATA transport class281~~~~~~~~~~~~~~~~~~~~282 283The SATA transport is handled by libata, which has its own book of284documentation in this directory.285 286Parallel SCSI (SPI) transport class287~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~288 289The file drivers/scsi/scsi_transport_spi.c defines transport290attributes for traditional (fast/wide/ultra) SCSI busses.291 292.. kernel-doc:: drivers/scsi/scsi_transport_spi.c293 :export:294 295SCSI RDMA (SRP) transport class296~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~297 298The file drivers/scsi/scsi_transport_srp.c defines transport299attributes for SCSI over Remote Direct Memory Access.300 301.. kernel-doc:: drivers/scsi/scsi_transport_srp.c302 :export:303 304SCSI lower layer305================306 307Host Bus Adapter transport types308--------------------------------309 310Many modern device controllers use the SCSI command set as a protocol to311communicate with their devices through many different types of physical312connections.313 314In SCSI language a bus capable of carrying SCSI commands is called a315"transport", and a controller connecting to such a bus is called a "host316bus adapter" (HBA).317 318Debug transport319~~~~~~~~~~~~~~~320 321The file drivers/scsi/scsi_debug.c simulates a host adapter with a322variable number of disks (or disk like devices) attached, sharing a323common amount of RAM. Does a lot of checking to make sure that we are324not getting blocks mixed up, and panics the kernel if anything out of325the ordinary is seen.326 327To be more realistic, the simulated devices have the transport328attributes of SAS disks.329 330For documentation see http://sg.danny.cz/sg/scsi_debug.html331 332todo333~~~~334 335Parallel (fast/wide/ultra) SCSI, USB, SATA, SAS, Fibre Channel,336FireWire, ATAPI devices, Infiniband, Parallel ports,337netlink...338