.BIN File Format – Color Computer machine-language file

The machine-language file of the Tandy Color Computer and the Dragon (Disk Extended Color BASIC “BIN”)

What it is

A machine-language program for the Tandy Color Computer (and the Dragon 32 and 64, which use the same file) is stored by SAVEM on disk, or CSAVEM on tape, as a list of segments followed by an end record. LOADM (or CLOADM) copies each segment to its load address and EXEC jumps to the address in the end record. Every number is big-endian, like everything on the 6809. The file has no signature and no extension of its own: it is usually called .BIN, which hundreds of unrelated file types also use, so the explorer does not open files by that name. Instead it recognises the structure itself (below), and offers the viewer under Identify and Read as.

Segments

OffsetSizeFieldMeaning
01Preamble$00: a data segment follows
12LengthThe number of data bytes, big-endian
32Load addressWhere the first data byte goes, big-endian
5LengthDataThe bytes: code, data, or both. Nothing in the file says which

A file holds one or more segments one after the other. Segments need not be in address order and may overlap: the loader copies them in file order, so a later one wins. The explorer disassembles each segment as code at its load address and lists them in a table.

The end record

OffsetSizeFieldMeaning
01Marker$FF
12Zero$00 $00: a length of zero
32Execution addressWhere EXEC jumps to, big-endian. LOADM with an offset adds the offset to the load addresses and to this

The end record is the last five bytes of the file. The execution address is often inside the last segment but need not be (a program may start a ROM routine).

How the explorer recognises it

The viewer’s test reads the whole file and accepts it only when all of these hold: it starts with $00; every preamble has its 5 bytes and a length of at least 1; each segment’s load address plus length stays at or below $10000; the data of each segment is in the file; the segments are followed by a postamble $FF $00 $00 with its two address bytes; and the postamble ends the file exactly. The file may be at most 128 KB. Anything else (any other first byte, a trailing byte, a length that does not fit) is not read as this format.

Measured: over 30,000 files on the author’s machine (emulator sources, firmware, documents, downloads), 318 started with $00 and were at most 128 KB, and the test accepted none. No real Color Computer or Dragon machine-language file was found on this machine, so the viewer has been tried only on built files (every branch of the test) and, for the code, on the real ROMs of the Color Computer and Dragon: see the checks. The tape wrapper of CSAVEM (a file name block before the same data) and the .CAS, .DSK, .VDK, .DMK and .JVC containers are not read yet.

Options

  • Processor: MC6809 (default) or HD6309. The file does not say; with the HD6309 chosen its extra instructions decode.
  • Assembler syntax: Motorola (lda $40) or lwasm (lda <$40, lda >$1234).
  • Direct page register assumed: the high byte a direct operand names; 0 by default. The explorer does not follow TFR x,DP, so a program that changes DP shows its direct operands against the page chosen here.
  • Machine: Color Computer 1 and 2, Color Computer 3, Dragon, or none: which hardware names to use.

Names in the disassembly

An operand address that has a name is written with it. Only names read from a source are used (the sources are at the foot of this section); the Color BASIC jump table at $A000 (POLCAT, CHROUT…) and most of the direct page are not named because no readable source was found, and no Dragon ROM routine is named.

AddressNamesMachines
$FFF0–$FFFFRESERVED_VEC SWI3_VEC SWI2_VEC FIRQ_VEC IRQ_VEC SWI_VEC NMI_VEC RESET_VECall
$FF00–$FF03PIA0_PA PIA0_CRA PIA0_PB PIA0_CRB: the first MC6821 (keyboard, joystick comparator, sync interrupts)all
$FF20–$FF23PIA1_PA PIA1_CRA PIA1_PB PIA1_CRB: the second MC6821 (cassette, six-bit DAC, serial, VDG mode)all
$FFC0–$FFDFSAM_V0_CLR SAM_V0_SET … SAM_TY_CLR SAM_TY_SET: the MC6883 (display mode V0–V2, display offset F0–F6, P1, CPU rate R0–R1, memory size M0–M1, map type TY), one bit per address pair: a write to the even address clears it and to the odd one sets itall
$FF90–$FFBFINIT0 INIT1 IRQENR FIRQENR TIMER_MSB TIMER_LSB VMODE VRES BRDR VSC VOFFSET_MSB VOFFSET_LSB HOFFSET MMU_T0_0…MMU_T1_7 PALETTE_0…PALETTE_15: the CoCo 3’s GIMEColor Computer 3
$19–$28TXTTAB VARTAB ARYTAB ARYEND FRETOP STRTAB FRESPC MEMSIZ: Color BASIC’s pointersColor Computer
$A027 …RESVEC BAWMST BFRQSV PUTCHR KEYIN CLS BIRQSV: seven Color BASIC routinesColor Computer

Sources: the Color Computer memory map on exileinparadise.com (vectors, BASIC pointers and routines), the CoCo 3 GIME register reference (GIME names), and the Color Computer Technical Reference Manual (SAM and PIA). The port and bit names of the PIA registers beyond “data or direction” and “control” are not named.

How this was checked

  • Built files: one, three and many segments; an execution address outside the segments; overlapping segments; every way the structure test must refuse a file (a trailing byte, no postamble, a cut postamble, a segment past $FFFF, length 0, a wrong marker, a length that is too long or too short, an empty file); the processor, syntax, direct page and machine choices.
  • Scan of 30,000 files: none accepted (above).
  • Real code: the Color Computer and Dragon ROMs in emulators.org were run on a 6809 core, 1,200,000 instructions in all, and every instruction was decoded by the same decoder first: the length, the branch targets and the registers written agree with the core every time.

Not described

  • The tape format of CSAVEM and the disk, tape and container images (.CAS, .DSK, .VDK, .DMK, .JVC), and the Disk Extended Color BASIC directory and granules.
  • Which bytes are code and which are data: every byte of a segment is shown as code; the disassembly does not follow jumps.
  • The OS-9 and FLEX executable formats, which are different files.

Links

Reference