UVM

uVM

This is an 8-bit virtual machine with 16-bit addressing. It is RISC-style with no direct operations on memory, instead operations are done on one of 16 8-bit registers with 6 16-bit registers mapped over them.

An ASM language is defined and implemented for this VM.

Building / Running

CMake and a C build toolchain are required to build. On a debian-based system install build-essential and cmake packages.

# setup makefiles (run once)
$ cmake -DCMAKE_BUILD_TYPE=Release -G "Unix Makefiles" -S . -B ./cmake-build-release
# build project
$ cmake --build ./cmake-build-release --target uVM

Usage is printed with no options given.

$ ./cmake-build-release/uVM 
Usage:
  uVM program.bin                            # load at 0x0000
  uVM -a 0x100 file1.bin -a 0x200 file2.bin  # multiple files at absolute addresses
  uVM -p 0x100 program.bin                   # set PC to 0x100
  uVM -c file.asm [-o output.bin]            # assemble into binary format

Compiling and running asm files can be achieved with the following.

$ ./cmake-build-release/uVM -c programs/basic.asm -o programs/basic.bin
Assembling 'programs/basic.asm' -> 'programs/basic.bin'
$ /cmake-build-release/uVM programs/basic.bin                         
Loaded 'programs/basic.bin' at 0x0000 (272 bytes)
VM Halted with code 0
PC: 0110  carry: 0  halted: 1 haltcode: 0000 (0)
R0: 00 (000) R4: 02 (002) R8: 00 (000) RC: 00 (000) 
R1: 01 (001) R5: 00 (000) R9: 00 (000) RD: 00 (000) 
R2: 64 (100) R6: 00 (000) RA: 00 (000) RE: 00 (000) 
R3: 00 (000) R7: 00 (000) RB: 00 (000) RF: 00 (000) 
RXA: 200 (00512) RXB: 00 (00000) RXE: 00 (00000)
RXC: 00 (00000) RXF: 00 (00000) RXD: 00 (00000)

VM

Registers and Flags

• 8-bit registers 16 registers (R0–RF), 8-bit each.
• 16-bit registers 16 registers (RX0-RXF) mapped over the 8-bit registers.
  • RX0-RX9 mirroring R0-RF extended to 16-bits
  • RXA-RXF mapped to pairs of 8-bit registers
• R0/RX0 always reads as 0. Writes to R0 are a no-op.
• PC (program counter), 16-bit. Increments by 2 each instruction fetch. Must be word-aligned.
• carry, 1-bit flag used by ADC and SBC.

16-bit Register Mapping

Some instructions can use two 8-bit registers as one 16-bit register for addressing.

The upper 12 registers form six extended 16-bit address registers (big-endian, high byte : low byte):

vm_get_rx() returns the 16-bit value of a register: 0x0-0x9 return the 8-bit variant, with 0xA-0xF returning the above registers.

Memory

• 64KB address space (0x0000 - 0xFFFF).
• All operations work on registers only, no direct memory-to-memory operations.
• Memory access is via hook functions: readAddr and writeAddr on the VM struct.

Instruction Format

All instructions are two bytes (big-endian). The upper four bits are the opcode. Three operand formats share the lower 12 bits:

Operations / Opcodes

Operand terms

• exitcode - sets the vm exitcode
• rd/rx/ry - 8-bit register
• rdx - rd with extended register support
• imm4 - immediate value 4-bit
• imm4_s - immediate value 4-bit
• imm4_s_x2 - immediate value 4-bit multiplied by two
• test - a conditional jump type
• imm8 - immediate value 8-bit
• imm8_s - signed immediate value 8-bit
• imm8_s_x2 - signed immediate value 8-bit multiplied by two
• imm12 - immediate value 12-bit
• imm12_s - signed immediate value 12-bit
• imm12_s_x2 - signed immediate value 12-bit multiplied by two
• carry - carry flag

All jumps are in words/instructions.

Conditional Jumps

Test types, used for comparing values in rd and rx.

Tests are mapped into a 4-bit value and can be in any combination

3   2   1   0
|   |   |   |
|   |   |   +-- Equality
|   |   +------ Less Than
|   +---------- Greater Than
+-------------- Negate Result

Setting bits 0–3 will pass for any value, negating it will not pass for any value, similarly not setting any bits will not pass for any value.

Error Handling

Errors are reported via the error hook and halt the VM:

Execution Model

1. vm_step() fetches one 2-byte instruction from readAddr(PC).
2. Decodes the opcode and operand format.
3. Executes the operation, writing the result to rd via vm_put_r().
4. Increments PC by 2 (except for jumps which set PC directly).
5. The main loop calls vm_step() repeatedly until vm->halted is true.

TODO

ASM

• allow variables in STA/LDA address offset
• allow referencing variable high/low byte with :h/:l

VM

• Add device support
  • File