The Linux SCSI Generic (sg) Driver

Time 2021-11-20 19:23:29

Web Name: The Linux SCSI Generic (sg) Driver

WebSite: http://sg.danny.cz

ID:241903

Keywords:

SCSI,Linux,The,Driver,sg,Generic,Linuxstorage,SCSI,sgdriver,passthrough

Description:

keywords:Linux storage, SCSI, sg driver, pass through
description:Linux SCSI Generic driver home page
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

[2021-11-10] release of sg3_utils-1.47 . See sg3_utilspage.

[2021-08-23] Updated sg version 4 driver. See the sg_v40page, this driver is in development

[2021-05-05] lsscsi-0.32released, see lsscsi page.

[2021-04-21] release of ddpt version 0.97 . See ddptpage.

[2021-04-21] release of sdparm version 1.12 . See sdparmpage

[2021-04-16] Updated scsi_debug pagefor 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

[2021-02-03] lsscsi-0.32beta, see lsscsi page.

[2020-03-19] release of smp_utils version 0.99 . See smp_utilspage

[2020-02-20] lsscsi-0.31 released,see lsscsi page.

The author's various SCSI related packages are now mirrored ongithub.com . The primaryrepositories remain in subversion on the author's equipment. Thesg3_utils and lsscsipackages are mirrored on Hannes Reinecke's site at github :https://github.com/hreinecke/sg3_utilsin the master (default) branch. The author continues to trackprogress with a subversion revision number which is a sequentialnumber currently at 891 for sg3_utils. The github sg3_utils package'sChangeLogfile shows where the mirror is at and currently that isrevision 841 dated 20200210, several commits behind the author'srepository. The other sg3_utils git branches may be of interest tousers and relate to Hannes' work at SUSE Labs. Most work in thoseother branches will be merged into the master branch in time. Alsofound at that location is the lsscsimirror. Both packages may have later versions on this site (astarballs in the Downloads section of the links given above). So itmight be worthwhile to check both locations.

The authoralso has a github account at https://github.com/doug-gilbertwhich has mirrors for the sdparm, ddptand smp_utils packages and alternativemirrors for sg3_utilsand lsscsi. Thesdparm and ddpt packages depend on a library from sg3_utils.

So,for example to build sdparm, clone the github sdparm andsg3_utils_lib repositories to the build machine; then fromsg3_utils_lib clone, copy the include/ andlib/ directories with those names andcontents over to the sdparm clone, under the main directory. So thatmain directory should end up at least containing thesesub-directories: src/, doc/,lib/ and include/.The sdparm package should be then ready to build. IMO, contrary tomuch online propaganda, git is not better in all respects thansubversion, especially for non-distributed development. In this casethe author uses subversion's externals feature to includethe library sub-tree of sg3_utils in the source trees of sdparm andddpt. There is no exact parallel to this feature in git.

Packageswill still have major releases done through this site. For example,that will be release 1.46 for sg3_utils . The release will havesource tarballs and Debian and Redhat packages for Linux. There willalso be a tarball of Windows executable(s) typically built withMinGW. Also there is an attempt to publicise the releases on relatednewsgroups (e.g. Note that the subversion revision number stopsincreasing in the ChangeLog once a release has been made, and a newparagraph will appear at the top of the ChangeLog when revisions arecommitted for the next release.

Introduction

The Linux sg driver is a upper level SCSI subsystem device driverthat is used primarily to handle devices _not_ covered by the otherupper 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 alsobe used for less usual tasks performed on disks, tapes and cdroms. Sgis a character device driver which, in some contexts, gives itadvantages over block device drivers such as sd and sr. The interfaceof sg is at the level of SCSI command requests and their associatedresponses.

The term SCSI has several meaning depending onthe context. This leads to confusion. One practical way of definingit today is everything that the T10 INCITS committee controls, seewww.t10.org . Probably the mostsuccinct overview is this standards architecture page. For practical purposes a SCSI device in Linux is anydevice that uses the Linux SCSI subsystem and this often includesSATA disks.

From about Linux kernel 2.6.24, there is analternate SCSI pass-through driver called bsg (block SCSIgeneric 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 3interface. The bsg driver also supports the sg version 4 interfacewhich at this time the sg driver does not. Amongst other improvementsthe sg version 4 interface supports SCSI bidirectional commands. Allrecent sg user space packages (i.e. sg3_utils, sdparm,ddpt and smp_utils) work equally well on both sg and bsg devicenames.

Background

The original driver was written by Lawrence Foard in 1992 andremained unchanged for several years. In August 1998 Heiko Eissfeldtand Joerg Schilling started working on enhancements to this driver.Soon after, the author became involved and these efforts culminatedin a new sg driver being placed in Linux kernel 2.2.6 which wasreleased on 16th April 1999. It contains the first major upgrade tothe SCSI generic packet device driver (sg) since 1992.This new driver has a super-set of the original interface and thesemantics of the implementation are very similar. Hence it offers ahigh degree of backward compatibility with the original driver.

The major reason for introducing a new sg driver into the 2.2series of kernels was the problem that the original device driver washaving finding memory. This driver improves the situation by usingscatter gather, memory above the 16 MBytes level and memory from thescsi dma pool as appropriate. Other drivers were affected by thesememory problems (especially those associated with ISA hardware). Inkernel 2.2.10 H.J. Lu introduced a new kernel memory allocator thatalleviated many of these memory problems.

On 4th January 2001 the Linux 2.4.0 kernel was introduced and itcontained the version 3 sg driver that is describedbelow.

On 17th December 2003 the Linux 2.6.0 kernel was introduced and italso contained the version 3 sg driver that is describedbelow. The SG_IO ioctl was implemented in the block layer and inseveral other char SCSI drivers (e.g. the st driver fortapes). Hence many programs can use primary device nodes (e.g./dev/hdd for an ATAPI cd/dvd writer) to send SCSI command via theSG_IO ioctl. The sg driver still permits a clean pass throughinterface to all devices that use the Linux SCSI subsystem.

Features

The following enhancements have been added (in lk 2.2.6): scattergather, command queueing, per file descriptor sequencing (was perdevice) and asynchronous notification. Scatter gather allows largebuffers (previously limited to 128 KB on i386) to be used. Scattergather is also a lot more kernel friendly. The originaldriver used a single large buffer which made it impossible to run 2or more sg-based applications at the same time. With the new driver abuffer is reserved for each file descriptor guaranteeing that atleast that buffer size will be available for each request on the filedescriptor. A user may request a larger buffer size on any particularrequest but runs the (usually remote) risk of an out of memory(ENOMEM) error.

A version 3 sg driver was introduced in Linux kernel2.4.0 . It adds a new interface that allows more control over SCSIcommands and returns more information about their performance. Thisdriver is present in Linux kernel 2.4.0 . A separate version withreduced 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 sginterface in the lk 2.2 series and earlier.

In the lk 2.6series the SG_IO ioctl has been replicated (with a slightly reducedfeature set) in the block subsystem. This allows the SG_IO ioctl tobe used on block devices such as /dev/sda and /dev/scd0. In lk 2.6.6the SG_IO ioctl became available in the st upper level SCSI subsystemdriver (for tapes). See the sg_io page.

SG device driverdownloads

The following table summarizes the different versions of the sgdevice driver that are available. If you wish to use one of thesetarballs then untar it in /usr/src/linux (or wherever the top of yourkernel tree is). As a precaution you may wish to copy the filesinclude/scsi/sg.h and drivers/scsi/sg.c to other names. This willfacilitate reversing the patch if required. For information about thedifferences between versions see the history section at the top ofthe include/scsi/sg.h file.

Table 1. sgdevice drivers

Sg driver
version+tarball

Notes

sg version 3.0.19

sg version 3 backported to lk 2.2

sg version 1.5.01

sg version 1 (original) ported to lk 2.4

sg3117_lk240

documentation and notes

sg_lk2422

bug fix

sg_lk2423

bug fix, found in lk 2.4.23-26

sg_lk2428

version found in lk 2.4.28

sg_lk2429

version found in lk 2.4.29,30,31,32

sg_lk2611

driver found in 2.6.11

sg_lk2613

driver found in 2.6.13

sg_lk2616

driver found in 2.6.16

sg_lk2618

driver found in 2.6.18

sg_lk2618scat

proposed additions including scatter_elem_sz attribute

For the Linux kernel 2.2 series, the currentproduction version of the sg driver is 2.1.39 . All sg drivers forthe 2.2 series of kernels (including the original) areinterchangeable (but see final section on this page about Red Hat 6.2and Mandrake 7.1). So, for example, sg22orig.tgz can be put in lk2.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 ofsg is 3.1.25 (in lk 2.4.23-32).

For the Linux kernel 2.6 series, the current production version ofsg is 3.5.34 .

Older versions can be obtained from thisdirectory. A sub directory called original contains theoriginal driver (i.e. prior to linux kernel 2.2.6) and its HOWTOdocument.

Utilities: sg3_utils and sg_utils

These packages contain multiple utilities, all with command lineinterfaces. They send one one more SCSI commands to the nominateddevice and output the response including error reports if the commandfailed. The name of the SCSI command executed is typically reflectedin the name of the utility; for example: sg_inq sends aSCSI INQUIRY command and decodes its response. These utilities wereoriginally written for the Linux operating system. In sg3_utilsversion 1.19 a subset of the utilities were ported to FreeBSD andTru64; in version 1.22 a similar subset of the utilities were portedto Windows; and in version 1.24 a Solaris port was added.

Themost recent package is called sg3_utils and it uses the sgversion 3 interface (sometimes known as the SG_IOinterface) in linux. This interface is in lk 2.4.0 and laterkernels, including the lk 2.6, 3 and 4 series. All new features arebeing added into sg3_utils (i.e. it is stillbeing 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 higherlevel issuing SCSI READ and WRITE commands to copy data, mimickingthe Unix dd command. See the sg3_utilspackage page for more details.

The older (and original) package is called sg_utils and ituses the sg version 2 interface found linux kernel version 2.2.6 andonward. Over half of those utilities will also work on the originalsg device driver (at least back to the lk 2.0 series). If required,make common will produce the subset that will work on thewhole lk 2.x series. Since the sg version 3 device driverstill maintains the original interface, the sg_utils package willcontinue to work in the lk 2.4 and lk 2.6 series . This package isnow in maintenance mode, only bugs will be fixed. See this pagefor more details.

The latest versions, packaged intarballs, source, binary rpms and debian packages are given in thefollowing table. They contain README and CHANGELOG files and manpages. The tarball contains a spec file forbuilding rpms and a debian directory containing build information.Here is the most recently released sg3_utils CHANGELOG.

Table 2.sg3_utils/sg_utils tarballs and packages

tarballs

rpm source rpms

i386 rpm binaries

debian packages

sg3_utils
check News
section above
for betas

sg3_utils-1.47.tgz
sg3_utils-1.47.tar.xz

sg3-utils_1.47-0.1_amd64.deb
libsgutils2-2_1.47-0.1_amd64.deb

sg_utils

sg_utils-1.02.tgz

sg_utils-1.02-1.src.rpm

sg_utils-1.02-1.i386.rpm

See the sg3_utils page for morepackages (e.g. 64 bit versions of Debian, Redhat and Windows binarypackages) 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 disks 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 systemd and udev

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 othersites:

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

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.

DouglasGilbert can be emailed at that address.
Last updated: 11thNovember 2021, 14:00 [UTC-5]

TAGS:SCSI Linux The Driver sg Generic Linuxstorage SCSI sgdriver passthrough

<<< Thank you for your visit >>>

Linux SCSI Generic driver home page

Hot Websites