root/drivers/block/ide-tape.h

/* [previous][next][first][last][top][bottom][index][help] */

INCLUDED FROM


   1 /*
   2  * linux/drivers/block/ide-tape.h       Version 1.3 - ALPHA     Feb   9, 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  *      ide-tape currently uses two continous 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 correspoding 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 correspoding 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 */

/* [previous][next][first][last][top][bottom][index][help] */