Instructions, Data and Storage

Atom accepts the complete documented Z80 instruction set together with the classic undocumented forms listed in the instruction reference. It rejects operand combinations that the processor cannot encode.

Instruction families

The supported surface includes base, CB, ED, DD, FD, DDCB, and FDCB encodings:

LD A,(HL)
ADC HL,DE
BIT 3,(IX+2)
LD I,A
LDIR
SET 6,(IY-1)

Atom also accepts the classic undocumented index-half registers IXH, IXL, IYH, and IYL. SLL and SLS are two names for the same undocumented shift operation.

Branch width remains explicit. Atom never changes JR into JP. A forward JR whose final displacement lies outside −128 through 127 is an error.

Enumerated fields are checked:

• BIT, RES, and SET accept bit numbers 0 through 7;
• RST accepts 0, 8, 16, 24, 32, 40, 48, or 56; and
• IM accepts 0, 1, or 2.

The DD/FD rules follow the processor's real encodings. LD A,IXH and LD IXH,IXL are valid. LD IXH,H is not encodable. In LD H,(IX+1), the destination is the ordinary H register, not IXH.

The Z80 instruction reference lists the exact standard and classic-undocumented forms accepted for each mnemonic.

DB — define bytes

DB emits comma-separated numeric expressions and double-quoted byte strings:

DB 0,$FF,%10101010
DB "ATOM",0
DB 'A','Z'

Each numeric result contributes its low byte. A forward affine expression is resolved when its symbol is declared.

String escapes are \0, \n, \r, \t, \', \", \\, and \xHH. Strings and numeric items may share one list.

DW — define words

DW emits each expression as a 16-bit little-endian word:

DW 1234H              ; EMITS $34,$12
DW START,TABLE+2

Strings are not accepted. A forward affine expression is resolved to a little-endian word when its symbol is declared.

DS — reserve or fill storage

DS COUNT advances the logical cursor without emitting IMAGE bytes:

BUFFER:
    DS 64

DS COUNT,FILL emits COUNT initialized bytes:

PAGE:
    DS 256,0

Both operands must already be resolved. Count and capacity are checked before the first output operation, so a failed directive publishes no partial span.

Uninitialized reservations still affect later labels, the output length, listing rows, and D8 source ranges. The command-line hosts use zero bytes for their BIN and HEX materialisation; the JavaScript API can select another fill value. The span remains part of the materialised output image.

ALIGN

ALIGN BOUNDARY emits zero bytes until the cursor reaches the next address divisible by the boundary:

ALIGN 16
TABLE:
    DB 1,2,3,4

The boundary is a resolved positive value and need not be a power of two. An already aligned address emits no byte.

String directives

Three directives state a string's storage convention directly:

CSTR "READY"     ; BYTES FOLLOWED BY $00
PSTR "NAME"      ; LENGTH BYTE FOLLOWED BY BYTES
ISTR "TOKEN"     ; BIT 7 SET ON THE FINAL BYTE

CSTR and PSTR accept decoded payloads of at most 255 bytes. CSTR adds its terminator to the output-capacity requirement. ISTR "" emits nothing; a non-empty payload receives bit 7 on its last byte.

Each directive requires one double-quoted string and accepts the same escapes as DB.

INCBIN

INCBIN emits bytes from a binary file as initialized data:

FONT: INCBIN "FONT.BIN", 2048

The optional second operand is a byte count. It must be a numeric literal and selects that many bytes from the start of the file. A count of zero is allowed. Node accepts INCBIN "PATH" without a count and emits the complete file. CP/M requires the count, so a source that must assemble on both hosts should give one.

On Node, the path is relative to the source file containing the directive. It must use ASCII, resolve inside the project root, and match the filename's capitalisation. Symlink targets outside the root are rejected. One binary may contain 0 through 65,535 bytes. Atom reads the selected bytes before assembly, so one build uses one stable copy of the file. During source preparation, Atom replaces the line with an equal-length reservation for address calculation and attaches the saved bytes to the resulting output. Listings and D8 maps retain the original INCBIN line.

On CP/M, the name is a current-drive 8.3 filename and Atom reads the file's records in sequence during assembly. CP/M stores files in 128-byte records, so padding in the final record cannot be told apart from data. The count decides how many bytes are used. One CP/M assembly may have at most 32 active INCBIN statements. The CP/M guide gives the details.

Directive summary

The assembler reserves the bare words EQU, ORG, DB, DW, DS, ALIGN, INCBIN, CSTR, PSTR, and ISTR. Dotted aliases are invalid. The complete table appears in the directive reference.