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:

Address

Function

Zero-Page Addresses

$0080-$0081

Used to store the 16-bit address pointer to a filename used with File I/O APIs.

$00f0-$00f1

16-bit address pointer to current data-segment

$00f2

Data segment size

$00f4

Byte holding the parameter type

$00f5-$00f6

Either a 16-bit address pointer to a string, or 16-bit integer depending on the parameter

$00fa-$00fb

Used to store a 16-bit address pointer to a Kernel API routine parameter.

$00fc-$00fd

Used to store a 16-bit address pointer to a Kernel API routine parameter.

$00ff

The result of a few Kernel API routines is stored here, such as the fexists API.

Stack segment

$0100-$01ff

Stack segment

Default data segment

$0200-$02ff

Data segment currently set by the Kernel after it finishes booting, new programs will load their data segment here.

Default code segment

$0800-$08ff

Currently 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-$e0ff

Default location of the network stack segment

$e100-$efff

Default location of remote connection stack segments

$f000-$f0ff

KERNEL.SYS Code segment

$f100-$f1ff

KERNEL.SYS Data segment

$f200-$f2ff

File system driver

$f300-$f3ff

Network driver

$f400-$f4ff

Kernel buffers and data

$f500-$f5ff

File system driver buffer page

$f600-$f7ff

2 pages Reserved for future use

$f800-$fbff

1k for player-made drivers

$fc00-$fcff

Shell program code segment

$fd00-$fdff

Shell program data segment

$fe00-$feff

Kernel system call JSR table.

Memory mapped device I/O

$ff27-$ff2a

32-bit integer containing the current time in seconds since the Epoch

$ff30-$ff34

Routine to halt the CPU

$ff70

Configures Network device's network stack segment page.

$ff71

Network connection descriptor to work with.

$ff72-$ff73

16-bit address pointer to callback function.

$ff74

Port configurations for listening sockets

$ff75

Network device control code

$ff76-$ff77

16-bit address pointer to an IP address.

$ff78

Output a RAW byte to the connected socket, or read in a RAW byte

$ff80-$ff81

16-bit address pointer of filename to read/write

$ff82

File system control code address

$ff83

File seek pointer

$ff85

File size integeter

$ff8a

Block device to read/write from.

$ff8b

Memory page to use for buffer when read/write to/from block device.

$ff8c-$ff8d

The specific block on the block device which we are going to read/write.

$ff8e

Control/Execute code to send to the block device controller to either read/write data to/from memory buffer.

$ffd0

Write a character out to the terminal.

$ffd1

Write a integer out to the terminal.

$ffd2

Write the hexadecimal representation out to the terminal.

$ffd3

Write a VT100 escape code out to the terminal.

$ffd4

Get/Set the foreground color of the terminal.

$ffd5

Get/Set the background color of the terminal.

$ffd6

Get/Set the current row of the cursor.

$ffd7

Get/Set the current col of the cursor.

$ffd9-$ffdb

Mouse button, X and Y

$ffdc

Get/Set the terminal bitset flags.

$ffdd-$ffde

16-bit address of mouse event callback.

$ffe0

Read a character from the keyboard buffer.

$fff0-$fff4

HE Internal API access

$fffe-$ffff

Address 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.