db stands for "define byte", dm for "define message". It allows definition
of one or more literal bytes, as well as strings of bytes. All definitions
should be separated by commas. Strings of bytes should be between double
quotes. Example code:
label: equ 20
defb "This is a text", label / 2, "This is more text", 10, 0
dw stands for "define word". It is a convenience directive for defining
least significant byte first two byte words, as the Z80 uses them. Multiple
expressions, separated by commas, may be specified. Example:
org 0x8000
pointertable: defw sub1, sub2
sub1: sub b
ret nz
sub2: ld h,0
ret
ds stands for "define space". It takes one or two arguments, num and
val. It reserves num bytes of space and initializes them to
val. If val is omitted, it defaults to 0. Example:
buffer: defs 20
sevens: defs 10, 7
At the end of the program, it is allowed to use the "end" directive. There is no need to do this. Everything after this directive is ignored. This can be used to put some comments at the end.
This sets the assembler's idea of the current address. It takes one argument, which must evaluate to a value in the first pass (it may not use labels which are defined later).
At the start, the current address is set to 0. Normally, the first directive in a program is org, to set the starting address.
Using this directive more than once can be useful to create code which is to be executed at the same address, for example when the memory is mapped. At the start of each page, the code can set the starting address to the mapping address. The previously defined pages are not overwritten.
Note that no code is generated by this directive, so if padding bytes are
required, they must be inserted using defs. Org only changes the assembler's
idea of "where" it is. In the following example, the output contains 4 bytes:
23, 12, 00, 00.
first_label: defw second_label
org 0x1234
second_label: defw first_label
People have requested to be able to overwrite the generated output. This is what seek is for. It will seek in the output file and start overwriting previous output. This is mostly useful in combination with incbin. It allows the included binary to be "patched".
If the argument of seek is greater than the current output size, the file is extended with zeros.
As in C (but without the #), this includes an other source file. No
substitution at all is done on the filename, which means that ~ cannot be
used to refer to the home directory. Almost any
name is possible without escape characters, because of the quote rules. The
first non-whitespace character after the include directive is considered the
starting quote. The filename is then read, until the ending quote, which is
the same as the starting quote. Example:
include 'math.asm'
include -file'with"quotes".asm-
include zletter as quotes and spaces in name.asmz
Incbin stands for "include binary". It allows any binary data to be included verbatim into the output. The argument is given in the same way as for include.
Parts of the code can be omitted using these conditional statements.
else can be repeated as many times as desired. Code which is not assembled is
checked for a correct command. Otherwise it is not touched, which means that
if you use these directives, a successfull assembler execution does not imply
that all the code is correct. Example:
org 0x8000
include "math.asm"
if $ < 0x9000 ; Only do the following if math.asm is small enough
ld a,3
else
ld a,6
else
;this is also only assembled if math.asm is small enough
ld h,8
endif
;this is always assembled
call math_init
With these directives it is possible to define new commands, which will output defined code. arguments can be given as well. Example:
callf: macro slot, address
rst 0x30
db slot
dw address
endm
After this definition, it is possible to use the macro, like this:
callf 0x8b, 0x4000