README - platform/external/sg3_utils - Git at Google

                       README for sg3_utils
                       ====================
 Introduction
 ------------
 In this directory are some utilities and test programs for the Linux sg
 (version 3) device driver. This driver is found in the lk 2.4 series kernels.
 If you have problems or questions about them please contact me.
 The home site for the Linux sg device drivers is: http://www.torque.net/sg .
 Documentation for the 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_err.[hc]" files contain
 ASCII text corresponding to most of the error and warning conditions
 defined by the SCSI 2 standard. They are used by most other programs.

 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
    v3   lk >= 2.4      additional sg_io_hdr interface structure.

 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 essentially the same utilities.

 Some sg ioctls (noteably SG_IO) are defined for all block devices
 from lk 2.5.48 . This version of sg3_utils (1.02 and later) allows
 some utilities that use SG_IO to just work for block devices
 (e.g. sg_inq). It guards some others that formerly assumed that any
 device that answers one of sg's ioctls was automatically an sg device
 (e.g. sginfo).


 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 and sg_reset
   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

 There is a brief description of each utility in the following sections.


 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.

 All numeric 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]
 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. [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).
 The "sg_dd" command has a "man" page [section 8].

 "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. This command has a
 "man" page [section 8].

 "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. The "sgm_dd" command has a "man"
 page [section 8].

 "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 SCSI bus scan and prints the results to standard output.
 With no arguments only read permissions are needed on the sg devices
 but if "-i" is given (to do a SCSI Inquiry command on the device) then
 write permissions are also needed. This command has a "man" page
 [section 8].

 "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. This command has a "man"
 page [section 8].

 "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.
  This command has a "man" page [section 8].


 3) SCSI support
 ---------------
 "sg_inq" is a utility for poking around the INQUIRY command which
 contains much interesting information. It is based on SCSI 3's SPC-2
 document. Has switches to output "command support" and "vital product
 data" pages. It can output in formatted ASCII, hex or binary. This
 command is applicable to SCSI 2 (and perhaps SCSI 1) devices as well.
 The "sg_inq" command has a "man" page [section 8].

 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 re-porting of the "scsiinfo" program by Eric Youngdale to
 use the sg devices (rather than the sd, sr or st block devices). This
 program outputs "mode sense" information. Amongst other things it outputs
 the full defect list of a disk (which was truncated at 4096 bytes in
 the original). The "sginfo" command has a "man" page [section 8].

 "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).
 The "sg_readcap" command has a "man" page [section 8].

 "sg_start" has been provided by Kurt Garloff <garloff@suse.de> for spinning
 up (or down) disks. The "sg_start" command has a "man" page [section 8] and
 see the README.sg_start file.

 "sg_modes" and "sg_logs" print out mode sense pages and log sense pages
 respectively.  The "sg_modes" and "sg_logs" commands have a "man" pages
 [section 8].

 "sg_senddiag" permits various device self tests to be run. It can also
 list the diagnostic pages support by a device. The "sg_senddiag" command
 has a "man" page [section 8].

 "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. The "sg_reset" command has
 a "man" page [section 8].


 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. This command has a "man" page [section 8].

 "sg_test_rwbuf" is a program by Kurt Garloff <garloff@suse.de> that has
 the following description:  Program to test the SCSI host adapter by
 issueing write and read operations on a device's buffer and calculating
 checksums. The "sg_test_rwbuf" command has a "man" page [section 8].

 "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 manuafacturers, "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.  The "sg_read" command has a "man" page [section 8].

 "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.
 The "sg_turs" command has a "man" page [section 8].

 "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_err.[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@cwi.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

 Doug Gilbert
 13th May 2003
	README for sg3_utils
	====================
	Introduction
	------------
	In this directory are some utilities and test programs for the Linux sg
	(version 3) device driver. This driver is found in the lk 2.4 series kernels.
	If you have problems or questions about them please contact me.
	The home site for the Linux sg device drivers is: http://www.torque.net/sg .
	Documentation for the 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_err.[hc]" files contain
	ASCII text corresponding to most of the error and warning conditions
	defined by the SCSI 2 standard. They are used by most other programs.

	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
	v3 lk >= 2.4 additional sg_io_hdr interface structure.

	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 essentially the same utilities.

	Some sg ioctls (noteably SG_IO) are defined for all block devices
	from lk 2.5.48 . This version of sg3_utils (1.02 and later) allows
	some utilities that use SG_IO to just work for block devices
	(e.g. sg_inq). It guards some others that formerly assumed that any
	device that answers one of sg's ioctls was automatically an sg device
	(e.g. sginfo).


	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 and sg_reset
	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

	There is a brief description of each utility in the following sections.


	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.

	All numeric 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]
	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. [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).
	The "sg_dd" command has a "man" page [section 8].

	"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. This command has a
	"man" page [section 8].

	"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. The "sgm_dd" command has a "man"
	page [section 8].

	"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 SCSI bus scan and prints the results to standard output.
	With no arguments only read permissions are needed on the sg devices
	but if "-i" is given (to do a SCSI Inquiry command on the device) then
	write permissions are also needed. This command has a "man" page
	[section 8].

	"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. This command has a "man"
	page [section 8].

	"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.
	This command has a "man" page [section 8].


	3) SCSI support
	---------------
	"sg_inq" is a utility for poking around the INQUIRY command which
	contains much interesting information. It is based on SCSI 3's SPC-2
	document. Has switches to output "command support" and "vital product
	data" pages. It can output in formatted ASCII, hex or binary. This
	command is applicable to SCSI 2 (and perhaps SCSI 1) devices as well.
	The "sg_inq" command has a "man" page [section 8].

	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 re-porting of the "scsiinfo" program by Eric Youngdale to
	use the sg devices (rather than the sd, sr or st block devices). This
	program outputs "mode sense" information. Amongst other things it outputs
	the full defect list of a disk (which was truncated at 4096 bytes in
	the original). The "sginfo" command has a "man" page [section 8].

	"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).
	The "sg_readcap" command has a "man" page [section 8].

	"sg_start" has been provided by Kurt Garloff <garloff@suse.de> for spinning
	up (or down) disks. The "sg_start" command has a "man" page [section 8] and
	see the README.sg_start file.

	"sg_modes" and "sg_logs" print out mode sense pages and log sense pages
	respectively. The "sg_modes" and "sg_logs" commands have a "man" pages
	[section 8].

	"sg_senddiag" permits various device self tests to be run. It can also
	list the diagnostic pages support by a device. The "sg_senddiag" command
	has a "man" page [section 8].

	"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. The "sg_reset" command has
	a "man" page [section 8].


	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. This command has a "man" page [section 8].

	"sg_test_rwbuf" is a program by Kurt Garloff <garloff@suse.de> that has
	the following description: Program to test the SCSI host adapter by
	issueing write and read operations on a device's buffer and calculating
	checksums. The "sg_test_rwbuf" command has a "man" page [section 8].

	"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 manuafacturers, "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. The "sg_read" command has a "man" page [section 8].

	"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.
	The "sg_turs" command has a "man" page [section 8].

	"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_err.[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@cwi.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

	Doug Gilbert
	13th May 2003