kernel/linux/Documentation/scsi/osst.txt

   1 README file for the osst driver
   2 ===============================
   3 (w) Kurt Garloff <garloff@suse.de> 12/2000
   4
   5 This file describes the osst driver as of version 0.8.x/0.9.x, the released
   6 version of the osst driver.
   7 It is intended to help advanced users to understand the role of osst and to
   8 get them started using (and maybe debugging) it.
   9 It won't address issues like "How do I compile a kernel?" or "How do I load
  10 a module?", as these are too basic.
  11 Once the OnStream got merged into the official kernel, the distro makers
  12 will provide the OnStream support for those who are not familiar with
  13 hacking their kernels.
  14
  15
  16 Purpose
  17 -------
  18 The osst driver was developed, because the standard SCSI tape driver in
  19 Linux, st, does not support the OnStream SC-x0 SCSI tape. The st is not to
  20 blame for that, as the OnStream tape drives do not support the standard SCSI
  21 command set for Serial Access Storage Devices (SASDs), which basically
  22 corresponds to the QIC-157 spec.
  23 Nevertheless, the OnStream tapes are nice pieces of hardware and therefore
  24 the osst driver has been written to make these tape devs supported by Linux.
  25 The driver is free software. It's released under the GNU GPL and planned to
  26 be integrated into the mainstream kernel.
  27
  28
  29 Implementation
  30 --------------
  31 The osst is a new high-level SCSI driver, just like st, sr, sd and sg. It
  32 can be compiled into the kernel or loaded as a module.
  33 As it represents a new device, it got assigned a new device node: /dev/osstX
  34 are character devices with major no 206 and minor numbers like the /dev/stX
  35 devices. If those are not present, you may create them by calling
  36 Makedevs.sh as root (see below).
  37 The driver started being a copy of st and as such, the osst devices'
  38 behavior looks very much the same as st to the userspace applications.
  39
  40
  41 History
  42 -------
  43 In the first place, osst shared it's identity very much with st. That meant
  44 that it used the same kernel structures and the same device node as st.
  45 So you could only have either of them being present in the kernel. This has
  46 been fixed by registering an own device, now.
  47 st and osst can coexist, each only accessing the devices it can support by
  48 themselves.
  49
  50
  51 Installation
  52 ------------
  53 osst got integrated into the linux kernel. Select it during kernel
  54 configuration as module or compile statically into the kernel.
  55 Compile your kernel and install the modules.
  56
  57 Now, your osst driver is inside the kernel or available as a module,
  58 depending on your choice during kernel config. You may still need to create
  59 the device nodes by calling the Makedevs.sh script (see below) manually,
  60 unless you use a devfs kernel, where this won't be needed.
  61
  62 To load your module, you may use the command
  63 modprobe osst
  64 as root. dmesg should show you, whether your OnStream tapes have been
  65 recognized.
  66
  67 If you want to have the module autoloaded on access to /dev/osst, you may
  68 add something like
  69 alias char-major-206 osst
  70 to your /etc/modprobe.conf (before 2.6: modules.conf).
  71
  72 You may find it convenient to create a symbolic link
  73 ln -s nosst0 /dev/tape
  74 to make programs assuming a default name of /dev/tape more convenient to
  75 use.
  76
  77 The device nodes for osst have to be created. Use the Makedevs.sh script
  78 attached to this file.
  79
  80
  81 Using it
  82 --------
  83 You may use the OnStream tape driver with your standard backup software,
  84 which may be tar, cpio, amanda, arkeia, BRU, Lone Tar, ...
  85 by specifying /dev/(n)osst0 as the tape device to use or using the above
  86 symlink trick. The IOCTLs to control tape operation are also mostly
  87 supported and you may try the mt (or mt_st) program to jump between
  88 filemarks, eject the tape, ...
  89
  90 There's one limitation: You need to use a block size of 32kB.
  91
  92 (This limitation is worked on and will be fixed in version 0.8.8 of
  93  this driver.)
  94
  95 If you just want to get started with standard software, here is an example
  96 for creating and restoring a full backup:
  97 # Backup
  98 tar cvf - / --exclude /proc | buffer -s 32k -m 24M -B -t -o /dev/nosst0
  99 # Restore
 100 buffer -s 32k -m 8M -B -t -i /dev/osst0 | tar xvf - -C /
 101
 102 The buffer command has been used to buffer the data before it goes to the
 103 tape (or the file system) in order to smooth out the data stream and prevent
 104 the tape from needing to stop and rewind. The OnStream does have an internal
 105 buffer and a variable speed which help this, but especially on writing, the
 106 buffering still proves useful in most cases. It also pads the data to
 107 guarantees the block size of 32k. (Otherwise you may pass the -b64 option to
 108 tar.)
 109 Expect something like 1.8MB/s for the SC-x0 drives and 0.9MB/s for the DI-30.
 110 The USB drive will give you about 0.7MB/s.
 111 On a fast machine, you may profit from software data compression (z flag for
 112 tar).
 113
 114
 115 USB and IDE
 116 -----------
 117 Via the SCSI emulation layers usb-storage and ide-scsi, you can also use the
 118 osst driver to drive the USB-30 and the DI-30 drives. (Unfortunately, there
 119 is no such layer for the parallel port, otherwise the DP-30 would work as
 120 well.) For the USB support, you need the latest 2.4.0-test kernels and the
 121 latest usb-storage driver from
 122 http://www.linux-usb.org/
 123 http://sourceforge.net/cvs/?group_id=3581
 124
 125 Note that the ide-tape driver as of 1.16f uses a slightly outdated on-tape
 126 format and therefore is not completely interoperable with osst tapes.
 127
 128 The ADR-x0 line is fully SCSI-2 compliant and is supported by st, not osst.
 129 The on-tape format is supposed to be compatible with the one used by osst.
 130
 131
 132 Feedback and updates
 133 --------------------
 134 The driver development is coordinated through a mailing list
 135 <osst@linux1.onstream.nl>
 136 a CVS repository and some web pages.
 137 The tester's pages which contain recent news and updated drivers to download
 138 can be found on
 139 http://linux1.onstream.nl/test/
 140
 141 If you find any problems, please have a look at the tester's page in order
 142 to see whether the problem is already known and solved. Otherwise, please
 143 report it to the mailing list. Your feedback is welcome. (This holds also
 144 for reports of successful usage, of course.)
 145 In case of trouble, please do always provide the following info:
 146 * driver and kernel version used (see syslog)
 147 * driver messages (syslog)
 148 * SCSI config and OnStream Firmware (/proc/scsi/scsi)
 149 * description of error. Is it reproducible?
 150 * software and commands used
 151
 152 You may subscribe to the mailing list, BTW, it's a majordomo list.
 153
 154
 155 Status
 156 ------
 157 0.8.0 was the first widespread BETA release. Since then a lot of reports
 158 have been sent, but mostly reported success or only minor trouble.
 159 All the issues have been addressed.
 160 Check the web pages for more info about the current developments.
 161 0.9.x is the tree for the 2.3/2.4 kernel.
 162
 163
 164 Acknowledgments
 165 ----------------
 166 The driver has been started by making a copy of Kai Makisara's st driver.
 167 Most of the development has been done by Willem Riede. The presence of the
 168 userspace program osg (onstreamsg) from Terry Hardie has been rather
 169 helpful. The same holds for Gadi Oxman's ide-tape support for the DI-30.
 170 I did add some patches to those drivers as well and coordinated things a
 171 little bit.
 172 Note that most of them did mostly spend their spare time for the creation of
 173 this driver.
 174 The people from OnStream, especially Jack Bombeeck did support this project
 175 and always tried to answer HW or FW related questions. Furthermore, he
 176 pushed the FW developers to do the right things.
 177 SuSE did support this project by allowing me to work on it during my working
 178 time for them and by integrating the driver into their distro.
 179
 180 More people did help by sending useful comments. Sorry to those who have
 181 been forgotten. Thanks to all the GNU/FSF and Linux developers who made this
 182 platform such an interesting, nice and stable platform.
 183 Thanks go to those who tested the drivers and did send useful reports. Your
 184 help is needed!
 185
 186
 187 Makedevs.sh
 188 -----------
 189 #!/bin/sh
 190 # Script to create OnStream SC-x0 device nodes (major 206)
 191 # Usage: Makedevs.sh [nos [path to dev]]
 192 # $Id: osst.txt,v 1.1.1.1 2005/04/29 01:40:34 echo Exp $
 193 major=206
 194 nrs=4
 195 dir=/dev
 196 test -z "$1" || nrs=$1
 197 test -z "$2" || dir=$2
 198 declare -i nr
 199 nr=0
 200 test -d $dir || mkdir -p $dir
 201 while test $nr -lt $nrs; do
 202   mknod $dir/osst$nr c $major $nr
 203   chown 0.disk $dir/osst$nr; chmod 660 $dir/osst$nr;
 204   mknod $dir/nosst$nr c $major $[nr+128]
 205   chown 0.disk $dir/nosst$nr; chmod 660 $dir/nosst$nr;
 206   mknod $dir/osst${nr}l c $major $[nr+32]
 207   chown 0.disk $dir/osst${nr}l; chmod 660 $dir/osst${nr}l;
 208   mknod $dir/nosst${nr}l c $major $[nr+160]
 209   chown 0.disk $dir/nosst${nr}l; chmod 660 $dir/nosst${nr}l;
 210   mknod $dir/osst${nr}m c $major $[nr+64]
 211   chown 0.disk $dir/osst${nr}m; chmod 660 $dir/osst${nr}m;
 212   mknod $dir/nosst${nr}m c $major $[nr+192]
 213   chown 0.disk $dir/nosst${nr}m; chmod 660 $dir/nosst${nr}m;
 214   mknod $dir/osst${nr}a c $major $[nr+96]
 215   chown 0.disk $dir/osst${nr}a; chmod 660 $dir/osst${nr}a;
 216   mknod $dir/nosst${nr}a c $major $[nr+224]
 217   chown 0.disk $dir/nosst${nr}a; chmod 660 $dir/nosst${nr}a;
 218   let nr+=1
 219 done