A Motorola 68000 assembler, disassembler and virtual machine, written in Go.
| Package | Description |
|---|---|
assembler |
Assembles MC68000 source into big-endian machine code |
disassembler |
Disassembles flat binaries back into readable assembly |
cpu |
Shared definitions: opcodes, addressing modes, status flags |
vm |
Virtual machine that loads and executes assembled programs |
system |
System call interface (stub, for future expansion) |
cmd/
├── asm68 Assembler
├── dis68 Disassembler
└── run68 Code runner / VM frontend
Assembles one or more source files into a flat binary.
asm68 -o output.bin input.asm # write binary to file
asm68 input.asm # assemble and hexdump to stdout
asm68 -o output.bin part1.asm part2.asm # concatenate sourcesDisassembles a flat binary into MC68000 assembly.
dis68 input.bin # print disassembly to stdout
dis68 input.bin output.asm # write disassembly to fileThe disassembler performs control-flow analysis to separate code from data,
emits labels for branch targets and subroutine entry points, and resolves
PC-relative references to label names. Data regions are emitted as dc.b
hex byte directives.
Loads and executes a program in the virtual machine.
run68 program.asm # assemble and run
run68 -load 0x1000 program.bin # load binary at address
run68 -d0 FF -a0 2000 program.asm # set initial registers (hex)
run68 -cycles 5000 program.asm # limit executionThe VM provides 16 MB of RAM. Execution halts on rts or trap #15.
- Full MC68000 instruction set including all 12 standard addressing modes
- Labels, forward references and automatic PC-relative encoding
SPalias forA7in all contexts (operands, register lists)- Directives:
.org,dc.b,dc.w,dc.l,ds.b,ds.w,ds.l,even - Comment syntax:
;and* - Multi-pass sizing with label stabilisation
- Linear sweep followed by control-flow analysis
- Dead code recovery for instructions after unconditional branches
- Automatic labelling:
sub_XXXXfor subroutine targets,loc_XXXXfor branches - PC-relative operands resolved to bare label references
- Data regions emitted as even-aligned
dc.blines for round-trip fidelity - Big-endian input (native M68k byte order)
Both packages expose a minimal public interface:
// Assembler
code, err := assembler.Assemble(source, baseAddress)
code, err := assembler.AssembleFile("input.asm", 0)
// Disassembler
text, err := disassembler.Disassemble(code)
text, err := disassembler.DisassembleFile("input.bin")
// Single-instruction decoding
mnemonic, operands, extBytes := disassembler.Decode(opcode, pc, extensionBytes)See docs/architecture.md for internals.
go build ./cmd/asm68
go build ./cmd/dis68
go build ./cmd/run68Or build all at once:
go build ./...go test ./...The examples/ directory contains demonstration programs:
| File | Description |
|---|---|
hello.asm |
Writes "Hello, World!" to memory using a byte-copy loop |
fibonacci.asm |
Computes Fibonacci numbers and stores them in a table |
bubblesort.asm |
Sorts an array of words using bubble sort |
main.asm |
Simple addition — runs in the VM (run68) |
full.asm |
Catalogue of all addressing modes and instruction groups |
The VM currently implements a subset of the MC68000 instruction set (see
docs/architecture.md). Most examples are designed to
demonstrate the assembler and disassembler. Use main.asm for a working VM
demo.
Assemble and disassemble an example:
asm68 -o /tmp/hello.bin examples/hello.asm
dis68 /tmp/hello.binRun the VM-compatible example:
run68 examples/main.asm.
├── assembler/ Assembler package
├── cpu/ CPU definitions (opcodes, modes, flags)
├── disassembler/ Disassembler package
├── vm/ Virtual machine
├── system/ System call stubs
├── cmd/
│ ├── asm68/ Assembler CLI
│ ├── dis68/ Disassembler CLI
│ └── run68/ VM runner CLI
├── tests/ Integration tests
├── examples/ Example programs
└── docs/ Technical documentation
MIT — see LICENSE.