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