DouBle Alpha Version 0.2		25 Feb 1994
------------------------

Double is a block device driver for Linux that does on-the-fly compression.
It does not implement a compressed file system as such, but a file system
can be mounted on a compressed device.

Version 0.2 is very significantly different from version 0.1 and
has many new features. Therefore it needs some testing before I
can consider it stable. Please try it out.

NEW FEATURES
------------

DouBle 0.2 comes with a choice of 4 different compression algorithms.

- LZW is still included, but will probably not be supported in future
releases: It is slow, does not give the best compression, and is patented.
- A derivative of the predictor used in PPP (by Dave Rand) has been
chosen as the new default algorithm. Although it does not give the best
compression either, it is much faster than LZW and is in the public domain.
Although its not the best algorithm, I intend to improve its performance in
future releases.
- LZRW2 and LZRW3A, written by Ross Williams. LZRW3A yields the best
compression of all 4 algorithms, and LZRW2 yields a pretty good high speed
compression. 

mount/umount/df support for DouBle devices. 

- Version 0.2 provides optional support for some (few indeed) fs-like
operations. THE DRIVER IS NOT A FILESYSTEM HOWEVER. There is only support
for put_super, read_super and statfs, with a fs type named "dble" (see below).
Unfortunately, this involves patches to the kernel (and to mount) that I am
not really happy with. Therefore, this is only an option, and the driver can
also be used without fs support.



MISSING FEATURES Please, tell me if you think I should add something.
----------------
- Better recovery when DouBle device becomes out of space. I have something
in mind, but suggestions are welcome.
- A better fsck-like program. dbck is closer to fsck and does more checking
than in version 0.1, but it still does not fix problems.
- The predictor algorithm needs a boost in compression.
- Documentation: there are still no man pages and it's probably going to take
a while because I don't know how to write them (what good am I, really ?).



WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
!                                                                     !
!   Back up your disks before you even think of trying it. I take no  !
!   responsibility for data lost because of this driver.              !
!                                                                     !
WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING


INSTALLATION
------------

 This distribution includes:
- patches against kernel 0.99.15. Unlike previous versions, the driver
itself is included in the patch.
- A set of utilities.
- A patch to the source of mount.c from the usermount package, by Peter
Orbaek and a binary. see section 5b.

0 cd to /usr/src and tar xvfz double-0.2.tar.gz
-----------------------------------------------

1 Patch the kernel (Linux 0.99pl15), from /usr/src:
---------------------------------------------------
patch -p0 <double/double-0.2.patch

You may have to update config.in manually.

The driver uses 2 definitions in config.in:
if CONFIG_DOUBLE is defined, the driver will be compiled into the kernel.
if CONFIG_DBLE_FS is defined, mount/umount/df support for DouBle devices
will be enabled. CONFIG_DBLE_FS is not necessary to the driver. The
utilities dbmount and dbumount can still be used instead.

2 make config, clean and zlilo
------------------------------
There are some warning I didn't get rid of, but I hope it works.

3 reboot
--------
You should see "DouBle: 8 devices, 48 buffers 157K." or something
similar.

4a Make devices with major=19, minor=0-7 say:
--------------------------------------------
mknod -m 611 /dev/double0 b 19 0
mknod -m 611 /dev/double1 b 19 1
........
mknod -m 611 /dev/double7 b 19 7
(of course, you don't have to make all of them)

4b IF you have used the CONFIG_DBLE_FS option
---------------------------------------------
If you want to use that option, you need to make the following devices as well:
major = 19, minor = 128-135.
mknod -m 611 /dev/cdouble0 b 19 128
mknod -m 611 /dev/cdouble1 b 19 129
........
mknod -m 611 /dev/cdouble7 b 19 135

These devices actually mirror the devices with minors 0 to 7.
They are useful only with mount/umount.
These devices should not be used for accessing data on the DouBle device.


5a Make the utilities in ./double
---------------------------------
make
mv mkdble dbmount dbumount dbck /usr/bin (unless you want to compress /usr).
you can also move dbstat, and dbdebug, but it's not necessary.


5b IF you have used the CONFIG_DBLE_FS option
---------------------------------------------
You have a choice of:

- waiting and seeing if your current mount utility is going to work. If it
does, don't read any further, use it as it is.
- using the mount binary included in this distribution.
- making the mount binary from mount.c included in this distribution:
make mount
- patching your mount.c source with the HELP of (not just with) mount.diff. 
Again, this is only an option and you can use the driver without it, even
if you have compiled the kernel with the option set.


6 Make a test (compressed) device/file with mkdble
--------------------------------------------------
mkdble testfile 1000 (Warning: the order of options has changed since V 0.1)

This will create a 1Mb file, with a default compression factor of 2.0
(hence the driver name), clusters of 10240 bytes, blocks of 512 and the
predictor compression algorithm.
After the creation of headers, there will be ~1.9MB of virtual disk
space available in that file. Headers would be smaller on a real device
(as opposed to a regular file). See mkdble for more details.
From my experience, (see HINTS), it is almost always better to use a smaller
compression factor, such as 1.5 (Remember, the predictor is fast, but does
not compress so well).


7a dbmount this new file on a DouBle device
-------------------------------------------
dbmount testfile /dev/double0
If you have made cdouble[0-7], you can use them as well, but there is no
reason to do it.


7b CONFIG_DBLE_FS option ?
--------------------------
try (this is where these cdouble[0-7] devices come up):
mount -t dble ./testfile /dev/cdouble0

UNLIKE dbmount, mount -t dble WILL NOT WORK WITH /dev/double[0-7]

If you have problems with mount read HINTS and/or use dbmount instead.
If it works, try df. If it doesn't work, tell me.


8 create a filesystem on the DouBle device
------------------------------------------
mkfs -t ext2 /dev/double0 [size]
Size is optional and is the value reported by dbmount. I know it may be
confusing, but DO NOT USE cdouble0 HERE. cdouble[0-7] SHOULD ONLY BE
USED FOR mount -t dble (7b) and umount (10b).


9 mount the newly created filesystem
------------------------------------
mount -t ext2 /dev/double0 /mnt

Now, try df.

If (and only if) you have used mount -t dble, you'll see 2 new entries:
testfile      .... /dev/cdouble0
/dev/double0 ..... /mnt
The space used/available on testfile actually is the available free space
on the compressed device. 
WARNING WARNING -------- NEVER LET IT DROP TO 0% ------------- WARNING

If you have used dbmount, there will only be one new entry:
/dev/double0 ..... /mnt
The available free space on the compressed device can only obtained through
dbck.

Et Voila!
Now that you have done it, please read the HINTS document.

10 to unmount the device
------------------------
10a with dbumount (Only if you have used dbmount).
-----------------
umount /dev/double0     or umount /mnt
then,
dbumount /dev/double0

10b with umount (Only if you have used mount -t dble)
---------------
umount /dev/double0   or umount /mnt
umount /dev/cdouble0  or umount testfile


ADDITIONAL UTILITIES AND INFORMATION
------------------------------------

- dbumount unmounts the device/file from the DouBle device. If the DouBle
device is mounted on a directory, umount it first.
dbumount /dev/double0

- dbck checks the integrity of the compressed device/file:
dbck testfile
dbck still needs some work; it does not fix problems yet. It is recommended
to dbumount before running dbck.

- when the mount -t dble option is used, df will report block usage on the
double device. It is safe to have more blocks used on the device than on
the filesystem that uses it, as long as the compression ratio (reported by
dbck) remains satisfactory. It is dangerous however, to let the block usage
on the compressed device reach 100%.


- dbdebug changes debugging level on a DouBle device (MANY messages will
go to the kernel):
dbdebug /dev/double0 5

- dbstat reports the number of read/write accesses made and how often buffers
were already loaded when requested:
dbstat /dev/double0   (dbstat will cumulate information on all devices).


Finally and foremost, this new version of the DouBle driver hasn't been
tested very extensively yet. I want you to give it a try and help me improve
it.
					Thanks in advance.


Send bug reports to <jmv@receptor.MGH.harvard.edu>


ACKNOWLEDGMENTS
---------------

Leo Broukhis <leo@fuso.zycad.com> and Jean-Loup Gailly <jloup@chorus.fr>
have contributed a kind and precious expertise in the choice of new
compression algorithms. The salient new features of this version are
due only to their contribution.
Thomas Graichen <graichen@sirius.physik.fu-berlin.de> has been most
helpful in making suggestions and comprehensive tests of this driver,
which have resulted in several improvements.
Many other people have provided useful reports; I hope you will continue
to help me inprove the DouBle driver.


AUTHORS
-------

Jean-Marc Verbavatz (Jan 1994) <jmv@receptor.mgh.harvard.edu>

Parts of the driver source were adapted from the loop driver copyright
by Theodore Ts'o.
The LZRW2, LZRW3-A algorithms were written by Ross Williams
The predictor algorithm was originally written by Dave Rand, updated by
a couple of other people (see file pred.c)
All three source files were modified for the DouBle driver by Jean-Marc
Verbavatz