path: root/README

                      README for sg3_utils
                      ====================
Introduction
============
This package contains utilities and test programs for the Linux SCSI
subsystem. In the Linux 2.6 kernel series almost all of these programs 
will work on any devices that use the SCSI command set. Apart from SCSI 
parallel devices, ATAPI devices (CD/DVDs and tapes), USB mass storage 
devices, Fibre Channel disks and IEEE 1394 storage devices (that use 
the "SBP" protocol) use the SCSI command set.

A web site supporting the sg3_utils package, its predecessor sg_utils,
and the Linux SCSI generic driver (and the scsi_debug driver) can be
found at http://www.torque.net/sg . The most recent release version
of sg3_utils and the most recent beta is on that page. There is also
a page describing the utilities in the sg3_utils and sg_utils packages:
http://www.torque.net/sg/u_index.html .

In the Linux 2.4 kernel series these programs need to use the SCSI generic
(sg) driver to access SCSI devices. The name of this package (i.e.
sg3_utils) refers to version 3 of the SCSI generic (sg) driver which
was introduced at the beginning of the 2.4 linux kernel series. Significantly
this added a new SCSI command interface structure (i.e. struct sg_io_hdr)
that is more flexible than the older "sg_header" structure found in the
sg driver in the 2.2 and earlier linux kernel series. The sg_io_hdr structure
is also more flexible than the awkward (and limiting) interface to the
SCSI_IOCTL_SEND_COMMAND ioctl supported by the linux SCSI mid level.
Also added in the version 3 sg driver was the SG_IO ioctl that is synchronous
(i.e. it issues the requested SCSI command and waits for the response
(or a timeout) before the ioctl returns to the user space program that
invoked it). The SG_IO ioctl is now found in other parts of the linux
kernel in the 2.6 series.

Utilities that wish to use the asynchronous SCSI command interface
(i.e. via a write() read() sequence) or issue special "commands"
(e.g. bus and device resets) still need to use the sg driver. Note
that various drivers (e.g. cdrom/sr) have different open() flag and
permissions policies that the user may need to take into account.

If you have problems or questions about them please contact the author.
Documentation for the sg device driver can be found at:
http://www.torque.net/sg/p/sg_v3_ho.html .
This is written in DocBook and the original xml can be found in the 
same directory with the ".xml" extension. Postscript and
pdf renderings are also in that directory.
Older documentation for the sg version 3 driver can be found at:
http://www.torque.net/sg/p/scsi_generic_v3.txt .

All programs are "GPL"-ed so you can incorporate all or part of them
in your applications as you please. The "sg_lib.[hc]" files contain
ASCII text corresponding to most of the error and warning conditions
defined in recent drafts at www.t10.org which is the home site of
SCSI (draft) standards. 

Additional information (including a version number) can be found
towards the top of each ".c" file corresponding to each utility and
test program.


Scope
=====
The sg driver in Linux can be seen as having 3 distinct versions:

   v1   lk < 2.2.6     sg_header based relatively unchanged since 1992
   v2   lk >= 2.2.6    enhanced sg_header interface structure [1999/4/16]
   v3   lk >= 2.4      additional sg_io_hdr interface structure [2001/1/4]
   v3   lk >= 2.6      same interface as found in lk 2.4 [2004/1/??]

This package is targeted as "v3" only. Another package called "sg_utils"
is targeted at "v2" and to a lesser extent "v1". The "sg_utils"
package has a subset of the utilities found in this package.

Some sg ioctls (notably SG_IO) are defined for many block devices
in lk 2.6 . In practice this means all SCSI block devices, ATAPI block devices
(mainly CD and DVD players) but _not_ ATA disks (currently). Support for
the SG_IO as been added to the scsi tape driver (st) in lk 2.6.6 (and
support for osst will soon follow).

No utilities in the main directory use the sg driver's older "sg_header"
interface; instead they use the newer "sg_io_hdr" interface. The "sg_io_hdr"
interface can be accessed two ways:
  - using the SG_IO ioctl [for synchronous access]
  - using a write()/read() sequence that convey instances of "sg_io_hdr"

All utilities in the main directory use the SG_IO ioctl except for sgp_dd.
This is due to the asynchronous nature of sgp_dd. Note that sgp_dd does _not_
support the "blk_sgio" switch found in sg_dd. This is important since block
devices often identify themselves (programmatically) as sg devices in lk 2.6
and it would cause serious damage to do a write() of the sg driver's "sg_io_hdr"
metadata (i.e. disk corruption).  


Utilities
=========
Here is a (somewhat arbitrary) categorization of the utilities included
in this package:
  1) dd variants: sg_dd, sgp_dd, sgm_dd and sgq_dd
  2) scanning and mapping: sg_scan, sg_map and scsi_devfs_scan
  3) SCSI support: sg_inq, scsi_inquiry, sginfo, sg_readcap, sg_start,
     sg_modes, sg_logs, sg_senddiag, sg_reset, sg_opcodes, sg_persist,
     sg_write_long, sg_read_long, sg_requests, sg_ses, sg_verify,
     sg_emc_trespass and sg_luns
  4) timing and testing: sg_rbuf, sg_test_rwbuf, sg_read, sg_turs,
     and sg_debug
  5) example programs: sg_simple1, sg_simple2, sg_simple3, sg_simple4
     and sg_simple16
  6) miscellaneous programs: isosize, hxascdmp

There is a brief description of each utility in the following sections.
All utilities in the main directory have a "man" page in section 8
which is a category for administration and privileged commands. Some
utilities in the other (sub-)directories have man pages.

To see which SCSI commands (and ATA commands) are used by these
utilities see the COVERAGE file.

  
1) dd variants
--------------
The main utility is a variant of the standard Unix command "dd" that
is called "sg_dd". This program takes a useful subset of the command
line arguments that "dd" takes. Furthermore "sg_dd" will only work if
one or both of the given files (ie "if" or "of") is an "sg" or a raw
device. If "bs" (block size) is not given it is assumed to be 512 bytes.
Available dd options:
   bs=<n>        typically 512 or 2048
   ibs=<n>       if given must be the same as "bs"
   obs=<n>       if given must be the same as "bs"
   if=<name>     like dd plus sg device or "-" (read from stdin)
   of=<name>     like dd plus sg device or "-" (write to stdout)
   skip=<n>      block offset to start reading "if"
   seek=<n>      block offset to start writing "of"
Extra options:
   bpt=<n>       blocks per transfer (default 128)
   dio=<n>       0 or 1, request direct IO (default 0)
   cdbsz=6|10|12|16   allow the command size of SCSI READ and WRITE commands
                      to be specified (default is 10)
   sync=0|1      when 1, do a SYNCHRONIZE CACHE on "of" after the transfer
                 is complete
   fua=0|1|2|3   when 0, do not set 'force unit access' bit; when 1, set it
                 on "of"; when 2, set it on "if"; when 3, set it on "if"+"of"
   time=0|1      times the transfer and calculates a throughput figure when
                 1, output sent to stderr. Default is 0
   coe=0|1       continue on error (only on sg devices) when 1. Default is 0.

Numeric arguments can be given in decimal or hexadecimal. Hex arguments should
be prefixed with "0x" or "0X". Decimal arguments can take multiplier suffixes:
  "c", "C"        * 1
  "b", "B"        * 512
  "k"             * 1024           [2 ^ 10]
  "K"             * 1000           [10 ^ 3]
  "m"             * 1048576        [2 ^ 20]
  "M"             * 1000000        [10 ^ 6]
  "g"             * 1073741824     [2 ^ 30]
  "G"             * 1000000000     [10 ^ 9]
  "t"             * 1099511627776  [2 ^ 40]
  "T"             * 1000000000000  [10 ^ 12]
The 'skip' and 'seek' options lead to the use of the system command
lseek() to a byte offset when used on raw devices and normal files.
[For sg devices 32 bit block addresses are used thus limiting accesses
on disks with 512 byte blocks to 1 TB.] On 32 bit architectures the
normal lseek() is limited to a signed 32 bit byte offset (i.e. 2 GB).
"sg_dd" bypasses this limit by using Linux's _llseek() [while modern
"dd" commands use read loops to "walk" around the limit].
If 'count' is not given then the SCSI READ CAPACITY command will be
used (on sg devices) if appropriate. Block devices are queried for their
length if 'count' is not given. [Note that READ CAPACITY often
gives a 2 block overestimate for iso9660 file systems on CD-ROMs. 
See the "isosize" command below.]  Disk partition information can
be found with a command like "fdisk -ul /dev/sda". The 'dio' argument
requests direct IO (only functions in 2.4 kernels). A warning is issued 
if direct IO is requested and /proc/scsi/sg/allow_dio == 0 . 
"of=/dev/null" causes writes to be skipped, and "of=." is accepted as
an alias for "of=/dev/null" (convenient shorthand).

"sgp_dd" uses POSIX threads and attempts to run multiple IO operations
in parallel. The user can control the amount of parallelism from 
1 worker (i.e. single threaded) through to 16 worker threads. This is
done via the "thr=<n>" option (default 4). Copies from one sg device to
another can be considerably faster due to this parallelism. There is
also some speed benefit when raw devices are used. To obtain fine level 
SCSI command level control, sg devices should be used rather than block
devices which will be interpreted as normal Unix files.

"sgm_dd" is very similar to sg_dd but it uses mmap-ed IO on one of its
given sg device names. If both "if" and "of" are sg devices then mmap-ed
IO is selected on "if" while normal IO is selected on "of". Direct IO
cannot be selected with this command. To obtain fine level SCSI command
level control, sg devices should be used rather than block devices which
will be interpreted as normal Unix files. 

"sgq_dd" is yet another implementation found in the archive directory.
From the user point of view it is very similar to sgp_dd but uses a
non-blocking state machine rather then POSIX threads for parallelism.


2) Scanning and mapping
-----------------------
"sg_scan" does a scan of all sg device and prints the results to 
standard output. Alternatively one or more device names can be
given (e.g. 'sg_scan -i /dev/scd[01]') and these will be scanned instead
of the sg devices. Additional information from the INQUIRY command can
be obtained by using the "-i" option.

"sg_map" shows the mapping between sg device names and those of the
sd, sr and st device names. Some devices such as scanners have no
corresponding sd, sr nor st device names.

"scsi_devfs_scan" is a utility for doing a directory scan on a system
running devfs to identify SCSI (and optionally IDE) devices. Various
information (including an INQUIRY) can be listed for each found device.


3) SCSI support
---------------
"sg_inq" is a utility for examining the INQUIRY command which
contains much interesting information. It is based on SCSI 3's SPC-2
document. Has switches to output "vital product data" and "command support"
(now obsolete) pages. It can output in formatted ASCII, hex or binary. 
Has '-i' to decode the now mandatory device identification VPD page (0x83).
This command is applicable to SCSI 2 (and perhaps SCSI 1) devices as well.

The "scsi_inquiry" program shows the use of the SCSI_IOCTL_SEND_COMMAND
ioctl to send a SCSI INQUIRY command. That ioctl() is supported by the 
SCSI sub system mid level and so is common to all sd, sr, st and sg devices. 
This program has been placed in the "examples" subdirectory.

"sginfo" is a port of the "scsiinfo" program by Eric Youngdale to use the sg
devices. It can still take other SCSI device nodes (e.g. /dev/sda, /dev/st0 
or /dev/hdc (if "hdc" is an ATAPI device)). This program outputs mode
page (and subpage) information and allows it to be modified. Additionally 
defect lists (for disks) can be output and information from the SCSI INQUIRY
command is available.

"sg_readcap" call a READ CAPACITY command on the given device. Now also
supports "partial medium indicator" (PMI) flag that indicates where the
next significant delay will be on the media (after a given address).

"sg_start" has been provided by Kurt Garloff <garloff at suse dot de> 
for spinning up (or down) disks.
see the README.sg_start file.

"sg_modes" and "sg_logs" print out mode sense pages and log sense pages 
respectively.

"sg_senddiag" permits various device self tests to be run. It can also
list the diagnostic pages support by a device.

"sg_reset" exercises the SCSI device/bus/host reset capability. It is
supported by the sg driver in lk 2.2.16 and beyond but associated
SCSI middle level driver changes have not been accepted into the
standard kernel at this time. Many distributions contain the patch to
the mid-level that activates this feature. This patch is in later
lk 2.4 versions and in the lk 2.6 series. This utility will only
work on sg device names.

"sg_opcodes" lists available opcode names. It uses the REPORT SUPPORTED
OPERATION CODES SCSI command which was introduced in February 2002
(and replaced the Cmd modes (CmdDt bit) in the INQUIRY command). Opcode
names include various SCSI commands with service actions (e.g.
the Maintenance In command) and variable length commands. The command
list is either unsorted (as returned by the device), numerically sorted
(default) or alphabetically sorted. An individual opcode (and optionally
a service action) can be given in which case the "changeable" bits of
that command are output. With the '-t' command line option this utility
will list supported task management functions.

"sg_persist" accesses the Persistent Reservation In and Out commands.
These are relatively complex commands and potential users are referred
to the SPC-3 document at http://www.t10.org . That said, it is
relatively safe to query the state of existing registrations and
reservations with the PR In command (use the switch "--in" with
sg_persist to enforce this).

"sg_write_long" can be used to write a "long" block to the given device
(typically a disk). A "long" block includes data, ECC information and
and other vendor specific information.

"sg_read_long" can be used to read a "long" block from the given device
(typically a disk).

"sg_requests" issues a REQUEST SENSE SCSI command. One SPC-3 addition
supported by this utility is the 'DESC' flag to request sense data in
descriptor format.

"sg_ses" issues SEND and RECEIVE DIAGNOSTIC PAGE commands to the
given device which is assumed to be either an enclosure or another
type of device (e.g. disk) that supports emclosure services. The
latter case is indicated by a device setting the "EncServ" bit in
a standard INQUIRY response.

"sg_verify" verifies media by invoking SCSI VERIFY commands.

"sg_emc_trespass" permits modification of EMC specific trespass
mode page.

"sg_emc_trespass" sends a REPORT LUNS SCSI command to the given device
and outputs the response. The '--select' options allows the "select
report" field to be specified.


4) Timing and testing
---------------------
"sg_rbuf" does repeated SCSI READ BUFFER commands which allows SCSI
bus bandwidth and the SCSI sub-system throughput to be measured.
This can be done in 4 modes: normal transfer to user space, no
transfer to user space, direct IO or mmap-ed IO. The latter one wins
on my hardware.

"sg_test_rwbuf" is a program by Kurt Garloff <garloff at suse dot de> that
has the following description:  Program to test the SCSI host adapter by 
issuing write and read operations on a device's buffer and calculating 
checksums. 

"sg_read" reads multiple blocks of data starting at the same logical
address. It can time the transfers (potentially ignoring the first
issued command) and calculate a MB/sec figure. [In keeping with most
disk manufacturers, "MB" is 1,000,000 bytes in this context.] Its 
command line syntax is modelled on "sg_dd". It allows SCSI device,
SCSI bus bandwidth and the SCSI sub-system throughput to be measured.
This can be done in 3 modes: normal transfer to user space, direct
IO or mmap-ed IO.

"sg_turs" executes a user specified number of TEST UNIT READY commands on
the given device. This can be used to time SCSI command overhead.

"sg_debug" is effectively defunct now. The user can instead do:
$ cat /proc/scsi/sg/debug . This command has been placed in the
archive directory.


5) Example programs
-------------------
"sg_simple1" and "sg_simple2" are simple example programs demonstrating
calls to the SCSI INQUIRY and TEST UNIT READY commands. They only differ
in their error processing: sg_simple1 uses sg_lib.[hc] for error
processing while sg_simple2 does its own more primitive checks.

"sg_simple3" tests out user space scatter gather added to the version 3
sg driver.

"sg_simple4" shows the INQUIRY command using mmap-ed IO to obtain its
response buffer.

"sg_simple16" attempts to send a 16 byte SCSI command, READ_16, to the
scsi device. This is only supported for lk >= 2.4.15 and for adapter
drivers that indicate that they have 16 byte CDB capability (otherwise
DID_ABORT will appear in the host_status).

All these example programs (plus scsi_inquiry) have been placed in the
"examples" subdirectory with their own Makefile.


6) Miscellaneous
----------------
"isosize" is a utility that gives the number of bytes in an iso9660
file system. It is a rewrite by Andries Brouwer<Andries.Brouwer at cwi dot nl>
of a utility that first appeared in the cdwrite package but is now
difficult to obtain. Note that the value given by isosize is usually
2 or more blocks less than the READ CAPACITY SCSI command yields on
a CD-ROM (due to run out sectors). This command has a "man" page
[section 8]. This utility has been moved to the archive directory
as isosize is now available in the util-linux-2.10s package (and later).

Building
========
A Makefile is provided that builds the above utilities and test programs
'make' and 'make all' will cause everything (that is stale) to be built.

A complete rebuild can be forced by executing 'make clean' prior to
any of the above make commands. Individual commands can be built be
giving the executable name to make, for example: 'make sg_dd'.

There is also a 'make dep' but that shouldn't be needed very often.
A 'make install' will build if necessary and then install the
executables into /usr/local/bin by default (controlled by variable
INSTDIR). The "man" pages are loaded int /usr/local/man/man8 by default.

Header file problems
====================
These utilities include 2 special Linux header files:
#include <scsi/sg.h>
#include <scsi/scsi.h>
These files are typically found in the directory /usr/include/scsi which
is maintained by the GNU glibc team. Unfortunately these GNU supplied
headers may not be (functionally) the same as those found in the kernel
source:
/usr/src/linux/include/scsi/sg.h   and
/usr/src/linux/include/scsi/scsi.h

If glibc and the kernel on a machine are of the same vintage then it is
probably sufficient to use the simple includes listed at the start of this
section. Another technique that used to work was to rely on
/usr/include/linux being a symbolic link to /usr/src/linux/include/linux . 
That caused the following:
#include <linux/../scsi/sg.h> 
#include <linux/../scsi/scsi.h>
to find the kernel supplied header files. However recent versions of
glibc have removed this symlink! Hence this technique is no longer
recommended.

The include file path issues are now all addressed in one file called
"sg_include.h". Please read that file.

scsirastools
============
This package found at http://scsirastools.sourceforge.net contains utilities
which overlap with the functionality offered in sg3_utils. Utilities of note
in scsirastools are:
  - sgdskfl: for loading firmware into SCSI disks
  - sgmode: get and set mode pages
  - sgdefects: list primary and grown defect lists
  - sgdiag to perform format and other test functions

plscsi
======
The author is considering implementing FreeBSD's camcontrol utility
which can issue arbitrary SCSI commands (i.e. supplied by user). There is
a similar utility called "plscsi" which is available for Linux and other
operating systems. See http://members.aol.com/plscsi .

Doug Gilbert
30th October 2004