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 drivers/scsi/constants.c
 228 ~~~~~~~~~~~~~~~~~~~~~~~~
 229
 230 mid to lowlevel SCSI driver interface
 231
 232 .. kernel-doc:: drivers/scsi/constants.c
 233    :export:
 234
 235 Transport classes
 236 -----------------
 237
 238 Transport classes are service libraries for drivers in the SCSI lower
 239 layer, which expose transport attributes in sysfs.
 240
 241 Fibre Channel transport
 242 ~~~~~~~~~~~~~~~~~~~~~~~
 243
 244 The file drivers/scsi/scsi_transport_fc.c defines transport attributes
 245 for Fibre Channel.
 246
 247 .. kernel-doc:: drivers/scsi/scsi_transport_fc.c
 248    :export:
 249
 250 iSCSI transport class
 251 ~~~~~~~~~~~~~~~~~~~~~
 252
 253 The file drivers/scsi/scsi_transport_iscsi.c defines transport
 254 attributes for the iSCSI class, which sends SCSI packets over TCP/IP
 255 connections.
 256
 257 .. kernel-doc:: drivers/scsi/scsi_transport_iscsi.c
 258    :export:
 259
 260 Serial Attached SCSI (SAS) transport class
 261 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 262
 263 The file drivers/scsi/scsi_transport_sas.c defines transport
 264 attributes for Serial Attached SCSI, a variant of SATA aimed at large
 265 high-end systems.
 266
 267 The SAS transport class contains common code to deal with SAS HBAs, an
 268 aproximated representation of SAS topologies in the driver model, and
 269 various sysfs attributes to expose these topologies and management
 270 interfaces to userspace.
 271
 272 In addition to the basic SCSI core objects this transport class
 273 introduces two additional intermediate objects: The SAS PHY as
 274 represented by struct sas_phy defines an "outgoing" PHY on a SAS HBA or
 275 Expander, and the SAS remote PHY represented by struct sas_rphy defines
 276 an "incoming" PHY on a SAS Expander or end device. Note that this is
 277 purely a software concept, the underlying hardware for a PHY and a
 278 remote PHY is the exactly the same.
 279
 280 There is no concept of a SAS port in this code, users can see what PHYs
 281 form a wide port based on the port_identifier attribute, which is the
 282 same for all PHYs in a port.
 283
 284 .. kernel-doc:: drivers/scsi/scsi_transport_sas.c
 285    :export:
 286
 287 SATA transport class
 288 ~~~~~~~~~~~~~~~~~~~~
 289
 290 The SATA transport is handled by libata, which has its own book of
 291 documentation in this directory.
 292
 293 Parallel SCSI (SPI) transport class
 294 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 295
 296 The file drivers/scsi/scsi_transport_spi.c defines transport
 297 attributes for traditional (fast/wide/ultra) SCSI busses.
 298
 299 .. kernel-doc:: drivers/scsi/scsi_transport_spi.c
 300    :export:
 301
 302 SCSI RDMA (SRP) transport class
 303 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 304
 305 The file drivers/scsi/scsi_transport_srp.c defines transport
 306 attributes for SCSI over Remote Direct Memory Access.
 307
 308 .. kernel-doc:: drivers/scsi/scsi_transport_srp.c
 309    :export:
 310
 311 SCSI lower layer
 312 ================
 313
 314 Host Bus Adapter transport types
 315 --------------------------------
 316
 317 Many modern device controllers use the SCSI command set as a protocol to
 318 communicate with their devices through many different types of physical
 319 connections.
 320
 321 In SCSI language a bus capable of carrying SCSI commands is called a
 322 "transport", and a controller connecting to such a bus is called a "host
 323 bus adapter" (HBA).
 324
 325 Debug transport
 326 ~~~~~~~~~~~~~~~
 327
 328 The file drivers/scsi/scsi_debug.c simulates a host adapter with a
 329 variable number of disks (or disk like devices) attached, sharing a
 330 common amount of RAM. Does a lot of checking to make sure that we are
 331 not getting blocks mixed up, and panics the kernel if anything out of
 332 the ordinary is seen.
 333
 334 To be more realistic, the simulated devices have the transport
 335 attributes of SAS disks.
 336
 337 For documentation see http://sg.danny.cz/sg/sdebug26.html
 338
 339 todo
 340 ~~~~
 341
 342 Parallel (fast/wide/ultra) SCSI, USB, SATA, SAS, Fibre Channel,
 343 FireWire, ATAPI devices, Infiniband, I20, iSCSI, Parallel ports,
 344 netlink...