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