.TOS File Format – Relocations

Why programs are relocated

GEMDOS starts a program in whatever free memory it finds, so the address of its text is not known when the program is linked. The linker writes every address inside the program as an offset from the start of the text, and the relocation table lists each long that holds one. The loader adds the address it loaded the text at to each listed long. Only 32-bit values (addresses) can be relocated this way. A program with ABSFLAG not 0 has no table: it can only run at the address it was linked for.

The table

The table follows the symbol table (or the data, when there are no symbols) and runs to the end of the file.

The text and the data are one image for this purpose: an offset past the text lands in the data. The explorer reports an offset that is odd, or whose long would run past the end of the text and data, as a problem.

What the explorer shows

The relocation table node lists the first offset and the distance bytes; the Relocations table lists each relocated long with the value stored in the file, the segment and offset it points to (text + $42, data + $10, BSS + 0) and the symbol at that address if the program has one. In the disassembly an instruction that holds a relocated long carries the note reloc -> data + $10. The load address option adds its value to every relocated long, as the loader does; with the default of 0 the file is shown as stored. A relocated value that points past the end of the BSS is reported as a problem.

Not described

Known, not yet covered

• Reference: the encoding is from the FreeMiNT TOS documentation and the GNU linker code for the MiNT program format, both read through summaries. The documentation says before GEMDOS 0.15 (TOS 1.04) the relocation information was limited to 32 KB; what exactly happens then is not described. The first page read did not say whether a 0 byte ends the table; the linker code writes a long 0 at the end, which begins with that byte, and the explorer ends the table at the first 0 byte.
• Viewer: checked against an independent loader written from this description on built programs, with distances up to 2000 and every chain of 1 bytes tried; no real Atari program with a relocation table was available.

Links