proj-oot-bootReferenceOld201018

1. Boot (Oot Boot) reference

Version: unreleased (0.0.0-0)

Boot is a low-level 'assembly language' virtual machine (VM) that is easy to implement.

1. # Introduction

Boot is a target language that is easy to implement on a wide variety of platforms, even on very primitive bare metal, or 'on top of'/within an existing high-level languages such as Python.

Highlights:

• 3-operand fixed-length register machine
• signed 32-bit integers
• integers and pointers both have implementation-dependent sizes in memory, and may be different sizes
• opaque pointer representation
• 7 integer registers, 7 pointer registers, 15 opaque registers to copy values of any type, and a zero register, and a null pointer register
• <=64 instructions
• RISC-like; no addressing modes (or rather, each instruction has one fixed addressing mode), and only a few instructions access (non-register) memory
• instructions for I/O, memory allocation, and calling to and from host platform
• the extension BootX? is available (well, rather it's in progress) that specifies more instructions and functionality (see bootx_reference.md)

[TOC]

1. # Instruction encoding ## 4 bytes per instruction. The bytes are:

• op0 (operand 0)
• op1
• op2
• opcode

Op0 is restricted to a maximum value of 63 (when interpreted as unsigned), meaning that the 2 most-significant-bits are always zero.

1. # Datatypes ##

two primary datatypes:

• int32 (32-bit integers)
• ptr (pointers)

ptr has two subtypes: - ptrd (data pointers) - ptrc (code pointers)

1. # Registers ## Two banks of 8 registers each; one for int32, one for ptr. The first register in the int32 bank is constant zero, and the first register in the ptr bank is the null pointer; writes to these registers have no effect. The notation $n refers to the n-th int32 register, and &n refers to the n-th ptr register, for example the first and last registers in each bank are: $0, $15, &0, &15.
   1. Instructions ##

47 instructions

(Notation for the instruction tables below) #imm6, #imm8, #imm16, #imm22 are immediate constants using two's complement encoding (#imm6 is 6 bits instead of 8 and #imm22 is 22 bits instead of 24 because op0 can only reach 63, as noted in 'Instruction encoding' above), #imm22u, #imm16u, #imm8u, #imm6u are immediate constants interpreted as unsigned, $X is an integer register, &X is a pointer register, _ is an unused argument that must always be 0 in proper Boot programs (Boot implementation are free to make use of these locations however), and X is an untyped argument. All immediate constants are signed two's-complement ints.

From left to right, the arguments go into operands op0, op1, op2. Immediate operands are always on the right (the highest-numbered operand). When two immediate operands are combined into an #imm16 (as with instruction lm), op1 is the high-order bits and op2 is the low order bits (imm16 = (op1 << 8) + op2). Similarly for #imm22 (imm24 = (op0 << 16) + (op1 << 8) + op2).

JREL and branch immediates are in units of bytes in the Boot code. JREL and branch immediates may not jump into the middle of an instruction. Platforms which compile or represent Boot code in memory in ways such that one instruction spans more or less than 4 memory locations must adjust the jrel and branch offsets accordingly before executing them.

Mnemonics with a trailing 'm' represent instructions involving an 'iMmediate' (although not all instructions with immediates have a trailing 'm' in the mnemonic).

annotation:

• ann ? ? ?: ANNotation; no effect on execution

load constants:

• l32m $dest $src #imm8u: Load 32-bit iMmediate int constant (embedded in instruction stream immediately following instruction), shift it left by #imm8u, add it to $src, then write it to $dest

register loads and stores and copies:

• lw $dest &addr #imm8: Load Word int32 from memory addr (&addr + #imm8*INT32_SIZE)
• lh $dest &addr #imm8: Load Halfword int16 from memory addr (&addr + #imm8*INT16_SIZE)
• lhu $dest &addr #imm8: Load Unsigned int16 from memory addr (&addr + #imm8*INT16_SIZE)
• lb $dest &addr #imm8: Load Byte int8 from memory addr (&addr + #imm8)
• lbu $dest &addr #imm8: Load unsigned int8 from memory addr (&addr + #imm8)
• lp &dest &addr #imm8: Load Ptr from memory addr (&addr + #imm8*PTRD_SIZE)
• sw &addr $src #imm8: Store Word int32 to memory addr (&addr + #imm8*INT32_SIZE))
• sh &addr $src #imm8: Store Halfword int16 to memory addr (&addr + #imm8*INT16_SIZE)
• sb &addr $src #imm8: Store Byte int8 to memory addr (&addr + #imm8)
• sp &addr &src #imm8: Store Ptr to memory addr (&addr + #imm8*PTRD_SIZE)
• cp $dest $src $cond: if $cond == 0, then CoPy? int between registers
• cpp &dest &src $cond: if $cond == 0, then CoPy?