Memory and layouts

This page shows where the code, data and stacks of a program are in the 64 KiB of the //e. It tells how to select and change a linker layout, and how to read the memory report of the build. It also gives the cost of each part of the library.

Main memory

The two shared layouts

The two layouts make a raw ProDOS SYS file that ProDOS loads and starts at $2000. They link with the cc65 none.lib and the startup code of the project. A manifest selects one layout with config.

In cfg/game.cfg, startup copies the low segments one time from the end of the loaded image into $0800-$1FFF. It does this before it clears BSS. The code that runs one time at entry is in the ONCE segment. This layout puts ONCE at the addresses of BSS, so the clear of BSS makes these bytes available again. For the near-pointer checks, low memory is read-only.

A layout of your own

A game can link with its own copy of a layout file. Then it can use the memory that the library does not need. STARFALL makes no file calls. Thus examples/starfall/starfall.cfg does not define _ti_file_buffer.

That layout sets the end of WORK and of writable near memory, _ti_memory_end, to $B400. In the shared layouts this end is $AF00. Thus the guard page and the buffer give 1,280 more bytes of game memory. In that game, a file call does not link, so ProDOS cannot write over its variables.

Keep the checks of the build. The build rejects each segment outside the areas that the symbols of a layout give.

Read the memory report

starfall memory: LOW $0800-$1FFF 88 free; IMAGE $2000-$BEFF 1032 free; WORK $A26C-$B3FF 1110 free; NEAR $B480-$B6FF 1 free
starter memory: MAIN $2000-$9FFF 12321 free; NEAR $A900-$AEFF 1532 free

Each entry is a linker memory area with its free bytes. build/memory.json gives the same values and the used bytes for each program. When a segment does not fit, the build stops and gives the missing bytes:

starfall does not fit: segment BSS needs 50 more bytes in memory area WORK

IMAGE is the load image. It also holds the low segments until startup copies them. Thus its free bytes show how much more the SYS file can hold. WORK holds BSS while the program runs.

The near arena

Variables in the NEARBSS segment are in the near arena of the layout, outside the main area of the program. Startup sets them to zero, as for BSS. The linker rejects more data than the arena holds. All near API calls accept pointers into the arena. The library puts no data there.

#pragma bss-name (push, "NEARBSS")
static uint8_t level[512];
static uint16_t palette[16];
#pragma bss-name (pop)

STARFALL keeps its 547-byte simulation state, star columns, animated palette and two text buffers there. They use 639 of the 640 bytes.

Where code and data go

cc65 puts code in CODE, constants in RODATA, initialized variables in DATA and the other variables in BSS. Pragmas move a part of a file to a different segment:

/* Code that runs rarely, into low memory, in the full-game layout. */
#pragma code-name (push, "LOWCODE")
static void title_option(void) { /* ... */ }
#pragma code-name (pop)

/* Keep the constants of this file in main memory, where space is available. */
#pragma rodata-name (push, "CODE")
static const uint8_t table[64] = { /* ... */ };
#pragma rodata-name (pop)

Do not put code that runs after startup in ONCE. Use OSSTATE only for the startup code.

Auxiliary memory and banks

A resource continues from $BFFF of one granted bank to $0200 of the next bank. While auxiliary reads are mapped, only the page-one trampoline runs. Main memory and selector 0 come back before C code or interrupts continue. A grant of all selectors 1-126 gives 6,128,640 resource bytes.

The cost of each part of the library

A program links an archive member only when it uses one of its symbols. These sizes come from the CPU-only build. For your program, read build/<game>.map.

The startup code adds 563 bytes. This includes 228 bytes of entry code, which the full-game layout uses again for BSS, and 98 bytes of saved OS state. The cc65 runtime routines that the program uses are added to this.

Save memory and time with cc65

• Foreground code that does not call itself can use --static-locals in the cflags of the manifest, as STARFALL does. This removes most C stack operations.
• Keep pools as parallel byte arrays (enemy_x[i], enemy_y[i]), not as arrays of structures. The 65C02 indexes each array with one absolute,Y operand.
• Do not use 32-bit arithmetic in loops. For this reason, the library uses 16-bit arithmetic in its checks.
• The library gives memory a higher priority than speed, because each game pays for its bytes. A game can use its own memory to get more speed.