Crate pir_8_emu

An implementation of the pir-8 ISA.

The library

pir-8-emu can be thought of as consisting of layers:

The first layer is the isa module, which contains a pure implementation of the pir-8 ISA, and can be used on its own to parse/generate binaries at the instruction level.

The second layer is the vm module, which contains parts of VM memory and port handling.

The third layer is the micro module, which contains a full stack-based microcode implementation, and can be used to fully emulate a pir-8 machine (see example inside).

The fourth layer is the various binutils, which contain useful parts of the executables, like AssemblerDirective and OutputWithQueue, or NativePortHandler.

These utilities can be used to quickly and correctly build off existing solutions, but may have some quirks or be less absolutely generic (e.g. Vm will allow you to integrate a fully (as-emulator) controllable and functional pir-8 virtual machine in about 5 lines, but it needs to have the INS SP register be observed after each μOp (see example inside)).

The binaries

The headers link to manpages with more detailed usage instructions:

pir-8-as

An assembler with an… idiosyncratic syntax:

JUMP
:label load text

:literal "*pounces on u* OwO what's whis?"
0x00

:label save text
LOAD IMM Y
1

LOAD IMM A
0x00

LOAD IMM X
0x03

:label save loop-head
SAVE X
:label load-offset load-byte 2

JUMP
:label load load-byte

:label save post-load
PORT OUT S
COMP S
JMPZ
:label load end

ALU ADD
MOVE S X
JUMP
:label load loop-head

:label save end
HALT

:label save load-byte
LOAD IND S
0x0000
JUMP
:label load post-load

If you'd rather use a more normal syntax, CatPlusPlus has also made a fasm-based assembler:

include 'pir8.finc'

origin 0x0002

	load a, [0x0000]
	load b, [0x0001]

top:
	move x, a
	move y, b
	sub

	jmpz exit

	move s, a
	comp b

	jmpl lt

	sub
	move a, s
	jump top

lt:
	move y, a
	move x, b
	sub
	move b, s
	jump top

exit:
	move d, a
	halt

pir-8-disasm

A dissassembler with a ndisasm-based frontend:

$ pir-8-disasm -k 1,7 test-data/xor-swap-with-loads.p8b
00000000   24   LOAD IND A
00000002 0110 D 0x0110
00000003   1D   LOAD IMM B
00000004   69 D 0x69
00000005   62   MOVE A X
00000006   6B   MOVE B Y
00000007   35   ALU XOR
00000008      S skipping 0x07 bytes
00000010   4C   MOVE S A
00000011   FF   HALT

pir-8-emu

The emulator in-of itself:

Example programs

Apart from the two forthlaid above, take a look at the test-data/ directory in the git repo, which contains a mix of assembler programs (.p8a), program binaries (.p8b), and derivations/hand-assemblies (.diz).

Native handlers

For more information, consult the documentation on RawNativePortHandler.

For examples, take a look at the handler-examples/ directory in the git repo. Running make at the root thereof should build them without much hassle, if it doesn't, please open an issue.

The include/pir-8-emu/port_handler.h file contains C declarations.

Special thanks

To all who support further development on Patreon, in particular:

• ThePhD

Modules

binutils	Additional utilities used to implement the binaries
isa	All data specified directly in the ISA.
micro	Microcode implementation
options	Executable option parsing and management.
util	Module containing various utility functions.
vm	Various parts of the virtual machine implementation

Structs

ReadWriteMarker

Marker for wrapper types that need to track when they were read from/written to.

Traits

ReadWritable

Generic trait for objects that can track whether they've been read from and/or written to.