
LIL' FILE

by Dave Hassler, 2024, a Compact Flash interface and file system for the HM-68 (Hassler's Monster 6800) homemade computer.  SWTBUG at $E000 and RAM at $B000-BFFF is required, unless Lil' File is relocated.

Based upon and inspired by Daniel Tufvesson's QUICKFILE 1.0
for his MC3: a 6303-based computer, in 2013.

All mangling of Daniel's code is entirely my fault.  - DHH

I   - Introduction
II  - Commands
III - CFTEST Utility
IV  - Note on CF Cards
V   - Background
VI  - License

I - INTRODUCTION

   LIL' FILE is just that: it's little.  It has few capabilities.  You can:

	C) Print a catalog/directory of a partition
	F) Format (erase) a partition's catalog track
	I) Get information about the CF card
	L) Load a CF card track to the Monster's user RAM
	Q) Quit the file system to the SWTBUG monitor
	S) Save user RAM to a track on the CF card

   Yeah.  That's it.

   The program is not meant to be a complete disk operating system -- that's way above my pay grade.  What it allows a hobbyist to do is save "states" of the machine's user RAM for later fast retrieval.  It can transfer 32 KB in about 9 seconds, which is almost 9 times as fast as a Commodore 1541 disk drive connected to a C64.  Not too shabby!

   The RAM version of Lil' File resides in the 4K block of $B000 (with a lot left over); the ROM version sits at $F200.  SWTBUG was modified so that the 'D' command jumps to Lil' File, instead of executing the FLEX bootloader.  The system both saves and loads the entirety of the Monster's user RAM area: $0000-$7FFF.  This is for simplicity -- it would have been a whole lot more complex to figure out RAM use limits for a pile of different programs.  Feel free to take this code and do whatever you want to make it better/more efficient/more capable.

   One important note regards the physical interface betwen the Monster and the CF card: I have a pile of old Cisco 64 MB CF cards. For some reason (see Note on CF Cards, below), I cannot consistently write and then read back the final byte of a user RAM page (byte 255) to/from the CF card.  I managed to come up with a workaround, which is to write only 128 bytes to an individual CF card sector (using 256 bytes of said sector, even-numbered bytes only).  This allows the user RAM to fill an entire CF card track:

TRACK - CF:  512 bytes/sector   x 256 CF sectors = 131,072 bytes
	RAM: 128 bytes user RAM x 256 CF sectors =  32,768 bytes
	
   This is an effieciency of only 25 percent use of the CF card.  Yet, in True IDE Mode -- i.e., "8-bit mode" -- the CF card will only access the even-numbered bytes anyway -- a 50 percent efficiency.  The way I see it, if I have a cheap 64 MB CF card, I end up with a 16 MB hard drive (in two, 8-MB partitions), which is more storage than anyone in 1979 ever *dreamed* he'd have connected to his personal home computer.  Put another way, 16 MB is the equivalent of 160 FLEX 2.0 single-sided floppy disks.  I think, in 1985, I had no more than 20 floppy disks for either my Apple II or my VIC-20...

   Last, but certainly NOT least: there is VERY little error checking in this file system.  You can over-write files without any warning, or access non-existent tracks -- sadly, the burden falls upon you, the user, to make proper and/or desired access.  Of course, feel free to add in whatever user protections you'd like.  :^)

II - COMMANDS

	C - Catalog

   The Catalog command reads Track 00 of a partition, scanning each sector from $00 to $EA for a valid filename at the start of the sector ($EA is the number of tracks available, per partition, on my Cisco 64 MB cards).  See the commented source code for details of how this record is set up.  The gist is that bytes 00-0F hold an ASCII filename; all other bytes in the sector are $00 (...well, the first 256, anyway...).
   The Catalog command will list out the names of the files held in the various tracks, along with the track number.  ** THE TRACK NUMBER IS VERY IMPORTANT **  It is how the user identifies her desired "file" to load; filenames are not used for the loading process -- again, it's a *very* simple file system.  Maybe I should have called it a "RAM Identifier," instead of "filename."
   Once 17 existing files/tracks are listed, press the SPACE bar to continue the listing, noting the track number in which you are interested.

	F - Format

   Issuing a Format command will write #$00 into every byte of Track 00 in a given partition, from sectors $00 to $EA (for a 64 MB card), thus wiping out any catalog entries previously entered and preparing the 64 MB CF card for new saves.  The data on the actual tracks of the partition are unaffected, partly because the Save function erases sectors as it writes, and so I didn't see the need for a low-level format.

	I - Info

   This command returns the serial number of the inserted CF card, the firmware version/date, the model of the card, and its size, expressed in partitions, tracks and sectors: PP:PP:TT:SS.  PP:PP is, essentially, a 16-bit hexidecimal number of raw 128K tracks available.  It's important to know the bounds of a given card when saving data to it, so as not to "overstep" the limits of the card.  This is the least-adulterated part of Daniel's CFTEST program.  :^)

	L - Load

   Once issued, this command asks for the partition you wish to access, then the track number you wish to load to user RAM.  With a 64 MB card, there will be only two partitions available: 00 00, and 00 01.  Use the C command before the L command to determine the track you wish to load.
   After loading in a track, the contents of user RAM locations $0000 to $7FFF will be exactly as when the track was saved.

	Q - Quit

   This simply exits the Lil' File system and returns to SWTBUG.

	S - Save

   Perhaps the most complex command of the bunch...  It's important to know the partition and track upon which you want to write the whole of user RAM.  For example, let's say you have Altair BASIC loaded and running Mac Oglesby's awesome CAPTURE game.  You decide to save that to the CF card.
   The first thing to do is break out of Altair BASIC with a hard reset, then run Lil' File, use the Catalog command, and determine where there's an open track on your desired partition.  Alternatively, you might choose to overwrite a track that's already in use; that's fine, but you'll receive NO warning you're about to overwrite existing data.
   Anyway, from there, enter 'S' to start the Save-All-User-RAM process.  Answer the filename question, the destination partition, and the destination track.  From there, all data in user RAM from $0000 to $7FFF will be written to the track specified, and an entry into that partition's "catalog track" will be made, recording the filename and what track that particular 'save' is on.

III - CFTEST

   This is a lightly modified version of Daniel's CFTEST to run on the Monster-68 with SWTBUG.  It loads at $A100, so as not to disrupt any main user RAM.  Upon execution, the program reads the CF card's details and capacity.  The really useful part is the 'R' command, which reads and prints out a particular track and sector from the CF card.  The 'W' command lets the user write a page of RAM to a selected track and sector; HOWEVER, that page is going to be $AA.  This is mainly good for editing the contents of a catalog sector, and occasionally for testing.  Just put your new data into Page $AA, then let 'er rip.  'Q' will quit the program.

IV - NOTE ON CF CARDS

   Use "industrial-rated" cards whenever possible; they have 10 times the use-before-failure life as comsumer-grade cards.  I got my stack of nine cards -- pulls from a server system -- off eBay for $20.  I figure there's plenty of life left in even used industrial grade cards for my limited purposes.
   HOWEVER, the stack of used CISCO industrial-grade cards I bought were a mixed lot and some had flaws: part were manufactured in the USA, part in China; the some of the USA cards will not write the 511th byte of a sector reliably.  That drove me mad for a while, until I learned about the wonky manufacture of some of these old CISCO USA-made cards.    This does not matter to Lil' File, as it only uses the top half of any 512-byte card sector, but I thought you should know.
   Anyway, using even a 64 MB CompactFlash Card is overkill on simple, homemade, 8-bit machines.  Lil' File is hard-coded to use a 64 MB card.  If you use a 256 MB card, for example, you'll have a memory layout of 00:07:B0:00.  You'll need to change a few locations to make that work:

	1. In label LOOP5 in the FORMAT section, change CMPB #$EB
		to CMPB #$B1
	2. In label SEC_INC of the CATALOG section, change CMPB #$EB
		to CMPB #$B1

   Other sizes of cards will, of course, need appropriate track (TT) values.  It should be trivial to modify the program to read the card's info at initialization, store the track size value somewhere, then retrieve it (+1) when needed to either format the catalog track(s) or print partition catalogs.
 

V - BACKGROUND

   After building a CF card interface for the Monster in late 2023, I hoped to find a file system or operating system to run on it.  TSC's FLEX 2.0 was the goal, but I could not find a source for anyone having done this before, and it seemed so far out of the reach of my rudamentary programming skills to do it on my own that I abandoned the idea.
   I had followed Daniel Tufvesson's 6303 project for a while on the 'net, and I figured it would not be too difficult to translate his CFTEST code "down" to 6800 assembly to be able to access, read, and write individual sectors from my own system.  Indeed, that proved to be the case -- 6303/6809 code can be ported with a few "extensions" (subroutines) to emulate some of the missing op codes.  Anyway, once I had the CF Card test program working correctly, I took a crack at his full-blown file system for his 6303 machine.  Alas, it was too complicated for me to translate effectively; at least, not within the bounds of my limited knowledge and patience.  :^)
   But it was obvious that if I could get the CFTEST program running on my machine, I could extend Daniel's routines and functionality to make a simple, crude file system that would at least read memory, write it to the card, retrieve it, and keep a log of what was where: minimal functionality!  And thus, Lil' File was born.

VI - LICENSE

   I hope this is useful, maybe informative, or at least entertaining.  The portions of the derivative software written by myself, David H. Hassler, and this 'Lil-File-68_DOC.txt' document, are copyright by David H. Hassler and released under the MIT license; the remainder remains under the copyright and control of Daniel Tufvesson.

Cheers!
Dave