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