sg.h

嵌入式系统设计与实例开发实验教材二源码 多线程应用程序设计 串行端口程序设计 AD接口实验 CAN总线通信实验 GPS通信实验 Linux内核移植与编译实验 IC卡读写实验 SD驱动使

#ifndef _SCSI_GENERIC_H
#define _SCSI_GENERIC_H

/*
   History:
    Started: Aug 9 by Lawrence Foard ([e-mail]), to allow user
     process control of SCSI devices.
    Development Sponsored by Killy Corp. NY NY
Original driver (sg.h):
*       Copyright (C) 1992 Lawrence Foard
Version 2 and 3 extensions to driver:
*       Copyright (C) 1998 - 2001 Douglas Gilbert

    Version: 3.1.22 (20011208)
    This version is for 2.4 series kernels.

    Changes since 3.1.21 (20011029)
    	- add support for SG_FLAG_MMAP_IO [permit mmap() on sg devices]
    	- update documentation pointers in this header
    	- put KERNEL_VERSION macros around code that breaks early 2.4 series
    	- fix use count for multiple queued requests on closed fd
    	- switch back to alloc_kiovec()
    Changes since 3.1.20 (20010814)
	- use alloc_kiovec_sz() to speed dio [set num_buffer_heads==0]
	- changes to cope with larger scatter gather element sizes
	- clean up some printk()s
	- add MODULE_LICENSE("GPL") [in a 3.1.20 subversion]
	- fix race around generic_unplug_device() [in a 3.1.20 subversion]
    Changes since 3.1.19 (20010623)
	- add SG_GET_ACCESS_COUNT ioctl 
	- make open() increment and close() decrement access_count
	- only register first 256 devices, reject subsequent devices
    Changes since 3.1.18 (20010505)
	- fix bug that caused long wait when large buffer requested
	- fix leak in error case of sg_new_read() [report: Eric Barton]
	- add 'online' column to /proc/scsi/sg/devices
    Changes since 3.1.17 (20000921)
    	- add CAP_SYS_RAWIO capability for sensitive stuff
    	- compile in dio stuff, procfs 'allow_dio' defaulted off (0)
	- make premature close and detach more robust
	- lun masked into commands <= SCSI_2
	- poll() and async notification now yield POLL_HUP on detach
	- various 3rd party tweaks tracking lk 2.4 internal changes

Map of SG verions to the Linux kernels in which they appear:
       ----------        ----------------------------------
       original          all kernels < 2.2.6
       2.1.40            2.2.20
       3.0.x             optional version 3 sg driver for 2.2 series
       3.1.17++          2.4.0++

Major new features in SG 3.x driver (cf SG 2.x drivers)
	- SG_IO ioctl() combines function if write() and read()
	- new interface (sg_io_hdr_t) but still supports old interface
	- scatter/gather in user space, direct IO, and mmap supported

 The normal action of this driver is to use the adapter (HBA) driver to DMA
 data into kernel buffers and then use the CPU to copy the data into the 
 user space (vice versa for writes). That is called "indirect" IO due to 
 the double handling of data. There are two methods offered to remove the
 redundant copy: 1) direct IO which uses the kernel kiobuf mechanism and 
 2) using the mmap() system call to map the reserve buffer (this driver has 
 one reserve buffer per fd) into the user space. Both have their advantages.
 In terms of absolute speed mmap() is faster. If speed is not a concern, 
 indirect IO should be fine. Read the documentation for more information.

 ** N.B. To use direct IO 'echo 1 > /proc/scsi/sg/allow_dio' may be
         needed. That pseudo file's content is defaulted to 0. **
 
 Historical note: this SCSI pass-through driver has been known as "sg" for 
 a decade. In broader kernel discussions "sg" is used to refer to scatter
 gather techniques. The context should clarify which "sg" is referred to.

 Documentation
 =============
 A web site for the SG device driver can be found at:
	http://www.torque.net/sg  [alternatively check the MAINTAINERS file]
 The documentation for the sg version 3 driver can be found at:
 	http://www.torque.net/sg/p/sg_v3_ho.html
 This is a rendering from DocBook source [change the extension to "sgml"
 or "xml"]. There are renderings in "ps", "pdf", "rtf" and "txt" (soon).

 The older, version 2 documents discuss the original sg interface in detail:
	http://www.torque.net/sg/p/scsi-generic.txt
	http://www.torque.net/sg/p/scsi-generic_long.txt
 A version of this document (potentially out of date) may also be found in
 the kernel source tree, probably at:
        /usr/src/linux/Documentation/scsi-generic.txt .

 Utility and test programs are available at the sg web site. They are 
 bundled as sg_utils (for the lk 2.2 series) and sg3_utils (for the
 lk 2.4 series).

 There is a HOWTO on the Linux SCSI subsystem in the lk 2.4 series at:
 	http://www.linuxdoc.org/HOWTO/SCSI-2.4-HOWTO
*/


/* New interface introduced in the 3.x SG drivers follows */

typedef struct sg_iovec /* same structure as used by readv() Linux system */
{                       /* call. It defines one scatter-gather element. */
    void * iov_base;            /* Starting address  */
    size_t iov_len;             /* Length in bytes  */
} sg_iovec_t;


typedef struct sg_io_hdr
{
    int interface_id;           /* [i] 'S' for SCSI generic (required) */
    int dxfer_direction;        /* [i] data transfer direction  */
    unsigned char cmd_len;      /* [i] SCSI command length ( <= 16 bytes) */
    unsigned char mx_sb_len;    /* [i] max length to write to sbp */
    unsigned short iovec_count; /* [i] 0 implies no scatter gather */
    unsigned int dxfer_len;     /* [i] byte count of data transfer */
    void * dxferp;              /* [i], [*io] points to data transfer memory
					      or scatter gather list */
    unsigned char * cmdp;       /* [i], [*i] points to command to perform */
    unsigned char * sbp;        /* [i], [*o] points to sense_buffer memory */
    unsigned int timeout;       /* [i] MAX_UINT->no timeout (unit: millisec) */
    unsigned int flags;         /* [i] 0 -> default, see SG_FLAG... */
    int pack_id;                /* [i->o] unused internally (normally) */
    void * usr_ptr;             /* [i->o] unused internally */
    unsigned char status;       /* [o] scsi status */
    unsigned char masked_status;/* [o] shifted, masked scsi status */
    unsigned char msg_status;   /* [o] messaging level data (optional) */
    unsigned char sb_len_wr;    /* [o] byte count actually written to sbp */
    unsigned short host_status; /* [o] errors from host adapter */
    unsigned short driver_status;/* [o] errors from software driver */
    int resid;                  /* [o] dxfer_len - actual_transferred */
    unsigned int duration;      /* [o] time taken by cmd (unit: millisec) */
    unsigned int info;          /* [o] auxiliary information */
} sg_io_hdr_t;  /* 64 bytes long (on i386) */

/* Use negative values to flag difference from original sg_header structure */
#define SG_DXFER_NONE (-1)      /* e.g. a SCSI Test Unit Ready command */
#define SG_DXFER_TO_DEV (-2)    /* e.g. a SCSI WRITE command */
#define SG_DXFER_FROM_DEV (-3)  /* e.g. a SCSI READ command */
#define SG_DXFER_TO_FROM_DEV (-4) /* treated like SG_DXFER_FROM_DEV with the
				   additional property than during indirect
				   IO the user buffer is copied into the
				   kernel buffers before the transfer */
#define SG_DXFER_UNKNOWN (-5)   /* Unknown data direction */

/* following flag values can be "or"-ed together */
#define SG_FLAG_DIRECT_IO 1     /* default is indirect IO */
#define SG_FLAG_LUN_INHIBIT 2   /* default is overwrite lun in SCSI */
				/* command block (when <= SCSI_2) */
#define SG_FLAG_MMAP_IO 4       /* request memory mapped IO */
#define SG_FLAG_NO_DXFER 0x10000 /* no transfer of kernel buffers to/from */
				/* user space (debug indirect IO) */

/* following 'info' values are "or"-ed together */
#define SG_INFO_OK_MASK 0x1
#define SG_INFO_OK 0x0          /* no sense, host nor driver "noise" */
#define SG_INFO_CHECK 0x1       /* something abnormal happened */

#define SG_INFO_DIRECT_IO_MASK 0x6
#define SG_INFO_INDIRECT_IO 0x0 /* data xfer via kernel buffers (or no xfer) */
#define SG_INFO_DIRECT_IO 0x2   /* direct IO requested and performed */
#define SG_INFO_MIXED_IO 0x4    /* part direct, part indirect IO */


typedef struct sg_scsi_id { /* used by SG_GET_SCSI_ID ioctl() */