=====cut-here=============================================================== README.tape-0.7.1.6: INSTRUCTIONS FOR INSTALLATION OF LINUX QIC-02 DRIVER ============================================================================ DATE: ===== 1994-05-28 Contributed for v0.4.1.3 by Jeff Stern. 1994-06-07 Minor edits/changes by Hennus 1996-07-30 changes for Linux 2.0.x VERSION NUMBERS APPLICABLE: =========================== QIC-02 DRIVER: 0.7.1.6 QIC-02 DRIVER SUPPORT PROGRAMS COLLECTION: 1.9b KERNEL: 2.0.x GCC: 2.7.2 Below I'm going to describe how to install only version 0.7.1.6 of QIC-02 tape driver onto a system running Linux version 2.0.x. Further, I'll describe only how to do it with dynamic configuration (for most people, the preferred). There are other ways to do it, for other versions of the driver and of the kernel. This README.tape, however, applies only to the above versions of the driver and kernel.. There may be later versions of the kernel, compiler, libc, or driver, but this README.tape is not intended to apply to them, so beware! If you have a later kernel, for instance, I am sorry to not provide help or pointers on patchfiles, etc. for them: it's just a matter of time available.. I wrote this because I had trouble installing the driver without recent documentation, and thought that others might benefit from having a README.tape~ that would help them through, too. This is just how I got my driver installed, so that's why it's restricted to the version numbers of the software and kernel that I used. FILES NEEDED: ============= [******** THE FOLLOWING URLS ARE OUT OF DATE **********] *sunsite.unc.edu: /pub/Linux/kernel/linux-2.0.x.tar.gz nic.funet.fi: /pub/OS/Linux/BETA/QIC-02/README.tape-0.7.1.6 (this file) nic.funet.fi: /pub/OS/Linux/BETA/QIC-02/release.note-0.7.1.6 *nic.funet.fi: /pub/OS/Linux/BETA/QIC-02/tpqic02-0.7.1.6.diffs.gz *nic.funet.fi: /pub/OS/Linux/BETA/QIC-02/tpqic02-support-1.9b.tar.gz *- retrieved during installation (so they go into correct directories) OVERVIEW: ========= Basically, what you need to know is that there are two sets of files you are going to install. The first set is all the source files for the linux 2.x kernel. And the second set of files is for the support programs, v.1.9b, for the driver. After installing the first, you are going to make a new kernel which will have the new QIC-02 tape driver built in. It would be helpful to know ahead of time what QIC-02 controller card and drive you have, as well as what IRQ, DMA, and port address you'll want to use for your card. It would also be helpful to make sure you have the correct gcc and libc versions installed. WARNING: ======== This code is still BETA -- There *are* bugs in it! Use it at your own risk! INSTRUCTIONS FOR INSTALLATION: ============================== (Twenty-six steps to 'recovery', heheh ;) ...'And, they're off!!!' STEP 1 Print out and skim through this README completely before attempting installation. Also, see the current `release.note-0.7.1.6' file. Do all of the below as 'root', of course. :) STEP 2 Backup your entire system onto floppies. [Seriously ...] STEP 3 Rename your old source tree for your linux kernel, so you have backup source if you need it. In my case, the linux kernel resides in /usr/src/linux. So, when I upgraded from 0.99.15 to 1.1.0, I just did this: cd /usr/src mv linux linux_0.99.15 STEP 4 Now (while still in the /usr/src directory), get the new linux kernel source file by ftp'ing the file sunsite.unc.edu:/pub/Linux/kernel/v1.1.0.tar.gz (remember to do this in binary mode), then gunzip and de-tar it: ftp sunsite.unc.edu (get file) gzip -d v1.1.0.tar.gz tar -xvf v1.1.0.tar Now you should have a clean, new Linux 1.1.0 source tree. STEP 5 Make sure you have the latest gcc (2.7.2) and libc (at least 5.2.18). (You might get away with using an older library and recompiling the support programs yourself, but is not recommended.) By the way, you can get libc from pub/linux/packages/GCC/ on tsx-11.mit.edu. The files should be 'libc-x.y.z.tar.gz' and 'release.libc-x.y.z', for the full installation. I don't know, there may be some other files you need to get there: as always, RTFM, hehe.. The gcc compiler is, I believe in the same directory, under gcc-*.*... STEP 6 [********* THESE URLS ARE OUT OF DATE!! *********** Try http://www.cybercomm.nl/~hennus/ until sunsite.unc.edu has them again. ] If you like to live dangerously and you absolutely must run the very latest revision of the QIC-02 driver, you can try the following to upgrade the standard driver in the linux kernel distribution: To get the latest version of the QIC-02 tape driver, get two of Hennus' files via ftp from nic.funet.fi in the directory /pub/OS/Linux/BETA/QIC-02: tpqic02-0.7.1.6.diffs.gz and tpqic02-support-1.9b.tar.gz The diffs file is the patchfile to change things such as the config.in file in /usr/src/linux and the tpqic02.c and tpqic02.h files, etc. Eventually these patches will be merged into the mainline Linux kernel distribution but before that happens, they have to be tested a bit... The support file contains the latest versions of support programs such as edd, mt, cpio, and buffer. *** If you don't want to play beta-tester, skip to STEP 10 *** STEP 7 Now, you're going to apply the patchfile to some of the files in the Linux source tree. To do this, we first need to unpack the patchfile: gzip -d tpqic02-0.7.1.6.diffs.gz STEP 8 Next we need to copy the file with the patches to the correct source directory, and then move there: cp tpqic02-0.7.1.6.diffs /usr/src cd /usr/src then we need to apply the patch: patch -p0 < tpqic02-0.7.1.6.diffs >& qic.diffs.output STEP 9 Now, look at the 'qic.diffs.output' file you've created, with an editor like emacs or mg or vi to see that all 'hunks' (patches) of the patchfile succeeded. In emacs and mg, for instance, one way to check that they all succeeded is to search for the word 'fail' (Ctrl-S f a i l). If it says 'Failing I-Search' then they all succeeded (that is, it failed to find any word 'fail' in the output), and you can go on to STEP 10. What to do if there are any failures? Well, this is where you have to use your head, because you're kind of on your own. Look *carefully* at the qic.diffs.output file you have made for yourself and check out where the failure was exactly. Figure out what file the patchfile was patching, and where in that file it went wrong.. then you have the option of figuring out what it was trying to change and editting it by hand.. BUT you really shouldn't have to do this, because *if* you have followed the instructions closely, it *should* work for you. It might be better to just erase your linux source tree (rm -rf /usr/src/linux) and reinstall it from the tar file (that is, go back to STEP 4). If you figure out that you are sure you have done *exactly* what we have told you to do and it is *still* not working, then we'd like to hear about it. Be as *specific* as possible in describing the problem and all the steps you did that led up to it, and send us email (our addresses are below). STEP 10 Make a floppy that boots with your OLD (current, not the new) kernel, ON FLOPPY, that boots from floppy. This is in case the new kernel you're about to make doesn't boot up. KEEP THIS IN A SAFE PLACE! STEP 11 Now, make your new kernel. Read /usr/src/linux/README for directions on how to do this, but basically it consists of: cd /usr/src/linux make mrproper make config -when it asks you whether you want dynamic configuration of your QIC-02 drive, type 'y': QIC-02 tape support (CONFIG_QIC02_TAPE) [y] y Do you want runtime configuration for QIC-02 (CONFIG_QIC02_DYNCONF) [y] y * * Setting runtime QIC-02 configuration is done with qic02conf * NOTE: Using the driver with dynamic configuration is a little more `expensive' in runtime than the old `static' way, but it is more convenient: If you want to change a port address, irq, dma or other parameter, you will still have to reboot the computer if you are going to change the actual jumpers on your card, but at least you won't have to recompile the kernel. If you want to use static configuration, on the other hand, then you need to edit /usr/src/linux/include/linux/tpqic02.h for the drive type, IRQ, DMA, etc. settings. There are comments in the tpqic02.h file to help you out with that, and we don't get into it here, since we're just going to assume you're going to use dynamic configuration. -you may possibly have to edit drivers/net/CONFIG and the top Makefile now. I didn't have to. make dep make clean make zImage (have some lunch here) cp /zImage /zImage.old cp zImage / cd /etc/lilo install [You don't have to use Lilo, a `make zdisk' does the job too. --hhb] [Module support is being added, but it hasn't been tested nor documented yet. --hhb] STEP 12 Now reboot, and if you come up okay, then congratulations! STEP 13 Now that you know that your new kernel works, make a floppy that boots with your NEW kernel. KEEP THIS IN A SAFE PLACE! STEP 14 Now, gzip -d and tar -xvf the support file, and change into that directory: gzip -d tpqic02-support-1.9b.tar.gz tar -xvf tpqic02-support-1.9b.tar cd tpqic02-support STEP 15 Now, since the new driver is dynamically configurable, we need to edit a configuration file.. In my case, I have a Mountain QIC-02 card/drive, so I edited 'conf-mountain'. Make sure the DMA, irq, and port variables are all set correctly for your card. Make your best guess about addresses/locations of other cards in your system so that your QIC-02 card doesn't conflict with them by having the same address/locations.. STEP 16 Now there should be a quick and very dirty Makefile in the current (tpqic02-support) directory which I use to install this stuff.. You may not want to install this stuff in global areas yet, in which case skip this step... But if you want to use it you should edit it for your preferences for where stuff should go by editting the USRBIN, BIN, and SBIN variables (although the current values are the recommended ones). If you want to put your conf-* and qic02conf files in some other location than /sbin, then you should also edit the conf-* script you're going to use, because inside your conf- script it refers to /sbin/qic02conf. You'd have to change that to whatever location qic02conf is in.. I recommend just keeping them in /sbin. If you don't have /sbin, this Makefile will make it for you. If you already have one, it will use the one you have. So edit, then run the makefile: emacs Makefile make STEP 17 Copy 'mt' to the root floppy. Don't forget to link them statically if you're not using shared libs on the root floppy! [You'll also want `qic02conf' and the conf-* of your choice on your rootdisk. ;) --hhb] (If you have >=2 floppy drives, you may want to create a `bare bones' recovery disk and simply use the standard root disk to boot from, then mount the recovery floppy on the other floppy drive. Make sure you put a copy of the root/boot disks with tape support in a safe place.) STEP 18 Usually the `tar' program on the standard root disk is actually `pax', which may not fully understand all GNU tar special stuff, like volume labels. Check this before it's too late. Make sure you have a good tar program. Check that it supports symbolic links. GNU tar is useful because it adds Volume headers (-V) and multivolume support, but it may not fit on your root disk. As of the time of this writing, one could ftp this file from: sunsite.unc.edu:/pub/Linux/system/Backup/tar1111B.taz STEP 19 Make the device files [Check tpqic02.h for the minor bits] mknod /dev/rmt0 c 12 4 # QIC-24 mknod /dev/rmt8 c 12 6 # QIC-120 mknod /dev/rmt16 c 12 8 # QIC-150 rm /dev/tape mknod /dev/tape c 12 8 # Or whatever appropriate mknod /dev/tape-d c 12 `expr 128 + 8` # ditto mknod /dev/tape-reset c 12 255 # For resetting only mknod /dev/tape-nodens c 12 0 # Without setting density Make /dev/tape a copy of the device file you prefer as the default device. The names /dev/rmt? are used mainly for historic reasons. (i.e. GNU tar uses them.) NOTE: When using a drive without `set density' command, you should use minor number 0. Beware that lots of programs will default to /dev/tape, especially `mt'. Use of a tape device with any minor number other than 0 will force a `set density' command. Some drives may be unable to recognize other formats after they have received a `set density' command. The actual major number (currently 12) may be different. [Note: The minor numbers given above don't rewind automatically. Most *nix variants use ``rmtN'' for a rewinding device. If you want that behaviour, add one to the minor number.] STEP 20 Insert a blank tape. STEP 21 Run your particular 'conf-*' program. In my case, I type: conf-mountain (You actually don't need a tape in the drive to run the conf- scripts, but you would need it for the next step :) STEP 22 Do an 'mt rewind'. STEP 23 Now the big test: tar -cvf /dev/tape / If your fs is slow, the drive will not `stream' continuously. In that case, a buffering program should be used. Unfortunately, that's not available (yet?) for Linux. In the meantime, try: tar -b 3000 -cvf /dev/tape / [Newsflash: You may want to try ``edd''. The source for edd can be found in ftp.mei.co.jp:/free/others/edd.tar.Z.] [Mountain NOTE: At least for me, the Mountain driver does not currently work correctly for large files.. that is, it completely hangs the system. :( If this happens for you, turning your tape drive off and on twice (slowly) should release the system and give you a prompt back. ] STEP 24 Verify with: mt rewind; cd /; tar -b 3000 -dvf /dev/tape [not sure pax can do this] [Maybe: ``cd /; tar -cvf - | cmp -'' for pax] STEP 25 If all this works, then you might want to include the conf- script in your /etc/rc.local file. Mine has a couple of lines which say, simply: # Configure and reset the QIC-02 tape drive /sbin/conf-mountain STEP 26 Take the rest of the day off! You deserve it! NOTES FROM HENNUS: ================== NOTE 1: When using tapes, it is important that the tape 'streams', i.e. doesn't start/stop all the time because that is bad for the tape as well as for the drive. If you are cursed with a slow hard disk, you should use a large buffer (-b option for tar) to reduce the starting/stopping. When doing backups on heavely loaded systems however, you may experience similar problems. Alternatively, you can use the 'buffer' program. NOTE 2: A QIC-02 drive will attempt to rewind the tape after power-on and also after it has been given a reset command. It will not rewind the tape immediately but instead it will will delay the rewind until it is given a command that requires actual tape movement. So, if you don't want any nasty surprises, get used to rewinding the tape before/after using it. Otherwise you may insert a tape that has not been rewound and try to append to the end and discover that your data has just been overwritten. The driver sometimes rewinds the tape after reading or writing a file on the tape. [It should only do this when something goes wrong...] So always make sure you know the tape position before performing any command that will write to the tape! NOTE 3: The QIC-02 standard specifies that all drives should support at least some basic commandset, and specifies some optional commands as well. I don't know which drives support which optional commands. Some optional commands are required for certain ioctl operations. In tpqic02.h you can specify which commands are supported by your drive using the TP_HAVE_... defines. You could first try it with all commands enabled and disable the ones that return an 'illegal command' exception status. The seek-to-end-of-recorded media is particularly useful as it avoids re-reading the entire tape, but it will only work correctly if you drive supports it and if there is no data recorded beyond the end of the most recently written file. [With the runtime config this testing has become a little easier...] NOTE 4: Please send me a note whether it works or not. Try to find out what commands are supported by your drive. If I get enough feedback on this, I will include the TP_HAVEs in the distributed sources. Bug fixes and suggestions are of course welcome! IF YOU SEND ME A NOTE ABOUT A PROBLEM OR BUG, MAKE SURE YOU SPECIFY WHAT VERSION OF THE DRIVER, WHAT VERSION OF LINUX, WHAT KIND OF HARDWARE AND ANY OTHER RELEVANT INFO YOU HAVE. The version number of the driver should be printed on-screen when linux boots. If you have problems, please make sure that you are using a clean Linus-distributed kernel with my unmodified qic02 driver/patches. Otherwise contact your distributor in case of problems. NOTE 5: Keep reading comp.os.linux.announce and the tape mailing list. The tape mailing list is now distributed as Usenet News in newsgroup "linux.dev.tape". However, not all sites carry this. NOTE 6: This driver will NOT work for the QIC-40/QIC-80 tape drives, like the well-known tape drives that attach to the floppy controller. It will not work for any kind of SCSI or IDE tape drive. It will not work for the new Travan TR-4 tape drives. NOTE 7: If you are working on another (e.g. SCSI or QIC-40) tape driver, please try to use the same sys/mtio.h file! Also, join the TAPE mailing list! This code has not been tested in combination with SCSI driver(s). If you do, make sure you use different interrupts, dma numbers and IO addresses! Enjoy! --Hennus Bergman hennus@cybercomm.nl ============================================================================== This README.tape was originally written by Jeff Stern. Original README.tape by Hennus Bergman. Please don't write me (Jeff Stern) with problems in installation intrinsic to the driver itself. Jeff Stern .