patch-2.3.99-pre2 linux/Documentation/scsi-generic.txt

Next file: linux/Documentation/sysrq.txt
Previous file: linux/Documentation/i2c/dev-interface
Back to the patch index
Back to the overall index

diff -u --recursive --new-file v2.3.99-pre1/linux/Documentation/scsi-generic.txt linux/Documentation/scsi-generic.txt
@@ -1,17 +1,18 @@
-            Notes on Linux's SG driver version 2.1.34
+            Notes on Linux's SG driver version 2.1.36
             -----------------------------------------
-                                                        990606
+                                                        20000110
 
 Introduction
 ============
-Sg is one of the four "high level" SCSI device drivers along with
-sd, st and sr (disk, tape and CDROM 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.
+The SCSI Generic driver (sg) is one of the four "high level" SCSI device
+drivers along with sd, st and sr (disk, tape and CDROM 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.
 
 These are notes on the Linux SCSI generic packet device driver (sg)
-describing version 2.1.34 . The original driver was written by Lawrence
+describing version 2.1.36 . The original driver was written by Lawrence
 Foard and remained in place with minimal changes since circa 1992.
 Version 2 of this driver remains backward compatible (binary and
 source **) with the original. It adds scatter gather, command queuing,
@@ -27,12 +28,12 @@
 of the document is version 1.5 dated 7th May 1996. It can found at
 ftp://sunsite.unc.edu/pub/Linux/docs/HOWTO-SCSI-Programming-HOWTO .
 A copy of this document can be found at:
-http://www.torque.net/sg/p/original/HOWTO-SCSI-Programming-HOWTO .
+http://www.torque.net/sg/p/original/HOWTO-SCSI-Programming-HOWTO.txt .
 
 ** It is possible to write applications that perform differently
 depending on whether they are using the original or this version of
-the sg device driver. The author is not aware of any useful 
-pre-existing applications that have problems with version 2 (yet).
+the sg device driver. The author is not aware of any useful
+pre-existing applications that have problems with version 2.
 
 
 Architecture
@@ -52,12 +53,12 @@
 system calls of open(), close(), read(), write() and ioctl(). Two other
 related system calls: poll() and fcntl() are added to this list and
 how they interact with the sg device driver is documented later.
- 
-An SG device is accessed by write()ing SCSI commands plus any associated 
+
+An SG device is accessed by write()ing SCSI commands plus any associated
 outgoing data to it; the resulting status codes and any incoming data are
 then obtained by a read() call. The device can be opened O_NONBLOCK
 (non-blocking) and poll() used to monitor its progress. The device may be
-opened O_EXCL which excludes other "sg" users from this device (but not 
+opened O_EXCL which excludes other "sg" users from this device (but not
 "sd", "st" or "sr" users). The buffer given to the write() call is made
 up as follows:
         - struct sg_header image (see below)
@@ -71,6 +72,12 @@
 The given SCSI command has its LUN field overwritten by the LUN value of
 the associated sg device that has been open()ed.
 
+SCSI commands are only attempted once (i.e. there are no internal
+retries). If appropriate (e.g. a SCSI READ) the data buffer is copied back
+to user space irrespective of the values of the various SCSI related
+error/status codes. [Some adapters that use an old error interface in
+the SCSI mid level ignore the retry count and retry certain errors.]
+
 
 sg_header
 =========
@@ -96,11 +103,11 @@
 input variable, it is not read by sg internally (only written).
 
 The 'reply_len' is the length of the data the corresponding read()
-will/should request (including the sg_header). 
+will/should request (including the sg_header).
 
 The 'pack_id' is not acted upon by the sg device driver but is conveyed
 back to the corresponding read() so it can be used for sequencing by an
-application. 
+application.
 
 The 'result' is also bizarre, turning certain types of host codes to 0 (no
 error), EBUSY or EIO. With better error reporting now available, the
@@ -138,7 +145,7 @@
     unsigned int driver_status:8;   /* [o] driver status+suggestion */
     unsigned int other_flags:10;    /* unused */
     unsigned char sense_buffer[SG_MAX_SENSE]; /* [o] Output in 3 cases:
-           when target_status is CHECK_CONDITION or 
+           when target_status is CHECK_CONDITION or
            when target_status is COMMAND_TERMINATED or
            when (driver_status & DRIVER_SENSE) is true. */
 };      /* This structure is 36 bytes long on i386 */
@@ -164,7 +171,7 @@
 values are (found in <scsi/scsi.h>):
 /* N.B. 1 bit offset from usual SCSI status values */
 #define GOOD                 0x00
-#define CHECK_CONDITION      0x01  
+#define CHECK_CONDITION      0x01
 #define CONDITION_GOOD       0x02
 #define BUSY                 0x04
 #define INTERMEDIATE_GOOD    0x08
@@ -175,7 +182,7 @@
 When the 'target_status' is CHECK_CONDITION or COMMAND_TERMINATED the
 'sense_buffer' is output. Note that when (driver_status & DRIVER_SENSE)
 is true then the 'sense_buffer' is also output (this seems to occur when
-the ide-scsi emulation is used). When the 'sense_buffer' is output the 
+the ide-scsi emulation is used). When the 'sense_buffer' is output the
 SCSI Sense Key can be found at (sense_buffer[2] & 0x0f) .
 
 The 'host_status' field is always output and has the following values
@@ -269,12 +276,12 @@
 Returns a file descriptor if >= 0 , otherwise -1 implies an error.
 
 Error codes (value in 'errno' after -1 returned):
-EACCES          Either the user doesn't have appropriate permissions on 
+EACCES          Either the user doesn't have appropriate permissions on
                 'filename' or attempted to use both O_RDONLY and O_EXCL
 EBUSY           O_NONBLOCK set and some user of this sg device has O_EXCL
                 set while someone is already using this device
 EINTR           while waiting for an "exclusive" lock to clear, a signal
-                is received, just try again ...        
+                is received, just try again ...
 ENODEV          sg not compiled into kernel or the kernel cannot find the
                 sg module (or it can't initialize itself (low memory??))
 ENOENT          given filename not found
@@ -320,12 +327,13 @@
                 This is more likely to happen when queuing commands,
                 so wait a bit (eg usleep(10000) ) before trying again
 EDOM            a) command queuing off: a packet is already queued
-                b) command queuing on: too many packets queued 
+                b) command queuing on: too many packets queued
                    (SG_MAX_QUEUE exceeded)
-                c) SCSI command length given in SG_NEXT_CMD_LEN too long
 EFAULT          'buffer' for 'count' bytes is an invalid memory range
-EIO             incoming buffer too short. It should be at least (6 +
-                sizeof(struct sg_header))==42 bytes long
+EIO             a) incoming buffer too short. It should be at least
+                   (6 + sizeof(struct sg_header))==42 bytes long
+                b) SCSI command length given in SG_NEXT_CMD_LEN too long
+                c) reply_len negative
 ENOMEM          can't get memory for DMA. Take evasive action ...
 ENXIO           either scsi sub-system is currently processing some error
                 (eg doing a device reset) or the sg driver/module removed
@@ -334,7 +342,7 @@
 
 read(int sg_fd, void * buffer, size_t count)
 --------------------------------------------
-Read() is used to receive a packet containing 1 mandatory part and 1 
+Read() is used to receive a packet containing 1 mandatory part and 1
 optional part. The mandatory part is:
   - a control block (an instance of struct sg_header)
 The optional part is:
@@ -343,7 +351,7 @@
 sufficient to accommodate this packet to avoid truncation. Truncation occurs
 if count < sg_header::replylen .
 
-By default, read() will return the oldest packet queued up. If the 
+By default, read() will return the oldest packet queued up. If the
 SG_SET_FORCE_PACK_ID,1 ioctl() is active then read() will attempt to
 fetch the packet whose pack_id (given earlier to write()) matches the
 sg_header::pack_id given to this read(). If not available it will either
@@ -356,12 +364,16 @@
 DMA-ed by the SCSI device. This driver is currently unable to provide
 such an underrun indication.
 
+If the SCSI device reports an error then a REQUEST SENSE is automatically
+done and the output is placed in the sense_buffer array which is in the
+control block. This action is sometimes called "auto-sense".
+
 Error codes (value in 'errno' after -1 returned):
 EAGAIN          either no waiting packet or requested packet is not
                 available while O_NONBLOCK flag was set
 EFAULT          'buffer' for 'count' bytes is an invalid memory range
 EINTR           while waiting for a packet, a signal is received, just
-                try again ...        
+                try again ...
 EIO             if the 'count' given to read() is < sizeof(struct sg_header)
                 and the 'result' element in sg_header is non-zero. Not a
                 recommended error reporting technique
@@ -380,11 +392,11 @@
 flight".
 
 A process that has an open file descriptor to an sg device may be aborted
-(eg by a kill signal). In this case, the kernel automatically calls close 
+(eg by a kill signal). In this case, the kernel automatically calls close
 (which is called 'sg_release()' in the version 2 driver) to facilitate
 the cleanup mentioned above.
 
-A problem persists in version 2.1.34 if the sg driver is a module and is
+A problem persists in version 2.1.36 if the sg driver is a module and is
 removed while packets are still "in flight".
 
 Returns 0 if successful, otherwise -1 implies an error.
@@ -394,7 +406,7 @@
 
 ioctl(int sg_fd, int command, ...)  [sg specific]
 -------------------------------------------------
-Ken Thompson (or perhaps some other Unix luminary) described ioctl() as 
+Ken Thompson (or perhaps some other Unix luminary) described ioctl() as
 the "garbage bin of Unix". This driver compounds the situation by adding
 more ...
 If a ioctl command is not recognized by sg (and the various lower levels
@@ -417,7 +429,8 @@
 for this file descriptor. The unit is a "jiffy". Packets that are
 already "in flight" will not be affected. The default value is set
 on open() and is SG_DEFAULT_TIMEOUT (defined in sg.h). This default is
-currently 1 minute and may not be long enough for formats.
+currently 1 minute and may not be long enough for formats. Negative
+values will yield an EIO error.
 
 SG_EMULATED_HOST:
 Assumes 3rd argument points to an int and outputs a flag indicating
@@ -426,33 +439,31 @@
 while 0 is not.
 
 SG_SET_TRANSFORM  W:
-Third argument is ignored. Only is meaningful when SG_EMULATED host has
-yielded 1 (ie the low-level is the ide-scsi device driver); otherwise
-an EINVAL error occurs. The default state is to _not_ transform SCSI
-commands to the corresponding ATAPI commands but pass them straight
-through as is. [Only certain classes of SCSI commands need to be
-transformed to their ATAPI equivalents.] Making this ioctl command causes
-transforms to occur thereafter. Subsequent calls to this ioctl command
-have no additional effect. Beware, this state will affect all devices
-(and hence all related sg file descriptors) associated with this ide-scsi
-"bus".
-The author of ide-scsi has pointed out that this is not the intended
-behaviour which is a 3rd argument of 0 to disable transforms and 1 to
-enable transforms. Note the 3rd argument is an 'int' not a 'int *'.
-Perhaps the intended behaviour will be implemented soon.
+Only is meaningful when SG_EMULATED host has yielded 1 (i.e. the low-level
+is the ide-scsi device driver); otherwise an EINVAL error occurs. The
+default state is to _not_ transform SCSI commands to the corresponding
+ATAPI commands but pass them straight through as is. [Only certain classes
+of SCSI commands need to be transformed to their ATAPI equivalents.]
+The third argument is interpreted as an integer. When it is non-zero then
+a flag is set inside the ide-scsi driver that transforms subsequent
+commands sent to this driver. When zero is passed as the 3rd argument to
+this ioctl then the flag within the ide-scsi driver is cleared and
+subsequent commands are not transformed. Beware, this state will affect
+all devices (and hence all related sg file descriptors) associated with
+this ide-scsi "bus".
 
 SG_GET_TRANSFORM:
 Third argument is ignored. Only is meaningful when SG_EMULATED host has
 yielded 1 (ie the low-level is the ide-scsi device driver); otherwise
 an EINVAL error occurs. Returns 0 to indicate _not_ transforming SCSI
-to ATAPI commands (default). Returns 1 when it is transforming.
+to ATAPI commands (default). Returns 1 when it is transforming them.
 
 SG_SET_FORCE_LOW_DMA +:
 Assumes 3rd argument points to an int containing 0 or 1. 0 (default)
 means sg decides whether to use memory above 16 Mbyte level (on i386)
 based on the host adapter being used by this SCSI device. Typically
 PCI SCSI adapters will indicate they can DMA to the whole 32 bit address
-space. 
+space.
 If 1 is given then the host adapter is overridden and only memory below
 the 16MB level is used for DMA. A requirement for this should be
 extremely rare. If the "reserved" buffer allocated on open() is not in
@@ -469,15 +480,21 @@
 
 SG_GET_SCSI_ID +:
 Assumes 3rd argument is pointing to an object of type Sg_scsi_id (see
-sg.h) and populates it. That structure contains ints for host_no, 
-channel, scsi_id, lun and scsi_type. Most of this information is 
-available from other sources (eg SCSI_IOCTL_GET_IDLUN and 
-SCSI_IOCTL_GET_BUS_NUMBER) but tends to be awkward to collect.
+sg.h) and populates it. That structure contains ints for host_no,
+channel, scsi_id, lun, scsi_type, allowable commands per lun and
+queue_depth. Most of this information is available from other sources
+(eg SCSI_IOCTL_GET_IDLUN and SCSI_IOCTL_GET_BUS_NUMBER) but tends to be
+awkward to collect.
+Allowable commands per lun and queue_depth give an insight to the
+command queuing capabilities of the adapters and the device. The latter
+overrides the former (logically) and the former is only of interest
+if it is equal to queue_depth which probably indicates the device
+does not support queueing commands (e.g. most scanners).
 
 SG_SET_FORCE_PACK_ID +:
 Assumes 3rd argument is pointing to an int. 0 (default) instructs read()
 to return the oldest (written) packet if multiple packets are
-waiting to be read (when command queuing is being used). 
+waiting to be read (when command queuing is being used).
 1 instructs read() to view the sg_header::pack_id as input and return the
 oldest packet matching that pack_id or wait until it arrives (or yield
 EAGAIN if O_NONBLOCK is in force). As a special case the pack_id of -1
@@ -524,7 +541,7 @@
 device then an EBUSY error occurs. Per device sequencing was the original
 semantics and allowed, for example different processes to "share" the
 device, one perhaps write()ing with the other one read()ing. This command
-is supplied if anyone needs those semantics. Per file descriptor 
+is supplied if anyone needs those semantics. Per file descriptor
 sequencing, perhaps with the use of the O_EXCL flag, seems more sensible.
 
 SG_GET_MERGE_FD +:
@@ -548,7 +565,7 @@
 SG_SET_UNDERRUN_FLAG +:
 Assumes 3rd argument is pointing to an int. 0 (current default, set by
 SG_DEF_UNDERRUN_FLAG in sg.h) requests underruns be ignored. 1 requests
-that underruns be flagged. [The only low level driver that acts on this 
+that underruns be flagged. [The only low level driver that acts on this
 at the moment is the aic7xxx which yields a DID_ERROR error on underrun.]
 Only the current file descriptor is affected by this command (unless
 "per device" sequencing has been selected).
@@ -571,7 +588,13 @@
 
 SG_GET_VERSION_NUM +:
 Assumes 3rd argument points to an int. The version number is then placed
-in that int. A sg version such as 2.1.34 will yield "20134" from this ioctl.
+in that int. A sg version such as 2.1.36 will yield "20136" from this ioctl.
+
+SG_SCSI_RESET +:
+Assumes 3rd argument points to an int. Unfortunately doesn't currently
+do much (may in the future after other issues are resolved). Yields an
+EBUSY error if the SCSI bus or the associated device is being reset
+when this ioctl() is called, otherwise returns 0.
 
 SG_SET_DEBUG +:
 Assumes 3rd argument is pointing to an int. 0 (default) turns debugging
@@ -641,13 +664,16 @@
 
 Utility and Test Programs
 =========================
-See the README file in the sg_utils<date>.tgz tarball. At the time of
-writing this was sg_utils990527.tgz .
+See the README file in the sg_utils<date>.tgz tarball. Look on the
+http://www.torque.net/sg website for the latest version.
 
 Briefly, that tarball contains the following utilities:
 sg_dd512        'dd' like program that assumes 512 byte blocks size
 sg_dd2048       'dd' like program that assumes 2048 byte blocks size
+sg_dd2352       'dd' like program that assumes 2352 byte blocks size
 sgq_dd512       like 'sg_dd512' but does command queuing on "if"
+sgp_dd          probably the most flexible 'dd' variant. It uses POSIX
+                threads, block size set by "bs=..." plus other options.
 sg_scan         outputs information (optionally Inquiry) on SCSI devices
 sg_rbuf         tests SCSI bus transfer speed (without physical IO)
 sg_whoami       outputs info (optionally capacity) of given SCSI device
@@ -657,6 +683,9 @@
 It also contains the following test programs:
 sg_debug        outputs sg driver state to console/log file
 sg_poll         tests asynchronous notification
+sg_runt_ex      example run time selection program for application authors
+sg_simple1      example program first time users
+sg_simple2      like sg_simple1 but with more primitive error processing
 sg_inquiry      does a SCSI Inquiry command (from original HOWTO)
 sg_tst_med      checks presence of media (from original HOWTO)
 
@@ -664,36 +693,40 @@
 SCSI 2 errors and warnings. This code is used by most of the above
 utility and test programs.
 
-The following programs: sg_dd512, sg_dd2048, sg_scan, sg_rbuf, sg_tst_med, 
-sg_inquiry and sginfo, can be compiled either for this new sg driver _or_
-the original sg driver.
+The following programs: sg_dd512, sg_dd2048, sg_dd2352, sg_scan, sg_runt_ex,
+sg_rbuf, sg_tst_med, sg_inquiry and sginfo, can be compiled either for this
+new sg driver _or_ the original sg driver (in 2.0 or 2.2 series kernels).
+sg_runt_ex can be run on 2.0, 2.2 or 2.3 series kernels even if it is
+compiled on a different series (eg compiled on 2.0, run on 2.2).
 
 
 Header files
 ============
 User applications need to find the correct "sg.h" header file matching
-their kernel in order to write code using the sg device driver. This is 
+their kernel in order to write code using the sg device driver. This is
 sometimes more difficult than it should be. The correct "sg.h" will usually
-be found at /usr/src/linux/include/scsi/sg.h . Another important header 
+be found at /usr/src/linux/include/scsi/sg.h . Another important header
 file is "scsi.h" which will be in the same directory.
 
-Several distributions have taken their own copies of these files and placed
-them in /usr/include/scsi which is where "#include <scsi/sg.h>" would go
-looking. The directory /usr/include/scsi _should_ be a symbolic link to
-/usr/src/linux/include/scsi/ . It was is Redhat 5.1 and 5.2 but it is
-not is Redhat 6.0 . Some other distributions have the same problem. To
-solve this (as root) do the following:
-
-# cd /usr/include
-# mv scsi scsi_orig
-# ln -s ../src/linux/include/scsi scsi
-
-This doesn't seem to be a problem with /usr/include/linux (at least in
-Redhat where it is a symbolic link) so it is hard to understand why
-/usr/include/scsi is defined the way it is. The fact the
-/usr/include/linux is a symbolic link opens up the following solution
-proposed by the author of cdparanoia (Monty):
-#include <linux/../scsi/sg.h>
+When "#include <scsi/sg.h>" is written in an application then this refers
+to the file /usr/include/scsi/sg.h . A problem sometimes arises because
+the files in the /usr/include/scsi directory are controlled by the GNU
+library people who maintain glibc. Unfortunately these 2 versions of
+the sg.h header file are not always in sync. [This was the case in Redhat
+6.0 and 6.1 .] Glibc 2.1.3 and later versions should get this right.
+
+If this is a problem, the user may need to copy sg.h (and scsi.h) from
+the kernel source includes to /usr/include scsi. If the user can change
+the effected source code then another approach is to rely on the fact that
+/usr/src/linux is a symbolic link to /usr/src/linux/include/linux and
+change the sg.h include to look like:
+    #include <linux/../scsi/sg.h>
+This solution is used by the author of cdparanoia (Monty) in his application.
+
+[Former scsi generic documents suggested adding a symbolic link to
+bypass this problem but that is not popular with the glibc maintainers.
+I would like to thank Andreas Jaeger <aj@suse.de> for his contributions
+on this subject.]
 
 
 Extra information in scsi-generic_long.txt
@@ -709,6 +742,27 @@
    - shortcomings
    - future directions
    - an appendix with some SCSI 2 information in it
+
+
+References
+==========
+http://www.t10.org      Very important site for SCSI related information.
+                        Contains SCSI 2 and 3 draft standards.
+http://www.andante.org/scsi.html
+                        This is Eric Youngdale's site. Eric is primarily
+                        responsible for the Linux SCSI architecture and
+                        its mid-level implementation.
+http://www.kernel.dk    Jens Axboe's site for Linux cdrom matters including
+                        the SCSI "sr" driver.
+http://www.torque.net/sg
+                        My site with sg related information.
+newsgroup:linux-scsi@vger.rutgers.edu
+                        Newsgroup for Linux related SCSI matters
+/usr/src/linux/MAINTAINERS
+                        This is a file in the Linux kernel source that
+                        contains up to date information about who maintains
+                        what and where information can be found. Links to
+                        SCSI adapter information are also here.
 
 
 Conclusion
FUNET's LINUX-ADM group, linux-adm@nic.funet.fi
TCL-scripts by Sam Shen (who was at: slshen@lbl.gov)