Early August work on LBAcache & bugs

2026-08-09

Most of the work this week was on converting Eric Auer's LBAcache to provide and use an Alternate Multiplex Interrupt Specification (AMIS) multiplexer. (The use is in uncache, the transient part that works with previously installed instances rather than installing a new one.) The advantages are as follows:

• Cooperates with other TSRs by providing an IBM Interrupt Sharing Protocol (IISP) header, and an interrupt list for the AMIS interface.
• Decouples the hardcoded variable and entry layout required for prior versions.
• Allows detecting resident instances without the error-prone memory scan.
• Using the advanced deinstallation method the uninstaller can take advantage of other IISP headers and AMIS interrupt lists.
• Multiple resident instances can now uninstall cleanly using a single STOP command.

The disadvantages are:

• Need to hook interrupt 2Dh.
• Several paragraphs of memory spent for the multiplexer-specific data structures and code handlers. (Due to the optimisations of the resident part, the updated LBAcache including the multiplexer still uses less memory (table @ 1050h) than Eric's last version (table @ 117Ch).)

I found that testing LBAcache works best with buffers=1 in ldos.ini, or by adding append buffers=1 to the kernel command line. That way, DOS cannot buffer as much as it would usually, hence more reads go to LBAcache's handler.

The patldos.asm assembly language program's matching of progress type keywords was severely broken. The changeset message states:

patldos.asm: fix match of PRO mode keywords

Selecting "app" would indicate an error stating that "pp" was an invalid progress mode. The cause of this error was the stray mov dx,si (si is CHG after the call to comparecaps).

Next, the description would be matched unintentionally. This was due to not incrementing past it for the first .loopinnerpro iteration. Solved by moving inc di twice to that label.

Subsequent mode keywords wouldn't be matched because the code at .nextouterpro popped di once rather than twice.

Finally, .gotpro doesn't use the stacked di pointers any longer so discard them off the stack.

• Fix a typo in the manual.
• Empty changeset to rebuild for the new patldos revision of patchini.

Add new bugs recently found:

• Build of small inicomp test program failed.
• Add the scanner mode to inicomp.
• LZMA-lzip depacker did not work with small buffers.
• LZMA-lzip depacker didn't check window size properly.
• New NASM spams label changed during code generation warnings.
• Pass mak.sh parameters faithfully (including quoted blanks) from mak.sh bash to the assembler that's executed via the makefile.
• Allow mak.sh variables for multiple options to quote so that parameters with blanks can be passed.
• ident86 would misdetect instruction boundary if a difference is in a continued machine code dump listing line.

• Add LBAcache build to script.
• Add intlist documentation to script, older change that was present in the working directory but not yet checked in.

• Add empty file to track listing subdirectories.
• Add mak.sh script.
• Add a .hgignore file.
• Include the lmacros3.mac file, identicalised to prior revision.
• Optimisations.
• Automate calculation of three defines. Identicalised.
• Strip trailing whitespace, using a perl scriptlet: perl -i -pe 's/[ \t]+([\r\n]*)$/$1/' *.* tools/*.*
• Move the table label into an [absolute $] section, so its alignment need not be emitted into the binary. Identicalised.
• Delete the progbits alignment in hello message.
• Update version.
• Update all mentions of "GPL 2" to "GPL 2+".
• Update attribution to include ecm.
• Avoid repeatedly writing to tableend. The tableend and bonustable variables already were using the same word in memory, yet the writers wrote using both labels.
• Optimisations in binsel.asm
• Check for an invalid S=0 coordinate.
• Align table on an 8-byte boundary (rather than only 4-byte).
• Align several variables on word or dword boundaries.
• Drop tabs before help message db directives, so the source text lines fit on the screen better.
• More optimisations, including to call old int 13h without a retn near return eating a stack slot.
• Add amis.mac macro file from lDebug repo.
• Use IISP header for int13new. Drop the magic signature used to find resident instances in the memory scan. This makes the current uncache component incompatible with resident instances of this revision.
• Optimise the int 13h handler and jump to downlink.
• Add an int 2Dh handler, not yet used.
• Fix so that XMS handle is freed on later installation errors.
• Check that int 2Dh and int 2Fh are valid before calling or hooking them in setup.asm
• Find a free AMIS multiplex number and patch it into the multiplexer's int 2Dh handler.
• Install the int 2Dh handler. This completes most of the resident part of the multiplexer.
• Make checkhandlers a function.
• Display the allocated multiplex number.
• Parse MPX keyword for preferred multiplex number.
• Display hex number hexits in allcaps.
• Insert a cld in the NEWI13 handler.
• Move strtty function from lbacache.asm to uncache.asm
• Setup for a stand-alone build of uncache. Doesn't build yet. The lbacache.com build is identicalised.
• Add CTRLx structures needed by uncache to access the multiplexer.
• Call checkhandlers in uncache, and use args instead of the separate unflag byte variable.
• Fix to actually call eject (13.46) with drive B: rather than calling it twice for drive A:
• Change amissig.desc to refer to "disk read cache". Description of the hgweb repo also changed.
• Drop unused variable named suppzero.
• Add mak.sh lines separating the assembler commands, to be able to tell at a glance whether an error corresponds to the lbacache.com or uncache.com build.
• Add the multiplexer detection loop to uncache. Uninstall is broken. Control variables are accessed using the hardcoded layout as yet. The stand-alone uncache.com build doesn't assemble yet.
• Add uncache files to .hgignore file.
• Convert the infolists to an expanded format, which controls formatting in more detail and makes use of the ctrlX variables and interrupt list as returned by the resident multiplexer.
• Add INFO display of new i13 handler, old and new i2D handlers, and the multiplex number.
• Mark some dispatch.asm variables as ctrl4, and expose them from the multiplexer.
• Fix to reset the amisintrptr if a subsequent instance doesn't support int 2D.mm04 as expected (unlikely).
• Add CTRL4 structure and variables to uncache.
• Fix detection of MPX keyword in command line processing, the high byte of EAX must be cleared for a valid check.
• Use remaining ctrlX and intr pointers for uncache. The uncache.com stand-alone build assembles for the first time. Uninstalling is commented out and as the changeset message states, "ecm advanced deinstallation method is tbd".
• Allow running 2D.mm02 if XMS handle already freed.
• Implement STOP for the multiplexer. Picked lots of code from the lDOS TSR example.
• Add a cld to int 2Dh handler.
• Drop unused variable currint13, no longer read anywhere.
• For STOP command, disable resident instance and free XMS handle after the interrupt unhooking simulation succeeds. This makes it more likely to end up either with a completely uninstalled instance or one that is still operable.
• Add int 2Dh functions to flush all drives or one drive. This is required to properly implement disabling and enabling the resident instance; enabling needs to flush so no stale data is used.
• Fix flush function to initialise EAX.
• Add DISA and ENAB commands to disable or enable a resident instance.
• Add ONCE command to operate on the first detected instance only, rather than on all instances that can be detected.

ETA:

• Move the hello message into space re-used for the cache table, to save on resident space. The multiplexer already contains some identifying strings.
• Optimise resinst entrypoint to just a call flush, increment running variable, and run int 21h to execute TSR. Saves some resident space.
• Close all process handles on successful installation before TSR using int 21h function 31h. Fixes the System File Table (SFT) leak if run with I/O redirection.
• Add RUNNING_ equates and clean up uses of the running variable, introducing the states RUNNING_INIT (as before), RUNNING_ENABLED (as before), and the newly distinguished disabled states: RUNNING_DISA (disabled using DISA command), RUNNING_SHUTDOWN (resident instance shut itself down due to invalid sector addressed or fishyfishy handler entered), RUNNING_FREED (XMS handle has been freed and thus the instance must not be re-enabled without allocating an XMS block).
• Fix MEMOIZE function to use the drive/unit number for hashing, rather than the LRU byte of the cache table entry.
• Drop some cs: overrides, callers of MEMOIZE already set up ds => resident segment.
• Use all-ones cache table entries as uninitialised. This saves some code in the flush functions which can just init the affected entries using all-ones. The inverted mask of used sectors takes slightly more code. The unit number field is used the same as before. The most complex change is using 255 as a "not used" LRU code and move the "frozen" LRU code to 254.
• Fix REMEMOIZE code to mask away the BINMASK from sector number in EAX, both to run the memo hash and to compare the resulting cache table entry to the requested sector.
• In setup use the preferamisnum variable to check for a free multiplex number. In command line processing, do not set amisnum variable, only preferamisnum. This is in preparation for the next changesets.
• Delete the magic number previously used to scan for resident instances.
• Apply a patch to PSP:60h area (which is safe to re-use without interfering with DOS for the TSR), to stash part of the multiplexer (interrupt entries and int 2Dh handler) in the PSP trailer and in the spot used by the flat-format application entrypoint jump. Saves some resident space.
• Insure that there's enough stack space between the end of the tables and the stack used during TSR, so that DOS certainly won't corrupt the bonus table after the flush.
• Align the fbPOINT variable (find bin last used table entry pointer).
• Optimise, drop the default cs: override from MEMOHASH mmacro. All users have ds => resident segment set up.
• Optimise, do not MEMOIZE after a REMEMOIZE match, would just rewrite the same bonus table entry with the pointer to the same cache table entry.
• Disable the checks on bonus table entries being in range of the main cache table. This should always be true, since we only ever write valid pointers to the bonus table.
• Add ctrl5 control data structure with the point query, point hit, memo query, and memo hit counters (each a dword). Inclusion in the resident instance is controlled by a define (default enabled), whereas the transient uncache always includes support for these. Adds the new MEMO command to list these counters. (Note that point query minus point hit always should equal memo query.)
• Drop an obsolete comment on the data layout of the resident instance.
• Move telltabsize into setup.asm and inline it into the only caller. Saves a bunch of resident space and even some of the file size.
• Add the TABLEENTRY structure and use its labels throughout instead of hardcoding the entry field offsets.
• Align the nbwhere and hashwhere variables.
• Swap the jumps in betterbin code, so that the expected repeated jump instruction comes first.
• Fix bestalloc to treat byte [teLRU] equal to 255 as an unused table entry.
• Move the binsel settings into lbacache.asm, preparing for the next changeset.
• Hardcode the BINTABFORM define into tabsz variable instead of initialising it with a separate instruction in setup.asm
• Add amounttableentries variable to do fewer resident calculations, saving some resident space. Also optimise the setup some more.
• Optimise zeroing of stats by using rep stosd
• For ZERO, also clear the known ctrl5 counters.
• Add TABLE command which uses the newly expanded ctrl2 structure to count some values on the cache table use.
• For TABLE command also display amount of total and likely used bonus entries. The heuristic used is that a bonus entry pointing to c2hint (ie, the very first cache table entry) is likely unused, otherwise it is likely used.

ETA:

• Free separate stack block on int 2Dh function 02h call (uninstall), if TUNS was used during installation.

The veritable bugs in the old revision of Eric's LBAcache, mostly copying the entries from above that list the fixes:

• Check for an invalid S=0 coordinate.
• The memory scanning uninstaller didn't free all memory if multiple instances of LBAcache were installed. The multiplexer uninstaller naturally finds the downlink from one LBAcache instance to another and uses it to uninstall everything, regardless the order of the scan results.
• The memory scanning didn't find an LBAcache instance in a certain UMB on dosemu2, due to the segment addresses that it chose to scan, specifically with the PSP at segment C1AAh.
• Fix so that XMS handle is freed on later installation errors.
• Fix to actually call eject (13.46) with drive B: rather than calling it twice for drive A:
• Close all process handles on successful installation before TSR using int 21h function 31h. Fixes the System File Table (SFT) leak if run with I/O redirection.
• Fix MEMOIZE function to use the drive/unit number for hashing, rather than the LRU byte of the cache table entry.
• Fix REMEMOIZE code to mask away the BINMASK from sector number in EAX, both to run the memo hash and to compare the resulting cache table entry to the requested sector.
• Insure that there's enough stack space between the end of the tables and the stack used during TSR, so that DOS certainly won't corrupt the bonus table after the flush.
• Free separate stack block on int 2Dh function 02h call (uninstall), if TUNS was used during installation.

Bugs that I introduced and later fixed during my work on LBAcache:

• Fix detection of MPX keyword in command line processing, the high byte of EAX must be cleared for a valid check. Introduced in the change adding the MPX keyword.
• Fix flush function to initialise EAX. Introduced in the binsel.asm optimisations.
• Fix bestalloc to treat byte [teLRU] equal to 255 as an unused table entry. Introduced in the all-ones as uninitialised patch.

• Aligning several variables.
• Resident space saved.
• Fixing the MEMOIZE and REMEMOIZE bugs (see above).
• Optimise, do not MEMOIZE after a REMEMOIZE match, would just rewrite the same bonus table entry with the pointer to the same cache table entry.
• Disable the checks on bonus table entries being in range of the main cache table. This should always be true, since we only ever write valid pointers to the bonus table.
• Add amounttableentries variable to do fewer resident calculations, saving some resident space. Also optimise the setup some more.