0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 =======================================
0004 Notes on Linux SCSI Generic (sg) driver
0005 =======================================
0006
0007 20020126
0008
0009 Introduction
0010 ============
0011 The SCSI Generic driver (sg) is one of the four "high level" SCSI device
0012 drivers along with sd, st and sr (disk, tape and CDROM respectively). Sg
0013 is more generalized (but lower level) than its siblings and tends to be
0014 used on SCSI devices that don't fit into the already serviced categories.
0015 Thus sg is used for scanners, CD writers and reading audio CDs digitally
0016 amongst other things.
0017
0018 Rather than document the driver's interface here, version information
0019 is provided plus pointers (i.e. URLs) where to find documentation
0020 and examples.
0021
0022
0023 Major versions of the sg driver
0024 ===============================
0025 There are three major versions of sg found in the linux kernel (lk):
0026 - sg version 1 (original) from 1992 to early 1999 (lk 2.2.5) .
0027 It is based in the sg_header interface structure.
0028 - sg version 2 from lk 2.2.6 in the 2.2 series. It is based on
0029 an extended version of the sg_header interface structure.
0030 - sg version 3 found in the lk 2.4 series (and the lk 2.5 series).
0031 It adds the sg_io_hdr interface structure.
0032
0033
0034 Sg driver documentation
0035 =======================
0036 The most recent documentation of the sg driver is kept at the Linux
0037 Documentation Project's (LDP) site:
0038
0039 - http://www.tldp.org/HOWTO/SCSI-Generic-HOWTO
0040
0041 This describes the sg version 3 driver found in the lk 2.4 series.
0042
0043 The LDP renders documents in single and multiple page HTML, postscript
0044 and pdf. This document can also be found at:
0045
0046 - http://sg.danny.cz/sg/p/sg_v3_ho.html
0047
0048 Documentation for the version 2 sg driver found in the lk 2.2 series can
0049 be found at http://sg.danny.cz/sg/. A larger version
0050 is at: http://sg.danny.cz/sg/p/scsi-generic_long.txt.
0051
0052 The original documentation for the sg driver (prior to lk 2.2.6) can be
0053 found at http://www.torque.net/sg/p/original/SCSI-Programming-HOWTO.txt
0054 and in the LDP archives.
0055
0056 A changelog with brief notes can be found in the
0057 /usr/src/linux/include/scsi/sg.h file. Note that the glibc maintainers copy
0058 and edit this file (removing its changelog for example) before placing it
0059 in /usr/include/scsi/sg.h . Driver debugging information and other notes
0060 can be found at the top of the /usr/src/linux/drivers/scsi/sg.c file.
0061
0062 A more general description of the Linux SCSI subsystem of which sg is a
0063 part can be found at http://www.tldp.org/HOWTO/SCSI-2.4-HOWTO .
0064
0065
0066 Example code and utilities
0067 ==========================
0068 There are two packages of sg utilities:
0069
0070 ========= ==========================================================
0071 sg3_utils for the sg version 3 driver found in lk 2.4
0072 sg_utils for the sg version 2 (and original) driver found in lk 2.2
0073 and earlier
0074 ========= ==========================================================
0075
0076 Both packages will work in the lk 2.4 series however sg3_utils offers more
0077 capabilities. They can be found at: http://sg.danny.cz/sg/sg3_utils.html and
0078 freecode.com
0079
0080 Another approach is to look at the applications that use the sg driver.
0081 These include cdrecord, cdparanoia, SANE and cdrdao.
0082
0083
0084 Mapping of Linux kernel versions to sg driver versions
0085 ======================================================
0086 Here is a list of linux kernels in the 2.4 series that had new version
0087 of the sg driver:
0088
0089 - lk 2.4.0 : sg version 3.1.17
0090 - lk 2.4.7 : sg version 3.1.19
0091 - lk 2.4.10 : sg version 3.1.20 [#]_
0092 - lk 2.4.17 : sg version 3.1.22
0093
0094 .. [#] There were 3 changes to sg version 3.1.20 by third parties in the
0095 next six linux kernel versions.
0096
0097 For reference here is a list of linux kernels in the 2.2 series that had
0098 new version of the sg driver:
0099
0100 - lk 2.2.0 : original sg version [with no version number]
0101 - lk 2.2.6 : sg version 2.1.31
0102 - lk 2.2.8 : sg version 2.1.32
0103 - lk 2.2.10 : sg version 2.1.34 [SG_GET_VERSION_NUM ioctl first appeared]
0104 - lk 2.2.14 : sg version 2.1.36
0105 - lk 2.2.16 : sg version 2.1.38
0106 - lk 2.2.17 : sg version 2.1.39
0107 - lk 2.2.20 : sg version 2.1.40
0108
0109 The lk 2.5 development series has recently commenced and it currently
0110 contains sg version 3.5.23 which is functionally equivalent to sg
0111 version 3.1.22 found in lk 2.4.17.
0112
0113
0114 Douglas Gilbert
0115
0116 26th January 2002
0117
0118 dgilbert@interlog.com
