The Linux SCSI
Generic (sg) Driver
- The Linux SCSI Generic (sg) Driver
- News
- Introduction
- Background
- Features
- SG device driver downloads
- Utilities: sg3_utils and
sg_utils
- Sg related pages
- External references
News
[2016-07-05] git mirrors: see Download section in sg3_utils and lsscsi pages
[2016-04-12] beta version of sg3_utils-1.43b1, see
ChangeLog in tarball
[2016-02-22] release sdparm version 1.10 , see the sdparm page
[2016-02-17] release sg3_utils version 1.42, see the sg3_utils page
[2016-02-09] beta version of ddpt-0.96b3,
see ChangeLog in tarball
[2016-02-02] beta version of smp_utils-0.99b4, see
ChangeLog in tarball
[2015-12-03] beta version of lsscsi-0.29b1,
see ChangeLog in tarball
[2014-12-27] release ddpt version 0.95, see ddpt
page
[2014-11-27] release lsscsi version 0.28 , see lsscsi page
[2014-09-30] update tools page: brief
summary of various storage/scsi tools
[2014-05-26] release smp_utils 0.98 (for SAS expander management),
see smp_utils page
[2010-09-13] add device naming page
[2008-10-01] sg pages find a new home at http://sg.danny.cz/sg/
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.
For the Linux kernel 2.2 series, the current production
version of the sg driver is 2.1.39 . All sg drivers for the 2.2
series of kernels (including the original) are interchangeable
(but see final section on this page about Red Hat 6.2 and Mandrake
7.1). So, for example, sg22orig.tgz can be put in lk 2.2.17 while,
on the other hand, sg2140.tgz can be put in lk 2.2.0 .
For the Linux kernel 2.4 series, the current production version
of sg is 3.1.25 (in lk 2.4.23->32).
For the Linux kernel 2.6 series, the current production version
of sg is 3.5.34 .
Older versions can be obtained from this directory. A sub
directory called "original" contains the original driver (i.e.
prior to linux kernel 2.2.6) and its HOWTO document.
Utilities:
sg3_utils and sg_utils
These packages contain multiple utilities, all with command line
interfaces. They send one one more SCSI commands to the nominated
device and output the response including error reports if the
command failed. The name of the SCSI command executed is typically
reflected in the name of the utility; for example: "sg_inq" sends a
SCSI INQUIRY command and decodes its response. These utilities were
originally written for the Linux operating system. In sg3_utils
version 1.19 a subset of the utilities were ported to FreeBSD and
Tru64; in version 1.22 a similar subset of the utilities were ported
to Windows; and in version 1.24 a Solaris port was added.
The most recent package is called sg3_utils and it uses the
sg "version 3" interface (sometimes known as the SG_IO interface) in
linux. This interface is in lk 2.4.0 and later kernels,
including the lk 2.6, 3 and 4 series. All new features are being
added into sg3_utils (i.e. it is still being
actively developed). Many of the utilities in sg3_utils (versions
>= 1.02) can be used directly on block devices (e.g. sg_inq /dev/sda) in the lk
2.6 series. The sg_dd utility is at
a slightly higher level issuing SCSI READ and WRITE commands to copy
data, mimicking the Unix dd command. See the sg3_utils package page for more details.
The older (and original) package is called sg_utils and
it uses the sg version 2 interface found linux kernel version
2.2.6 and onward. Over half of those utilities will also work on
the original sg device driver (at least back to the lk 2.0
series). If required, "make common" will produce the subset that
will work on the whole lk 2.x series. Since the sg "version 3"
device driver still maintains the original interface, the sg_utils
package will continue to work in the lk 2.4 and lk 2.6 series .
This package is now in maintenance mode, only bugs will be fixed.
See this page for more details.
The latest versions, packaged in tarballs, source, binary rpms and
debian packages are given in the following table. They contain
README and CHANGELOG files and man pages. The tarball contains
a "spec" file for building rpms and a debian directory containing
build information. Here is the most recently released
sg3_utils CHANGELOG .
See the sg3_utils page for more
packages (e.g. 64 bit versions of Debian, Redhat and Windows binary
packages) plus older versions.
Sg related pages
Following are some links to related pages on this site:
- Full sg version 3 documentation for lk 2.4 series is now
available. It is in DocBook format (html rendering): sg_v3_ho.html (ps, pdf and text
renderings also in same directory). This document is also
available as LDP's SCSI-Generic-HOWTO
Here
is
documentation
specific
to
the
sg_io ioctl, especially in the lk
2.6 series.
- Older Sg version 3 documentation
for lk 2.4 series (now superseded by the DocBook version above)
- lsscsi command for the lk
2.6 series. Lists SCSI devices or SCSI hosts.
- sdparm utility to view and change
mode pages, view VPD pages and send commands (for lk 2.6 and 2.4
series)
- ddpt utility which is dd-like which is
able to access SCSI devices at the SCSI command level
- sg3_utils package of utilities
that send SCSI commands
- smp_utils package of utilities
for Serial Attached SCSI (SAS) SMP functions
- the tools page contains information
about many scsi/storage packages from various sources
- Some notes about the "version 3"
sg driver found in the lk 2.4 series (including mmap notes).
- scsi_debug LLD (adapter) driver
for simulating lots of disk and doing tests in the lk 2.6 and lk
3 series. Here is the scsi_debug
driver for the lk 2.4 series.
- scsi_ses LLD (adapter) driver for
simulating an enclosure services (SES) device.
- Timings for direct and indirect
IO (as used by sg); these are old and should be updated
- Some fast copy options for disks
(including raw devices)
- devfs and SCSI in lk
2.3.46 and the lk 2.4 series. Devfs has been replaced by udev
and hotplug in the lk 2.6 series
- description of the Linux SCSI subsystem in
the lk 2.4 series. There is a single page html rendering:
SCSI-2.4-HOWTO.html plus ps, pdf and text renderings in the same
directory. This document has become the LDP's SCSI-2.4-HOWTO
. The version on this site may be more recent.
- linux 2.6 series SCSI mid to lower level API document can be
found in the Documentation/scsi/scsi_mid_low_api.txt file in the
kernel source tree.
- smartmontools for SCSI article .
- Abridged and longer documentation for sg
driver in lk 2.2 series (describes sg version 2.1.39)
- A FAQ including current project
status, bug fixes and other useful patches
External
references
Here are some useful links to related information held at other
sites:
- www.t10.org is
a very important site for SCSI related information. It contains
SCSI 2 and 3 draft standards.
- every wonder what all those acronyms mean and how they relate,
see this diagram at
t10.org .
- www.scsita.org is the SCSI
Trade Association. There is an interesting tutorial on Serial
Attached SCSI (SAS) there.
- www.andante.org/scsi.html
is Eric Youngdale's site. Eric is primarily responsible for the
Linux SCSI architecture and its mid-level implementation in the
2.2 and 2.4 series of kernels
- Kurt Garloff has several pages
with Linux SCSI themes (including the scsidev, scsiinfo and
rescan-scsi-bus programs).
- The Scsi Command Utility (scu)
is quite comprehensive and is ported to several OSes including
Linux. Its home page can be found here
.
- The newsgroup linux-scsi@vger.kernel.org is the appropriate
place to discuss Linux SCSI related issues.
- The MAINTAINERS source file in the top level of the linux
kernel source tree contains up to date information about who
maintains what and where information can be found. Links to SCSI
adapter information are also in that file. SCSI documentation
within the kernel source has been moved to the
Documentation/scsi directory in the lk 2.6 series.
Douglas
Gilbert can be emailed at that address.
Last updated: 5th July 2016, 12:30 [UTC-4]