esxDOS dot-command compatibility

One of the most useful ways to make Spectranext easier to adopt is to support the tools people already use. That is why esxDOS-compatible dot-command support is being implemented.

The goal is not to reimplement esxDOS, or to replace Spectranext's virtual filesystem. It is to let a familiar .dot utility run, make its usual calls, and see the files supplied by Spectranext: the RAM and flash overlay, ROM filesystem, network mounts, and the rest of the VFS.

Two systems with different ideas about memory

Spectranet and esxDOS are both built around paging, but they do not expect the same pages in the same sections.

A normal 48K BASIC environment expects its ROM in the low memory area. Spectranet uses the low 16K differently: its ROM, module pages, and permanent RAM have jobs to do there. A dot command, meanwhile, expects an 8K window at $2000-$3fff, split across sections B and 3. The conventional ABI reserves its final 512 bytes, $3e00-$3fff, for the command line, leaving up to 7.5K at $2000-$3dff for executable code and writable program data.

That is the incompatibility. If a dot command is simply launched inside the ordinary Spectranet map, its code can overwrite a page Spectranet needs, or Spectranet can page away code the command is still running.

Classic spectranet could not repage sections 0 and 3 while its own environment was active. Spectranext can temporarily repage both sections and restore them afterwards, which is the capability that makes the shim possible.

The solution is not a new filesystem. It is a small compatibility shim that temporarily constructs the memory view expected by the command, then carefully returns to the normal Spectranet view whenever the command asks for an esxDOS service.

The compatibility shim

The shim has two phases: loading the command into its conventional execution window, then bridging its RST $08 calls back to the normal esxDOS compatibility module.

Phase 1: load and enter the command

When BASIC sees an otherwise unrecognised command beginning with ., the loader looks for the matching command file and reads it into two reserved 4K RAM pages. The first 4K becomes the command's $2000-$2fff region; the second becomes $3000-$3fff. The command line is retained in that second page's reserved $3e00-$3fff tail.

The final map is deliberately the one a conventional dot command expects: the small esxDOS kernel is at section 0, standard RAM page 0 is at A, and the two command pages are at B and 3. The kernel can then enter the command at $2000.

Complex dance of switching environments between Spectranet and EsxDOS

Phase 2: bridge RST $08 back to Spectranet

An executing dot command makes esxDOS calls with RST $08. Its arguments may point into the command's own $2000-$3fff area—an area that will disappear while Spectranet restores its ordinary module map.

The kernel therefore first converts or stages those arguments in permanent RAM. It then pages its own ROM page into B and jumps to a small final jumper at $2f00. That jumper is safe to execute while the mapping changes beneath it. It restores the ordinary Spectranet module-call view: Spectranet page-0 ROM at section 0, RAM page 0 at A and 3, and the esxDOS module at B. Calls to Spectrum ROM routines then use the normal CALLBAS mechanism.

The regular esxDOS compatibility module can now handle the request through Spectranet's VFS. When it returns, the shim reverses the sequence and recreates the dot-command map before returning to the utility.

This is the important boundary: existing programs continue to speak the esxDOS ABI, while Spectranet remains in charge of the underlying storage and module system.

Output and interrupts

The compatibility kernel also implements RST $10, the normal Spectrum character-output restart used by many dot commands. It briefly restores the normal ROM view, calls the Spectrum character printer, and reinstates the dot-command map. That lets commands such as .ls print normally without paying for a full module dispatch for every character.

While the kernel owns section 0, the normal Spectrum interrupt handler is not mapped there. The kernel therefore provides its own small $0038 interrupt stub. This is important for commands that use HALT for timing or keyboard debounce: interrupts continue to wake them instead of leaving the command permanently halted.

The present compatibility target is RST $08 for esxDOS services and RST $10 for output. RST $18 and RST $20 have vector slots reserved in the kernel, but are not yet implemented, so commands depending on them are outside the current compatibility promise.

What dot mode deliberately does not provide

While a dot command is executing, it is in a dot-compatible environment rather than the normal Spectranet module environment. Apart from the filesystem services reached through the esxDOS compatibility layer, Spectranet functions are not directly available to it. The compatible esxDOS ABI surface is still being reviewed and expanded, but a dot command should not assume it can make arbitrary Spectranet module calls.

If an application needs Spectranet-specific functions as well as its own code, it should load a TAP program and transfer execution to that program instead of trying to use them from dot mode.

Ordinary TAP programs have a different and less constrained integration path. They run in the normal Spectrum memory map, without the dot-command kernel's temporary paging arrangement. Spectranet can therefore retain esxDOS compatibility through its normal RST $08 handler while the TAP program also uses Spectranet operations. In other words: dot mode provides a carefully isolated compatibility environment; a normal TAP program can use both interfaces together.

Providing your dot commands

The standard dot commands are placed in the /bin folder. When you type a dot command, the loader resolves its name there—so .ls, for example, becomes /bin/ls.

That folder is not limited to the built-in set. Users can supply many compatible .dot programs in /bin and invoke them in the same way. The compatibility layer gives those programs the conventional command window and the esxDOS call interface; their file operations are then served by Spectranet's VFS rather than by a direct FAT implementation.

There are still compatibility boundaries: a standard command image has the usual roughly 7.5K execution budget, and not every esxDOS attribute or filesystem detail has an identical Spectranet equivalent. One useful translation is .chmod +a file: where esxDOS uses the archive attribute, Spectranet treats it as a request to commit a RAM-overlay file into flash. The familiar command remains useful, while the storage semantics remain native to Spectranet.

The aim is practical compatibility: familiar tools, familiar commands, and the storage back ends Spectranet already provides.