Z80 Assembler User Help

This document describes the source language accepted by the assembler from an end-user point of view: source line structure, labels, expressions, instructions, directives, macros, conditional assembly, segments, and common usage patterns.

1. Basic line structure

A source line may contain a label, an instruction or directive, operands, and a comment.

label: opcode operand1, operand2 ; comment

Whitespace is flexible. Empty lines are allowed. Comments begin with ; and continue to the end of the line.

START: LD A,1 ; load constant into A

2. Case and naming

Mnemonics, directives, registers, conditions, and labels are case-insensitive. Source may be written in upper case, lower case, or mixed case.

ld a,1
LD A,1

Labels may use letters, digits, underscore, and hyphen. A label normally ends with a colon.

loop:
copy_1:
my-label:

For clarity and portability of source style, use the colon form consistently.

3. Registers and addressing forms

Common 8-bit registers are supported: A B C D E H L.

Common 16-bit register pairs are supported: BC DE HL SP AF IX IY.

Special registers used by some transfer instructions are supported: I and R.

Indexed high and low halves are supported: IXH IXL IYH IYL.

Typical memory addressing forms include:

(HL)
(BC)
(DE)
(1234H)
(IX+5)
(IX-2)
(IY+3)

Indexed displacements must fit in signed 8-bit range.

4. Numbers and character strings

Numbers may be written in decimal, hexadecimal, or binary forms.

123
$7B
0x7B
7Bh
%1010
1010b

Character strings may be written in double quotes or single quotes.

"HELLO"
'A'

Escape sequences such as newline and tab are accepted in string literals.

5. Expressions

Operands and directive arguments may use expressions. The current location counter is written as $.

LD A,VALUE+1
JP START+$10
DW $

Low-byte and high-byte extraction are available with prefix operators.

DB <LABEL
DB >LABEL

Named helpers such as lsb() and msb() may also be used.

DB lsb(LABEL), msb(LABEL)

Arithmetic and expression functions may be used in constants, address calculations, and conditional assembly.

6. Instructions

The assembler supports normal Z80 instruction families including data transfer, arithmetic, logic, shifts and rotates, bit operations, calls, jumps, returns, block instructions, interrupt control, and indexed addressing.

Examples:

LD A,B
LD HL,$8000
LD (IX+1),A
ADD A,10
ADC HL,DE
BIT 3,(IY+2)
SET 5,A
JP NZ,LOOP
JR C,NEXT
DJNZ AGAIN
IN A,(10H)
OUT (C),A

Relative branches such as JR and DJNZ must reach a target within relative branch range.

7. Conditions

Conditional instruction forms use the standard Z80 conditions:

NZ Z NC C PO PE P M

Examples:

JP Z,DONE
CALL NC,HANDLER
RET M

8. Symbol definition

Constants may be defined with EQU or =.

BUFFER_SIZE EQU 64
SCREEN = $4000

Use symbolic names for addresses, constants, bit positions, and structure offsets.

9. Data definition directives

DB defines bytes. Strings in DB expand to one byte per character.

DB 0,1,2,"ABC"

DW defines 16-bit words.

DW START,BUFFER,1234H

DS reserves storage.

DS 32
DS 16,0

FCB is a byte-definition alias. FDB is a word-definition alias. RMB is a reserve-storage alias.

BSZ and ZMB reserve zero-filled storage.

BSZ 64
ZMB 128

FILL repeats one value a given number of times.

FILL 0FFH,16

10. String-oriented directives

.CSTR emits characters followed by a trailing zero byte.

.CSTR "READY"

.PSTR emits a length byte followed by the characters.

.PSTR "HELLO"

.ISTR emits characters in high-bit terminated form, suitable for software conventions that mark the last character.

.ISTR "NAME"

11. Repetition shorthand

A repeated data form may be written with DUP(...).

DB 8 DUP(0)
DW 4 DUP($FFFF)

This is useful for buffers, tables, and padding.

12. Origin and layout control

ORG sets the assembly location.

ORG $8000

ALIGN advances the location counter to the next alignment boundary.

ALIGN 16

Use these directives to control program placement, tables, vectors, and page boundaries.

13. Segments

The assembler supports code and data segmentation directives.

.CSEG
.DSEG
.ESEG
.BSSEG

Use .CSEG for executable code, .DSEG for initialized data, and .BSSEG for uninitialized storage. Keep segment usage consistent within a project.

14. Phase control

.PHASE temporarily changes the logical assembly address without permanently changing the underlying placement, and .DEPHASE ends that phase.

.PHASE $0100
.DEPHASE

This is useful for code that runs at one logical address but is stored elsewhere.

15. Conditional assembly

Conditional assembly is available with IF, IFN, ELSE, and ENDIF.

IF DEBUG
DB "TRACE"
ELSE
DB 0
ENDIF

IFN assembles the following block when the expression is false or zero.

Use straightforward, fully resolvable expressions in conditional assembly. Avoid nesting conditional blocks.

16. Include files and binary inclusion

.INCLUDE inserts another source file.

.INCLUDE "macros.inc"

.INCBIN inserts raw binary data from a file.

.INCBIN "sprite.bin"

Use include files for shared constants, macros, device definitions, and common routines.

17. Macros

Define a macro with .MACRO and end it with .ENDM.

.MACRO PUSHALL
PUSH BC
PUSH DE
PUSH HL
.ENDM

Invoke a macro by writing its name as an instruction.

PUSHALL

Macro arguments are referenced as %%1, %%2, and so on.

.MACRO LOAD8
LD %%1,%%2
.ENDM

LOAD8 A,10

18. Repeated macro blocks

.REPT repeats a block a fixed number of times and uses .ENDM to terminate the repeated block.

.REPT 4
DB 0
.ENDM

19. Local scoping with blocks

.BLOCK and .ENDBLOCK create a local block scope for labels.

.BLOCK
LOCAL1: NOP
.ENDBLOCK

A label that begins with @ may be used when a label needs to remain visible outside the current block.

@ENTRY:

20. End of source

Use END or .END to mark the logical end of the source file.

END

21. Common aliases

Several directive names are accepted as aliases.

DEFB, .DB, .BYTE  -> DB
DEFW, .DW         -> DW
DEFS, .RES        -> DS

Use one naming style consistently within a project.

22. Practical example

ORG $8000

COUNT   EQU 10
BUFFER  EQU $9000

START:  LD HL,BUFFER
        LD B,COUNT
LOOP:   LD (HL),0
        INC HL
        DJNZ LOOP
        JP DONE

DONE:   .CSTR "OK"
        END

23. Good usage advice

Prefer explicit labels with a trailing colon.

Keep one instruction or directive per line.

Use symbols instead of hard-coded addresses whenever possible.

Use DB for bytes, DW for 16-bit values, and DS or reserve aliases for storage.

Use JR and DJNZ only when the destination is known to be in relative range.

Use .BLOCK to keep local labels tidy in larger modules.

Keep conditional assembly simple and non-nested.

Use include files for project-wide constants and macros.

24. Minimal template

ORG $8000

MAIN:   NOP
        JP MAIN

END