LBAcache/COMcache, in the version of Jan 24 2002, all
written and conceived by Eric Auer <eric@coli.uni-sb.de>.
Updated to describe the version of Apr 23 2003 / Aug 25 2003.
Update Jun 26 2003: See description of TICKLE below.


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.


*** Limitations ***


* Read cache only *


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.


* Disclaimer/Warning *


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: ***


* Usage as a driver (.sys device or .com TSR) *


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


* Usage to control the already loaded driver *


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: .. J: by "ejecting" the
associated media. STOP also frees the XMS used. [NEW 11/2002: .. J:]


* Details on the syntax *


The argument syntax of the cache itself is currently as follows:
To load:     LBACACHE  [[BUF] size]  [DRV drivelist] [FLOP]
When loaded: LBACACHE  [INFO] [SYNC] [STOP]
To get help: LBACACHE  [HELP] [/?]
Options:
  BUF size  Specifies the buffer size. Maximum value: 99 Default: 8.
            Unit is 256k (in XMS), so default is to use 2 MB XMS.
            (text after the digits is ignored)
  DRV list  Selects which harddisks are cached. NULL means none. Examples:
            C     caches all partitions on the first harddisk only.
            023   caches BIOS drives 80h, 82h, 83h - first, third and   
                  fourth harddisk (hda, hdc, hdd in Linux terminology).
            Allowed drives are 0..7 (BIOS 80h..87h). Alias names: C..J.
  FLOP      Enable the floppy cache (A: and B:, autodetected). To speed up   
            floppy use, load TICKLE, too! Please report if FLOP has bugs.
  INFO      Shows cache statistics and details about resident LBAcaches.
  SYNC      Synchronizes all running LBAcache buffers for all drives. As   
            LBAcache never delays writes, SYNC only is "forget cached data".
  STOP      Shuts down all running LBAcache instances and frees allocated
            XMS. DOS RAM only freed for .com instances, not for .sys ones.

The STAK option is deprecated and now ignored - LBAcache now uses an
internal stack all the time, as FreeDOS only has 192 bytes kernel stack
(STAK deprecated since 11/2002). Text directly following the "size" value
is ignored, and Arguments starting with "X:\" (or A:\ etc.) are also ignored.


* FLOPPY NOTE *


Floppy caching exists in LBAcache since Jan 2002. Nov 2002, I
have added default size detection at startup. In Mar / Apr 2003,
I have finally added logics to automatically adjust to the new
geometry as needed (and flush the affected data) on disk change
and "resize". NEW feature warning: This MIGHT be buggy.

* Update 23 Apr 2003: There WAS indeed a serious bug in the floppy
* handling (chs2lba.asm, *geoFLOPPY did not use drive=dl...).
* Please update to the 23 Apr 2003 version if you have the 1 Apr
* 2003 version. Do not forget to delete the discontinued files
* bin\lbacachd*.* before or after updating.

* Update 26 Jun 2003: Now using DDPT sectors per track values
* (["int 1e" + 4] byte) which are set by DOS based on the boot
* sector contents and may differ from the "native" drive geometry.

You can use -D... options to compile versions which do/do not report
disk change, allow caching of disks without change line, never
flush, etc.: DOSEMU 1.1.3 for example tells "has no change line",
and if asked anyway, it reports "disk changed" all the time.


* TICKLE explanation *


You can load TICKLE after LBACACHE to speed up floppy reads. TICKLE
takes about 10k of RAM (if you load it into an UMB, you must make
sure that the UMB is suitable as floppy buffer - for example if you
use UMBPCI (www.uwe-sieber.de), run DMACHK to verify that. TICKLE only
makes sense if loaded after LBACACHE (or another int 13 cache) -with-
floppy caching enabled (FLOP option). Otherwise, floppy reads will
become slower, not faster!

The working of TICKLE is simple: Whenever a track is read for the
first time after a disk change or reboot (boot sector reads are
excluded, as they may cause DOS to re-configure disk geometry as
stored at ["int 1e"+4] byte), TICKLE will read the whole track
(only up to 18 sectors if the track size is bigger - so for disk
sizes above 1.44MB, the effect of TICKLE will be less). This will
cause the track to be buffered by LBACACHE - TICKLE itself just
ignores the actual track contents, only the side effect of
"tickling" LBACACHE is important.

TICKLE is experimental software under public domain license.
First tests show that it can improve floppy read speed a lot.
The program is meant to implement "pluggable read-ahead" for
floppies, although the applied method is not a normal read-ahead:
My idea is that reading a full track at a time is the fastest you
can get (reading more or not track-aligned data is not supposed to
be faster). Support for LBA harddisk readahead is planned. Support
for CHS harddisk readahead is a hidden option in TICKLE of 7/2003
(find out how to enable it if you dare ;-)). Contact me if you have
comments or questions. Linux, by the way, has 8 sector (4k) readahead
for disks (configurable, use less if you have mostly small files).


* Common usage examples *


Some popular command lines or config.sys lines for LBAcache:

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 2 MB.
[NOTE: Default buffer size will often change!] If you specify a
buffer size of zero, LBAcache *tries* to use as much RAM as possible!
INFO and startup messages are more user friendly since Aug 25 2003...


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


* Drive detection and LBA *


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. As of 4/2003, floppy size
is checked both at startup and whenever it might change - older
versions may horribly mess up floppy handling for unexpected sizes
or size changes, please UPDATE.


* Multi sector read speed up *


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


* BINSEL cleverness *


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). 
[NOTE: Has been 4 sub entries until 11/2002]

Older versions used more space for the tables and/or were dumber.
Check the binsels.zip for the older versions. Currently, BINSEL2.ASM
contains the two MAIN cleverness functions. See BINSEL2.TXT for some
info on how to write your own versions of them! The LBAcacheD.com
and .sys versions have BINSEL2.ASM->NEWBIN debugging messages turned
on: When LBAcacheD decides to throw away cached sectors to make room
for new sectors, you will get a short message on the screen. Also
helpful to determine the right size of my cache for your task :-).

The 13nov02 version of BINSEL2 uses a generic (possibly slow: up to
some 6500 loop iterations to find back a sector in cache) scan for
buffered sectors. The new method to allocate space for a NEW sector
is pretty simple: If the sector cannot become part of an already
existing bundle (of currently 8 sectors), a new bundle is allocated
at the end of a circular buffer. You can mark the importance of a
bundle as 255 to protect it from being overwritten! No tool provided
for doing this, though. The idea is to use this to make FAT/directory
data stay in the cache forever, something like: "freeze mode on",
then do "dir /s /b > nul" on all drives, "freeze mode off".

The 13nov02 was indeed too slow: Loading Descent took 40 seconds on
133 MHz due to calculations (without cache: 4 seconds), so I have
written code to speed up BINSEL2 by the use of a 256 entry by-hash-
addressed MEMOIZATION lookup buffer. Should be fast enough now :-).
The 15nov02 also has yet another cleanup of the INFO screen done,
as has the 25aug2003 version.


* Memory consumption details *


Normally, memory usage is limited to 56k (5k for the driver and up
to 50k for managing up to 24.75 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
or by the driver size limit of 64k (whatever limit is hit first).
The special "maximum size mode" (option "buf 0") reaches 29 MB XMS
size if the driver finds 64k DOS memory available if you use the
25aug2003 version with the standard 4k element size.

New in [NEW 11/2002]: When you make LBAcache so big that there would
not be enough DOS RAM for the driver, the driver will display "..."
while shrinking itself! XMS usage will *not* shrink, so loading will
simply fail if not enough XMS is available. The "..." are meant as
a warning to you to use a smaller value for the BUF size selection
argument! So please unload, use a better value, and load again.
Or edit your config.sys, reboot. You get my point :-). This is
especially useful for DEVICEHIGH or LOADHI usage, when you are not
sure if your UMBs are big enough.


*** Footnotes ***


* 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!
The working of the GPL allows you to use my code in your project
ONLY IF your project will be open source, too. You may charge money
for your product, but you cannot disallow users to give the source
code of it to others, once they got it. This will help to create an
evergrowing source of open code for all open minded programmers :-).

