Hacker's Edge Game Guide: Programming/CPU memory space

CPU memory space
Sept. 4, 2014
Last updated at Nov. 14, 2017

This is an updated guide for the new 6502 Virtual Machine CPU used in the current version of the game engine. This is going to be a introductory guide to explain the basics of the memory address space in the Virtual 6502. There will be a separate guide on the included KERNEL.SYS API calls which your code can call into.

Firstly, let me explain the concept of the zero-page or shortened as zp. This page is memory is located from $0000-$00ff. This page is very special, in that the operations required to access this memory is very minimal, as you only need to request a small 8-bit address, effectively keeping the code small, simple, and efficient when accessing this memory block. The zero-page on traditional 6502 was used to store variables for runtime, as the registers on the 6502 was very limited. Many operations can make use of this zero-page memory. This memory will have special uses in the future.

The other interesting segment of memory is the block from $ff00-$ffff, which is for memory mapped I/O devices. This is where the 6502 CPU can talk with the outside world using various devices. This segment of memory cannot be used for general purpose memory storage, if you try, it may lead to unexpected behavior and at the worsted, your program will crash. Here is a table of important addresses in the memory mapped I/O:

Zero-Page Addresses
$0080-$0081Used to store the 16-bit address pointer to a filename used with File I/O APIs.
$00f0-$00f116-bit address pointer to current data-segment
$00f2Data segment size
$00f4Byte holding the parameter type
$00f5-$00f6Either a 16-bit address pointer to a string, or 16-bit integer depending on the parameter
$00fa-$00fbUsed to store a 16-bit address pointer to a Kernel API routine parameter.
$00fc-$00fdUsed to store a 16-bit address pointer to a Kernel API routine parameter.
$00ffThe result of a few Kernel API routines is stored here, such as the fexists API.
Stack segment
$0100-$01ffStack segment
Default data segment
$0200-$02ffData segment currently set by the Kernel after it finishes booting, new programs will load their data segment here.
Default code segment
$0800-$08ffCurrently where the binary loader loads new relocatable code into, and where BOOT.SYS is initially loaded. This will change soon.
Default KERNEL.SYS memory locations / Upper memory
$e000-$e0ffDefault location of the network stack segment
$e100-$efffDefault location of remote connection stack segments
$f000-$f0ffKERNEL.SYS Code segment
$f100-$f1ffKERNEL.SYS Data segment
$f200-$f2ffFile system driver
$f300-$f3ffNetwork driver
$f400-$f4ffKernel buffers and data
$f500-$f5ffFile system driver buffer page
$f600-$f7ff2 pages Reserved for future use
$f800-$fbff1k for player-made drivers
$fc00-$fcffShell program code segment
$fd00-$fdffShell program data segment
$fe00-$feffKernel system call JSR table.
Memory mapped device I/O
$ff27-$ff2a32-bit integer containing the current time in seconds since the Epoch
$ff30-$ff34Routine to halt the CPU
$ff70Configures Network device's network stack segment page.
$ff71Network connection descriptor to work with.
$ff72-$ff7316-bit address pointer to callback function.
$ff74Port configurations for listening sockets
$ff75Network device control code
$ff76-$ff7716-bit address pointer to an IP address.
$ff78Output a RAW byte to the connected socket, or read in a RAW byte
$ff80-$ff8116-bit address pointer of filename to read/write
$ff82File system control code address
$ff83File seek pointer
$ff85File size integeter
$ff8aBlock device to read/write from.
$ff8bMemory page to use for buffer when read/write to/from block device.
$ff8c-$ff8dThe specific block on the block device which we are going to read/write.
$ff8eControl/Execute code to send to the block device controller to either read/write data to/from memory buffer.
$ffd0Write a character out to the terminal.
$ffd1Write a integer out to the terminal.
$ffd2Write the hexadecimal representation out to the terminal.
$ffd3Write a VT100 escape code out to the terminal.
$ffd4Get/Set the foreground color of the terminal.
$ffd5Get/Set the background color of the terminal.
$ffd6Get/Set the current row of the cursor.
$ffd7Get/Set the current col of the cursor.
$ffd9-$ffdbMouse button, X and Y
$ffdcGet/Set the terminal bitset flags.
$ffdd-$ffde16-bit address of mouse event callback.
$ffe0Read a character from the keyboard buffer.
$fff0-$fff4HE Internal API access
$fffe-$ffffAddress to Interrupt service request routine

This table is subject to change. Please check back on this page often, as new I/O devices are going to be added during the development cycle.

At the time of this writing, all code is actually loaded into address $0800 as it's starting address.

Hopefully this introduction was helpful, and happy coding!