diff options
Diffstat (limited to 'Documentation/scsi-generic.txt')
| -rw-r--r-- | Documentation/scsi-generic.txt | 210 |
1 files changed, 132 insertions, 78 deletions
diff --git a/Documentation/scsi-generic.txt b/Documentation/scsi-generic.txt index 2d26dec9d..48ec05c3c 100644 --- a/Documentation/scsi-generic.txt +++ b/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 @@ by Heiko Eissfeldt in a HOWTO called SCSI-Programming-HOWTO. My copy 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 @@ Since sg is a character device it supports the traditional Unix 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 buffer received from the corresponding read() call contains: 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 @@ The 'pack_len' is bizarre and ends up having the 'reply_len' put in it 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 @@ struct sg_header 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 @@ The 'target_status' field is always output and is the (masked and shifted 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 @@ values are (found in <scsi/scsi.h>): 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 @@ The reserved buffer will be used if: 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 @@ EAGAIN SCSI mid-level out of command blocks (rare), try again. 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 @@ ENXIO either scsi sub-system is currently processing some error 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 @@ The buffer given to a read() and its corresponding count should be 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 @@ same as the count argument. It is not the actual number of bytes 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 @@ arrange for an orderly cleanup of those packets that are still "in 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 @@ ENXIO sg driver/module removed or corrupted 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 @@ Assumes 3rd argument points to an int containing the new timeout value 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 @@ emulated one (eg ide-scsi device driver). A value of 1 means emulated 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 @@ adapters setting has been overridden by SG_SET_FORCE_LOW_DMA,1 . 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 @@ state and there is one or more _other_ file descriptors using this sg 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 @@ queuing is on. 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 @@ this ioctl(). 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 @@ fcntl(sg_fd, F_SETFL, flags | O_ASYNC) 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 @@ sginfo outputs "mode" information about SCSI devices (it is a 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 @@ There are also 2 source files (sg_err.[hc]) for outputting and categorizing 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: +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. -# cd /usr/include -# mv scsi scsi_orig -# ln -s ../src/linux/include/scsi scsi +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. -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> +[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 @@ -711,6 +744,27 @@ The longer document contains additional sections on: - 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 ========== The SCSI generic packet device driver attempts to make as few assumptions |