include/scsi/sg.h

   1 #ifndef _SCSI_GENERIC_H
   2 #define _SCSI_GENERIC_H
   3
   4 /*
   5    History:
   6     Started: Aug 9 by Lawrence Foard (entropy@world.std.com), to allow user
   7      process control of SCSI devices.
   8     Development Sponsored by Killy Corp. NY NY
   9 Original driver (sg.h):
  10 *       Copyright (C) 1992 Lawrence Foard
  11 2.x extensions to driver:
  12 *       Copyright (C) 1998, 1999 Douglas Gilbert
  13
  14
  15     Version: 2.1.34 (990603)
  16     This version for later 2.1.x and 2.2.x series kernels
  17     D. P. Gilbert (dgilbert@interlog.com, dougg@triode.net.au)
  18
  19     Changes since 2.1.33 (990521)
  20         - implement SG_SET_RESERVED_SIZE and associated memory re-org.
  21         - add SG_NEXT_CMD_LEN to override SCSI command lengths
  22         - add SG_GET_VERSION_NUM to get version expressed as an integer
  23     Changes since 2.1.32 (990501)
  24         - fix race condition in sg_read() and sg_open()
  25     Changes since 2.1.31 (990327)
  26         - add ioctls SG_GET_UNDERRUN_FLAG and _SET_. Change the default
  27           to _not_ flag underruns (affects aic7xxx driver)
  28         - clean up logging of pointers to use %p (for 64 bit architectures)
  29         - rework usage of get_user/copy_to_user family of kernel calls
  30         - "disown" scsi_command blocks before releasing them
  31     Changes since 2.1.30 (990320)
  32         - memory tweaks: change flags on kmalloc (GFP_KERNEL to GFP_ATOMIC)
  33         -                increase max allowable mid-level pool usage
  34
  35
  36     New features and changes:
  37         - per file descriptor (fd) write-read sequencing and command queues.
  38         - command queuing supported (SG_MAX_QUEUE is maximum per fd).
  39         - scatter-gather supported (allowing potentially megabyte transfers).
  40         - the SCSI target, host and driver status are returned
  41           in unused fields of sg_header (maintaining its original size).
  42         - asynchronous notification support added (SIGPOLL, SIGIO) for
  43           read()s (write()s should never block).
  44         - pack_id logic added so read() can wait for a specific pack_id.
  45         - uses memory > ISA_DMA_THRESHOLD if adapter allows it (e.g. a
  46           pci scsi adapter).
  47         - this driver no longer uses a single SG_BIG_BUFF sized buffer
  48           obtained at driver/module init time. Rather it tries to obtain a
  49           SG_DEF_RESERVED_SIZE buffer when a fd is open()ed and frees it
  50           at the corresponding release() (ie per fd). Actually the "buffer"
  51           may be a collection of buffers if scatter-gather is being used.
  52         - add SG_SET_RESERVED_SIZE ioctl allowing the user to request a
  53           large buffer for duration of current file descriptor's lifetime.
  54         - SG_GET_RESERVED_SIZE ioctl can be used to find out how much
  55           actually has been reserved.
  56         - add SG_NEXT_CMD_LEN ioctl to override SCSI command length on
  57           the next write() to this file descriptor.
  58         - SG_GET_RESERVED_SIZE's presence as a symbol can be used for
  59           compile time identification of the version 2 sg driver.
  60           However, it is recommended that run time identification based on
  61           calling the ioctl of the same name is a more flexible and
  62           safer approach.
  63         - adds several ioctl calls, see ioctl section below.
  64
  65  Good documentation on the original "sg" device interface and usage can be
  66  found in the Linux HOWTO document: "SCSI Programming HOWTO" (version 0.5)
  67  by Heiko Eissfeldt; last updated 7 May 1996. Here is a quick summary of
  68  sg basics:
  69  An SG device is accessed by writing SCSI commands plus any associated
  70  outgoing data to it; the resulting status codes and any incoming data
  71  are then obtained by a read call. The device can be opened O_NONBLOCK
  72  (non-blocking) and poll() used to monitor its progress. The device may be
  73  opened O_EXCL which excludes other "sg" users from this device (but not
  74  "sd", "st" or "sr" users). The buffer given to the write() call is made
  75  up as follows:
  76         - struct sg_header image (see below)
  77         - scsi command (6, 10 or 12 bytes long)
  78         - data to be written to the device (if any)
  79
  80  The buffer received from the corresponding read() call contains:
  81         - struct sg_header image (check results + sense_buffer)
  82         - data read back from device (if any)
  83
  84  The given SCSI command has its LUN field overwritten internally by the
  85  value associated with the device that has been opened.
  86
  87  This device currently uses "indirect IO" in the sense that data is
  88  DMAed into kernel buffers from the hardware and afterwards is
  89  transferred into the user space (or vice versa if you are writing).
  90  Transfer speeds or up to 20 to 30MBytes/sec have been measured using
  91  indirect IO. For faster throughputs "direct IO" which cuts out the
  92  double handling of data is required. This will also need a new interface.
  93
  94  Grabbing memory for those kernel buffers used in this driver for DMA may
  95  cause the dreaded ENOMEM error. This error seems to be more prevalent
  96  under early 2.2.x kernels than under the 2.0.x kernel series. For a given
  97  (large) transfer the memory obtained by this driver must be contiguous or
  98  scatter-gather must be used (if supported by the adapter). [Furthermore,
  99  ISA SCSI adapters can only use memory below the 16MB level on a i386.]
 100
 101  When a "sg" device is open()ed O_RDWR then this driver will attempt to
 102  reserve a buffer of SG_DEF_RESERVED_SIZE that will be used by subsequent
 103  write()s on this file descriptor as long as:
 104     -  it is not already in use (eg when command queuing is in use)
 105     -  the write() does not call for a buffer size larger than the
 106        reserved size.
 107  In these cases the write() will attempt to find the memory it needs for
 108  DMA buffers dynamically and in the worst case will fail with ENOMEM.
 109  The amount of memory actually reserved depends on various dynamic factors
 110  and can be checked with the SG_GET_RESERVED_SIZE ioctl(). [In a very
 111  tight memory situation it may yield 0!] The size of the reserved buffer
 112  can be changed with the SG_SET_RESERVED_SIZE ioctl(). It should be
 113  followed with a call to the SG_GET_RESERVED_SIZE ioctl() to find out how
 114  much was actually reserved.
 115
 116  More documentation plus test and utility programs can be found at
 117  http://www.torque.net/sg
 118 */
 119
 120 #define SG_MAX_SENSE 16   /* too little, unlikely to change in 2.2.x */
 121
 122 struct sg_header
 123 {
 124     int pack_len;    /* [o] reply_len (ie useless), ignored as input */
 125     int reply_len;   /* [i] max length of expected reply (inc. sg_header) */
 126     int pack_id;     /* [io] id number of packet (use ints >= 0) */
 127     int result;      /* [o] 0==ok, else (+ve) Unix errno (best ignored) */
 128     unsigned int twelve_byte:1;
 129         /* [i] Force 12 byte command length for group 6 & 7 commands  */
 130     unsigned int target_status:5;   /* [o] scsi status from target */
 131     unsigned int host_status:8;     /* [o] host status (see "DID" codes) */
 132     unsigned int driver_status:8;   /* [o] driver status+suggestion */
 133     unsigned int other_flags:10;    /* unused */
 134     unsigned char sense_buffer[SG_MAX_SENSE]; /* [o] Output in 3 cases:
 135            when target_status is CHECK_CONDITION or
 136            when target_status is COMMAND_TERMINATED or
 137            when (driver_status & DRIVER_SENSE) is true. */
 138 };      /* This structure is 36 bytes long on i386 */
 139
 140
 141 typedef struct sg_scsi_id {
 142     int host_no;        /* as in "scsi<n>" where 'n' is one of 0, 1, 2 etc */
 143     int channel;
 144     int scsi_id;        /* scsi id of target device */
 145     int lun;
 146     int scsi_type;      /* TYPE_... defined in scsi/scsi.h */
 147     int unused1;        /* probably find a good use, set 0 for now */
 148     int unused2;        /* ditto */
 149     int unused3;
 150 } Sg_scsi_id;
 151
 152 /* IOCTLs: ( _GET_s yield result via 'int *' 3rd argument unless
 153              otherwise indicated) */
 154 #define SG_SET_TIMEOUT 0x2201  /* unit: jiffies (10ms on i386) */
 155 #define SG_GET_TIMEOUT 0x2202  /* yield timeout as _return_ value */
 156
 157 #define SG_EMULATED_HOST 0x2203 /* true for emulated host adapter (ATAPI) */
 158
 159 /* Used to configure SCSI command transformation layer for ATAPI devices */
 160 #define SG_SET_TRANSFORM 0x2204
 161 #define SG_GET_TRANSFORM 0x2205
 162
 163 #define SG_SET_RESERVED_SIZE 0x2275  /* request a new reserved buffer size */
 164 #define SG_GET_RESERVED_SIZE 0x2272  /* actual size of reserved buffer */
 165
 166 /* The following ioctl takes a 'Sg_scsi_id *' object as its 3rd argument. */
 167 #define SG_GET_SCSI_ID 0x2276   /* Yields fd's bus, chan, dev, lun + type */
 168 /* SCSI id information can also be obtained from SCSI_IOCTL_GET_IDLUN */
 169
 170 /* Override host setting and always DMA using low memory ( <16MB on i386) */
 171 #define SG_SET_FORCE_LOW_DMA 0x2279  /* 0-> use adapter setting, 1-> force */
 172 #define SG_GET_LOW_DMA 0x227a   /* 0-> use all ram for dma; 1-> low dma ram */
 173
 174 /* When SG_SET_FORCE_PACK_ID set to 1, pack_id is input to read() which
 175    will attempt to read that pack_id or block (or return EAGAIN). If
 176    pack_id is -1 then read oldest waiting. When ...FORCE_PACK_ID set to 0
 177    then pack_id ignored by read() and oldest readable fetched. */
 178 #define SG_SET_FORCE_PACK_ID 0x227b
 179 #define SG_GET_PACK_ID 0x227c /* Yields oldest readable pack_id (or -1) */
 180
 181 #define SG_GET_NUM_WAITING 0x227d /* Number of commands awaiting read() */
 182
 183 /* Turn on error sense trace (1..8), dump this device to log/console (9)
 184    or dump all sg device states ( >9 ) to log/console */
 185 #define SG_SET_DEBUG 0x227e    /* 0 -> turn off debug */
 186
 187 /* Yields max scatter gather tablesize allowed by current host adapter */
 188 #define SG_GET_SG_TABLESIZE 0x227F  /* 0 implies can't do scatter gather */
 189
 190 /* Control whether sequencing per file descriptor or per device */
 191 #define SG_GET_MERGE_FD 0x2274   /* 0-> per fd, 1-> per device */
 192 #define SG_SET_MERGE_FD 0x2273   /* Attempt to change sequencing state,
 193   if more than current fd open on device, will fail with EBUSY */
 194
 195 /* Get/set command queuing state per fd (default is SG_DEF_COMMAND_Q) */
 196 #define SG_GET_COMMAND_Q 0x2270   /* Yields 0 (queuing off) or 1 (on) */
 197 #define SG_SET_COMMAND_Q 0x2271   /* Change queuing state with 0 or 1 */
 198
 199 /* Get/set whether DMA underrun will cause an error (DID_ERROR). This only
 200    currently applies to the [much-used] aic7xxx driver. */
 201 #define SG_GET_UNDERRUN_FLAG 0x2280 /* Yields 0 (don't flag) or 1 (flag) */
 202 #define SG_SET_UNDERRUN_FLAG 0x2281 /* Change flag underrun state */
 203
 204 #define SG_GET_VERSION_NUM 0x2282 /* Example: version 2.1.34 yields 20134 */
 205 #define SG_NEXT_CMD_LEN 0x2283  /* override SCSI command length with given
 206                    number on the next write() on this file descriptor */
 207
 208
 209 #define SG_SCATTER_SZ (8 * 4096)  /* PAGE_SIZE not available to user */
 210 /* Largest size (in bytes) a single scatter-gather list element can have.
 211    The value must be a power of 2 and <= (PAGE_SIZE * 32) [131072 bytes on
 212    i386]. The minimum value is PAGE_SIZE. If scatter-gather not supported
 213    by adapter then this value is the largest data block that can be
 214    read/written by a single scsi command. The user can find the value of
 215    PAGE_SIZE by calling getpagesize() defined in unistd.h . */
 216
 217 #define SG_DEFAULT_TIMEOUT (60*HZ) /* HZ == 'jiffies in 1 second' */
 218 #define SG_DEFAULT_RETRIES 1
 219
 220 /* Defaults, commented if they differ from original sg driver */
 221 #define SG_DEF_COMMAND_Q 0
 222 #define SG_DEF_MERGE_FD 0       /* was 1 -> per device sequencing */
 223 #define SG_DEF_FORCE_LOW_DMA 0  /* was 1 -> memory below 16MB on i386 */
 224 #define SG_DEF_FORCE_PACK_ID 0
 225 #define SG_DEF_UNDERRUN_FLAG 0
 226 #define SG_DEF_RESERVED_SIZE SG_SCATTER_SZ
 227
 228 /* maximum outstanding requests, write() yields EDOM if exceeded */
 229 #define SG_MAX_QUEUE 16
 230
 231 #define SG_BIG_BUFF SG_DEF_RESERVED_SIZE    /* for backward compatibility */
 232
 233 #endif