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

@section Legal

    This module is copyright in 2002-2014 by Frank Wille.

    This archive may be redistributed without modifications and used
    for non-commercial purposes.

    Distributing modified versions and commercial usage needs my written
    consent.

    Certain modules may fall under additional copyrights.

@section Additional options for this version
 
This syntax module provides the following additional options:
 
@table @option
 
@item -align
 Enables natural alignment for constant declaration (@code{dc.?}) directives.

@item -devpac
 Devpac-compatibility mode.
@itemize @minus
  @item Enables natural alignment for constant declaration (@code{dc.?})
        directives.
  @item Predefines offset symbols @code{__RS}, @code{__SO} and @code{__FO} as
        @code{0}, which in vasm are undefined until first referenced.
  @item Disable escape codes handling in strings (see @option{-noesc}).
  @item Enable dots within identifiers (see @option{-ldots}).
  @item Up to 35 macro arguments.
@end itemize

@item -ldots
 Allow dots (@code{.}) within all identifiers.

@item -localu
 Local symbols are prefixed by @code{'_'} instead of @code{'.'}. For
 Devpac compatbility, which offers a similar option.

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

@item -spaces
 Allow blanks in operands.

@end table

@section General Syntax

Labels must either start at the first column of a line or need to be
terminated by a colon (@code{:}). In the first case the mnemonic
has to be separated from the label by whitespace (not required in any case,
e.g. with a @code{=} 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 (@code{,}).

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

Otherwise dots (@code{.}) are not allowed within a label by default, unless
the option @option{-ldots} or @option{-devpac} was specified. Even then,
labels ending on @code{.b}, @code{.w} or @code{.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:
@code{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 @option{-spaces} was not specified.

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

Example:

@code{mylabel inst.q op1,op2,op3  ;comment}

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


@section Directives

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

@table @code
@item <symbol> = <expression>
      Equivalent to @code{<symbol> equ <expression>}.

@item <symbol> =.s <expression>
      Equivalent to @code{<symbol> fequ.s <expression>}. PhxAss compatibility.

@item <symbol> =.d <expression>
      Equivalent to @code{<symbol> fequ.d <expression>}. PhxAss compatibility.

@item <symbol> =.x <expression>
      Equivalent to @code{<symbol> fequ.x <expression>}. PhxAss compatibility.

@item <symbol> =.p <expression>
      Equivalent to @code{<symbol> fequ.p <expression>}. PhxAss compatibility.

@item align <bitcount>
      Insert as much zero bytes as required to reach an address where
      <bitcount> low order bits are zero. For example @code{align 2} would
      make an alignment to the next 32-bit boundary.
      Equivalent to @code{cnop 0,1<<bitcount}.

@item blk.b <exp>[,<fill>]
      Equivalent to @code{dcb.b <exp>,<fill>}.

@item blk.d <exp>[,<fill>]
      Equivalent to @code{dcb.d <exp>,<fill>}.

@item blk.l <exp>[,<fill>]
      Equivalent to @code{dcb.l <exp>,<fill>}.

@item blk.q <exp>[,<fill>]
      Equivalent to @code{dcb.q <exp>,<fill>}.

@item blk.s <exp>[,<fill>]
      Equivalent to @code{dcb.s <exp>,<fill>}.

@item blk.w <exp>[,<fill>]
      Equivalent to @code{dcb.w <exp>,<fill>}.

@item blk.x <exp>[,<fill>]
      Equivalent to @code{dcb.x <exp>,<fill>}.

@item bss
      Equivalent to @code{section bss,bss}.

@item bss_c
      Equivalent to @code{section bss_c,bss,chip}.

@item bss_f
      Equivalent to @code{section bss_f,bss,fast}.

@item 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: @code{.b}, @code{.w}, @code{.l},
      where @code{.l} results in a size of 4, the others 2.
      The <offset> argument defaults to 4, when not given.

@item clrfo
      Reset stack-frame offset counter to zero. See @code{fo} directive.

@item clrso
      Reset structure offset counter to zero. See @code{so} directive.

@item 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.

@item code
      Equivalent to @code{section code,code}.

@item code_c
      Equivalent to @code{section code_c,code,chip}.

@item code_f
      Equivalent to @code{section code_f,code,fast}.

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

@item cseg
      Equivalent to @code{section code,code}.

@item data
      Equivalent to @code{section data,data}.

@item data_c
      Equivalent to @code{section data_c,data,chip}.

@item data_f
      Equivalent to @code{section data_f,data,fast}.

@item 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.

@item 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.

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

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

@item 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.

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

@item 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.

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

@item 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.

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

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

@item 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.

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

@item 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.

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

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

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

@item ds.b <exp>
      Equivalent to @code{dcb.b <exp>,0}.

@item ds.d <exp>
      Equivalent to @code{dcb.d <exp>,0}.

@item ds.l <exp>
      Equivalent to @code{dcb.l <exp>,0}.

@item ds.q <exp>
      Equivalent to @code{dcb.q <exp>,0}.

@item ds.s <exp>
      Equivalent to @code{dcb.s <exp>,0}.

@item ds.w <exp>
      Equivalent to @code{dcb.w <exp>,0}.

@item ds.x <exp>
      Equivalent to @code{dcb.x <exp>,0}.

@item dseg
      Equivalent to @code{section data,data}.

@item echo <string>
      Prints <string> to stdout.

@item else
      Assemble the following lines if the previous @code{if} condition
      was false.

@item end
      Assembly will terminate behind this line.

@item endif
      Ends a section of conditional assembly.

@item endm
      Ends a macro definition.

@item endr
      Ends a repetition block.

@item <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.

@item <symbol> equ.s <expression>
      Equivalent to @code{<symbol> fequ.s <expression>}. PhxAss compatibility.

@item <symbol> equ.d <expression>
      Equivalent to @code{<symbol> fequ.d <expression>}. PhxAss compatibility.

@item <symbol> equ.x <expression>
      Equivalent to @code{<symbol> fequ.x <expression>}. PhxAss compatibility.

@item <symbol> equ.p <expression>
      Equivalent to @code{<symbol> fequ.p <expression>}. PhxAss compatibility.

@item erem
      Ends an outcommented block. Assembly will continue.

@item even
      Aligns to an even address. Equivalent to @code{cnop 0,2}.

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

@item <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.

@item <symbol> fequ.d <expression>
      Equivalent to @code{<symbol> fequ.s <expression>}.

@item <symbol> fequ.x <expression>
      Equivalent to @code{<symbol> fequ.s <expression>}.

@item <symbol> fequ.p <expression>
      Equivalent to @code{<symbol> fequ.s <expression>}.

@item <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
      @code{__FO}.

@item 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.

@item if <expression>
      Conditionally assemble the following lines if <expression> is non-zero.

@item ifeq <expression>
      Conditionally assemble the following lines if <expression> is zero.

@item ifne <expression>
      Conditionally assemble the following lines if <expression> is non-zero.

@item ifgt <expression>
      Conditionally assemble the following lines if <expression> is
      greater than zero.

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

@item iflt <expression>
      Conditionally assemble the following lines if <expression> is
      less than zero.

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

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

@item ifnb <operand>
      Conditionally assemble the following lines when <operand> is
      non-blank.

@item ifc <string1>,<string2>
      Conditionally assemble the following lines if <string1> matches
      <string2>.

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

@item ifd <symbol>
      Conditionally assemble the following lines if <symbol> is defined.

@item ifnd <symbol>
      Conditionally assemble the following lines if <symbol> is undefined.

@item 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 @option{-I} or @code{incdir}
      in the order of occurence.

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

@item 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 @option{-I} or @code{incdir} in the order of
      occurence.

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

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

@item macro <name>
      Defines a macro which can be referenced by <name>. The <name>
      may also appear at the left side of the @code{macro} directive,
      starting at the first column. Then the operand field is ignored.
      The macro definition is closed
      by an @code{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 @code{\1} to @code{\9}.
      Argument @code{\0} is set to the macro's first qualifier
      (mnemonic extension), when given.
      In Devpac- and PhxAss-compatibility mode up to 35 arguments are
      accepted, where argument 10-35 can be referenced by @code{\a} to
      @code{\z}.
      The special argument @code{\@@} inserts a unique id, useful for
      defining labels. @code{\#} is replaced by the number of arguments
      (also stored in @code{NARG}) and @code{\?n} is replaced by the
      length of argument @code{n}.
      @code{\.} selects the argument indexed by the current value of
      @code{CARG}. @code{\+} and @code{\-} do the same, but additionally
      post-increment and post-decrement @code{CARG}.
      @code{\()} may be used as a separator between the name of a macro
      argument and the subsequent text.

@item 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 @code{if} directives).

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

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

@item odd
      Aligns to an odd address. Equivalent to @code{cnop 1,2}.

@item 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.

@item org <expression>
      Sets the base address for the subsequent code.

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

@item 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.

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

@item printt <string>
      Prints <string> to stdout.

@item printv <expression>
      Evaluate <expression> and print it to stdout out in decimal and
      hexadecimal form.

@item 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.

@item rem
      The assembler will ignore everything from encountering the @code{rem}
      directive until an @code{erem} directive was found.

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

@item 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.

@item <label> rs.<size> <expression>
      Works like the @code{so} directive, with the only difference that
      the offset symbol is named @code{__RS}.

@item rsreset
      Equivalent to @code{clrso}, but the symbol manipulated is @code{__RS}.

@item rsset
      Equivalent to @code{setso}, but the symbol manipulated is @code{__RS}.

@item section [<name>,]<sec_type>[,<mem_type>]]
      Starts a new section named @code{<name>} or reactivates an old one.
      @code{<sec_type>} defines the section type and may be @code{code},
      @code{text} (same as @code{code}), @code{data} or @code{bss}.
      @code{<sec_type>} defaults to @code{code} in Phxass mode. Otherwise
      a single argument will start a section with the type and name of
      @code{<sec_type>}. When @code{<mem_type>} is given
      it defines the type of memory, where the section can
      be loaded. This is Amiga-specific, and allowed identifiers are
      @code{chip} for Chip-RAM and @code{fast} for Fast-RAM. Optionally
      it is also possible to attach the suffix @code{_C}, @code{_F} or
      @code{_P} to the @code{<sec_type>} argument for defining the memory type.

@item <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.

@item setfo <expression>
      Sets the stack-frame offset counter to <expresion>.
      See @code{fo} directive.

@item setso <expression>
      Sets the structure offset counter to <expresion>.
      See @code{so} directive.

@item <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
      @code{__SO}.

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

@item text
      Equivalent to @code{section code,code}.

@item ttl <name>
      PhxAss syntax. Equivalent to @code{idnt <name>}.

@item <name> ttl
      Motorola syntax. Equivalent to @code{idnt <name>}.

@item xdef <symbol>[,<symbol>...]
      Flag <symbol> as an global symbol, which means that
      <symbol> is visible to all modules in the linking process.
      See also @code{public}.

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

@end table

@section Known Problems

    Some known problems of this module at the moment:

@itemize @minus

@item None?

@end itemize

@section Error Messages

This module has the following error messages:

@itemize @minus
@item 1001: mnemonic expected
@item 1002: invalid extension
@item 1003: no space before oprands
@item 1004: too many closing parentheses
@item 1005: missing closing parentheses
@item 1006: missing operand
@item 1007: garbage at end of line
@item 1008: syntax error
@item 1009: invalid data operand
@item 1010: , expected
@item 1011: identifier expected
@item 1012: directive has no effect
@item 1013: expression must be a constant
@item 1014: illegal section type
@item 1015: repeatedly defined symbol
@item 1016: illegal memory type
@item 1017: unexpected %s without %s
@item 1018: endc/endif missing for conditional block started at %s line %d
@item 1020: maximum if-nesting depth exceeded (%d levels)
@item 1022: missing %c

@end itemize
