Documentation/scsi/scsi-generic.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 =======================================
   4 Notes on Linux SCSI Generic (sg) driver
   5 =======================================
   6
   7                                                         20020126
   8
   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):
  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
  34 Sg driver documentation
  35 =======================
  36 The most recent documentation of the sg driver is kept at the Linux
  37 Documentation Project's (LDP) site:
  38
  39 - http://www.tldp.org/HOWTO/SCSI-Generic-HOWTO
  40
  41 This describes the sg version 3 driver found in the lk 2.4 series.
  42
  43 The LDP renders documents in single and multiple page HTML, postscript
  44 and pdf. This document can also be found at:
  45
  46 - http://sg.danny.cz/sg/p/sg_v3_ho.html
  47
  48 Documentation for the version 2 sg driver found in the lk 2.2 series can
  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.
  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
  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
  60 can be found at the top of the /usr/src/linux/drivers/scsi/sg.c file.
  61
  62 A more general description of the Linux SCSI subsystem of which sg is a
  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:
  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
  73                 and earlier
  74     =========   ==========================================================
  75
  76 Both packages will work in the lk 2.4 series however sg3_utils offers more
  77 capabilities. They can be found at: http://sg.danny.cz/sg/sg3_utils.html and
  78 freecode.com
  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:
  88
  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.
  96
  97 For reference here is a list of linux kernels in the 2.2 series that had
  98 new version of the sg driver:
  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
 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
 111 version 3.1.22 found in lk 2.4.17.
 112
 113
 114 Douglas Gilbert
 115
 116 26th January 2002
 117
 118 dgilbert@interlog.com