waveasm

Crates.io	waveasm
lib.rs	waveasm
version	0.2.3
created_at	2025-06-03 05:18:43.195566+00
updated_at	2025-12-05 23:28:15.751852+00
description	Assembler for the Wave2 CPU Architecture
homepage	https://nimphio.us/wave2/
repository	https://github.com/zeb-hicks/wave2_assembler
max_upload_size
id	1698663
size	156,948

Nimphious (zeb-hicks)

documentation

README

Wave2 Assembler

Assembler for the Wave2 architecture.

Example

This example program cycles the user's ship colour through a list of colours stored in the constant register.

; This section describes the memory layout of the constant registers
.memory

000f 00ff 00f0 0ff0
0f00 ff00 f000 0f0f
f0f0 fff0 f00f 0fff
f0ff ff0f 7777 ffff

; This section contains the code that is inserted at 0x40
.code

set r1, $0f          ; Colour count
set r4, $39c         ; Ship colour
:loop

mov r1.x, [r0.x]     ; Read colour from constants
mov [r0.x+], r1.x    ; Increment r0 and also copy the colour

mov r2.x, r0.x       ; Make a copy of the counter
ge.w r2, r2, r1      ; If counter > colour count
sub.w ri, ri, r2     ; (skips next if false)
sub.w r0, r0, r0     ; then reset counter

set r6, $04ff        ; Wait duration
slp.w r6             ; Sleep for duration
mov [r4.x], r1.x     ; Set ship colour
jmp :loop

Instruction Set

N = Number ^{42, $20 ...}
C = Constant register ^{c0 .. c7}
R = General Purpose Register ^{r0 .. r7|ri}
P = Pointer ^{[r0.x], [r3], [c4.xyzw] ...}
I = Increment Pointer ^{[ri.x+], [r0+], [r2.xyzw+] ...}
L = Label ^{:Loop_Start, :MAIN, :Example ...}

	Mnemonics	Operands	Description	Notes / Examples
Halt	`hlt\|halt`		Halts the process
Nop	`nop`		No-op.	A single-tick sleep. Under the hood this is a sleep for 0 ticks.
Skip	`skip\|skip1` `skip2` `skip3` `skip4`		Skip increments the program counter by the specified amount. This can be useful for flow control in certian situations.
Sleep	`slp\|sleep`	`N` `C` `R`	Pauses execution for a specified duration. When specifying a number, the number must be between 0 and 255. When specifying a register, the instruction requires an additional specifier for the byte or word from which to select the duration from the target register.	`slp.w r0` sleeps for the duration specified by the word `r0.x` `slp.h r3` sleeps for the duration specified by the high byte of the word `r3.x` The valid specifiers are `.w` for word, `.h` for high byte, and `.l` for low byte.
Move	`mov\|move`	`R, R` `R, C` `R, P` `R, I` `P, R` `P, C` `I, R` `I, C`	Copy a value between registers or pointers. Registers can either be unswizzled, or have matching swizzles. Different swizzles are not supported. Moves to pointers are encoded as store instructions. Moves from pointers are encoded as load instructions.	`mov r0, c1` Copies `c1`'s value into `r0` `mov [c4.x], r5.x` Stores the first word of `r5` into the address of the pointer in the first word of `c4`
Select	`wmov\|wmove` `wswap` `wadd` `wsub`	`R, R` `R, C`	Performs specified operations on a an arbitrary source word to the first word in the destination.	`wmove r0, c4.y` Copies `c4.y` into `r0.x` `wadd r2, c1.w` Adds `c1.w` to `r2.x`
Swizzle	`swi` `swizzle`	`R`	Swizzles the words within a register arbitrarily. Using the `.[xyzw]` notation the words in a register can be arbitrarily reassigned/copied.	`swizzle r4.wwww` Sets every word in `r4` to its fourth word. (`r4.w`) `swizzle r0.yyzz` Given `r0` is `[1, 2, 3, 4]`, sets `r0` to be `[1, 1, 2, 2]`
Math	`add` `adds` `ado\|addo\|addover` `sub` `subs` `suo\|subo\|subover` `eq\|equ` `ne\|neq` `lt` `le\|lte` `gt` `ge\|gte` `carry`	`R, R, R` or `R, R, C` or `R, C, R`	Math instructions take three operands in the order destination, left, right. The destination register must be writeable (not constant) and this same register must be at least one of the other two operands. The remaining operand can be a constant register. Additionally, math instructions require a width specifier `.b` or `.w` to control whether the operation is performed between bytes or words, respectively.
Bitwise	`all` `one` `swp\|swap` `nsrc\|notsrc` `ndst\|notdst` `sand\|srcandnotdest` `nsad\|notsrcanddest` `sond\|srcornotdest` `nsod\|notsrcordest` `and` `or` `xor` `nand` `nor` `xnor`	`R` `R, R` `R, C`	Bitwise operations are all binary operand except for `all` and `one` which are unary operations taking only one writeable register as an operand. Bitwise operations operate on all words of the specified registers.	Some examples include: `and r0, r4` → `r0 = r0 & r4` `xor r1, c0` → `r1 = r1 ^ c0` `srcandnotdest ri, c2` → `ri = ri & !c2`
Shift	`asl\|lsl` `rol` `asr` `lsr` `ror`	`R, R` `R, N`	Math instructions take three operands in the order destination, left, right. The destination register must be writeable (not constant) and this same register must be at least one of the other two operands. The remaining operand can be a constant register. Additionally, shift instructions require a width specifier `.b` or `.w` to control whether the operation is performed at the byte or word level, respectively.
Special	`hadd` `mul\|mults\|multisat` `mlo\|multl\|multlow` `mhi\|multh\|multhigh` `div\|divide` `rdiv\|rdivide`	`R, R` `R, C`	Special advanced arithmetic instructions. These instructions are all SIMD and operate on all words in a specified register.
Set	`set\|set1` `set2` `set3` `set4`	`R, N` `R, L`	Set is a shorthand for an advanced usage of the `move` instruction in which the incremented program counter is used as a pointer to the raw value stored in the proceding memory addresses. The second operand can be a literal value or a label.	Literal values will simply be stored in the proceding memory addresses directly. Labels will store the jump address of the specified label into the proceding memory address.
Jump	`jmp`	`N` `L`	Jump is a shorthand for storing literal values directly into the program counter. Similar to Set except we load the value into `ri.x` specifically.	Effectively equivalent to writing `set ri, *` but a little more idiomatic.

Install

Make sure rust is installed, and then run:

cargo install --git https://github.com/zeb-hicks/wave2_assembler

Usage

waveasm [OPTIONS] <INPUT>

Arguments:
  <INPUT>  Input file path

Options:
  -b, --binary                 Output as Wave2 binary format
  -o, --output <OUTPUT>        Output file path, only logs to stdout if not set
  -l, --log-level <LOG_LEVEL>  Log level, valid values are: OFF, ERROR, WARN, INFO, DEBUG, TRACE [default: WARN]
  -h, --help                   Print help

Commit count: 73