Various directives can be used to control the behaviour of the assembler or to include non-code/data in the resulting output. Those directives that are not described in detail in other sections of this document are described below.
expr[,...]
, .DB expr[,...]
, .BYTE expr[,...]
Include one or more constant bytes (separated by commas) in the output.
expr[,...]
, .DW expr[,...]
, .WORD expr[,...]
Include one or more words (separated by commas) in the output.
expr[,...]
, .QUAD expr[,...]
, .4BYTE expr[,...]
Include one or more double words (separated by commas) in the output.
string
, .ASCII string
, .STR string
Include a string of text in the output. The first character of the operand is the delimiter which must appear as the last character and cannot appear within the string. The string is included with no modifications>
string
, .ASCIZ string
, .STRZ string
Include a NUL terminated string of text in the output. The first character of the operand is the delimiter which must appear as the last character and cannot appear within the string. A NUL byte is automatically appended to the string.
string
, .ASCIS string
, .STRS string
Include a string of text in the output with bit 7 of the final byte set. The first character of the operand is the delimiter which must appear as the last character and cannot appear within the string.
expr
Include a number of NUL bytes in the output. The number must be fully resolvable during pass 1 of assembly so no forward or external references are permitted.
expr
Include a number of zero words in the output. The number must be fully resolvable during pass 1 of assembly so no forward or external references are permitted.
expr
Include a number of zero double-words in the output. The number must be fully resolvable during pass 1 of assembly so no forward or external references are permitted.
expr
, .BLKB expr
, .DS expr
, .RS expr
Reserve a number of bytes in the output. The number must be fully resolvable during pass 1 of assembly so no forward or external references are permitted. The value of the bytes is undefined.
expr
Reserve a number of words in the output. The number must be fully resolvable during pass 1 of assembly so no forward or external references are permitted. The value of the words is undefined.
expr
Reserve a number of double-words in the output. The number must be fully resolvable during pass 1 of assembly so no forward or external references are permitted. The value of the double-words is undefined.
filename
Treat the contents of filename
as a string of bytes to
be included literally at the current assembly point. This has the same effect
as converting the file contents to a series of FCB statements and including
those at the current assembly point.
The directives in this section all control the addresses of symbols or the assembly process itself.
expr
Set the assembly address. The address must be fully resolvable on the first pass so no external or forward references are permitted. ORG is not permitted within sections when outputting to object files. For the DECB target, each ORG directive after which output is generated will cause a new preamble to be output. ORG is only used to determine the addresses of symbols when the raw target is used.
sym
EQU expr
, sym
= expr
Define the value of sym
to be expr
.
sym
SET expr
Define the value of sym
to be expr
.
Unlike EQU, SET permits symbols to be defined multiple times as long as SET
is used for all instances. Use of the symbol before the first SET statement
that sets its value is undefined.
expr
Inform the assembler that it can assume the DP register contains
expr
. This directive is only advice to the assembler
to determine whether an address is in the direct page and has no effect
on the contents of the DP register. The value must be fully resolved during
the first assembly pass because it affects the sizes of subsequent instructions.
This directive has no effect in the object file target.
expr
[,value
]Force the current assembly address to be a multiple of
expr
. If value
is not
specified, a series of NUL bytes is output to force the alignment, if
required. Otherwise, the low order 8 bits of value
will be used as the fill. The alignment value must be fully resolved on the
first pass because it affects the addresses of subsquent instructions.
However, value
may include forward references; as
long as it resolves to a constant for the second pass, the value will be
accepted.
Unless value
is specified as something like $12,
this directive is not suitable for inclusion in the middle of actual code.
The default padding value is $00 which is intended to be used within data
blocks.
Portions of the source code can be excluded or included based on conditions known at assembly time. Conditionals can be nested arbitrarily deeply. The directives associated with conditional assembly are described in this section.
All conditionals must be fully bracketed. That is, every conditional statement must eventually be followed by an ENDC at the same level of nesting.
Conditional expressions are only evaluated on the first assembly pass. It is not possible to game the assembly process by having a conditional change its value between assembly passes. Thus there is not and never will be any equivalent of IFP1 or IFP2 as provided by other assemblers.
expr
If expr
evaluates to zero, the conditional
will be considered true.
expr
, IF expr
If expr
evaluates to a non-zero value, the conditional
will be considered true.
expr
If expr
evaluates to a value greater than zero, the conditional
will be considered true.
expr
If expr
evaluates to a value greater than or equal to zero, the conditional
will be considered true.
expr
If expr
evaluates to a value less than zero, the conditional
will be considered true.
expr
If expr
evaluates to a value less than or equal to zero , the conditional
will be considered true.
sym
If sym
is defined at this point in the assembly
process, the conditional
will be considered true.
sym
If sym
is not defined at this point in the assembly
process, the conditional
will be considered true.
If the preceding conditional at the same level of nesting was false, the statements following will be assembled. If the preceding conditional at the same level was true, the statements following will not be assembled. Note that the preceding conditional might have been another ELSE statement although this behaviour is not guaranteed to be supported in future versions of LWASM.
This directive marks the end of a conditional construct. Every conditional construct must end with an ENDC directive.
This section includes directives that apply solely to the OS9 target.
syscall
This directive generates a call to the specified system call. syscall
may be an arbitrary expression.
size
,name
,type
,flags
,execoff
,datasize
This tells LWASM that the beginning of the actual module is here. It will generate a module header based on the parameters specified. It will also begin calcuating the module CRC.
The precise meaning of the various parameters is beyond the scope of this document since it is not a tutorial on OS9 module programming.
This marks the end of a module and causes LWASM to emit the calculated CRC for the module.
This section includes directives that do not fit into the other categories.
filename
, USE filename
Include the contents of filename
at
this point in the assembly as though it were a part of the file currently
being processed. Note that if whitespace appears in the name of the file,
you must enclose filename
in quotes.
Note that the USE variation is provided only for compatibility with other assemblers. It is recommended to use the INCLUDE variation.
[expr]
This directive causes the assembler to stop assembling immediately as though
it ran out of input. For the DECB target only, expr
can be used to set the execution address of the resulting binary. For all
other targets, specifying expr
will cause an error.
string
Causes a custom error message to be printed at this line. This will cause assembly to fail. This directive is most useful inside conditional constructs to cause assembly to fail if some condition that is known bad happens.
string
This directive is ignored for most output targets. If the output target
supports encoding a module name into it, string
will be used as the module name.
As of version 2.2, no supported output targets support this directive.