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