.TOS File Format

Introduction

An Atari ST, TT or Falcon program is a GEMDOS executable. Its file name ends in .PRG (a program that uses the desktop’s windows), .TOS (a text program), .TTP (a text program that asks for a command line first), .APP (a GEM application), .ACC (a desk accessory) or .GTP (a GEM program that asks for a command line). The file is a 28-byte header, the text (code) and data, an optional symbol table, and a relocation table that lists the longs holding an address, so GEMDOS can start the program wherever it finds free memory. Every number is big-endian, as on the 68000, and the code is for the Motorola 68000 family: a 68000 in the ST and STE, a 68030 in the TT and Falcon.

The explorer recognises the file by its first word, $601A, and by header sizes that fit the file’s length. The extension .PRG is also the Commodore 64 program (.PRG), whose first two bytes are its load address, so an extension cannot decide; the sizes can. A C64 program that happens to load at $1A60 starts with the same two bytes, but the next ten bytes then have to read as four sizes that fit the file, which almost never happens.

Structure

The program header page lists every field and the program flags. Relocations explains the table and how the viewer applies a load address. Symbols covers the 14-byte entries and the long names. System calls lists how the explorer names GEMDOS, BIOS and XBIOS calls, AES and VDI calls and Line-A opcodes, and memory map the hardware registers it names.

What the explorer shows

• The header field by field, the flags decoded, the segments with their sizes, and the memory the program needs.
• The relocation table decoded to a list of relocated longs, each with the segment and offset it points to.
• The symbol table as labels in the disassembly.
• The text disassembled with the 68000-family decoder (68000 by default; 68010 to 68060 as an option), each relocated long marked, and notes on system calls and hardware addresses.
• A load address option (0 by default): every relocated long is increased by it, as the loader does.

Not described

Known, not yet covered

• Reference: the layouts come from third-party descriptions (the FreeMiNT TOS documentation and the GNU linker code for the MiNT program format); the fetch tool that read the web pages returns summaries, so the layouts rest on those summaries. Not covered: the exact way GEMDOS places the text after the base page and clears the BSS (the pages read did not say), the Pure C and GNU symbol formats, the MiNT extended header (the “MiNT” signature after the sizes), shared-library programs, and the original Atari GEMDOS manual (its text could not be read).
• Viewer: checked on programs built by a program written from this description, an independent loader of the relocation table, and the recognition of 55 real C64 programs; no real Atari program was found on this machine, so no symbol table, relocation table or instruction sequence from a real Atari program has been checked. It decodes every even address of the text as an instruction (code and data are not told apart), does not decode the data segment, and names a GEMDOS call only when the instruction just before the TRAP pushes the number as an immediate word. It has not been run in a browser by its author.

Links