1 files changed, 307 insertions, 0 deletions

diff --git a/Documentation/ftape.txt b/Documentation/ftape.txt
new file mode 100644
index 000000000000..7d8bb3384031
--- /dev/null
+++ b/Documentation/ftape.txt
@@ -0,0 +1,307 @@
+Intro
+=====
+
+This file describes some issues involved when using the "ftape"
+floppy tape device driver that comes with the Linux kernel.
+
+ftape has a home page at
+
+http://ftape.dot-heine.de/
+
+which contains further information about ftape. Please cross check
+this WWW address against the address given (if any) in the MAINTAINERS
+file located in the top level directory of the Linux kernel source
+tree.
+
+NOTE: This is an unmaintained set of drivers, and it is not guaranteed to work.
+If you are interested in taking over maintenance, contact Claus-Justus Heine
+<ch@dot-heine.de>, the former maintainer.
+
+Contents
+========
+
+A minus 1: Ftape documentation
+
+A. Changes
+   1. Goal
+   2. I/O Block Size
+   3. Write Access when not at EOD (End Of Data) or BOT (Begin Of Tape)
+   4. Formatting
+   5. Interchanging cartridges with other operating systems
+
+B. Debugging Output
+   1. Introduction
+   2. Tuning the debugging output
+
+C. Boot and load time configuration
+   1. Setting boot time parameters
+   2. Module load time parameters
+   3. Ftape boot- and load time options
+   4. Example kernel parameter setting
+   5. Example module parameter setting
+
+D. Support and contacts
+
+*******************************************************************************
+
+A minus 1. Ftape documentation
+==============================
+
+Unluckily, the ftape-HOWTO is out of date. This really needs to be
+changed. Up to date documentation as well as recent development
+versions of ftape and useful links to related topics can be found at
+the ftape home page at
+
+http://ftape.dot-heine.de/
+
+*******************************************************************************
+
+A. Changes
+==========
+
+1. Goal
+   ~~~~
+   The goal of all that incompatibilities was to give ftape an interface
+   that resembles the interface provided by SCSI tape drives as close
+   as possible. Thus any Unix backup program that is known to work
+   with SCSI tape drives should also work.
+
+   The concept of a fixed block size for read/write transfers is
+   rather unrelated to this SCSI tape compatibility at the file system
+   interface level. It developed out of a feature of zftape, a
+   block wise user transparent on-the-fly compression. That compression
+   support will not be dropped in future releases for compatibility
+   reasons with previous releases of zftape.
+
+2. I/O Block Size
+   ~~~~~~~~~~~~~~
+   The block size defaults to 10k which is the default block size of
+   GNU tar.
+
+   The block size can be tuned either during kernel configuration or
+   at runtime with the MTIOCTOP ioctl using the MTSETBLK operation
+   (i.e. do "mt -f /dev/qft0" setblk #BLKSZ). A block size of 0
+   switches to variable block size mode i.e. "mt setblk 0" switches
+   off the block size restriction. However, this disables zftape's
+   built in on-the-fly compression which doesn't work with variable
+   block size mode.
+
+   The BLKSZ parameter must be given as a byte count and must be a
+   multiple of 32k or 0, i.e. use "mt setblk 32768" to switch to a
+   block size of 32k.
+
+   The typical symptom of a block size mismatch is an "invalid
+   argument" error message.
+
+3. Write Access when not at EOD (End Of Data) or BOT (Begin Of Tape)
+   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+   zftape (the file system interface of ftape-3.x) denies write access
+   to the tape cartridge when it isn't positioned either at BOT or
+   EOD.
+
+4. Formatting
+   ~~~~~~~~~~
+   ftape DOES support formatting of floppy tape cartridges. You need the
+   `ftformat' program that is shipped with the modules version of ftape.
+   Please get the latest version of ftape from
+
+   ftp://sunsite.unc.edu/pub/Linux/kernel/tapes
+
+   or from the ftape home page at
+
+   http://ftape.dot-heine.de/
+
+   `ftformat' is contained in the `./contrib/' subdirectory of that
+   separate ftape package.
+
+5. Interchanging cartridges with other operating systems
+   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+   The internal emulation of Unix tape device file marks has changed
+   completely. ftape now uses the volume table segment as specified
+   by the QIC-40/80/3010/3020/113 standards to emulate file marks. As
+   a consequence there is limited support to interchange cartridges
+   with other operating systems.
+
+   To be more precise: ftape will detect volumes written by other OS's
+   programs and other OS's programs will detect volumes written by
+   ftape.
+
+   However, it isn't possible to extract the data dumped to the tape
+   by some MSDOS program with ftape. This exceeds the scope of a
+   kernel device driver. If you need such functionality, then go ahead
+   and write a user space utility that is able to do that. ftape already
+   provides all kernel level support necessary to do that.
+
+*******************************************************************************
+
+B. Debugging Output
+   ================
+
+1. Introduction
+   ~~~~~~~~~~~~
+   The ftape driver can be very noisy in that is can print lots of
+   debugging messages to the kernel log files and the system console.
+   While this is useful for debugging it might be annoying during
+   normal use and enlarges the size of the driver by several kilobytes.
+
+   To reduce the size of the driver you can trim the maximal amount of
+   debugging information available during kernel configuration. Please
+   refer to the kernel configuration script and its on-line help
+   functionality.
+
+   The amount of debugging output maps to the "tracing" boot time
+   option and the "ft_tracing" modules option as follows:
+
+   0              bugs
+   1              + errors (with call-stack dump)
+   2              + warnings
+   3              + information
+   4              + more information
+   5              + program flow
+   6              + fdc/dma info
+   7              + data flow
+   8              + everything else
+
+2. Tuning the debugging output
+   ~~~~~~~~~~~~~~~~~~~~~~~~~~~
+   To reduce the amount of debugging output printed to the system
+   console you can
+
+   i)  trim the debugging output at run-time with
+
+       mt -f /dev/nqft0 setdensity #DBGLVL
+
+       where "#DBGLVL" is a number between 0 and 9
+
+   ii) trim the debugging output at module load time with
+
+       modprobe ftape ft_tracing=#DBGLVL
+
+       Of course, this applies only if you have configured ftape to be
+       compiled as a module.
+
+   iii) trim the debugging output during system boot time. Add the
+       following to the kernel command line:
+
+       ftape=#DBGLVL,tracing
+
+       Please refer also to the next section if you don't know how to
+       set boot time parameters.
+
+*******************************************************************************
+
+C. Boot and load time configuration
+   ================================
+
+1. Setting boot time parameters
+   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
+   Assuming that you use lilo, the LI)nux LO)ader, boot time kernel
+   parameters can be set by adding a line
+
+   append some_kernel_boot_time_parameter
+
+   to `/etc/lilo.conf' or at real boot time by typing in the options
+   at the prompt provided by LILO. I can't give you advice on how to
+   specify those parameters with other loaders as I don't use them.
+
+   For ftape, each "some_kernel_boot_time_parameter" looks like
+   "ftape=value,option". As an example, the debugging output can be
+   increased with
+
+   ftape=4,tracing
+
+   NOTE: the value precedes the option name.
+
+2. Module load time parameters
+   ~~~~~~~~~~~~~~~~~~~~~~~~~~~
+   Module parameters can be specified either directly when invoking
+   the program 'modprobe' at the shell prompt:
+
+   modprobe ftape ft_tracing=4
+
+   or by editing the file `/etc/modprobe.conf' in which case they take
+   effect each time when the module is loaded with `modprobe' (please
+   refer to the respective manual pages). Thus, you should add a line
+
+   options ftape ft_tracing=4
+
+   to `/etc/modprobe.conf` if you intend to increase the debugging
+   output of the driver.
+
+
+3. Ftape boot- and load time options
+   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+   i.   Controlling the amount of debugging output
+        DBGLVL has to be replaced by a number between 0 and 8.
+
+        module                 |  kernel command line
+        -----------------------|----------------------
+        ft_tracing=DBGLVL      |  ftape=DBGLVL,tracing
+
+   ii.  Hardware setup
+        BASE is the base address of your floppy disk controller,
+        IRQ and DMA give its interrupt and DMA channel, respectively.
+        BOOL is an integer, "0" means "no"; any other value means
+        "yes". You don't need to specify anything if connecting your tape
+        drive to the standard floppy disk controller. All of these
+        values have reasonable defaults. The defaults can be modified
+        during kernel configuration, i.e. while running "make config",
+        "make menuconfig" or "make xconfig" in the top level directory
+        of the Linux kernel source tree. Please refer also to the on
+        line documentation provided during that kernel configuration
+        process.
+
+        ft_probe_fc10 is set to a non-zero value if you wish for ftape to
+        probe for a Colorado FC-10 or FC-20 controller.
+
+        ft_mach2 is set to a non-zero value if you wish for ftape to probe
+        for a Mountain MACH-2 controller.
+
+        module                 |  kernel command line
+        -----------------------|----------------------
+        ft_fdc_base=BASE       |  ftape=BASE,ioport
+        ft_fdc_irq=IRQ         |  ftape=IRQ,irq
+        ft_fdc_dma=DMA         |  ftape=DMA,dma
+        ft_probe_fc10=BOOL     |  ftape=BOOL,fc10
+        ft_mach2=BOOL          |  ftape=BOOL,mach2
+        ft_fdc_threshold=THR   |  ftape=THR,threshold
+        ft_fdc_rate_limit=RATE |  ftape=RATE,datarate
+
+4. Example kernel parameter setting
+   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
+   To configure ftape to probe for a Colorado FC-10/FC-20 controller
+   and to increase the amount of debugging output a little bit, add
+   the following line to `/etc/lilo.conf':
+
+   append ftape=1,fc10 ftape=4,tracing
+
+5. Example module parameter setting
+   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+   To do the same, but with ftape compiled as a loadable kernel
+   module, add the following line to `/etc/modprobe.conf':
+
+   options ftape ft_probe_fc10=1 ft_tracing=4
+
+*******************************************************************************
+
+D. Support and contacts
+   ====================
+
+   Ftape is distributed under the GNU General Public License. There is
+   absolutely no warranty for this software. However, you can reach
+   the current maintainer of the ftape package under the email address
+   given in the MAINTAINERS file which is located in the top level
+   directory of the Linux kernel source tree. There you'll find also
+   the relevant mailing list to use as a discussion forum and the web
+   page to query for the most recent documentation, related work and
+   development versions of ftape.
+
+   Changelog:
+   ==========
+
+~1996:          Original Document
+
+10-24-2004:     General cleanup and updating, noting additional module options.
+                James Nelson <james4765@gmail.com>