The Linux SCSI Generic (sg) Driver
[2021-11-10] release of sg3_utils-1.47 . See sg3_utils page.
[2021-08-23] Updated sg version 4 driver. See the sg_v40 page, this driver is in development
[2021-05-05] lsscsi-0.32 released, see lsscsi page.
[2021-04-21] release of ddpt version 0.97 . See ddpt page.
[2021-04-21] release of sdparm version 1.12 . See sdparm page
[2021-04-16] Updated scsi_debug page for lk 5.9 through , 5.12 additions
[2021-04-08] This site (i.e. danny.cz ) now supports https , please adjust your browsers; caches may need to be cleared
[2020-03-19] release of smp_utils version 0.99 . See smp_utils page
[2020-02-20] lsscsi-0.31 released, see lsscsi page.
The author’s various SCSI related packages are now mirrored on github.com . The primary repositories remain in subversion on the author’s equipment. The sg3_utils and lsscsi packages are mirrored on Hannes Reinecke’s site at github : https://github.com/hreinecke/sg3_utils in the master (default) branch. The author continues to track progress with a subversion revision number which is a sequential number currently at 891 for sg3_utils. The github sg3_utils package’s ChangeLog file shows where the mirror is «at» and currently that is revision 841 dated 20200210, several commits behind the author’s repository. The other sg3_utils git branches may be of interest to users and relate to Hannes’ work at SUSE Labs. Most work in those other branches will be merged into the master branch in time. Also found at that location is the lsscsi mirror. Both packages may have later versions on this site (as tarballs in the Downloads section of the links given above). So it might be worthwhile to check both locations.
The author also has a github account at https://github.com/doug-gilbert which has mirrors for the sdparm, ddpt and smp_utils packages and alternative mirrors for sg3_utils and lsscsi. The sdparm and ddpt packages depend on a library from sg3_utils.
So, for example to build sdparm, clone the github sdparm and sg3_utils_lib repositories to the build machine; then from sg3_utils_lib clone, copy the include/ and lib/ directories with those names and contents over to the sdparm clone, under the main directory. So that main directory should end up at least containing these sub-directories: src/, doc/, lib/ and include/. The sdparm package should be then ready to build. IMO, contrary to much online propaganda, git is not better in all respects than subversion, especially for non-distributed development. In this case the author uses subversion’s «externals» feature to include the library sub-tree of sg3_utils in the source trees of sdparm and ddpt. There is no exact parallel to this feature in git.
Packages will still have major releases done through this site. For example, that will be release 1.46 for sg3_utils . The release will have source tarballs and Debian and Redhat packages for Linux. There will also be a tarball of Windows executable(s) typically built with MinGW. Also there is an attempt to publicise the releases on related newsgroups (e.g. Note that the subversion revision number stops increasing in the ChangeLog once a release has been made, and a new paragraph will appear at the top of the ChangeLog when revisions are committed for the next release.
Introduction
The Linux sg driver is a upper level SCSI subsystem device driver that is used primarily to handle devices _not_ covered by the other upper level drivers: sd (disks), st (tapes) and sr (CDROMs and DVDs). The sg driver is used for enclosure management, cd writers, applications that read cd audio digitally and scanners. Sg can also be used for less usual tasks performed on disks, tapes and cdroms. Sg is a character device driver which, in some contexts, gives it advantages over block device drivers such as sd and sr. The interface of sg is at the level of SCSI command requests and their associated responses.
The term SCSI has several meaning depending on the context. This leads to confusion. One practical way of defining it today is everything that the T10 INCITS committee controls, see www.t10.org . Probably the most succinct overview is this standards architecture page . For practical purposes a «SCSI device» in Linux is any device that uses the Linux SCSI subsystem and this often includes SATA disks.
From about Linux kernel 2.6.24, there is an alternate SCSI pass-through driver called «bsg» (block SCSI generic driver). The bsg driver has device names of the form /dev/bsg/0:1:2:3 and supports the SG_IO ioctl with the sg version 3 interface. The bsg driver also supports the sg version 4 interface which at this time the sg driver does not. Amongst other improvements the sg version 4 interface supports SCSI bidirectional commands. All recent «sg» user space packages (i.e. sg3_utils, sdparm, ddpt and smp_utils) work equally well on both sg and bsg device names.
Background
The original driver was written by Lawrence Foard in 1992 and remained unchanged for several years. In August 1998 Heiko Eissfeldt and Joerg Schilling started working on enhancements to this driver. Soon after, the author became involved and these efforts culminated in a new sg driver being placed in Linux kernel 2.2.6 which was released on 16th April 1999. It contains the first major upgrade to the SCSI generic packet device driver («sg») since 1992. This new driver has a super-set of the original interface and the semantics of the implementation are very similar. Hence it offers a high degree of backward compatibility with the original driver.
The major reason for introducing a new sg driver into the 2.2 series of kernels was the problem that the original device driver was having finding memory. This driver improves the situation by using scatter gather, memory above the 16 MBytes level and memory from the scsi dma pool as appropriate. Other drivers were affected by these memory problems (especially those associated with ISA hardware). In kernel 2.2.10 H.J. Lu introduced a new kernel memory allocator that alleviated many of these memory problems.
On 4th January 2001 the Linux 2.4.0 kernel was introduced and it contained the «version 3» sg driver that is described below.
On 17th December 2003 the Linux 2.6.0 kernel was introduced and it also contained the «version 3» sg driver that is described below. The SG_IO ioctl was implemented in the block layer and in several other «char» SCSI drivers (e.g. the st driver for tapes). Hence many programs can use primary device nodes (e.g. /dev/hdd for an ATAPI cd/dvd writer) to send SCSI command via the SG_IO ioctl. The sg driver still permits a clean pass through interface to all devices that use the Linux SCSI subsystem.
Features
The following enhancements have been added (in lk 2.2.6): scatter gather, command queueing, per file descriptor sequencing (was per device) and asynchronous notification. Scatter gather allows large buffers (previously limited to 128 KB on i386) to be used. Scatter gather is also a lot more «kernel friendly». The original driver used a single large buffer which made it impossible to run 2 or more sg-based applications at the same time. With the new driver a buffer is reserved for each file descriptor guaranteeing that at least that buffer size will be available for each request on the file descriptor. A user may request a larger buffer size on any particular request but runs the (usually remote) risk of an out of memory (ENOMEM) error.
A «version 3» sg driver was introduced in Linux kernel 2.4.0 . It adds a new interface that allows more control over SCSI commands and returns more information about their performance. This driver is present in Linux kernel 2.4.0 . A separate version with reduced capabilities is available for the 2.2 series kernels. Features include: a simplified SG_IO ioctl, larger sense buffer, residual DMA count, 16 byte (or longer) commands, direct IO support, command duration timing and a «proc_fs» interface. Naturally it is backward compatible with applications based on the sg interface in the lk 2.2 series and earlier.
In the lk 2.6 series the SG_IO ioctl has been replicated (with a slightly reduced feature set) in the block subsystem. This allows the SG_IO ioctl to be used on block devices such as /dev/sda and /dev/scd0. In lk 2.6.6 the SG_IO ioctl became available in the st upper level SCSI subsystem driver (for tapes). See the sg_io page.
SG device driver downloads
The following table summarizes the different versions of the sg device driver that are available. If you wish to use one of these tarballs then untar it in /usr/src/linux (or wherever the top of your kernel tree is). As a precaution you may wish to copy the files include/scsi/sg.h and drivers/scsi/sg.c to other names. This will facilitate reversing the patch if required. For information about the differences between versions see the history section at the top of the include/scsi/sg.h file.
Table 1. sg device drivers
Sg driver
version+tarball
sg version 3 backported to lk 2.2
SCSI Generic (sg) driver¶
The SCSI Generic driver (sg) is one of the four «high level» SCSI device drivers along with sd, st and sr (disk, tape and CD-ROM respectively). Sg is more generalized (but lower level) than its siblings and tends to be used on SCSI devices that don’t fit into the already serviced categories. Thus sg is used for scanners, CD writers and reading audio CDs digitally amongst other things.
Rather than document the driver’s interface here, version information is provided plus pointers (i.e. URLs) where to find documentation and examples.
Major versions of the sg driver¶
- sg version 1 (original) from 1992 to early 1999 (lk 2.2.5) . It is based in the sg_header interface structure.
- sg version 2 from lk 2.2.6 in the 2.2 series. It is based on an extended version of the sg_header interface structure.
- sg version 3 found in the lk 2.4 series (and the lk 2.5 series). It adds the sg_io_hdr interface structure.
Sg driver documentation¶
The most recent documentation of the sg driver is kept at
This describes the sg version 3 driver found in the lk 2.4 series.
Documentation (large version) for the version 2 sg driver found in the lk 2.2 series can be found at
The original documentation for the sg driver (prior to lk 2.2.6) can be found in the LDP archives at
A more general description of the Linux SCSI subsystem of which sg is a part can be found at https://www.tldp.org/HOWTO/SCSI-2.4-HOWTO .
Example code and utilities¶
There are two packages of sg utilities:
| sg3_utils | for the sg version 3 driver found in lk 2.4 |
| sg_utils | for the sg version 2 (and original) driver found in lk 2.2 and earlier |
Both packages will work in the lk 2.4 series. However, sg3_utils offers more capabilities. They can be found at: https://sg.danny.cz/sg/sg3_utils.html and freecode.com
Another approach is to look at the applications that use the sg driver. These include cdrecord, cdparanoia, SANE and cdrdao.
Mapping of Linux kernel versions to sg driver versions¶
Here is a list of Linux kernels in the 2.4 series that had the new version of the sg driver:
- lk 2.4.0 : sg version 3.1.17
- lk 2.4.7 : sg version 3.1.19
- lk 2.4.10 : sg version 3.1.20 1
- lk 2.4.17 : sg version 3.1.22
There were 3 changes to sg version 3.1.20 by third parties in the next six Linux kernel versions.
For reference here is a list of Linux kernels in the 2.2 series that had the new version of the sg driver:
- lk 2.2.0 : original sg version [with no version number]
- lk 2.2.6 : sg version 2.1.31
- lk 2.2.8 : sg version 2.1.32
- lk 2.2.10 : sg version 2.1.34 [SG_GET_VERSION_NUM ioctl first appeared]
- lk 2.2.14 : sg version 2.1.36
- lk 2.2.16 : sg version 2.1.38
- lk 2.2.17 : sg version 2.1.39
- lk 2.2.20 : sg version 2.1.40
The lk 2.5 development series currently contains sg version 3.5.23 which is functionally equivalent to sg version 3.1.22 found in lk 2.4.17.