/*
* linux/drivers/block/ide-tape.h Version 1.9 - ALPHA Nov 5, 1996
*
* Copyright (C) 1995, 1996 Gadi Oxman <gadio@netvision.net.il>
*/
/*
* Include file for the IDE ATAPI streaming tape driver.
*
* This file contains various ide-tape related structures and function
* prototypes which are already used in ide.h.
*
* The various compile time options are described below.
*/
#ifndef IDETAPE_H
#define IDETAPE_H
/**************************** Tunable parameters *****************************/
/*
* This is probably the most important configuration option.
*
* Pipelined operation mode has the potential to maximize the
* performance of the driver and thus to saturate the throughput
* to the maximum value supported by the tape.
*
* In pipelined mode we are servicing requests without blocking the
* user backup program. For example, on a write request, we will add it
* to the pipeline and return without waiting for it to complete. The
* user program will then have enough time to prepare the next blocks
* while the tape is still busy working on the previous requests.
*
* Pipelined operation mode is enabled by default, but since it has a
* few downfalls as well, you may wish to disable it.
* Further explanation of pipelined mode is available in ide-tape.c .
*/
#define IDETAPE_PIPELINE 1
/*
* Pipelined mode parameters.
*
* We try to use the minimum number of stages which is enough to
* keep the tape constantly streaming. To accomplish that, we implement
* a feedback loop around the maximum number of stages:
*
* We start from MIN maximum stages (we will not even use MIN stages
* if we don't need them), increment it by RATE*(MAX-MIN)
* whenever we sense that the pipeline is empty, until we reach
* the optimum value or until we reach MAX.
*/
#define IDETAPE_MIN_PIPELINE_STAGES 100
#define IDETAPE_MAX_PIPELINE_STAGES 200
#define IDETAPE_INCREASE_STAGES_RATE 20
/*
* Assuming the tape shares an interface with another device, the default
* behavior is to service our pending pipeline requests as soon as
* possible, but to gracefully postpone them in favor of the other device
* when the tape is busy. This has the potential to maximize our
* throughput and in the same time, to make efficient use of the IDE bus.
*
* Note that when we transfer data to / from the tape, we co-operate with
* the relatively fast tape buffers and the tape will perform the
* actual media access in the background, without blocking the IDE
* bus. This means that as long as the maximum IDE bus throughput is much
* higher than the sum of our maximum throughput and the maximum
* throughput of the other device, we should probably leave the default
* behavior.
*
* However, if it is still desired to give the other device a share even
* in our own (small) bus bandwidth, you can set IDETAPE_LOW_TAPE_PRIORITY
* to 1. This will let the other device finish *all* its pending requests
* before we even check if we can service our next pending request.
*/
#define IDETAPE_LOW_TAPE_PRIORITY 0
/*
* It seems that dynamically allocating buffers of about 32KB
* each is doomed to fail, unless we are in or very near the
* initialization stage. Take care when changing this value, as it
* is now optimized with the design of kmalloc, so that we will not
* allocate parts of a page. Setting the size to 512 bytes, for example,
* would cause kmalloc to allocate for us 1024 bytes, and to
* unnecessarily waste double amount of memory.
*/
#if PAGE_SIZE == 4096
#define IDETAPE_ALLOCATION_BLOCK 500
#elif PAGE_SIZE == 8192
#define IDETAPE_ALLOCATION_BLOCK 496
#else /* ??? Not defined by linux/mm/kmalloc.c */
#define IDETAPE_ALLOCATION_BLOCK 512
#endif
/*
* ide-tape currently uses two continuous buffers, each of the size of
* one stage. By default, those buffers are allocated at initialization
* time and never released, since dynamic allocation of pages bigger
* than PAGE_SIZE may fail as memory becomes fragmented.
*
* This results in about 100 KB memory usage when the tape is idle.
* Setting IDETAPE_MINIMIZE_IDLE_MEMORY_USAGE to 1 will let ide-tape
* to dynamically allocate those buffers, resulting in about 20 KB idle
* memory usage.
*/
#define IDETAPE_MINIMIZE_IDLE_MEMORY_USAGE 0
/*
* The following are used to debug the driver:
*
* Setting IDETAPE_DEBUG_LOG to 1 will log driver flow control.
* Setting IDETAPE_DEBUG_BUGS to 1 will enable self-sanity checks in
* some places.
*
* Setting them to 0 will restore normal operation mode:
*
* 1. Disable logging normal successful operations.
* 2. Disable self-sanity checks.
* 3. Errors will still be logged, of course.
*
* All the #if DEBUG code will be removed some day, when the driver
* is verified to be stable enough. This will make it much more
* esthetic.
*/
#define IDETAPE_DEBUG_LOG 0
#define IDETAPE_DEBUG_BUGS 1
/*
* After each failed packet command we issue a request sense command
* and retry the packet command IDETAPE_MAX_PC_RETRIES times.
*
* Setting IDETAPE_MAX_PC_RETRIES to 0 will disable retries.
*/
#define IDETAPE_MAX_PC_RETRIES 3
/*
* With each packet command, we allocate a buffer of
* IDETAPE_TEMP_BUFFER_SIZE bytes. This is used for several packet
* commands (Not for READ/WRITE commands).
*
* The default below is too high - We should be using around 100 bytes
* typically, but I didn't check all the cases, so I rather be on the
* safe size.
*/
#define IDETAPE_TEMP_BUFFER_SIZE 256
/*
* In various places in the driver, we need to allocate storage
* for packet commands and requests, which will remain valid while
* we leave the driver to wait for an interrupt or a timeout event.
*
* In the corresponding ide_drive_t structure, we pre-allocate storage
* for IDETAPE_PC_STACK packet commands and requests. This storage is
* used as a circular array - Each time we reach the last entry, we
* warp around to the first.
*
* It is crucial that we have enough entries for the maximum number
* of packet commands / sub-requests which we need to allocate during
* the handling of a specific request.
*
* Follows a worse case calculation of the required storage, with a
* large safety margin.
*/
#define IDETAPE_PC_STACK 20+IDETAPE_MAX_PC_RETRIES
/*
* DSC polling parameters.
*
* Polling for DSC (a single bit in the status register) is a very
* important function in ide-tape. There are two cases in which we
* poll for DSC:
*
* 1. Before a read/write packet command, to ensure that we
* can transfer data from/to the tape's data buffers, without
* causing an actual media access. In case the tape is not
* ready yet, we take out our request from the device
* request queue, so that ide.c will service requests from
* the other device on the same interface meanwhile.
*
* We can now automatically select the "best" polling frequency.
* Have a look at IDETAPE_ANTICIPATE_READ_WRITE_DSC below.
*
* In case you don't want to use the automatic selection,
* choose it to be relatively fast. The default fallback
* frequency is 1/50 msec.
*
* 2. After the successful initialization of a "media access
* packet command", which is a command which can take a long
* time to complete (it can be several seconds or even an hour).
*
* Again, we postpone our request in the middle to free the bus
* for the other device. The polling frequency here should be
* lower than the read/write frequency since those media access
* commands are slow. We start from a "fast" frequency -
* IDETAPE_DSC_FAST_MEDIA_ACCESS_FREQUENCY (one second), and
* if we don't receive DSC after IDETAPE_FAST_SLOW_THRESHOLD
* (5 minutes), we switch it to a lower frequency -
* IDETAPE_DSC_SLOW_MEDIA_ACCESS_FREQUENCY (1 minute).
*
* We also set a timeout for the timer, in case something goes wrong.
* The timeout should be longer then the maximum execution time of a
* tape operation. I still have to measure exactly how much time does
* it take to space over a far filemark, etc. It seemed that 15 minutes
* was way too low, so I am meanwhile setting it to a rather large
* timeout - 2 Hours ...
*
*/
/*
* Setting IDETAPE_ANTICIPATE_READ_WRITE_DSC to 1 will allow ide-tape
* to cleverly select the lowest possible frequency which will
* not affect performance, based on the tape parameters and our operation
* mode. This has potential to dramatically decrease our polling load
* on Linux.
*
* However, for the cases in which our calculation fails, setting
* the following option to 0 will force the use of the "fallback"
* polling period defined below (defaults to 50 msec).
*
* In any case, the frequency will be between the "lowest" value
* to the "fallback" value, to ensure that our selected "best" frequency
* is reasonable.
*/
#define IDETAPE_ANTICIPATE_READ_WRITE_DSC 1
/*
* The following parameter is used to select the point in the internal
* tape fifo in which we will start to refill the buffer. Decreasing
* the following parameter will improve the system's latency and
* interactive response, while using a high value might improve sytem
* throughput.
*/
#define IDETAPE_FIFO_THRESHOLD 2
/*
* DSC timings.
*/
#define IDETAPE_DSC_READ_WRITE_FALLBACK_FREQUENCY 5*HZ/100 /* 50 msec */
#define IDETAPE_DSC_READ_WRITE_LOWEST_FREQUENCY 40*HZ/100 /* 400 msec */
#define IDETAPE_DSC_FAST_MEDIA_ACCESS_FREQUENCY 1*HZ /* 1 second */
#define IDETAPE_FAST_SLOW_THRESHOLD 5*60*HZ /* 5 minutes */
#define IDETAPE_DSC_SLOW_MEDIA_ACCESS_FREQUENCY 60*HZ /* 1 minute */
#define IDETAPE_DSC_TIMEOUT 2*60*60*HZ /* 2 hours */
/*************************** End of tunable parameters ***********************/
/*
* Definitions which are already needed in ide.h
*/
/*
* Current character device data transfer direction.
*/
typedef enum {idetape_direction_none,idetape_direction_read,idetape_direction_write} chrdev_direction_t;
struct ide_drive_s; /* Forward declaration - Will be defined later in ide.h */
typedef void (idetape_pc_completed_t)(struct ide_drive_s *);
/*
* Our view of a packet command.
*/
typedef struct idetape_packet_command_s {
byte c [12]; /* Actual packet bytes */
byte retries; /* On each retry, we increment retries */
byte error; /* Error code */
byte abort; /* Set when an error is considered normal - We won't retry */
byte wait_for_dsc; /* 1 When polling for DSC on a media access command */
byte dma_recommended; /* 1 when we prefer to use DMA if possible */
byte dma_in_progress; /* 1 while DMA in progress */
byte dma_error; /* 1 when encountered problem during DMA */
unsigned long request_transfer; /* Bytes to transfer */
unsigned long actually_transferred; /* Bytes actually transferred */
unsigned long buffer_size; /* Size of our data buffer */
byte *buffer; /* Data buffer */
byte *current_position; /* Pointer into the above buffer */
byte writing; /* Data direction */
idetape_pc_completed_t *callback; /* Called when this packet command is completed */
byte temp_buffer [IDETAPE_TEMP_BUFFER_SIZE]; /* Temporary buffer */
} idetape_packet_command_t;
/*
* Capabilities and Mechanical Status Page
*/
typedef struct {
unsigned page_code :6; /* Page code - Should be 0x2a */
unsigned reserved1_67 :2;
byte page_length; /* Page Length - Should be 0x12 */
byte reserved2;
byte reserved3;
unsigned ro :1; /* Read Only Mode */
unsigned reserved4_1234 :4;
unsigned sprev :1; /* Supports SPACE in the reverse direction */
unsigned reserved4_67 :2;
unsigned reserved5_012 :3;
unsigned efmt :1; /* Supports ERASE command initiated formatting */
unsigned reserved5_4 :1;
unsigned qfa :1; /* Supports the QFA two partition formats */
unsigned reserved5_67 :2;
unsigned lock :1; /* Supports locking the volume */
unsigned locked :1; /* The volume is locked */
unsigned prevent :1; /* The device defaults in the prevent state after power up */
unsigned eject :1; /* The device can eject the volume */
unsigned reserved6_45 :2; /* Reserved */
unsigned ecc :1; /* Supports error correction */
unsigned cmprs :1; /* Supports data compression */
unsigned reserved7_0 :1;
unsigned blk512 :1; /* Supports 512 bytes block size */
unsigned blk1024 :1; /* Supports 1024 bytes block size */
unsigned reserved7_3_6 :4;
unsigned slowb :1; /* The device restricts the byte count for PIO */
/* transfers for slow buffer memory ??? */
unsigned short max_speed; /* Maximum speed supported in KBps */
byte reserved10;
byte reserved11;
unsigned short ctl; /* Continuous Transfer Limit in blocks */
unsigned short speed; /* Current Speed, in KBps */
unsigned short buffer_size; /* Buffer Size, in 512 bytes */
byte reserved18;
byte reserved19;
} idetape_capabilities_page_t;
/*
* A pipeline stage contains several small buffers of type
* idetape_buffer_head_t. This is necessary since dynamical allocation
* of large (32 KB or so) continuous memory blocks will usually fail.
*/
typedef struct idetape_buffer_head_s {
char *data; /* Pointer to data (512 bytes by default) */
struct idetape_buffer_head_s *next;
} idetape_buffer_head_t;
/*
* A pipeline stage.
*
* In a pipeline stage we have a request, pointer to a list of small
* buffers, and pointers to the near stages.
*/
typedef struct idetape_pipeline_stage_s {
struct request rq; /* The corresponding request */
idetape_buffer_head_t *bh; /* The data buffers */
struct idetape_pipeline_stage_s *next,*prev; /* Pointers to the next and previous stages */
} idetape_pipeline_stage_t;
/*
* Most of our global data which we need to save even as we leave the
* driver due to an interrupt or a timer event is stored in a variable
* of type tape_info, defined below.
*
* Additional global variables which provide the link between the
* character device interface to this structure are defined in
* ide-tape.c
*/
typedef struct {
/*
* Since a typical character device operation requires more
* than one packet command, we provide here enough memory
* for the maximum of interconnected packet commands.
* The packet commands are stored in the circular array pc_stack.
* pc_stack_index points to the last used entry, and warps around
* to the start when we get to the last array entry.
*
* pc points to the current processed packet command.
*
* failed_pc points to the last failed packet command, or contains
* NULL if we do not need to retry any packet command. This is
* required since an additional packet command is needed before the
* retry, to get detailed information on what went wrong.
*/
idetape_packet_command_t *pc; /* Current packet command */
idetape_packet_command_t *failed_pc; /* Last failed packet command */
idetape_packet_command_t pc_stack [IDETAPE_PC_STACK]; /* Packet command stack */
byte pc_stack_index; /* Next free packet command storage space */
/*
* The Linux ide driver basically traverses the request lists
* of the ide block devices, finds the next request, completes
* it, and passes to the next one. This is done in ide_do_request.
*
* In this regard, ide-tape.c is fully compatible with the rest of
* the ide driver - From the point of view of ide.c, we are just
* another ide block device which receives requests and completes
* them.
*
* However, our requests don't originate in the buffer cache but
* rather in ide-tape.c itself. Here we provide safe storage for
* such requests.
*/
struct request rq_stack [IDETAPE_PC_STACK];
byte rq_stack_index; /* We implement a circular array */
/*
* While polling for DSC we use postponed_rq to postpone the
* current request so that ide.c will be able to service
* pending requests on the other device. Note that at most
* we will have only one DSC (usually data transfer) request
* in the device request queue. Additional request can be
* queued in our internal pipeline, but they will be visible
* to ide.c only one at a time.
*/
struct request *postponed_rq;
/*
* DSC polling variables.
*/
byte dsc_count; /* We received DSC dsc_count times in a row */
unsigned long dsc_polling_start; /* The time in which we started polling for DSC */
struct timer_list dsc_timer; /* Timer used to poll for dsc */
/*
* We can now be much more clever in our selection of the
* read/write polling frequency. This is used along with
* the compile time option IDETAPE_ANTICIPATE_DSC.
*/
unsigned long best_dsc_rw_frequency; /* Read/Write dsc polling frequency */
unsigned long dsc_polling_frequency; /* The current polling frequency */
unsigned long dsc_timeout; /* Maximum waiting time */
byte dsc_received; /* Set when we receive DSC */
byte request_status;
byte last_status; /* Contents of the tape status register */
/* before the current request (saved for us */
/* by ide.c) */
/*
* After an ATAPI software reset, the status register will be
* locked, and thus we need to ignore it when checking DSC for
* the first time.
*/
byte reset_issued;
/* Position information */
byte partition_num; /* Currently not used */
unsigned long block_address; /* Current block */
byte block_address_valid; /* 0 When the tape position is unknown */
/* (To the tape or to us) */
/* Last error information */
byte sense_key,asc,ascq;
/* Character device operation */
chrdev_direction_t chrdev_direction; /* Current character device data transfer direction */
int filemark; /* Currently on a filemark */
byte busy; /* Device already opened */
/* Device information */
unsigned short tape_block_size; /* Usually 512 or 1024 bytes */
idetape_capabilities_page_t capabilities; /* Copy of the tape's Capabilities and Mechanical Page */
/*
* Active data transfer request parameters.
*
* At most, there is only one ide-tape originated data transfer
* request in the device request queue. This allows ide.c to
* easily service requests from the other device when we
* postpone our active request. In the pipelined operation
* mode, we use our internal pipeline structure to hold
* more data requests.
*
* The data buffer size is chosen based on the tape's
* recommendation.
*/
struct request *active_data_request; /* Pointer to the request which is waiting in the device request queue */
char *data_buffer; /* The corresponding data buffer (for read/write requests) */
int data_buffer_size; /* Data buffer size (chosen based on the tape's recommendation */
char *merge_buffer; /* Temporary buffer for user <-> kernel space data transfer */
int merge_buffer_offset;
int merge_buffer_size;
/*
* Pipeline parameters.
*
* To accomplish non-pipelined mode, we simply set the following
* variables to zero (or NULL, where appropriate).
*/
int current_number_of_stages; /* Number of currently used stages */
int max_number_of_stages; /* We will not allocate more than this number of stages */
idetape_pipeline_stage_t *first_stage; /* The first stage which will be removed from the pipeline */
idetape_pipeline_stage_t *active_stage; /* The currently active stage */
idetape_pipeline_stage_t *next_stage; /* Will be serviced after the currently active request */
idetape_pipeline_stage_t *last_stage; /* New requests will be added to the pipeline here */
int error_in_pipeline_stage; /* Set when an error was detected in one of the pipeline stages */
} idetape_tape_t;
/*
* The following is used to have a quick look at the tape's status
* register between requests of the other device.
*/
#define POLL_HWIF_TAPE_DRIVE \
if (hwif->tape_drive != NULL) { \
if (hwif->tape_drive->tape.request_status) { \
SELECT_DRIVE(hwif,hwif->tape_drive); \
hwif->tape_drive->tape.last_status=GET_STAT(); \
hwif->tape_drive->tape.request_status=0; \
} \
}
#endif /* IDETAPE_H */
