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