What's up with the ASxxx and the "CoCo Disk BASIC binary format"?

Question

The ASxxxx assembler system is a multi-platform assembler that supports a lot of different CPUs, including Z80, 6800, 6502, 6809, etc. I'm intending to use it to build software for a variety of popular retrocomputing platforms based on these CPUs.

Its linker, ASlink, supports three basic output formats. Intel HEX and Motorola S-record are ASCII formats that are both well known and documented (if slightly informal) standards.

The linker's one binary output format is "Tandy Color Computer Disk BASIC binary format" This format, while simple, seems obscure; the only documentation I've ever been able to find for it, outside of the ASlink documentation itself, is in a book that reverse-engineered the ROMs in the CoCo disk controller, Disk Basic Unravelled II (p.17).

The format itself is record-based, with two types of records, distinguished by the first byte:

• 00 l₁ l₀ a₁ a₀: A record with data of length l₁ * 256 + l₀, starting at address a₁ * 256 + a₀. The data follow this header.
• FF 00 00 a₁ a₀: End record, with a₁ * 256 + a₀ giving the entry point of the program.

For other binary formats, even simpler and more popular ones such as the "two byte location header followed by data" used by Commodore, others, or even just a raw binary dump, the developer seems expected to provide a program to convert one of the three formats above. (One such program for OS-9 is provided with ASxxxx; it reads the S-record output format.)

So my actual questions are:

1. Is this format really used only by to ASxxxx and CoCo Disk BASIC, or is it actually a format that's been used elsewhere under different names?
2. What tools, outside of custom-written ones, are avilable for manipulating this format and converting it to other formats used by popular retrocomputing platforms?
3. It seems unlikely that, of all the hundreds of platforms for which this suite of assemblers could be used, a particular output format for only one not-particularly-popular (relatively) computer would be added. Are there non-platform-specific general technical reasons why this output format would be chosen? What are similar alternative formats that might have been considered, and how do they compare?

Answer 1

The original assembler released on the CUG volume 292 (see here for the files in that volume) had support for only the Intel Hex and Motorola S19 output formats. Support for the CoCo format was added in 2006 with version 4.10 of the project:

Summary of changes/additions to the ASxxxx Assemblers from Version 4.00 to Version 4.10:
     * Added support for the Tandy Color Computer Disc Basic binary file format to ASLINK.
     * Other irrelevant stuff.

That's a little late (about 15 years too late) for someone buying a new CoCo and wanting support, so it's far more likely that this was a retro-computing desire. Unfortunately, there are no comments in the code or documentation that state why a change was made, just that it was made.

So we're unfortunately reduced to supposition⁽¹⁾, such as the possibility that the author or some other interested party got their hands on a retro CoCo at some point and wanted to use the assembler to directly create the CoCo Disk BASIC format files that could be simply dropped onto a disk and run without any issue.

The format exactly matches that specified for Disk BASIC (shown here, for example):

Header record:
  Offset  Length  Description
       0       1  Value of zero indicating header.
       1       2  Length in bytes of data (n).
       3       2  Load address of data.
       5       n  Data.
Tail record:
  Offset  Length  Description
       0       1  Value of 0xff indicating tail.
       1       2  Always zero.
       3       2  Execution address.

This bears little relationship to the cassette-based format (other than the existence of blocks with specific identifiers but that's probably the case for most possible formats). The cassette format has the addresses encoded as part of the initial name-file block, before any of the data blocks begin (see here).

It's a little more similar to the scheme used in TRS-DOS for the CMD file format as can be seen here:

A CMD File is set up with a record type header
followed by data. The record type header does
not need to be in any particular order, so the
order below isn’t necessarily dispositive:

Record Type 5 – Filename
   05 nn ...
      nn is length of the filename block followed
         by the applicable data.

Record Type 1 – Object Code / Load Block
   01 nn xx yy zz ...`
      nn is 0..2, meaning that there will
         be (nn + 254) data bytes.
      xx/yy is the address where to put the data.
      zz are the data bytes.

Record Type 2 – Transfer Address
   02 nn xx yy zz ...
      nn is length of the block following the
         address (always zero?).
      xx/yy is the address to start executing
         code at.

So, in answer to your specific questions:

1. It seems to be specific to CoCo Disk BASIC. The source code uses db prefixes for functions and data related to that output format and I assume that stands for (d)isk (b)asic. I've done a fair bit of embedded stuff in my long career and never seen it elsewhere. However, that doesn't preclude the existence of use elsewhere.

2. Honestly, for a format that simple, the only tool you need is a scripting language like Python that's capable of working with bytes.

3. See the body of my answer above, maybe the author picked up a CoCo at some garage sale and just fell in love with it⁽²⁾. It does have several advantages over the other two formats:

   • It allows for much larger data blocks than the 256-odd bytes allowed in Intel Hex and S19. This would provide some saving, given you can reduce the overhead bytes with larger blocks.
   • It gives you a file you can just write directly on to a CoCo disk and have it magically run without some external loader for the other two formats.
   • Since it's binary, it doesn't bloat the data stream like the other two formats. They encode each 8-bit value as two hex characters (each of which is itself an eight-bit value, hence twice the size).

---

⁽¹⁾ As an aside, I had actually reached out to the author to hopefully gain some more "straight from the horses mouth" information.

And, as promised, Alec Baldwin (the author) has kindly gotten back to me with a more definitive explanation, specifically:

A long time ago I was approached by Boisy Pitre who was disassembling the NitrOS-9 operating system for the Tandy CoCo.

Boisy had previously offered some major enhancements to the conditional handling in the ASxxxx assemblers and sent me some code to add the CoCo Disk Basic as an alternate to Intel and Motorola formats.

I got the impression he was using AS6809 in the process to disassemble and reassemble the operating system code. So the code was added and thus remains a part of the assemblers.

Until recently I was unaware of his prolific publishing history.

So it appears that my suggestion, "it's far more likely that this was a retro-computing desire" may have been closer to the mark than I imagined. Especially if you look at the rather large number of retro-computing projects Boisy has been involved in.

---

⁽²⁾ I'm sure none of us here have felt that experience :-)