Getting Started

Installing

Add the package for the CPU you are targeting; it brings in the core packages:

dotnet add package MrKWatkins.OakAsm.Z80    # Z80
dotnet add package MrKWatkins.OakAsm.Z80N   # ZX Spectrum Next

Building Assembly from C#

The Z80Assembly class has a static builder method for every instruction and directive. Build a Source, assemble it, then write the bytes out:

using MrKWatkins.OakAsm.Ast;
using MrKWatkins.OakAsm.IO;
using MrKWatkins.OakAsm.Z80;
using static MrKWatkins.OakAsm.Z80.Z80Assembly;

var source = new Source(
    ORG(0x6000),
        LD(BC, "STRING"),
    Label("LOOP"),
        LD(A, [BC]),
        CP(0),
        JR(Z, "EXIT"),
        RST10(),               // ZX Spectrum ROM: print the character in A.
        INC(BC),
        JR("LOOP"),
    Label("EXIT"),
        RET(),
    Label("STRING"),
        DEFB("Hello World"),
        DEFB(13, 0));

Z80Assembler.Instance.Assemble(source);

var output = new Output(source);    // output.Regions has the assembled bytes and their locations.

Memory operands use collection expressions — LD(A, [BC]) is LD A, (BC) — and labels are referenced by name, resolved at assembly time.

DEFB and DEFW take any number of values, so generated data can be passed straight through without unpacking it — DEFB(bytes) for a byte[] or span, DEFW(words) for ushorts. Both throw if given nothing to emit.

Parsing Assembly Text

using MrKWatkins.Ast.Position;
using MrKWatkins.OakAsm.Parsing;
using MrKWatkins.OakAsm.Z80;

var source = OakAsmParser.Parse(new TextFile("hello.asm", File.ReadAllText("hello.asm")));

Z80Assembler.Instance.Assemble(source);

if (source.ThisAndDescendentsHaveErrors)
{
    // Inspect source.ThisAndDescendentsWithErrors for details.
}

Supported Directives

Directive	Purpose
`ORG address`	Set the assembly location.
`EQU value`	Define a constant for the preceding label.
`DEFB value, ...`	Emit bytes or strings. `DEFM` is an alias, conventionally used for strings.
`DEFW value, ...`	Emit words.
`DEFS length[, fill]`	Reserve `length` bytes, filled with `fill` or zero. `DS` is an alias.
`ALIGN boundary`	Advance the location to the next multiple of `boundary`, filling with zeroes.
`INCLUDE "file.asm"`	Splice in another assembly file, relative to the including file. Available when assembling projects.
`INCBIN "file.bin"`	Place the bytes of a binary file in the output as-is, relative to the including file. Available when assembling projects.
`END [entry point]`	End of source, with an optional entry point given as an address or a label. Nothing after `END` is emitted.

Expressions

Instruction and directive arguments can be expressions over numbers, labels and $, the current location:

        ORG $8000
Start:
        LD HL, Table + 2 * 4
        LD A, 0b00001111 & Mask     ; See operators below.
        JR $                        ; Jump to self.
Finish:
Size:   EQU $ - Start
        DEFW Finish - Start

Operators, highest precedence first:

Operators	Meaning
`-` `~` (unary)	Negate, bitwise complement.
`*` `/` `%`	Multiply, divide, modulo.
`+` `-`	Add, subtract.
`<<` `>>`	Bit shifts.
`&`	Bitwise AND.
`^`	Bitwise exclusive OR.
`\\|`	Bitwise OR.

Brackets group sub-expressions, but an argument starting with an open bracket is a memory reference — LD A, (Base + 1) reads memory, LD HL, Base + 1 is address arithmetic.

$ evaluates to the location of the containing instruction, so JR $ jumps to itself. Constant expressions for relative jumps, e.g. JR 5, are raw displacements; expressions involving labels or $ are target addresses and the displacement is calculated for you, with an error if the target is out of range.