| .. | ||
| src | ||
| README.md | ||
#PLASMA ##Introduction
PLASMA is a combination of virtual machine and assembler/compiler matched closely to the 6502 architecture. It is an attempt to satisfy a few challenges surrounding code size, efficient execution, small runtime and fast just-in-time compilation. By architecting a unique bytecode that maps nearly one-to-one to the higher level representation, the compiler/assembler can be very simple and execute quickly on the Apple II for a self-hosted environment. A modular approach provides for incremental development and code reuse. Different projects have led to the architecture of PLASMA, most notably Apple Pascal, FORTH, and my own Java VM for the 6502, VM02. Each has tried to map a generic VM to the 6502 with varying levels of success. Apple Pascal, based on the USCD Pascal using the p-code interpreter, was a very powerful system and ran fast enough on the Apple II to be interactive but didn't win any speed contests. FORTH was the poster child for efficiency and obtuse syntax. Commonly referred to as a write only language, it was difficult to come up to speed as a developer, especially when using other's code. My own project in creating a Java VM for the Apple II uncovered the folly of shoehorning a large system into something never intended to run 32 bit applications.
##Low Level Implementation
Both the Pascal and Java VMs used a bytecode to hide the underlying CPU architecture and offer platform agnostic application execution. The application and tool chains were easily moved from platform to platform by simply writing a bytecode interpreter and small runtime to translate the higher level constructs to the underlying hardware. The performance of the system was dependent on the actual hardware and efficiency of the interpreter. Just-in-time compilation wasn't really an option on small, 8 bit systems. FORTH, on the other hand, was usually implemented as a threaded interpreter. A threaded interpreter will use the address of functions to call as the code stream instead of a bytecode, eliminating one level of indirection with a slight increase in code size. The threaded approach can be made faster at the expense of another slight increase in size by inserting an actual Jump SubRoutine opcode before each address, thus removing the interpreter's inner loop altogether.
All three systems were implemented using stack architecture. Pascal and Java were meant to be compiled high level languages, using a stack machine as a simple compilation target. FORTH was meant to be written directly as a stack oriented language, similar to RPN on HP calculators. The 6502 is a challenging target due to it's unusual architecture so writing a bytecode interpreter for Pascal and Java results in some inefficiencies and limitations. FORTH's inner interpreter loop on the 6502 tends to be less efficient than most other CPUs. Another difference is how each system creates and manipulates it's stack. Pascal and Java use the 6502 hardware stack for all stack operations. Unfortunately the 6502 stack is hard-limited to 256 bytes. However, in normal usage this isn't too much of a problem as the compilers don't put undue pressure on the stack size by keeping most values in global or local variables. FORTH creates a small stack using a portion of the 6502's zero page, a 256 byte area of low memory that can be accessed with only a byte address and indexed using either of the X or Y registers. With zero page, the X register can be used as an indexed, indirect address and the Y register can be used as an indirect, indexed address.
##A New Approach
PLASMA takes an approach that uses the best of all the above implementations to create a unique, powerful and efficient platform for developing new applications on the Apple II. One goal was to create a very small VM runtime, bytecode interpreter, and module loader. The decision was made early on to implement a stack based architecture duplicating the approach taken by FORTH. Space in the zero page would be assigned to a 16 bit, 16 element evaluation stack, indexed by the X register.
A simple compiler was written so that higher level constructs could be used and global/local variables would hold values instead of using clever stack manipulation. Function/procedure frames would allow for local variables, but with a limitation - the frame could be no larger than 256 bytes. By enforcing this limitation, the function frame could easily be accessed through a frame pointer value in zero page, indexed by the Y register. The call stack uses the 6502's hardware stack resulting in the same 256 byte limitation imposed by the hardware. However, this limitation could be lifted by extending the call sequence to save and restore the return address in the function frame. This was not done initially for performance reasons and simplicity of implementation. Even with these limitations, recursive functions can be effectively implemented.
One of the goals of PLASMA was to allow for intermixing of functions implemented as bytecode, or native code. Taking a page from the FORTH play book, a function call is implemented as a native subroutine call to an address. If the function is in bytecode, the first thing it does is call back into the interpreter to execute the following bytecode (or a pointer to the bytecode). Function call parameters are pushed onto the evaluation stack in order they are written. The first operation inside of the function call is to pull the parameters off the evaluation stack and put them in local frame storage. Function callers and callees must agree on the number of parameters to avoid stack underflow/overflow. All functions return a value on the evaluation stack regardless of it being used or not.
The bytecode interpreter is capable of executing code in main memory or banked memory, increasing the available code space and relieving pressure on the limited 48K of data memory. In the Apple IIe with 64K expansion card, the IIc, and the IIgs, there is an auxilliary memory that swaps in and out for the main memory in chunks. The interpreter resides in the Language Card memory area that can easily swap in and out the $0200 to $BFFF memory bank. The module loader will move the bytecode into the auxilliary memory and fix up the entrypoints to reflect the bytecode location.
Lastly, PLASMA is not a typed language. Just like assembly, any value can represent a character, integer, or address. It's the programmer's job to know the type. Only bytes and words are known to PLASMA. Bytes are unsigned 8 bit quantities, words are signed 16 bit quantities. All stack operations involve 16 bits of precision.
The PLASMA low level operations are defined as:
| OPCODE | Description |
|---|---|
| ZERO | push zero on the stack |
| ADD | add top two values, leave result on top |
| SUB | subtract next from top from top, leave result on top |
| MUL | multiply two topmost stack values, leave result on top |
| DIV | divide next from top by top, leave result on top |
| MOD | divide next from top by top, leave remainder on top |
| INCR | increment top of stack |
| DECR | decrement top of stack |
| NEG | negate top of stack |
| COMP | compliment top of stack |
| AND | bit wise AND top two values, leave result on top |
| IOR | bit wise inclusive OR top two values, leave result on top |
| XOR | bit wise exclusive OR top two values, leave result on top |
| LOR | logical OR top two values, leave result on top |
| LAND | logical AND top two values, leave result on top |
| SHL | shift left next from top by top, leave result on top |
| SHR | shift right next from top by top, leave result on top |
| IDXB | add top of stack to next from top, leave result on top (ADD) |
| IDXW | add 2X top of stack to next from top, leave result on top |
| NOT | logical NOT of top of stack |
| LA | load address |
| LLA | load local address from frame offset |
| CB | constant byte |
| CW | constant word |
| SWAP | swap two topmost stack values |
| DROP | drop top stack value |
| DUP | duplicate top stack value |
| PUSH | push top to call stack |
| PULL | pull from call stack |
| BRGT | branch next from top greater than top |
| BRLT | branch next from top less than top |
| BREQ | branch next from top equal to top |
| BRNE | branch next from top not equal to top |
| ISEQ | if next from top is equal to top, set top true |
| ISNE | if next from top is not equal to top, set top true |
| ISGT | if next from top is greater than top, set top true |
| ISLT | if next from top is less than top, set top true |
| ISGE | if next from top is greater than or equal to top, set top true |
| ISLE | if next from top is less than or equal to top, set top true |
| BRFLS | branch if top of stack is zero |
| BRTRU | branch if top of stack is non-zero |
| BRNCH | branch to address |
| CALL | sub routine call with stack parameters |
| ICAL | sub routine call to indirect address on stack top with stack parameters |
| ENTER | allocate frame size and copy stack parameters to local frame |
| LEAVE | deallocate frame and return from sub routine call |
| RET | return from sub routine call |
| LB | load byte from top of stack address |
| LW | load word from top of stack address |
| LLB | load byte from frame offset |
| LLW | load word from frame offset |
| LAB | load byte from absolute address |
| LAW | load word from absolute address |
| SB | store top of stack byte into next from top address |
| SW | store top of stack word into next from top address |
| SLB | store top of stack into local byte at frame offset |
| SLW | store top of stack into local word at frame offset |
| SAB | store top of stack into byte at absolute address |
| SAW | store top of stack into word at absolute address |
| DLB | duplicate top of stack into local byte at frame offset |
| DLW | duplicate top of stack into local word at frame offset |
| DAB | duplicate top of stack into byte at absolute address |
| DAW | duplicate top of stack into word at absolute address |
##PLASMA Compiler/Assembler
Although the low-level operations could easily by coded by hand, they were chosen to be an easy target for a simple compiler. Think along the lines of an advanced assembler or stripped down C compiler ( C--). Taking concepts from BASIC, Pascal, C and assembler, the PLASMA compiler is simple yet expressive. The syntax is line oriented. However, the ';' character can seperate multiple statements on a single line. It is generally considered bad form to have multiple statements per line unless they are very short.
Comments are allowed throughout the source, starting with the ‘//’ symbol. The rest of the line is ignored.
// Data and text buffer constants
Hexadecimal constants are preceded with a ‘$’ to identify them as such.
$C030 // Speaker address
###Constants, Variables and Functions
The source code of a PLASMA module first defines imports, constants, variables and data. Constants must be initialized with a value. Variables can have sizes associated with them to declare storage space. Data can be declared with or without a variable name associated with it. Arrays, tables, strings and any predeclared data can be created and accessed in multiple ways.
//
// Import standard library functions.
//
import stdlib
predef putc, puts, getc, gets, cls, memcpy, memset, memclr
end
//
// Constants used for hardware and flags
//
const speaker = $C030
const changed = 1
const insmode = 2
//
// Array declaration of screen row addresses
//
word txtscrn[] = $0400,$0480,$0500,$0580,$0600,$0680,$0700,$0780
word = $0428,$04A8,$0528,$05A8,$0628,$06A8,$0728,$07A8
word = $0450,$04D0,$0550,$05D0,$0650,$06D0,$0750,$07D0
//
// Misc global variables
//
byte flags = 0
word numlines = 0
byte cursx, cursy
word cursrow, scrntop, cursptr
Variables can have optional brackets; empty brackets don’t reserve any space for the variable but are useful as a label for data that is defined following the variable. Brackets with a constant inside defines a minimum size reserved for the variable. Any data following the variable will take at least the amount of reserved space, but potentially more.
Strings are defined like Pascal strings, a length byte followed by the string characters so they can be a maximum of 255 characters long. Strings can only appear in the variable definitions of a module. String constants can’t be used in expressions or statements.
//
// An initialized string of 64 characters
//
byte txtfile[64] = "UNTITLED"
Functions are defined after all constants, variables and data. Functions can be forward declared with a predef type in the constant and variable declarations. Functions have optional parameters and always return a value. Functions can have their own variable declarations. However, unlike the global declarations, no data can be predeclared, only storage space. There is also a limit of 254 bytes of local storage. Each parameter takes two bytes of local storage, plus two bytes for the previous frame pointer. If a function has no parameters or local variables, no local frame will be created, improving performance. A function can specify a value to return. If no return value is specified, a default of 0 will be returned.
After functions are defined, the main code for the module follows. The main code will be executed as soon as the module is loaded. For library modules, this is a good place to do any runtime initialization, before any of the exported functions are called. The last statement in the module must be done, or else a compile error is issued.
There are four basic types of data that can be manipulated: constants, variables, addresses, and functions. Memory can only be read or written as either a byte or a word. Bytes are unsigned 8 bit quantities, words are signed 16 bit quantities. Everything on the evaluation stack is treated as a word. Other than that, any value can be treated as a pointer, address, function, character, integer, etc. There are convenience operations in PLASMA to easily manipulate addresses and expressions as pointers, arrays, structures, functions, or combinations thereof. If a variable is declared as a byte, it can be accessed as a simple, single dimension byte array by using brackets to indicate the offset. Any expression can calculate the indexed offset. A word variable can be accessed as a word array in the same fashion. In order to access expressions or constants as arrays, a type identifier has to be inserted before the brackets. a ‘.’ character denotes a byte type, a ‘:’ character denotes a word type. Along with brackets to calculate an indexed offset, a constant can be used after the ‘.’ or ‘:’ and will be added to the base address. The constant can be a defined const to allow for structure style syntax. If the offset is a known constant, using the constant offset is a much more efficient way to address the elements over an array index. Multidimensional arrays are treated as arrays of array pointers. Multiple brackets can follow the ‘.’ or ‘:’ type identifier, but all but the last index will be treated as a pointer to an array.
word hgrscan[] = $2000,$2400,$2800,$2C00,$3000,$3400,$3800,$3C00
word = $2080,$2480,$2880,$2C80,$3080,$3480,$3880,$3C80
hgrscan:[yscan][xscan] = fillval
Values can be treated as pointers by preceding them with a ‘^’ for byte pointers, ‘*’ for word pointers.
strlen = ^srcstr
Addresses of variables and functions can be taken with a preceding ‘@’, address-of operator. Parenthesis can surround an expression to be used as a pointer, but not address-of.
Functions can have optional parameters when called and local variables. Defined functions without parameters can be called simply, without any paranthesis.
def drawscrn(topline, leftpos)
byte i
for i = 0 to 23
drawline(textbuff[i + topline], leftpos)
next
end
def redraw
cursoff
drawscrn(scrntop, scrnleft)
curson
end
redraw
Functions with parameters or expressions to be used as a function address to call must use parenthesis, even if empty.
predef keyin2plus
word keyin
byte key
keyin = @keyin2plus // address-of keyin2plus function
key = keyin()
Expressions and Statements
Expressions are algebraic. Data is free-form, but all operations on the evaluation stack use 16 bits of precision with the exception of byte load and stores. A stand-alone expression will be evaluated and read from or called. This allows for easy access to the Apple’s soft switches and other memory mapped hardware. The value of the expression is dropped.
const speaker=$C030
^speaker // click speaker
close(refnum)
More complex expressions can be built up using algebraic unary and binary operations.
| OP | Unary Operation |
|---|---|
| ^ | byte pointer |
| * | word pointer |
| @ | address of |
| - | negate |
| ~ | bitwise compliment |
| NOT | logical NOT |
| OP | Binary Operation |
|---|---|
| * | multiply |
| / | divide |
| % | modulo |
| + | add |
| - | subtract |
| << | shift left |
| >> | shift right |
| & | bitwise AND |
| ^ | bitwise XOR |
| | | bitwise OR |
| == | equals |
| <> | not equal |
| >= | greater than or equal |
| > | greater than |
| <= | less than or equal |
| < | less than |
| OR | logical OR |
| AND | logical AND |
Statements are built up from expressions and control flow keywords. Simplicity of syntax took precedence over flexibility and complexity. The simplest statement is the basic assignment using ‘=’.
byte numchars
numchars = 0
Expressions can be built up with constants, variables, function calls, addresses, and pointers/arrays. Comparison operators evaluate to 0 or -1 instead of the more traditional 0 or 1. The use of -1 allows binary operations to be applied to other non-zero values and still retain a non-zero result. Any conditional tests check only for zero and non-zero values.
Control structures affect the flow of control through the program. There are conditional and looping constructs. The most widely used is probably the if/elsif/else/fin construct.
if ^pushbttn3 < 128
if key == $C0
key = $D0 // P
elsif key == $DD
key = $CD // M
elsif key == $DE
key = $CE // N
fin
else
key = key | $E0
fin
The when/is/otherwise/wend statement is similar to the if/elsif/else/fin construct except that it is more efficient. It selects one path based on the evaluated expressions, then merges the code path back together at the end. However only the 'when' value is compared against a list of expressions. The expressions do not need to be constants, they can be any valid expression. The list of expressions is evaluated in order, so for efficiency sake, place the most common cases earlier in the list. Just as in C programs, a 'break' statement is required to keep one clause from falling through to the next. Falling through from one clause to the next can have it's uses, so this behavior has been added to PLASMA.
when keypressed
is keyarrowup
cursup
break
is keyarrowdown
cursdown
break
is keyarrowleft
cursleft
break
is keyarrowright
cursright
break
is keyctrlx
cutline
break
is keyctrlv
pasteline
break
is keyescape
cursoff
cmdmode
redraw
break
otherwise
bell
wend
The most common looping statement is the for/next construct.
for xscan = 0 to 19
(scanptr):[xscan] = val
next
The for/next statement will efficiently increment or decrement a variable form the starting value to the ending value. The increment/decrement amount can be set with the step option after the ending value; the default is one. If the ending value is less than the starting value, use downto instead of to to progress in the negative direction. Only use positive step values. The to or downto will add or subtract the step value appropriately.
for i = heapmapsz - 1 downto 0
if sheapmap.[i] <> $FF
mapmask = szmask
fin
next
while/loop statements will continue looping as long as the while expression is non-zero.
while !(mask & 1)
addr = addr + 16
mask = mask >> 1
loop
Lastly, the repeat/until statement will continue looping as long as the until expression is zero.
repeat
txtbuf = read(refnum, @txtbuf + 1, maxlnlen)
numlines = numlines + 1
until txtbuf == 0 or numlines == maxlines
###Runtime
PLASMA includes a very minimal runtime that nevertheless provides a great deal of functionality to the system. Two system calls are provided to access native 6502 routines (usually in ROM) and ProDOS.
romcall(aReg, xReg, yReg, statusReg, addr) returns a pointer to a four byte structure containing the A,X,Y and STATUS register results.
const xreg = 1
const getlin = $FD6A
numchars = (romcall(0, 0, 0, 0, getlin)).xreg // return char count in X reg
syscall(cmd, params) calls ProDOS, returning the status value.
def read(refnum, buff, len)
byte params[8]
params.0 = 4
params.1 = refnum
params:2 = buff
params:4 = len
perr = syscall($CA, @params)
return params:6
end
putc(char), puts(string), home, gotoxy(x,y), getc() and gets() are other handy utility routines for interacting with the console.
byte okstr[] = "OK"
putc('.')
puts(@okstr)
memset(addr, len, val) will fill memory with a 16 bit value. memcpy(dstaddr, srcaddr, len) will copy memory from one address to another, taking care to copy in the proper direction.
byte nullstr[] = ""
memset(strlinbuf, maxfill * 2, @nullstr) // fill line buff with pointer to null string
memcpy(scrnptr, strptr + ofst + 1, numchars)
##Implementation Details ###The Original PLASMA The original design concept was to create an efficient, flexible, and expressive environment for building applications directly on the Apple II. Choosing a stack based architecture was easy after much experience with other stack based implementations. It also makes the compiler simple to implement. The first take on the stack architecture was to make it a very strict stack architecture in that everything had to be on the stack. The only opcode with operands was the CONSTANT opcode. This allowed for a very small bytecode interpreter and a very easy compile target. However, only when adding an opcode with operands that would greatly improved performance, native code generation or code size was it done. The opcode table grew slowly over time but still retains a small runtime interpreter with good native code density.
The VM was constructed such that code generation could output native 6502 code, threaded code into the opcode functions, or interpreted bytecodes. This gave a level of control over speed vs memory.
###The Lawless Legends PLASMA This version of PLASMA has dispensed with the native/threaded/bytecode code generation from the original version to focus on code density and the ability to interpret bytecode from AUX memory, should it be available. By focussing on the bytecode interpreter, certain optimizations were implemented that weren't posssible when allowing for threaded/native code; the interpreted bytecode is now about the same performance as the directly threaded code.
Dynamically loadable modules, a backward compatible extension to the .REL format introduced by EDASM, is the new, main feature for this version of PLASMA. A game like Lawless Legends will push the capabilities of the Apple II well beyond anything before it. A powerful OS + language + VM environment is required to achieve the goals set out.
References
PLASMA User Manual: https://github.com/badvision/lawless-legends/blob/master/Docs/Tutorials/PLASMA/User%20Manual.md
B Programming Language User Manual http://cm.bell-labs.com/cm/cs/who/dmr/kbman.html
FORTH http://en.wikipedia.org/wiki/Forth_(programming_language)
UCSD Pascal http://wiki.freepascal.org/UCSD_Pascal
p-code https://www.princeton.edu/~achaney/tmve/wiki100k/docs/P-code_machine.html
VM02: Apple II Java VM http://sourceforge.net/projects/vm02/
Threaded code http://en.wikipedia.org/wiki/Threaded_code