331 lines
12 KiB
Plaintext
331 lines
12 KiB
Plaintext
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.
|
|
|
|
@section Legal
|
|
|
|
This module is written in 2015 by Frank Wille and
|
|
is covered by the vasm copyright without modifications.
|
|
|
|
@section General Syntax
|
|
|
|
A statement may contain up to four fields which are identified by order
|
|
of appearance and terminating characters. The general form is:
|
|
@example
|
|
label: operator operand(s) ; comment
|
|
@end example
|
|
|
|
Labels must not start at the first column, as they are identified by the
|
|
mandatory terminating colon (@code{:}) character. A double colon (@code{::})
|
|
automatically makes the label externally visible.
|
|
|
|
Labels preceded by '@code{.}' 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 (@code{=}) can be used as an alias for @code{equ}.
|
|
A double-equals (@code{==}) automatically makes the symbol externally
|
|
visible.
|
|
@example
|
|
symbol equate expression ; comment
|
|
@end example
|
|
|
|
Identifiers, like symbols or labels, may start with any upper- or lower-case
|
|
character, a dot (@code{.}), question-mark (@code{?}) or underscore
|
|
(@code{_}). The remaining characters may be any alphanumeric character,
|
|
a dollar-sign (@code{$}), question-mark (@code{?}) or underscore (@code{_}).
|
|
|
|
The operands are separated from the operator by whitespace. Multiple
|
|
operands are separated by comma (@code{,}).
|
|
|
|
Comments are introduced by the comment character @code{;}. The asterisk
|
|
(@code{*}) can be used at the first column to start a comment.
|
|
The rest of the line will be ignored.
|
|
|
|
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 other numbers starting with a digit are decimal, e.g. @code{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.
|
|
|
|
|
|
@section 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 (@code{.}).
|
|
|
|
@table @code
|
|
@item <symbol> = <expression>
|
|
Equivalent to @code{<symbol> equ <expression>}.
|
|
|
|
@item <symbol> == <expression>
|
|
Equivalent to @code{<symbol> equ <expression>}, but declare <symbol>
|
|
as externally visible.
|
|
|
|
@item assert <expresion>[,<expression>...]
|
|
Assert that all conditions are true (non-zero), otherwise issue a
|
|
warning.
|
|
|
|
@item bss
|
|
The following data (space definitions) are going into the BSS section.
|
|
The BSS section cannot contain any initialized data.
|
|
|
|
@item data
|
|
The following data are going into the data section, which usually
|
|
contains pre-initialized data and no executable code.
|
|
|
|
@item dc <exp1>[,<exp2>...]
|
|
Equivalent to @code{dc.w}.
|
|
|
|
@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.i <exp1>[,<exp2>...]
|
|
Assign the values of the operands into successive 32-bit words
|
|
of memory in the current section. In contrast to @code{dc.l} the
|
|
high and low half-words will be swapped as with the Jaguar-RISC
|
|
@code{movei} instruction.
|
|
|
|
@item dc.l <exp1>[,<exp2>...]
|
|
Assign the values of the operands into successive 32-bit words
|
|
of memory in the current section.
|
|
|
|
@item dc.w <exp1>[,<exp2>...]
|
|
Assign the values of the operands into successive 16-bit words
|
|
of memory in the current section.
|
|
|
|
@item dcb
|
|
Equivalent to @code{dcb.w}.
|
|
|
|
@item dcb.b <exp>[,<fill>]
|
|
Insert <exp> zero or <fill> bytes into the current section.
|
|
|
|
@item dcb.l <exp>[,<fill>]
|
|
Insert <exp> zero or <fill> 32-bit words into the current section.
|
|
|
|
@item dcb.w <exp>[,<fill>]
|
|
Insert <exp> zero or <fill> 16-bit words into the current section.
|
|
|
|
@item dphrase
|
|
Align the program counter to the next integral double phrase
|
|
boundary (16 bytes).
|
|
|
|
@item ds <exp>
|
|
Equivalent to @code{dcb.w <exp>,0}.
|
|
|
|
@item ds.b <exp>
|
|
Equivalent to @code{dcb.b <exp>,0}.
|
|
|
|
@item ds.l <exp>
|
|
Equivalent to @code{dcb.l <exp>,0}.
|
|
|
|
@item ds.w <exp>
|
|
Equivalent to @code{dcb.w <exp>,0}.
|
|
|
|
@item else
|
|
Else-part of a conditional-assembly block. Refer to '@code{if}'.
|
|
|
|
@item 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.
|
|
|
|
@item endif
|
|
Ends a block 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 even
|
|
Align the program counter to an even value, by inserting a zero-byte
|
|
when it is odd.
|
|
|
|
@item exitm
|
|
Exit the current macro (proceed to @code{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 @code{if} directives).
|
|
|
|
@item extern <symbol>[,<symbol>...]
|
|
Declare the given symbols as externally defined. Internally there is
|
|
no difference to @code{globl}, as both declare the symbols, no
|
|
matter if defined or not, as externally visible.
|
|
|
|
@item 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 (@code{::}) on labels or a double-equal (@code{==})
|
|
on equate-symbols.
|
|
|
|
@item if <expression>
|
|
Start of block of conditional assembly. If <expression> is true, the
|
|
block between '@code{if}' and the matching '@code{endif}' or
|
|
'@code{else}' will be assembled. When false, ignore all lines until
|
|
and '@code{else}' or '@code{endif}' directive is encountered.
|
|
It is possible to leave such a block early from within an include
|
|
file (with @code{end}) or a macro (with @code{endm}).
|
|
|
|
@item 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.
|
|
|
|
@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} in the order
|
|
of occurence.
|
|
|
|
@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} in the order of occurence.
|
|
|
|
@item list
|
|
The following lines will appear in the listing file, if it was
|
|
requested.
|
|
|
|
@item long
|
|
Align the program counter to the next integral longword boundary
|
|
(4 bytes), by inserting as many zero-bytes as needed.
|
|
|
|
@item macro <name> [<argname>[,<argname>...]]
|
|
Defines a macro which can be referenced by <name> (case-sensitive).
|
|
The macro definition is terminated by an @code{endm} directive
|
|
and may be exited by @code{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 @code{\1} to @code{\9} and @code{\0} for the tenth.
|
|
Optionally you can specify a list of argument names, which are
|
|
referenced with a leading backslash character (@code{\}) within the macro.
|
|
The special code @code{\~} inserts a unique id, useful for
|
|
defining labels. @code{\#} is replaced by the number of arguments.
|
|
@code{\!} writes the the size-qualifier (M68k) including the dot.
|
|
@code{\?argname} expands to @code{1} when the named argument is
|
|
specified and non-empty, otherwise it expands to @code{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.
|
|
|
|
@item macundef <name>[,<name>...]
|
|
Undefine one or more already defined macros, making them unknown for
|
|
the following source to assemble.
|
|
|
|
@item nlist
|
|
The following lines will not be visible in a listing file.
|
|
|
|
@item nolist
|
|
The following lines will not be visible in a listing file.
|
|
|
|
@item 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 @code{.68000} (Jaguar only).
|
|
|
|
@item phrase
|
|
Align the program counter to the next integral phrase
|
|
boundary (8 bytes).
|
|
|
|
@item 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.
|
|
@table @code
|
|
@item /x
|
|
hexadecimal
|
|
@item /d
|
|
signed decimal
|
|
@item /u
|
|
unsigned decimal
|
|
@item /w
|
|
16-bit word
|
|
@item /l
|
|
32-bit longword
|
|
@end table
|
|
For example:
|
|
@example
|
|
.print "Value: ", /d/l xyz
|
|
@end example
|
|
|
|
@item qphrase
|
|
Align the program counter to the next integral quad phrase
|
|
boundary (32 bytes).
|
|
|
|
@item rept <expression>
|
|
The block between @code{rept} and @code{endr} will be repeated
|
|
<expression> times, which has to be positive.
|
|
|
|
@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 text
|
|
The following code and data is going into the text section, which
|
|
usually is the first program section, containing the executable code.
|
|
|
|
@end table
|
|
|
|
|
|
@section Known Problems
|
|
|
|
Some known problems of this module at the moment:
|
|
|
|
@itemize @minus
|
|
|
|
@item Not all Madmac, smac and extended Jaguar-Madmac directives are
|
|
supported.
|
|
|
|
@item Expressions are not evaluated left-to-right, but mathematically
|
|
correct.
|
|
|
|
@item Square-brackets (@code{[]}) are currently not supported to
|
|
prioritize terms, as an alternative for parentheses.
|
|
|
|
@item Functions (@code{^^func}) are currently not supported.
|
|
|
|
@end itemize
|
|
|
|
|
|
@section Error Messages
|
|
|
|
This module has the following error messages:
|
|
|
|
@itemize @minus
|
|
@item 1001: malformed immediate-if
|
|
@item 1003: cannot export local symbol
|
|
@item 1004: no space before operands
|
|
@item 1005: too many closing parentheses
|
|
@item 1006: missing closing parentheses
|
|
@item 1007: missing operand
|
|
@item 1008: garbage at end of line
|
|
@item 1009: unknown print format flag '%c'
|
|
@item 1010: invalid data operand
|
|
@item 1011: print format corrupted
|
|
@item 1012: identifier expected
|
|
@item 1014: unexpected "%s" without "%s"
|
|
@end itemize
|