Commit | Line | Data |
---|---|---|
d4d79340 MCC |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | ======================================= | |
4 | Notes on Linux SCSI Generic (sg) driver | |
5 | ======================================= | |
6 | ||
1da177e4 | 7 | 20020126 |
d4d79340 | 8 | |
1da177e4 LT |
9 | Introduction |
10 | ============ | |
11 | The SCSI Generic driver (sg) is one of the four "high level" SCSI device | |
12 | drivers along with sd, st and sr (disk, tape and CDROM respectively). Sg | |
13 | is more generalized (but lower level) than its siblings and tends to be | |
14 | used on SCSI devices that don't fit into the already serviced categories. | |
15 | Thus sg is used for scanners, CD writers and reading audio CDs digitally | |
16 | amongst other things. | |
17 | ||
18 | Rather than document the driver's interface here, version information | |
19 | is provided plus pointers (i.e. URLs) where to find documentation | |
20 | and examples. | |
21 | ||
22 | ||
23 | Major versions of the sg driver | |
24 | =============================== | |
25 | There are three major versions of sg found in the linux kernel (lk): | |
d4d79340 | 26 | - sg version 1 (original) from 1992 to early 1999 (lk 2.2.5) . |
1da177e4 LT |
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 | ||
34 | Sg driver documentation | |
35 | ======================= | |
36 | The most recent documentation of the sg driver is kept at the Linux | |
d4d79340 MCC |
37 | Documentation Project's (LDP) site: |
38 | ||
39 | - http://www.tldp.org/HOWTO/SCSI-Generic-HOWTO | |
40 | ||
1da177e4 | 41 | This describes the sg version 3 driver found in the lk 2.4 series. |
d4d79340 | 42 | |
1da177e4 LT |
43 | The LDP renders documents in single and multiple page HTML, postscript |
44 | and pdf. This document can also be found at: | |
d4d79340 MCC |
45 | |
46 | - http://sg.danny.cz/sg/p/sg_v3_ho.html | |
1da177e4 LT |
47 | |
48 | Documentation for the version 2 sg driver found in the lk 2.2 series can | |
0ea6e611 JM |
49 | be found at http://sg.danny.cz/sg/. A larger version |
50 | is at: http://sg.danny.cz/sg/p/scsi-generic_long.txt. | |
1da177e4 LT |
51 | |
52 | The original documentation for the sg driver (prior to lk 2.2.6) can be | |
53 | found at http://www.torque.net/sg/p/original/SCSI-Programming-HOWTO.txt | |
54 | and in the LDP archives. | |
55 | ||
56 | A changelog with brief notes can be found in the | |
d4d79340 MCC |
57 | /usr/src/linux/include/scsi/sg.h file. Note that the glibc maintainers copy |
58 | and edit this file (removing its changelog for example) before placing it | |
59 | in /usr/include/scsi/sg.h . Driver debugging information and other notes | |
1da177e4 LT |
60 | can be found at the top of the /usr/src/linux/drivers/scsi/sg.c file. |
61 | ||
d4d79340 | 62 | A more general description of the Linux SCSI subsystem of which sg is a |
1da177e4 LT |
63 | part can be found at http://www.tldp.org/HOWTO/SCSI-2.4-HOWTO . |
64 | ||
65 | ||
66 | Example code and utilities | |
67 | ========================== | |
68 | There are two packages of sg utilities: | |
d4d79340 MCC |
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 | |
1da177e4 | 73 | and earlier |
d4d79340 MCC |
74 | ========= ========================================================== |
75 | ||
1da177e4 | 76 | Both packages will work in the lk 2.4 series however sg3_utils offers more |
d4d79340 | 77 | capabilities. They can be found at: http://sg.danny.cz/sg/sg3_utils.html and |
1f8ee46b | 78 | freecode.com |
1da177e4 LT |
79 | |
80 | Another approach is to look at the applications that use the sg driver. | |
81 | These include cdrecord, cdparanoia, SANE and cdrdao. | |
82 | ||
83 | ||
84 | Mapping of Linux kernel versions to sg driver versions | |
85 | ====================================================== | |
86 | Here is a list of linux kernels in the 2.4 series that had new version | |
87 | of the sg driver: | |
1da177e4 | 88 | |
d4d79340 MCC |
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. | |
1da177e4 | 96 | |
d4d79340 | 97 | For reference here is a list of linux kernels in the 2.2 series that had |
1da177e4 | 98 | new version of the sg driver: |
d4d79340 MCC |
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 | |
1da177e4 LT |
108 | |
109 | The lk 2.5 development series has recently commenced and it currently | |
110 | contains sg version 3.5.23 which is functionally equivalent to sg | |
d4d79340 | 111 | version 3.1.22 found in lk 2.4.17. |
1da177e4 LT |
112 | |
113 | ||
114 | Douglas Gilbert | |
d4d79340 | 115 | |
1da177e4 | 116 | 26th January 2002 |
d4d79340 | 117 | |
1da177e4 | 118 | dgilbert@interlog.com |