GNU Linux-libre 4.14.266-gnu1
[releases.git] / 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...