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