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.

1 Legal
=======

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

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.

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.

‘assert <expresion>[,<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 and '‘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.  The file will be searched first in the current
     directory, then in all paths defined by ‘-I’ in the order of
     occurence.

‘include "<file>"’
     Include source text of <file> at this position.  The include file
     will be searched first in the current directory, then in all paths
     defined by ‘-I’ in the order of occurence.

‘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’
     The following lines will not be visible in a listing file.

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

‘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’ (Jaguar only).

‘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.

4 Known Problems
================

Some known problems of this module at the moment:

   − Not all Madmac, smac and extended Jaguar-Madmac directives are
     supported.

   − Expressions are not evaluated left-to-right, but mathematically
     correct.

   − Square-brackets (‘[]’) are currently not supported to prioritize
     terms, as an alternative for parentheses.

   − Functions (‘^^func’) are currently not supported.

5 Error Messages
================

This module has the following error messages:

   − 1001: malformed immediate-if
   − 1003: cannot export local symbol
   − 1004: no space before operands
   − 1005: too many closing parentheses
   − 1006: missing closing parentheses
   − 1007: missing operand
   − 1008: garbage at end of line
   − 1009: unknown print format flag '%c'
   − 1010: invalid data operand
   − 1011: print format corrupted
   − 1012: identifier expected
   − 1014: unexpected "%s" without "%s"
