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