include/scsi/sg.h

   1 #ifndef _SCSI_GENERIC_H
   2 #define _SCSI_GENERIC_H
   3
   4 #include <linux/compiler.h>
   5
   6 /*
   7    History:
   8     Started: Aug 9 by Lawrence Foard (entropy@world.std.com), to allow user
   9      process control of SCSI devices.
  10     Development Sponsored by Killy Corp. NY NY
  11 Original driver (sg.h):
  12 *       Copyright (C) 1992 Lawrence Foard
  13 Version 2 and 3 extensions to driver:
  14 *       Copyright (C) 1998 - 2003 Douglas Gilbert
  15
  16     Version: 3.5.29 (20030529)
  17     This version is for 2.5 series kernels.
  18
  19     Changes since 3.5.28 (20030308)
  20         - fix bug introduced in version 3.1.24 (last segment of sgat list)
  21     Changes since 3.5.27 (20020812)
  22         - remove procfs entries: hosts, host_hdr + host_strs (now in sysfs)
  23         - add sysfs sg driver params: def_reserved_size, allow_dio, version
  24         - new boot option: "sg_allow_dio" and module parameter: "allow_dio"
  25         - multiple internal changes due to scsi subsystem rework
  26     Changes since 3.5.26 (20020708)
  27         - re-add direct IO using Kai Makisara's work
  28         - re-tab to 8, start using C99-isms
  29         - simplify memory management
  30     Changes since 3.5.25 (20020504)
  31         - driverfs additions
  32         - copy_to/from_user() fixes [William Stinson]
  33         - disable kiobufs support
  34
  35     For a full changelog see http://www.torque.net/sg
  36
  37 Map of SG verions to the Linux kernels in which they appear:
  38        ----------        ----------------------------------
  39        original          all kernels < 2.2.6
  40        2.1.40            2.2.20
  41        3.0.x             optional version 3 sg driver for 2.2 series
  42        3.1.17++          2.4.0++
  43        3.5.23++          2.5.0++
  44
  45 Major new features in SG 3.x driver (cf SG 2.x drivers)
  46         - SG_IO ioctl() combines function if write() and read()
  47         - new interface (sg_io_hdr_t) but still supports old interface
  48         - scatter/gather in user space, direct IO, and mmap supported
  49
  50  The normal action of this driver is to use the adapter (HBA) driver to DMA
  51  data into kernel buffers and then use the CPU to copy the data into the
  52  user space (vice versa for writes). That is called "indirect" IO due to
  53  the double handling of data. There are two methods offered to remove the
  54  redundant copy: 1) direct IO which uses the kernel kiobuf mechanism and
  55  2) using the mmap() system call to map the reserve buffer (this driver has
  56  one reserve buffer per fd) into the user space. Both have their advantages.
  57  In terms of absolute speed mmap() is faster. If speed is not a concern,
  58  indirect IO should be fine. Read the documentation for more information.
  59
  60  ** N.B. To use direct IO 'echo 1 > /proc/scsi/sg/allow_dio' may be
  61          needed. That pseudo file's content is defaulted to 0. **
  62
  63  Historical note: this SCSI pass-through driver has been known as "sg" for
  64  a decade. In broader kernel discussions "sg" is used to refer to scatter
  65  gather techniques. The context should clarify which "sg" is referred to.
  66
  67  Documentation
  68  =============
  69  A web site for the SG device driver can be found at:
  70         http://www.torque.net/sg  [alternatively check the MAINTAINERS file]
  71  The documentation for the sg version 3 driver can be found at:
  72         http://www.torque.net/sg/p/sg_v3_ho.html
  73  This is a rendering from DocBook source [change the extension to "sgml"
  74  or "xml"]. There are renderings in "ps", "pdf", "rtf" and "txt" (soon).
  75
  76  The older, version 2 documents discuss the original sg interface in detail:
  77         http://www.torque.net/sg/p/scsi-generic.txt
  78         http://www.torque.net/sg/p/scsi-generic_long.txt
  79  A version of this document (potentially out of date) may also be found in
  80  the kernel source tree, probably at:
  81         Documentation/scsi/scsi-generic.txt .
  82
  83  Utility and test programs are available at the sg web site. They are
  84  bundled as sg_utils (for the lk 2.2 series) and sg3_utils (for the
  85  lk 2.4 series).
  86
  87  There is a HOWTO on the Linux SCSI subsystem in the lk 2.4 series at:
  88         http://www.linuxdoc.org/HOWTO/SCSI-2.4-HOWTO
  89 */
  90
  91
  92 /* New interface introduced in the 3.x SG drivers follows */
  93
  94 typedef struct sg_iovec /* same structure as used by readv() Linux system */
  95 {                       /* call. It defines one scatter-gather element. */
  96     void __user *iov_base;      /* Starting address  */
  97     size_t iov_len;             /* Length in bytes  */
  98 } sg_iovec_t;
  99
 100
 101 typedef struct sg_io_hdr
 102 {
 103     int interface_id;           /* [i] 'S' for SCSI generic (required) */
 104     int dxfer_direction;        /* [i] data transfer direction  */
 105     unsigned char cmd_len;      /* [i] SCSI command length ( <= 16 bytes) */
 106     unsigned char mx_sb_len;    /* [i] max length to write to sbp */
 107     unsigned short iovec_count; /* [i] 0 implies no scatter gather */
 108     unsigned int dxfer_len;     /* [i] byte count of data transfer */
 109     void __user *dxferp;        /* [i], [*io] points to data transfer memory
 110                                               or scatter gather list */
 111     unsigned char __user *cmdp; /* [i], [*i] points to command to perform */
 112     void __user *sbp;           /* [i], [*o] points to sense_buffer memory */
 113     unsigned int timeout;       /* [i] MAX_UINT->no timeout (unit: millisec) */
 114     unsigned int flags;         /* [i] 0 -> default, see SG_FLAG... */
 115     int pack_id;                /* [i->o] unused internally (normally) */
 116     void __user * usr_ptr;      /* [i->o] unused internally */
 117     unsigned char status;       /* [o] scsi status */
 118     unsigned char masked_status;/* [o] shifted, masked scsi status */
 119     unsigned char msg_status;   /* [o] messaging level data (optional) */
 120     unsigned char sb_len_wr;    /* [o] byte count actually written to sbp */
 121     unsigned short host_status; /* [o] errors from host adapter */
 122     unsigned short driver_status;/* [o] errors from software driver */
 123     int resid;                  /* [o] dxfer_len - actual_transferred */
 124     unsigned int duration;      /* [o] time taken by cmd (unit: millisec) */
 125     unsigned int info;          /* [o] auxiliary information */
 126 } sg_io_hdr_t;  /* 64 bytes long (on i386) */
 127
 128 #define SG_INTERFACE_ID_ORIG 'S'
 129
 130 /* Use negative values to flag difference from original sg_header structure */
 131 #define SG_DXFER_NONE (-1)      /* e.g. a SCSI Test Unit Ready command */
 132 #define SG_DXFER_TO_DEV (-2)    /* e.g. a SCSI WRITE command */
 133 #define SG_DXFER_FROM_DEV (-3)  /* e.g. a SCSI READ command */
 134 #define SG_DXFER_TO_FROM_DEV (-4) /* treated like SG_DXFER_FROM_DEV with the
 135                                    additional property than during indirect
 136                                    IO the user buffer is copied into the
 137                                    kernel buffers before the transfer */
 138 #define SG_DXFER_UNKNOWN (-5)   /* Unknown data direction */
 139
 140 /* following flag values can be "or"-ed together */
 141 #define SG_FLAG_DIRECT_IO 1     /* default is indirect IO */
 142 #define SG_FLAG_UNUSED_LUN_INHIBIT 2   /* default is overwrite lun in SCSI */
 143                                 /* command block (when <= SCSI_2) */
 144 #define SG_FLAG_MMAP_IO 4       /* request memory mapped IO */
 145 #define SG_FLAG_NO_DXFER 0x10000 /* no transfer of kernel buffers to/from */
 146                                 /* user space (debug indirect IO) */
 147
 148 /* following 'info' values are "or"-ed together */
 149 #define SG_INFO_OK_MASK 0x1
 150 #define SG_INFO_OK 0x0          /* no sense, host nor driver "noise" */
 151 #define SG_INFO_CHECK 0x1       /* something abnormal happened */
 152
 153 #define SG_INFO_DIRECT_IO_MASK 0x6
 154 #define SG_INFO_INDIRECT_IO 0x0 /* data xfer via kernel buffers (or no xfer) */
 155 #define SG_INFO_DIRECT_IO 0x2   /* direct IO requested and performed */
 156 #define SG_INFO_MIXED_IO 0x4    /* part direct, part indirect IO */
 157
 158
 159 typedef struct sg_scsi_id { /* used by SG_GET_SCSI_ID ioctl() */
 160     int host_no;        /* as in "scsi<n>" where 'n' is one of 0, 1, 2 etc */
 161     int channel;
 162     int scsi_id;        /* scsi id of target device */
 163     int lun;
 164     int scsi_type;      /* TYPE_... defined in scsi/scsi.h */
 165     short h_cmd_per_lun;/* host (adapter) maximum commands per lun */
 166     short d_queue_depth;/* device (or adapter) maximum queue length */
 167     int unused[2];      /* probably find a good use, set 0 for now */
 168 } sg_scsi_id_t; /* 32 bytes long on i386 */
 169
 170 typedef struct sg_req_info { /* used by SG_GET_REQUEST_TABLE ioctl() */
 171     char req_state;     /* 0 -> not used, 1 -> written, 2 -> ready to read */
 172     char orphan;        /* 0 -> normal request, 1 -> from interruped SG_IO */
 173     char sg_io_owned;   /* 0 -> complete with read(), 1 -> owned by SG_IO */
 174     char problem;       /* 0 -> no problem detected, 1 -> error to report */
 175     int pack_id;        /* pack_id associated with request */
 176     void __user *usr_ptr;     /* user provided pointer (in new interface) */
 177     unsigned int duration; /* millisecs elapsed since written (req_state==1)
 178                               or request duration (req_state==2) */
 179     int unused;
 180 } sg_req_info_t; /* 20 bytes long on i386 */
 181
 182
 183 /* IOCTLs: Those ioctls that are relevant to the SG 3.x drivers follow.
 184  [Those that only apply to the SG 2.x drivers are at the end of the file.]
 185  (_GET_s yield result via 'int *' 3rd argument unless otherwise indicated) */
 186
 187 #define SG_EMULATED_HOST 0x2203 /* true for emulated host adapter (ATAPI) */
 188
 189 /* Used to configure SCSI command transformation layer for ATAPI devices */
 190 /* Only supported by the ide-scsi driver */
 191 #define SG_SET_TRANSFORM 0x2204 /* N.B. 3rd arg is not pointer but value: */
 192                       /* 3rd arg = 0 to disable transform, 1 to enable it */
 193 #define SG_GET_TRANSFORM 0x2205
 194
 195 #define SG_SET_RESERVED_SIZE 0x2275  /* request a new reserved buffer size */
 196 #define SG_GET_RESERVED_SIZE 0x2272  /* actual size of reserved buffer */
 197
 198 /* The following ioctl has a 'sg_scsi_id_t *' object as its 3rd argument. */
 199 #define SG_GET_SCSI_ID 0x2276   /* Yields fd's bus, chan, dev, lun + type */
 200 /* SCSI id information can also be obtained from SCSI_IOCTL_GET_IDLUN */
 201
 202 /* Override host setting and always DMA using low memory ( <16MB on i386) */
 203 #define SG_SET_FORCE_LOW_DMA 0x2279  /* 0-> use adapter setting, 1-> force */
 204 #define SG_GET_LOW_DMA 0x227a   /* 0-> use all ram for dma; 1-> low dma ram */
 205
 206 /* When SG_SET_FORCE_PACK_ID set to 1, pack_id is input to read() which
 207    tries to fetch a packet with a matching pack_id, waits, or returns EAGAIN.
 208    If pack_id is -1 then read oldest waiting. When ...FORCE_PACK_ID set to 0
 209    then pack_id ignored by read() and oldest readable fetched. */
 210 #define SG_SET_FORCE_PACK_ID 0x227b
 211 #define SG_GET_PACK_ID 0x227c /* Yields oldest readable pack_id (or -1) */
 212
 213 #define SG_GET_NUM_WAITING 0x227d /* Number of commands awaiting read() */
 214
 215 /* Yields max scatter gather tablesize allowed by current host adapter */
 216 #define SG_GET_SG_TABLESIZE 0x227F  /* 0 implies can't do scatter gather */
 217
 218 #define SG_GET_VERSION_NUM 0x2282 /* Example: version 2.1.34 yields 20134 */
 219
 220 /* Returns -EBUSY if occupied. 3rd argument pointer to int (see next) */
 221 #define SG_SCSI_RESET 0x2284
 222 /* Associated values that can be given to SG_SCSI_RESET follow */
 223 #define         SG_SCSI_RESET_NOTHING   0
 224 #define         SG_SCSI_RESET_DEVICE    1
 225 #define         SG_SCSI_RESET_BUS       2
 226 #define         SG_SCSI_RESET_HOST      3
 227
 228 /* synchronous SCSI command ioctl, (only in version 3 interface) */
 229 #define SG_IO 0x2285   /* similar effect as write() followed by read() */
 230
 231 #define SG_GET_REQUEST_TABLE 0x2286   /* yields table of active requests */
 232
 233 /* How to treat EINTR during SG_IO ioctl(), only in SG 3.x series */
 234 #define SG_SET_KEEP_ORPHAN 0x2287 /* 1 -> hold for read(), 0 -> drop (def) */
 235 #define SG_GET_KEEP_ORPHAN 0x2288
 236
 237 /* yields scsi midlevel's access_count for this SCSI device */
 238 #define SG_GET_ACCESS_COUNT 0x2289
 239
 240
 241 #define SG_SCATTER_SZ (8 * 4096)  /* PAGE_SIZE not available to user */
 242 /* Largest size (in bytes) a single scatter-gather list element can have.
 243    The value must be a power of 2 and <= (PAGE_SIZE * 32) [131072 bytes on
 244    i386]. The minimum value is PAGE_SIZE. If scatter-gather not supported
 245    by adapter then this value is the largest data block that can be
 246    read/written by a single scsi command. The user can find the value of
 247    PAGE_SIZE by calling getpagesize() defined in unistd.h . */
 248
 249 #define SG_DEFAULT_RETRIES 0
 250
 251 /* Defaults, commented if they differ from original sg driver */
 252 #define SG_DEF_FORCE_LOW_DMA 0  /* was 1 -> memory below 16MB on i386 */
 253 #define SG_DEF_FORCE_PACK_ID 0
 254 #define SG_DEF_KEEP_ORPHAN 0
 255 #define SG_DEF_RESERVED_SIZE SG_SCATTER_SZ /* load time option */
 256
 257 /* maximum outstanding requests, write() yields EDOM if exceeded */
 258 #define SG_MAX_QUEUE 16
 259
 260 #define SG_BIG_BUFF SG_DEF_RESERVED_SIZE    /* for backward compatibility */
 261
 262 /* Alternate style type names, "..._t" variants preferred */
 263 typedef struct sg_io_hdr Sg_io_hdr;
 264 typedef struct sg_io_vec Sg_io_vec;
 265 typedef struct sg_scsi_id Sg_scsi_id;
 266 typedef struct sg_req_info Sg_req_info;
 267
 268
 269 /* vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv */
 270 /*   The older SG interface based on the 'sg_header' structure follows.   */
 271 /* ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ */
 272
 273 #define SG_MAX_SENSE 16   /* this only applies to the sg_header interface */
 274
 275 struct sg_header
 276 {
 277     int pack_len;    /* [o] reply_len (ie useless), ignored as input */
 278     int reply_len;   /* [i] max length of expected reply (inc. sg_header) */
 279     int pack_id;     /* [io] id number of packet (use ints >= 0) */
 280     int result;      /* [o] 0==ok, else (+ve) Unix errno (best ignored) */
 281     unsigned int twelve_byte:1;
 282         /* [i] Force 12 byte command length for group 6 & 7 commands  */
 283     unsigned int target_status:5;   /* [o] scsi status from target */
 284     unsigned int host_status:8;     /* [o] host status (see "DID" codes) */
 285     unsigned int driver_status:8;   /* [o] driver status+suggestion */
 286     unsigned int other_flags:10;    /* unused */
 287     unsigned char sense_buffer[SG_MAX_SENSE]; /* [o] Output in 3 cases:
 288            when target_status is CHECK_CONDITION or
 289            when target_status is COMMAND_TERMINATED or
 290            when (driver_status & DRIVER_SENSE) is true. */
 291 };      /* This structure is 36 bytes long on i386 */
 292
 293
 294 /* IOCTLs: The following are not required (or ignored) when the sg_io_hdr_t
 295            interface is used. They are kept for backward compatibility with
 296            the original and version 2 drivers. */
 297
 298 #define SG_SET_TIMEOUT 0x2201  /* unit: jiffies (10ms on i386) */
 299 #define SG_GET_TIMEOUT 0x2202  /* yield timeout as _return_ value */
 300
 301 /* Get/set command queuing state per fd (default is SG_DEF_COMMAND_Q.
 302    Each time a sg_io_hdr_t object is seen on this file descriptor, this
 303    command queuing flag is set on (overriding the previous setting). */
 304 #define SG_GET_COMMAND_Q 0x2270   /* Yields 0 (queuing off) or 1 (on) */
 305 #define SG_SET_COMMAND_Q 0x2271   /* Change queuing state with 0 or 1 */
 306
 307 /* Turn on/off error sense trace (1 and 0 respectively, default is off).
 308    Try using: "# cat /proc/scsi/sg/debug" instead in the v3 driver */
 309 #define SG_SET_DEBUG 0x227e    /* 0 -> turn off debug */
 310
 311 #define SG_NEXT_CMD_LEN 0x2283  /* override SCSI command length with given
 312                    number on the next write() on this file descriptor */
 313
 314
 315 /* Defaults, commented if they differ from original sg driver */
 316 #ifdef __KERNEL__
 317 #define SG_DEFAULT_TIMEOUT_USER (60*USER_HZ) /* HZ == 'jiffies in 1 second' */
 318 #else
 319 #define SG_DEFAULT_TIMEOUT      (60*HZ)      /* HZ == 'jiffies in 1 second' */
 320 #endif
 321
 322 #define SG_DEF_COMMAND_Q 0     /* command queuing is always on when
 323                                   the new interface is used */
 324 #define SG_DEF_UNDERRUN_FLAG 0
 325
 326 #endif