Skip to content

Directives

Failure

Most content is IA generated and not yet proofreaded. However all examples are unit-tested

LIST, NOLIST

Synopsis:

LIST
NOLIST

Description: Control assembly listing output. LIST enables listing generation, NOLIST disables it. Useful for hiding macro expansions or repetitive code from listings.

Example:

    ; LIST/NOLIST directives
    list        ; Enable listing

    org $4000
    ld a, 5

    nolist      ; Disable listing
    ld b, 10
    list        ; Re-enable listing

    ret

ALIGN

Synopsis:

ALIGN boundary

Description: Align the assembly address to the specified boundary. Pads with zeros until the address is a multiple of the boundary value.

Example:

    ; ALIGN directive
    org $4000

    db 1, 2, 3

    align 256   ; Align to next 256-byte boundary

    db 4, 5, 6
    ret

CONFINED

Synopsis:

CONFINED
  ... code/data ...
ENDCONFINED

Description: Confine a memory area of 256 bytes maximum in such a way that it is always possible to navigate in the data by only modifying the low byte address (i.e INC L always works).

Example:

    ; CONFINED directive
    org $4000

    confined
        ; This data is confined to 256 bytes
        ; Can navigate with INC L without overflow
        db 0, 1, 2, 3, 4, 5, 6, 7, 8, 9
    endconfined

    ret

ORG

Synopsis:

ORG address

Description: Set the assembly address. Code will be placed at this address in memory.

Example:

    ; ORG directive - set assembly address
    org $4000
    ld a, 5
    ret

    ; Move to another address
    org $8000
    ld b, 10
    ret

LIMIT

Synopsis:

LIMIT address

Description: Set an upper limit for the assembly address. Assembly will fail if code exceeds this address. Works on the code space ($), not physical space ($$).

Example:

    ; LIMIT directive
    org $4000
    limit $4100  ; Fail if code exceeds this address

    ; This code fits within the limit
    ld a, 5
    ld b, 10
    ret

PHASE, DEPHASE

Synopsis:

PHASE address
  ... code ...
DEPHASE

Description: Assemble code as if it were at a different address (relocation). Code is written to current $ but assembled as if at the PHASE address.

Example:

; https://k1.spdns.de/Develop/Projects/zasm/Documentation/z71.htm
    org 0x100

label_100
    nop
label_101

    assert $$ == 0x101
    assert $ == 0x101

    phase 0x200

    assert $$ == 0x101
    assert $ == 0x200

label_200
    nop
label_201

    dephase
label_102

    assert label_100 == 0x100
    assert label_101 == 0x101
    assert label_102 == 0x102
    assert label_200 == 0x200
    assert label_201 == 0x201

RORG

Synopsis:

RORG address
...
REND

Description: Relocatable ORG. Similar to PHASE but for relocatable code. Sets both physical and logical address. RORG must be closed with REND to return to normal addressing mode.

Example:

    org $4000

    ; Code assembled at $4000
    ld a, 1

    ; Use RORG to relocate
    rorg $8000
        ld b, 2

    rend

PROTECT

Synopsis: 

PROTECT START, STOP
Description: Mark the memory between START and STOP as protected against write. Assembler fails when writting there.

On the code space ($), not physical space ($$)

Example: 

    org 0x4000

    protect 0x8000, 0xbfff

    defb "No memory issue"

RANGE/DEFSECTION

Synopsis:

RANGE start, stop, name
DEFSECTION start, stop, name    ; alias for RANGE

Description: RANGE (and its alias DEFSECTION) allows to define named portions of the memory. Takes start address, stop address, and section name.

Example with DEFSECTION: 

    ; DEFSECTION is an alias for RANGE - Syntax: DEFSECTION start, stop, name
    defsection $4000, $8000, code_section
    defsection $8000, $9000, data_section

    ; Now use the sections
    section code_section
    ld a, 5
    ret

    section data_section
    db 1, 2, 3, 4, 5

SECTION

Synopsis:

SECTION name

Description: SECTION allows to choose which portion of memory to use. The section must have been previously defined with RANGE or DEFSECTION.

Example: 

; sarcasm inspiration https://www.ecstaticlyrics.com/electronics/Z80/sarcasm/

range $0080, $3FFF, code
range $4000, $7FFF, data

section code
  ld hl, message_1
  call print_message

section data
message_1: db "This is message #1.", $00

section code
  ld hl, message_2
  call print_message

section data
message_2: db "This is message #2.", $00

section code
  print_message: 
    ld a, (hl)
    or a
    ret z
    call 0xbb5a
    inc hl
    jr print_message

    assert section_start("data") ==  0x4000
    assert section_length("data") == 0x4000
    assert section_used("data") == 40

BANK

Description:

When used with no argument, a bank corresponds to a memory area outside of the snapshot. All things read&write in memory are thus uncorrelated to the snapshot. Sections do not apply in a bank.

BANK page is similar to WRITE DIRECT -1 -1 page

Synopsis:

BANK [EXPRESSION]

Example: 

    ; Set up a unique value in various banks
    BANK 0xc0
    org 0x4000 + 0
    db 0xc0

    BANK 0xc4
    org 0x4000 + 1
    db 0xc4


    BANK 0xc5
    org 0x4000 + 2
    db 0xc5

    BANK 0xc6
    org 0x4000 + 3
    db 0xc6


    BANK 0xc7
    org 0x4000 + 4
    db 0xc7


    BANKSET 0
    assert memory(0x4000 + 0) == 0xC0 

    BANKSET 1
    assert memory(0x4000 + 2) == 0xC5
    assert memory(0x8000 + 3) == 0xC6
    assert memory(0xC000 + 4) == 0xC7

BANKSET

Synopsis:

BANKSET EXPRESSION

Example: 

    BANKSET 0

    org 0x0000
    db 1,2,3,4

    org 0x4000
    db 5,6,7,8

    org 0x8000
    db 9,10,11,12

    org 0xc000
    db 13, 14, 15, 16


    BANKSET 1
    org 0x0000
    db 10,20,30,40

    org 0x4000
    db 50,60,70,80

    org 0x8000
    db 90,100,110,120

    org 0xc000
    db 130, 140, 150, 160


    BANKSET 0
    assert memory(0x0000) == 1
    assert memory(0x4000) == 5
    assert memory(0x8000) == 9
    assert memory(0xc000) == 13

    save "good_bankset_0_0.o", 0x0000, 4
    save "good_bankset_0_1.o", 0x4000, 4
    save "good_bankset_0_2.o", 0x8000, 4
    save "good_bankset_0_3.o", 0xc000, 4

    BANKSET 1
    assert memory(0x0000) == 10
    assert memory(0x4000) == 50
    assert memory(0x8000) == 90
    assert memory(0xc000) == 130

    save "good_bankset_1_0.o", 0x0000, 4
    save "good_bankset_1_1.o", 0x4000, 4
    save "good_bankset_1_2.o", 0x8000, 4
    save "good_bankset_1_3.o", 0xc000, 4

WRITE DIRECT

Description: WRITE DIRECT is a directive from Winape that we have not fully reproduced. It's two first arguments need to be -1.

Example: 

    WRITE DIRECT -1, -1, 0xc0
    org 0x4000+0
    db 0xc0

    WRITE DIRECT -1, -1,  0xc4
    org 0x4000+1
    db 0xc4


    WRITE DIRECT -1, -1,  0xc5
    org 0x4000+2
    db 0xc5

    WRITE DIRECT -1, -1,  0xc6
    org 0x4000+3
    db 0xc6


    WRITE DIRECT -1, -1,  0xc7
    org 0x4000+4
    db 0xc7


    BANKSET 0
    assert memory(0x4000 + 0) == 0xC0 

    BANKSET 1
    assert memory(0x4000 + 2) == 0xC5
    assert memory(0x8000 + 3) == 0xC6
    assert memory(0xC000 + 4) == 0xC7

=, SET

Description:

Assign an expression to a label. Assignement can be repeated several times.

Synopsis: 

LABEL = EXPRESSION

Example: 

label = 1
label =3
.label=2

    assert label == 3


label = 5
    assert label == 5

label <<= 1
    assert label == 10

EQU

Description: Assign an expression to a label. Assignement cannot be repeated several times.

Synopsis: 

LABEL = EXPRESSION

Example: 

label = 1
label =3
.label=2

    assert label == 3


label = 5
    assert label == 5

label <<= 1
    assert label == 10

LET

Synopsis:

LET label = expression

Description: Explicit variable assignment. Equivalent to label = expression but with explicit LET keyword (BASIC-style).

Example:

    ; LET directive for explicit variable assignment
    let value = 42
    let address = $4000

    ; Use the variables
    org address
    ld a, value
    ret

MAP

Synopsis:

MAP VALUE
label #increment

Description: MAP VALUE defines a map counter to the required value. # is used to assign the value to a given label and increment it of the appropriate amount.

Example:

    ; MAP directive
    map $4000

label1  #1      ; label1 = $4000, increment by 1
label2  #2      ; label2 = $4001, increment by 2
label3  #1      ; label3 = $4003, increment by 1

    db label1, label2, label3
    ret

SETN, NEXT

Synopsis:

SETN value
label NEXT increment

Description: Legacy directive for sequential label assignment. MAP directive is probably easier to use.

Example:

 ; http://www.aspisys.com/asm11man.htm

 org 0x100


data set $
    assert data == 0x100

data1 setn  data ; data1 could be modified
data2 next data, 2 ; data2 cannot be modified
data3 next data

    assert data1 == 0x100
    assert data2 == 0x101
    assert data3 == 0x103
    assert data == 0x104

UNDEF

Synopsis:

UNDEF label

Description: Undefine a previously defined label, allowing it to be redefined.

Example:

    ; UNDEF directive
    value = 42
    db value

    undef value  ; Undefine the label

    value = 100  ; Can redefine now
    db value

    ret

BYTE, TEXT, DB, DEFB, DM, DEFM

Synopsis:

DB|DEFB|BYTE|TEXT expression [, expression]*
DM|DEFM string [, string]*

Description: Define byte(s) in memory. Can accept integers, characters, strings, or expressions.

Example:

    ; defb tests
    org 0x200

    defb 1, 2, 3, 4
    defb "hello", ' ', "world"
    defb $, $ ; should generate 2 different values
    db "Hello world", 0

WORD, DW, DEFW

Synopsis:

DW|DEFW|WORD expression [, expression]*

Description: Define 16-bit word(s) in memory (little-endian format).

Example:

    ; WORD/DW/DEFW directive - define 16-bit words
    org $4000

    dw $1234
    defw $ABCD
    word $5678, $9ABC

    ret

DS, DEFS, FILL, RMEM

Synopsis:

DS|DEFS|FILL|RMEM size [, value]

Description: Reserve space in memory. If value is specified, fills the space with that value.

Example:

    org 0x100


    defs 5
    defs 5, 8, 4
    defs 5, 8, 4, 1

ABYTE

Synopsis:

ABYTE expression

Description: Define a byte and align it at the specified address or boundary.

Example:

    ; ABYTE directive
    org $4000

    abyte 10, 100, 200

    assert memory(0x4000) == 100+10
    assert memory(0x4001) == 200+10
    ret

STR

Description: STR encodes string in AMSDOS format (i.e., adds 0x80 to the last char) and stores its bytes in memory.

Example:

    org 0x1000
    defb "hell"
    defb 'o' + 0x80

    org 0x2000
    str "hello"

    org 0x3000
    db "Next one will be more complex"
    db "   \" et voila"
    db " \" et voila"
    db "\" et voila"

    assert memory(0x1000) == memory(0x2000)
    assert memory(0x1001) == memory(0x2001)
    assert memory(0x1002) == memory(0x2002)
    assert memory(0x1003) == memory(0x2003)

CHARSET

Synopsis:

CHARSET "filename"

Description: Load a character set definition from a file for use in subsequent character encoding.

Example:

 org 0x100

 charset "abcdefghijklmnopqrstuvwxyz", 0
 charset "AB", 100
 db "aA"
 ASSERT memory(0x100) == 0x00
 ASSERT memory(0x101) == 100

 org 0x200
 charset
 db "aA"
 ASSERT memory(0x200) == 'a'
 ASSERT memory(0x201) == 'A'

STARTINGINDEX

Synopsis:

STARTINGINDEX value

Description: Set the starting index for character encoding when using custom charsets.

Example:

    ; STARTINGINDEX directive
    startingindex 32

    db 'A'  ; Will use starting index

    ret

Module and Namespace Directives

MODULE, ENDMODULE

Synopsis:

MODULE name
  ... code ...
ENDMODULE

Description: Define a namespace module. Labels inside are prefixed with the module name.

Example:

    MODULE graphics
start:
    ld a, 0
    ret
    ENDMODULE

    ; Access label from module
    call graphics.start

Conditional directives

IF, ELSE, ENDIF

Synopsis:

IF condition
  ... code if true ...
[ELSE
  ... code if false ...]
ENDIF

Description: Conditional assembly based on expression evaluation at assembly time.

Example:

    ; IF/ELSE/ENDIF directive
    value = 1

    if value == 1
        ld a, 1
    else
        ld a, 0
    endif

    ret

IFNOT

Synopsis:

IFNOT condition
  ... code if false ...
ENDIF

Description: Opposite of IF - executes block if condition is false.

Example:

    ; IFNOT directive
    value = 0

    ifnot value
        ld a, 1  ; Executed because value is 0 (false)
    endif

    ret

IFDEF, IFNDEF

Synopsis:

IFDEF label
  ... code if defined ...
ENDIF

IFNDEF label
  ... code if not defined ...
ENDIF

Description: Check if a label has ALREADY been defined before reading this directive.

Example:

    ; IFDEF/IFNDEF directive
    DEBUG = 1

    ifdef DEBUG
        db "Debug mode"
    endif

    ifndef RELEASE
        db "Not release"
    endif

    ret

IFUSED/IFEXIST

Synopsis:

IFUSED label
IFEXIST label    ; alias for IFUSED
  ... code if label is used ...
ENDIF

Description: Check if a label is referenced anywhere in the code. IFEXIST is an alias for IFUSED. Useful for conditional inclusion of code.

Example: 

    org 0x1000
; 3 passes are needed there

    ifused toto
toto
        ret
    endif

    call toto

; test

IFNUSED

Synopsis:

IFNUSED label
  ... code if label is NOT used ...
ENDIF

Description: Opposite of IFUSED. Executes block if label is never referenced.

Example:

    ; Define a label
unused_label:
    nop

used_label:
    nop

    ; This block is assembled because unused_label is not referenced
    ifnused unused_label
        ld a, 1
    endif

    ; This block is NOT assembled because used_label is referenced below
    ifnused used_label
        ld b, 2
    endif

    ; Use one of the labels
    jp used_label

ELSEIF, ELSEIFDEF, ELSEIFNDEF, ELSEIFNOT, ELSEIFUSED/ELSEIFEXIST

Synopsis:

IF condition1
  ... code ...
ELSE IF condition2        ; or ELSEIF
  ... code ...
ELSE IFDEF label          ; or ELSEIFDEF
  ... code ...
ELSE IFNDEF label         ; or ELSEIFNDEF
  ... code ...
ELSE IFUSED label         ; or ELSEIFUSED
  ... code ...
ELSE IFNOT condition      ; or ELSEIFNOT
  ... code ...
ELSE
  ... code ...
ENDIF

Description: Chained conditional directives. Allow multiple conditions without nesting. Can be written as two words (ELSE IF) or one word (ELSEIF). Available variants:

  • ELSEIF - else + if combined
  • ELSEIFDEF - else + ifdef combined
  • ELSEIFNDEF - else + ifndef combined
  • ELSEIFNOT - else + ifnot combined
  • ELSEIFUSED/ELSEIFEXIST - else + ifused combined (ELSEIFEXIST is an alias)

Example:

    ; Chained conditionals with ELSEIF
    value = 2

    if value == 1
        db 1
    elseif value == 2
        db 2
    elseif value == 3
        db 3
    else
        db 0
    endif

Nested conditions

Conditions can be nested.

Example:

    org 0x100

    if 0 == 1
        fail "not reachable"
    else ifdef toto
        fail "not reachable"
    else ifndef toto
        print "reached"
        db 1
    else
        fail "not reachable"
    endif

BREAKPOINT

Synopsis:

BREAKPOINT [expression]

Description: Insert a breakpoint in the generated snapshot for debugging. Optional expression can specify a condition.

Example:

    ; BREAKPOINT directive
    org $4000

    ld a, 5
    breakpoint  ; Debugger will stop here
    ld b, 10

    ret

FAIL

Synopsis:

FAIL [message]

Description: Force assembly to fail with an optional error message. Useful for compile-time validation.

Example:

    ; Example of FAIL directive
    ; This file demonstrates the syntax but would fail if assembled
    ; Uncomment the following lines to test failure:

    ; IFDEF DEBUG
    ; FAIL "Debug mode not supported"
    ; ENDIF

    ; This code assembles successfully
    nop

STOP, END

Synopsis:

STOP
END

Description: Stop assembly processing at this point. Useful for conditional assembly or debugging.

Example:

    ; STOP/END directive
    org $4000

    ld a, 5
    ret

    stop  ; Assembly stops here

    ; This code is never assembled
    ld b, 10

SWITCH, ENDSWITCH

Synopsis:

SWITCH expression
CASE value1
  ... code for value1 ...
  [BREAK]
CASE value2
  ... code for value2 ...
  [BREAK]
DEFAULT
  ... code if no match ...
ENDSWITCH

Description: Multi-way conditional based on expression value. CASE defines match values, DEFAULT handles unmatched cases. BREAK exits the switch early.

Example: 

    org 0x100

    switch 3
    ; one comment
    case 1
        db 1
        break
    case 3
        db 3
    ; another comment
    case 4
        db 4
        break
    case 5
        db 5
    default
        db 6
    endswitch



        switch 5
    case 1
        db 1
        break
    case 3
        db 3
    case 4
        db 4
        break
    case 5
        db 5
    default
        db 6
    endswitch

Code duplication directives

FOR

Synopsis:

FOR <variable>, EXPRESSION [, EXPRESSION]*
  ... LISTING ...
ENDFOR|FEND

Description: Iterate over a list of values, executing the block for each value. The variable takes on each value in the list.

Example:

    ; Takes inspiration from BRASS assembler

    for count, 0, 10, 3
        db {count}
    endfor

    for x, 0, 3
        for y, 0, 3
            db {x}*4 + {y}
        fend
    endfor

WHILE

Synopsis:

WHILE condition
  ... LISTING ...
ENDWHILE|WEND

Description: Repeat a block of code while the condition is true. Condition is evaluated before each iteration.

Example:

    ; WHILE directive
    counter = 0

    while counter < 5
        db counter
counter = counter + 1
    endwhile

    ret

REPEAT, REP, REPT

Synopsis:

REPEAT count [, counter [, start]]
  ... inner listing ...
REND|ENDR|ENDREPEAT

Description: Repeat a block of code a fixed number of times. Optional counter variable tracks iteration (0-based by default, or from start value).

Aliases: REP, REPT (same as REPEAT)

Example:

start
    repeat 3, count
        incbin 'AZERTY{{count}}.TXT'
    rend


    assert char(memory(start+0)) == 'A'
    assert char(memory(start+1)) == 'Z'
    assert char(memory(start+2)) == 'E'
    assert char(memory(start+3)) == 'R'
    assert char(memory(start+4)) == 'T'
    assert char(memory(start+5)) == 'Y'
    assert char(memory(start+6)) == 'U'
    assert char(memory(start+7)) == 'I'
    assert char(memory(start+8)) == 'O'
    assert char(memory(start+9)) == 'P'

    assert char(memory(start+10)) == 'Q'
    assert char(memory(start+11)) == 'S'
    assert char(memory(start+12)) == 'D'
    assert char(memory(start+13)) == 'F'
    assert char(memory(start+14)) == 'G'
    assert char(memory(start+15)) == 'H'
    assert char(memory(start+16)) == 'J'
    assert char(memory(start+17)) == 'K'
    assert char(memory(start+18)) == 'L'
    assert char(memory(start+19)) == 'M'


    assert char(memory(start+20)) == 'W'
    assert char(memory(start+21)) == 'X'
    assert char(memory(start+22)) == 'C'
    assert char(memory(start+23)) == 'V'
    assert char(memory(start+24)) == 'B'
    assert char(memory(start+25)) == 'N'

ITERATE

Synopsis:

ITERATE COUNTER, EXPR [, EXPR]*
  ... INNER LISTING ...
IEND|ENDITERATE

Description: Iterate over expressions, evaluating each expression after having generated the code of the previous one. Take that into account if expressions use $.

Example:

    iterate idx, $4000, $4010, $4020, $4030
        dw {idx}
    iend

    ret

Code and data generation directives

MACRO

Synopsis:

MACRO name [param1, param2, ...]
  ... macro body ...
ENDMACRO|ENDM

; Call macro
name [arg1, arg2, ...]

Description: Define a reusable block of code that can be called with parameters. Macros are expanded inline at each call site.

Example:

    macro add_to_a value
        add a, {value}
    endm

    ld a, 5
    add_to_a(10)
    add_to_a(3)

STRUCT

Synopsis:

STRUCT <name>
  <field1> DB|DW|STR|<other struct> [<value>]
  ...
  <fieldn> DB|DW|<other struct> [<value>]
ENDSTRUCT

; Create instance
[<label>:] <name> <arg1>, ... , <argn>

Description: Structures allow to define data blocks with semantics. In practice, they replace bunches of DEFB, DEFW directives and enforce checks at assembling (you cannot add more data than expected or forget some). If a label is used before the use of a struct, it is necessary to postfix it by :. Otherwise the assembler thinks the label is a macro or structure call.

Example:

    ; STRUCT directive
    struct Point
        x db
        y db
    endstruct

    Point 10, 20    ; Create instance with x=10, y=20
    Point 30, 40    ; Another instance

    ret

Data loading and transformation directives

Filenames are stored in a string. These string can do expansion of formulas embedded in {}.

basm embeds some files in its executable, they are access under the name "inner://" :

LZAPU, LZ4, LZ48, LZ49, LZEXO, LZSA1, LZSA2, LZUPKR, LZSHRINKLER, LZX0, LZX0_BACKWARD, LZX7, INCSHRINKLER, INCUPKR, INCZX0, INCZX0_BACKWARD

Synopsis (as block directives):

LZ4|LZ48|LZ49|LZAPU|LZEXO|LZX0|LZX7|LZSHRINKLER
  ... data to crunch ...
LZCLOSE

Synopsis (as include directives):

INCAPU|INCLZ4|INCL48|INCL49|INCEXO|INCLZSA1|INCLZSA2|INCUPKR|INCSHRINKLER|INCZX0 "filename" [[, SKIP], AMOUNT]
INCZX0_BACKWARD "filename" [[, SKIP], AMOUNT]

Description: Crunch (compress) data using various compression algorithms. Can be used as block directives (crunch inline data) or include directives (load and crunch file).

Supported crunchers:

  • LZ4 - LZ4 compression
  • LZ48 - LZ4 variant optimized for Z80
  • LZ49 - Another LZ4 variant
  • LZAPU / INCAPU - Aplib compression
  • LZEXO / INCEXO - Exomizer compression
  • LZSA1 / INCLZSA1 - LZSA1 compression
  • LZSA2 / INCLZSA2 - LZSA2 compression
  • LZUPKR / INCUPKR - Upkr compression
  • LZSHRINKLER / INCSHRINKLER - Shrinkler compression
  • LZX0 / INCZX0 - ZX0 compression (forward)
  • LZX0_BACKWARD / INCZX0_BACKWARD - ZX0 compression (backward)
  • LZX7 - ZX7 compression

Example: 

    org 0x100


    ld hl, CS_START
    ld de, 0xc000
    call aplib.depack
    jp $

CS_START
    LZAPU
INNER_START
        defs 100
INNER_STOP
    LZCLOSE
CS_STOP

    assert INNER_STOP - INNER_START == 100
    assert CS_STOP - CS_START < 100

    include "inner://unaplib.asm" namespace "aplib"

basm automatically replaces the content of some automatic variables after crunching data. They can help in the uncrunch process for some uncrunchers (mainly the backward ones):

  • BASM_LATEST_CRUNCH_INPUT_DATA_SIZE contains the size of the data BEFORE crunching.
  • BASM_LATEST_CRUNCH_OUTPUT_DATA_SIZE contains the size of the data AFTER crunching.
  • BASM_LATEST_CRUNCH_DELTA contains the delta value of the compressor. -1 if does not exist

INCBIN, BINCLUDE

Synopsis:

INCBIN|BINCLUDE "fname" [[, SKIP], AMOUNT]

Description: Include binary file content. Fname can be built with variables. File is loaded fully in memory before being sliced depending on arguments.

Example:

    ; INCBIN/BINCLUDE directive
    org $4000

    ; Include binary file
    incbin "good_all.bin"

    ret

INCLUDE, READ

Synopsis:

INCLUDE|READ [ONCE] "<fname>" [AS|MODULE|NAMESPACE "<module>"]

Description: Include another source file. Fname can be built with variables. Files prefixed by inner:// are embedded by BASM. In case of conditional assembling, inclusion are only done in the executed branch.

Example:

    ; INCLUDE/READ directive
    org $4000

    ; Include another source file
    include "good_db.asm"

    ret

Data saving and export

EXPORT, NOEXPORT

Synopsis:

EXPORT [label]
NOEXPORT

Description: Control which symbols are exported to external files. EXPORT makes labels visible externally, NOEXPORT hides them.

Example:

    ; EXPORT/NOEXPORT directive
    export start
    export my_data

    org $4000
start:
    ld a, 5

noexport
my_private_label:
    nop

    export
my_data:
    db 1, 2, 3

    ret

SAVE, WRITE

Synopsis:

SAVE "<fname>", [[[START], [SIZE]], AMSDOS|BASIC|TAPE]
SAVE "<fname>", START, SIZE, DSK, "<fname.dsk>" [, SIDE]
SAVE "<fname>", START, SIZE, HFE, "<fname.hfe>" [, SIDE]
SAVE "<fname>", START, SIZE, DISC, "<fname.hfe>"|"<fname.dsk>" [, SIDE]

Description: Save assembled data to a file in various formats (AMSDOS, DSK, HFE). TAPE option is not coded. Other options are not intensively tested.

Example:

    ; SAVE/WRITE directive
    org $4000

start:
    ld a, 5
    ret

    save "output.bin", start, 10, amsdos

Debug directives

PAUSE

Synopsis:

PAUSE

Description: Insert a pause during assembly. Can be useful for interactive debugging or inspection during multi-pass assembly.

Example:

    ; PAUSE directive example
    ; Note: PAUSE may halt assembly for user interaction
    ; Commented out to allow automatic testing

    org $4000
    ld a, 5

    ; pause

    ld b, 10
    ret

ASSERT

Synopsis:

ASSERT BOOLEAN_EXPRESSION [, PRINTABLE_EXPRESSION]*

Description: Validate a condition at assembly time. If the condition is false, assembly fails with an optional message.

Example:

    ; ASSERT directive
    value = 42

    assert value == 42, "Value must be 42"
    assert value > 0

    db value
    ret

PRINT

Synopsis:

PRINT expression [, expression]*

Description: Print expressions to the console during assembly. Useful for debugging and displaying assembly-time values.

Example:

    ; PRINT directive
    value = 42

    print "Value is: ", value
    print "Assembly complete"

    db value
    ret

TICKER

Synopsis:

TICKER START variable
  ... instructions ...
TICKER STOP

Description: Compute the execution duration of a block of code. The variable will contain the number of T-states (cycles) required to execute the code.

Example:

    ; TICKER directive
    org $4000

    ticker start timing_var
        ld a, 5
        ld b, 10
        add a, b
    ticker stop

    ; timing_var now contains execution time
    db timing_var
    ret

WAITNOPS

Synopsis:

WAITNOPS count

Description: Generate instructions that wait for the specified number of NOPs without modifying registers or memory. Currently generates NOP instructions, but may use optimized instruction sequences in the future.

Example:

    ; WAITNOPS directive
    org $4000

    ld a, 5
    waitnops 100  ; Wait for 100 NOPs
    ld b, 10

    ret

LOCOMOTIVE, ENDLOCOMOTIVE

Synopsis:

LOCOMOTIVE
  BASIC code lines
ENDLOCOMOTIVE

Description: Embed Locomotive BASIC code in the assembly. Useful for creating loaders or bootstrap code.

Example: 

    LOCOMOTIVE start
10 REM Basic loader of binary exec
20 REM yeah !!
30 call {start}
    ENDLOCOMOTIVE

start
        ld hl, txt
.loop
        ld a, (hl)
        or a : jr z, .end
        call #bb5a
        inc hl
        jr .loop
.end
        jp $

txt
    db "Hello world", 0

    print "LOADER START IN ", {hex}start
    save "LOADER.BAS",,,BASIC

SNASET

Synopsis:

SNASET FLAG, VALUE

Description: Set CPU register or hardware state values in the generated snapshot. All register names must be prefixed with Z80_.

Z80 CPU Registers

Main registers: - Z80_AF, Z80_BC, Z80_DE, Z80_HL (16-bit register pairs) - Z80_A, Z80_F, Z80_B, Z80_C, Z80_D, Z80_E, Z80_H, Z80_L (8-bit registers)

Alternate registers (shadow registers): - Z80_AFX, Z80_BCX, Z80_DEX, Z80_HLX (16-bit alternate pairs) - Z80_AX, Z80_FX, Z80_BX, Z80_CX, Z80_DX, Z80_EX, Z80_HX, Z80_LX (8-bit alternates)

Index registers: - Z80_IX, Z80_IY (16-bit index registers) - Z80_IXL, Z80_IXH, Z80_IYL, Z80_IYH (8-bit index register halves)

Special registers: - Z80_SP (Stack Pointer) - Z80_PC (Program Counter) - Z80_I (Interrupt Vector) - Z80_R (Memory Refresh) - Z80_IFF0, Z80_IFF1 (Interrupt Flip-Flops) - Z80_IM (Interrupt Mode: 0, 1, or 2)

Gate Array Registers

  • GA_PEN - Selected pen number
  • GA_PAL:n - Palette color n (0-16), requires index
  • GA_ROMCFG - ROM/screen mode configuration
  • GA_RAMCFG - RAM configuration
  • GA_MULTIMODE:n - Multi-mode register n, requires index
  • GA_VSC - Vertical sync counter
  • GA_ISC - Interrupt sync counter

CRTC Registers

  • CRTC_SEL - Selected CRTC register
  • CRTC_REG:n - CRTC register n (0-17), requires index
  • CRTC_TYPE - CRTC type (0=HD6845S/UM6845, 1=UM6845R, 2=MC6845, 3=AMS40489, 4=Pre-ASIC)
  • CRTC_HCC - Horizontal character counter
  • CRTC_CLC - Character line counter
  • CRTC_RLC - Raster line counter
  • CRTC_VAC - Vertical adjustment counter
  • CRTC_VSWC - Vertical sync width counter
  • CRTC_HSWC - Horizontal sync width counter
  • CRTC_STATE - CRTC state flags

PPI (8255) Registers

  • PPI_A - Port A
  • PPI_B - Port B
  • PPI_C - Port C
  • PPI_CTL - Control register

PSG (AY-3-8912) Registers

  • PSG_SEL - Selected PSG register
  • PSG_REG:n - PSG register n (0-15), requires index

Other Hardware

  • ROM_UP - Upper ROM number
  • CPC_TYPE - CPC type (0=464, 1=664, 2=6128, 3=464+, 4=6128+, 5=KC Compact, 6=Unknown)
  • INT_NUM - Interrupt number
  • INT_REQ - Interrupt request flag
  • FDD_MOTOR - Floppy disk motor state
  • FDD_TRACK - Floppy disk current track
  • PRNT_DATA - Printer data port

Note: Flags with :n suffix (like GA_PAL:0, CRTC_REG:1, PSG_REG:7) require an index to specify which register.

Example:

    ; Snapshot generation example
    buildsna 

    org $8000
    ld a, 42
    ret

    ; Set snapshot registers (must use Z80_ prefix)
    snaset Z80_PC, $8000
    snaset Z80_SP, $C000
    snaset Z80_AF, $0000
    snaset Z80_AFX, $0000  ; Alternate AF register

    ; Set CRTC (display controller) registers
    snaset CRTC_SEL, 1      ; Selected CRTC register index
    snaset CRTC_REG:0, 63   ; CRTC register 0 (Horizontal Total)
    snaset CRTC_REG:1, 40   ; CRTC register 1 (Horizontal Displayed)
    snaset CRTC_HCC, 10     ; Horizontal character counter
    snaset CRTC_CLC, 5      ; Character-line counter
    snaset CRTC_TYPE, 0     ; CRTC type: 0 = HD6845S/UM6845
    snaset CRTC_STATE, 255  ; CRTC internal state

    ; Set Gate Array palette (indexed flags)
    snaset GA_PAL:0, $54    ; Palette entry 0
    snaset GA_PAL:1, $44    ; Palette entry 1

    ; Build the snapshot

SNAINIT, SNAPINIT

Synopsis:

SNAINIT "template.sna"

Description: Initialize snapshot generation from a template snapshot file. The template provides the initial memory and register state. Must be called before using SNASET or other snapshot directives.

Example:

    ; SNAINIT/SNAPINIT directive
    snainit "../cpclib-sna/src/cpc6128.sna" 


    org $4000
    ld a, 5
    ret

BUILDSNA

Synopsis:

BUILDSNA "filename.sna"

Description: Generate an Amstrad CPC snapshot file with the assembled code and configured registers. See SNASET example for complete usage.

BUILDCPR

Synopsis:

BUILDCPR "filename.cpr"

Description: Generate a cartridge (CPR) file for the CPC Plus/GX4000.

Example:

    buildcpr

    bank 0
    print {hex}$
    print {hex}$$
    db 'A'


    bank 1
    org 0x8000
    print {hex}$
    print {hex}$$
    db 'B'

    ;assert 0 == 1 => msut raise an assertion failure when uncommented

RUN

Synopsis:

RUN address

Description: Set the execution address for the assembled program in a snapshot.

Example:

    ; RUN directive
    org $4000

    ld a, 5
    ret

    run $4000  ; Set execution address

ENT

Synopsis:

ENT address

Description: Set the entry point for AMSDOS files.

Example:

    ; ENT directive
    org $4000

    ld a, 5
    ret

    ent $4000  ; Set entry point for AMSDOS

Assembler Control Directives

ASMCONTROL

Synopsis:

ASMCONTROL PRINT_PARSE, expression [, expression]*
ASMCONTROL PRINT_ANY_PASS, expression [, expression]*

Description: Control assembler behavior during assembly. PRINT_PARSE prints expressions during the parsing pass. PRINT_ANY_PASS prints expressions during any assembly pass.

Example:

    ; ASMCONTROL directive - print during parsing
    org $4000
    asmcontrol PRINT_PARSE, "Assembling at address: ", $

    ld a, 10
    asmcontrol PRINT_ANY_PASS, "Value loaded: ", 10
    ret

ASMCONTROLENV, ENDASMCONTROLENV

Synopsis:

ASMCONTROLENV SET_MAX_NB_OF_PASSES = expression
  ... code with limited assembly passes ...
ENDASMCONTROLENV

Description: Create a block with a maximum number of assembly passes. This restricts the assembler to complete the enclosed code within the specified number of passes.

Example:

    ; ASMCONTROLENV example - limit number of passes
    org $4000

    asmcontrolenv SET_MAX_NB_OF_PASSES = 2
        ; Code that must assemble in 2 passes or fewer
        nop
        ld a, 5
    endasmcontrolenv

    ret

IMPORT

Synopsis:

IMPORT "filename"

Description: Import symbols from an external symbol file.

Example:

    ; IMPORT directive example
    ; Imports symbols from an external file
    ; Note: This requires an actual symbol file to work
    ; Commented out for testing

    ; import "symbols.sym"

    org $4000
    nop
    ret

FUNCTION, ENDFUNCTION

Synopsis:

FUNCTION name(param1, param2, ...)
  ... function body ...
  RETURN result
ENDFUNCTION

Description: Define a custom function that can be called in expressions. Similar to macros but returns a value.

Example:

    FUNCTION square, x
        RETURN {x} * {x}
    ENDFUNCTION

    org $4000
    ; Use the function
    db square(5)
    db square(10)

    ; Verify with assertions
    assert square(5) == 25
    assert square(10) == 100
    assert memory($4000) == 25
    assert memory($4001) == 100

RETURN

Synopsis:

RETURN expression

Description: Return a value from a function definition. Can only be used within FUNCTION blocks, not in macros. The expression is evaluated and becomes the return value of the function.

Example:

    ; RETURN directive in function
    function get_value
        return 42
    endfunction

    org $4000
    db get_value()  ; Returns 42
    ret