0001 =====================
0002 SCSI Interfaces Guide
0003 =====================
0004
0005 :Author: James Bottomley
0006 :Author: Rob Landley
0007
0008 Introduction
0009 ============
0010
0011 Protocol vs bus
0012 ---------------
0013
0014 Once upon a time, the Small Computer Systems Interface defined both a
0015 parallel I/O bus and a data protocol to connect a wide variety of
0016 peripherals (disk drives, tape drives, modems, printers, scanners,
0017 optical drives, test equipment, and medical devices) to a host computer.
0018
0019 Although the old parallel (fast/wide/ultra) SCSI bus has largely fallen
0020 out of use, the SCSI command set is more widely used than ever to
0021 communicate with devices over a number of different busses.
0022
0023 The `SCSI protocol <http://www.t10.org/scsi-3.htm>`__ is a big-endian
0024 peer-to-peer packet based protocol. SCSI commands are 6, 10, 12, or 16
0025 bytes long, often followed by an associated data payload.
0026
0027 SCSI commands can be transported over just about any kind of bus, and
0028 are the default protocol for storage devices attached to USB, SATA, SAS,
0029 Fibre Channel, FireWire, and ATAPI devices. SCSI packets are also
0030 commonly exchanged over Infiniband,
0031 `I2O <http://i2o.shadowconnect.com/faq.php>`__, TCP/IP
0032 (`iSCSI <https://en.wikipedia.org/wiki/ISCSI>`__), even `Parallel
0033 ports <http://cyberelk.net/tim/parport/parscsi.html>`__.
0034
0035 Design of the Linux SCSI subsystem
0036 ----------------------------------
0037
0038 The SCSI subsystem uses a three layer design, with upper, mid, and low
0039 layers. Every operation involving the SCSI subsystem (such as reading a
0040 sector from a disk) uses one driver at each of the 3 levels: one upper
0041 layer driver, one lower layer driver, and the SCSI midlayer.
0042
0043 The SCSI upper layer provides the interface between userspace and the
0044 kernel, in the form of block and char device nodes for I/O and ioctl().
0045 The SCSI lower layer contains drivers for specific hardware devices.
0046
0047 In between is the SCSI mid-layer, analogous to a network routing layer
0048 such as the IPv4 stack. The SCSI mid-layer routes a packet based data
0049 protocol between the upper layer's /dev nodes and the corresponding
0050 devices in the lower layer. It manages command queues, provides error
0051 handling and power management functions, and responds to ioctl()
0052 requests.
0053
0054 SCSI upper layer
0055 ================
0056
0057 The upper layer supports the user-kernel interface by providing device
0058 nodes.
0059
0060 sd (SCSI Disk)
0061 --------------
0062
0063 sd (sd_mod.o)
0064
0065 sr (SCSI CD-ROM)
0066 ----------------
0067
0068 sr (sr_mod.o)
0069
0070 st (SCSI Tape)
0071 --------------
0072
0073 st (st.o)
0074
0075 sg (SCSI Generic)
0076 -----------------
0077
0078 sg (sg.o)
0079
0080 ch (SCSI Media Changer)
0081 -----------------------
0082
0083 ch (ch.c)
0084
0085 SCSI mid layer
0086 ==============
0087
0088 SCSI midlayer implementation
0089 ----------------------------
0090
0091 include/scsi/scsi_device.h
0092 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
0093
0094 .. kernel-doc:: include/scsi/scsi_device.h
0095 :internal:
0096
0097 drivers/scsi/scsi.c
0098 ~~~~~~~~~~~~~~~~~~~
0099
0100 Main file for the SCSI midlayer.
0101
0102 .. kernel-doc:: drivers/scsi/scsi.c
0103 :export:
0104
0105 drivers/scsi/scsicam.c
0106 ~~~~~~~~~~~~~~~~~~~~~~
0107
0108 `SCSI Common Access
0109 Method <http://www.t10.org/ftp/t10/drafts/cam/cam-r12b.pdf>`__ support
0110 functions, for use with HDIO_GETGEO, etc.
0111
0112 .. kernel-doc:: drivers/scsi/scsicam.c
0113 :export:
0114
0115 drivers/scsi/scsi_error.c
0116 ~~~~~~~~~~~~~~~~~~~~~~~~~~
0117
0118 Common SCSI error/timeout handling routines.
0119
0120 .. kernel-doc:: drivers/scsi/scsi_error.c
0121 :export:
0122
0123 drivers/scsi/scsi_devinfo.c
0124 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0125
0126 Manage scsi_dev_info_list, which tracks blacklisted and whitelisted
0127 devices.
0128
0129 .. kernel-doc:: drivers/scsi/scsi_devinfo.c
0130 :internal:
0131
0132 drivers/scsi/scsi_ioctl.c
0133 ~~~~~~~~~~~~~~~~~~~~~~~~~~
0134
0135 Handle ioctl() calls for SCSI devices.
0136
0137 .. kernel-doc:: drivers/scsi/scsi_ioctl.c
0138 :export:
0139
0140 drivers/scsi/scsi_lib.c
0141 ~~~~~~~~~~~~~~~~~~~~~~~~
0142
0143 SCSI queuing library.
0144
0145 .. kernel-doc:: drivers/scsi/scsi_lib.c
0146 :export:
0147
0148 drivers/scsi/scsi_lib_dma.c
0149 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0150
0151 SCSI library functions depending on DMA (map and unmap scatter-gather
0152 lists).
0153
0154 .. kernel-doc:: drivers/scsi/scsi_lib_dma.c
0155 :export:
0156
0157 drivers/scsi/scsi_proc.c
0158 ~~~~~~~~~~~~~~~~~~~~~~~~~
0159
0160 The functions in this file provide an interface between the PROC file
0161 system and the SCSI device drivers It is mainly used for debugging,
0162 statistics and to pass information directly to the lowlevel driver. I.E.
0163 plumbing to manage /proc/scsi/\*
0164
0165 .. kernel-doc:: drivers/scsi/scsi_proc.c
0166 :internal:
0167
0168 drivers/scsi/scsi_netlink.c
0169 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0170
0171 Infrastructure to provide async events from transports to userspace via
0172 netlink, using a single NETLINK_SCSITRANSPORT protocol for all
0173 transports. See `the original patch
0174 submission <http://marc.info/?l=linux-scsi&m=115507374832500&w=2>`__ for
0175 more details.
0176
0177 .. kernel-doc:: drivers/scsi/scsi_netlink.c
0178 :internal:
0179
0180 drivers/scsi/scsi_scan.c
0181 ~~~~~~~~~~~~~~~~~~~~~~~~~
0182
0183 Scan a host to determine which (if any) devices are attached. The
0184 general scanning/probing algorithm is as follows, exceptions are made to
0185 it depending on device specific flags, compilation options, and global
0186 variable (boot or module load time) settings. A specific LUN is scanned
0187 via an INQUIRY command; if the LUN has a device attached, a scsi_device
0188 is allocated and setup for it. For every id of every channel on the
0189 given host, start by scanning LUN 0. Skip hosts that don't respond at
0190 all to a scan of LUN 0. Otherwise, if LUN 0 has a device attached,
0191 allocate and setup a scsi_device for it. If target is SCSI-3 or up,
0192 issue a REPORT LUN, and scan all of the LUNs returned by the REPORT LUN;
0193 else, sequentially scan LUNs up until some maximum is reached, or a LUN
0194 is seen that cannot have a device attached to it.
0195
0196 .. kernel-doc:: drivers/scsi/scsi_scan.c
0197 :internal:
0198
0199 drivers/scsi/scsi_sysctl.c
0200 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
0201
0202 Set up the sysctl entry: "/dev/scsi/logging_level"
0203 (DEV_SCSI_LOGGING_LEVEL) which sets/returns scsi_logging_level.
0204
0205 drivers/scsi/scsi_sysfs.c
0206 ~~~~~~~~~~~~~~~~~~~~~~~~~~
0207
0208 SCSI sysfs interface routines.
0209
0210 .. kernel-doc:: drivers/scsi/scsi_sysfs.c
0211 :export:
0212
0213 drivers/scsi/hosts.c
0214 ~~~~~~~~~~~~~~~~~~~~
0215
0216 mid to lowlevel SCSI driver interface
0217
0218 .. kernel-doc:: drivers/scsi/hosts.c
0219 :export:
0220
0221 drivers/scsi/scsi_common.c
0222 ~~~~~~~~~~~~~~~~~~~~~~~~~~
0223
0224 general support functions
0225
0226 .. kernel-doc:: drivers/scsi/scsi_common.c
0227 :export:
0228
0229 Transport classes
0230 -----------------
0231
0232 Transport classes are service libraries for drivers in the SCSI lower
0233 layer, which expose transport attributes in sysfs.
0234
0235 Fibre Channel transport
0236 ~~~~~~~~~~~~~~~~~~~~~~~
0237
0238 The file drivers/scsi/scsi_transport_fc.c defines transport attributes
0239 for Fibre Channel.
0240
0241 .. kernel-doc:: drivers/scsi/scsi_transport_fc.c
0242 :export:
0243
0244 iSCSI transport class
0245 ~~~~~~~~~~~~~~~~~~~~~
0246
0247 The file drivers/scsi/scsi_transport_iscsi.c defines transport
0248 attributes for the iSCSI class, which sends SCSI packets over TCP/IP
0249 connections.
0250
0251 .. kernel-doc:: drivers/scsi/scsi_transport_iscsi.c
0252 :export:
0253
0254 Serial Attached SCSI (SAS) transport class
0255 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0256
0257 The file drivers/scsi/scsi_transport_sas.c defines transport
0258 attributes for Serial Attached SCSI, a variant of SATA aimed at large
0259 high-end systems.
0260
0261 The SAS transport class contains common code to deal with SAS HBAs, an
0262 aproximated representation of SAS topologies in the driver model, and
0263 various sysfs attributes to expose these topologies and management
0264 interfaces to userspace.
0265
0266 In addition to the basic SCSI core objects this transport class
0267 introduces two additional intermediate objects: The SAS PHY as
0268 represented by struct sas_phy defines an "outgoing" PHY on a SAS HBA or
0269 Expander, and the SAS remote PHY represented by struct sas_rphy defines
0270 an "incoming" PHY on a SAS Expander or end device. Note that this is
0271 purely a software concept, the underlying hardware for a PHY and a
0272 remote PHY is the exactly the same.
0273
0274 There is no concept of a SAS port in this code, users can see what PHYs
0275 form a wide port based on the port_identifier attribute, which is the
0276 same for all PHYs in a port.
0277
0278 .. kernel-doc:: drivers/scsi/scsi_transport_sas.c
0279 :export:
0280
0281 SATA transport class
0282 ~~~~~~~~~~~~~~~~~~~~
0283
0284 The SATA transport is handled by libata, which has its own book of
0285 documentation in this directory.
0286
0287 Parallel SCSI (SPI) transport class
0288 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0289
0290 The file drivers/scsi/scsi_transport_spi.c defines transport
0291 attributes for traditional (fast/wide/ultra) SCSI busses.
0292
0293 .. kernel-doc:: drivers/scsi/scsi_transport_spi.c
0294 :export:
0295
0296 SCSI RDMA (SRP) transport class
0297 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0298
0299 The file drivers/scsi/scsi_transport_srp.c defines transport
0300 attributes for SCSI over Remote Direct Memory Access.
0301
0302 .. kernel-doc:: drivers/scsi/scsi_transport_srp.c
0303 :export:
0304
0305 SCSI lower layer
0306 ================
0307
0308 Host Bus Adapter transport types
0309 --------------------------------
0310
0311 Many modern device controllers use the SCSI command set as a protocol to
0312 communicate with their devices through many different types of physical
0313 connections.
0314
0315 In SCSI language a bus capable of carrying SCSI commands is called a
0316 "transport", and a controller connecting to such a bus is called a "host
0317 bus adapter" (HBA).
0318
0319 Debug transport
0320 ~~~~~~~~~~~~~~~
0321
0322 The file drivers/scsi/scsi_debug.c simulates a host adapter with a
0323 variable number of disks (or disk like devices) attached, sharing a
0324 common amount of RAM. Does a lot of checking to make sure that we are
0325 not getting blocks mixed up, and panics the kernel if anything out of
0326 the ordinary is seen.
0327
0328 To be more realistic, the simulated devices have the transport
0329 attributes of SAS disks.
0330
0331 For documentation see http://sg.danny.cz/sg/sdebug26.html
0332
0333 todo
0334 ~~~~
0335
0336 Parallel (fast/wide/ultra) SCSI, USB, SATA, SAS, Fibre Channel,
0337 FireWire, ATAPI devices, Infiniband, I2O, Parallel ports,
0338 netlink...
