Next Previous Contents

9. Other hints

9.1 Function keys

Function keys are mapped to Atari + number key.

9.2 Passing arguments to the program

Command line arguments can be passed to main() when DOS supports it.

  1. Arguments are separated by spaces.
  2. Leading and trailing spaces around an argument are ignored.
  3. The first argument passed to main is the program name.
  4. A maximum number of 16 arguments (including the program name) are supported.

9.3 Interrupts

The runtime for the Atari uses routines marked as .INTERRUPTOR for interrupt handlers. Such routines must be written as simple machine language subroutines and will be called automatically by the VBI handler code when they are linked into a program. See the discussion of the .CONDES feature in the assembler manual.

9.4 Reserving a memory area inside a program

The Atari 130XE maps its additional memory into CPU memory in 16K chunks at address $4000 to $7FFF. One might want to prevent this memory area from being used by cc65. Other reasons to prevent the use of some memory area could be to reserve space for the buffers for display lists and screen memory.

The Atari executable format allows holes inside a program, e.g. one part loads into $2E00 to $3FFF, going below the reserved memory area (assuming a reserved area from $4000 to $7FFF), and another part loads into $8000 to $BC1F.

Each load chunk of the executable starts with a 4 byte header which defines its load address and size. In the following linker scripts these headers are named HEADER and SECHDR (for the MEMORY layout), and accordingly NEXEHDR and CHKHDR (for the SEGMENTS layout).

Low code and high data example

Goal: Create an executable with 2 load chunks which doesn't use the memory area from $4000 to $7FFF. The CODE segment of the program should go below $4000 and the DATA and RODATA segments should go above $7FFF.

The main problem is that the EXE header generated by the cc65 runtime lib is wrong. It defines a single load chunk with the sizes/addresses of the STARTUP, LOWCODE, INIT, CODE, RODATA, and DATA segments (the whole user program).

The contents of the EXE header come from the EXEHDR segment, which is defined in crt0.s. This cannot be changed without modifying and recompiling the cc65 atari runtime lib. Therefore the original EXE header must be discarded. It will be replaced by a user created one. The discarding is done by assigning the EXEHDR segment to the BANK memory area. The BANK memory area is discarded in the new linker script (written to file "").

The user needs to create a customized linker config file which adds new memory areas and segments to hold the new EXE header and the header data for the second load chunk. Also an assembly source file needs to be created which defines the contents of the new EXE header and the second load chunk header.

This is an example of a modified cc65 Atari linker configuration file (split.cfg):

SYMBOLS {
    __STACKSIZE__ = $800;                               # 2K stack
    __RESERVED_MEMORY__: value = $0000, weak = yes;
}
FEATURES {
    STARTADDRESS: default = $2E00;
}
MEMORY {
    ZP: start = $82, size = $7E, type = rw, define = yes;

    HEADER: start = $0000, size = $6, file = %O;        # first load chunk
    RAMLO: start = %S, size = $4000 - %S, file = %O;

    BANK: start = $4000, size = $4000, file = "";

    SECHDR: start = $0000, size = $4, file = %O;        # second load chunk
    RAM: start = $8000, size = $3C20, file = %O;        # $3C20: matches upper bound $BC1F
}
SEGMENTS {
    EXEHDR: load = BANK, type = ro;

    NEXEHDR: load = HEADER, type = ro;                  # first load chunk
    STARTUP: load = RAMLO, type = ro, define = yes;
    LOWCODE: load = RAMLO, type = ro, define = yes, optional = yes;
    INIT: load = RAMLO, type = ro, optional = yes;
    CODE: load = RAMLO, type = ro, define = yes;

    CHKHDR: load = SECHDR, type = ro;                   # second load chunk
    RODATA: load = RAM, type = ro, define = yes;
    DATA: load = RAM, type = rw, define = yes;
    BSS: load = RAM, type = bss, define = yes;
    ZPSAVE: load = RAM, type = bss, define = yes;

    ZEROPAGE: load = ZP, type = zp;
    AUTOSTRT: load = RAM, type = ro;                    # defines program entry point
}
FEATURES {
    CONDES: segment = RODATA,
            type = constructor,
            label = __CONSTRUCTOR_TABLE__,
            count = __CONSTRUCTOR_COUNT__;
    CONDES: segment = RODATA,
            type = destructor,
            label = __DESTRUCTOR_TABLE__,
            count = __DESTRUCTOR_COUNT__;
}

A new memory area BANK was added which describes the reserved area. It gets loaded with the contents of the old EXEHDR segment. But the memory area isn't written to the output file. This way the contents of the EXEHDR segment get discarded.

The newly added NEXEHDR segment defines the correct EXE header. It puts the STARTUP, LOWCODE, INIT, and CODE segments, which are the segments containing only code, into load chunk #1 (RAMLO memory area).

The header for the second load chunk comes from the new CHKHDR segment. It puts the RODATA, DATA, BSS, and ZPSAVE segments into load chunk #2 (RAM memory area).

The contents of the new NEXEHDR and CHKHDR segments come from this file (split.s):

        .import __CODE_LOAD__, __BSS_LOAD__, __CODE_SIZE__
        .import __DATA_LOAD__, __RODATA_LOAD__, __STARTUP_LOAD__

        .segment "NEXEHDR"
        .word    $FFFF
        .word    __STARTUP_LOAD__
        .word    __CODE_LOAD__ + __CODE_SIZE__ - 1

        .segment "CHKHDR"
        .word    __RODATA_LOAD__
        .word    __BSS_LOAD__ - 1

Compile with

cl65 -t atari -C split.cfg -o prog.com prog.c split.s

Low data and high code example

Goal: Put RODATA and DATA into low memory and STARTUP, LOWCODE, INIT, CODE, BSS, ZPSAVE into high memory (split2.cfg):

SYMBOLS {
    __STACKSIZE__ = $800;       # 2K stack
    __RESERVED_MEMORY__: value = $0000, weak = yes;
}
FEATURES {
    STARTADDRESS: default = $2E00;
}
MEMORY {
    ZP: start = $82, size = $7E, type = rw, define = yes;

    HEADER: start = $0000, size = $6, file = %O;        # first load chunk
    RAMLO: start = %S, size = $4000 - %S, file = %O;

    BANK: start = $4000, size = $4000, file = "";

    SECHDR: start = $0000, size = $4, file = %O;        # second load chunk
    RAM: start = $8000, size = $3C20, file = %O;        # $3C20: matches upper bound $BC1F
}
SEGMENTS {
    EXEHDR: load = BANK, type = ro;                     # discarded old EXE header

    NEXEHDR: load = HEADER, type = ro;                  # first load chunk
    RODATA: load = RAMLO, type = ro, define = yes;
    DATA: load = RAMLO, type = rw, define = yes;

    CHKHDR: load = SECHDR, type = ro;                   # second load chunk
    STARTUP: load = RAM, type = ro, define = yes;
    INIT: load = RAM, type = ro, optional = yes;
    CODE: load = RAM, type = ro, define = yes;
    ZPSAVE: load = RAM, type = bss, define = yes;
    BSS: load = RAM, type = bss, define = yes;

    ZEROPAGE: load = ZP, type = zp;
    AUTOSTRT: load = RAM, type = ro;                    # defines program entry point
}
FEATURES {
    CONDES: segment = RODATA,
            type = constructor,
            label = __CONSTRUCTOR_TABLE__,
            count = __CONSTRUCTOR_COUNT__;
    CONDES: segment = RODATA,
            type = destructor,
            label = __DESTRUCTOR_TABLE__,
            count = __DESTRUCTOR_COUNT__;
}

New contents for NEXEHDR and CHKHDR are needed (split2.s):

        .import __STARTUP_LOAD__, __ZPSAVE_LOAD__, __DATA_SIZE__
        .import __DATA_LOAD__, __RODATA_LOAD__

        .segment "NEXEHDR"
        .word    $FFFF
        .word    __RODATA_LOAD__
        .word    __DATA_LOAD__ + __DATA_SIZE__ - 1

        .segment "CHKHDR"
        .word    __STARTUP_LOAD__
        .word    __ZPSAVE_LOAD__ - 1

Compile with

cl65 -t atari -C split2.cfg -o prog.com prog.c split2.s

Final note

There are two other memory areas which don't appear directly in the linker script. They are the stack and the heap.

The cc65 runtime lib places the stack location at the end of available memory. This is dynamically set from the MEMTOP system variable at startup. The heap is located in the area between the end of the BSS segment and the top of the stack as defined by __STACKSIZE__.

If BSS and/or the stack shouldn't stay at the end of the program, some parts of the cc65 runtime lib need to be replaced/modified.

common/_heap.s defines the location of the heap and atari/crt0.s defines the location of the stack by initializing sp.


Next Previous Contents