Instructions

FantASM assembles the full Z80 instruction set, the undocumented instructions, the thirty Z80N additions, and two CSpect pseudo-instructions. This page is about what it accepts and what you have to turn on — for what each instruction does to the flags and how long it takes, see the references at the bottom.

What is always available

The documented Z80 set, and the undocumented instructions with it — no flag, no option:

    sll b               ; CB 30
    sll (ix+4)          ; DD CB 04 36
    inc ixh             ; DD 24
    dec iyl             ; FD 2D

SLL and the IXH/IXL/IYH/IYL halves are assembled as readily as anything else. Nothing warns about them, so a typo that happens to be a valid undocumented instruction assembles.

Turning on Z80N

The Next’s thirty extra instructions are off unless you ask:

Error [E1016]: Z80n extended instructions are not enabled

Three ways to ask, all equivalent:

fantasm build main.asm -N
fantasm build main.asm -t zxnext        # the machine implies the CPU

    opt z80n on

target = "zxnext" or z80n = true in fantasm.toml do the same. Any of them and nextreg 7,3 assembles to ED 91 07 03.

Turning on the CSpect pseudo-instructions

break and exit are instructions to an emulator, not to a CPU:

They need -c, cspect = true, or opt cspect on, and are E1019 without.

⛔ They are real bytes in your image. On hardware FD 00 and DD 00 are a prefix followed by NOP, so they cost time and do nothing rather than being stripped. Take them out before you ship.

Writing an operand

Mnemonics and register names are case-insensitive. LD A,1, ld a,1 and Ld A,1 are the same three bytes. Your own names are not — see Writing Source.

An index displacement may be negative, and is a signed byte:

    ld  a,(ix-3)        ; DD 7E FD
    ld  (iy+10),b

A port may be computed, in either direction:

    out (0x80-0x10),a   ; D3 70
    in  a,(0x80-0x10)   ; DB 70
    in  a,(c)           ; ED 78
    out (c),a           ; ED 79

Z80N instructions take their operands written out. mul d,e is the form; a bare mul is E1005, though some assemblers accept it.

⛔ Condition codes are reserved words, and so are single letters. m, p, z, c, nc are condition codes; b, c, d, e, h, l, a are registers. A label or macro parameter with one of those names produces a diagnostic that says nothing about registers — the list is in Diagnostics.

ex af,af' is written with the apostrophe and needs no escaping.

Where the details are

What an instruction does — flags, timing, edge cases — is documented against measured hardware, not restated here.

• Bizmuth’s Z80N reference gives opcode, T-states, operation and flags for all thirty, taken from a T-state-for-T-state comparison against a simulation of the FPGA design. Several published descriptions disagree with it and are listed there.
• Machine timing covers contention and the rest of what a cycle count means in practice.

FantASM’s own docs/instructions.md, which travels with the source, holds the encoding table — the bit patterns and byte sequences the assembler emits for all 268 forms, including the operand notation. That is the assembler’s business and the one place it is written down.

⛔ Two copies of a flag table drift. FantASM’s once said ADD HL,A set no flags when it clears carry, and the correction came from the measured data. Nothing here restates a flag or a T-state count for that reason.

Timing, and where it is used

FantASM carries its own timing figures, which is what makes these work:

• assert_cycles in a !test fails the build when a routine grows past a budget — see Testing.
• Hover in an editor answers Timing: 12/7 T-states (taken/not taken) — see The Language Server.
• tstates in an expression is the running total since assembly started.

What next

• Writing Source — what may appear in an operand once it is an expression.
• Testing — checking a routine’s cycle count rather than counting by hand.
• Memory and Banking — what nextreg is usually doing.

← Documentation