100% Machine Code

Back in the times when cassette inlay texts and cover artwork were doing a lot of the heavy lifting for what turned out to be a game written in BASIC, the above statement was used as an additional mark of quality – this game must be good as it’s written entirely in machine code. And as we all know, it’s impossible to write a bad game in machine code.

On Christmas Eve, I released version 1.00 of my esxDOS file browser. As the previous version was 0.24 there’s been a bit of a jump in the numbering but there is a reason for this.

Originally the browser was written using the z88dk C compiler. I write C/C++ code for a living so it was a good place to start, especially as my Z80 assembly was a bit lacking back in 2020. Over time, I swapped out bits of the C code for Z80 assembly equivalents where possible but the main part of the browser – the code that accesses the FAT16 / 32 file system – was still written in C.

This wasn’t terrible but there was an overhead in switching between the compiled C code and my hand written assembly. Assembly code can use the Z80 registers as it pleases, so the C compiler has to add some code around assembly functions to ensure everything is saved and restored correctly. After v0.24 was released, I decided to bite the bullet and rewrite this core code in assembly.

This took several months – breaking the code a number of times – but ended with an assembly code version of the FAT code. With this done, it wasn’t too much additional work to remove the final bits of C that were keeping things together and driving the main input loop of the browser. The browser was now fully written in assembly. As a kind of throwback to the 100% machine code boasts of the past, I decided to bump the version to 1.00.

Looking back, peak browse was reached in v0.15 at 12,908 bytes for the main BROWSE.BIN file. v0.24, the last of the C based browsers had gotten this down to 9194 bytes (over 3kb smaller) through a combination of partial assembly refactoring and moving functionality out into separate browser plugins. v1.00 got this down to 8039 – another 1kb shaved off.

As ever, v1.00 can be downloaded from here. The official support thread over at the Spectrum Computing forum can be used to report any issues, bugs or feature requests. Thanks to all those patient people who participated in testing and reporting bugs with the interim builds.

Many happy returns!

Today marks the 41st birthday of the ZX Spectrum, so I thought I’d mark the occasion by bringing some presents to the party.

Let’s start with a party game. Or more accurately the digital download of Winter Wonder Worm. This isn’t the complete version you get if you purchase the tape from TheFutureWas8Bit – but you do now get 4 levels to worm around in. You can download it from here.

In a bizarre coincidence, the first public release (v0.01) of my long filename browser the ZXUNO and DivMMC / DivIDE devices was also released on this day three years ago. To mark this anniversary, I’ve released v0.24 today as well. This includes some new features, obligatory bug fixes, speed ups and a full rewrite of the .brwscfg configuration program in assembly. You can see me previewing a development version of it in the following video:

Version 0.24 can be downloaded here.

And what’s a birthday party without jelly? I’ve got you covered there as well, especially if you lurrrvve green jelly. I did a mod of my Kempston joystick mod of Snake Pit for Rod Hull so the eggs were changed into green jellies. This probably makes more sense if you were watching certain TV programs on BBC2 back in the 1990s. You can avoid snakes and chow down on jelly here. Here’s a video of Rod playing my green jelly mod:

Enjoy!

381 days later…

Spurred on by the recent one year anniversary of the release of v0.01 and the YouTube videos by Rod Hull (HE IS ROD HULL!) of TheFutureWas8Bit fame showcasing my long filename browser for esxDOS with his DivMMC Future device, I thought I’d post a small update.

v0.17 with custom colour scheme based on the standard esxDOS NMI browser

At the time of writing this, version 0.17 has just been released which contains a couple of important bug fixes to the code used by the NMI version of the browser. So, if you’re on an older version or running the No_MMC_Memory version on your divIDE device, I would strongly recommend updating to this version even if you’re just using it to launch your .tap and snapshot files and not using some of the more advanced functionality.

As always, you can get the latest version of the browser here and the forum thread at spectrumcomputing.co.uk is a good place to ask for advice, request features, report bugs and get the latest test versions of the browser before official releases.

If you’re a fan of videos with poor production quality, that use the Spectrum ROM font and feature shonky camera phone or video capture footage, then you may also be interested in my fledgling YouTube channel, where you can find videos highlighting new features in upcoming versions of the browser.

I’d like to say a big thank you to all the people who have reported bugs, made suggestions, given feedback and spread the word about my browser. Seeing where the browser is now, just a year on from the first release (which only worked with .tap files on FAT16 cards) is very satisfying!

The Long And The Short Of It

Like many people during the months of April and May, I found myself with a lot more free time on my hands after being put on furlough whilst COVID-19 caused things to grind to a halt across the world. I’d been spending some of it playing around with the ZX-UNO I purchased a while back. This is an FPGA recreation of the Sinclair Spectrum family of computers which also has support for the Russian ‘Pentagon 128’ variant – and the ability to simulate other 8 bit micros like the BBC, C64 and Amstrad.

Picture of my ZX-UNO.
My ZX-UNO.

It uses an SD card to provide an emulated DivIDE/DivMMC interface. These are hardware that let you access an IDE drive, Compact Flash or SD Cards on a real Spectrum. The ‘OS’ these devices use is called ESXDOS. This gives you a command driven interface for accessing files on the disk as well as providing a hardware NMI (Non Maskable Interrupt) button which launches a file browser. This works like a freezer cartridge letting you break in at any point to save a snapshot of the currently running program. It can navigate the contents of the disk as well as letting you automatically load .tap files (virtual Spectrum tape images), .sna, .z80 (memory snapshots) and .trd files (virtual Spectrum disk images normally found on Pentagon machines).

For reference, here’s the standard ESXDOS NMI browser:

The default esxdos NMI browser.
The standard ESXDOS NMI browser with a guest appearance from the ROM font.

You’ll notice it doesn’t handle long file names. ESXDOS supports FAT16 and FAT32 file systems but is limited to the old DOS 8.3 style filenames. The files are also listed in the order they appear on the disk – not in alphabetical order. After using this for a while and having forgotten the joys of dealing with an 8.3 filename world, I started to wonder whether it was possible to do a nicer file browser that could somehow support long filenames.

My first attempt was to write a Python script which took a folder on the SD card and read in all the long filenames and wrote them out to a binary file with a special filename in that folder. I then wrote a basic browser program in C that looked for this file and displayed the contents on the screen to show the long filenames. It then converted the long file name on the fly back to the 8.3 form and launched that through ESXDOS. This sort of worked but had several limitations.

Any time you deleted a file, created a folder, added a new file or renamed an existing one you needed to rebuild the special data file to keep everything in sync. I also ran into an issue during development (I’m primarily running Ubuntu these days. Life’s too short for Windows 10 hassle) where I couldn’t easily determine the 8.3 filename from the original long filename. Most of the time, this wasn’t an issue as the majority of the files all mapped to unique 8.3 filenames. The order of files I was getting in my Python script when enumerating a folder wasn’t quite the same as the order on the disk. So I couldn’t be a 100% sure when you had two filenames like ‘Jet Set Willy.tap’ and ‘Jet Set Willy 2.tap’ – which would appear in 8.3 format as JETSET~1.TAP and JETSET~2.TAP – which short filename related to which long filename.

I decided to start again, this time seeing whether I could access the information directly from the FAT file system. Using the supplied ESXDOS dot command .dskprobe (a low level disk utility) I saw it was possible to access the FAT boot sector which was the first step in getting the information I required. At this point, I switched to C and wrote a test console program that loaded in a disk image I had made of the 512MB FAT16 SD card I’d been using with the ZX-UNO.

After reading a few web pages on the FAT file system, a couple of trips to the hex editor to confer with my disk image and lots of trial and error I had located the root folder and could read the directory entries in it. Long filename support on FAT is rather convoluted due to maintaining backwards compatibility with existing software (it uses pseudo invalid 8.3 filename entries to store the additional information). After getting my head round that, I now had some test code which could list the files in a given directory and show long filenames where used.

The browser code I’d written during my first attempt was then modified to use a list of data structure supplied directly from the FAT rather than from the pre-populated binary file – so that wasn’t a complete waste. I had to do a spot of disassembly on the .dskprobe program as the parameters to the ESXDOS API call to access the disk were not particularly well documented. This wasn’t the only time I had to resort to disassembling ESXDOS components during development of the browser. Fortunately, z88dk has ESXDOS support so it’s includes and code filled in a lot of the blanks.

After a couple of days of hacking around with my FAT test program, I’d knocked up a prototype .dot command called .browse using z88dk. The C FAT code from my test program cross compiled without major issues in z88dk (most of the browser was written in C, except for some assembly graphics routines).

Here’s how the initial version 0.01 of .browse looked:

Version 0.01 of my browser.
Long filenames abound!

It supported long file names and also sorted the filenames – directories first, then files in A-Z order. The colours were hardcoded so folders appeared in blue and files appeared in black. Launching .tap files was supported – the other formats – .sna, .z80 and .trd weren’t. It was also limited to FAT16. There was no support for FAT32. At this stage it was a bit rough around the edges and lacked some key features but was a good enough proof of concept.

My first go at FAT32 support was added in version 0.02, alongside some fixes to the existing FAT code to handle folders that spanned multiple clusters. I also fixed an issue from the first version where on launching .browse, you were always dumped into the root folder regardless of your current directory before hand. I added some code that took the current directory and located it in the FAT.

Version 0.03 of the browser
Those extra 10 characters make all the difference.

On the Spectrum, if you use 8×8 characters in your font you can fit 32 characters on a line. There have been a number of ways to workaround this limitation. Tasword Two, a word processor that shipped with certain editions of the Spectrum 48k+ used a custom font of 4 x 8 to fit 64 characters on to the line. This works but the characters can look poorly defined due to the halved width. A good compromise is custom font of 6 x 8 which gives you 42 characters. I’d seen this used to good effect having played the Adventure International adventure games like Spiderman or Buckaroo Banzai. I decided to go with this to give the browser a bit more space to show filenames. I wrote the 42 column text routine myself in assembly which was a bit of challenge due to the memory layout of the screen on the Spectrum.

Alongside the more compact display, very long filenames were now truncated to the screen width with a custom ellipsis character. I also got .trd files to auto start from the browser after disassembling the .vdisk dot command and ESXDOS NMI browser to see how this was achieved. This was released as v0.03 and was the point when I noticed I was starting to get traction with the project. I’d started a topic on the Spectrum Computing website forum and was getting replies and feedback. From this, I discovered that my FAT code had a number of issues. On some configurations the browser just showed a blank screen and failed to start or listed the root folder correctly but showed empty sub folders or folders full of garbage characters.

v0.04 had a fix for the FAT16 problem where empty or garbage folders were being displayed rather than the actual contents. I also added the ability to load .z80 and .sna files using the ESXDOS .snapload dot command.

Picture of the configuration editor.
Green screens was my delight.

A user asked for the ability to change the colour scheme so I wrote a separate configuration editor program to adjust the colours. I also added the ability to specify the ESXDOS device identifier to use for directly accessing the disk in the browser for configurations with multiple disks or partitions. This was released in version 0.05 alongside some more FAT fixes – I wasn’t handling FAT32 clusters correctly which meant that files on larger drives with clusters greater than 65536 were returning empty folders or garbage folder listings. To my knowledge the FAT code is now working correctly (famous last words).

The hopeful finalisation of the FAT code seems like a good point to pause the story of developing the browser. There’s a lot of other things to go through – replacing the NMI, hitting the limit of .dot commands and accessing the ZX-UNO turbo modes – but that’s for another post.

The latest version of my browser can always be downloaded from here. There’s also the browser topic at the Spectrum Computing forum which contains ongoing information and discussions.