Subject: Linux Ftape HOWTO
From: [email-masked] (Linux ftape-HOWTO maintainer)
Newsgroups: comp.os.linux.announce,comp.os.linux.help

Archive-name: linux/howto/ftape

This is the `Frequently Asked Questions' (FAQ) / HOWTO document for the ftape
driver (ftape-HOWTO), Copyright (C) 1993,1994 Kai Harrekilde-Petersen.

Copyright statement:
  You may distribute this document freely *as a whole* in any form and of
charge.  You may distribute parts of this document, provided this copyright
message is included and you include a message stating that it is not the full
HOWTO document and a pointer to where the full document can be obtained.
Specifically, it may be included in commercial distributions, without my prior
consent.  However, I would like to be informed of such usage.
  You may translate this HOWTO into any language, whatsoever, provided that
you leave this copyright statement and the disclaimer intact, and that you
append a notice stating who translated the document.

DISCLAIMER:
  While I have tried to include the most correct and up-to-date information
available to me, I cannot guarantee that usage of the information in this
document does not result in loss of data.  I provide NO WARRANTY about the
information in the HOWTO and I cannot be made liable for any consequences for
any damage resulting from using information in this HOWTO.

Please read this document *to the very end*, before you post a question to a
newgroup / Linux-TAPE channel / the maintainer.  This will take off the peak
of questions, and releases us all to more constructive work (like improving
the ftape driver :-)

This HOWTO is written and maintained by: Kai Harrekilde-Petersen
Last update: February 17, 1994 11:50, for ftape 0.9.9d

Email's concerning the HOWTO should be directed to: <[email-masked]> 
========================================================================
CONTENTS

Section 1: The preliminaries
----------------------------
Q1.1	What's the newest version of ftape - and where can I get it?
Q1.2	Where can I follow the development?
Q1.3	Which drives are supported?
Q1.4	Which drives are *NOT* supported?
Q1.5	How do I install it?
Q1.6	Where can I get the kernel sources?
Q1.7	Can I format my tapes under Linux?
Q1.8	Which formatting programs can I use under DOS?

Section 2: Backing up and restoring data and other FAQ's
--------------------------------------------------------
Q2.1	How do I write backups to the tape?
Q2.2	... and how do I read them back?
Q2.3	I want to check the archive I've made ... how?
Q2.4	How can I put more than one tar file on a tape?
Q2.5	Can I append files to an archive?
Q2.6	How do I mount/unmount a tape?
Q2.7	Can I exchange tapes with someone using DOS?
Q2.8	How do I `....' with tar?

Section 3: Frequently Asked Questions
-------------------------------------
Q3.1	ftape DMA transfers gives ECC errors
Q3.2	Insmod says the kernel version is wrong

Section 4: Debugging the ftape driver
-------------------------------------
Q4.1	ftape crashes on me when I do  `...' - is that a bug?
Q4.2	ftape keep saying `... new tape', what do I do?
Q4.3	OK, it's a bug^H^H^H feature - How do I submit a report?
Q4.4	How do I change the trace-level?
Q4.5	When I use /dev/nftape, I get garbage ... why?

Section 5: Supporting the development of ftape
----------------------------------------------
Q5.1	I just *LOVE* this ftape driver, how can I support the developers?
Q5.2	I wanna help developing a `....' Who should I contact?
========================================================================

Section 1: The preliminaries
============================

Q1.1	What's the newest version of ftape - and where can I get it?
--------------------------------------------------------------------
  The newest version of the ftape driver is ftape-0.9.9d, and can be fetched
from the following sites:

    tsx-11.mit.edu [18.172.1.2]: /pub/linux/ALPHA/QIC-80/
    sunsite.unc.edu [152.2.22.81]: /pub/Linux/kernel/tapes/
    ftp.funet.fi [128.214.248.6]: /pub/OS/Linux/BETA/QIC-80/

  You should get the files: ftape-0.9.9d.tar.gz, ftape-0.9.9d.lsm and
modutils-0.99.15.tar.gz.  The tar.gz file is the ftape driver proper, while
the .lsm file is a Linux Software Map (LSM) file (for the LSM project), and
the modutils file is a set of utilities for manipulating loadable drivers
(inserting and removing).  (Note: if you already have the modules utilities,
you do not need to upgrade them).

Q1.2	How can I follow the development?
-----------------------------------------
  If you want to follow the development of the ftape driver, you should
consider subscribing to the TAPE channel on Linux-activists.  To subscribe,
you send a mail to <[email-masked]>, with the *FIRST
LINE* (or as a part of the header) saying `X-Mn-Admin: join TAPE'.  If you
send an empty mail (or the automagical mail-response system chokes on your
mail), you are sent a HOWTO mail.
  To submit a real mail to the mailing lists, send a mail to
<[email-masked]>, and remember that the first line (or a
header line) should read `X-Mn-Key: TAPE'.

Q1.3	Which drives are supported?
-----------------------------------
  All drives that are both QIC-117 compatible *AND* either QIC-40 or QIC-80
compatible should work.  Currently, the list of drives that's *positively*
known to work with ftape is:

	* Colorado DJ-10 / DJ-20 (aka: Jumbo 120 / Jumbo 250)
	* Archive 5580i / XL9250i
	* Insight 80Mb
	* Conner C250MQ
	* Wangtek 3080F
	* Iomega 250
	* Escom / Archive (Hornet) 31250Q
	* Summit SE 150 / SE 250
	* Mountain FS8000

NOTE: If you have a drive that works fine, but it is not listed here, please
send a mail to the HOWTO maintainer ([email-masked]). 

Q1.4	Which drives are *NOT* supported?
-----------------------------------------
	* All drives that connect to the parallel port (eg: Colorado Trakker) 
	* High-Speed controller's. (eg: Colorado FC-10 & FC-15)
	* Irwin AX250L / Accutrak 250. (not a QIC-80 drive)
	* IBM Internal Tape Backup Unit (identical to the Irwin AX250L drive)
	* COREtape light

  Generally, *ALL* drives that connect to the parallel port are *NOT*
supported.  This is because these drives uses (different) proprietary
interfaces, that are very much different from the QIC-117 standard.
  The Colorado FJ-10 High-Speed controller (and the likes) are not supported
directly by the ftape driver.  However, there exists some patches for the
FJ-10 specifically, which makes ftape work with it.
  IRWIN AX250L (and the IBM Internal Tape Backup Unit) does not work the
ftape.  This is because they only support QIC-117, but not the QIC-80
standard (they use Irwin's proprietary servoe (Rhomat) format).
  The COREtape light does not work (yet).  We have some info on it, but we
have not got it accepting the initialisation data.

Q1.5	How do I install it?
----------------------------
  There is included an installation guide (the file INSTALL) in the ftape
distribution; Read that.

Q1.6	Where can I get the kernel sources?
-------------------------------------------
  You can get the kernel sources from the same place as you got the ftape
sources.  The sources are kept at the following sites (and many mirror-sites)

    tsx-11.mit.edu [18.172.1.2]: /pub/linux/sources/system/
    sunsite.unc.edu [152.2.22.81]: /pub/Linux/kernel/
    ftp.funet.fi [128.214.248.6]: /pub/OS/Linux/PEOPLE/Linus/

funet carries the so-called ALPHA versions too.  These are typically more
advanced than the `standard' versions, but can be less stable.  New versions
may be introduced to fix a bug within days, but they may also introduce new
bugs.

Q1.7	Can I format my tapes under Linux?
------------------------------------------
  At the moment, no!  We have not had the time to develop a formatting utility
for Linux.  Instead you'll have to use MS-D*S (arghhh!) instead or buy
preformatted tapes.  However, some of the preformatted tapes are *not* checked
for bad sectors!.  If the ftape driver enocunters a tape with no bad blocks,
it will issue a warning.

Q1.8	Which formatting programs can I use under DOS? 
------------------------------------------------------
These are known to work:
	* Colorado Memory System's software (tape.exe)
	* Norton Backup
	* QICstream version 2

These programs are known to be more or less buggy:

	* CONNOR's Dos software (Windoze version is fine!)
	* CP Backup (wastes tape space, but is OK apart from that)

  In fact, most software under DOS should work.  CONNOR's program (the dos
version) has a parameter off-by-one (someone could not read the QIC-80 specs
right!), while their Windoze version works fine.  Central Point Backup can be
used, but it wastes precious tape spaces when it encounters a bad spot on the
tape.

NOTE: If you are running a formatting software under DOS, which is not
mentioned here, please mail the maintainer ([email-masked]) the relevant
info, so we can update the HOWTO.

Section 2: Backing up and restoring data
========================================

Q2.1	How do I write backups to the tape?
-------------------------------------------
  You can use `tar', `dd' and `cpio'.  For a start I'd recommend `tar', as it
can archive lots of directories and let you pick out seperate files from an
archive.  To make a backup of your kernel source tree, do this (assuming you
have the source in /usr/src/linux):

	cd /usr/src
	tar cf /dev/ftape linux

  This wont compress the files, but gives you a smoother tape run.  If you
want the compression (and you've got tar 1.11.2), you just include the -z
flag(*), eg: `tar czf /dev/ftape linux'

  For further instructions on how to use tar, dd and look at the man pages and
the texinfo files that comes with the respective distributions.

(*) tar assumes that the first argument is options, so the `-' is not
necessary, i.e. these two commands are the same: `tar xzf /dev/ftape' and `tar
-xzf /dev/ftape'

Q2.2	... and how do I read them back?
----------------------------------------
  OK, let us restore the backup of the kernel source you made in Q2.1 To do
this you simply say 

	tar xf /dev/ftape

If you used compression, you will have to say

	tar xzf /dev/ftape

When you use compression, gzip will complain about trailing garbage after the
very end of the archive (and this will lead to a `broken pipe' message).  This
can be safely ignored.

For the other utilities, please read the man page.

Q2.3	I want to check the archive I've made ... how?
------------------------------------------------------
  tar has an option (-d) for detecting differences between two archives. To
test your backup of the kernel source say

	tar df /dev/ftape

If you do not have the man page for tar, you are not lost (yet).  tar has a
builtin option list: try `tar --help 2>&1 | more'

Q2.4	How can I put more than one tar file on a tape?
-------------------------------------------------------
  "If I understand, tar -cf /dev/ftape stuff will only allow one tar file /
tape.  Does the trick of using `dd' via a pipe allow more than one file?"

  By using the nftape device (nope, it does not work yet), you should be able
to use `mt' to position the tape the correct place.  (`mt /dev/nftape fsf 2'
means go to tar file number 2)

  "I hate to say, but it appears (could be wrong) that the CMS software has
more capability than tar -- at least it can put two archives on one tape."

  Basically, yes. However, it depends on how you look at it: tar generates a
single Tape ARchive (that's why it is called `tar').  If you want more than
one backup on a single tape, you must use tar in conjunction with another
tool, eg: `mt'.
  There exists a `QIC-80 logical format', which is what the CMS software
conforms to.  I am going to look at it when I am done with my thesis (ie: i
will start working on the QIC-80 logical format in march '94 at the earliest)
  Truly, that is the way it goes, when you start using something that is still
in it's infancy :-/

Q2.5	Can I append files to an archive?
--------------------------------------------
  "Is there a way to extend an archive -- put a file on the tape, then later,
add more to the tape?"

  No. The tar documentation will tell you to use `tar -Ar', but it does not
work.  This is a limitation of the current ftape driver.

Q2.6	How do I mount/unmount a tape?
--------------------------------------
  You do not! -- Since a tape does not have a "filesystem" on it, you do not
mount / unmount the tape.  To backup, you just insert the tape and run your
`tar' command (or whatever you use to access the tape with).

  "Is there an explicit (dis)mount command for the tape?"

Nope.  The ftape device is a `character device', and they can not be
[u]mount'ed.  It is only block devices that gets mounted

Q2.7	Can I exchange tapes with someone using DOS?
----------------------------------------------------
  Nope. This is one of my pet-projects, so maybe in the future (any help is
welcome).

Q2.8	How do I `....' with tar?
---------------------------------
  These are really tar questions: Read the man page and the info page.  If you
have not got it either, DO try `tar --help 2>&1 | more'.

  If your tar is v1.11.1 or earlier, consider upgrading to v1.11.2 - This
version can call GNU zip directly (ie: it supports the -z option) and has an
elaborate help included.  Also, it compiles right out of the box on Linux.

Section 3: Frequently Asked Questions
=====================================

Q3.1	ftape DMA transfers gives ECC errors
--------------------------------------------
  Sadly to say there are some SVGA cards and ethernet cards that do not decode
their addresses correct.  This typically happens when the ftape buffers are in
the range 0x1a0000 to 0x1c0000.  Somehow, the DMA write cycles get clobbered
and every other byte written gets a bad value (0xff).  These problems are
reported to happen with both SVGA and ethernet cards.  We know of at least one
(bad?) ATI 16bit VGA card that caused this.
  The easiest solution is to put the card in an 8bit slot (it is often not
enough to reconfigure the card to 8bit transfers).
  Moving the ftape buffer away from the VGA range is only a partial solution;
All DMA buffers used in Linux can have this problem!

Let us make this one clear: This has nothing to do with the ftape software :-) 

Q3.2	Insmod says the kernel version is wrong
-----------------------------------------------
  The insmod program checks the kernel version against the version recorded in
the ftape driver.  This is a string in kernel-version.h, (char
kernel_version[] = "0.99.14k";) which is extracted from the kernel you are
running when you run `make'.  If you got the error when you tried to insert
the ftape driver, remove the file `kernel-version.h', type `make' again and
the kernel-version.h file should be updated.  Remember that you will have to
do this every time you change to another kernel version.

Section 4: Debugging the ftape driver
=====================================

Q4.1	ftape crashes on me when I do  `...' - is that a bug?
-------------------------------------------------------------
  No, that is a feature ;-)

  Seriously, reliable sofware do not crash.  Especially kernels do not or
rather *should* not crash.  If the kernel crashes upon you when you are
running ftape, and you can prove that it is ftape that is messing things up,
regard it as a Bug that Should Be Fixed.  Mail the details to the developers
(see Q4.3 below).

Q4.2	ftape keep saying `... new tape', what do I do?
-------------------------------------------------------
[You cannot do this anymore; I do not know a way of fixing it yet]
  To get rid of this, do this (blindfold): login as root and say `rmmod
driver'.  ftape should choke a few times, give three segmentation violations
(or so), and give up life.

  Check the activity LED on your floppy drive (you do have one, don't you?).
If it is constantly lit, you have turned the cable upside down somewhere.
Check your cable between controller, tape drive _and_ floppy drive.  Usually,
one (or more) of the cables have been turned upside down, such that pin 1 in
one end connects to pin 34 in the other end.  (All the even-numbered pins are
grounded, so you wont be able to use your floppy either)

Q4.3	OK, it's a bug^H^H^H feature - How do I submit a report?
----------------------------------------------------------------
  First, make sure you can reproduce the problem.  Spurious errors are a pain
in the ass, since they are just about impossible to hunt down.  This is a
quick check list:

	* Kernel version, and patches applied (even ftape patches)
	* ftape version
	* tape drive model / manufacturer
	* What you did to expose the problem
	* A log of the run with tracing level set to 7
	* What went wrong on your system.
	* Do not delete the kernel and driver.o file. We may want you run try
	  some patches out or run a different test on your system.

  Increase the tracing level to 7 (just below maximum tracing) and run the
offending command again.  Get the tracing data from the kernel log or
/proc/kmsg, depending on where you harvest your error messages.  Do not try to
`trim' the kernel log.  You might consider something irrelevant, which is
essential to the investigator of the bug.  State exactly what you did, and
what happened on your system.  We might not see the error because we use a
different tape drive or another version of the kernel!

Q4.4	How do I change the trace-level?
----------------------------------------
  You can do this two ways: either change the default trace-level (the var
`tracing' in file `ftape-rw.c') and recompile or say

	mt /dev/ftape fsf <tracing-level>

The use of the fsf command in mt is a *hack*, and will disappear in time.

Q4.5	When I use /dev/nftape, I get garbage ... why?
------------------------------------------------------
  The non-rewinding /dev/nftape device is not supported yet, but Bas is
working on it at the moment.  You don't *need* to have it, but we have
included it for completeness.
  For now: Do not use it!

Section 5: Supporting the development of ftape
----------------------------------------------

Q5.1	I just *LOVE* this ftape driver, how can I support the developers?
--------------------------------------------------------------------------
  You can support us by answering other users questions on the newsgroups.
There are many new users (newbies), that just need a simple answer to their
question, e.g. `where can I get the ftape-HOWTO'. 

  This is about the best support you can give us besides testing the driver
and writing good error-reports.

Q5.2	I wanna help developing a `....' Who should I contact?
--------------------------------------------------------------
  Below is a list of the developers.  If there is already someone working on a
similar / identical project, contact that person directly.  If you have an
program / feature that no-one is working on, contact me <[email-masked]> (NOT
Bas, he is already over-burdened by work and has little time to reply to
questions)

Formatting program:
  Kai Harrekilde-Petersen, [email-masked] (from March '94)
  Cesare Mastroianni, [email-masked]

ftape driver proper:
  Bas Laarhoven, [email-masked]

ECC code: (do not join in, we are enough already)
  David Mosberger-Tang, [email-masked]
  Ning Mosberger-Tang, [email-masked]
  Kai Harrekilde-Petersen, [email-masked]
  Bas Laarhoven, [email-masked]

ftape-HOWTO:
  Kai Harrekilde-Petersen, [email-masked]

QIC-80 logical format (r/w of DOS compatible backups, starts March '94):
  Kai Harrekilde-Petersen, [email-masked] 

/**************** T H E   E N D   O F   f t a p e - H O W T O ***************/