[ << ] [ >> ]           [] [] [] [ ? ]

5 Madmac Syntax Module

This chapter describes the madmac syntax module, which is compatible to the MadMac assembler syntax, written by Landon Dyer for Atari and improved later to support Jaguar and JRISC. It is mainly intended for Atari’s 6502, 68000 and Jaguar systems.

5.1 Legal

This module is written in 2015-2023 by Frank Wille and is covered by the vasm copyright without modifications.

5.2 General Syntax

A statement may contain up to four fields which are identified by order of appearance and terminating characters. The general form is: 

label:    operator    operand(s)    ; comment

Labels must not start at the first column, as they are identified by the mandatory terminating colon (:) character. A double colon (::) automatically makes the label externally visible.

Labels preceded by ’.’ have local scope and are only valid between two global labels.

Equate directives, starting in the operator field, have a symbol without terminating colon in the first field, left of the operator. The equals-character (=) can be used as an alias for equ. A double-equals (==) automatically makes the symbol externally visible. 

symbol    equate    expression    ; comment

Identifiers, like symbols or labels, may start with any upper- or lower-case character, a dot (.), question-mark (?) or underscore (_). The remaining characters may be any alphanumeric character, a dollar-sign ($), question-mark (?) or underscore (_).

The operands are separated from the operator by whitespace. Multiple operands are separated by comma (,).

Comments are introduced by the comment character ;. The asterisk (*) can be used at the first column to start a comment. The rest of the line will be ignored.

In expressions, numbers starting with $ are hexadecimal (e.g. $fb2c). % introduces binary numbers (e.g. %1100101). Numbers starting with @ are assumed to be octal numbers, e.g. @237. All other numbers starting with a digit are decimal, e.g. 1239.

NOTE: Unlike the original Madmac assembler all expressions are evaluated following the usual mathematical operator priorities.

C-like escape characters are supported in strings.

5.3 Directives

The following directives are supported by this syntax module (if the CPU- and output-module allow it). Note that all directives, besides the equals-character, may be optionally preceded by a dot (.).

<symbol> = <expression>

Equivalent to <symbol> equ <expression>.

<symbol> == <expression>

Equivalent to <symbol> equ <expression>, but declare <symbol> as externally visible.

abs [<expression>]

Equivaluent to offset for compatibility with older Madmac versions. Note that abs is not available for the jagrisc cpu backend as it conflicts with an instruction name.

assert <expression>[,<expression>...]

Assert that all conditions are true (non-zero), otherwise issue a warning.

bss

The following data (space definitions) are going into the BSS section. The BSS section cannot contain any initialized data.

data

The following data are going into the data section, which usually contains pre-initialized data and no executable code.

dc <exp1>[,<exp2>...]

Equivalent to dc.w.

dc.b <exp1>[,<exp2>,"<string1>",'<string2>'...]

Assign the integer or string constant operands into successive bytes of memory in the current section. Any combination of integer and character string constant operands is permitted.

dc.i <exp1>[,<exp2>...]

Assign the values of the operands into successive 32-bit words of memory in the current section. In contrast to dc.l the high and low half-words will be swapped as with the Jaguar-RISC movei instruction.

dc.l <exp1>[,<exp2>...]

Assign the values of the operands into successive 32-bit words of memory in the current section.

dc.w <exp1>[,<exp2>...]

Assign the values of the operands into successive 16-bit words of memory in the current section.

dcb

Equivalent to dcb.w.

dcb.b <exp>[,<fill>]

Insert <exp> zero or <fill> bytes into the current section.

dcb.l <exp>[,<fill>]

Insert <exp> zero or <fill> 32-bit words into the current section.

dcb.w <exp>[,<fill>]

Insert <exp> zero or <fill> 16-bit words into the current section.

dphrase

Align the program counter to the next integral double phrase boundary (16 bytes).

ds <exp>

Equivalent to dcb.w <exp>,0.

ds.b <exp>

Equivalent to dcb.b <exp>,0.

ds.l <exp>

Equivalent to dcb.l <exp>,0.

ds.w <exp>

Equivalent to dcb.w <exp>,0.

else

Else-part of a conditional-assembly block. Refer to ’if’.

end

End the assembly of the current file. Parsing of an include file is terminated here and assembling of the parent source commences. It also works to break the current conditional block, repetition or macro.

endif

Ends a block of conditional assembly.

endm

Ends a macro definition.

endr

Ends a repetition block.

<symbol> equ <expression>

Define a new program symbol with the name <symbol> and assign to it the value of <expression>. Defining <symbol> twice will cause an error.

even

Align the program counter to an even value, by inserting a zero-byte when it is odd.

exitm

Exit the current macro (proceed to endm) at this point and continue assembling the parent context. Note that this directive also resets the level of conditional assembly to a state before the macro was invoked (which means that it works as a ’break’ command on all new if directives).

extern <symbol>[,<symbol>...]

Declare the given symbols as externally defined. Internally there is no difference to globl, as both declare the symbols, no matter if defined or not, as externally visible.

globl <symbol>[,<symbol>...]

Declare the given symbols as externally visible in the object file for the linker. Note that you can have the same effect by using a double-colon (::) on labels or a double-equal (==) on equate-symbols.

if <expression>

Start of block of conditional assembly. If <expression> is true, the block between ’if’ and the matching ’endif’ or ’else’ will be assembled. When false, ignore all lines until an ’else’ or ’endif’ directive is encountered. It is possible to leave such a block early from within an include file (with end) or a macro (with endm).

iif <expression>, <statement>

A single-line conditional assembly. The <statement> will be parsed when <expression> evaluates to true (non-zero). <statement> may be a normal source line, including labels, operators and operands.

incbin "<file>"

Inserts the binary contents of <file> into the object code at this position.

include "<file>"

Include source text of <file> at this position.

list

The following lines will appear in the listing file, if it was requested.

long

Align the program counter to the next integral longword boundary (4 bytes), by inserting as many zero-bytes as needed.

macro <name> [<argname>[,<argname>...]]

Defines a macro which can be referenced by <name> (case-sensitive). The macro definition is terminated by an endm directive and may be exited by exitm. When calling a macro you may pass up to 64 arguments, separated by comma. The first ten arguments are referenced within the macro context as \1 to \9 and \0 for the tenth. Optionally you can specify a list of argument names, which are referenced with a leading backslash character (\) within the macro. The special code \~ inserts a unique id, useful for defining labels. \# is replaced by the number of arguments. \! writes the the size-qualifier (M68k) including the dot. \?argname expands to 1 when the named argument is specified and non-empty, otherwise it expands to 0. It is also allowed to enclose argument names in curly braces, which is useful in situations where the argument name is followed by another valid identifier character.

macundef <name>[,<name>...]

Undefine one or more already defined macros, making them unknown for the following source to assemble.

nlist

This line and the following lines will not be visible in a listing file.

nolist

The following lines will not be visible in a listing file.

offset [<expression>]

Switches to a special offset-section. The contents of such a section is not included in the output. Their labels may be referenced as absolute offset symbols. Can be used to define structure offsets. The optional <expression> gives the start offset for this section. Defaults to zero when omitted. <expression> must evaluate as a constant!

org <expression>

Sets the base address for the subsequent code and switch into absolute mode. Such a block is terminated by any section directive or by .68000.

phrase

Align the program counter to the next integral phrase boundary (8 bytes).

print <expression>[,<expression>...]

Prints strings and formatted expressions to the assembler’s console. <expression> is either a string in quotes or an expression, which is optionally preceded by special format flags:

Several flags can be used to format the output of expressions. The default is a 16-bit signed decimal.

/x

hexadecimal

/d

signed decimal

/u

unsigned decimal

/w

16-bit word

/l

32-bit longword

For example: 

        .print  "Value: ", /d/l xyz
qphrase

Align the program counter to the next integral quad phrase boundary (32 bytes).

rept <expression>

The block between rept and endr will be repeated <expression> times, which has to be positive.

<symbol> set <expression>

Create a new symbol with the name <symbol> and assign the value of <expression>. If <symbol> is already assigned, it will contain a new value from now on.

text

The following code and data is going into the text section, which usually is the first program section, containing the executable code.

5.4 Known Problems

Some known problems of this module at the moment:

5.5 Error Messages

This module has the following error messages:

[ << ] [ >> ]           [] [] [] [ ? ]