Loading...
1.. SPDX-License-Identifier: GPL-2.0
2
3========================
4SCSI 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 CD-ROM 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
37
38- https://sg.danny.cz/sg/
39
40This describes the sg version 3 driver found in the lk 2.4 series.
41
42Documentation (large version) for the version 2 sg driver found in the
43lk 2.2 series can be found at
44
45- https://sg.danny.cz/sg/p/scsi-generic_long.txt.
46
47The original documentation for the sg driver (prior to lk 2.2.6) can be
48found in the LDP archives at
49
50- https://tldp.org/HOWTO/archived/SCSI-Programming-HOWTO/index.html
51
52A more general description of the Linux SCSI subsystem of which sg is a
53part can be found at https://www.tldp.org/HOWTO/SCSI-2.4-HOWTO .
54
55
56Example code and utilities
57==========================
58There are two packages of sg utilities:
59
60 ========= ==========================================================
61 sg3_utils for the sg version 3 driver found in lk 2.4
62 sg_utils for the sg version 2 (and original) driver found in lk 2.2
63 and earlier
64 ========= ==========================================================
65
66Both packages will work in the lk 2.4 series. However, sg3_utils offers more
67capabilities. They can be found at: https://sg.danny.cz/sg/sg3_utils.html and
68freecode.com
69
70Another approach is to look at the applications that use the sg driver.
71These include cdrecord, cdparanoia, SANE and cdrdao.
72
73
74Mapping of Linux kernel versions to sg driver versions
75======================================================
76Here is a list of Linux kernels in the 2.4 series that had the new version
77of the sg driver:
78
79 - lk 2.4.0 : sg version 3.1.17
80 - lk 2.4.7 : sg version 3.1.19
81 - lk 2.4.10 : sg version 3.1.20 [#]_
82 - lk 2.4.17 : sg version 3.1.22
83
84.. [#] There were 3 changes to sg version 3.1.20 by third parties in the
85 next six Linux kernel versions.
86
87For reference here is a list of Linux kernels in the 2.2 series that had
88the new version of the sg driver:
89
90 - lk 2.2.0 : original sg version [with no version number]
91 - lk 2.2.6 : sg version 2.1.31
92 - lk 2.2.8 : sg version 2.1.32
93 - lk 2.2.10 : sg version 2.1.34 [SG_GET_VERSION_NUM ioctl first appeared]
94 - lk 2.2.14 : sg version 2.1.36
95 - lk 2.2.16 : sg version 2.1.38
96 - lk 2.2.17 : sg version 2.1.39
97 - lk 2.2.20 : sg version 2.1.40
98
99The lk 2.5 development series currently contains sg version 3.5.23
100which is functionally equivalent to sg version 3.1.22 found in lk 2.4.17.
101
102
103Douglas Gilbert
104
10526th January 2002
106
107dgilbert@interlog.com
1.. SPDX-License-Identifier: GPL-2.0
2
3========================
4SCSI 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 CD-ROM 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
37
38- https://sg.danny.cz/sg/
39
40This describes the sg version 3 driver found in the lk 2.4 series.
41
42Documentation (large version) for the version 2 sg driver found in the
43lk 2.2 series can be found at
44
45- https://sg.danny.cz/sg/p/scsi-generic_long.txt.
46
47The original documentation for the sg driver (prior to lk 2.2.6) can be
48found in the LDP archives at
49
50- https://tldp.org/HOWTO/archived/SCSI-Programming-HOWTO/index.html
51
52A more general description of the Linux SCSI subsystem of which sg is a
53part can be found at https://www.tldp.org/HOWTO/SCSI-2.4-HOWTO .
54
55
56Example code and utilities
57==========================
58There are two packages of sg utilities:
59
60 ========= ==========================================================
61 sg3_utils for the sg version 3 driver found in lk 2.4
62 sg_utils for the sg version 2 (and original) driver found in lk 2.2
63 and earlier
64 ========= ==========================================================
65
66Both packages will work in the lk 2.4 series. However, sg3_utils offers more
67capabilities. They can be found at: https://sg.danny.cz/sg/sg3_utils.html and
68freecode.com
69
70Another approach is to look at the applications that use the sg driver.
71These include cdrecord, cdparanoia, SANE and cdrdao.
72
73
74Mapping of Linux kernel versions to sg driver versions
75======================================================
76Here is a list of Linux kernels in the 2.4 series that had the new version
77of the sg driver:
78
79 - lk 2.4.0 : sg version 3.1.17
80 - lk 2.4.7 : sg version 3.1.19
81 - lk 2.4.10 : sg version 3.1.20 [#]_
82 - lk 2.4.17 : sg version 3.1.22
83
84.. [#] There were 3 changes to sg version 3.1.20 by third parties in the
85 next six Linux kernel versions.
86
87For reference here is a list of Linux kernels in the 2.2 series that had
88the new version of the sg driver:
89
90 - lk 2.2.0 : original sg version [with no version number]
91 - lk 2.2.6 : sg version 2.1.31
92 - lk 2.2.8 : sg version 2.1.32
93 - lk 2.2.10 : sg version 2.1.34 [SG_GET_VERSION_NUM ioctl first appeared]
94 - lk 2.2.14 : sg version 2.1.36
95 - lk 2.2.16 : sg version 2.1.38
96 - lk 2.2.17 : sg version 2.1.39
97 - lk 2.2.20 : sg version 2.1.40
98
99The lk 2.5 development series currently contains sg version 3.5.23
100which is functionally equivalent to sg version 3.1.22 found in lk 2.4.17.
101
102
103Douglas Gilbert
104
10526th January 2002
106
107dgilbert@interlog.com