Haxor VM

Haxor consists of compiler hc and virtual machine hvm.

Man, why have you written that?

Writing own implementation of VM gives a lot of knowledge about computer's architecture. You hit into issues not known during day by day activity in high level languages you use. So... just to broaden horizons and for fun ;)

How to install?

You need to install these software before installing Haxor:

• cmake 2.8.7 or newer
• c++11 compatible compiler (e.g. clang 3.5, Apple clang 6.0, gcc 4.8)
• flex (tested on 2.5)
• bison 3.x (the one bundled with OS X is too old, you can use version from homebrew)

haxor is written in c++, you must compile it before use:

git clone https://github.com/krzysztof-magosa/haxor.git
cd haxor
mkdir build
cd build
cmake ..
make
make install

Optionally you can change installation prefix by invoking this command instead of cmake ..:

cmake -DCMAKE_INSTALL_PREFIX=/opt/haxor ..

To specify non-standard Bison location (for example on OS X):

cmake -DBISON_EXECUTABLE=/opt/homebrew/Cellar/bison/3.0.4/bin/bison ..

Usage

Compilation:

hc program.hax

Run:

hvm program.hax.e

License

Haxor is licensed under BSD 3-clause license. You can read it here.

Architecture

General information

• Design: RISC, load/store
• Endianness: Little Endian
• WORD size: 64-bit
• Registers size: 64-bit
• Instruction: fixed size, 64-bit
• Arithmetic: integer only, 64-bit
• Memory model: paging with protection flags (read, write, exec)
• Call convention: parameters are passed by $a0-$a9 registers, return values by $v0, $v1

OpCodes

Instruction is 64-bit, and contains:

• 0:6 bits - instruction code (7 bits, unsigned)
• 7:8 bits - flags (2 bits, unsigned, not used at the moment)
• 9:14 bits - register 1 (6 bits, unsigned)
• 15:20 bits - register 2 (6 bits, unsigned)
• 21:26 bits - register 3 (6 bits, unsigned)
• 27:63 bits - immediate value (37 bits, signed)

vCPU

vCPU has 64 registers, some of them have special role:

Please always use aliases and not register numbers.

Memory map

|Segment|Read |Write |Execute | |-------|------------------|------------------|------------------|c |ivt |✅|✅|🚫 | |code |🚫 |🚫 |✅| |data |✅|✅|🚫 | |bss |✅|✅|🚫 | |heap |✅|✅|🚫 | |stack |✅|✅|🚫 |

* Heap is not implemented yet.

Language

Haxor uses primitive asm-like syntax. Each command goes into separate line. You can use comments using #. Program starts from main label. Labels are created by putting name followed by colon.

Most of instructions take 3 registers or 2 registers and immediate value. If not stated differently result goes to first specified register.

Instructions

Native instructions

Pseudo instructions

System calls

Using syscall command you can run some system calls provided by Haxor VM. System call number is passed via $sc register, arguments are passed by registers $a0-$a9. Return value is written into $v0 register, some syscalls return error code in $v1.

print_string (01h)

Print 0 terminated string located under specific address.

Example:

li $sc, 01h
la $a0, label_msg
syscall

print_int (02h)

Print number.

Example:

li $sc, 02h
li $a0, 123
syscall

read_string (03h)

Reads line from standard input and writes under specified address. Second parameter designates buffer size (including terminating 0).

Example:

li $sc, 03h
la $a0, destination_label
li $a1, 100
syscall

read_int (04h)

Reads integer from standard input. Value is returned via $v0, error code via $v1.

Example:

li $sc, 04h
syscall

rand (05h)

Generate random number between min and max.

li $sc, 05h
li $a0, 100
li $a1, 200
syscall

sleep (06h)

Sleeps for specified number of milliseconds.

li $sc, 06h
li $a0, 1000
syscall

exit (07h)

Stops virtual machine and exits with specified exit code.

li $sc, 07h
li $a0, 5
syscall

create_timer (08h)

Schedule interrupt to be run every N ticks of system timer (it runs 1000 ticks per second). Timer identificator is returned in $v0 register.

Please note that because of way how syscalls are implemented they are not preemptive. It means that if you for example use sleep syscall, timer interrupt may be fired after sleep. You can implement your own sleep routine based on steady_time to bypass this limitation (see example here).

la $t0, isr0     # load address of isr0 label into register $t0
sw $zero, 0, $t0 # load $t0 value into memory[0]

li $sc, 08h
li $a0, 0 # int number
syscall

enable_timer (09h)

Enables previously disabled timer.

li $sc, 09h
li $a0, 0 # timer id
syscall

disable_timer (0ah)

Disables calling interrupt by timer. Ticks are still counted so it does not impair the cycle..

li $sc, 0ah
li $a0, 0 # timer id
syscall

time (0bh)

Returns time in specified unit.

li $sc, 0bh
li $a0, 2
syscall

steady_time (0ch)

Returns steady time which cannot be decreased. It's suitable for measuring intervals. Units are controlled in the same way as in time syscall.

li $sc, 0ch
li $a0, 3
syscall

Interrupts

Haxor VM provides 128 interrupts, first 32 are reserved for exceptions and internal things, you can use rest for your needs e.g. timers. To assign interrupt service routine to specific interrupt you need to put ISR address into relevant cell of interrupt vector table.

The formula is

ivr_cell_address = interrupt_number * 8

Example of assigning ISR to interrupt 32

isr32:
  # isr body
  reti

main:
  la $t0, isr32
  sw $zero, 256, $t0 # 32 * 8 = 256

  # rest of code

CPU Exceptions

In some situations Haxor VM can raise exception. Every exception type has assigned specific interrupt.

Useful knowledge related to (virtual) machines

• Reduced instruction set computing
• Sigil
• Endianness
• Berkeley RISC
• Comparison of instruction set architectures
• Flag field
• Delay slot
• Processor register
• Index register
• Instruction set
• ARM architecture
• Arithmetic logic unit
• Processor design
• Minimal instruction set computer
• Opcode
• Computer architecture
• NX bit
• Register memory architecture
• Vector processor
• Instruction set
• VDSO
• Bytecode
• Virtual machine
• Stack machine
• Zero instruction set computer
• System call
• P-code machine
• Accumulator
• Register machine
• Memory segmentation
• Zero page
• Status register
• Call stack
• Virtual memory
• Stride_of_an_array
• Relocation
• Zero_address_arithmetic
• Addressing_mode
• Nibble
• .bss