PLASMA is designed to run on the Apple I, Apple ///, and all versions of the Apple ][ from the original up to the IIGS. As such, it is already portable enough to target the hardware variability amongst all these systems, plus offer basic VM functionality and a PLASMA cross-compiler running on modern Unix-like systems. Obviously, some PLASMA programmers may desire using the language and toolchain on one of the many other Retrocomputer systems powered by the 6502 microprocessor - such as Commodore's and Atari's 8-bit line, BBC micro, or even the NES and SNES. Additionally, programmers may also want to use PLASMA on seriously constrained 8-bit systems that are not powered by a 6502 family microprocessor, such as Z80 systems or even AVR microcontrollers. This guide aspires to describe the necessary steps and desired approach for such porting efforts.
Minimum requirements for any porting effort
A full PLASMA virtual machine implementation is built from two parts:
- A PLASMA bytecode interpreter. This is written in 6502 assembler and the source code can be seen in vmsrc/plvm*.s. vmsrc/plvm01.s is the Apple I implementation.
- "cmd", written in a mixture of PLASMA language code and 6502 assembler. This runs on top of the bytecode interpreter. It is responsible for interacting with the user. In particular, it responds to the command '+foo' by loading and executing the module 'foo' from disk. This involves loading PLASMA modules from disk into RAM recursively to satisfy inter-module dependencies and fixing up symbol references. The source code for this can be seen in vmsrc/*cmd.pla. vmsrc/a1cmd.pla is the Apple I implementation.
The Apple I implementation combines the two parts into a single executable. a1cmd.pla is compiled into a1cmd.a, and this is included directly from plvm01.s (see the label A1CMD). For a minimal or initial port to another system, this is likely to be the best approach to use - it means that no disk I/O is needed from within the VM in order to start executing "cmd". Everything up to and including allowing the user to enter commands at the prompt can be tested with no more complex I/O than get/put character - simple operations that don't vary much between different systems. (The Apple II implementation has the bytecode interpreter load "cmd" from disk. Even if you think this is a desirable feature in your port, it is probably easiest to stick with the Apple I style to start with.)
The bytecode interpreter absolutely has to be ported. It is highly desirable to also port "cmd", but it is possible (if only as an intermediate stage in the port) to replace "cmd" with a simpler PLASMA program, such as:
const addr = $4000
*addr = $1234
done
This allows the bytecode interpreter to be tested independently of the full and complex "cmd". For example, after building an executable using the bytecode interpreter and the above mini "cmd", running it should store $1234 at address $4000 if the VM has started up correctly and the relevant VM opcodes have been implemented correctly - this can be verified using a debugger/monitor. (If you are porting to a 6502 system, it is highly likely the VM opcodes will be implemented correctly as you can use the Apple code almost unmodified, but this test is still useful as it shows that the VM has started up correctly and executed bytecodes.)
If your system has no concept of terminal I/O (a games console or embedded system) or has no disks (needed by a full PLASMA implementation for random access to modules stored in files), the same technique allows you to write a PLASMA program which runs in place of the interactive "cmd" when the executable is started.
Porting to other 6502-based retro systems
BBC micro Port (WIP)
Porting to other 8-bit microprocessor systems
Porting to 16-bit microprocessor systems
One of the objectives of PLASMA was to ease the programmer burden for routine use of 16-bit quantities on the 8-bit 6502. This is similar to the motivation behind Woz's initial inclusion of the SWEET16 virtual machine in the original Apple ][ ROM. As such, 16-bit WORDs are a primitive data type in PLASMA. In fact, WORDs and BYTEs are the only primitive data types, and WORDs serve a double purpose by being the addressing primitive for all pointer types.
Due to these features of the language, PLASMA will be a natural fit for CPUs that can perform 16-bit internal operations and can address byte locations in memory (odd -or- even address) using 16-bit addresses. Of course, the PLVM must be reimplemented for the CPU, but would theoretically result in a more streamlined VM since some VM opcodes would be much more trivially performed by the 16-bit CPU compared to a 6502. If only PLASMA language portability is necessary (no PLVM byte code portability), then it may even be practical to compile PLASMA directly to the 16-bit CPU's native code so it can be executed without an interpreter. However, at this point one must ask what benefits PLASMA offers to the 16-bit platform, alongside the likely existing high-level language compilers for C/C++.
The 65802/65816 VM demonstrates using a 16 bit CPU and the hardware stack for expression evaluation yet retaining compatibility with external 8 bit code and interface of the 6502 VM.
There is a somewhat raw implementation of the PLASMA bytecode interpreter (no "cmd") for the homebrew 16-bit OPC6 CPU discussed here: http://anycpu.org/forum/viewtopic.php?f=3&t=426 This implementation doesn't have the latest VM opcode changes, so you must use a version of the PLASMA compiler from the same time as the thread posts. (It would be possible to implement "cmd", but this requires a fuller OPC6 environment with terminal I/O and random access files, which the basic OPC6 emulator lacks.)