prog8/docs/system.md

System documentation: memory model and CPU

Memory address space layout

The 6502 CPU can directly address 64 kilobyte of memory. Most of the 64 kilobyte address space can be used by IL65 programs.

type	memory area	note
ZeroPage	$00 - $ff	contains many sensitive system variables
Hardware stack	$100 - $1ff	is used by the CPU and should normally not be accessed directly
Free RAM or ROM	$0200 - $ffff	free to use memory area, often a mix of RAM and ROM

A few memory addresses are reserved and cannot be used, because they have a special hardware function, or are reserved for internal use in the code generated by the compiler:

reserved address	in use for
$00	data direction (hw)
$01	bank select (hw)
$02	IL65 scratch var
$03	IL65 scratch var
$fb-$fc	IL65 scratch var
$fd-$fe	IL65 scratch var
$fffa-$fffb	NMI vector (hw)
$fffc-$fffd	RESET vector (hw)
$fffe-$ffff	IRQ vector (hw)

A particular 6502/6510 based machine such as the Commodore-64 will have many other special addresses as well:

• ROMs installed in the machine (BASIC, kernal and character roms)
• memory-mapped I/O registers (for the video and sound chip for example)
• RAM areas used for screen graphics and sprite data

Directly Usable CPU Registers

The following 6502 CPU hardware registers are directly usable in program code (and are reserved symbols):

• A, X, Y the A, X and Y cpu registers (8 bits)
• AX, AY, XY surrogate 16-bit registers: LSB-order (lo/hi) combined register pairs
• SC status register's Carry flag
• SI status register's Interrupt Disable flag

The other status bits of the status register are not directly accessible, but can be acted upon via conditional statements. The stack pointer and program counter registers are not accessible.

ZeroPage ("ZP")

The ZP addresses $02 - $ff can be regarded as 254 other 'registers', because they take less clock cycles to access and need fewer instruction bytes than access to other memory locations. Theoretically you can use all of them in a program but there are a few limitations:

• several addresses ($02, $03, $fb - $fc, $fd - $fe) are reserved for internal use as scratch registers by IL65
• most other addresses often are in use by the machine's operating system or kernal, and overwriting them can crash the machine. The program must take over the entire system to be able to safely use all ZP addresses. This means it can no longer use most BASIC and kernal routines.
• it's often more convenient to let IL65 allocate the particular addresses for you and just use symbolic names in the code.

For the Commodore-64 here is a list of free-to-use ZP addresses even when its BASIC and KERNAL are active:

$02; $03; $04; $05; $06; $2a; $52; $f7 - $f8; $f9 - $fa; $fb - $fc; $fd - $fe

The six reserved addresses mentioned above are subtracted from this set, leaving you with just five 1-byte and two 2-byte usable ZP 'registers'. IL65 knows about all this: it will use the above ZP addresses to place its ZP variables in, until they're all used up. You can instruct it to output a program that takes over the entire machine, in which case (almost) all of the ZP addresses are suddenly available for variables. IL65 can also generate a special routine that saves and restores the ZP to let the program run and return safely back to the system afterwards - you don't have to take care of that yourself.

IRQs and the ZeroPage:

The normal IRQ routine in the C-64's kernal will read and write several addresses in the ZP (such as the system's software jiffy clock which sits in $a0 - $a2):

$a0 - $a2; $91; $c0; $c5; $cb; $f5 - $f6

These addresses will never be used by the compiler for ZP variables, so variables will not interfere with the IRQ routine and vice versa. This is tru for the normal zp mode but also for the mode where the whole ZP has been taken over. So the normal IRQ vector is still running when the program is entered!

ZeroPage handling in programs

The global %zp directive can be used to specify the way the compiler will treat the ZP for the program. The default is compatible, where most of the ZP is considered a no-go zone by the compiler.

• compatible : only use the few 'free' addresses in the ZP, and don't change anything else. This allows full use of BASIC and KERNAL ROM routines including default IRQs during normal system operation.
• full : claim the whole ZP for variables for the program, overwriting everything, except the few addresses mentioned above that are used by the system's IRQ routine. Even though the default IRQ routine is still active, it is impossible to use most BASIC and KERNAL ROM routines. This includes many floating point operations and several utility routines that do I/O, such as print_string. It is also not possible to cleanly exit the program, other than resetting the machine. This option makes programs smaller and faster because many more variables can be stored in the ZP, which is more efficient.
• full-restore : like full, but makes a backup copy of the original values at program start. These are restored (except for the software jiffy clock in $a0 - $a2) when the program exits, and allows it to exit back to the BASIC prompt.

Subroutine Calling Conventions

Subroutine arguments and results are passed via registers (and sometimes implicitly via certain memory locations).
@todo support call non-register args (variable parameter passing)

In IL65 the "caller saves" principle applies to registers used in a subroutine. This means the code that calls a subroutine or performs some function that clobber certain registers (A, X or Y), is responsible for storing and restoring the original values if that is required.

You should assume that the 3 hardware registers A, X and Y are volatile and their contents cannot be depended upon, unless you make sure otherwise.

Normally, the registers are NOT preserved when calling a subroutine or when a certian operations are performed. Most calls will be simply a few instructions to load the values in the registers and then a JSR or JMP.

By using the %saveregisters directive in a block, you can tell the compiler to preserve all registers. This does generate a lot of extra code that puts original values on the stack and gets them off the stack again once the subroutine is done. In this case however you don't have to worry about A, X and Y losing their original values and you can essentially treat them as three local variables instead of scratch data.

You can also use a ! on a single subroutine call to preserve register values, instead of setting this behavior for the entire block.