summaryrefslogtreecommitdiff
path: root/Documentation/ftape.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/ftape.txt')
-rw-r--r--Documentation/ftape.txt307
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>