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