DouBle Alpha Version 0.1a		10 Feb 1994
------------------------

The purpose of DouBle is to provide on the fly disk compression.
This version needs some testing and is submitted for you to
try it out.
Version 0.1a includes the patch (patch01) required to use the DouBle
driver with several devices and patches against kernel 0.99.15.
Otherwise, it is not significantly different from version 0.1

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 with this driver.                    !
!                                                                     !
WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING

The DouBle device driver acts as an interface between the physical
(compressed) data on a device or a regular file, and a pseudo
"DouBle" block device, where raw data is written/read.

DouBle was inspired from the loop driver, written and copyright by
Theodore Ts'o. and works similarly, with the following additions/differences:

1 - The physical file/device contains a header (a), a bitmap (b) and a
block allocation table (c) referred to as BAT in the source. Regular
files used as devices also contain a block map table (d).

2 - The physical file/device needs to be formatted before it can be
used (see the mkdble utility).

3 - The major number for DouBle is currently 19.

4 - some kernel functions have been included within the driver.

(a) The header contains a Magic number and relevant informations on
the size and number of physical blocks (called isize and iblocks) and
virtual block clusters (osize and oblocks).

(b) The bitmap tells which iblocks are already allocated.

(c) The BAT contains information on the type of compression, and on
which iblocks the clusters are made of. Each oblock (cluster) is made of
several (smaller) iblocks (from 1 to osize/isize), depending on the
compression factor for the cluster. 

(d) The block map table is used by the driver to access a real block
from the block number of a regular file.


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

1 Patch the kernel (Linux 0.99pl15). I have added CONFIG_DBLE to config.in,
but you'll probably need to update this file manually.

2 make config, clean and zlilo or zImage

3 reboot: You should see "DouBle: 8 devices, 30 buffers 130K." or something
similar

4 Make devices in dev 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)

5 Make the utilities in util.tar.

6 Make a test (compressed) device/file with mkdble. Example:
mkdble testfile 1000

This will create a 1Mb file, with a default compression factor of 2.0
(hence the driver name), oblocks of 8192 bytes and iblocks of 1024. 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.

7 mount this new file on a DouBle device:
dbmount testfile /dev/double0

8 create a filesystem on the DouBle device:
mkfs -t ext2 /dev/double0 size 	(where size is the value reported by dbmount).

9 mount the newly created filesystem anywhere you want:
mount -t ext2 /dev/double0 /mnt

Et Voila!
You now have almost 2Mb of space where there was only 1Mb.
Well, it's not that simple, because it all depends on what you are going
to put there. With gzipped files your compression factor will be 1, and
you will only be able to store <1MB of data before you run out of
"physical space". The driver message:
"get_new_bit: out of space", would come along with numerous other kernel
messages. It means troubles.

If you want to avoid problems, be conservative in the compression factor
used in mkdble (I often use 1.6-1.7) and DON'T STORE COMPRESSED FILES ON A
COMPRESSED DEVICE.
In addition, it is recommended to run dbck from time to time; just to
see problems looming before they occur.

10 to unmount the device, first use umount, then dbumount as follows:
umount /dev/double0
dbumount /dev/double0

on a (formatted) floppy, you could try:
* mkdble /dev/fd0 1440  (if it's a 1.44MB floppy)
  dbmount /dev/fd0 /dev/double1
* mkfs -t ext2 /dev/double0  nnnn  (where nnnn is the size reported
  mount -t ext2 /dev/double0 /mnt   both by mkdble and dbmount)

And to unmount the device:
  umount /dev/double0
  dbumount /dev/double0

(commands with a *, only need to be typed for creation and don't need to
be repeated the following times around).



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

For obvious reasons, I don't recommend using the following two utilities
while the DouBle device is being used (i.e. mounted on a filesystem).
In other words, umount it first and sync:

- dbumount unmounts the device/file from the DouBle device:
dbumount /dev/double0

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

- 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).

This driver is slow and I am seeking suggestions to improve it. Regular files
used as compressed devices will probably be VERY slow as additional disk
access is required. Increasing DB_NR_BH and/or DB_NR_VB in
include/linux/double.h, or changing cluster/block sizes might help.

Finally and foremost, this driver has'nt been tested very extensively yet.
I want you to give it a try and help me improve it.
					Thanks in advance.

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.
