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 */