← Back to branch summary

~ubuntu-branches/ubuntu/utopic/xen/utopic

« back to all changes in this revision

Viewing changes to xen/include/scsi/sg.h

  • Committer: Bazaar Package Importer
  • Author(s): Bastian Blank
  • Date: 2010-05-06 15:47:38 UTC
  • mto: (1.3.1) (15.1.1 sid) (4.1.1 experimental)
  • mto: This revision was merged to the branch mainline in revision 3.
  • Revision ID: james.westby@ubuntu.com-20100506154738-agoz0rlafrh1fnq7
Tags: upstream-4.0.0
Import upstream version 4.0.0

Show diffs side-by-side

added added

removed removed

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