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