Tool Z80asm

Tool — z80asm

Agent essentials

PHASE expression … DEPHASE

Assemble bytes at the current storage PC (the section, as the linker will place it). Resolve labels and $ / ASMPC as if ORG expression were in effect.

Wiki: Tool — z80asm — directives. Source: src/z80asm/src/c/directives.c (asm_PHASE / asm_DEPHASE), codearea.c (asmpc_phase).

The linker has no knowledge of PHASE. It is assembly-time only.

That split guarantees the PHASE’d code cannot run where it is stored. Runtime must copy it to expression (typically ldir) before call / jp to those labels. jr still works (relative offset is the same in both spaces). call / jp to a PHASE label go to the run address, not the storage address.

    ld  hl, start          ; storage address (relocatable)
    ld  de, $8000          ; run address
    ld  bc, end-start      ; size of the PHASE’d bytes
    ldir
    jp  $8000
start:
    PHASE $8000
f1: ...                    ; f1 = $8000 (const), bytes sit at start
    DEPHASE
end:

ROM-resident / in-situ code (runs at its storage address: shell, FAT, IDE that is not LDIR’d) must not sit inside PHASE. Put it in another file/SECTION with no PHASE, or after DEPHASE in the same file. A second source with its own SECTION does not inherit a PHASE origin from an INCLUDE into a PHASE’d file.

PHASE / DEPHASE reset module-local @ labels. PHASE address is 0…$FFFF. Nested PHASE replaces the phase PC; DEPHASE ends phasing for the section (logical $ = storage PC again).

Synthetic opcodes (normal mode)

Assembler sugar expanded to real ops (no harmful flag/side effects for the documented forms). Strict / -no-synth forbids free synthetics.

16-bit register-pair copies (full set) — two 8-bit lds each:

Prefer these over hand two-byte moves and over swap dances when parking one pair (ld bc,hl … work … ld hl,bc). Same family on 8080/8085/z80/z80n/z180/gbz80 (and related) in normal mode — coding rules still differ per cpu-* skill.

Other examples: ld a,(hl+) (load + inc). Listings (-l) show the expansion.

CPU capability fixtures (how to read them)

Question these answer: “If I assemble this source line with z88dk-z80asm -m<cpu>, does the assembler accept it, and what does it emit?”

That is assembler acceptance, not a human ISA manual and not always a single native chip opcode. Library coding rules (e.g. 8085 stack-only, prefer true extended ops) can be stricter than “assembler accepts.”

Where

Tree path (always prefer this checkout):

src/z80asm/dev/cpu/

Same on GitHub: https://github.com/z88dk/z88dk/tree/master/src/z80asm/dev/cpu

Generated from opcode tables (make in that dir rebuilds them). Treat as last resort when skills or external opcode sites disagree with the toolchain.

Which file for which CPU

Default library / zcc work uses the non-strict pair matching -m (synthetics allowed). Use *_strict_* only when checking strict assemble rules.

Strict mode (*_strict_*)

strict means the assembler is run in strict mode: synthetic opcodes are forbidden.

Still legal in strict if they are real CPU ops (or accepted aliases of real ops), e.g. on 8085:

• sub hl,bc → ; 08 (extended)
• ld de,sp+0 → ; 38 00 (extended; Intel alias ldsi exists for compat only)
• ld de,hl+0 → ; 28 00 (extended LDHI — not the synthetic ld de,hl pair copy)

Strict rejects forms that only exist as assembler sugar, e.g. on 8085 strict: ld de,hl and ld (de),l → Error (see cpu_test_8085_strict_err.asm).

CLI: strict corresponds to the assembler’s strict CPU / no-synth-style path (fixtures are the ground truth; also note general -no-synth in help for disabling synthetics on non-strict runs).

Mnemonics: Zilog everywhere; Intel only for external compatibility

z88dk prefers Zilog mnemonics everywhere (library, CRT, examples, agent-written asm). Emit ld, jp, add a,*, … — not MOV / JMP / ADI.

z80asm also accepts Intel mnemonics on 8080/8085 (and lists them in fixtures, especially *_strict_ok.asm) for compatibility with external / third-party sources, not as a z88dk house style.

When bringing external Intel-syntax asm into this tree, translate to Zilog. Do not write new z88dk sources in Intel mnemonics because the assembler would accept them.

Line format (both ok and err)

One instruction form per line, columns loosely:

<asm source form>                 ; <result>

On *_ok.asm, <result> is the expected encoding, for example:

On *_err.asm:

exx                             ; Error

Means: with that -m CPU, this form is illegal — assembler must reject it. Do not emit it in sources for that CPU.

How to query (do not bulk-read)

*_err.asm files are huge (tens of thousands of lines). Never read whole fixtures into context.

# Is this form accepted on 8085? What encoding?
rg -n 'sub hl, *bc|ld de,sp\+|ld \(de\),hl|exx' \
  src/z80asm/dev/cpu/cpu_test_8085_ok.asm \
  src/z80asm/dev/cpu/cpu_test_8085_err.asm

# Compare CPUs for one mnemonic
rg -n '^\s*mul de|^\s*mlt de' \
  src/z80asm/dev/cpu/cpu_test_z80_ok.asm \
  src/z80asm/dev/cpu/cpu_test_z80n_ok.asm \
  src/z80asm/dev/cpu/cpu_test_z180_ok.asm

Interpretation checklist:

1. Only in *_err.asm (for the mode you care about) → do not use.
2. Normal *_ok.asm + short hex → native or allowed synthetic.
3. Normal *_ok.asm + @__z80asm__… → helper call; usually avoid as the core of hand-written hot library code.
4. Strict *_ok.asm → real ops / accepted aliases only; no free synthetics.
5. Strict *_err.asm → includes many forms that normal mode still accepts (synthetics).
6. Same mnemonic, different CPUs → encodings differ; check the file for that -m.
7. 8080/8085 fixtures may list Intel spellings for external-compat tests; z88dk tree code uses Zilog only.

Worked examples (8085)

Decision order when unsure

1. Matching cpu skill (coding rules / house style).
2. Neighbour sources under libsrc/ for that CPU.
3. These fixtures (rg only) to settle assembler accept/reject and encoding class.
4. Optional: assemble a one-liner with z88dk-z80asm -m<cpu> -l and read the .lis.

Condensed reference (from wiki / tree)

Tool — z80asm (z88dk-z80asm)

z80asm is the z88dk relocatable macro assembler, linker, and librarian. It is not the same project as other tools named “z80asm” on the internet.

Normally you call it through zcc. Use the binary directly for pure asm projects, libraries, or debugging the link step.

Quick start

z88dk-z80asm file.asm
z88dk-z80asm -b file.o
z88dk-z80asm -xlibname.lib file1.o file2.o
z88dk-z80asm -h

Via zcc, assembler flags pass through -Ca.

Capability summary

Subpages (detail)

When a subpage disagrees with z88dk-z80asm -h or src/z80asm/, the tool and source win.

… (full reference: in-tree wiki page and live tool help)

Related

• Driver front end: tool-zcc
• Measurement: methodology-measure, tool-ticks
• Per-CPU coding skills: cpu-8085, cpu-z80, cpu-z80n, cpu-z180, cpu-8080, cpu-gbz80 (capability authority remains src/z80asm/dev/cpu/)