Documentation/ftape.txt

   1 Intro
   2 =====
   3
   4 This file describes some issues involved when using the "ftape"
   5 floppy tape device driver that comes with the Linux kernel.
   6
   7 ftape has a home page at
   8
   9 http://ftape.dot-heine.de/
  10
  11 which contains further information about ftape. Please cross check
  12 this WWW address against the address given (if any) in the MAINTAINERS
  13 file located in the top level directory of the Linux kernel source
  14 tree.
  15
  16 NOTE: This is an unmaintained set of drivers, and it is not guaranteed to work.
  17 If you are interested in taking over maintenance, contact Claus-Justus Heine
  18 <ch@dot-heine.de>, the former maintainer.
  19
  20 Contents
  21 ========
  22
  23 A minus 1: Ftape documentation
  24
  25 A. Changes
  26    1. Goal
  27    2. I/O Block Size
  28    3. Write Access when not at EOD (End Of Data) or BOT (Begin Of Tape)
  29    4. Formatting
  30    5. Interchanging cartridges with other operating systems
  31
  32 B. Debugging Output
  33    1. Introduction
  34    2. Tuning the debugging output
  35
  36 C. Boot and load time configuration
  37    1. Setting boot time parameters
  38    2. Module load time parameters
  39    3. Ftape boot- and load time options
  40    4. Example kernel parameter setting
  41    5. Example module parameter setting
  42
  43 D. Support and contacts
  44
  45 *******************************************************************************
  46
  47 A minus 1. Ftape documentation
  48 ==============================
  49
  50 Unluckily, the ftape-HOWTO is out of date. This really needs to be
  51 changed. Up to date documentation as well as recent development
  52 versions of ftape and useful links to related topics can be found at
  53 the ftape home page at
  54
  55 http://ftape.dot-heine.de/
  56
  57 *******************************************************************************
  58
  59 A. Changes
  60 ==========
  61
  62 1. Goal
  63    ~~~~
  64    The goal of all that incompatibilities was to give ftape an interface
  65    that resembles the interface provided by SCSI tape drives as close
  66    as possible. Thus any Unix backup program that is known to work
  67    with SCSI tape drives should also work.
  68
  69    The concept of a fixed block size for read/write transfers is
  70    rather unrelated to this SCSI tape compatibility at the file system
  71    interface level. It developed out of a feature of zftape, a
  72    block wise user transparent on-the-fly compression. That compression
  73    support will not be dropped in future releases for compatibility
  74    reasons with previous releases of zftape.
  75
  76 2. I/O Block Size
  77    ~~~~~~~~~~~~~~
  78    The block size defaults to 10k which is the default block size of
  79    GNU tar.
  80
  81    The block size can be tuned either during kernel configuration or
  82    at runtime with the MTIOCTOP ioctl using the MTSETBLK operation
  83    (i.e. do "mt -f /dev/qft0" setblk #BLKSZ). A block size of 0
  84    switches to variable block size mode i.e. "mt setblk 0" switches
  85    off the block size restriction. However, this disables zftape's
  86    built in on-the-fly compression which doesn't work with variable
  87    block size mode.
  88
  89    The BLKSZ parameter must be given as a byte count and must be a
  90    multiple of 32k or 0, i.e. use "mt setblk 32768" to switch to a
  91    block size of 32k.
  92
  93    The typical symptom of a block size mismatch is an "invalid
  94    argument" error message.
  95
  96 3. Write Access when not at EOD (End Of Data) or BOT (Begin Of Tape)
  97    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  98    zftape (the file system interface of ftape-3.x) denies write access
  99    to the tape cartridge when it isn't positioned either at BOT or
 100    EOD.
 101
 102 4. Formatting
 103    ~~~~~~~~~~
 104    ftape DOES support formatting of floppy tape cartridges. You need the
 105    `ftformat' program that is shipped with the modules version of ftape.
 106    Please get the latest version of ftape from
 107
 108    ftp://sunsite.unc.edu/pub/Linux/kernel/tapes
 109
 110    or from the ftape home page at
 111
 112    http://ftape.dot-heine.de/
 113
 114    `ftformat' is contained in the `./contrib/' subdirectory of that
 115    separate ftape package.
 116
 117 5. Interchanging cartridges with other operating systems
 118    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 119
 120    The internal emulation of Unix tape device file marks has changed
 121    completely. ftape now uses the volume table segment as specified
 122    by the QIC-40/80/3010/3020/113 standards to emulate file marks. As
 123    a consequence there is limited support to interchange cartridges
 124    with other operating systems.
 125
 126    To be more precise: ftape will detect volumes written by other OS's
 127    programs and other OS's programs will detect volumes written by
 128    ftape.
 129
 130    However, it isn't possible to extract the data dumped to the tape
 131    by some MSDOS program with ftape. This exceeds the scope of a
 132    kernel device driver. If you need such functionality, then go ahead
 133    and write a user space utility that is able to do that. ftape already
 134    provides all kernel level support necessary to do that.
 135
 136 *******************************************************************************
 137
 138 B. Debugging Output
 139    ================
 140
 141 1. Introduction
 142    ~~~~~~~~~~~~
 143    The ftape driver can be very noisy in that is can print lots of
 144    debugging messages to the kernel log files and the system console.
 145    While this is useful for debugging it might be annoying during
 146    normal use and enlarges the size of the driver by several kilobytes.
 147
 148    To reduce the size of the driver you can trim the maximal amount of
 149    debugging information available during kernel configuration. Please
 150    refer to the kernel configuration script and its on-line help
 151    functionality.
 152
 153    The amount of debugging output maps to the "tracing" boot time
 154    option and the "ft_tracing" modules option as follows:
 155
 156    0              bugs
 157    1              + errors (with call-stack dump)
 158    2              + warnings
 159    3              + information
 160    4              + more information
 161    5              + program flow
 162    6              + fdc/dma info
 163    7              + data flow
 164    8              + everything else
 165
 166 2. Tuning the debugging output
 167    ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 168    To reduce the amount of debugging output printed to the system
 169    console you can
 170
 171    i)  trim the debugging output at run-time with
 172
 173        mt -f /dev/nqft0 setdensity #DBGLVL
 174
 175        where "#DBGLVL" is a number between 0 and 9
 176
 177    ii) trim the debugging output at module load time with
 178
 179        modprobe ftape ft_tracing=#DBGLVL
 180
 181        Of course, this applies only if you have configured ftape to be
 182        compiled as a module.
 183
 184    iii) trim the debugging output during system boot time. Add the
 185        following to the kernel command line:
 186
 187        ftape=#DBGLVL,tracing
 188
 189        Please refer also to the next section if you don't know how to
 190        set boot time parameters.
 191
 192 *******************************************************************************
 193
 194 C. Boot and load time configuration
 195    ================================
 196
 197 1. Setting boot time parameters
 198    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 199    Assuming that you use lilo, the LI)nux LO)ader, boot time kernel
 200    parameters can be set by adding a line
 201
 202    append some_kernel_boot_time_parameter
 203
 204    to `/etc/lilo.conf' or at real boot time by typing in the options
 205    at the prompt provided by LILO. I can't give you advice on how to
 206    specify those parameters with other loaders as I don't use them.
 207
 208    For ftape, each "some_kernel_boot_time_parameter" looks like
 209    "ftape=value,option". As an example, the debugging output can be
 210    increased with
 211
 212    ftape=4,tracing
 213
 214    NOTE: the value precedes the option name.
 215
 216 2. Module load time parameters
 217    ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 218    Module parameters can be specified either directly when invoking
 219    the program 'modprobe' at the shell prompt:
 220
 221    modprobe ftape ft_tracing=4
 222
 223    or by editing the file `/etc/modprobe.conf' in which case they take
 224    effect each time when the module is loaded with `modprobe' (please
 225    refer to the respective manual pages). Thus, you should add a line
 226
 227    options ftape ft_tracing=4
 228
 229    to `/etc/modprobe.conf` if you intend to increase the debugging
 230    output of the driver.
 231
 232
 233 3. Ftape boot- and load time options
 234    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 235
 236    i.   Controlling the amount of debugging output
 237         DBGLVL has to be replaced by a number between 0 and 8.
 238
 239         module                 |  kernel command line
 240         -----------------------|----------------------
 241         ft_tracing=DBGLVL      |  ftape=DBGLVL,tracing
 242
 243    ii.  Hardware setup
 244         BASE is the base address of your floppy disk controller,
 245         IRQ and DMA give its interrupt and DMA channel, respectively.
 246         BOOL is an integer, "0" means "no"; any other value means
 247         "yes". You don't need to specify anything if connecting your tape
 248         drive to the standard floppy disk controller. All of these
 249         values have reasonable defaults. The defaults can be modified
 250         during kernel configuration, i.e. while running "make config",
 251         "make menuconfig" or "make xconfig" in the top level directory
 252         of the Linux kernel source tree. Please refer also to the on
 253         line documentation provided during that kernel configuration
 254         process.
 255
 256         ft_probe_fc10 is set to a non-zero value if you wish for ftape to
 257         probe for a Colorado FC-10 or FC-20 controller.
 258
 259         ft_mach2 is set to a non-zero value if you wish for ftape to probe
 260         for a Mountain MACH-2 controller.
 261
 262         module                 |  kernel command line
 263         -----------------------|----------------------
 264         ft_fdc_base=BASE       |  ftape=BASE,ioport
 265         ft_fdc_irq=IRQ         |  ftape=IRQ,irq
 266         ft_fdc_dma=DMA         |  ftape=DMA,dma
 267         ft_probe_fc10=BOOL     |  ftape=BOOL,fc10
 268         ft_mach2=BOOL          |  ftape=BOOL,mach2
 269         ft_fdc_threshold=THR   |  ftape=THR,threshold
 270         ft_fdc_rate_limit=RATE |  ftape=RATE,datarate
 271
 272 4. Example kernel parameter setting
 273    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 274    To configure ftape to probe for a Colorado FC-10/FC-20 controller
 275    and to increase the amount of debugging output a little bit, add
 276    the following line to `/etc/lilo.conf':
 277
 278    append ftape=1,fc10 ftape=4,tracing
 279
 280 5. Example module parameter setting
 281    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 282    To do the same, but with ftape compiled as a loadable kernel
 283    module, add the following line to `/etc/modprobe.conf':
 284
 285    options ftape ft_probe_fc10=1 ft_tracing=4
 286
 287 *******************************************************************************
 288
 289 D. Support and contacts
 290    ====================
 291
 292    Ftape is distributed under the GNU General Public License. There is
 293    absolutely no warranty for this software. However, you can reach
 294    the current maintainer of the ftape package under the email address
 295    given in the MAINTAINERS file which is located in the top level
 296    directory of the Linux kernel source tree. There you'll find also
 297    the relevant mailing list to use as a discussion forum and the web
 298    page to query for the most recent documentation, related work and
 299    development versions of ftape.
 300
 301    Changelog:
 302    ==========
 303
 304 ~1996:          Original Document
 305
 306 10-24-2004:     General cleanup and updating, noting additional module options.
 307                 James Nelson <james4765@gmail.com>