Documentation/ftape.txt - kernel/msm - Gitiles

 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>
	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>