32218e1aaf49a5e5b8b42330e7d37ad3b3da729e
[rmac] / docs / rmac.rst
1 RMAC
2 ----
3 68000 Macro Assembler
4 =====================
5 Reference Manual
6 ================
7 version 1.6.5
8 =============
9
10 © and notes
11 ===========
12
13 *NOTE: Every effort has been made to ensure the accuracy and robustness of this
14 manual and the associated software. However, because Reboot is constantly improving
15 and updating its computer software, it is unable to guarantee
16 the accuracy of printed or duplicated material after the date of publication and
17 disclaims liability for changes, errors or omissions.*
18
19
20 *Copyright © 2011-2017, Reboot*
21
22 *All rights reserved.*
23
24 *Reboot Document number F00000K-001 Rev. A.*
25
26 Contents
27 ========
28
29 .. contents::
30
31 Introduction
32 ============
33
34 Introduction
35 ''''''''''''
36 This document describes RMAC, a fast macro assembler for the 68000. RMAC currently
37 runs on the any POSIX compatible platform and the Atari ST. It was initially written
38 at Atari Corporation by programmers who needed a high performance assembler
39 for their work. Then, more than 20 years later, because there was still a need for
40 such an assembler and what was available wasn't up to expectations, Subqmod
41 and eventually Reboot continued work on the freely released source, adding Jaguar extensions
42 and fixing bugs.
43
44 RMAC is intended to be used by programmers who write mostly in assembly language.
45 It was not originally a back-end to a C compiler, therefore it
46 has creature comfort that are usually neglected in such back-end assemblers. It
47 supports include files, macros, symbols with limited scope, some limited control
48 structures, and other features. RMAC is also blindingly fast, another feature
49 often sadly and obviously missing in today's assemblers.\ [1]_
50
51 RMAC is not entirely compatible with the AS68 assembler provided with
52 the original Atari ST Developer's Kit, but most changes are minor and a few minutes
53 with an editor should allow you to assemble your current source files. If you are an
54 AS68 user, before you leap into the unknown please read the section on Notes for
55 AS68 Users.
56
57 .. [1] It processes 30,000 lines a minute on a lightly loaded VAX 11/780; maybe 40,000 on a 520-ST with an SH-204 hard disk. Yet it could be sped up even more with some effort and without resorting to assembly language; C doesn't have to be slow!
58
59 `Getting Started`_
60 ''''''''''''''''''
61
62  =>Write protect your distribution disk and make a backup of it now. Put the
63    original disk in a safe place.
64
65 * The distribution disk contains a file called README that you should read.
66   This file contains important nays about the contents of the distribution disk
67   and summarizes the most recent changes to the tools.
68
69 * Hard disk users can simply copy the executable files to their work or binary
70   directories. People with floppy disks can copy the executables to ramdisks,
71   install the assembler with the -q option, or even work right off of the floppies.
72
73 * You will need an editor that can produce "normal" format text files. Micro
74   Emacs will work well, as will most other commercial program editors, but not
75   most word processors (such as First Word or Microsoft Write).
76
77 * You will probably want to examine or get a listing of the file "ATARI.S". It
78   contains lots of definitions for the Atari ST, including BIOS variables, most
79   BIOS, XBIOS and GEMDOS traps, and line-A equates. We (or you) could
80   split the file up into pieces (a file for line-A equates, a file for hardware and
81   BIOS variables and so on), but RMAC is so fast that it doesn't matter
82   much.
83
84 * Read the rest of the manual, especially the first two chapters on The Command Line and Using RMAC.
85   Also, `Notes for migrating from other 68000 assemblers`_ will save a lot of time and frustration in the long run.
86   The distribution disk contains example
87   programs that you can look at, assemble and modify.
88
89 `The Command Line`_
90 '''''''''''''''''''
91
92 The assembler is called "**rmac**" or "**rmac.prg**". The command line takes the form:
93
94                           **rmac** [*switches*] [*files* ...]
95
96 A command line consists of any number of switches followed by the names of files
97 to assemble. A switch is specified with a dash (**-**) followed immediately by a key
98 character. Key characters are not case-sensitive, so "**-d**" is the same as "**-D**". Some
99 switches accept (or require) arguments to immediately follow the key character,
100 with no spaces in between.
101
102 Switch order is important. Command lines are processed from left to right in
103 one pass, and switches usually take effect when they are encountered. In general it
104 is best to specify all switches before the names of any input files.
105
106 If the command line is entirely empty then RMAC prints a copyright message
107 along with usage info and exit.
108
109 Input files are assumed to have the extension "**.s**"; if a filename has no extension
110 (i.e. no dot) then "**.s**" will be appended to it. More than one source filename may be
111 specified: the files are assembled into one object file, as if they were concatenated.
112
113 RMAC normally produces object code in "**file.o**" if "**file.s**" is the first
114 input filename. If the first input file is a special character device, the output name
115 is noname.o. The **-o** switch (see below) can be used change the output file name.
116
117
118 ===================  ===========
119 Switch               Description
120 ===================  ===========
121 -dname\ *[=value]*   Define symbol, with optional value.
122 -e\ *[file[.err]]*   Direct error messages to the specified file.
123 -fa                  ALCYON output object file format (implied with **-ps** is enabled).
124 -fb                  BSD COFF output object file format.
125 -fe                  ELF output object file format.
126 -fx                  Atari 800 com/exe/xex output object file format.
127 -i\ *path*           Set include-file directory search path.
128 -l\ *[file[prn]]*    Construct and direct assembly listing to the specified file.
129 -l\ *\*[filename]*   Create an output listing file without pagination
130 -o\ *file[.o]*       Direct object code output to the specified file.
131 +/~oall              Turn all optimisations on/off
132 +o\ *0-3*            Enable specific optimisation
133 ~o\ *0-3*            Disable specific optimisation
134
135                       `0: Absolute long adddresses to word`
136                       
137                       `1: move.l #x,dn/an to moveq`
138
139                       `2: Word branches to short
140                       
141                       `3: Outer displacement 0(an) to (an)`                      
142 -p                   Produce an executable (**.prg**) output file.
143 -ps                  Produce an executable (**.prg**) output file with symbols.
144 -q                   Make RMAC resident in memory (Atari ST only).
145 -r *size*            automatically pad the size of each
146                      segment in the output file until the size is an integral multiple of the
147                      specified boundary. Size is a letter that specifies the desired boundary.
148                                          
149                       `-rw Word (2 bytes, default alignment)`
150
151                       `-rl Long (4 bytes)`
152
153                       `-rp Phrase (8 bytes)`
154                       
155                       `-rd Double Phrase (16 bytes)`
156                       
157                       `-rq Quad Phrase (32 bytes)`
158 -s                   Warn about unoptimized long branches and applied optimisations.
159 -u                   Force referenced and undefined symbols global.
160 -v                   Verbose mode (print running dialogue).
161 -x                   Turn on debugging mode
162 -yn                  Set listing page size to n lines.
163 file\ *[s]*          Assemble the specified file.
164 ===================  ===========
165
166 The switches are described below. A summary of all the switches is given in
167 the table.
168
169 **-d**
170  The **-d** switch permits symbols to be defined on the command line. The name
171  of the symbol to be defined immediately follows the switch (no spaces). The
172  symbol name may optionally be followed by an equals sign (=) and a decimal
173  number. If no value is specified the symbol's value is zero. The symbol at-
174  tributes are "defined, not referenced, and absolute". This switch is most useful
175  for enabling conditionally-assembled debugging code on the command line; for
176  example:
177
178   ::
179
180       -dDEBUG -dLoopCount=999 -dDebugLevel=55
181
182 **-e**
183  The -e switch causes RMAC to send error messages to a file, instead of the
184  console. If a filename immediately follows the switch character, error messages
185  are written to the specified file. If no filename is specified, a file is created with
186  the default extension "**.err**" and with the root name taken from the first input
187  file name (e.g. error messages are written to "**file.err**" if "**file**" or "**file.s**" is
188  the first input file name). If no errors are encountered, then no error listing
189  file is created. Beware! If an assembly produces no errors, any error file from
190  a previous assembly is not removed.
191
192 **-i**
193  The **-i** switch allows automatic directory searching for include files. A list of
194  semi-colon seperated directory search paths may be mentioned immediately
195  following the switch (with no spaces anywhere). For example:
196
197   ::
198
199          -im:;c:include;c:include\sys
200
201  will cause the assembler to search the current directory of device **M**, and the
202  directories include and include\sys on drive **C**. If *-i* is not specified, and the
203  enviroment variable "**RMACPATH**" exists, its value is used in the same manner.
204  For example, users of the Mark Williams shell could put the following line in
205  their profile script to achieve the same result as the **-i** example above:
206
207   ::
208
209       setenv RMACPATH="m:;c:include;c:include\sys"
210 **-l**
211  The -l switch causes RMAC to generate an assembly listing file. If a file-
212  name immediately follows the switch character, the listing is written to the
213  specified file. If no filename is specified, then a listing file is created with the
214  default extension "**.prn**" and with the root name taken from the first input file
215  name (e.g. the listing is written to "**file.prn**" if "**file**" or "**file.s**" is the first
216  input file name).
217 **-o**
218  The -o switch causes RMAC to write object code on the specified file. No
219  default extension is applied to the filename. For historical reasons the filename
220  can also be seperated from the switch with a space (e.g. "**-o file**").
221
222 **-p**
223
224 **-ps**
225  The **-p** and **-ps** switches cause RMAC to produce an Atari ST executable
226  file with the default extension of "**.prg**". If there are any external references
227  at the end of the assembly, an error message is emitted and no executable file
228  is generated. The **-p** switch does not write symbols to the executable file. The
229  **-ps** switch includes symbols (Alcyon format) in the executable file.
230 **-q**
231   The **-q** switch is aimed primarily at users of floppy-disk-only systems. It causes
232   RMAC to install itself in memory, like a RAMdisk. Then the program
233   **m.prg** (which is very short - less than a sector) can be used instead of
234   **mac.prg**, which can take ten or twelve seconds to load. (**NOTE** not available
235   for now, might be re-implemented in the future).
236 **-s**
237   The **-s** switch causes RMAC to generate a list of unoptimized forward
238   branches as warning messages. This is used to point out branches that could
239   have been short (e.g. "bra" could be "bra.s").
240 **-u**
241   The **-u** switch takes effect at the end of the assembly. It forces all referenced
242   and undefined symbols to be global, exactly as if they had been made global
243   with a **.extern** or **.globl** directive. This can be used if you have a lot of
244   external symbols, and you don't feel like declaring them all external.
245 **-v**
246   The **-v** switch turns on a "verbose" mode in which RMAC prints out (for
247   example) the names of the files it is currently processing. Verbose mode is
248   automatically entered when RMAC prompts for input with a star.
249 **-y**
250   The **-y** switch, followed immediately by a decimal number (with no intervening
251   space), sets the number of lines in a page. RMAC will produce *N* lines
252   before emitting a form-feed. If *N* is missing or less than 10 an error message is
253   generated.
254
255 `Using RMAC`_
256 ===============
257
258 Let's assemble and link some example programs. These programs are included
259 on the distribution disk in the "**EXAMPLES**" directory - you should copy them to
260 your work area before continuing. In the following examples we adopt the conven-
261 tions that the shell prompt is a percent sign (%) and that your input (the stuff you
262 type) is presented in **bold face**.
263
264 If you have been reading carefully, you know that RMAC can generate
265 an executable file without linking. This is useful for making small, stand alone
266 programs that don't require externals or library routines. For example, the following
267 two commands:
268
269  ::
270
271       % rmac examples
272       % aln -s example.s
273
274 could be replaced by the single command:
275
276  ::
277
278       % rmac -ps example.s
279
280 since you don't need the linker for stand-alone object files.
281
282 Successive source files named in the command line are are concatenated, as in
283 this example, which assembles three files into a single executable, as if they were
284 one big file:
285
286  ::
287
288       % rmac -p bugs shift images
289
290 Of course you can get the same effect by using the **.include** directive, but sometimes
291 it is convenient to do the concatenation from the command line.
292
293    Here we have an unbelievably complex command line:
294
295     ::
296
297       % rmac -lzorf -y95 -o tmp -ehack -Ddebug=123 -ps example
298
299 This produces a listing on the file called "**zorf.prn**" with 95 lines per page, writes
300 the executable code (with symbols) to a file called "**tmp.prg**", writes an error listing
301 to the file "**hack.err**", specifies an include-file path that includes the current
302 directory on the drive "**M:**," defines the symbol "**debug**" to have the value 123, and
303 assembles the file "**example.s**". (Take a deep breath - you got all that?)
304
305 One last thing. If there are any assembly errors, RMAC will terminate
306 with an exit code of 1. If the assembly succeeds (no errors, although there may be
307 warnings) the exit code will be 0. This is primarily for use with "make" utilities.
308
309 Things You Should Be Aware Of
310 '''''''''''''''''''''''''''''
311 RMAC is a one pass assembler. This means that it gets all of its work done by
312 reading each source file exactly once and then "back-patching" to fix up forward
313 references. This one-pass nature is usually transparent to the programmer, with
314 the following important exceptions:
315
316  o in listings, the object code for forward references is not shown. Instead, lower-
317    case "xx"s are displayed for each undefined byte, as in the following example:
318
319     ::
320
321      60xx   1: bra.s.2  ;forward branch
322      xxxxxxxx  dc.l .2  ;forward reference
323      60FE  .2: bra.s.2  ;backward reference
324
325  o Forward branches (including **BSR**\s) are never optimized to their short forms.
326    To get a short forward branch it is necessary to explicitly use the ".s" suffix in
327    the source code.
328  o Error messages may appear at the end of the assembly, referring to earlier source
329    lines that contained undefined symbols.
330  o All object code generated must fit in memory. Running out of memory is a
331    fatal error that you must deal with by splitting up your source files, re-sizing
332    or eliminating memory-using programs such as ramdisks and desk accessories,
333    or buying more RAM.
334
335 Forward Branches
336 ''''''''''''''''
337 RMAC does not optimize forward branches for you, but it will tell you about
338 them if you use the -s (short branch) option:
339
340  ::
341
342      % mac -s example.s
343      "example.s", line 20: warning: unoptimized short branch
344
345 With the -e option you can redirect the error output to a file, and determine by
346 hand (or editor macros) which forward branches are safe to explicitly declare short.
347
348 `Notes for migrating from other 68000 assemblers`_
349 ''''''''''''''''''''''''''''''''''''''''''''''''''
350 RMAC is not entirely compatible with the other popular assemblers
351 like Devpac or vasm. This section
352 outlines the major differences. In practice, we have found that very few changes are
353 necessary to make other assemblers' source code assemble.
354
355 o A semicolon (;) must be used to introduce a comment,
356   except that a star (*)
357   may be used in the first column. AS68 treated anything following the operand
358   field, preceeded by whitespace, as a comment. (RMAC treats a star that
359   is not in column 1 as a multiplication operator).
360 o Labels require colons (even labels that begin in column 1).
361
362 o Conditional assembly directives are called **if**, **else** and **endif**.
363   Devpac and vasm called these
364   **ifne**, **ifeq** (etc.), and **endc**.
365 o The tilde (~) character is an operator, and back-quote (`) is an illegal character.
366   AS68 permitted the tilde and back-quote characters in symbols.
367 o There are no equivalents to org or section directives.
368   The **.xdef** and **.xref** directives are not implemented,
369   but **.globl** makes these unnecessary anyway.
370
371   o The location counter cannot be manipulated with a statement of the form:
372
373   ::
374
375                                 * = expression
376
377 o The **ds** directive is not permitted in the text or data segments;
378   an error message is issued. Use **dcb** instead to reserve large blocks of
379   initialized storage.
380 o Back-slashes in strings are "electric" characters that are used to escape C-like
381   character codes. Watch out for GEMDOS path names in ASCII constants -
382   you will have to convert them to double-backslashes.
383 o Expression evaluation is done left-to-right without operator precedence. Use parentheses to
384   force the expression evaluation as you wish.
385 o Mark your segments across files.
386   Branching to a code segment that could be identified as BSS will cause a "Error: cannot initialize non-storage (BSS) section"
387 o rs.b/rs.w/rs.l/rscount/rsreset can be simulated in rmac using abs.
388   For example the following source:
389
390   ::
391
392    rsreset
393    label1: rs.w 1
394    label2: rs.w 10
395    label3: rs.l 5
396    label4: rs.b 2
397    
398    size_so_far equ rscount
399
400   can be converted to:
401
402   ::
403
404    abs
405    label1: ds.w 1
406    label2: ds.w 10
407    label3: ds.l 5
408    label4: ds.b 2
409    
410    size_so_far equ ^^abscount
411 o A rare case: if your macro contains something like:
412
413   ::
414
415    macro test
416    move.l #$\1,d0
417    endm
418
419    test 10
420
421   then by the assembler's design this will fail as the parameters are automatically converted to hex. Changing the code like this works:
422
423   ::
424
425    macro test
426    move.l #\1,d0
427    endm
428
429    test $10
430
431 `Text File Format`_
432 '''''''''''''''''''
433 For those using editors other than the "Emacs" style ones (Micro-Emacs, Mince,
434 etc.) this section documents the source file format that RMAC expects.
435
436  o Files must contain characters with ASCII values less than 128; it is not per-
437    missable to have characters with their high bits set unless those characters are
438    contained in strings (i.e. between single or double quotes) or in comments.
439
440  o Lines of text are terminated with carriage-return/line-feed, linefeed alone, or
441    carriage-return alone.
442
443  o The file is assumed to end with the last terminated line. If there is text beyond
444    the last line terminator (e.g. control-Z) it is ignored.
445
446 `Source Format`_
447 ================
448
449 `Statements`_
450 '''''''''''''
451 A statement may contain up to four fields which are identified by order of ap-
452 pearance and terminating characters. The general form of an assembler statement
453 is:
454
455   ::
456
457       label: operator operand(s)  ; comment
458
459 The label and comment fields are optional. An operand field may not appear
460 without an operator field. Operands are seperated with commas. Blank lines are
461 legal. If the first character on a line is an asterisk (*) or semicolon (;) then the
462 entire line is a comment. A semicolon anywhere on the line (except in a string)
463 begins a comment field which extends to the end of the line.
464
465 The label, if it appears, must be terminated with a single or double colon. If
466 it is terminated with a double colon it is automatically declared global. It is illegal
467 to declare a confined symbol global (see: `Symbols and Scope`_).
468
469 `Equates`_
470 ''''''''''
471 A statement may also take one of these special forms:
472
473       *symbol* **equ** *expression*
474
475       *symbol* **=** *expression*
476
477       *symbol* **==** *expression*
478
479       *symbol* **set** *expression*
480
481       *symbol* **reg** *register list*
482
483 The first two forms are identical; they equate the symbol to the value of an
484 expression, which must be defined (no forward references). The third form, double-
485 equals (==), is just like an equate except that it also makes the symbol global. (As
486 with labels, it is illegal to make a confined equate global.) The fourth form allows
487 a symbol to be set to a value any number of times, like a variable. The last form
488 equates the symbol to a 16-bit register mask specified by a register list. It is possible
489 to equate confined symbols (see: `Symbols and Scope`_). For example:
490
491   ::
492
493       cr    equ    13          carriage-return
494       if    =      10          line-feed
495       DEBUG ==     1           global debug flag
496       count set    0           variable
497       count set    count + 1   increment variable
498       .rags reg    d3-d7/a3-a6 register list
499       .cr          13          confined equate
500
501 `Symbols and Scope`_
502 ''''''''''''''''''''
503 Symbols may start with an uppercase or lowercase letter (A-Z a-z), an underscore
504 (**_**), a question mark (**?**) or a period (**.**). Each remaining character may be an
505 upper or lowercase letter, a digit (**0-9**), an underscore, a dollar sign (**$**), or a question
506 mark. (Periods can only begin a symbol, they cannot appear as a symbol
507 continuation character). Symbols are terminated with a character that is not a
508 symbol continuation character (e.g. a period or comma, whitespace, etc.). Case is
509 significant for user-defined symbols, but not for 68000 mnemonics, assembler direc-
510 tives and register names. Symbols are limited to 100 characters. When symbols
511 are written to the object file they are silently truncated to eight (or sixteen) char-
512 acters (depending on the object file format) with no check for (or warnings about)
513 collisions.
514
515    For example, all of the following symbols are legal and unique:
516
517      ::
518
519       reallyLongSymbolName .reallyLongConfinedSymbolName
520       a10 ret move dc frog aa6 a9 ????
521       .a1 .ret .move .dc .frog .a9 .9 ????
522       .0  .00  .000 .1  .11. .111 . ._
523       _frog ?zippo? sys$syetem atari Atari ATARI aTaRi
524
525 while all of the following symbols are illegal:
526
527      ::
528
529       12days dc.10   dc.z   'quote  .right.here
530       @work hi.there $money$ ~tilde
531
532
533 Symbols beginning with a period (**.**) are *confined*; their scope is between two
534 normal (unconfined) labels. Confined symbols may be labels or equates. It is illegal
535 to make a confined symbol global (with the ".globl" directive, a double colon, or a
536 double equals). Only unconfined labels delimit a confined symbol's scope; equates
537 (of any kind) do not count. For example, all symbols are unique and have unique
538 values in the following:
539
540    ::
541
542       zero:: subq.w $1,d1
543              bmi.s .ret
544       .loop: clr.w (a0)+
545              dbra  d0,.loop
546       .ret:  rta
547       FF::   subq.w #1,d1
548              bmi.s .99
549       .loop: move.w -1,(a0)+
550              dbra  d0,.loop
551       .99:   its
552
553 Confined symbols are useful since the programmer has to be much less inventive
554 about finding small, unique names that also have meaning.
555
556 It is legal to define symbols that have the same names as processor mnemonics
557 (such as "**move**" or "**rts**") or assembler directives (such as "**.even**"). Indeed, one
558 should be careful to avoid typographical errors, such as this classic (in 6502 mode):
559
560     ::
561
562              .6502
563       .org   =     $8000
564
565
566 which equates a confined symbol to a hexadecimal value, rather than setting the
567 location counter, which the .org directive does (without the equals sign).
568
569 `Keywords`_
570 '''''''''''
571 The following names, in all combinations of uppercase and lowercase, are keywords
572 and may not be used as symbols (e.g. labels, equates, or the names of macros):
573
574    ::
575
576       equ set reg
577       sr ccr pc sp ssp usp
578       d0 d1 d2 d3 d4 d5 d6 d7
579       a0 a1 a2 a3 a4 a5 a6 a7
580       r0 r1 r2 r3 r4 r5 r6 r7
581       r8 r9 r10 r11 r12 rl3 r14 ri5
582
583 `Constants`_
584 ''''''''''''
585 Numbers may be decimal, hexadecimal, octal, binary or concatenated ASCII. The
586 default radix is decimal, and it may not be changed. Decimal numbers are specified
587 with a string of digits (**0-9**). Hexadecimal numbers are specified with a leading
588 dollar sign (**$**) followed by a string of digits and uppercase or lowercase letters (**A-F
589 a-f**). Octal numbers are specified with a leading at-sign (**@**) followed by a string
590 of octal digits (**0-7**). Binary numbers are specified with a leading percent sign
591 (**%**) followed by a string of binary digits (**0-1**). Concatenated ASCII constants are
592 specified by enclosing from one to four characters in single or double quotes. For
593 example:
594
595     ::
596
597       1234   *decimal*
598       $1234  *hexadecimal*
599       @777   *octal*
600       %10111 *binary*
601       "z"    *ASCII*
602       'frog' *ASCII*
603
604 Negative numbers Are specified with a unary minus (**-**). For example:
605
606     ::
607
608       -5678  -@334 -$4e71
609       -%11011 -'z' -"WIND"
610
611 `Strings`_
612 ''''''''''
613 Strings are contained between double (") or single ( ') quote marks. Strings may
614 contain non-printable characters by specifying "backslash" escapes, similar to the
615 ones used in the C programming language. RMAC will generate a warning if a
616 backslash is followed by a character not appearing below:
617
618     ::
619
620       \\    $5c    backslash
621       \n    $0a    line-feed (newline)
622       \b    $08    backspace
623       \t    $09    tab
624       \r    $0c1   carriage-return
625       \f    $0c    form-feed
626       \e    $1b    escape
627       \'    $27    single-quote
628       \"    $22    double-quote
629
630 It is possible for strings (but not symbols) to contain characters with their high
631 bits set (i.e. character codes 128...255).
632
633 You should be aware that backslash characters are popular in GEMDOS path
634 names, and that you may have to escape backslash characters in your existing source
635 code. For example, to get the file "'c:\\auto\\ahdi.s'" you would specify the string
636 "`c:\\\\auto\\\\ahdi.s`".
637
638 `Register Lists`_
639 '''''''''''''''''
640 Register lists are special forms used with the **movem** mnemonic and the **.reg**
641 directive. They are 16-bit values, with bits 0 through 15 corresponding to registers
642 **D0** through **A7**. A register list consists of a series of register names or register
643 ranges seperated by slashes. A register range consists of two register names, Rm
644 and Rn,m<n, seperated by a dash. For example:
645
646      ::
647
648        register list           value
649        -------------           -----
650        d0-d7/a0-a7             $FFFF
651        d2-d7/a0/a3-a6          $39FC
652        d0/d1/a0-a3/d7/a6-a7    $CF83
653        d0                      $0001
654        r0-r16                  $FFFF
655
656 Register lists and register equates may be used in conjunction with the movem
657 mnemonic, as in this example:
658
659      ::
660
661        temps   reg     d0-d2/a0-a2     ; temp registers
662        keeps   reg     d3-d7/d3-a6     ; registers to preserve
663        allregs reg     d0-d7/a0-a7     ; all registers
664                movem.l #temps,-(sp)    ; these two lines ...
665                movea.l d0-d2/a0-a2,-(sp) ; are identical
666                movem.l #keeps,-(sp)    ; save "keep" registers
667                movem.l (sp)+,#keeps    ; restore "keep" registers
668
669
670 `Expressions`_
671 ==============
672 `Order of Evaluation`_
673 ''''''''''''''''''''''
674 All values are computed with 32-bit 2's complement arithmetic. For boolean operations
675 (such as if or **assert**) zero is considered false, and non-zero is considered
676 true.
677
678      **Expressions are evaluated strictly left-to-right, with no
679      regard for operator precedence.**
680
681 Thus the expression "1+2*3" evaluates to 9, not 7. However, precedence may be
682 forced with parenthesis (**()**) or square-brackets (**[]**).
683
684 `Types`_
685 '''''''''
686 Expressions belong to one of three classes: undefined, absolute or relocatable. An
687 expression is undefined if it involves an undefined symbol (e.g. an undeclared sym-
688 bol, or a forward reference). An expression is absolute if its value will not change
689 when the program is relocated (for instance, the number 0, all labels declared in
690 an abs section, and all Atari ST hardware register locations are absolute values).
691 An expression is relocatable if it involves exactly one symbol that is contained in a
692 text, data or BSS section.
693
694 Only absolute values may be used with operators other than addition (+) or
695 subtraction (-). It is illegal, for instance, to multiply or divide by a relocatable or
696 undefined value. Subtracting a relocatable value from another relocatable value in
697 the same section results in an absolute value (the distance between them, positive
698 or negative). Adding (or subtracting) an absolute value to or from a relocatable
699 value yeilds a relocatable value (an offset from the relocatable address).
700
701 It is important to realize that relocatable values belong to the sections they
702 are defined in (e.g. text, data or BSS), and it is not permissible to mix and match
703 sections. For example, in this code:
704
705     ::
706
707      linel:  dc.l   line2, line1+8
708      line2:  dc.l   line1, line2-8
709      line3:  dc.l   line2-line1, 8
710      error:  dc.l   line1+line2, line2 >> 1, line3/4
711
712 Line 1 deposits two longwords that point to line 2. Line 2 deposits two longwords
713 that point to line 1. Line 3 deposits two longwords that have the absolute value
714 eight. The fourth line will result in an assembly error, since the expressions (re-
715 spectively) attempt to add two relocatable values, shift a relocatable value right by
716 one, and divide a relocatable value by four.
717
718 The pseudo-symbol "*****" (star) has the value that the current section's location
719 counter had at the beginning of the current source line. For example, these two
720 statements deposit three pointers to the label "**bar**":
721
722     ::
723
724      too:    dc.l   *+4
725      bar:    dc.l   *, *
726
727 Similarly, the pseudo-symbol "**$**" has the value that the current section's location
728 counter has, and it is kept up to date as the assembler deposits information
729 "across" a line of source code. For example, these two statements deposit four
730 pointers to the label "zip":
731
732         ::
733
734           zip:      dc.l      $+8, $+4
735           zop:      dc.l      $, $-4
736
737 `Unary Operators`_
738 ''''''''''''''''''
739
740 ================================    ========================================
741 Operator                            Description
742 ================================    ========================================
743 **-**                               Unary minus (2's complement).
744 **!**                               Logical (boolean) NOT.
745 **~**                               Tilde: bitwise not (l's complement).
746 **^^defined** *symbol*              True if symbol has a value.
747 **^^referenced** *symbol*           True if symbol has been referenced.
748 **^^streq** *stringl*,*string2*     True if the strings are equal.
749 **^^macdef** *macroName*            True if the macro is defined.
750 **^^abscount**                      Returns the size of current .abs section
751 ================================    ========================================
752
753  o The boolean operators generate the value 1 if the expression is true, and 0 if it is not.
754
755  o A symbol is referenced if it is involved in an expression.
756      A symbol may have
757      any combination of attributes: undefined and unreferenced, defined and unref-
758      erenced (i.e. declared but never used), undefined and referenced (in the case
759      of a forward or external reference), or defined and referenced.
760
761
762
763 `Binary Operators`_
764 '''''''''''''''''''
765
766 ===========  ==============================================
767 Operator     Description
768 ===========  ==============================================
769 \ + - * /    The usual arithmetic operators.
770 %            Modulo. Do *not* attempt to modulo by 0 or 1.
771 & | ^        Bit-wise **AND**, **OR** and **Exclusive-OR**.
772 << >>        Bit-wise shift left and shift right.
773 < <=  >=  >  Boolean magnitude comparisons.
774 =            Boolean equality.
775 <>  !=       Boolean inequality.
776 ===========  ==============================================
777
778  o All binary operators have the same precedence:
779    expressions are evaluated strictly left to right.
780
781  o Division or modulo by zero yields an assembly error.
782
783    o The "<>" and "!=" operators are synonyms.
784
785    o Note that the modulo operator (%) is also used to introduce binary constants
786      (see: `Constants`_). A percent sign should be followed by at least one space if
787      it is meant to be a modulo operator, and is followed by a '0' or '1'.
788
789 `Special Forms`_
790 ''''''''''''''''
791
792 ============    =========================================
793 Special Form    Description
794 ============    =========================================
795 **^^date**      The current system date (Gemdos format).
796 **^^time**      The current system time (Gemdos format).
797 ============    =========================================
798
799    o The "**^^date**" special form expands to the current system date, in Gemdos
800      format. The format is a 16-bit word with bits 0 ...4 indicating the day of the
801      month (1...31), bits 5...8 indicating the month (1...12), and bits 9...15
802      indicating the year since 1980, in the range 0...119.
803
804    o The "**^^time**" special form expands to the current system time, in Gemdos
805      format. The format is a 16-bit word with bits 0...4 indicating the current
806      second divided by 2, bits 5...10 indicating the current minute 0...59. and
807      bits 11...15 indicating the current hour 0...23.
808
809 `Example Expressions`_
810 ''''''''''''''''''''''
811
812        ::
813
814         line address contents      source code
815         ---- ------- --------      -------------------------------
816            1 00000000 4480         lab1:  neg.l  d0
817            2 00000002 427900000000 lab2:  clr.w  lab1
818            3         =00000064     equ1   =      100
819            4         =00000096     equ2   =      equ1 + 50
820            5 00000008 00000064            dc.l   lab1 + equ1
821            6 0000000C 7FFFFFE6            dc.l   (equl + ~equ2) >> 1
822            7 00000010 0001                dc.w   ^^defined equl
823            8 00000012 0000                dc.w   ^^referenced lab2
824            9 00000014 00000002            dc.l   lab2
825           10 00000018 0001                dc.w   ^^referenced lab2
826           11 0000001A 0001                dc.w   lab1 = (lab2 - 6)
827
828 Lines 1 through four here are used to set up the rest of the example. Line 5 deposits
829 a relocatable pointer to the location 100 bytes beyond the label "**lab1**". Line 6 is
830 a nonsensical expression that uses the and right-shift operators. Line 7 deposits
831 a word of 1 because the symbol "**equ1**" is defined (in line 3).
832
833 Line 8 deposits a word of 0 because the symbol "**lab2**", defined in line 2, has
834 not been referenced. But the expression in line 9 references the symbol "**lab2**", so
835 line 10 (which is a copy of line-8) deposits a word of 1. Finally, line 11 deposits a
836 word of 1 because the Boolean equality operator evaluates to true.
837
838 The operators "**^^defined**" and "**^^referenced**" are particularly useful in
839 conditional assembly. For instance, it is possible to automatically include debugging
840 code if the debugging code is referenced, as in:
841
842       ::
843
844                lea    string,a0            ; AO -> message
845                jsr    debug                ; print a message
846                its                         ; and return
847         string: dc.b  "Help me, Spock!",0  ; (the message)
848                     .
849                     .
850                     .
851                .iif ^^defined debug, .include "debug.s"
852
853 The **jsr** statement references the symbol debug. Near the end of the source file, the
854 "**.iif**" statement includes the file "**debug.s**" if the symbol debug was referenced.
855
856 In production code, presumably all references to the debug symbol will be removed,
857 and the debug source file will not be included. (We could have as easily made the
858 symbol **debug** external, instead of including another source file).
859
860
861 `Directives`_
862 =============
863
864 Assembler directives may be any mix of upper- or lowercase. The leading periods
865 are optional, though they are shown here and their use is encouraged. Directives
866 may be preceeded by a label; the label is defined before the directive is executed.
867 Some directives accept size suffixes (**.b**, **.s**, **.w** or **.1**); the default is word (**.w**) if no
868 size is specified. The **.s** suffix is identical to **.b**. Directives relating to the 6502 are
869 described in the chapter on `6502 Support`_.
870
871
872
873 **.even**
874
875    If the location counter for the current section is odd, make it even by adding
876    one to it. In text and data sections a zero byte is deposited if necessary.
877 **.long**
878
879    Align the program counter to the next integral long boundary (4 bytes).
880    Note that GPU/DSP code sections are not contained in their own
881    segments and are actually part of the TEXT or DATA segments.
882    Therefore, to align GPU/DSP code, align the current section before and
883    after the GPU/DSP code.
884 **.phrase**
885
886    Align the program counter to the next integral phrase boundary (8 bytes).
887    Note that GPU/DSP code sections are not contained in their own
888    segments and are actually part of the TEXT or DATA segments.
889    Therefore, to align GPU/DSP code, align the current section before and
890    after the GPU/DSP code.
891 **.dphrase**
892
893    Align the program counter to the next integral double phrase boundary (16
894    bytes). Note that GPU/DSP code sections are not contained in their own
895    segments and are actually part of the TEXT or DATA segments.
896    Therefore, to align GPU/DSP code, align the current section before and
897    after the GPU/DSP code.
898 **.qphrase**
899
900    Align the program counter to the next integral quad phrase boundary (32
901    bytes). Note that GPU/DSP code sections are not contained in their own
902    segments and are actually part of the TEXT or DATA segments.
903    Therefore, to align GPU/DSP code, align the current section before and
904    after the GPU/DSP code.
905 **.assert** *expression* [,\ *expression*...]
906
907    Assert that the conditions are true (non-zero). If any of the comma-seperated
908    expressions evaluates to zero an assembler warning is issued. For example:
909
910           ::
911
912            .assert *-start = $76
913            .assert stacksize >= $400
914
915 **.bss**
916
917 **.data**
918
919 **.text**
920
921    Switch to the BSS, data or text segments. Instructions and data may not
922    be assembled into the BSS-segment, but symbols may be defined and storage
923    may be reserved with the **.ds** directive. Each assembly starts out in the text
924    segment.
925 **.abs** [*location*]
926
927    Start an absolute section, beginning with the specified location (or zero, if
928    no location is specified). An absolute section is much like BSS, except that
929    locations declared with .ds are based absolute. This directive is useful for
930
931    declaring structures or hardware locations.
932    For example, the following equates:
933
934           ::
935
936            VPLANES = 0
937            VWRAP   = 2
938            CONTRL  = 4
939            INTIN   = 8
940            PTSIN   = 12
941
942    could be as easily defined as:
943
944           ::
945
946                    .abs
947            VPLANES: ds.w    1
948            VWRAP:  ds.w     1
949            CONTRL: ds.l     1
950            INTIE:  ds.l     1
951            PTSIN:  ds.l     1
952
953    Another interesting example worth mentioning is the emulation of "C"'s "union" keyword
954    using *.abs*. For example, the following "C" code:
955
956           ::
957
958            struct spritesheet
959            {
960                 short spf_w;
961                 short spf_h;
962                 short spf_xo;
963                 short spf_yo;
964                 union { int spf_em_colour;     int spf_emx_colour;    };
965                 union { int spf_em_psmask[16]; int spf_emx_colouropt; };
966            }
967
968    can be expressed as:
969
970           ::
971
972            .abs
973            *-------------------------------------------------------*
974            spf_w:          ds.w    1   ;<- common
975            spf_h:          ds.w    1
976            spf_xo:         ds.w    1
977            spf_yo:         ds.w    1
978            spf_data:       ds.l    0
979            *-------------------------------------------------------*
980            ;           .union  set
981            spf_em_colour:      ds.l    1   ;<- union #1
982            spf_em_psmask:      ds.l    16
983            *-------------------------------------------------------*
984            .68000
985                        .abs spf_em_colour
986            ;           .union  reset
987            spf_emx_colour:     ds.l    1   ;<- union #2
988            spf_emx_colouropt:  ds.l    1
989            spf_emx_psmask:     ds.l    16
990            spf_emx_psmaskopt:  ds.l    16
991            
992            .68000
993            ;*-------------------------------------------------------*
994            
995                move #spf_em_colour,d0
996                move #spf_emx_colour,d0
997
998    In this example, *spf_em_colour* and *spf_emx_colour* will have the same value.
999            
1000 **.comm** *symbol*, *expression*
1001
1002    Specifies a label and the size of a common region. The label is made global,
1003    thus confined symbols cannot be made common. The linker groups all common
1004    regions of the same name; the largest size determines the real size of the
1005    common region when the file is linked.
1006 **.ccdef** *expression*
1007
1008    Allows you to define names for the condition codes used by the JUMP
1009    and JR instructions for GPU and DSP code. For example:
1010
1011     ::
1012    
1013      Always .ccdef 0
1014      . . .
1015           jump Always,(r3) ; ‘Always’ is actually 0
1016
1017 **.ccundef** *regname*
1018
1019    Undefines a register name (regname) previously assigned using the
1020    .CCDEF directive. This is only implemented in GPU and DSP code
1021    sections.     
1022 **.dc.i** *expression*
1023
1024    This directive generates long data values and is similar to the DC.L
1025    directive, except the high and low words are swapped. This is provided
1026    for use with the GPU/DSP MOVEI instruction.
1027 **.dc**\ [.\ *size*] *expression* [, *expression*...]
1028
1029    Deposit initialized storage in the current section. If the specified size is word
1030    or long, the assembler will execute a .even before depositing data. If the size
1031    is .b, then strings that are not part of arithmetic expressions are deposited
1032    byte-by-byte. If no size is specified, the default is .w. This directive cannot be
1033    used in the BSS section.
1034 **.dcb**\ [.\ *size*] *expression1*, *expression2*
1035
1036    Generate an initialized block of *expression1* bytes, words or longwords of the
1037    value *expression2*. If the specified size is word or long, the assembler will
1038    execute .even before generating data. If no size is specified, the default is **.w**.
1039    This directive cannot be used in the BSS section.
1040 **.ds**\ [.\ *size*] *expression*
1041
1042    Reserve space in the current segment for the appropriate number of bytes,
1043    words or longwords. If no size is specified, the default size is .w. If the size
1044    is word or long, the assembler will execute .even before reserving space. This
1045    directive can only be used in the BSS or ABS sections (in text or data, use
1046    .dcb to reserve large chunks of initialized storage.)
1047 **.dsp**
1048
1049    Switch to Jaguar DSP assembly mode. This directive must be used
1050    within the TEXT or DATA segments.
1051 **.init**\ [.\ *size*] [#\ *expression*,]\ *expression*\ [.\ *size*] [,...]
1052
1053    Generalized initialization directive. The size specified on the directive becomes
1054    the default size for the rest of the line. (The "default" default size is **.w**.) A
1055    comma-seperated list of expressions follows the directive; an expression may be
1056    followed by a size to override the default size. An expression may be preceeded
1057    by a sharp sign, an expression and a comma, which specifies a repeat count to
1058    be applied to the next expression. For example:
1059
1060       ::
1061
1062        .init.l -1, 0.w, #16,'z'.b, #3,0, 11.b
1063
1064    will deposit a longword of -1, a word of zero, sixteen bytes of lower-case 'z',
1065    three longwords of zero, and a byte of 11.
1066
1067    No auto-alignment is performed within the line, but a **.even** is done once
1068    (before the first value is deposited) if the default size is word or long.
1069 **.cargs** [#\ *expression*,] *symbol*\ [.\ *size*] [, *symbol*\ [.\ *size*].. .]
1070
1071    Compute stack offsets to C (and other language) arguments. Each symbol is
1072    assigned an absolute value (like equ) which starts at expression and increases
1073    by the size of each symbol, for each symbol. If the expression is not supplied,
1074    the default starting value is 4. For example:
1075
1076     ::
1077
1078      .cargs #8, .fileliams.1, .openMode, .butPointer.l
1079
1080    could be used to declare offsets from A6 to a pointer to a filename, a word
1081    containing an open mode, and a pointer to a buffer. (Note that the symbols
1082    used here are confined). Another example, a C-style "string-length" function,
1083    could be written as:
1084
1085         ::
1086
1087          _strlen:: .cargs .string     ; declare arg
1088                move.l .string(sp),a0  ; a0 -> string
1089                moveq  #-1,d0          ; initial size = -1
1090          .1:   addq.1 #1,d0           ; bump size
1091                tst.b  (a0)+           ; at end of string?
1092                bne   .1               ; (no -- try again)
1093                rts                    ; return string length
1094
1095 **.end**
1096
1097    End the assembly. In an include file, end the include file and resume assembling
1098    the superior file. This statement is not required, nor are warning messages
1099    generated if it is missing at the end of a file. This directive may be used inside
1100    conditional assembly, macros or **.rept** blocks.
1101 **.equr** *expression*
1102
1103    Allows you to name a register. This is only implemented for GPU/DSP
1104    code sections. For example:
1105
1106     ::
1107
1108      Clipw .equr r19
1109      . . .
1110           add ClipW,r0 ; ClipW actually is r19
1111
1112 **.if** *expression*
1113
1114 **.else**
1115
1116 **.endif**
1117
1118    Start a block of conditional assembly. If the expression is true (non-zero) then
1119    assemble the statements between the .if and the matching **.endif** or **.else**.
1120    If the expression is false, ignore the statements unless a matching .else is
1121    encountered. Conditional assembly may be nested to any depth.
1122
1123    It is possible to exit a conditional assembly block early from within an include
1124    file (with **end**) or a macro (with **endm**).
1125
1126 **.iif** *expression*, *statement*
1127
1128    Immediate version of **.if**. If the expression is true (non-zero) then the state-
1129    ment, which may be an instruction, a directive or a macro, is executed. If
1130    the expression is false, the statement is ignored. No **.endif** is required. For
1131    example:
1132
1133         ::
1134
1135          .iif age < 21, canDrink = 0
1136          .iif weight > 500, dangerFlag = 1
1137          .iif !(^^defined DEBUG), .include dbsrc
1138
1139 **.macro** *name* [*formal*, *formal*,...]
1140
1141 **.endm**
1142
1143 **.exitm**
1144
1145    Define a macro called name with the specified formal arguments. The macro
1146    definition is terminated with a **.endm** statement. A macro may be exited early
1147    with the .exitm directive. See the chapter on `Macros`_ for more information.
1148
1149 **.undefmac** *macroName* [, *macroName*...]
1150
1151    Remove the macro-definition for the specified macro names. If reference is
1152    made to a macro that is not defined, no error message is printed and the name
1153    is ignored.
1154
1155 **.rept** *expression*
1156
1157 **.endr**
1158
1159    The statements between the **.rept** and **.endr** directives will be repeated *expression*
1160    times. If the expression is zero or negative, no statements will be
1161    assembled. No label may appear on a line containing either of these directives.
1162
1163 **.globl** *symbol* [, *symbol*...]
1164
1165 **.extern** *symbol* [, *symbol*...]
1166
1167    Each symbol is made global. None of the symbols may be confined symbols
1168    (those starting with a period). If the symbol is defined in the assembly, the
1169    symbol is exported in the object file. If the symbol is undefined at the end
1170    of the assembly, and it was referenced (i.e. used in an expression), then the
1171    symbol value is imported as an external reference that must be resolved by the
1172    linker. The **.extern** directive is merely a synonym for **.globl**.
1173
1174 **.include** "*file*"
1175
1176    Include a file. If the filename is not enclosed in quotes, then a default extension
1177    of "**.s**" is applied to it. If the filename is quoted, then the name is not changed
1178    in any way.
1179
1180    Note: If the filename is not a valid symbol, then the assembler will generate an
1181              error message. You should enclose filenames such as "**atari.s**" in quotes,
1182              because such names are not symbols.
1183
1184    If the include file cannot be found in the current directory, then the directory
1185    search path, as specified by -i on the commandline, or' by the 'RMACPATH'
1186    enviroment string, is traversed.
1187
1188 **.eject**
1189
1190    Issue a page eject in the listing file.
1191
1192 **.title** "*string*"
1193
1194 **.subttl** [-] "*string*"
1195
1196    Set the title or subtitle on the listing page. The title should be specified on
1197    the the first line of the source program in order to take effect on the first page.
1198    The second and subsequent uses of **.title** will cause page ejects. The second
1199    and subsequent uses of .subttl will cause page ejects unless the subtitle string
1200    is preceeded by a dash (-).
1201
1202 **.list**
1203
1204 **.nlist**
1205
1206    Enable or disable source code listing. These directives increment and decrement
1207    an internal counter, so they may be appropriately nested. They have no effect
1208    if the **-l** switch is not specified on the commandline.
1209
1210 **.goto** *label*
1211
1212    This directive provides unstructured flow of control within a macro definition.
1213    It will transfer control to the line of the macro containing the specified goto
1214    label. A goto label is a symbol preceeded by a colon that appears in the first
1215    column of a source line within a macro definition:
1216
1217                  :  *label*
1218
1219    where the label itself can be any valid symbol name, followed immediately by
1220    whitespace and a valid source line (or end of line). The colon **must** appear in
1221    the first column.
1222
1223    The goto-label is removed from the source line prior to macro expansion -
1224    to all intents and purposes the label is invisible except to the .goto directive
1225    Macro expansion does not take place within the label.
1226
1227    For example, here is a silly way to count from 1 to 10 without using **.rept**:
1228
1229               ::
1230
1231                                .macro Count
1232                  count         set     1
1233                  :loop         dc.w    count
1234                  count         set     count + 1
1235                                iif count <= 10, goto loop
1236                                .endm
1237
1238 **.gpu**
1239
1240    Switch to Jaguar GPU assembly mode. This directive must be used
1241    within the TEXT or DATA segments.
1242 **.gpumain**
1243
1244    No. Just... no. Don't ask about it. Ever.
1245 **.prgflags** *value*
1246
1247    Sets ST executable .PRG field *PRGFLAGS* to *value*. *PRGFLAGS* is a bit field defined as follows:
1248
1249 ============ ======  =======
1250 Definition   Bit(s)  Meaning
1251 ============ ======  =======
1252 PF_FASTLOAD  0       If set, clear only the BSS area on program load, otherwise clear the entire heap. 
1253 PF_TTRAMLOAD 1       If set, the program may be loaded into alternative RAM, otherwise it must be loaded into standard RAM. 
1254 PF_TTRAMMEM  2       If set, the program's Malloc() requests may be satisfied from alternative RAM, otherwise they must be satisfied from standard RAM. 
1255 --           3       Currently unused.
1256 See left.    4 & 5   If these bits are set to 0 (PF_PRIVATE), the processes' entire memory space will be considered private (when memory protection is enabled).If these bits are set to 1 (PF_GLOBAL), the processes' entire memory space will be readable and writable by any process (i.e. global).If these bits are set to 2 (PF_SUPERVISOR), the processes' entire memory space will only be readable and writable by itself and any other process in supervisor mode.If these bits are set to 3 (PF_READABLE), the processes' entire memory space will be readable by any application but only writable by itself. 
1257 --           6-15    Currently unused.
1258 ============ ======  =======
1259
1260 **.regequ** *expression*
1261    Essentially the same as **.EQUR.** Included for compatibility with the GASM
1262    assembler.
1263 **.regundef**
1264    Essentially the same as **.EQURUNDEF.** Included for compatibility with
1265    the GASM assembler.
1266
1267
1268 `68000 Mnemonics`_
1269 ==================
1270
1271 `Mnemonics`_
1272 ''''''''''''
1273 All of the standard Motorola 68000 mnemonics and addressing modes are supported;
1274 you should refer to **The Motorola M68000 Programmer's Reference Manual**
1275 for a description of the instruction set and the allowable addressing modes for each
1276 instruction. With one major exception (forward branches) the assembler performs
1277 all the reasonable optimizations of instructions to their short or address register
1278 forms.
1279
1280 Register names may be in upper or lower case. The alternate forms ``R0`` through
1281 ``R15`` may be used to specify ``D0`` through ``A7``. All register names are keywords, and
1282 may not be used as labels or symbols. None of the 68010 or 68020 register names
1283 are keywords (but they may become keywords in the future).
1284
1285 `Addressing Modes`_
1286 '''''''''''''''''''
1287
1288 =====================================    ===========================================
1289 Assembler Syntax                         Description
1290 =====================================    ===========================================
1291 *Dn*                                     Data register direct
1292 *An*                                     Address register direct
1293 (*An*)                                   Address register indirect
1294 (*An*)+                                  Address register indirect postincrement
1295 -(*An*)                                  Address register indirect predecrement
1296 *disp*\ (*An*)                           Address register indirect with displacement
1297 *bdisp*\ (*An*, *Xi*\ [.\ *size*])       Address register indirect indexed
1298 *abs*.w                                  Absolute short
1299 *abs*                                    Absolute (long or short)
1300 *abs*.l                                  Forced absolute long
1301 *disp*\ (PC)                             Program counter with displacement
1302 *bdisp*\ (PC, *Xi*\ )                    Program counter indexed
1303 #\ *imm*                                 Immediate
1304 =====================================    ===========================================
1305
1306 `Branches`_
1307 '''''''''''
1308 Since RMAC is a one pass assembler, forward branches cannot be automatically
1309 optimized to their short form. Instead, unsized forward branches are assumed to
1310 be long. Backward branches are always optimized to the short form if possible.
1311
1312 A table that lists "extra" branch mnemonics (common synonyms for the Motorola
1313 defined mnemonics) appears below.
1314
1315 `Linker Constraints`_
1316 '''''''''''''''''''''
1317 It is not possible to make an external reference that will fix up a byte. For example:
1318
1319                    ::
1320
1321                      extern frog
1322                     move.l frog(pc,d0),d1
1323
1324 is illegal (and generates an assembly error) when frog is external, because the
1325 displacement occupies a byte field in the 68000 offset word, which the object file
1326 cannot represent.
1327
1328 `Branch Synonyms`_
1329 ''''''''''''''''''
1330 ============== ========
1331 Alternate name Becomes:
1332 ============== ========
1333 bhs            bcc
1334 blo            bcs
1335 bse, bs        beq
1336 bns            bne
1337 dblo           dbcs
1338 dbse           dbeq
1339 dbra           dbf
1340 dbhs           dbhi
1341 dbns           dbne
1342 ============== ========
1343
1344 `Optimizations and Translations`_
1345 '''''''''''''''''''''''''''''''''
1346 The assembler provides "creature comforts" when it processes 68000 mnemonics:
1347
1348  o **CLR.x An** will really generate **SUB.x An,An**.
1349
1350  o **ADD**, **SUB** and **CMP** with an address register will really generate **ADDA**,
1351  **SUBA** and **CMPA**.
1352
1353  o The **ADD**, **AND**, **CMP**, **EOR**, **OR** and **SUB** mnemonics with immediate
1354  first operands will generate the "I" forms of their instructions (**ADDI**, etc.) if
1355  the second operand is not register direct.
1356
1357  o All shift instructions with no count value assume a count of one.
1358
1359  o **MOVE.L** is optimized to **MOVEQ** if the immediate operand is defined and
1360  in the range -128...127. However, **ADD** and **SUB** are never translated to
1361  their quick forms; **ADDQ** and **SUBQ** must be explicit.
1362
1363  o In GPU/DSP code sections, you can use JUMP (Rx) in place of JUMP T, (Rx) and JR
1364   (Rx) in place of JR T,(Rx).
1365  o RMAC tests all GPU/DSP restrictions and corrects them wherever possible (such as
1366   inserting a NOP instruction when needed).
1367  o The “(Rx+N)” addressing mode for GPU/DSP instructions is optimized to “(Rx)”
1368   when “N” is zero.
1369
1370 `Macros`_
1371 =========
1372 `Macro declaration`_
1373 ''''''''''''''''''''
1374 A macro definition is a series of statements of the form:
1375                               ::
1376
1377                                  .macro name [ formal-arg, ...]
1378                                     .
1379                                     .
1380                                     .
1381                                  statements making up the macro body
1382                                     .
1383                                     .
1384                                     .
1385                                  .endm
1386
1387 The name of the macro may be any valid symbol that is not also a 68000 instruction
1388 or an assembler directive. (The name may begin with a period - macros cannot
1389 be made confined the way labels or equated symbols can be). The formal argument
1390 list is optional; it is specified with a comma-seperated list of valid symbol names.
1391 Note that there is no comma between the name of the macro and the name of the
1392 first formal argument.
1393
1394 A macro body begins on the line after the **.macro** directive. All instructions
1395 and directives, except other macro definitions, are legal inside the body.
1396
1397 The macro ends with the **.endm** statement. If a label appears on the line with
1398 this directive, the label is ignored and a warning is generated.
1399
1400 `Parameter Substitution`_
1401 '''''''''''''''''''''''''
1402 Within the body, formal parameters may be expanded with the special forms:
1403               ::
1404
1405                 \name
1406                 \{name}
1407
1408 The second form (enclosed in braces) can be used in situations where the characters
1409 following the formal parameter name are valid symbol continuation characters. This
1410 is usually used to force concatentation, as in:
1411
1412                ::
1413
1414                 \{frog}star
1415                 \(godzilla}vs\{reagan}
1416
1417 The formal parameter name is terminated with a character that is not valid in
1418 a symbol (e.g. whitespace or puncuation); optionally, the name may be enclosed in
1419 curly-braces. The names must be symbols appearing on the formal argument list,
1420 or a single decimal digit (``\1`` corresponds to the first argument, ``\2`` to the second,
1421 ``\9`` to the ninth, and ``\0`` to the tenth). It is possible for a macro to have more than
1422 ten formal arguments, but arguments 11 and on must be referenced by name, not
1423 by number.
1424
1425         Other special forms are:
1426
1427 ============ ================================================
1428 Special Form Description
1429 ============ ================================================
1430 ``\\``       a single "\",
1431 ``\~``       a unique label of the form "Mn"
1432 ``\#``       the number of arguments actually specified
1433 ``\!``       the "dot-size" specified on the macro invocation
1434 ``\?name``   conditional expansion
1435 ``\?{name}`` conditional expansion
1436 ============ ================================================
1437
1438 The last two forms are identical: if the argument is specified and is non-empty, the
1439 form expands to a "1", otherwise (if the argument is missing or empty) the form
1440 expands to a "0".
1441
1442 The form "``\!``" expands to the "dot-size" that was specified when the macro
1443 was invoked. This can be used to write macros that behave differently depending
1444 on the size suffix they are given, as in this macro which provides a synonym for the
1445 "``dc``" directive:
1446
1447               ::
1448
1449                .macro deposit value
1450                dc\!   \value
1451                .endm
1452                deposit.b 1          ; byte of 1
1453                deposit.w 2          ; word of 2
1454                deposit.l 3          ; longvord of 3
1455                deposit   4          ; word of 4 (no explicit size)
1456
1457 `Macro Invocation`_
1458 '''''''''''''''''''
1459 A previously-defined macro is called when its name appears in the operation field of
1460 a statement. Arguments may be specified following the macro name; each argument
1461 is seperated by a comma. Arguments may be empty. Arguments are stored for
1462 substitution in the macro body in the following manner:
1463
1464   o Numbers are converted to hexadecimal.
1465
1466   o All spaces outside strings are removed.
1467
1468   o Keywords (such as register names, dot sizes and "^^" operators) are converted
1469     to lowercase.
1470
1471   o Strings are enclosed in double-quote marks (").
1472
1473 For example, a hypothetical call to the macro "``mymacro``", of the form:
1474        ``mymacro A0, , 'Zorch' / 32, "^^DEFINED foo, , , tick tock``
1475
1476 will result in the translations:
1477
1478 ========      ================= =================================================
1479 Argument      Expansion         Comment
1480 ========      ================= =================================================
1481 ``\1``        ``a0``            "``A0``" converted to lower-case
1482 ``\2``                          empty
1483 ``\3``        ``"Zorch"/$20``   "``Zorch``" in double-quotes, 32 in hexadecimal
1484 ``\4``        ``^^defined foo`` "``^^DEFINED``" converted to lower-case
1485 ``\5``                          empty
1486 ``\6``                          empty
1487 ``\7``        ``ticktock``      spaces removed (note concatenation)
1488 ========      ================= =================================================
1489
1490 The **.exitm** directive will cause an immediate exit from a macro body. Thus
1491 the macro definition:
1492
1493          ::
1494
1495           .macro foo source
1496               .iif !\?source, .exitm ; exit if source is empty
1497               move \source,d0        ; otherwise, deposit source
1498           .endm
1499
1500 will not generate the move instruction if the argument **"source"** is missing from
1501 the macro invocation.
1502
1503 The **.end**, **.endif** and **.exitm** directives all pop-out of their include levels
1504 appropriately. That is, if a macro performs a **.include** to include a source file, an
1505 executed **.exitm** directive within the include-file will pop out of both the include-file
1506 and the macro.
1507
1508 Macros may be recursive or mutually recursive to any level, subject only to
1509 the availability of memory. When writing recursive macros, take care in the coding
1510 of the termination condition(s). A macro that repeatedly calls itself will cause the
1511 assembler to exhaust its memory and abort the assembly.
1512
1513
1514 `Example Macros`_
1515 '''''''''''''''''
1516 The Gemdos macro is used to make file system calls. It has two parameters, a
1517 function number and the number of bytes to clean off the stack after the call. The
1518 macro pushes the function number onto the stack and does the trap to the file
1519 system. After the trap returns, conditional assembly is used to choose an addq or
1520 an **add.w** to remove the arguments that were pushed.
1521
1522      ::
1523
1524        .macro Gemdos trpno, clean
1525           move.w  #\trpno,-(sp)  ; push trap number
1526           trap    #1             ; do GEMDOS trap
1527           .if \clean <= 8        ;
1528           addq    #\clean,sp     ; clean-up up to 8 bytes
1529           .else                  ;
1530           add.w   #\clean,sp     ; clean-up more than 8 bytes
1531           .endif                 ;
1532        .endm
1533
1534 The Fopen macro is supplied two arguments; the address of a filename, and
1535 the open mode. Note that plain move instructions are used, and that the caller of
1536 the macro must supply an appropriate addressing mode (e.g. immediate) for each
1537 argument.
1538
1539      ::
1540
1541        .macro Fopen file, mode
1542           movs.w   \mode,-(sp)  ;push open mode
1543           move.1   \file,-(sp)  ;push address of tile name
1544           Gemdos   $3d,8        ;do the GEMDOS call
1545        .endm
1546
1547 The **String** macro is used to allocate storage for a string, and to place the
1548 string's address somewhere. The first argument should be a string or other expres-
1549 sion acceptable in a dc.b directive. The second argument is optional; it specifies
1550 where the address of the string should be placed. If the second argument is omitted,
1551 the string's address is pushed onto the stack. The string data itself is kept in the
1552 data segment.
1553
1554                   ::
1555
1556                    .macro String str,loc
1557                        .if \?loc                                        ; if loc is defined
1558                          move.l #.\~,\loc                               ; put the string's address there
1559                        .else                                            ; otherwise
1560                          pea .\~                                        ; push the string's address
1561                        .endif                                           ;
1562                        .data                                            ; put the string data
1563                    .\~: dc.b \str,0                                     ;  in the data segment
1564                        .text                                            ; and switch back to the text segment
1565                    .endm
1566
1567 The construction "``.\~``" will expand to a label of the form "``.M``\ *n*" (where *n* is
1568 a unique number for every macro invocation), which is used to tag the location of
1569 the string. The label should be confined because the macro may be used along with
1570 other confined symbols.
1571
1572 Unique symbol generation plays an important part in the art of writing fine
1573 macros. For instance, if we needed three unique symbols, we might write "``.a\~``",
1574 "``.b\~``" and "``.c\~``".
1575
1576 `Repeat Blocks`_
1577 ''''''''''''''''
1578 Repeat-blocks provide a simple iteration capability. A repeat block allows a range
1579 of statements to be repeated a specified number of times. For instance, to generate
1580 a table consisting of the numbers 255 through 0 (counting backwards) you could
1581 write:
1582
1583                   ::
1584
1585                    .count  set     255             ; initialize counter
1586                            .rept 256               ; repeat 256 times:
1587                            dc.b    .count          ;   deposit counter
1588                    .count  set     .count - 1      ;   and decrement it
1589                            .endr                   ; (end of repeat block)
1590
1591 Repeat blocks can also be used to duplicate identical pieces of code (which are
1592 common in bitmap-graphics routines). For example:
1593
1594                   ::
1595
1596                    .rept 16                        ; clear 16 words
1597                    clr.w (a0)+                     ;   starting at AO
1598                    .endr                           ;
1599
1600 `Jaguar GPU/DSP Mode`_
1601 ======================
1602
1603 RMAC will generate code for the Atari jaguar GPU and DSP custom RISC (Reduced
1604 Instruction Set Computer) processors. See the Atari Jaguar Software reference Manual – Tom
1605 & Jerry for a complete listing of Jaguar GPU and DSP assembler mnemonics and addressing
1606 modes.
1607
1608 `Condition Codes`_
1609 ''''''''''''''''''
1610 The following condition codes for the GPU/DSP JUMP and JR instructions are built-in:
1611  
1612   ::
1613
1614    CC (Carry Clear) = %00100
1615    CS (Carry Set)   = %01000
1616    EQ (Equal)       = %00010
1617    MI (Minus)       = %11000
1618    NE (Not Equal)   = %00001
1619    PL (Plus)        = %10100
1620    HI (Higher)      = %00101
1621    T (True)         = %00000
1622
1623                    
1624 `6502 Support`_
1625 ===============
1626 RMAC will generate code for the Motorola 6502 microprocessor. This chapter
1627 describes extra addressing modes and directives used to support the 6502.
1628
1629 As the 6502 object code is not linkable (currently there is no linker) external
1630 references may not be made. (Nevertheless, RMAC may reasonably be used for
1631 large assemblies because of its blinding speed.)
1632
1633 `6502 Addressing Modes`_
1634 ''''''''''''''''''''''''
1635 All standard 6502 addressing modes are supported, with the exception of the
1636 accumulator addressing form, which must be omitted (e.g. "ror a" becomes "ror").
1637 Five extra modes, synonyms for existing ones, are included for compatibility with
1638 the Atari Coinop assembler.
1639
1640 ============== ========================================
1641 *empty*        implied or accumulator (e.g. tsx or ror)
1642 *expr*         absolute or zeropage
1643 #\ *expr*      immediate
1644 #<\ *expr*     immediate low byte of a word
1645 #>\ *expr*     immediate high byte of a word
1646 (*expr*,x)     indirect X
1647 (*expr*),y     indirect Y
1648 (*expr*)       indirect
1649 *expr*,x       indexed X
1650 *expr*,y       indexed Y
1651 @\ *expr*\ (x) indirect X
1652 @\ *expr*\ (y) indirect Y
1653 @expr          indirect
1654 x,\ *expr*     indexed X
1655 y,\ *expr*     indexed Y
1656 ============== ========================================
1657
1658 `6502 Directives`_
1659 ''''''''''''''''''
1660 **.6502**
1661    This directive enters the 6502 section. The location counter is undefined, and
1662    must be set with ".org" before any code can be generated.
1663
1664    The "``dc.w``" directive will produce 6502-format words (low byte first). The
1665    68000's reserved keywords (``d0-d7/a0-a7/ssp/usp`` and so on) remain reserved
1666    (and thus unusable) while in the 6502 section. The directives **globl**, **dc.l**,
1667    **dcb.l**, **text**, **data**, **bss**, **abs**, **even** and **comm** are illegal in the 6502 section.
1668    It is permitted, though probably not useful, to generate both 6502 and 68000
1669    code in the same object file.
1670 **.68000**
1671    This directive leaves the 6502 segment and returns to the 68000's text segment.
1672    68000 instructions may be assembled as normal.
1673 **.org** *location*
1674    This directive is only legal in the 6502 section. It sets the value of the location
1675    counter (or **pc**) to location, an expression that must be defined, absolute, and
1676    less than $10000.
1677
1678    WARNING
1679
1680    It is possible to assemble "beyond" the microprocessor's 64K address space, but
1681    attempting to do so will probably screw up the assembler. DO NOT attempt
1682    to generate code like this:
1683
1684      ::
1685
1686       .org $fffe
1687       nop
1688       nop
1689       nop
1690
1691    the third NOP in this example, at location $10000, may cause the assembler
1692    to crash or exhibit spectacular schizophrenia. In any case, RMAC will give
1693    no warning before flaking out.
1694
1695 `6502 Object Code Format`_
1696 ''''''''''''''''''''''''''
1697 Traditionally Madmac had a very kludgy way of storing object files. This has been
1698 replaced with a more standard *.exe* (or *.com* or *.xex* if you prefer). Briefly,
1699 the *.exe* format consists of chunks of this format (one after the other):
1700
1701     ::
1702
1703      Offset     Description
1704      00-01      $FFFF - Indicates a binary load file. Mandatory for first segment, optional for any other segment
1705      02-03      Start Address. The segment will load at this address
1706      04-05      End Address. The last byte to load for this segment
1707      06-..      The actual segment data to load (End Address-Start Address + 1 bytes)
1708
1709 `Error Messages`_
1710 =================
1711
1712 `When Things Go Wrong`_
1713 '''''''''''''''''''''''
1714 Most of RMAC's error messages are self-explanatory. They fall into four classes:
1715 warnings about situations that you (or the assembler) may not be happy about,
1716 errors that cause the assembler to not generate object files, fatal errors that cause
1717 the assembler to abort immediately, and internal errors that should never happen.\ [3]_
1718
1719 You can write editor macros (or sed or awk scripts) to parse the error messages
1720 RMAC generates. When a message is printed, it is of the form:
1721
1722          "*filename*" , ``line`` *line-number*: *message*
1723
1724 The first element, a filename enclosed in double quotes, indicates the file that generated
1725 the error. The filename is followed by a comma, the word "``line``", and a line
1726 number, and finally a colon and the text of the message. The filename "**(\*top\*)**"
1727 indicates that the assembler could not determine which file had the problem.
1728
1729 The following sections list warnings, errors and fatal errors in alphabetical
1730 order, along with a short description of what may have caused the problem.
1731
1732 .. [3] If you come across an internal error, we would appreciate it if you would contact Atari Technical Support and let us know about the problem.
1733
1734 `Warnings`_
1735 '''''''''''
1736 **bad backslash code in string**
1737   You tried to follow a backslash in a string with a character that the assembler
1738   didn't recognize. Remember that RMAC uses a C-style escape system in
1739   strings.
1740 **label ignored**
1741   You specified a label before a macro, **rept** or **endm** directive. The assembler
1742   is warning you that the label will not be defined in the assembly.
1743 **unoptimized short branch**
1744   This warning is only generated if the -s switch is specified on the command
1745   line. The message refers to a forward, unsized long branch that you could have
1746   made short (.s).
1747
1748 `Fatal Errors`_
1749 '''''''''''''''
1750
1751 **cannot continue**
1752   As a result of previous errors, the assembler cannot continue processing. The
1753   assembly is aborted.
1754 **line too long as a result of macro expansion**
1755   When a source line within a macro was expanded, the resultant line was too
1756   long for RMAC (longer than 200 characters or so).
1757
1758
1759 **memory exhausted**
1760     The assembler ran out of memory. You should (1) split up your source files
1761     and assemble them seperately, or (2) if you have any ramdisks or RAM-resident
1762     programs (like desk accessories) decrease their size so that the assembler has
1763     more RAM to work with. As a rule of thumb, pure 68000 code will use up to
1764     twice the number of bytes contained in the source files, whereas 6502 code will
1765     use 64K of ram right away, plus the size of the source files. The assembler itself
1766     uses about 80K bytes. Get out your calculator...
1767 **too many ENDMs**
1768     The assembler ran across an **endm** directive when it wasn't expecting to see
1769     one. The assembly is aborted. Check the nesting of your macro definitions -
1770     you probably have an extra **endm**.
1771
1772
1773 `Errors`_
1774 '''''''''
1775
1776 **.cargs syntax**
1777
1778     Syntax error in **.cargs** directive.
1779 **.comm symbol already defined**
1780
1781     You tried to ``.comm`` a symbol that was already defined.
1782 **.ds permitted only in BSS**
1783
1784     You tried to use ``.ds`` in the text or data section.
1785 **.init not permitted in BSS or ABS**
1786
1787     You tried to use ``.init`` in the BSS or ABS section.
1788 **.org permitted only in .6502 section**
1789
1790     You tried to use ``.org`` in a 68000 section.
1791 **Cannot create:** *filename*
1792
1793     The assembler could not create the indicated filename.
1794 **External quick reference**
1795
1796     You tried to make the immediate operand of a **moveq**, **subq** or **addq** instruction external.
1797 **PC-relative expr across sections**
1798
1799     You tried to make a PC-relative reference to a location contained in another
1800     section.
1801 **[bwsl] must follow '.' in symbol**
1802
1803     You tried to follow a dot in a symbol name with something other than one of
1804     the four characters 'B', 'W', 'S' or 'L'.
1805 **addressing mode syntax**
1806
1807     You made a syntax error in an addressing mode.
1808 **assert failure**
1809
1810     One of your **.assert** directives failed!
1811 **bad (section) expression**
1812
1813     You tried to mix and match sections in an expression
1814 **bad 6502 addressing mode**
1815
1816     The 6502 mnemonic will not work with the addressing mode you specified.
1817 **bad expression**
1818
1819     There's a syntax error in the expression you typed.
1820 **bad size specified**
1821
1822   You tried to use an inappropriate size suffix for the instruction. Check your
1823   68000 manual for allowable sizes.
1824 **bad size suffix**
1825
1826   You can't use .b (byte) mode with the **movem** instruction.
1827 **cannot .globl local symbol**
1828
1829   You tried to make a confined symbol global or common.
1830 **cannot initialize non-storage (BSS) section**
1831
1832   You tried to generate instructions (or data, with dc) in the BSS or ABS section.
1833 **cannot use '.b' with an address register**
1834
1835   You tried to use a byte-size suffix with an address register. The 68000 does not
1836   perform byte-sized address register operations.
1837 **directive illegal in .6502 section**
1838
1839   You tried to use a 68000-oriented directive in the 6502 section.
1840 **divide by zero**
1841
1842   The expression you typed involves a division by zero.
1843 **expression out of range**
1844
1845   The expression you typed is out of range for its application.
1846 **external byte reference**
1847
1848   You tried to make a byte-sized reference to an external symbol, which the
1849   object file format will not allow
1850 **external short branch**
1851
1852   You tried to make a short branch to an external symbol, which the linker cannot
1853   handle.
1854 **extra (unexpected) text found after addressing mode**
1855
1856   RMAC thought it was done processing a line, but it ran up against "extra"
1857   stuff. Be sure that any comment on the line begins with a semicolon, and check
1858   for dangling commas, etc.
1859 **forward or undefined .assert**
1860
1861   The expression you typed after a **.assert** directive had an undefined value.
1862   Remember that RMAC is one-pass.
1863 **hit EOF without finding matching .endif**
1864
1865   The assembler fell off the end of last input file without finding a **.endif** to
1866   match an . it. You probably forgot a **.endif** somewhere.
1867 **illegal 6502 addressing mode**
1868
1869   The 6502 instruction you typed doesn't work with the addressing mode you
1870   specified.
1871 **illegal absolute expression**
1872
1873   You can't use an absolute-valued expression here.
1874 **illegal bra.s with zero offset**
1875
1876   You can't do a short branch to the very next instruction (read your 68000
1877   manual).
1878 **illegal byte-sized relative reference**
1879
1880   The object file format does not permit bytes contain relocatable values; you
1881   tried to use a byte-sized relocatable expression in an immediate addressing
1882   mode.
1883 **illegal character**
1884
1885  Your source file contains a character that RMAC doesn't allow. (most
1886  control characters fall into this category).
1887 **illegal initialization of section**
1888
1889  You tried to use .dc or .dcb in the BSS or ABS sections.
1890 **illegal relative address**
1891
1892  The relative address you specified is illegal because it belongs to a different
1893  section.
1894 **illegal word relocatable (in .PRG mode)**
1895
1896  You can't have anything other than long relocatable values when you're gener-
1897  ating a **.PRG** file.
1898 **inappropriate addressing mode**
1899
1900  The mnemonic you typed doesn't work with the addressing modes you specified.
1901  Check your 68000 manual for allowable combinations.
1902 **invalid addressing mode**
1903
1904  The combination of addressing modes you picked for the **movem** instruction
1905  are not implemented by the 68000. Check your 68000 reference manual for
1906  details.
1907 **invalid symbol following ^^**
1908
1909  What followed the ^^ wasn't a valid symbol at all.
1910 **mis-nested .endr**
1911
1912  The assembler found a **.endr** directive when it wasn't prepared to find one.
1913  Check your repeat-block nesting.
1914 **mismatched .else**
1915
1916  The assembler found a **.else** directive when it wasn't prepared to find one.
1917  Check your conditional assembly nesting.
1918 **mismatched .endif**
1919
1920  The assembler found a **.endif** directive when it wasn't prepared to find one.
1921  Check your conditional assembly nesting.
1922
1923 **missing '='**
1924
1925 **missing '}'**
1926
1927 **missing argument name**
1928
1929 **missing close parenthesis ')'**
1930
1931 **missing close parenthesis ']'**
1932
1933 **missing comma**
1934
1935 **missing filename**
1936
1937 **missing string**
1938
1939 **missing symbol**
1940
1941 **missing symbol or string**
1942
1943  The assembler expected to see a symbol/filename/string (etc...), but found
1944  something else instead. In most cases the problem should be obvious.
1945 **misuse of '.', not allowed in symbols**
1946
1947  You tried to use a dot (.) in the middle of a symbol name.
1948 **mod (%) by zero**
1949
1950  The expression you typed involves a modulo by zero.
1951 **multiple formal argument definition**
1952
1953   The list of formal parameter names you supplied for a macro definition includes
1954   two identical names.
1955 **multiple macro definition**
1956
1957   You tried to define a macro which already had a definition.
1958 **non-absolute byte reference**
1959
1960   You tried to make a byte reference to a relocatable value, which the object file
1961   format does not allow.
1962 **non-absolute byte value**
1963
1964   You tried to dc.b or dcb.b a relocatable value. Byte relocatable values are
1965   not permitted by the object file format.
1966 **register list order**
1967
1968   You tried to specify a register list like **D7-D0**, which is illegal. Remember
1969   that the first register number must be less than or equal to the second register
1970   number.
1971 **register list syntax**
1972
1973   You made an error in specifying a register list for a **.reg** directive or a **.movem**
1974   instruction.
1975 **symbol list syntax**
1976
1977   You probably forgot a comma between the names of two symbols in a symbol
1978   list, or you left a comma dangling on the end of the line.
1979 **syntax error**
1980
1981   This is a "catch-all" error.
1982 **undefined expression**
1983
1984   The expression has an undefined value because of a forward reference, or an
1985   undefined or external symbol.
1986 **unimplemented addressing mode**
1987
1988   You tried to use 68020 "square-bracket" notation for a 68020 addressing mode.
1989   RMAC does not support 68020 addressing modes.
1990 **unimplemented directive**
1991
1992   You have found a directive that didn't appear in the documentation. It doesn't
1993   work.
1994 **unimplemented mnemonic**
1995
1996   You've found an assembler for documentation) bug.
1997 **unknown symbol following ^^**
1998
1999   You followed a ^^ with something other than one of the names defined, ref-
2000   erenced or streq.
2001 **unsupported 68020 addressing mode**
2002
2003   The assembler saw a 68020-type addressing mode. RMAC does not assem-
2004   ble code for the 68020 or 68010.
2005 **unterminated string**
2006
2007   You specified a string starting with a single or double quote, but forgot to type
2008   the closing quote.
2009 **write error**
2010
2011   The assembler had a problem writing an object file. This is usually caused by
2012   a full disk, or a bad sector on the media.