Merge master.kernel.org:/home/rmk/linux-2.6-arm
[linux-2.6] / 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>