Documentation/driver-api/scsi.rst

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