NUC972-FreeRTOS+littleVGL--800x480或480x272.rar

Notes on Linux's SG driver version 2.1.36 ----------------------------------------- 20000110 Introduction ============ 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.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, per file descriptor sequencing, asynchronous notification and better error reporting. This is an abridged version of the sg documentation that is targeted at the linux/Documentation directory. The full document can be found at http://www.torque.net/sg/p/scsi-generic_long.txt . The interface and usage of the original sg driver have been documented 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.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. Architecture ============ The SCSI generic packet device driver (sg) is a character based device. It is one of the four high level device driver in the SCSI sub-system; the others are sd (for direct-access devices - disks), st (for tapes) and sr (for data cdroms). The other three devices are block devices. The unifying layer of the SCSI sub-system is the so-called mid-level. Below that are the "low level" drivers which are the drivers for the various adapters supported by Linux. Also at this level are pseudo adapter drivers such as ide-scsi which converts the SCSI protocol to ATAPI (which are similar to one another) for use by IDE devices. 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 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 "sd", "st" or "sr" users). The buffer given to the write() call is made up as follows: - struct sg_header image (see below) - scsi command (6, 10 or 12 bytes long) - data to be written to the device (if any) The buffer received from the corresponding read() call contains: - struct sg_header image (check status/errors + sense_buffer) - data read back from device (if any) 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 ========= This is the name of the control structure that conveys information about the length of data to be read/written by the associated SCSI command. It also conveys error and status information from the read() call. An instance of this structure is the first thing that is placed in the data buffers of both write() and read(). In its original form it looked like this: struct sg_header { int pack_len; int reply_len; int pack_id; int result; unsigned int twelve_byte:1; unsigned int other_flags:31; unsigned char sense_buffer[16]; }; /* this structure is 36 bytes long */ The 'pack_len' is bizarre and ends up having the 'reply_len' put in it (perhaps it had a use at some stage). Even though it looks like an 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). 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. 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 'result' is best ignored. The 'twelve_byte' field overrides the internal SCSI command length detection algorithm for group 6 and 7 commands (ie when 1st byte >= 0xc0) and forces a command length of 12 bytes. The command length detection algorithm is as follows: Group: 0 1 2 3 4 5 6 7 Length: 6 10 10 12 12 12 10 10 'other_flags' was originally documented as "not used" but some current applications assume it has 0 placed in it. The 'sense_buffer' is the first 16 bytes of SCSI sense buffer that is returned when the target returns a SCSI status code of CHECK_CONDITION or COMMAND_TERMINATED [or (driver_status & DRIVER_SENSE) is true]. This buffer should be at least 18 bytes long and arguably 32 bytes; unfortunately this is unlikely to happen in the 2.2.x series of kernels. The new sg_header offered in this driver is: #define SG_MAX_SENSE 16 struct sg_header { int pack_len; /* [o] reply_len (ie useless) ignored as input */ int reply_len; /* [i] max length of expected reply (inc. sg_header) */ int pack_id; /* [io] id number of packet (use ints >= 0) */ int result; /* [o] 0==ok, else (+ve) Unix errno (best ignored) */ unsigned int twelve_byte:1; /* [i] Force 12 byte command length for group 6 & 7 commands */ unsigned int target_status:5; /* [o] scsi status from target */ unsigned int host_status:8; /* [o] host status (see "DID" codes) */ 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 COMMAND_TERMINATED or when (driver_status & DRIVER_SENSE) is true. */ }; /* This structure is 36 bytes long on i386 */ Firstly the new header is binary compatible with the original. This is important for keeping existing apps working without recompilation. Only those elements (or fields) that are new or in some way different from the original are documented below. 'pack_id' becomes input to a read() when ioctl(sg_fd, SG_SET_FORCE_PACK_ID, &one) is active. A 'pack_id' of -1 is interpreted as fetch the oldest waiting packet; any other value will cause the read() to wait (or yield EAGAIN) until a packet with that 'pack_id' becomes available. In all cases the value of 'pack_id' available after a read() is the value given to that variable in the prior, corresponding write(). The SCSI command length can now be given directly using the SG_NEXT_CMD_LEN ioctl(). The 'target_status' field is always output and is the (masked and shifted 1 bit right) SCSI status code from the target devic