xref: /linux/Documentation/scsi/scsi-generic.rst (revision 2da68a77) 
1.. SPDX-License-Identifier: GPL-2.0
2
3=======================================
4Notes on Linux SCSI Generic (sg) driver
5=======================================
6
7                                                        20020126
8
9Introduction
10============
11The SCSI Generic driver (sg) is one of the four "high level" SCSI device
12drivers along with sd, st and sr (disk, tape and CDROM respectively). Sg
13is more generalized (but lower level) than its siblings and tends to be
14used on SCSI devices that don't fit into the already serviced categories.
15Thus sg is used for scanners, CD writers and reading audio CDs digitally
16amongst other things.
17
18Rather than document the driver's interface here, version information
19is provided plus pointers (i.e. URLs) where to find documentation
20and examples.
21
22
23Major versions of the sg driver
24===============================
25There are three major versions of sg found in the linux kernel (lk):
26      - sg version 1 (original) from 1992 to early 1999 (lk 2.2.5) .
27	It is based in the sg_header interface structure.
28      - sg version 2 from lk 2.2.6 in the 2.2 series. It is based on
29	an extended version of the sg_header interface structure.
30      - sg version 3 found in the lk 2.4 series (and the lk 2.5 series).
31	It adds the sg_io_hdr interface structure.
32
33
34Sg driver documentation
35=======================
36The most recent documentation of the sg driver is kept at the Linux
37Documentation Project's (LDP) site:
38
39- http://www.tldp.org/HOWTO/SCSI-Generic-HOWTO
40
41This describes the sg version 3 driver found in the lk 2.4 series.
42
43The LDP renders documents in single and multiple page HTML, postscript
44and pdf. This document can also be found at:
45
46- http://sg.danny.cz/sg/p/sg_v3_ho.html
47
48Documentation for the version 2 sg driver found in the lk 2.2 series can
49be found at http://sg.danny.cz/sg/. A larger version
50is at: http://sg.danny.cz/sg/p/scsi-generic_long.txt.
51
52The original documentation for the sg driver (prior to lk 2.2.6) can be
53found at http://www.torque.net/sg/p/original/SCSI-Programming-HOWTO.txt
54and in the LDP archives.
55
56A changelog with brief notes can be found in the
57/usr/src/linux/include/scsi/sg.h file. Note that the glibc maintainers copy
58and edit this file (removing its changelog for example) before placing it
59in /usr/include/scsi/sg.h . Driver debugging information and other notes
60can be found at the top of the /usr/src/linux/drivers/scsi/sg.c file.
61
62A more general description of the Linux SCSI subsystem of which sg is a
63part can be found at http://www.tldp.org/HOWTO/SCSI-2.4-HOWTO .
64
65
66Example code and utilities
67==========================
68There are two packages of sg utilities:
69
70    =========   ==========================================================
71    sg3_utils   for the sg version 3 driver found in lk 2.4
72    sg_utils    for the sg version 2 (and original) driver found in lk 2.2
73                and earlier
74    =========   ==========================================================
75
76Both packages will work in the lk 2.4 series however sg3_utils offers more
77capabilities. They can be found at: http://sg.danny.cz/sg/sg3_utils.html and
78freecode.com
79
80Another approach is to look at the applications that use the sg driver.
81These include cdrecord, cdparanoia, SANE and cdrdao.
82
83
84Mapping of Linux kernel versions to sg driver versions
85======================================================
86Here is a list of linux kernels in the 2.4 series that had new version
87of the sg driver:
88
89     - lk 2.4.0 : sg version 3.1.17
90     - lk 2.4.7 : sg version 3.1.19
91     - lk 2.4.10 : sg version 3.1.20 [#]_
92     - lk 2.4.17 : sg version 3.1.22
93
94.. [#] There were 3 changes to sg version 3.1.20 by third parties in the
95       next six linux kernel versions.
96
97For reference here is a list of linux kernels in the 2.2 series that had
98new version of the sg driver:
99
100     - lk 2.2.0 : original sg version [with no version number]
101     - lk 2.2.6 : sg version 2.1.31
102     - lk 2.2.8 : sg version 2.1.32
103     - lk 2.2.10 : sg version 2.1.34 [SG_GET_VERSION_NUM ioctl first appeared]
104     - lk 2.2.14 : sg version 2.1.36
105     - lk 2.2.16 : sg version 2.1.38
106     - lk 2.2.17 : sg version 2.1.39
107     - lk 2.2.20 : sg version 2.1.40
108
109The lk 2.5 development series has recently commenced and it currently
110contains sg version 3.5.23 which is functionally equivalent to sg
111version 3.1.22 found in lk 2.4.17.
112
113
114Douglas Gilbert
115
11626th January 2002
117
118dgilbert@interlog.com
119