1 files changed, 146 insertions, 0 deletions
diff --git a/Documentation/ide/ide-tape.txt b/Documentation/ide/ide-tape.txt
new file mode 100644
index 000000000000..658f271a373f
--- /dev/null
+++ b/Documentation/ide/ide-tape.txt
@@ -0,0 +1,146 @@
+/*
+ * IDE ATAPI streaming tape driver.
+ *
+ * This driver is a part of the Linux ide driver.
+ *
+ * The driver, in co-operation with ide.c, basically traverses the
+ * request-list for the block device interface. The character device
+ * interface, on the other hand, creates new requests, adds them
+ * to the request-list of the block device, and waits for their completion.
+ *
+ * Pipelined operation mode is now supported on both reads and writes.
+ *
+ * The block device major and minor numbers are determined from the
+ * tape's relative position in the ide interfaces, as explained in ide.c.
+ *
+ * The character device interface consists of the following devices:
+ *
+ * ht0          major 37, minor 0       first  IDE tape, rewind on close.
+ * ht1          major 37, minor 1       second IDE tape, rewind on close.
+ * ...
+ * nht0         major 37, minor 128     first  IDE tape, no rewind on close.
+ * nht1         major 37, minor 129     second IDE tape, no rewind on close.
+ * ...
+ *
+ * The general magnetic tape commands compatible interface, as defined by
+ * include/linux/mtio.h, is accessible through the character device.
+ *
+ * General ide driver configuration options, such as the interrupt-unmask
+ * flag, can be configured by issuing an ioctl to the block device interface,
+ * as any other ide device.
+ *
+ * Our own ide-tape ioctl's can be issued to either the block device or
+ * the character device interface.
+ *
+ * Maximal throughput with minimal bus load will usually be achieved in the
+ * following scenario:
+ *
+ *      1.      ide-tape is operating in the pipelined operation mode.
+ *      2.      No buffering is performed by the user backup program.
+ *
+ * Testing was done with a 2 GB CONNER CTMA 4000 IDE ATAPI Streaming Tape Drive.
+ *
+ * Here are some words from the first releases of hd.c, which are quoted
+ * in ide.c and apply here as well:
+ *
+ * | Special care is recommended.  Have Fun!
+ *
+ *
+ * An overview of the pipelined operation mode.
+ *
+ * In the pipelined write mode, we will usually just add requests to our
+ * pipeline and return immediately, before we even start to service them. The
+ * user program will then have enough time to prepare the next request while
+ * we are still busy servicing previous requests. In the pipelined read mode,
+ * the situation is similar - we add read-ahead requests into the pipeline,
+ * before the user even requested them.
+ *
+ * The pipeline can be viewed as a "safety net" which will be activated when
+ * the system load is high and prevents the user backup program from keeping up
+ * with the current tape speed. At this point, the pipeline will get
+ * shorter and shorter but the tape will still be streaming at the same speed.
+ * Assuming we have enough pipeline stages, the system load will hopefully
+ * decrease before the pipeline is completely empty, and the backup program
+ * will be able to "catch up" and refill the pipeline again.
+ *
+ * When using the pipelined mode, it would be best to disable any type of
+ * buffering done by the user program, as ide-tape already provides all the
+ * benefits in the kernel, where it can be done in a more efficient way.
+ * As we will usually not block the user program on a request, the most
+ * efficient user code will then be a simple read-write-read-... cycle.
+ * Any additional logic will usually just slow down the backup process.
+ *
+ * Using the pipelined mode, I get a constant over 400 KBps throughput,
+ * which seems to be the maximum throughput supported by my tape.
+ *
+ * However, there are some downfalls:
+ *
+ *      1.      We use memory (for data buffers) in proportional to the number
+ *              of pipeline stages (each stage is about 26 KB with my tape).
+ *      2.      In the pipelined write mode, we cheat and postpone error codes
+ *              to the user task. In read mode, the actual tape position
+ *              will be a bit further than the last requested block.
+ *
+ * Concerning (1):
+ *
+ *      1.      We allocate stages dynamically only when we need them. When
+ *              we don't need them, we don't consume additional memory. In
+ *              case we can't allocate stages, we just manage without them
+ *              (at the expense of decreased throughput) so when Linux is
+ *              tight in memory, we will not pose additional difficulties.
+ *
+ *      2.      The maximum number of stages (which is, in fact, the maximum
+ *              amount of memory) which we allocate is limited by the compile
+ *              time parameter IDETAPE_MAX_PIPELINE_STAGES.
+ *
+ *      3.      The maximum number of stages is a controlled parameter - We
+ *              don't start from the user defined maximum number of stages
+ *              but from the lower IDETAPE_MIN_PIPELINE_STAGES (again, we
+ *              will not even allocate this amount of stages if the user
+ *              program can't handle the speed). We then implement a feedback
+ *              loop which checks if the pipeline is empty, and if it is, we
+ *              increase the maximum number of stages as necessary until we
+ *              reach the optimum value which just manages to keep the tape
+ *              busy with minimum allocated memory or until we reach
+ *              IDETAPE_MAX_PIPELINE_STAGES.
+ *
+ * Concerning (2):
+ *
+ *      In pipelined write mode, ide-tape can not return accurate error codes
+ *      to the user program since we usually just add the request to the
+ *      pipeline without waiting for it to be serviced. In case an error
+ *      occurs, I will report it on the next user request.
+ *
+ *      In the pipelined read mode, subsequent read requests or forward
+ *      filemark spacing will perform correctly, as we preserve all blocks
+ *      and filemarks which we encountered during our excess read-ahead.
+ *
+ *      For accurate tape positioning and error reporting, disabling
+ *      pipelined mode might be the best option.
+ *
+ * You can enable/disable/tune the pipelined operation mode by adjusting
+ * the compile time parameters below.
+ *
+ *
+ *      Possible improvements.
+ *
+ *      1.      Support for the ATAPI overlap protocol.
+ *
+ *              In order to maximize bus throughput, we currently use the DSC
+ *              overlap method which enables ide.c to service requests from the
+ *              other device while the tape is busy executing a command. The
+ *              DSC overlap method involves polling the tape's status register
+ *              for the DSC bit, and servicing the other device while the tape
+ *              isn't ready.
+ *
+ *              In the current QIC development standard (December 1995),
+ *              it is recommended that new tape drives will *in addition*
+ *              implement the ATAPI overlap protocol, which is used for the
+ *              same purpose - efficient use of the IDE bus, but is interrupt
+ *              driven and thus has much less CPU overhead.
+ *
+ *              ATAPI overlap is likely to be supported in most new ATAPI
+ *              devices, including new ATAPI cdroms, and thus provides us
+ *              a method by which we can achieve higher throughput when
+ *              sharing a (fast) ATA-2 disk with any (slow) new ATAPI device.
+ */

diff --git a/Documentation/ide/ide-tape.txt b/Documentation/ide/ide-tape.txt new file mode 100644 index 000000000000..658f271a373f --- /dev/null +++ b/Documentation/ide/ide-tape.txt
@@ -0,0 +1,146 @@
	1	/*
	2	* IDE ATAPI streaming tape driver.
	3	*
	4	* This driver is a part of the Linux ide driver.
	5	*
	6	* The driver, in co-operation with ide.c, basically traverses the
	7	* request-list for the block device interface. The character device
	8	* interface, on the other hand, creates new requests, adds them
	9	* to the request-list of the block device, and waits for their completion.
	10	*
	11	* Pipelined operation mode is now supported on both reads and writes.
	12	*
	13	* The block device major and minor numbers are determined from the
	14	* tape's relative position in the ide interfaces, as explained in ide.c.
	15	*
	16	* The character device interface consists of the following devices:
	17	*
	18	* ht0 major 37, minor 0 first IDE tape, rewind on close.
	19	* ht1 major 37, minor 1 second IDE tape, rewind on close.
	20	* ...
	21	* nht0 major 37, minor 128 first IDE tape, no rewind on close.
	22	* nht1 major 37, minor 129 second IDE tape, no rewind on close.
	23	* ...
	24	*
	25	* The general magnetic tape commands compatible interface, as defined by
	26	* include/linux/mtio.h, is accessible through the character device.
	27	*
	28	* General ide driver configuration options, such as the interrupt-unmask
	29	* flag, can be configured by issuing an ioctl to the block device interface,
	30	* as any other ide device.
	31	*
	32	* Our own ide-tape ioctl's can be issued to either the block device or
	33	* the character device interface.
	34	*
	35	* Maximal throughput with minimal bus load will usually be achieved in the
	36	* following scenario:
	37	*
	38	* 1. ide-tape is operating in the pipelined operation mode.
	39	* 2. No buffering is performed by the user backup program.
	40	*
	41	* Testing was done with a 2 GB CONNER CTMA 4000 IDE ATAPI Streaming Tape Drive.
	42	*
	43	* Here are some words from the first releases of hd.c, which are quoted
	44	* in ide.c and apply here as well:
	45	*
	46	* \| Special care is recommended. Have Fun!
	47	*
	48	*
	49	* An overview of the pipelined operation mode.
	50	*
	51	* In the pipelined write mode, we will usually just add requests to our
	52	* pipeline and return immediately, before we even start to service them. The
	53	* user program will then have enough time to prepare the next request while
	54	* we are still busy servicing previous requests. In the pipelined read mode,
	55	* the situation is similar - we add read-ahead requests into the pipeline,
	56	* before the user even requested them.
	57	*
	58	* The pipeline can be viewed as a "safety net" which will be activated when
	59	* the system load is high and prevents the user backup program from keeping up
	60	* with the current tape speed. At this point, the pipeline will get
	61	* shorter and shorter but the tape will still be streaming at the same speed.
	62	* Assuming we have enough pipeline stages, the system load will hopefully
	63	* decrease before the pipeline is completely empty, and the backup program
	64	* will be able to "catch up" and refill the pipeline again.
	65	*
	66	* When using the pipelined mode, it would be best to disable any type of
	67	* buffering done by the user program, as ide-tape already provides all the
	68	* benefits in the kernel, where it can be done in a more efficient way.
	69	* As we will usually not block the user program on a request, the most
	70	* efficient user code will then be a simple read-write-read-... cycle.
	71	* Any additional logic will usually just slow down the backup process.
	72	*
	73	* Using the pipelined mode, I get a constant over 400 KBps throughput,
	74	* which seems to be the maximum throughput supported by my tape.
	75	*
	76	* However, there are some downfalls:
	77	*
	78	* 1. We use memory (for data buffers) in proportional to the number
	79	* of pipeline stages (each stage is about 26 KB with my tape).
	80	* 2. In the pipelined write mode, we cheat and postpone error codes
	81	* to the user task. In read mode, the actual tape position
	82	* will be a bit further than the last requested block.
	83	*
	84	* Concerning (1):
	85	*
	86	* 1. We allocate stages dynamically only when we need them. When
	87	* we don't need them, we don't consume additional memory. In
	88	* case we can't allocate stages, we just manage without them
	89	* (at the expense of decreased throughput) so when Linux is
	90	* tight in memory, we will not pose additional difficulties.
	91	*
	92	* 2. The maximum number of stages (which is, in fact, the maximum
	93	* amount of memory) which we allocate is limited by the compile
	94	* time parameter IDETAPE_MAX_PIPELINE_STAGES.
	95	*
	96	* 3. The maximum number of stages is a controlled parameter - We
	97	* don't start from the user defined maximum number of stages
	98	* but from the lower IDETAPE_MIN_PIPELINE_STAGES (again, we
	99	* will not even allocate this amount of stages if the user
	100	* program can't handle the speed). We then implement a feedback
	101	* loop which checks if the pipeline is empty, and if it is, we
	102	* increase the maximum number of stages as necessary until we
	103	* reach the optimum value which just manages to keep the tape
	104	* busy with minimum allocated memory or until we reach
	105	* IDETAPE_MAX_PIPELINE_STAGES.
	106	*
	107	* Concerning (2):
	108	*
	109	* In pipelined write mode, ide-tape can not return accurate error codes
	110	* to the user program since we usually just add the request to the
	111	* pipeline without waiting for it to be serviced. In case an error
	112	* occurs, I will report it on the next user request.
	113	*
	114	* In the pipelined read mode, subsequent read requests or forward
	115	* filemark spacing will perform correctly, as we preserve all blocks
	116	* and filemarks which we encountered during our excess read-ahead.
	117	*
	118	* For accurate tape positioning and error reporting, disabling
	119	* pipelined mode might be the best option.
	120	*
	121	* You can enable/disable/tune the pipelined operation mode by adjusting
	122	* the compile time parameters below.
	123	*
	124	*
	125	* Possible improvements.
	126	*
	127	* 1. Support for the ATAPI overlap protocol.
	128	*
	129	* In order to maximize bus throughput, we currently use the DSC
	130	* overlap method which enables ide.c to service requests from the
	131	* other device while the tape is busy executing a command. The
	132	* DSC overlap method involves polling the tape's status register
	133	* for the DSC bit, and servicing the other device while the tape
	134	* isn't ready.
	135	*
	136	* In the current QIC development standard (December 1995),
	137	* it is recommended that new tape drives will in addition
	138	* implement the ATAPI overlap protocol, which is used for the
	139	* same purpose - efficient use of the IDE bus, but is interrupt
	140	* driven and thus has much less CPU overhead.
	141	*
	142	* ATAPI overlap is likely to be supported in most new ATAPI
	143	* devices, including new ATAPI cdroms, and thus provides us
	144	* a method by which we can achieve higher throughput when
	145	* sharing a (fast) ATA-2 disk with any (slow) new ATAPI device.
	146	*/