Halfive Virtual Machine Specification

SPDX identifier: COIL-1.0

Copyright Nomagno 2021, 2022, 2023

H5VM assembly is identified by the MIME type text/x-h5asm, extension “.h5asm”

H5VM machine code sequences or “executables” are identified by the MIME type application/x-h5bin, extension “.h5bin”

H5VM drives are identified by the MIME type application/x-h5drive, extension “.h5drive”

The Halfive virtual machine

The Halfive virtual machine, henceforth referred to H5VM, is a specified execution engine for programs.

H5VM Memory layout (Code memory and data memory)

Following Harvard architecture principles, H5VM loads code and data separately into two different ‘members’. The machine code is loaded into the code member, while the data member contains almost all information that is manipulated during the program execution itself.

The code member is read-only.

The data member has addresses (8-bit unsigned memory cells indexed from 0 to 0xFFFF) that are either read/write (RW), read-only (RO), or unmapped (UM). These three properties are referred to as the ‘permission’ of an address.

Machine code format:


BINARY: 0001 0101 000000000000001 000000000011111 0000 0000 0000000000000000 0000000000000000
HEX:    0x01 0x05            0x01            0x1F 0x00 0x00             0x00             0x00
DECIMAL:   1    5               1              31 0       0                0                0
ASSEMBLY:     add               1             =1F      halt
ENGLISH: add the contents of address ONE and the constant 0x1F, put the result in address ONE; stop execution
    add 1 =1F

Assembly format:


add 1 =50
sub *27FA 12


set 0 =20
set 1 =02
set *0 =30
  1. halt - Stop program execution immediately and permanently

  2. jmp V1 - Jump

  3. skpz C1 - Skip plus if zero

  4. skmz C1 - Skip minus if zero

  5. set R1 V2 - Copy the value of V2 to the address of R1.

  6. add R1 V2 - Addition

  7. sub R1 V2 - Substraction

  8. and R1 V2 - Binary And

  9. or R1 V2 - Inclusive Or

  10. xor R1 V2 - Exclusive Or

  11. shift R1 V2 - Bitshift

  12. cmp V1 V2 - Comparison

  13. func C1

  14. ret C1 C2

  15. call C1 C2

  16. frame V1 C2