This chapter describes the Motorola syntax module, mostly used for the
M68k and ColdFire families of CPUs, which is available with the
extension ‘mot’.

1 Legal
=======

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

2 Additional options for this version
=====================================

This syntax module provides the following additional options:

‘-align’
     Enables natural alignment for data (e.g.  ‘dc.?’, ‘ds.?’) and
     offset directives (‘rs.?’, ‘so.?’, ‘fo.?’).

‘-allmp’
     Makes all 35 macro arguments available.  Default is 9 (‘\1’ to
     ‘\9’).  More arguments can be accessed through ‘\a’ to ‘\z’) which
     may conflict with escape characters or named arguments, therefore
     they are not enabled by default.

‘-devpac’
     Devpac-compatibility mode.  Only directives known to Devpac are
     recognized.
        − Enables natural alignment for data and structure offsets (see
          option ‘-align’).
        − Predefines offset symbols ‘__RS’, ‘__SO’ and ‘__FO’ as ‘0’,
          which otherwise are undefined until first referenced.
        − Disable escape codes handling in strings (see ‘-noesc’).
        − Enable dots within identifiers (see ‘-ldots’).
        − Up to 35 macro arguments.
        − Do not use ‘NOP’ instructions when aligning code.

‘-ldots’
     Allow dots (‘.’) within all identifiers.

‘-localu’
     Local symbols are prefixed by ‘'_'’ instead of ‘'.'’.  For Devpac
     compatbility, which offers a similar option.

‘-phxass’
     PhxAss-compatibilty mode.  Only directives known to PhxAss are
     recognized.  Enables the following features:
        − ‘section <name>’ starts a code section named ‘<name>’ instead
          of a section which also has the type ‘<name>’.
        − Enable escape codes handling in strings (see ‘-esc’).
        − Macro names are treated as case-insensitive.
        − Up to 35 macro arguments.
        − Allow blanks in operands.
        − Defines the symbol ‘_PHXASS_’ with value 2 (to differentiate
          from the real PhxAss with value 1).
        − When no output file name is given, construct it from the input
          name.

‘-spaces’
     Allow blanks in operands.

‘-warncomm’
     Warn about all lines, which have comments in the operand field,
     introduced by a blank character.  For example in: ‘dc.w 1 + 2’.

3 General Syntax
================

Labels must either start at the first column of a line or need to be
terminated by a colon (‘:’).  In the first case the mnemonic has to be
separated from the label by whitespace (not required in any case, e.g.
with a ‘=’ directive).  Qualifiers are appended to the mnemonic,
separated by a dot (if the CPU-module supports qualifiers).  The
operands are separated from the mnemonic by whitespace.  Multiple
operands are separated by comma (‘,’).

   Local labels are preceded by '‘.’' or terminated by '‘$’'.  For the
rest, any alphanumeric character including '‘_’' is allowed.  Local
labels are valid between two global label definitions.

   Otherwise dots (‘.’) are not allowed within a label by default,
unless the option ‘-ldots’ or ‘-devpac’ was specified.  Even then,
labels ending on ‘.b’, ‘.w’ or ‘.l’ can't be defined.

   It is possible to refer to any local symbol in the source by
preceding its name with the name of the last global symbol, which was
defined before: ‘global_name\local_name’.  This is for PhxAss
compatibility only, and is no recommended style.  Does not work in a
macro, as it conflicts with macro arguments.

   Make sure that you don't define a label on the same line as a
directive for conditional assembly (if, else, endif)!  This is not
supported.

   In this syntax module, the operand field must not contain any
whitespace characters, as long as the option ‘-spaces’ was not
specified.

   Comments are introduced by the comment character ‘;’ or ‘*’.  The
rest of the line will be ignored.  Also everything following the operand
field, separated by a whitespace, will be regarded as comment (unless
‘-spaces’).  Be careful with ‘*’, which is recognized as the "current pc
symbol" in any operand expression

   Example:

   ‘mylabel inst.q op1,op2,op3 ;comment’

   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
numbers starting with a digit are decimal, e.g.  ‘1239’.

4 Directives
============

The following directives are supported by this syntax module (provided
the CPU- and output-module support them):

‘<symbol> = <expression>’
     Equivalent to ‘<symbol> equ <expression>’.

‘<symbol> =.s <expression>’
     Equivalent to ‘<symbol> fequ.s <expression>’.  PhxAss
     compatibility.

‘<symbol> =.d <expression>’
     Equivalent to ‘<symbol> fequ.d <expression>’.  PhxAss
     compatibility.

‘<symbol> =.x <expression>’
     Equivalent to ‘<symbol> fequ.x <expression>’.  PhxAss
     compatibility.

‘<symbol> =.p <expression>’
     Equivalent to ‘<symbol> fequ.p <expression>’.  PhxAss
     compatibility.

‘align <bitcount>’
     Insert as much zero bytes as required to reach an address where
     <bitcount> low order bits are zero.  For example ‘align 2’ would
     make an alignment to the next 32-bit boundary.

‘blk.b <exp>[,<fill>]’
     Equivalent to ‘dcb.b <exp>,<fill>’.

‘blk.d <exp>[,<fill>]’
     Equivalent to ‘dcb.d <exp>,<fill>’.

‘blk.l <exp>[,<fill>]’
     Equivalent to ‘dcb.l <exp>,<fill>’.

‘blk.q <exp>[,<fill>]’
     Equivalent to ‘dcb.q <exp>,<fill>’.

‘blk.s <exp>[,<fill>]’
     Equivalent to ‘dcb.s <exp>,<fill>’.

‘blk.w <exp>[,<fill>]’
     Equivalent to ‘dcb.w <exp>,<fill>’.

‘blk.x <exp>[,<fill>]’
     Equivalent to ‘dcb.x <exp>,<fill>’.

‘bss’
     Equivalent to ‘section bss,bss’.

‘bss_c’
     Equivalent to ‘section bss_c,bss,chip’.

‘bss_f’
     Equivalent to ‘section bss_f,bss,fast’.

‘cargs [#<offset>,]<symbol1>[.<size1>][,<symbol2>[.<size2>]]...’
     Defines <symbol1> with the value of <offset>.  Further symbols on
     the line, separated by comma, will be assigned the <offset> plus
     the size of the previous symbol.  The size defaults to 2.  Valid
     optional size extensions are: ‘.b’, ‘.w’, ‘.l’, where ‘.l’ results
     in a size of 4, the others 2.  The <offset> argument defaults to 4,
     when not given.

‘clrfo’
     Reset stack-frame offset counter to zero.  See ‘fo’ directive.

‘clrso’
     Reset structure offset counter to zero.  See ‘so’ directive.

‘cnop <offset>,<alignment>’
     Insert as much zero bytes as required to reach an address which can
     be divided by <alignment>.  Then add <offset> zero bytes.  May fill
     the pad-bytes with no-operation instructions for certain cpus.

‘code’
     Equivalent to ‘section code,code’.

‘code_c’
     Equivalent to ‘section code_c,code,chip’.

‘code_f’
     Equivalent to ‘section code_f,code,fast’.

‘comm <symbol>,<size>’
     Create a common symbol with the given size.  The alignment is
     always 32 bits.

‘comment’
     Everything in the operand field is ignored and seen as a comment.
     There is only one exception, when the operand contains ‘HEAD=’.
     Then the following expression is passed to the TOS output module
     via the symbol '‘ TOSFLAGS’', to define the Atari specific TOS
     flags.

‘cseg’
     Equivalent to ‘section code,code’.

‘data’
     Equivalent to ‘section data,data’.

‘data_c’
     Equivalent to ‘section data_c,data,chip’.

‘data_f’
     Equivalent to ‘section data_f,data,fast’.

‘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.d <exp1>[,<exp2>...]’
     Assign the values of the operands into successive 64-bit words of
     memory in the current section.  Also IEEE double precision floating
     point constants are allowed.

‘dc.l <exp1>[,<exp2>...]’
     Assign the values of the operands into successive 32-bit words of
     memory in the current section.

‘dc.q <exp1>[,<exp2>...]’
     Assign the values of the operands into successive 64-bit words of
     memory in the current section.

‘dc.s <exp1>[,<exp2>...]’
     Assign the values of the operands into successive 32-bit words of
     memory in the current section.  Also IEEE single precision floating
     point constants are allowed.

‘dc.w <exp1>[,<exp2>...]’
     Assign the values of the operands into successive 16-bit words of
     memory in the current section.

‘dc.x <exp1>[,<exp2>...]’
     Assign the values of the operands into successive 96-bit words of
     memory in the current section.  Also IEEE extended precision
     floating point constants are allowed.

‘dcb.b <exp>[,<fill>]’
     Insert <exp> zero or <fill> bytes into the current section.

‘dcb.d <exp>[,<fill>]’
     Insert <exp> zero or <fill> 64-bit words into the current section.
     <fill> might also be an IEEE double precision constant.

‘dcb.l <exp>[,<fill>]’
     Insert <exp> zero or <fill> 32-bit words into the current section.

‘dcb.q <exp>[,<fill>]’
     Insert <exp> zero or <fill> 64-bit words into the current section.

‘dcb.s <exp>[,<fill>]’
     Insert <exp> zero or <fill> 32-bit words into the current section.
     <fill> might also be an IEEE single precision constant.

‘dcb.w <exp>[,<fill>]’
     Insert <exp> zero or <fill> 16-bit words into the current section.

‘dcb.x <exp>[,<fill>]’
     Insert <exp> zero or <fill> 96-bit words into the current section.
     <fill> might also be an IEEE extended precision constant.

‘dr.b <exp1>[,<exp2>...]’
     Calculates <expN> - <current pc value> and stores it into
     successive bytes of memory in the current section.

‘dr.w <exp1>[,<exp2>...]’
     Calculates <expN> - <current pc value> and stores it into
     successive 16-bit words of memory in the current section.

‘dr.l <exp1>[,<exp2>...]’
     Calculates <expN> - <current pc value> and stores it into
     successive 32-bit words of memory in the current section.

‘ds.b <exp>’
     Equivalent to ‘dcb.b <exp>,0’.

‘ds.d <exp>’
     Equivalent to ‘dcb.d <exp>,0’.

‘ds.l <exp>’
     Equivalent to ‘dcb.l <exp>,0’.

‘ds.q <exp>’
     Equivalent to ‘dcb.q <exp>,0’.

‘ds.s <exp>’
     Equivalent to ‘dcb.s <exp>,0’.

‘ds.w <exp>’
     Equivalent to ‘dcb.w <exp>,0’.

‘ds.x <exp>’
     Equivalent to ‘dcb.x <exp>,0’.

‘dseg’
     Equivalent to ‘section data,data’.

‘echo <string>’
     Prints <string> to stdout.

‘einline’
     End a block of isolated local labels, started by ‘inline’.

‘else’
     Assemble the following lines if the previous ‘if’ condition was
     false.

‘end’
     Assembly will terminate behind this line.

‘endif’
     Ends a section 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.

‘<symbol> equ.s <expression>’
     Equivalent to ‘<symbol> fequ.s <expression>’.  PhxAss
     compatibility.

‘<symbol> equ.d <expression>’
     Equivalent to ‘<symbol> fequ.d <expression>’.  PhxAss
     compatibility.

‘<symbol> equ.x <expression>’
     Equivalent to ‘<symbol> fequ.x <expression>’.  PhxAss
     compatibility.

‘<symbol> equ.p <expression>’
     Equivalent to ‘<symbol> fequ.p <expression>’.  PhxAss
     compatibility.

‘erem’
     Ends an outcommented block.  Assembly will continue.

‘even’
     Aligns to an even address.  Equivalent to ‘cnop 0,2’.

‘fail <message>’
     Show an error message including the <message> string.  Do not
     generate an ouput file.

‘<symbol> fequ.s <expression>’
     Define a new program symbol with the name <symbol> and assign to it
     the floating point value of <expression>.  Defining <symbol> twice
     will cause an error.  The extension is for Devpac-compatibility,
     but will be ignored.

‘<symbol> fequ.d <expression>’
     Equivalent to ‘<symbol> fequ.s <expression>’.

‘<symbol> fequ.x <expression>’
     Equivalent to ‘<symbol> fequ.s <expression>’.

‘<symbol> fequ.p <expression>’
     Equivalent to ‘<symbol> fequ.s <expression>’.

‘<label> fo.<size> <expression>’
     Assigns the current value of the stack-frame offset counter to
     <label>.  Afterwards the counter is decremented by the
     instruction's <size> multiplied by <expression>.  Any valid M68k
     size extension is allowed for <size>: b, w, l, q, s, d, x, p.  The
     offset counter can also be referenced directly under the name
     ‘__FO’.

‘idnt <name>’
     Sets the file or module name in the generated object file to
     <name>, when the selected output module supports it.  By default,
     the input filename passed on the command line is used.

‘if <expression>’
     Conditionally assemble the following lines if <expression> is
     non-zero.

‘ifeq <expression>’
     Conditionally assemble the following lines if <expression> is zero.

‘ifne <expression>’
     Conditionally assemble the following lines if <expression> is
     non-zero.

‘ifgt <expression>’
     Conditionally assemble the following lines if <expression> is
     greater than zero.

‘ifge <expression>’
     Conditionally assemble the following lines if <expression> is
     greater than zero or equal.

‘iflt <expression>’
     Conditionally assemble the following lines if <expression> is less
     than zero.

‘ifle <expression>’
     Conditionally assemble the following lines if <expression> is less
     than zero or equal.

‘ifb <operand>’
     Conditionally assemble the following lines when <operand> is
     completely blank, except an optional comment.

‘ifnb <operand>’
     Conditionally assemble the following lines when <operand> is
     non-blank.

‘ifc <string1>,<string2>’
     Conditionally assemble the following lines if <string1> matches
     <string2>.

‘ifnc <string1>,<string2>’
     Conditionally assemble the following lines if <string1> does not
     match <string2>.

‘ifd <symbol>’
     Conditionally assemble the following lines if <symbol> is defined.

‘ifnd <symbol>’
     Conditionally assemble the following lines if <symbol> is
     undefined.

‘ifmacrod <macro>’
     Conditionally assemble the following line if <macro> is defined.

‘ifmacrond <macro>’
     Conditionally assemble the following line if <macro> is undefined.

‘incbin <file>[,<offset>[,<length>]]’
     Inserts the binary contents of <file> into the object code at this
     position.  When <offset> is specified, then the given number of
     bytes will be skipped at the beginning of the file.  The optional
     <length> argument specifies the maximum number of bytes to be read
     from that file.  The file will be searched first in the current
     directory, then in all paths defined by ‘-I’ or ‘incdir’ in the
     order of occurence.

‘incdir <path>’
     Add another path to search for include files to the list of known
     paths.  Paths defined with ‘-I’ on the command line are searched
     first.

‘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’ or ‘incdir’ in the order of occurence.

‘inline’
     Local labels in the following block are isolated from previous
     local labels and those after ‘einline’.

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

‘llen <len>’
     Set the line length in a listing file to a maximum of <len>
     characters.  Currently without any effect.

‘macro <name>’
     Defines a macro which can be referenced by <name>.  The <name> may
     also appear at the left side of the ‘macro’ directive, starting at
     the first column.  Then the operand field is ignored.  The macro
     definition is closed by an ‘endm’ directive.  When calling a macro
     you may pass up to 9 arguments, separated by comma.  Those
     arguments are referenced within the macro context as ‘\1’ to ‘\9’.
     Parameter ‘\0’ is set to the macro's first qualifier (mnemonic
     extension), when given.  In Devpac- and PhxAss-compatibility mode,
     or with option ‘-allmp’, up to 35 arguments are accepted, where
     argument 10-35 can be referenced by ‘\a’ to ‘\z’.

     Special macro parameters:
     ‘\@’
          Insert a unique id, useful for defining labels.  Every macro
          call gets its own unique id.
     ‘\@!’
          Push the current unique id onto a global id stack, then insert
          it.
     ‘\@?’
          Push the current unique id below the top element of the global
          id stack, then insert it.
     ‘\@@’
          Pull the top element from the global id stack and insert it.
          The macro's current unique id is not affected by this
          operation.
     ‘\#’
          Insert the number of arguments that have been passed to this
          macro.  Equivalent to the conents of ‘NARG’.
     ‘\?n’
          Insert the length of the ‘n’'th macro argument.
     ‘\.’
          Insert the argument which is selected by the current value of
          the ‘CARG’ symbol (first argument, when ‘CARG’ is ‘1’).
     ‘\+’
          Works like ‘\.’, but increments the value of ‘CARG’ after
          that.
     ‘\-’
          Works like ‘\.’, but decrements the value of ‘CARG’ after
          that.
     ‘\<symbolname>’
          inserts the current decimal value of the absolute symbol
          ‘symbolname’.
     ‘\<$symbolname>’
          inserts the current hexadecimal value of the absolute symbol
          ‘symbolname’, without leading ‘$’.

‘mexit’
     Leave the current macro and continue with 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).

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

‘nopage’
     Never start a new page in the listing file.  This implementation
     will only prevent emitting the formfeed code.

‘nref <symbol>[,<symbol>...]’
     Flag <symbol> as externally defined, similar to ‘xref’, but also
     indicate that references should be optimized to base-relative
     addressing modes, when possible.  This directive is only present in
     PhxAss-compatibility mode.

‘odd’
     Aligns to an odd address.  Equivalent to ‘cnop 1,2’.

‘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.  When missing the last offset of the
     previous offset-section is used, or 0.

‘org <expression>’
     Sets the base address for the subsequent code.  Note that it is
     allowed to embed such an absolute ORG block into a section.  Return
     into relocatable mode with any new section directive.  Although in
     Devpac compatibility mode the previous section will stay absolute.

‘output <name>’
     Sets the output file name to ‘<name>’ when no output name was given
     on the command line.  A special case for Devpac-compatibility is
     when ‘<name>’ starts with a ‘'.'’ and an output name was already
     given.  Then the current output name gets ‘<name>’ appended as an
     extension.  When an extension already exists, then it is replaced.

‘page’
     Start a new page in the listing file (not implemented).  Make sure
     to start a new page when the maximum page length is reached.

‘plen <len>’
     The the page length for a listing file to <len> lines.  Currently
     ignored.

‘printt <string>[,<string>...]’
     Prints <string> to stdout.  Each additional string into a new line.
     Quotes are optional.

‘printv <expression>[,<expression>...]’
     Evaluate <expression> and print it to stdout out in hexadecimal,
     decimal, ASCII and binary format.

‘public <symbol>[,<symbol>...]’
     Flag <symbol> as an external symbol, which means that <symbol> is
     visible to all modules in the linking process.  It may be either
     defined or undefined.

‘rem’
     The assembler will ignore everything from encountering the ‘rem’
     directive until an ‘erem’ directive was found.

‘rept <expression>’
     Repeats the assembly of the block between ‘rept’ and ‘endr’
     <expression> number of times.  <expression> has to be positive.
     The internal symbol ‘REPTN’ always holds the iteration counter of
     the inner repeat loop, starting with 0.  ‘REPTN’ is -1 outside of
     any repeat block.

‘rorg <expression>’
     Sets the program counter <expression> bytes behind the start of the
     current section.  The new program counter must not be smaller than
     the current one.  The space will be padded with zeros.

‘<label> rs.<size> <expression>’
     Works like the ‘so’ directive, with the only difference that the
     offset symbol is named ‘__RS’.

‘rsreset’
     Equivalent to ‘clrso’, but the symbol manipulated is ‘__RS’.

‘rsset’
     Equivalent to ‘setso’, but the symbol manipulated is ‘__RS’.

‘section [<name>,]<sec_type>[,<mem_type>]’
     Starts a new section named ‘<name>’ or reactivates an old one.
     ‘<sec_type>’ defines the section type and may be ‘code’, ‘text’
     (same as ‘code’), ‘data’ or ‘bss’.  ‘<sec_type>’ defaults to ‘code’
     in Phxass mode.  Otherwise a single argument will start a section
     with the type and name of ‘<sec_type>’.  When ‘<mem_type>’ is given
     it defines a 32-bit memory attribute, which defines where to load
     the section.  ‘<mem_type>’ is either a numerical constant or one of
     the keywords ‘chip’ (for Chip-RAM) or ‘fast’ (for Fast-RAM).
     Optionally it is also possible to attach the suffix ‘_C’, ‘_F’ or
     ‘_P’ to the ‘<sec_type>’ argument for defining the memory type.
     The memory attributes are currently only used in the hunk-format
     output module.

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

‘setfo <expression>’
     Sets the stack-frame offset counter to <expresion>.  See ‘fo’
     directive.

‘setso <expression>’
     Sets the structure offset counter to <expresion>.  See ‘so’
     directive.

‘<label> so.<size> <expression>’
     Assigns the current value of the structure offset counter to
     <label>.  Afterwards the counter is incremented by the
     instruction's <size> multiplied by <expression>.  Any valid M68k
     size extension is allowed for <size>: b, w, l, q, s, d, x, p.  The
     offset counter can also be referenced directly under the name
     ‘__SO’.

‘spc <lines>’
     Output <lines> number of blank lines in the listing file.
     Currently without any effect.

‘text’
     Equivalent to ‘section code,code’.

‘ttl <name>’
     PhxAss syntax.  Equivalent to ‘idnt <name>’.

‘<name> ttl’
     Motorola syntax.  Equivalent to ‘idnt <name>’.

‘weak <symbol>[,<symbol>...]’
     Flag <symbol> as a weak symbol, which means that <symbol> is
     visible to all modules in the linking process and may be replaced
     by any global symbol with the same name.  When a weak symbol
     remains undefined its value defaults to 0.

‘xdef <symbol>[,<symbol>...]’
     Flag <symbol> as an global symbol, which means that <symbol> is
     visible to all modules in the linking process.  See also ‘public’.

‘xref <symbol>[,<symbol>...]’
     Flag <symbol> as externally defined, which means it has to be
     important from another module in the linking process.  See also
     ‘public’.

5 Known Problems
================

Some known problems of this module at the moment:

   − None?

6 Error Messages
================

This module has the following error messages:

   − 1001: mnemonic expected
   − 1002: invalid extension
   − 1003: no space before oprands
   − 1004: too many closing parentheses
   − 1005: missing closing parentheses
   − 1006: missing operand
   − 1007: garbage at end of line
   − 1008: syntax error
   − 1009: invalid data operand
   − 1010: , expected
   − 1011: identifier expected
   − 1012: directive has no effect
   − 1013: unexpected "%s" without "%s"
   − 1014: illegal section type
   − 1015: macro id insert on empty stack
   − 1016: illegal memory type
   − 1017: macro id stack overflow
   − 1018: macro id pull without matching push
   − 1019: check comment
   − 1020: invalid numeric expansion
   − 1021: einline without inline
   − 1022: missing %c
   − 1023: maximum inline nesting depth exceeded (%d)

