MrKWatkins.OakAsm.IO.ZXSpectrum 0.8.7

OakAsm

An assembler for 8-bit systems. Designed for generating assembly via C# code but also supports parsing and formatting assembly files.

OakAsm currently targets the Z80 and the Z80N, the extended Z80 found in the ZX Spectrum Next. Documentation is at mrkwatkins.github.io/OakAsm.

Installing

dotnet add package MrKWatkins.OakAsm.Z80                 # Z80 library.
dotnet add package MrKWatkins.OakAsm.Z80N                # ZX Spectrum Next library.
dotnet tool install --global MrKWatkins.OakAsm.Tool      # The oakasm command line tool.

Building Assembly from C#

Z80Assembly has a strongly-typed builder method for every instruction and directive:

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.

Assembling Files

Describe a project in YAML:

cpu: z80
sections:
  - org: "0x6000"
    sources:
      - "*.asm"
outputs:
  - format: binary
    file: "Output.bin"

Then assemble it with the command line tool:

oakasm assemble MyProject.yaml

The tool can also disassemble ZX Spectrum snapshots back to assembly with oakasm disassemble.

Packages

Use of AI

My general rule is I'll write the interesting bits and use AI for the boring bits. I wrote the bulk of the code, but then used AI to get it ready for release, or it would never have been done... So the project files, last few assembler features, finishing off the console tools and the documentation was mainly AI generated.

Licensing

OakAsm is licensed under the GPL v3.0. The test suite uses some files found in the wild:

• A snapshot of Hungry Horace by Psion Software Ltd. and published by Sinclair Research. According to World of Spectrum's publisher permissions, Sinclair allow distribution of their published games for non-profit purposes. The original snapshot was taken from archive.org but tweaked slightly so the program counter starts at the start of the program; the original starts slightly later.
• A binary of ZEXALL, Frank Cringle's Z80 instruction set exerciser, used to test the disassembler. ZEXALL is distributed under the GNU General Public License; its inclusion here as an unmodified test input does not affect the licensing of OakAsm itself.