![[bottom]](../icons/bottom.png){kind=icon}
![[previous]](../icons/n_left.png){kind=icon}
![[next]](../icons/n_right.png){kind=icon}
![[first]](../icons/n_first.png){kind=icon}
![[last]](../icons/n_last.png){kind=icon}
![[top]](../icons/n_top.png){kind=icon}
![[index]](../icons/index.png){kind=icon}
![[help]](../icons/help.png){kind=icon}
*/
1 /*
2 * linux/drivers/block/ide-tape.h Version 1.1 - ALPHA Dec 14, 1995
3 *
4 * Copyright (C) 1995 Gadi Oxman <tgud@tochnapc2.technion.ac.il>
5 */
6
7 /*
8 * Include file for the IDE ATAPI streaming tape driver.
9 *
10 * This file contains various ide-tape related structures and function
11 * prototypes which are already used in ide.h.
12 *
13 * The various compile time options are described below.
14 */
15
16 #ifndef IDETAPE_H
17 #define IDETAPE_H
18
19 /**************************** Tunable parameters *****************************/
20
21 /*
22 * This is probably the most important configuration option.
23 *
24 * Pipelined operation mode has the potential to maximize the
25 * performance of the driver and thus to saturate the throughput
26 * to the maximum value supported by the tape. Currently, pipelined
27 * mode is supported only on writes.
28 *
29 * In pipelined mode we are servicing requests without blocking the
30 * user backup program. For example, on a write request, we will add it
31 * to the pipeline and return without waiting for it to complete. The
32 * user program will then have enough time to prepare the next blocks
33 * while the tape is still busy working on the previous requests.
34 *
35 * Pipelined (write) operation mode is enabled by default, but since
36 * it has a few downfalls as well (Use of additional memory and deferred
37 * error code to the application), you may wish to disable it.
38 * Further explanation of pipelined mode is available in ide-tape.c .
39 */
40
41 #define IDETAPE_PIPELINE 1
42
43 /*
44 * Pipelined mode parameters.
45 *
46 * We try to use the minimum number of stages which is enough to
47 * keep the tape constantly streaming. To accomplish that, we implement
48 * a feedback loop around the maximum number of stages:
49 *
50 * We start from MIN maximum stages (we will not even use MIN stages
51 * if we don't need them), increment it by RATE*(MAX-MIN)
52 * whenever we sense that the pipeline is empty, until we reach
53 * the optimum value or until we reach MAX.
54 */
55
56 #define IDETAPE_MIN_PIPELINE_STAGES 100
57 #define IDETAPE_MAX_PIPELINE_STAGES 200
58 #define IDETAPE_INCREASE_STAGES_RATE 0.2
59
60 /*
61 * It seems that dynamically allocating buffers of about 32KB
62 * each is doomed to fail, unless we are in or very near the
63 * initialization stage. Take care when changing this value, as it
64 * is now optimized with the design of kmalloc, so that we will not
65 * allocate parts of a page. Setting the size to 512 bytes, for example,
66 * would cause kmalloc to allocate for us 1024 bytes, and to
67 * unnecessarily waste double amount of memory.
68 */
69
70 #if PAGE_SIZE == 4096
71 #define IDETAPE_ALLOCATION_BLOCK 500
72 #elif PAGE_SIZE == 8192
73 #define IDETAPE_ALLOCATION_BLOCK 496
74 #else /* ??? Not defined by linux/mm/kmalloc.c */
75 #define IDETAPE_ALLOCATION_BLOCK 512
76 #endif
77
78 /*
79 * Setting IDETAPE_DEBUG to 1 will:
80 *
81 * 1. Generally log all driver actions.
82 * 2. Enable self-sanity checks in some places.
83 *
84 * Use IDETAPE_DEBUG when encountering a problem with the driver.
85 *
86 * Setting IDETAPE_DEBUG to 0 will restore normal operation mode:
87 *
88 * 1. Disable logging normal successful operations.
89 * 2. Disable self-sanity checks.
90 * 3. Errors will still be logged, of course.
91 */
92
93 #define IDETAPE_DEBUG 0
94
95 /*
96 * After each failed packet command we issue a request sense command
97 * and retry the packet command IDETAPE_MAX_PC_RETRIES times.
98 *
99 * Setting IDETAPE_MAX_PC_RETRIES to 0 will disable retries.
100 */
101
102 #define IDETAPE_MAX_PC_RETRIES 2
103
104 /*
105 * With each packet command, we allocate a buffer of
106 * IDETAPE_TEMP_BUFFER_SIZE bytes. This is used for several packet
107 * commands (Not for READ/WRITE commands).
108 *
109 * The default below is too high - We should be using around 100 bytes
110 * typically, but I didn't check all the cases, so I rather be on the
111 * safe size.
112 */
113
114 #define IDETAPE_TEMP_BUFFER_SIZE 256
115
116 /*
117 * In various places in the driver, we need to allocate storage
118 * for packet commands and requests, which will remain valid while
119 * we leave the driver to wait for an interrupt or a timeout event.
120 *
121 * In the corresponding ide_drive_t structure, we pre-allocate storage
122 * for IDETAPE_PC_STACK packet commands and requests. This storage is
123 * used as a circular array - Each time we reach the last entry, we
124 * warp around to the first.
125 *
126 * It is crucial that we have enough entries for the maximum number
127 * of packet commands / sub-requests which we need to allocate during
128 * the handling of a specific request.
129 *
130 * Follows a worse case calculation of the required storage, with a
131 * large safety margin.
132 */
133
134 #define IDETAPE_PC_STACK 20+IDETAPE_MAX_PC_RETRIES
135
136 /*
137 * DSC polling parameters.
138 *
139 * Polling for DSC (a single bit in the status register) is a very
140 * important function in ide-tape. There are two cases in which we
141 * poll for DSC:
142 *
143 * 1. Before a read/write packet command, to ensure that we
144 * can transfer data from/to the tape's data buffers, without
145 * causing an actual media access. In case the tape is not
146 * ready yet, we take out our request from the device
147 * request queue, so that ide.c will service requests from
148 * the other device on the same interface meanwhile.
149 *
150 * The polling frequency is 1/IDETAPE_DSC_READ_WRITE_FREQUENCY,
151 * and it should be relatively fast. The default is a period
152 * of 50 msec.
153 *
154 * 2. After the successful initialization of a "media access
155 * packet command", which is a command which can take a long
156 * time to complete (it can be several seconds or even an hour).
157 *
158 * Again, we postpone our request in the middle to free the bus
159 * for the other device. The polling frequency here should be
160 * lower than the read/write frequency since those media access
161 * commands are slow. We start from a "fast" frequency -
162 * IDETAPE_DSC_FAST_MEDIA_ACCESS_FREQUENCY (one second), and
163 * if we don't receive DSC after IDETAPE_FAST_SLOW_THRESHOLD
164 * (5 minutes), we switch it to a lower frequency -
165 * IDETAPE_DSC_SLOW_MEDIA_ACCESS_FREQUENCY (1 minute).
166 *
167 * We also set a timeout for the timer, in case something goes wrong.
168 * The timeout should be longer then the maximum execution time of a
169 * tape operation. I still have to measure exactly how much time does
170 * it take to space over a far filemark, etc. It seemed that 15 minutes
171 * was way too low, so I am meanwhile setting it to a rather large
172 * timeout - 2 Hours ...
173 *
174 */
175
176 #define IDETAPE_DSC_READ_WRITE_FREQUENCY 5*HZ/100 /* 50 msec */
177 #define IDETAPE_DSC_FAST_MEDIA_ACCESS_FREQUENCY 1*HZ /* 1 second */
178 #define IDETAPE_FAST_SLOW_THRESHOLD 5*60*HZ /* 5 minutes */
179 #define IDETAPE_DSC_SLOW_MEDIA_ACCESS_FREQUENCY 60*HZ /* 1 minute */
180 #define IDETAPE_DSC_TIMEOUT 2*60*60*HZ /* 2 hours */
181
182 /*************************** End of tunable parameters ***********************/
183
184 /*
185 * Definitions which are already needed in ide.h
186 */
187
188 /*
189 * The following is currently not used.
190 */
191
192 typedef enum {no_excess_data,excess_data_read,excess_data_write} excess_data_status_t;
193
194
195 struct ide_drive_s; /* Forward declaration - Will be defined later in ide.h */
196 typedef void (idetape_pc_completed_t)(struct ide_drive_s *);
197
198 /*
199 * Our view of a packet command.
200 */
201
202 typedef struct idetape_packet_command_s {
203 byte c [12]; /* Actual packet bytes */
204
205 byte retries; /* On each retry, we increment retries */
206 byte error; /* Set when an error occured */
207 byte active; /* Set when a packet command is in progress */
208 byte wait_for_dsc; /* 1 When polling for DSC */
209 byte dsc_count;
210 unsigned long request_transfer; /* Bytes to transfer */
211 unsigned long actually_transferred; /* Bytes actually transferred */
212 unsigned long buffer_size; /* Size of our data buffer */
213 byte *buffer; /* Data buffer */
214 byte *current_position; /* Pointer into the above buffer */
215 byte writing; /* Data direction */
216 idetape_pc_completed_t *callback; /* Called when this packet command is completed */
217 byte temp_buffer [IDETAPE_TEMP_BUFFER_SIZE]; /* Temporary buffer */
218 } idetape_packet_command_t;
219
220 /*
221 * Capabilities and Mechanical Status Page
222 */
223
224 typedef struct {
225 unsigned page_code :6; /* Page code - Should be 0x2a */
226 unsigned reserved1_67 :2;
227 byte page_length; /* Page Length - Should be 0x12 */
228 byte reserved2;
229 byte reserved3;
230 unsigned ro :1; /* Read Only Mode */
231 unsigned reserved4_1234 :4;
232 unsigned sprev :1; /* Supports SPACE in the reverse direction */
233 unsigned reserved4_67 :2;
234 unsigned reserved5_012 :3;
235 unsigned efmt :1; /* Supports ERASE command initiated formatting */
236 unsigned reserved5_4 :1;
237 unsigned qfa :1; /* Supports the QFA two partition formats */
238 unsigned reserved5_67 :2;
239 unsigned lock :1; /* Supports locking the volume */
240 unsigned locked :1; /* The volume is locked */
241 unsigned prevent :1; /* The device defaults in the prevent state after power up */
242 unsigned eject :1; /* The device can eject the volume */
243 unsigned reserved6_45 :2; /* Reserved */
244 unsigned ecc :1; /* Supports error correction */
245 unsigned cmprs :1; /* Supports data compression */
246 unsigned reserved7_0 :1;
247 unsigned blk512 :1; /* Supports 512 bytes block size */
248 unsigned blk1024 :1; /* Supports 1024 bytes block size */
249 unsigned reserved7_3_6 :4;
250 unsigned slowb :1; /* The device restricts the byte count for PIO */
251 /* transfers for slow buffer memory ??? */
252 unsigned short max_speed; /* Maximum speed supported in KBps */
253 byte reserved10;
254 byte reserved11;
255 unsigned short ctl; /* Continuous Transfer Limit in blocks */
256 unsigned short speed; /* Current Speed, in KBps */
257 unsigned short buffer_size; /* Buffer Size, in 512 bytes */
258 byte reserved18;
259 byte reserved19;
260 } idetape_capabilities_page_t;
261
262 /*
263 * A pipeline stage contains several small buffers of type
264 * idetape_buffer_head_t. This is necessary since dynamical allocation
265 * of large (32 KB or so) continuous memory blocks will usually fail.
266 */
267
268 typedef struct idetape_buffer_head_s {
269 char *data; /* Pointer to data (512 bytes by default) */
270 struct idetape_buffer_head_s *next;
271 } idetape_buffer_head_t;
272
273 /*
274 * A pipeline stage.
275 *
276 * In a pipeline stage we have a request, pointer to a list of small
277 * buffers, and pointers to the near stages.
278 */
279
280 typedef struct idetape_pipeline_stage_s {
281 struct request rq; /* The correspoding request */
282 idetape_buffer_head_t *bh; /* The data buffers */
283 struct idetape_pipeline_stage_s *next,*prev; /* Pointers to the next and previous stages */
284 } idetape_pipeline_stage_t;
285
286 /*
287 * Most of our global data which we need to save even as we leave the
288 * driver due to an interrupt or a timer event is stored in a variable
289 * of type tape_info, defined below.
290 *
291 * Additional global variables which provide the link between the
292 * character device interface to this structure are defined in
293 * ide-tape.c
294 */
295
296 typedef struct {
297
298 /*
299 * Since a typical character device operation requires more
300 * than one packet command, we provide here enough memory
301 * for the maximum of interconnected packet commands.
302 * The packet commands are stored in the circular array pc_stack.
303 * pc_stack_index points to the last used entry, and warps around
304 * to the start when we get to the last array entry.
305 *
306 * pc points to the current processed packet command.
307 *
308 * failed_pc points to the last failed packet command, or contains
309 * NULL if we do not need to retry any packet command. This is
310 * required since an additional packet command is needed before the
311 * retry, to get detailed information on what went wrong.
312 */
313
314 idetape_packet_command_t *pc; /* Current packet command */
315 idetape_packet_command_t *failed_pc; /* Last failed packet command */
316 idetape_packet_command_t pc_stack [IDETAPE_PC_STACK]; /* Packet command stack */
317 byte pc_stack_index; /* Next free packet command storage space */
318
319 /*
320 * The Linux ide driver basically traverses the request lists
321 * of the ide block devices, finds the next request, completes
322 * it, and passes to the next one. This is done in ide_do_request.
323 *
324 * In this regard, ide-tape.c is fully compatible with the rest of
325 * the ide driver - From the point of view of ide.c, we are just
326 * another ide block device which receives requests and completes
327 * them.
328 *
329 * However, our requests don't originate in the buffer cache but
330 * rather in ide-tape.c itself. Here we provide safe storage for
331 * such requests.
332 */
333
334 struct request rq_stack [IDETAPE_PC_STACK];
335 byte rq_stack_index; /* We implement a circular array */
336
337 /*
338 * While polling for DSC we use postponed_rq to postpone the
339 * current request so that ide.c will be able to service
340 * pending requests on the other device. Note that at most
341 * we will have only one DSC (usually data transfer) request
342 * in the device request queue. Additional request can be
343 * queued in our internal pipeline, but they will be visible
344 * to ide.c only one at a time.
345 */
346
347 struct request *postponed_rq;
348
349 /*
350 * DSC polling variables.
351 */
352
353 byte dsc_count; /* We received DSC dsc_count times in a row */
354 unsigned long dsc_polling_start; /* The time in which we started polling for DSC */
355 struct timer_list dsc_timer; /* Timer used to poll for dsc */
356 unsigned long dsc_polling_frequency; /* The current polling frequency */
357 unsigned long dsc_timeout; /* Maximum waiting time */
358 byte dsc_received; /* Set when we receive DSC */
359
360 byte request_status;
361 byte request_dsc_callback;
362 byte last_status; /* Contents of the tape status register */
363 /* before the current request (saved for us */
364 /* by ide.c) */
365 /* Position information */
366
367 byte partition_num; /* Currently not used */
368 unsigned long block_address; /* Current block */
369 byte block_address_valid; /* 0 When the tape position is unknown */
370 /* (To the tape or to us) */
371 /* Last error information */
372
373 byte sense_key,asc,ascq;
374
375 /* Character device operation */
376
377 unsigned char last_dt_was_write; /* Last character device data transfer was a write */
378 byte busy; /* Device already opened */
379
380 /* Device information */
381
382 unsigned short tape_block_size; /* Usually 512 or 1024 bytes */
383 idetape_capabilities_page_t capabilities; /* Copy of the tape's Capabilities and Mechanical Page */
384
385 /*
386 * Active data transfer request parameters.
387 *
388 * At most, there is only one ide-tape originated data transfer
389 * request in the device request queue. This allows ide.c to
390 * easily service requests from the other device when we
391 * postpone our active request. In the pipelined operation
392 * mode, we use our internal pipeline structure to hold
393 * more data requests.
394 *
395 * The data buffer size is chosen based on the tape's
396 * recommendation.
397 */
398
399 struct request *active_data_request; /* Pointer to the request which is waiting in the device request queue */
400 char *data_buffer; /* The correspoding data buffer (for read/write requests) */
401 int data_buffer_size; /* Data buffer size (chosen based on the tape's recommendation */
402 char *temp_data_buffer; /* Temporary buffer for user <-> kernel space data transfer */
403
404 /*
405 * Pipeline parameters.
406 *
407 * To accomplish non-pipelined mode, we simply set the following
408 * variables to zero (or NULL, where appropriate).
409 */
410
411 int current_number_of_stages; /* Number of currently used stages */
412 int max_number_of_stages; /* We will not allocate more than this number of stages */
413 idetape_pipeline_stage_t *first_stage; /* Will be serviced after the currently active request */
414 idetape_pipeline_stage_t *last_stage; /* New write requests will be added to the pipeline here */
415 int pipeline_was_full_once; /* Set at the first time we fill the pipeline since the tape was opened */
416 int error_in_pipeline_stage; /* Set when an error was detected in one of the pipeline stages */
417 int pipeline_locked; /* Against race conditions ... */
418
419 } idetape_tape_t;
420
421 #define POLL_HWIF_TAPE_DRIVE \
422 if (hwif->tape_drive != NULL) { \
423 if (hwif->tape_drive->tape.request_status) { \
424 OUT_BYTE(hwif->tape_drive->select.all,IDE_SELECT_REG); \
425 hwif->tape_drive->tape.last_status=GET_STAT(); \
426 hwif->tape_drive->tape.request_status=0; \
427 } \
428 if (hwif->tape_drive->tape.request_dsc_callback) { \
429 hwif->tape_drive->tape.request_dsc_callback=0; \
430 idetape_put_back_postponed_request(hwif->tape_drive); \
431 } \
432 }
433
434 #endif /* IDETAPE_H */
![[top]](../icons/top.png){kind=icon}
![[bottom]](../icons/n_bottom.png){kind=icon}
*/