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