LBAcache/COMcache, in the version of Jan 24 2002, all
written and conceived by Eric Auer <eric@coli.uni-sb.de>.

Welcome to Erics GPLed* LBAcache hard disk cache! You need some
XMS, at least a 386 CPU and some (...) drive to cache to use this.

See the footnote on the GPL. It is GPL version 2, by the way.
In short: This is FREE software, intended to be useful, but
WITHOUT ANY GUARANTEE. And it comes with the (nasm) source code.
Please read COPYING.TXT which should also be in this directory,
which contains the full license agreement.

Only read access is cached, so no waiting for that "It is now
safe to turn off your PC" message - but also somehow suboptimal
performance. I recommend setting BUFFERS to 4*(cluster size in
KByte) + 2 in (fd)config.sys to maybe have some small write cache
as well. By the way, smartdrv usually offers 32 write buffers.

Next, the usual WARNING: This is a beta version of a thing that
interacts with your hardware very closely. So be warned that any
bug I have not found yet may destroy your data! Do BACKUPS of
your data before you start using this and once a while, stop
using this cache to make fresh versions of those backups, etc.!

You may have guessed it, but I would not have released this if it
were destroying data all the time. So here are the good news:
The cache has been NICE to my data recently, so I hope it will be
to yours as well. Only drives supported by the BIOS are supported,
but no special ones like CD drives and ZIP drives and similar.


*** How to use the cache: ***


You can load the cache in fdconfig.sys or config.sys using
DEVICE=LBACACHE.SYS [arguments]
or DEVICEHIGH=LBACACHE.SYS [arguments]
or you can load it from the DOS prompt or in autoexec.bat using
LBACACHE.COM [arguments]
or LOADHIGH LBACACHE.COM [arguments]
which should all work roughly the same, but maybe some systems
will not work with ...HIGH... and others will only work with
...HIGH... (please tell me if this is the case for you).

There are three "UNCACHE" options: INFO shows statistics on
loaded instances of LBACACHE. The STOP option removes all
instances of LBACACHE. Finally, the SYNC option empties/flushes/
syncs all cache instances for drives A: .. F: by "ejecting" the
associated media. STOP also frees the XMS used.

The argument syntax of the cache itself is currently as follows:
[BUF] digit(s)[text]   will set the buffer size to digit(s)*256k.
                       0 will set to some default value.
                       At most 2 digits for now! [NEW 11/2002]
DRV list               will only cache drives in list, using the
                       BIOS numbers. C = 0 = BIOS 0x80 = /dev/hda,
                       D = 1 = BIOS 0x81 = /dev/hdb ... up to J.
                       [up to J: is NEW 11/2002]
FLOP                   will enable caching for floppies, but only
                       if they allow change detection. WARNING:
                       see the note on havoc with this below!
STAK                   Activates an internal stack (for use with
                       FreeDOS, which has only 192 bytes of kernel
                       stack or so) - 500 bytes more RAM used.
{HELP|?}               Shows a help message.

WARNING: If your floppy change detection does not work and/or the
floppy cache function (since Jan 2002) is buggy, you have to flush
the cache by hand using "uncache f" or data from several floppies
may be mixed in an awful way in the lbacache and/or DOS buffers,
and this mix may even end up being written back, destroying data
on your floppy disk. [NOTE: seems to work fine. Phew :-) 11/2002]
Also, any geometry above 1.44 MBy is rejected at startup, BUT
if you later change it, lbacache will not detect the fact and
will horribly fail for that floppy. [NOTE: impoved detection at
startup 11/2002. Later changes will still cause HAVOC]

Using other geometries than 1.44 MBy for floppies will probably
cause data inconsistencies, so do NOT do it unless you are a
programmer trying to fix this bug! After all, the floppy cache is
a quite new feature and less tested than the hard disk cache.
[NOTE: When not changing the geometry while LBAcache is caching
them, OTHER sizes MIGHT work now. NEW 11/2002. Feedback wanted!]

Examples:
lbacache buf 7
device=lbacache.sys drv d buf 15 flop
lbacache info

The defaults are to cache CDEFGHIJ and set the buffer size to 1M.
[NOTE: Default buffer size will often change!]


*** Technical stuff (do not read this if you do not want to!): ***


If no LBA BIOS is found, reads will be converted from CHS to LBA
and back again on demand, and you will even be able to do LBA reads
after loading the cache. No such feature is planned for the writes
for now. Mail me if you have use for them. Floppy access will always
be converted to CHS style.

[NEW as from 11/2002:] LBAcache will now scan for up to 8 harddisks
and remember for each of them whether they support LBA (normally,
a LBA capable BIOS will support LBA for almost any harddisk) and
whether they seem suitable for caching. Sanity checking is also
there for floppy drives, but if you use mixed sizes of floppies,
LBAcache will most likely miss the size change and will trash all
data copied to/from the "floppy of the wrong size"! I do not even
recommend using any other floppy size than 1.44 MB at all yet.

Reads will be split up: A sector found in the cache will be read
directly, while disk reads are collected and done in larger chunks
if possible (since 1/2002). This will hopefully speed up reading
larger files with FreeDOS kernels 1.1.25 and better a lot (compared
to the situation with older kernels or older versions of LBAcache
which made no use of the new kernel feature).

The behaviour of the cache is to a very big extend controlled
by selecting one of the binsel.* as source of the binsel.asm,
but only binsel.asm (binsel.ni2) is maintained now. Maybe you
have to adjust the others to work with the current version.

The current version of binsel.asm uses a table with 8 bytes of DOS
memory per main entry, which can hold up to 16 sub entries. The
current setting is 8 sub entries per main entry - thus you need
2k of DOS memory for 1M of XMS memory (2k sectors). The old version
binsel.nil has no subentries and uses a lot of memory. The even
older binsel.cnt does the same, but tries to be clever in deciding
which part of XMS to reuse first as it runs out of memory, which
can on the other hand take a lot of CPU time! My plan is to add
a bit of cleverness to binsel.asm without taking too much time.
Comments on the sub entries per main entry ratio and the hashing
and the cleverness are welcome. Questions on the API used by binsel
are also welcome, if you want to do your own "binsel plugin".
[NOTE: Has been 4 sub entries until 11/2002]

Memory usage is limited to 60k (up to 8k for the driver and up to
52k for managing up to 25 MB of XMS in "8 sub entries per main
entry" mode), XMS usage is basically limited to "99*factor"
(currently, factor is 256k) or 64 MB or the XMS you have available
of by the DOS memory limit of 60k. Whatever limit you hit first,
you cannot have a 256 MB XMS cache for sure :-)). [11/2002 data]


* free as beer and speech and has to stay like that. Feel free to
improve this, but please tell me about your new versions... And do
not forget to mention me in the credits, or you will get bad karma!

