z80asm

README

Z80 Assembler

This repository contains a z80 assembler, both as a command-line tool, and as a library. It currently is somewhat limited, both in assembler features (for example, there's no macros), and can currently only output ZX-Spectrum .sna files. But the assembler does implement the full (standard) z80 instruction set.

The code is MIT licensed, and the details can be found in LICENSE.txt.

Syntax

Assembler instructions are case-insensitive, with destination registers (or addresses) appearing before source when applicable. Hex numbers can be used, and are written with a 0x prefix.

For example:

ld a, 42
jp label
ld b, 0x10

Multiple instructions may be written on one line, by separating them by ;.

ld a, 42 ; inc a

Indirection uses regular brackets (). For example:

ld hl, (123)
sub (hl)
ld (hl), d

Indirection via ix and iy use syntax like this: (ix+4). For example:

ld (ix+4), 42

Comments use // or /* ... */ (which don't nest). For example, this code generates the single instuction ld a, (de):

/* The next two instructions are commented out.
ld a, 42
ld b, 42 */
ld a, (de) // This is a comment

Labels are written in one of two forms: a name followed by a colon, or a dot followed by a name. The label: form denotes a major label, and the .label form denotes a minor label. Minor labels are relative to the most recent major label, and can only be accessed in that scope. This allows minor labels to be reused.

For example:

f:
    ld bc, 42
.loop
    djnz loop
g:
    ld bc, 102
.loop
    djnz loop

This defines two major labels f and g and two minor labels, both called loop.

A special label main: defines the entrypoint for the code.

Where applicable, constants may be expressions written in C (or equivalently go) syntax. For example:

ld a, 4+10

There are several assembler directives: org which speficies where to assemble, and db, dw, ds which allow literal bytes, words (16 bits, written low-byte first), and strings. For example:

org 0x9000
db 1, 2, 3
dw 0x1234
ds "hello\n"

This causes the following bytes to be generated at and beyond memory location 0x9000:

1, 2, 3, 0x34, 0x12, 'h', 'e', 'l', 'l', 'o', 0x0a

A two-value variant of org allows the PC and target memory to be specified separately that may be useful if there is a larger amount of RAM that can be paged in via a memory map, for example like that on the Spectrum Next.

org 0x9000, 0xff0000
.label
db 1, 2, 3, 4
dw label

This causes the following bytes to be generate at memory location 0xff0000:

1, 2, 3, 4, 0x00, 0x90

Named constants can be defined with const, and used thereafter:

const x = 0xabcd
dw x & 0xf0f0

If you want the length of a string (for example as an 8-bit value), you can use label arithmetic. Note that it is fine to refer to labels before they appear:

db endhello - hello
.hello ds "hello\n"
.endhello

This generates the bytes: 6, 'h', 'e', 'l', 'l', 'o', 0x0a.

Documentation

Overview

Package z80asm contains a text-based z80 assember. The format of input files can be found in the README.md file.

Index

• type Assembler
  • func NewAssembler(opts ...AssemblerOpt) (*Assembler, error)
  • func (asm *Assembler) AssembleFile(filename string) error
  • func (asm *Assembler) GetConst(c string) (int64, bool, error)
  • func (asm *Assembler) GetLabel(majLabel, l string) (uint16, bool)
  • func (asm *Assembler) RAM() []uint8
• type AssemblerOpt
  • func UseNextCore(core Z80Core) AssemblerOpt
• type Z80Core

Types

type Assembler

type Assembler struct {
	// contains filtered or unexported fields
}

An Assembler can assemble Z80 instructions into RAM.

func NewAssembler

func NewAssembler(opts ...AssemblerOpt) (*Assembler, error)

NewAssembler constructs a new assembler. By default, the assembler will assemble code starting at address 0x8000.

func (*Assembler) AssembleFile

func (asm *Assembler) AssembleFile(filename string) error

AssembleFile reads the named file, and assembles it as z80 instructions.

func (*Assembler) GetConst

func (asm *Assembler) GetConst(c string) (int64, bool, error)

GetConst returns the value of the given const. It is only valid after the assembler has run.

func (*Assembler) GetLabel

func (asm *Assembler) GetLabel(majLabel, l string) (uint16, bool)

GetLabel returns the value of the given label. It is only valid after the assembler has run.

func (*Assembler) RAM

func (asm *Assembler) RAM() []uint8

type AssemblerOpt

type AssemblerOpt func(*assemblerOption) error

func UseNextCore

func UseNextCore(core Z80Core) AssemblerOpt

UseNextCore include Z80N opcodes for the given core.

type Z80Core

type Z80Core int

const (
	Z80CoreStandard Z80Core = 0
	Z80CoreNext1    Z80Core = 1
	Z80CoreNext2    Z80Core = 2
)