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 - 2000 Douglas Gilbert
13
14 Version: 3.1.17 (20000921)
15 This version is for 2.4 series kernels.
16
17 Changes since 3.1.16 (20000716)
18 - changes for new scsi subsystem initialization
19 - change Scsi_Cmnd usage to Scsi_Request
20 - cleanup for no procfs
21 Changes since 3.1.15 (20000528)
22 - further (scatter gather) buffer length changes
23 Changes since 3.1.14 (20000503)
24 - fix aha1542 odd length buffer problem
25 - make multiple readers on same fd safe
26 Changes since 3.1.13 (20000324)
27 - revert change so sg_header interface doesn't send _UNKNOWN
28 - "discon" and "tq" in /proc/scsi/sg/devices replaced with
29 "bopens" and "busy"; correct duration output in procfs
30 - provision for SG_RESET
31 - lock file descriptor and request lists
32 Changes since 3.1.12 (20000222)
33 - make sg_header interface use SCSI_DATA_UNKNOWN
34 - add SG_DXFER_UNKNOWN define to sg interface
35 - stop allocating data buffers to non data transfer commands
36 Changes since 3.1.10 (20000123)
37 - make device allocation dynamic (get rid of SG_EXTRA_DEVS)
38 - move to sg0,sg1,sg2 rather than sga,sgb,sgc
39 - make sg_io_hdr_t safer across architectures
40 Changes since 2.1.34 (990603) and 2.3.35 (990708)
41 - add new interface structure: sg_io_hdr_t
42 - supports larger sense buffer, DMA residual count + direct IO
43 - add SG_IO ioctl (combines function of write() + read() )
44 - remove SG_SET_MERGE_FD, UNDERRUN_FLAG + _GET_ ioctls + logic
45 - add proc_fs support in /proc/scsi/sg/ directory
46 - add queuing info into struct sg_scsi_id
47 - def_reserved_size can be given at driver or module load time
48 Changes since 2.1.33 (990521)
49 - implement SG_SET_RESERVED_SIZE and associated memory re-org.
50 - add SG_NEXT_CMD_LEN to override SCSI command lengths
51 - add SG_GET_VERSION_NUM to get version expressed as an integer
52 Changes since 2.1.32 (990501)
53 - fix race condition in sg_read() and sg_open()
54 Changes since 2.1.31 (990327)
55 - add ioctls SG_GET_UNDERRUN_FLAG and _SET_. Change the default
56 to _not_ flag underruns (affects aic7xxx driver)
57 - clean up logging of pointers to use %p (for 64 bit architectures)
58 - rework usage of get_user/copy_to_user family of kernel calls
59 - "disown" scsi_command blocks before releasing them
60
61 Map of SG verions to the Linux kernels in which they appear:
62 ---------- ----------------------------------
63 original all kernels < 2.2.6
64 2.1.31 2.2.6 and 2.2.7
65 2.1.32 2.2.8 and 2.2.9
66 2.1.34 2.2.10 to 2.2.13
67 2.1.36 2.2.14 and 2.2.15
68 3.0.x optional version 3 sg driver for 2.2 series
69 3.1.x first appeared in lk 2.3.43
70
71 Major new features in SG 3.x driver (cf SG 2.x drivers)
72 - SG_IO ioctl() combines function if write() and read()
73 - new interface (sg_io_hdr_t) but still supports old interface
74 - scatter/gather in user space and direct IO supported
75
76 Major features in SG 2.x driver (cf original SG driver)
77 - per file descriptor (fd) write-read sequencing
78 - command queuing supported
79 - scatter-gather supported at kernel level allowing potentially
80 large transfers
81 - more SCSI status information returned
82 - asynchronous notification support added (SIGPOLL, SIGIO)
83 - read() can fetch by given pack_id
84 - uses kernel memory as appropriate for SCSI adapter being used
85 - single SG_BIG_BUFF replaced by per file descriptor "reserve
86 buffer" whose size can be manipulated by ioctls()
87
88 The term "indirect IO" refers a method by which data is DMAed into kernel
89 buffers from the hardware and afterwards is transferred into the user
90 space (or vice versa if you are writing). Transfer speeds of up to 20 to
91 30MBytes/sec have been measured using indirect IO. For faster throughputs
92 "direct IO" which cuts out the double handling of data is required.
93 Direct IO is supported by the SG 3.x drivers on 2.3 series Linux kernels
94 (or later) and requires the use of the new interface.
95
96 Requests for direct IO with the new interface will automatically fall back
97 to indirect IO mode if they cannot be fulfilled. An example of such a case
98 is an ISA SCSI adapter which is only capable of DMAing to the lower 16MB of
99 memory due to the architecture of ISA. The 'info' field in the new
100 interface indicates whether a direct or indirect data transfer took place.
101
102 Obtaining memory for the kernel buffers used in indirect IO is done by
103 first checking if the "reserved buffer" for the current file descriptor
104 is available and large enough. If these conditions are _not_ met then
105 kernel memory is obtained on a per SCSI command basis. This corresponds
106 to a write(), read() sequence or a SG_IO ioctl() call. Further, the
107 kernel memory that is suitable for DMA may be constrained by the
108 architecture of the SCSI adapter (e.g. ISA adapters).
109
110 Documentation
111 =============
112 A web site for SG device drivers can be found at:
113 http://www.torque.net/sg [alternatively check the MAINTAINERS file]
114 The main documents are still based on 2.x versions:
115 http://www.torque.net/sg/p/scsi-generic.txt
116 http://www.torque.net/sg/p/scsi-generic_long.txt
117 Documentation on the changes and additions in 3.x version of the sg driver
118 can be found at: http://www.torque.net/sg/p/scsi-generic_v3.txt
119 This document can also be found in the kernel source tree, probably at:
120 /usr/src/linux/Documentation/scsi-generic.txt .
121 Utility and test programs are also available at that web site.
122 */
123
124 /* New interface introduced in the 3.x SG drivers follows */
125
126 typedef struct sg_iovec /* same structure as used by readv() Linux system */
127 { /* call. It defines one scatter-gather element. */
128 void * iov_base; /* Starting address */
129 size_t iov_len; /* Length in bytes */
130 } sg_iovec_t;
131
132
133 typedef struct sg_io_hdr
134 {
135 int interface_id; /* [i] 'S' for SCSI generic (required) */
136 int dxfer_direction; /* [i] data transfer direction */
137 unsigned char cmd_len; /* [i] SCSI command length ( <= 16 bytes) */
138 unsigned char mx_sb_len; /* [i] max length to write to sbp */
139 unsigned short iovec_count; /* [i] 0 implies no scatter gather */
140 unsigned int dxfer_len; /* [i] byte count of data transfer */
141 void * dxferp; /* [i], [*io] points to data transfer memory
142 or scatter gather list */
143 unsigned char * cmdp; /* [i], [*i] points to command to perform */
144 unsigned char * sbp; /* [i], [*o] points to sense_buffer memory */
145 unsigned int timeout; /* [i] MAX_UINT->no timeout (unit: millisec) */
146 unsigned int flags; /* [i] 0 -> default, see SG_FLAG... */
147 int pack_id; /* [i->o] unused internally (normally) */
148 void * usr_ptr; /* [i->o] unused internally */
149 unsigned char status; /* [o] scsi status */
150 unsigned char masked_status;/* [o] shifted, masked scsi status */
151 unsigned char msg_status; /* [o] messaging level data (optional) */
152 unsigned char sb_len_wr; /* [o] byte count actually written to sbp */
153 unsigned short host_status; /* [o] errors from host adapter */
154 unsigned short driver_status;/* [o] errors from software driver */
155 int resid; /* [o] dxfer_len - actual_transferred */
156 unsigned int duration; /* [o] time taken by cmd (unit: millisec) */
157 unsigned int info; /* [o] auxiliary information */
158 } sg_io_hdr_t; /* 64 bytes long (on i386) */
159
160 /* Use negative values to flag difference from original sg_header structure */
161 #define SG_DXFER_NONE -1 /* e.g. a SCSI Test Unit Ready command */
162 #define SG_DXFER_TO_DEV -2 /* e.g. a SCSI WRITE command */
163 #define SG_DXFER_FROM_DEV -3 /* e.g. a SCSI READ command */
164 #define SG_DXFER_TO_FROM_DEV -4 /* treated like SG_DXFER_FROM_DEV with the
165 additional property than during indirect
166 IO the user buffer is copied into the
167 kernel buffers before the transfer */
168 #define SG_DXFER_UNKNOWN -5 /* Unknown data direction */
169
170 /* following flag values can be "or"-ed together */
171 #define SG_FLAG_DIRECT_IO 1 /* default is indirect IO */
172 #define SG_FLAG_LUN_INHIBIT 2 /* default is to put device's lun into */
173 /* the 2nd byte of SCSI command */
174 #define SG_FLAG_NO_DXFER 0x10000 /* no transfer of kernel buffers to/from */
175 /* user space (debug indirect IO) */
176
177 /* following 'info' values are "or"-ed together */
178 #define SG_INFO_OK_MASK 0x1
179 #define SG_INFO_OK 0x0 /* no sense, host nor driver "noise" */
180 #define SG_INFO_CHECK 0x1 /* something abnormal happened */
181
182 #define SG_INFO_DIRECT_IO_MASK 0x6
183 #define SG_INFO_INDIRECT_IO 0x0 /* data xfer via kernel buffers (or no xfer) */
184 #define SG_INFO_DIRECT_IO 0x2 /* direct IO requested and performed */
185 #define SG_INFO_MIXED_IO 0x4 /* part direct, part indirect IO */
186
187
188 typedef struct sg_scsi_id { /* used by SG_GET_SCSI_ID ioctl() */
189 int host_no; /* as in "scsi<n>" where 'n' is one of 0, 1, 2 etc */
190 int channel;
191 int scsi_id; /* scsi id of target device */
192 int lun;
193 int scsi_type; /* TYPE_... defined in scsi/scsi.h */
194 short h_cmd_per_lun;/* host (adapter) maximum commands per lun */
195 short d_queue_depth;/* device (or adapter) maximum queue length */
196 int unused[2]; /* probably find a good use, set 0 for now */
197 } sg_scsi_id_t; /* 32 bytes long on i386 */
198
199 typedef struct sg_req_info { /* used by SG_GET_REQUEST_TABLE ioctl() */
200 char req_state; /* 0 -> not used, 1 -> written, 2 -> ready to read */
201 char orphan; /* 0 -> normal request, 1 -> from interruped SG_IO */
202 char sg_io_owned; /* 0 -> complete with read(), 1 -> owned by SG_IO */
203 char problem; /* 0 -> no problem detected, 1 -> error to report */
204 int pack_id; /* pack_id associated with request */
205 void * usr_ptr; /* user provided pointer (in new interface) */
206 unsigned int duration; /* millisecs elapsed since written (req_state==1)
207 or request duration (req_state==2) */
208 int unused;
209 } sg_req_info_t; /* 20 bytes long on i386 */
210
211
212 /* IOCTLs: Those ioctls that are relevant to the SG 3.x drivers follow.
213 [Those that only apply to the SG 2.x drivers are at the end of the file.]
214 (_GET_s yield result via 'int *' 3rd argument unless otherwise indicated) */
215
216 #define SG_EMULATED_HOST 0x2203 /* true for emulated host adapter (ATAPI) */
217
218 /* Used to configure SCSI command transformation layer for ATAPI devices */
219 /* Only supported by the ide-scsi driver */
220 #define SG_SET_TRANSFORM 0x2204 /* N.B. 3rd arg is not pointer but value: */
221 /* 3rd arg = 0 to disable transform, 1 to enable it */
222 #define SG_GET_TRANSFORM 0x2205
223
224 #define SG_SET_RESERVED_SIZE 0x2275 /* request a new reserved buffer size */
225 #define SG_GET_RESERVED_SIZE 0x2272 /* actual size of reserved buffer */
226
227 /* The following ioctl has a 'sg_scsi_id_t *' object as its 3rd argument. */
228 #define SG_GET_SCSI_ID 0x2276 /* Yields fd's bus, chan, dev, lun + type */
229 /* SCSI id information can also be obtained from SCSI_IOCTL_GET_IDLUN */
230
231 /* Override host setting and always DMA using low memory ( <16MB on i386) */
232 #define SG_SET_FORCE_LOW_DMA 0x2279 /* 0-> use adapter setting, 1-> force */
233 #define SG_GET_LOW_DMA 0x227a /* 0-> use all ram for dma; 1-> low dma ram */
234
235 /* When SG_SET_FORCE_PACK_ID set to 1, pack_id is input to read() which
236 tries to fetch a packet with a matching pack_id, waits, or returns EAGAIN.
237 If pack_id is -1 then read oldest waiting. When ...FORCE_PACK_ID set to 0
238 then pack_id ignored by read() and oldest readable fetched. */
239 #define SG_SET_FORCE_PACK_ID 0x227b
240 #define SG_GET_PACK_ID 0x227c /* Yields oldest readable pack_id (or -1) */
241
242 #define SG_GET_NUM_WAITING 0x227d /* Number of commands awaiting read() */
243
244 /* Yields max scatter gather tablesize allowed by current host adapter */
245 #define SG_GET_SG_TABLESIZE 0x227F /* 0 implies can't do scatter gather */
246
247 #define SG_GET_VERSION_NUM 0x2282 /* Example: version 2.1.34 yields 20134 */
248
249 /* Returns -EBUSY if occupied. 3rd argument pointer to int (see next) */
250 #define SG_SCSI_RESET 0x2284
251 /* Associated values that can be given to SG_SCSI_RESET follow */
252 #define SG_SCSI_RESET_NOTHING 0
253 #define SG_SCSI_RESET_DEVICE 1
254 #define SG_SCSI_RESET_BUS 2
255 #define SG_SCSI_RESET_HOST 3
256
257 /* synchronous SCSI command ioctl, (only in version 3 interface) */
258 #define SG_IO 0x2285 /* similar effect as write() followed by read() */
259
260 #define SG_GET_REQUEST_TABLE 0x2286 /* yields table of active requests */
261
262 /* How to treat EINTR during SG_IO ioctl(), only in SG 3.x series */
263 #define SG_SET_KEEP_ORPHAN 0x2287 /* 1 -> hold for read(), 0 -> drop (def) */
264 #define SG_GET_KEEP_ORPHAN 0x2288
265
266
267 #define SG_SCATTER_SZ (8 * 4096) /* PAGE_SIZE not available to user */
268 /* Largest size (in bytes) a single scatter-gather list element can have.
269 The value must be a power of 2 and <= (PAGE_SIZE * 32) [131072 bytes on
270 i386]. The minimum value is PAGE_SIZE. If scatter-gather not supported
271 by adapter then this value is the largest data block that can be
272 read/written by a single scsi command. The user can find the value of
273 PAGE_SIZE by calling getpagesize() defined in unistd.h . */
274
275 #define SG_DEFAULT_RETRIES 1
276
277 /* Defaults, commented if they differ from original sg driver */
278 #define SG_DEF_FORCE_LOW_DMA 0 /* was 1 -> memory below 16MB on i386 */
279 #define SG_DEF_FORCE_PACK_ID 0
280 #define SG_DEF_KEEP_ORPHAN 0
281 #define SG_DEF_RESERVED_SIZE SG_SCATTER_SZ /* load time option */
282
283 /* maximum outstanding requests, write() yields EDOM if exceeded */
284 #define SG_MAX_QUEUE 16
285
286 #define SG_BIG_BUFF SG_DEF_RESERVED_SIZE /* for backward compatibility */
287
288 /* Alternate style type names, "..._t" variants preferred */
289 typedef struct sg_io_hdr Sg_io_hdr;
290 typedef struct sg_io_vec Sg_io_vec;
291 typedef struct sg_scsi_id Sg_scsi_id;
292 typedef struct sg_req_info Sg_req_info;
293
294
295 /* vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv */
296 /* The older SG interface based on the 'sg_header' structure follows. */
297 /* ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ */
298
299 #define SG_MAX_SENSE 16 /* this only applies to the sg_header interface */
300
301 struct sg_header
302 {
303 int pack_len; /* [o] reply_len (ie useless), ignored as input */
304 int reply_len; /* [i] max length of expected reply (inc. sg_header) */
305 int pack_id; /* [io] id number of packet (use ints >= 0) */
306 int result; /* [o] 0==ok, else (+ve) Unix errno (best ignored) */
307 unsigned int twelve_byte:1;
308 /* [i] Force 12 byte command length for group 6 & 7 commands */
309 unsigned int target_status:5; /* [o] scsi status from target */
310 unsigned int host_status:8; /* [o] host status (see "DID" codes) */
311 unsigned int driver_status:8; /* [o] driver status+suggestion */
312 unsigned int other_flags:10; /* unused */
313 unsigned char sense_buffer[SG_MAX_SENSE]; /* [o] Output in 3 cases:
314 when target_status is CHECK_CONDITION or
315 when target_status is COMMAND_TERMINATED or
316 when (driver_status & DRIVER_SENSE) is true. */
317 }; /* This structure is 36 bytes long on i386 */
318
319
320 /* IOCTLs: The following are not required (or ignored) when the sg_io_hdr_t
321 interface is used. They are kept for backward compatibility with
322 the original and version 2 drivers. */
323
324 #define SG_SET_TIMEOUT 0x2201 /* unit: jiffies (10ms on i386) */
325 #define SG_GET_TIMEOUT 0x2202 /* yield timeout as _return_ value */
326
327 /* Get/set command queuing state per fd (default is SG_DEF_COMMAND_Q.
328 Each time a sg_io_hdr_t object is seen on this file descriptor, this
329 command queuing flag is set on (overriding the previous setting). */
330 #define SG_GET_COMMAND_Q 0x2270 /* Yields 0 (queuing off) or 1 (on) */
331 #define SG_SET_COMMAND_Q 0x2271 /* Change queuing state with 0 or 1 */
332
333 /* Turn on/off error sense trace (1 and 0 respectively, default is off).
334 Try using: "# cat /proc/scsi/sg/debug" instead in the v3 driver */
335 #define SG_SET_DEBUG 0x227e /* 0 -> turn off debug */
336
337 #define SG_NEXT_CMD_LEN 0x2283 /* override SCSI command length with given
338 number on the next write() on this file descriptor */
339
340
341 /* Defaults, commented if they differ from original sg driver */
342 #define SG_DEFAULT_TIMEOUT (60*HZ) /* HZ == 'jiffies in 1 second' */
343 #define SG_DEF_COMMAND_Q 0 /* command queuing is always on when
344 the new interface is used */
345 #define SG_DEF_UNDERRUN_FLAG 0
346
347 #endif
348
This page was automatically generated by the
LXR engine.
Visit the LXR main site for more
information.