13 *NOTE: Every effort has been made to ensure the accuracy and robustness of this
14 manual and the associated software. However, the authors are constantly improving
15 and updating its computer software, we 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.*
20 *Copyright © 2011-2022, the rmac authors*
22 *All rights reserved.*
34 This document describes RMAC, a fast macro assembler for the 68000. RMAC currently
35 runs on the any POSIX compatible platform and the Atari ST. It was initially written
36 at Atari Corporation by programmers who needed a high performance assembler
37 for their work. Then, more than 20 years later, because there was still a need for
38 such an assembler and what was available wasn't up to expectations, Subqmod
39 and eventually the rmac authors continued work on the freely released source, adding Jaguar
40 extensions and fixing bugs. Over time the assembler has been extended by adding
41 support for Motorola's 68020/30/40/60, 68881/2, DSP56001 CPUs as well as Atari's
42 Object Processor (OP) found on the Atari Jaguar.
44 RMAC is intended to be used by programmers who write mostly in assembly language.
45 It was not originally a back-end to a C compiler, therefore it
46 has creature comfort that are usually neglected in such back-end assemblers. It
47 supports include files, macros, symbols with limited scope, some limited control
48 structures, and other features. RMAC is also blindingly fast, another feature
49 often sadly and obviously missing in today's assemblers.\ [1]_
51 RMAC is not entirely compatible with the AS68 assembler provided with
52 the original Atari ST Developer's Kit, but most changes are minor and a few minutes
53 with an editor should allow you to assemble your current source files. If you are an
54 AS68 user, before you leap into the unknown please read the section on Notes for
57 .. [1] It processes 30,000 lines a minute on a lightly loaded VAX 11/780; maybe 40,000 on a 520-ST with an SH-204 hard disk. Yet it could be sped up even more with some effort and without resorting to assembly language; C doesn't have to be slow!
63 * The distribution disk contains a file called README that you should read.
64 This file contains important nays about the contents of the distribution disk
65 and summarizes the most recent changes to the tools.
67 * Hard disk users can simply copy the executable files to their work or binary
68 directories. People with floppy disks can copy the executables to ramdisks,
69 install the assembler with the -q option, or even work right off of the floppies.
71 * You will need an editor that can produce "normal" format text files. Micro
72 Emacs will work well, as will most other commercial program editors, but not
73 most word processors (such as First Word or Microsoft Write).
75 * You will probably want to examine or get a listing of the file "ATARI.S". It
76 contains lots of definitions for the Atari ST, including BIOS variables, most
77 BIOS, XBIOS and GEMDOS traps, and line-A equates. We (or you) could
78 split the file up into pieces (a file for line-A equates, a file for hardware and
79 BIOS variables and so on), but RMAC is so fast that it doesn't matter
82 * Read the rest of the manual, especially the first two chapters on The Command Line and Using RMAC.
83 Also, `Notes for migrating from other 68000 assemblers`_ will save a lot of time and frustration in the long run.
84 The distribution disk contains example
85 programs that you can look at, assemble and modify.
90 The assembler is called "**rmac**" or "**rmac.prg**". The command line takes the form:
92 **rmac** [*switches*] [*files* ...]
94 A command line consists of any number of switches followed by the names of files
95 to assemble. A switch is specified with a dash (**-**) followed immediately by a key
96 character. Key characters are not case-sensitive, so "**-d**" is the same as "**-D**". Some
97 switches accept (or require) arguments to immediately follow the key character,
98 with no spaces in between.
100 Switch order is important. Command lines are processed from left to right in
101 one pass, and switches usually take effect when they are encountered. In general it
102 is best to specify all switches before the names of any input files.
104 If the command line is entirely empty then RMAC prints a copyright message
105 along with usage info and exit.
107 Input files are assumed to have the extension "**.s**"; if a filename has no extension
108 (i.e. no dot) then "**.s**" will be appended to it. More than one source filename may be
109 specified: the files are assembled into one object file, as if they were concatenated.
111 RMAC normally produces object code in "**file.o**" if "**file.s**" is the first
112 input filename. If the first input file is a special character device, the output name
113 is noname.o. The **-o** switch (see below) can be used change the output file name.
116 =================== ===========
118 =================== ===========
119 -dname\ *[=value]* Define symbol, with optional value.
120 -e\ *[file[.err]]* Direct error messages to the specified file.
121 -fa ALCYON output object file format (implied when **-ps** is enabled).
122 -fb BSD COFF output object file format.
123 -fb Commodore 64 PRG format.
124 -fe ELF output object file format.
125 -fr Absolute address. Source code is required to have one .org statement.
126 -fx Atari 800 com/exe/xex output object file format.
127 -g Generate source level debug info. Requires BSD COFF object file format.
128 -i\ *path* Set include-file directory search path.
129 -l\ *[file[prn]]* Construct and direct assembly listing to the specified file.
130 -l\ *\*[filename]* Create an output listing file without pagination.
131 -m\ *cpu* Switch CPU type
151 `tom - Jaguar GPU JRISC`
153 `jerry - Jaguar DSP JRISC`
155 -o\ *file[.o]* Direct object code output to the specified file.
156 +/~oall Turn all optimisations on/off
157 +o\ *0-30*/*p* Enable specific optimisation
158 ~o\ *0-30*/*p* Disable specific optimisation
160 `0: Absolute long adddresses to word`
162 `1: move.l #x,Dn/An to moveq`
164 `2: Word branches to short`
166 `3: Outer displacement 0(An) to (An)`
170 `5: 68020+ Absolute long base/outer displacement to word`
172 `6: Convert null short branches to NOP`
174 `7: Convert clr.l Dn to moveq #0,Dn`
176 `8: Convert adda.w/l #x,Dy to addq.w/l #x,Dy`
178 `9: Convert adda.w/l #x,Dy to lea x(Dy),Dy`
180 `10: 56001 Use short format for immediate values if possible`
182 `11: 56001 Auto convert short addressing mode to long (default: on)`
184 `30: Enforce PC relative (alternative name: op)`
186 -p Produce an executable (**.prg**) output file.
187 -ps Produce an executable (**.prg**) output file with symbols.
188 -px Produce an executable (**.prg**) output file with extended symbols.
189 -q Make RMAC resident in memory (Atari ST only).
190 -r *size* automatically pad the size of each
191 segment in the output file until the size is an integral multiple of the
192 specified boundary. Size is a letter that specifies the desired boundary.
194 `-rw Word (2 bytes, default alignment)`
198 `-rp Phrase (8 bytes)`
200 `-rd Double Phrase (16 bytes)`
202 `-rq Quad Phrase (32 bytes)`
203 -s Warn about unoptimized long branches and applied optimisations.
204 -u Force referenced and undefined symbols global.
205 -v Verbose mode (print running dialogue).
206 -x Turn on debugging mode.
207 -yn Set listing page size to n lines.
208 -4 Use C style operator precedence.
209 file\ *[s]* Assemble the specified file.
210 =================== ===========
212 The switches are described below. A summary of all the switches is given in
216 The **-d** switch permits symbols to be defined on the command line. The name
217 of the symbol to be defined immediately follows the switch (no spaces). The
218 symbol name may optionally be followed by an equals sign (=) and a decimal
219 number. If no value is specified the symbol's value is zero. The symbol at-
220 tributes are "defined, not referenced, and absolute". This switch is most useful
221 for enabling conditionally-assembled debugging code on the command line; for
226 -dDEBUG -dLoopCount=999 -dDebugLevel=55
229 The -e switch causes RMAC to send error messages to a file, instead of the
230 console. If a filename immediately follows the switch character, error messages
231 are written to the specified file. If no filename is specified, a file is created with
232 the default extension "**.err**" and with the root name taken from the first input
233 file name (e.g. error messages are written to "**file.err**" if "**file**" or "**file.s**" is
234 the first input file name). If no errors are encountered, then no error listing
235 file is created. Beware! If an assembly produces no errors, any error file from
236 a previous assembly is not removed.
239 The **-g** switch causes RMAC to generate source-level debug symbols using the
240 stabs format. When linked with a compatible linker such as RLN, these symbols
241 can be used by source-level debuggers such as rdbjag, wdb, or gdb to step
242 through assembly code line-by-line with all the additional context of labels,
243 macros, constants, register equates, etc. available in the original assembly
244 listings rather than relying on the simple disassembly or raw machine code
245 available when stepping through instruction-by-instruction. This option only
246 works with the BSD COFF object file format, as the others do not use the
247 a.out-style symbol tables required by stabs, and RMAC does not currently
248 support placing stabs debug symbols in their own dedicated section in ELF
252 The **-i** switch allows automatic directory searching for include files. A list of
253 semi-colon seperated directory search paths may be mentioned immediately
254 following the switch (with no spaces anywhere). For example:
258 -im:;c:include;c:include\sys
260 will cause the assembler to search the current directory of device **M**, and the
261 directories include and include\sys on drive **C**. If *-i* is not specified, and the
262 enviroment variable "**RMACPATH**" exists, its value is used in the same manner.
263 For example, users of the Mark Williams shell could put the following line in
264 their profile script to achieve the same result as the **-i** example above:
268 setenv RMACPATH="m:;c:include;c:include\sys"
270 The -l switch causes RMAC to generate an assembly listing file. If a file-
271 name immediately follows the switch character, the listing is written to the
272 specified file. If no filename is specified, then a listing file is created with the
273 default extension "**.prn**" and with the root name taken from the first input file
274 name (e.g. the listing is written to "**file.prn**" if "**file**" or "**file.s**" is the first
277 The -o switch causes RMAC to write object code on the specified file. No
278 default extension is applied to the filename. For historical reasons the filename
279 can also be seperated from the switch with a space (e.g. "**-o file**").
284 The **-p** and **-ps** switches cause RMAC to produce an Atari ST executable
285 file with the default extension of "**.prg**". If there are any external references
286 at the end of the assembly, an error message is emitted and no executable file
287 is generated. The **-p** switch does not write symbols to the executable file. The
288 **-ps** switch includes symbols (Alcyon format) in the executable file.
290 The **-q** switch is aimed primarily at users of floppy-disk-only systems. It causes
291 RMAC to install itself in memory, like a RAMdisk. Then the program
292 **m.prg** (which is very short - less than a sector) can be used instead of
293 **mac.prg**, which can take ten or twelve seconds to load. (**NOTE** not available
294 for now, might be re-implemented in the future).
296 The **-s** switch causes RMAC to generate a list of unoptimized forward
297 branches as warning messages. This is used to point out branches that could
298 have been short (e.g. "bra" could be "bra.s").
300 The **-u** switch takes effect at the end of the assembly. It forces all referenced
301 and undefined symbols to be global, exactly as if they had been made global
302 with a **.extern** or **.globl** directive. This can be used if you have a lot of
303 external symbols, and you don't feel like declaring them all external.
305 The **-v** switch turns on a "verbose" mode in which RMAC prints out (for
306 example) the names of the files it is currently processing. Verbose mode is
307 automatically entered when RMAC prompts for input with a star.
309 The **-y** switch, followed immediately by a decimal number (with no intervening
310 space), sets the number of lines in a page. RMAC will produce *N* lines
311 before emitting a form-feed. If *N* is missing or less than 10 an error message is
314 Use C style order of precedence in expressions. See `Order of Evaluation`_ for more
320 Let's assemble and link some example programs. These programs are included
321 on the distribution disk in the "**EXAMPLES**" directory - you should copy them to
322 your work area before continuing. In the following examples we adopt the conven-
323 tions that the shell prompt is a percent sign (%) and that your input (the stuff you
324 type) is presented in **bold face**.
326 If you have been reading carefully, you know that RMAC can generate
327 an executable file without linking. This is useful for making small, stand alone
328 programs that don't require externals or library routines. For example, the following
336 could be replaced by the single command:
342 since you don't need the linker for stand-alone object files.
344 Successive source files named in the command line are are concatenated, as in
345 this example, which assembles three files into a single executable, as if they were
350 % rmac -p bugs shift images
352 Of course you can get the same effect by using the **.include** directive, but sometimes
353 it is convenient to do the concatenation from the command line.
355 Here we have an unbelievably complex command line:
359 % rmac -lzorf -y95 -o tmp -ehack -Ddebug=123 -ps example
361 This produces a listing on the file called "**zorf.prn**" with 95 lines per page, writes
362 the executable code (with symbols) to a file called "**tmp.prg**", writes an error listing
363 to the file "**hack.err**", specifies an include-file path that includes the current
364 directory on the drive "**M:**," defines the symbol "**debug**" to have the value 123, and
365 assembles the file "**example.s**". (Take a deep breath - you got all that?)
367 One last thing. If there are any assembly errors, RMAC will terminate
368 with an exit code of 1. If the assembly succeeds (no errors, although there may be
369 warnings) the exit code will be 0. This is primarily for use with "make" utilities.
371 Things You Should Be Aware Of
372 '''''''''''''''''''''''''''''
373 RMAC is a one pass assembler. This means that it gets all of its work done by
374 reading each source file exactly once and then "back-patching" to fix up forward
375 references. This one-pass nature is usually transparent to the programmer, with
376 the following important exceptions:
378 * In listings, the object code for forward references is not shown. Instead, lower-
379 case "xx"s are displayed for each undefined byte, as in the following example:
383 60xx 1: bra.s.2 ;forward branch
384 xxxxxxxx dc.l .2 ;forward reference
385 60FE .2: bra.s.2 ;backward reference
387 * Forward branches (including **BSR**\s) are never optimized to their short forms.
388 To get a short forward branch it is necessary to explicitly use the ".s" suffix in
390 * Error messages may appear at the end of the assembly, referring to earlier source
391 lines that contained undefined symbols.
392 * All object code generated must fit in memory. Running out of memory is a
393 fatal error that you must deal with by splitting up your source files, re-sizing
394 or eliminating memory-using programs such as ramdisks and desk accessories,
399 RMAC does not optimize forward branches for you, but it will tell you about
400 them if you use the -s (short branch) option:
405 "example.s", line 20: warning: unoptimized short branch
407 With the -e option you can redirect the error output to a file, and determine by
408 hand (or editor macros) which forward branches are safe to explicitly declare short.
410 `Notes for migrating from other 68000 assemblers`_
411 ''''''''''''''''''''''''''''''''''''''''''''''''''
412 RMAC is not entirely compatible with the other popular assemblers
413 like Devpac or vasm. This section
414 outlines the major differences. In practice, we have found that very few changes are
415 necessary to make other assemblers' source code assemble.
417 * A semicolon (;) must be used to introduce a comment,
418 except that a star (*)
419 may be used in the first column. AS68 treated anything following the operand
420 field, preceeded by whitespace, as a comment. (RMAC treats a star that
421 is not in column 1 as a multiplication operator).
422 * Labels require colons (even labels that begin in column 1).
424 * Conditional assembly directives are called **if**, **else** and **endif**.
425 Devpac and vasm call these
426 **ifne**, **ifeq** (etc.), and **endc**.
427 * The tilde (~) character is an operator, and back-quote (`) is an illegal character.
428 AS68 permitted the tilde and back-quote characters in symbols.
429 * There are no equivalents to org or section directives apart from .text, .data, .bss.
430 The **.xdef** and **.xref** directives are not implemented,
431 but **.globl** makes these unnecessary anyway.
433 * The location counter cannot be manipulated with a statement of the form:
439 Exceptions to this rule are when outputting a binary using the **-fr** switch,
440 6502 mode, and Jaguar GPU/DSP.
441 * Back-slashes in strings are "electric" characters that are used to escape C-like
442 character codes. Watch out for GEMDOS path names in ASCII constants -
443 you will have to convert them to double-backslashes.
444 * Expression evaluation is done left-to-right without operator precedence. Use parentheses to
445 force the expression evaluation as you wish. Alternatively, use the **-4** switch to switch
446 to C style precedence. For more information refer to `Order of Evaluation`_.
447 * Mark your segments across files.
448 Branching to a code segment that could be identified as BSS will cause a "Error: cannot initialize non-storage (BSS) section"
449 * In 68020+ mode **Zan** and **Zri** (register suppression) is not supported.
450 * rs.b/rs.w/rs.l/rscount/rsreset can be simulated in rmac using **.abs**.
451 For example the following source:
461 size_so_far equ rscount
473 size_so_far equ ^^abscount
474 * A rare case: if your macro contains something like:
484 then by the assembler's design this will fail as the parameters are automatically converted to hex. Changing the code like this works:
496 For those using editors other than the "Emacs" style ones (Micro-Emacs, Mince,
497 etc.) this section documents the source file format that RMAC expects.
499 * Files must contain characters with ASCII values less than 128; it is not per-
500 missable to have characters with their high bits set unless those characters are
501 contained in strings (i.e. between single or double quotes) or in comments.
503 * Lines of text are terminated with carriage-return/line-feed, linefeed alone, or
504 carriage-return alone.
506 * The file is assumed to end with the last terminated line. If there is text beyond
507 the last line terminator (e.g. control-Z) it is ignored.
514 A statement may contain up to four fields which are identified by order of ap-
515 pearance and terminating characters. The general form of an assembler statement
520 label: operator operand(s) ; comment
522 The label and comment fields are optional. An operand field may not appear
523 without an operator field. Operands are seperated with commas. Blank lines are
524 legal. If the first character on a line is an asterisk (*) or semicolon (;) then the
525 entire line is a comment. A semicolon anywhere on the line (except in a string)
526 begins a comment field which extends to the end of the line.
528 The label, if it appears, must be terminated with a single or double colon. If
529 it is terminated with a double colon it is automatically declared global. It is illegal
530 to declare a confined symbol global (see: `Symbols and Scope`_).
532 As an addition, the exclamation mark character (**!**) can be placed at the very first
533 character of a line to disbale all optimisations for that specific line, i.e.
537 !label: operator operand(s) ; comment
541 A statement may also take one of these special forms:
543 *symbol* **equ** *expression*
545 *symbol* **=** *expression*
547 *symbol* **==** *expression*
549 *symbol* **set** *expression*
551 *symbol* **reg** *register list*
553 The first two forms are identical; they equate the symbol to the value of an
554 expression, which must be defined (no forward references). The third form, double-
555 equals (==), is just like an equate except that it also makes the symbol global. (As
556 with labels, it is illegal to make a confined equate global.) The fourth form allows
557 a symbol to be set to a value any number of times, like a variable. The last form
558 equates the symbol to a 16-bit register mask specified by a register list. It is possible
559 to equate confined symbols (see: `Symbols and Scope`_). For example:
563 cr equ 13 carriage-return
565 DEBUG == 1 global debug flag
567 count set count + 1 increment variable
568 .rags reg d3-d7/a3-a6 register list
569 .cr 13 confined equate
573 Symbols may start with an uppercase or lowercase letter (A-Z a-z), an underscore
574 (**_**), a question mark (**?**) or a period (**.**). Each remaining character may be an
575 upper or lowercase letter, a digit (**0-9**), an underscore, a dollar sign (**$**), or a question
576 mark. (Periods can only begin a symbol, they cannot appear as a symbol
577 continuation character). Symbols are terminated with a character that is not a
578 symbol continuation character (e.g. a period or comma, whitespace, etc.). Case is
579 significant for user-defined symbols, but not for 68000 mnemonics, assembler direc-
580 tives and register names. Symbols are limited to 100 characters. When symbols
581 are written to the object file they are silently truncated to eight (or sixteen) char-
582 acters (depending on the object file format) with no check for (or warnings about)
585 For example, all of the following symbols are legal and unique:
589 reallyLongSymbolName .reallyLongConfinedSymbolName
590 a10 ret move dc frog aa6 a9 ????
591 .a1 .ret .move .dc .frog .a9 .9 ????
592 .0 .00 .000 .1 .11. .111 . ._
593 _frog ?zippo? sys$syetem atari Atari ATARI aTaRi
595 while all of the following symbols are illegal:
599 12days dc.10 dc.z 'quote .right.here
600 @work hi.there $money$ ~tilde
603 Symbols beginning with a period (**.**) are *confined*; their scope is between two
604 normal (unconfined) labels. Confined symbols may be labels or equates. It is illegal
605 to make a confined symbol global (with the ".globl" directive, a double colon, or a
606 double equals). Only unconfined labels delimit a confined symbol's scope; equates
607 (of any kind) do not count. For example, all symbols are unique and have unique
608 values in the following:
619 .loop: move.w -1,(a0)+
623 Confined symbols are useful since the programmer has to be much less inventive
624 about finding small, unique names that also have meaning.
626 It is legal to define symbols that have the same names as processor mnemonics
627 (such as "**move**" or "**rts**") or assembler directives (such as "**.even**"). Indeed, one
628 should be careful to avoid typographical errors, such as this classic (in 6502 mode):
636 which equates a confined symbol to a hexadecimal value, rather than setting the
637 location counter, which the .org directive does (without the equals sign).
641 The following names, in all combinations of uppercase and lowercase, are keywords
642 and may not be used as symbols (e.g. labels, equates, or the names of macros):
650 d0 d1 d2 d3 d4 d5 d6 d7
651 a0 a1 a2 a3 a4 a5 a6 a7
653 r0 r1 r2 r3 r4 r5 r6 r7
654 r8 r9 r10 r11 r12 r13 r14 r15
658 x x0 x1 x2 y y0 y1 y2
659 a a0 a1 a2 b b0 b1 b2 ab ba
660 mr omr la lc ssh ssl ss
661 n0 n1 n2 n3 n4 n5 n6 n7
662 m0 m1 m2 m3 m4 m5 m6 m7
663 r0 r1 r2 r3 r4 r5 r6 r7
668 Numbers may be decimal, hexadecimal, octal, binary or concatenated ASCII. The
669 default radix is decimal, and it may not be changed. Decimal numbers are specified
670 with a string of digits (**0-9**). Hexadecimal numbers are specified with a leading
671 dollar sign (**$**) followed by a string of digits and uppercase or lowercase letters (**A-F
672 a-f**). Octal numbers are specified with a leading at-sign (**@**) followed by a string
673 of octal digits (**0-7**). Binary numbers are specified with a leading percent sign
674 (**%**) followed by a string of binary digits (**0-1**). Concatenated ASCII constants are
675 specified by enclosing from one to four characters in single or double quotes. For
687 Negative numbers Are specified with a unary minus (**-**). For example:
696 Strings are contained between double (") or single ( ') quote marks. Strings may
697 contain non-printable characters by specifying "backslash" escapes, similar to the
698 ones used in the C programming language. RMAC will generate a warning if a
699 backslash is followed by a character not appearing below:
704 \n $0a line-feed (newline)
707 \r $0c1 carriage-return
713 It is possible for strings (but not symbols) to contain characters with their high
714 bits set (i.e. character codes 128...255).
716 You should be aware that backslash characters are popular in GEMDOS path
717 names, and that you may have to escape backslash characters in your existing source
718 code. For example, to get the file "'c:\\auto\\ahdi.s'" you would specify the string
719 "`c:\\\\auto\\\\ahdi.s`".
723 Register lists are special forms used with the **movem** mnemonic and the **.reg**
724 directive. They are 16-bit values, with bits 0 through 15 corresponding to registers
725 **D0** through **A7**. A register list consists of a series of register names or register
726 ranges seperated by slashes. A register range consists of two register names, Rm
727 and Rn,m<n, seperated by a dash. For example:
735 d0/d1/a0-a3/d7/a6-a7 $CF83
739 Register lists and register equates may be used in conjunction with the movem
740 mnemonic, as in this example:
744 temps reg d0-d2/a0-a2 ; temp registers
745 keeps reg d3-d7/d3-a6 ; registers to preserve
746 allregs reg d0-d7/a0-a7 ; all registers
747 movem.l #temps,-(sp) ; these two lines ...
748 movem.l d0-d2/a0-a2,-(sp) ; are identical
749 movem.l #keeps,-(sp) ; save "keep" registers
750 movem.l (sp)+,#keeps ; restore "keep" registers
755 `Order of Evaluation`_
756 ''''''''''''''''''''''
757 All values are computed with 32-bit 2's complement arithmetic. For boolean operations
758 (such as if or **assert**) zero is considered false, and non-zero is considered
761 **Expressions are evaluated strictly left-to-right, with no
762 regard for operator precedence.**
764 Thus the expression "1+2*3" evaluates to 9, not 7. However, precedence may be
765 forced with parenthesis (**()**) or square-brackets (**[]**).
767 All the above behavior is the default. However if the command line switch **-4**
768 is used, then C style of operator precedence is enforced. The following list
769 shows the order of precedence in this mode, from lowest to highest:
777 * relational = < <= >= > !=
787 Expressions belong to one of three classes: undefined, absolute or relocatable. An
788 expression is undefined if it involves an undefined symbol (e.g. an undeclared sym-
789 bol, or a forward reference). An expression is absolute if its value will not change
790 when the program is relocated (for instance, the number 0, all labels declared in
791 an abs section, and all Atari ST hardware register locations are absolute values).
792 An expression is relocatable if it involves exactly one symbol that is contained in a
793 text, data or BSS section.
795 Only absolute values may be used with operators other than addition (+) or
796 subtraction (-). It is illegal, for instance, to multiply or divide by a relocatable or
797 undefined value. Subtracting a relocatable value from another relocatable value in
798 the same section results in an absolute value (the distance between them, positive
799 or negative). Adding (or subtracting) an absolute value to or from a relocatable
800 value yeilds a relocatable value (an offset from the relocatable address).
802 It is important to realize that relocatable values belong to the sections they
803 are defined in (e.g. text, data or BSS), and it is not permissible to mix and match
804 sections. For example, in this code:
808 linel: dc.l line2, line1+8
809 line2: dc.l line1, line2-8
810 line3: dc.l line2-line1, 8
811 error: dc.l line1+line2, line2 >> 1, line3/4
813 Line 1 deposits two longwords that point to line 2. Line 2 deposits two longwords
814 that point to line 1. Line 3 deposits two longwords that have the absolute value
815 eight. The fourth line will result in an assembly error, since the expressions (re-
816 spectively) attempt to add two relocatable values, shift a relocatable value right by
817 one, and divide a relocatable value by four.
819 The pseudo-symbol "*****" (star) has the value that the current section's location
820 counter had at the beginning of the current source line. For example, these two
821 statements deposit three pointers to the label "**bar**":
828 Similarly, the pseudo-symbol "**$**" has the value that the current section's location
829 counter has, and it is kept up to date as the assembler deposits information
830 "across" a line of source code. For example, these two statements deposit four
831 pointers to the label "zip":
841 ================================ ==========================================
843 ================================ ==========================================
844 **-** Unary minus (2's complement).
845 **!** Logical (boolean) NOT.
846 **~** Tilde: bitwise not (l's complement).
847 **^^defined** *symbol* True if symbol has a value.
848 **^^referenced** *symbol* True if symbol has been referenced.
849 **^^streq** *string1*, *string2* True if the strings are equal.
850 **^^macdef** *macroName* True if the macro is defined.
851 **^^abscount** Returns the size of current .abs section
852 **^^filesize** *string_filename* Returns the file size of supplied filename
853 ================================ ==========================================
855 * The boolean operators generate the value 1 if the expression is true, and 0 if it is not.
857 * A symbol is referenced if it is involved in an expression.
859 any combination of attributes: undefined and unreferenced, defined and unref-
860 erenced (i.e. declared but never used), undefined and referenced (in the case
861 of a forward or external reference), or defined and referenced.
868 =========== ==============================================
870 =========== ==============================================
871 \ + - * / The usual arithmetic operators.
872 % Modulo. Do *not* attempt to modulo by 0 or 1.
873 & | ^ Bit-wise **AND**, **OR** and **Exclusive-OR**.
874 << >> Bit-wise shift left and shift right.
875 < <= >= > Boolean magnitude comparisons.
877 <> != Boolean inequality.
878 =========== ==============================================
880 * All binary operators have the same precedence:
881 expressions are evaluated strictly left to right,
882 with the exception of the **-4** switch. For more information
883 refer to `Order of Evaluation`_.
885 * Division or modulo by zero yields an assembly error.
887 * The "<>" and "!=" operators are synonyms.
889 * Note that the modulo operator (%) is also used to introduce binary constants
890 (see: `Constants`_). A percent sign should be followed by at least one space if
891 it is meant to be a modulo operator, and is followed by a '0' or '1'.
896 ============ =========================================
897 Special Form Description
898 ============ =========================================
899 **^^date** The current system date (Gemdos format).
900 **^^time** The current system time (Gemdos format).
901 ============ =========================================
903 * The "**^^date**" special form expands to the current system date, in Gemdos
904 format. The format is a 16-bit word with bits 0 ...4 indicating the day of the
905 month (1...31), bits 5...8 indicating the month (1...12), and bits 9...15
906 indicating the year since 1980, in the range 0...119.
908 * The "**^^time**" special form expands to the current system time, in Gemdos
909 format. The format is a 16-bit word with bits 0...4 indicating the current
910 second divided by 2, bits 5...10 indicating the current minute 0...59. and
911 bits 11...15 indicating the current hour 0...23.
913 `Example Expressions`_
914 ''''''''''''''''''''''
918 line address contents source code
919 ---- ------- -------- -------------------------------
920 1 00000000 4480 lab1: neg.l d0
921 2 00000002 427900000000 lab2: clr.w lab1
922 3 =00000064 equ1 = 100
923 4 =00000096 equ2 = equ1 + 50
924 5 00000008 00000064 dc.l lab1 + equ1
925 6 0000000C 7FFFFFE6 dc.l (equl + ~equ2) >> 1
926 7 00000010 0001 dc.w ^^defined equl
927 8 00000012 0000 dc.w ^^referenced lab2
928 9 00000014 00000002 dc.l lab2
929 10 00000018 0001 dc.w ^^referenced lab2
930 11 0000001A 0001 dc.w lab1 = (lab2 - 6)
932 Lines 1 through four here are used to set up the rest of the example. Line 5 deposits
933 a relocatable pointer to the location 100 bytes beyond the label "**lab1**". Line 6 is
934 a nonsensical expression that uses the and right-shift operators. Line 7 deposits
935 a word of 1 because the symbol "**equ1**" is defined (in line 3).
937 Line 8 deposits a word of 0 because the symbol "**lab2**", defined in line 2, has
938 not been referenced. But the expression in line 9 references the symbol "**lab2**", so
939 line 10 (which is a copy of line-8) deposits a word of 1. Finally, line 11 deposits a
940 word of 1 because the Boolean equality operator evaluates to true.
942 The operators "**^^defined**" and "**^^referenced**" are particularly useful in
943 conditional assembly. For instance, it is possible to automatically include debugging
944 code if the debugging code is referenced, as in:
948 lea string,a0 ; AO -> message
949 jsr debug ; print a message
951 string: dc.b "Help me, Spock!",0 ; (the message)
955 .iif ^^referenced debug, .include "debug.s"
957 The **jsr** statement references the symbol debug. Near the end of the source file, the
958 "**.iif**" statement includes the file "**debug.s**" if the symbol debug was referenced.
960 In production code, presumably all references to the debug symbol will be removed,
961 and the debug source file will not be included. (We could have as easily made the
962 symbol **debug** external, instead of including another source file).
968 Assembler directives may be any mix of upper- or lowercase. The leading periods
969 are optional, though they are shown here and their use is encouraged. Directives
970 may be preceeded by a label; the label is defined before the directive is executed.
971 Some directives accept size suffixes (**.b**, **.s**, **.w**, **.1**, **.d**, **.x**, **.p**, or **.q**);
972 the default is word (**.w**) if no size is specified. The **.s** suffix is identical to **.b**,
973 with the exception of being used in a **dc** statement. In that case the **.s**
974 refers to single precision floating point numbers.
975 Directives relating to the 6502 are described in the chapter on `6502 Support`_.
981 If the location counter for the current section is odd, make it even by adding
982 one to it. In text and data sections a zero byte is deposited if necessary.
986 Align the program counter to the next integral long boundary (4 bytes).
987 Note that GPU/DSP code sections are not contained in their own
988 segments and are actually part of the TEXT or DATA segments.
989 Therefore, to align GPU/DSP code, align the current section before and
990 after the GPU/DSP code.
993 This directive is similar to the standard ‘C’ library printf() function
994 and is used to print user messages from the assembly process. You can
995 print any string or valid expression. Several format flags that can be used
996 to format your output are also supported.
1012 .print “Mask: $”,/x/w MASK
1013 .print “Value: “,/d/l VALUE
1017 Align the program counter to the next integral phrase boundary (8 bytes).
1018 Note that GPU/DSP code sections are not contained in their own
1019 segments and are actually part of the TEXT or DATA segments.
1020 Therefore, to align GPU/DSP code, align the current section before and
1021 after the GPU/DSP code.
1025 Align the program counter to the next integral double phrase boundary (16
1026 bytes). Note that GPU/DSP code sections are not contained in their own
1027 segments and are actually part of the TEXT or DATA segments.
1028 Therefore, to align GPU/DSP code, align the current section before and
1029 after the GPU/DSP code.
1033 Align the program counter to the next integral quad phrase boundary (32
1034 bytes). Note that GPU/DSP code sections are not contained in their own
1035 segments and are actually part of the TEXT or DATA segments.
1036 Therefore, to align GPU/DSP code, align the current section before and
1037 after the GPU/DSP code.
1039 **.align** *expression*
1041 A generalised version of the above directives, this will align the program
1042 counter to the boundary of the specified value. Note that there is not much
1043 error checking happening (only values 0 and 1 are rejected). Also note that
1044 in DSP56001 mode the align value is assumed to be in DSP words, i.e. 24 bits.
1046 **.assert** *expression* [,\ *expression*...]
1048 Assert that the conditions are true (non-zero). If any of the comma-seperated
1049 expressions evaluates to zero an assembler warning is issued. For example:
1053 .assert *-start = $76
1054 .assert stacksize >= $400
1062 Switch to the BSS, data or text segments. Instructions and data may not
1063 be assembled into the BSS-segment, but symbols may be defined and storage
1064 may be reserved with the **.ds** directive. Each assembly starts out in the text
1073 Enable different flavours of the MC68000 family of CPUs. Bear in mind that not all
1074 instructions and addressing modes are available in all CPUs so the correct CPU
1075 should be selected at all times. Notice that it is possible to switch CPUs
1081 Enable FPU support. Note that *.68882* is on by default when selecting *.68030*.
1085 Switch to Motorola DSP56001 mode.
1087 **.org** *location* [*X:*/*Y:*/*P:*/*L:*]
1089 This directive sets the value of the location counter (or **pc**) to location, an
1090 expression that must be defined and absolute. It is legal to use the directive in
1091 the following modes: 6502, Tom, Jerry, OP, 56001 and 680x0 (only with -fr switch).
1092 Especially for the 56001 mode the *location* field **must** be prefixed with the
1093 intended section (*X:*, *Y:*, *P:* or *L:*).
1100 These directives control the optimisations that rmac applies to the source
1101 automatically. Each directive is applied immediately from the line encountered
1102 onwards. So it is possible to turn specific optimisations on and off globally
1103 (when placed at the start of the first file) or locally (by turning desired
1104 optimisations on and off at certain parts of the source). For a list of the
1105 optimisations (*n*) available please consult the table in section `The Command Line`_.
1107 **all**, as expected, turns all available optimisations on or off. An exception to this
1108 is *o10*/*op* as this is not an optimisation that should be turned on unless the user
1109 absolutely needs it.
1111 Lastly, as a "creature comfort" feature, if the first column of any line is prefixed
1112 with an exclamation mark (*!*) then for that line all optimisations are turned off.
1114 **.abs** [*location*]
1116 Start an absolute section, beginning with the specified location (or zero, if
1117 no location is specified). An absolute section is much like BSS, except that
1118 locations declared with .ds are based absolute. This directive is useful for
1119 declaring structures or hardware locations.
1120 For example, the following equates:
1130 could be as easily defined as:
1141 Another interesting example worth mentioning is the emulation of "C"'s "union" keyword
1142 using *.abs*. For example, the following "C" code:
1152 union { int spf_em_colour; int spf_emx_colour; };
1153 union { int spf_em_psmask[16]; int spf_emx_colouropt; };
1156 can be expressed as:
1161 *-------------------------------------------------------*
1162 spf_w: ds.w 1 ;<- common
1167 *-------------------------------------------------------*
1169 spf_em_colour: ds.l 1 ;<- union #1
1170 spf_em_psmask: ds.l 16
1171 *-------------------------------------------------------*
1175 spf_emx_colour: ds.l 1 ;<- union #2
1176 spf_emx_colouropt: ds.l 1
1177 spf_emx_psmask: ds.l 16
1178 spf_emx_psmaskopt: ds.l 16
1181 ;*-------------------------------------------------------*
1183 move #spf_em_colour,d0
1184 move #spf_emx_colour,d0
1186 In this example, *spf_em_colour* and *spf_emx_colour* will have the same value.
1188 **.comm** *symbol*, *expression*
1190 Specifies a label and the size of a common region. The label is made global,
1191 thus confined symbols cannot be made common. The linker groups all common
1192 regions of the same name; the largest size determines the real size of the
1193 common region when the file is linked.
1195 **.ccdef** *expression*
1197 Allows you to define names for the condition codes used by the JUMP
1198 and JR instructions for GPU and DSP code. For example:
1204 jump Always,(r3) ; 'Always' is actually 0
1206 **.ccundef** *regname*
1208 Undefines a register name (regname) previously assigned using the
1209 .CCDEF directive. This is only implemented in GPU and DSP code
1212 **.dc.i** *expression*
1214 This directive generates long data values and is similar to the DC.L
1215 directive, except the high and low words are swapped. This is provided
1216 for use with the GPU/DSP MOVEI instruction.
1218 **.dc**\ [.\ *size*] *expression* [, *expression*...]
1220 Deposit initialized storage in the current section. If the specified size is word
1221 or long, the assembler will execute a .even before depositing data. If the size
1222 is .b, then strings that are not part of arithmetic expressions are deposited
1223 byte-by-byte. If no size is specified, the default is .w. This directive cannot be
1224 used in the BSS section.
1226 **.dcb**\ [.\ *size*] *expression1*, *expression2*
1228 Generate an initialized block of *expression1* bytes, words or longwords of the
1229 value *expression2*. If the specified size is word or long, the assembler will
1230 execute .even before generating data. If no size is specified, the default is **.w**.
1231 This directive cannot be used in the BSS section.
1233 **.ds**\ [.\ *size*] *expression*
1235 Reserve space in the current segment for the appropriate number of bytes,
1236 words or longwords. If no size is specified, the default size is .w. If the size
1237 is word or long, the assembler will execute .even before reserving space.
1241 Switch to Jaguar DSP assembly mode. This directive must be used
1242 within the TEXT or DATA segments.
1244 **.init**\ [.\ *size*] [#\ *expression*,]\ *expression*\ [.\ *size*] [,...]
1246 Generalized initialization directive. The size specified on the directive becomes
1247 the default size for the rest of the line. (The "default" default size is **.w**.) A
1248 comma-seperated list of expressions follows the directive; an expression may be
1249 followed by a size to override the default size. An expression may be preceeded
1250 by a sharp sign, an expression and a comma, which specifies a repeat count to
1251 be applied to the next expression. For example:
1255 .init.l -1, 0.w, #16,'z'.b, #3,0, 11.b
1257 will deposit a longword of -1, a word of zero, sixteen bytes of lower-case 'z',
1258 three longwords of zero, and a byte of 11.
1260 No auto-alignment is performed within the line, but a **.even** is done once
1261 (before the first value is deposited) if the default size is word or long.
1263 **.cargs** [#\ *expression*,] *symbol*\ [.\ *size*] [, *symbol*\ [.\ *size*].. .]
1265 Compute stack offsets to C (and other language) arguments. Each symbol is
1266 assigned an absolute value (like equ) which starts at expression and increases
1267 by the size of each symbol, for each symbol. If the expression is not supplied,
1268 the default starting value is 4. For example:
1272 .cargs #8, .fileliams.1, .openMode, .butPointer.l
1274 could be used to declare offsets from A6 to a pointer to a filename, a word
1275 containing an open mode, and a pointer to a buffer. (Note that the symbols
1276 used here are confined). Another example, a C-style "string-length" function,
1277 could be written as:
1281 _strlen:: .cargs .string ; declare arg
1282 move.l .string(sp),a0 ; a0 -> string
1283 moveq #-1,d0 ; initial size = -1
1284 .1: addq.1 #1,d0 ; bump size
1285 tst.b (a0)+ ; at end of string?
1286 bne .1 ; (no -- try again)
1287 rts ; return string length
1289 **.error** ["*string*"]
1291 Aborts the build, optionally printing a user defined string. Can be useful
1292 inside conditional assembly blocks in order to catch errors. For example:
1296 .if ^^defined JAGUAR
1297 .error "TOS cannot be built on Jaguar, don't be silly"
1302 End the assembly. In an include file, end the include file and resume assembling
1303 the superior file. This statement is not required, nor are warning messages
1304 generated if it is missing at the end of a file. This directive may be used inside
1305 conditional assembly, macros or **.rept** blocks.
1307 **.equr** *expression*
1309 Allows you to name a register. For example:
1316 add ClipW,r0 ; ClipW actually is r19
1318 **.if** *expression*
1324 Start a block of conditional assembly. If the expression is true (non-zero) then
1325 assemble the statements between the .if and the matching **.endif** or **.else**.
1326 If the expression is false, ignore the statements unless a matching .else is
1327 encountered. Conditional assembly may be nested to any depth.
1329 It is possible to exit a conditional assembly block early from within an include
1330 file (with **end**) or a macro (with **endm**).
1332 **.iif** *expression*, *statement*
1334 Immediate version of **.if**. If the expression is true (non-zero) then the state-
1335 ment, which may be an instruction, a directive or a macro, is executed. If
1336 the expression is false, the statement is ignored. No **.endif** is required. For
1341 .iif age < 21, canDrink = 0
1342 .iif weight > 500, dangerFlag = 1
1343 .iif !(^^defined DEBUG), .include dbsrc
1345 **.macro** *name* [*formal*, *formal*,...]
1351 Define a macro called name with the specified formal arguments. The macro
1352 definition is terminated with a **.endm** statement. A macro may be exited early
1353 with the .exitm directive. See the chapter on `Macros`_ for more information.
1355 **.undefmac** *macroName* [, *macroName*...]
1357 Remove the macro-definition for the specified macro names. If reference is
1358 made to a macro that is not defined, no error message is printed and the name
1361 **.rept** *expression*
1365 The statements between the **.rept** and **.endr** directives will be repeated *expression*
1366 times. If the expression is zero or negative, no statements will be
1367 assembled. No label may appear on a line containing either of these directives.
1369 **.globl** *symbol* [, *symbol*...]
1371 **.extern** *symbol* [, *symbol*...]
1373 Each symbol is made global. None of the symbols may be confined symbols
1374 (those starting with a period). If the symbol is defined in the assembly, the
1375 symbol is exported in the object file. If the symbol is undefined at the end
1376 of the assembly, and it was referenced (i.e. used in an expression), then the
1377 symbol value is imported as an external reference that must be resolved by the
1378 linker. The **.extern** directive is merely a synonym for **.globl**.
1380 **.include** "*file*"
1382 Include a file. If the filename is not enclosed in quotes, then a default extension
1383 of "**.s**" is applied to it. If the filename is quoted, then the name is not changed
1386 Note: If the filename is not a valid symbol, then the assembler will generate an
1387 error message. You should enclose filenames such as "**atari.s**" in quotes,
1388 because such names are not symbols.
1390 If the include file cannot be found in the current directory, then the directory
1391 search path, as specified by -i on the commandline, or' by the 'RMACPATH'
1392 enviroment string, is traversed.
1394 **.incbin** "*file*" [, [*size*], [*offset*]]
1396 Include a file as a binary. This can be thought of a series of **dc.b** statements
1397 that match the binary bytes of the included file, inserted at the location of the
1398 directive. The directive is not allowed in a BSS section. Optional parameters
1399 control the amount of bytes to be included and offset from the start of the file.
1400 All the following lines are valid:
1403 .incbin "test.bin" ; Include the whole file
1404 .incbin "test.bin",,$30 ; Skip the first 48 bytes
1405 .incbin "test.bin",$70,$30 ; Include $70 bytes starting at offset $30
1406 .incbin "test.bin",$48 ; Include the file starting at offset 48 till the end
1407 .incbin "test.bin",, ; Include the whole file
1411 Issue a page eject in the listing file.
1413 **.title** "*string*"
1415 **.subttl** [-] "*string*"
1417 Set the title or subtitle on the listing page. The title should be specified on
1418 the the first line of the source program in order to take effect on the first page.
1419 The second and subsequent uses of **.title** will cause page ejects. The second
1420 and subsequent uses of .subttl will cause page ejects unless the subtitle string
1421 is preceeded by a dash (-).
1427 Enable or disable source code listing. These directives increment and decrement
1428 an internal counter, so they may be appropriately nested. They have no effect
1429 if the **-l** switch is not specified on the commandline.
1433 This directive provides unstructured flow of control within a macro definition.
1434 It will transfer control to the line of the macro containing the specified goto
1435 label. A goto label is a symbol preceeded by a colon that appears in the first
1436 column of a source line within a macro definition:
1440 where the label itself can be any valid symbol name, followed immediately by
1441 whitespace and a valid source line (or end of line). The colon **must** appear in
1444 The goto-label is removed from the source line prior to macro expansion -
1445 to all intents and purposes the label is invisible except to the .goto directive
1446 Macro expansion does not take place within the label.
1448 For example, here is a silly way to count from 1 to 10 without using **.rept**:
1456 iif count <= 10, goto loop
1461 Switch to Jaguar GPU assembly mode. This directive must be used
1462 within the TEXT or DATA segments.
1466 No. Just... no. Don't ask about it. Ever.
1468 **.prgflags** *value*
1470 Sets ST executable .PRG field *PRGFLAGS* to *value*. *PRGFLAGS* is a bit field defined as follows:
1472 ============ ====== =======
1473 Definition Bit(s) Meaning
1474 ============ ====== =======
1475 PF_FASTLOAD 0 If set, clear only the BSS area on program load, otherwise clear the entire heap.
1476 PF_TTRAMLOAD 1 If set, the program may be loaded into alternative RAM, otherwise it must be loaded into standard RAM.
1477 PF_TTRAMMEM 2 If set, the program's Malloc() requests may be satisfied from alternative RAM, otherwise they must be satisfied from standard RAM.
1478 -- 3 Currently unused.
1479 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.
1480 -- 6-15 Currently unused.
1481 ============ ====== =======
1483 **.regequ** *expression*
1484 Essentially the same as **.EQUR.** Included for compatibility with the GASM
1488 Essentially the same as **.EQURUNDEF.** Included for compatibility with
1497 All of the standard Motorola 68000 mnemonics and addressing modes are supported;
1498 you should refer to **The Motorola M68000 Programmer's Reference Manual**
1499 for a description of the instruction set and the allowable addressing modes for each
1500 instruction. With one major exception (forward branches) the assembler performs
1501 all the reasonable optimizations of instructions to their short or address register
1504 Register names may be in upper or lower case. The alternate forms ``R0`` through
1505 ``R15`` may be used to specify ``D0`` through ``A7``. All register names are keywords, and
1506 may not be used as labels or symbols. None of the 68010 or 68020 register names
1507 are keywords (but they may become keywords in the future).
1512 ===================================== ===========================================
1513 Assembler Syntax Description
1514 ===================================== ===========================================
1515 *Dn* Data register direct
1516 *An* Address register direct
1517 (*An*) Address register indirect
1518 (*An*)+ Address register indirect postincrement
1519 -(*An*) Address register indirect predecrement
1520 *disp*\ (*An*) Address register indirect with displacement
1521 *bdisp*\ (*An*, *Xi*\ [.\ *size*]) Address register indirect indexed
1522 *abs*.w Absolute short
1523 *abs* Absolute (long or short)
1524 *abs*.l Forced absolute long
1525 *disp*\ (PC) Program counter with displacement
1526 *bdisp*\ (PC, *Xi*\ ) Program counter indexed
1528 ===================================== ===========================================
1530 `68020+ Addressing Modes`_
1531 ''''''''''''''''''''''''''
1533 The following addressing modes are only valid for 68020 and newer CPUs. In these
1534 modes most of the parameters like Base Displacement (**bd**), Outer Displacement
1535 (**od**), Base Register (**An**) and Index Register (**Xn**) can be omitted. RMAC
1536 will detect this and *suppress* the registers in the produced code.
1539 use a special syntax to denote register suppression like **Zan** to suppress the Base
1540 Register and **Rin** to suppress the Index Register. RMAC has no support for this
1541 behaviour nor needs it to suppress registers.
1543 In addition, other assemblers will allow reordering of the parameters (for example
1544 ([*An*,\ *bd*])). This is not allowed in RMAC.
1546 Also noteworthy is that the Index Register can be an address or data register.
1548 To avoid internal confusion the 68040/68060 registers *DC*, *IC* and *BC* are named
1549 *DC40*, *IC40* and *BC40* respectively.
1551 ====================================================== =============================================================
1552 Assembler Syntax Description
1553 ====================================================== =============================================================
1554 *bd*\ (*An*, *Xi*\ [.\ *size*][*\*scale*]) Address register indirect indexed
1555 ([*bd*,\ *An*],\ *Xn*\[.\ *siz*][*\*scale*],\ *od*) Register indirect preindexed with outer displacement
1556 ([*bd*,\ *An*,\ *Xn*\[.\ *siz*][*\*scale*],\ *od*) Register indirect postindexed with outer displacement
1557 ([*bd*,\ *PC*],\ *Xn*\[.\ *siz*][*\*scale*],\ *od*) Program counter indirect preindexed with outer displacement
1558 ([*bd*,\ *PC*,\ *Xn*\[.\ *siz*][*\*scale*],\ *od*) Program counter indirect postindexed with outer displacement
1559 ====================================================== =============================================================
1563 Since RMAC is a one pass assembler, forward branches cannot be automatically
1564 optimized to their short form. Instead, unsized forward branches are assumed to
1565 be long. Backward branches are always optimized to the short form if possible.
1567 A table that lists "extra" branch mnemonics (common synonyms for the Motorola
1568 defined mnemonics) appears below.
1570 `Linker Constraints`_
1571 '''''''''''''''''''''
1572 It is not possible to make an external reference that will fix up a byte. For example:
1577 move.l frog(pc,d0),d1
1579 is illegal (and generates an assembly error) when frog is external, because the
1580 displacement occupies a byte field in the 68000 offset word, which the object file
1585 ============== ========
1586 Alternate name Becomes:
1587 ============== ========
1597 ============== ========
1599 `Optimizations and Translations`_
1600 '''''''''''''''''''''''''''''''''
1601 The assembler provides "creature comforts" when it processes 68000 mnemonics:
1603 * **CLR.x An** will really generate **SUB.x An,An**.
1605 * **ADD**, **SUB** and **CMP** with an address register will really generate **ADDA**,
1606 **SUBA** and **CMPA**.
1608 * The **ADD**, **AND**, **CMP**, **EOR**, **OR** and **SUB** mnemonics with immediate
1609 first operands will generate the "I" forms of their instructions (**ADDI**, etc.) if
1610 the second operand is not register direct.
1612 * All shift instructions with no count value assume a count of one.
1614 * **MOVE.L** is optimized to **MOVEQ** if the immediate operand is defined and
1615 in the range -128...127. However, **ADD** and **SUB** are never translated to
1616 their quick forms; **ADDQ** and **SUBQ** must be explicit.
1618 * All optimisations are controllable using the **.opt** directive. Refer to its
1619 description in section `Directives`_.
1621 * All optimisations are turned off for any source line that has an exclamation mark
1622 (*!*) on their first column.
1624 * Optimisation switch 11 is turned on by default for compatibility with the
1625 Motorola reference 56001 DSP assembler.
1626 All other levels are off by default. (refer to section `The Command Line`_
1627 for a description of all the switches).
1629 * Optimisation warnings are off by default. Invoke RMAC with the *-s* switch to
1630 turn on warnings in console and listing output.
1632 * In GPU/DSP code sections, you can use JUMP (Rx) in place of JUMP T, (Rx) and JR
1633 (Rx) in place of JR T,(Rx).
1635 * RMAC tests all GPU/DSP restrictions and corrects them wherever possible (such as
1636 inserting a NOP instruction when needed).
1638 * The *(Rx+N)* addressing mode for GPU/DSP instructions is optimized to *(Rx)*
1643 `Macro declaration`_
1644 ''''''''''''''''''''
1645 A macro definition is a series of statements of the form:
1648 .macro name [ formal-arg, ...]
1652 statements making up the macro body
1658 The name of the macro may be any valid symbol that is not also a 68000 instruction
1659 or an assembler directive. (The name may begin with a period - macros cannot
1660 be made confined the way labels or equated symbols can be). The formal argument
1661 list is optional; it is specified with a comma-seperated list of valid symbol names.
1662 Note that there is no comma between the name of the macro and the name of the
1663 first formal argument. It is not advised to begin an argument name with a numeric
1666 A macro body begins on the line after the **.macro** directive. All instructions
1667 and directives, except other macro definitions, are legal inside the body.
1669 The macro ends with the **.endm** statement. If a label appears on the line with
1670 this directive, the label is ignored and a warning is generated.
1672 `Parameter Substitution`_
1673 '''''''''''''''''''''''''
1674 Within the body, formal parameters may be expanded with the special forms:
1680 The second form (enclosed in braces) can be used in situations where the characters
1681 following the formal parameter name are valid symbol continuation characters. This
1682 is usually used to force concatentation, as in:
1687 \(godzilla}vs\{reagan}
1689 The formal parameter name is terminated with a character that is not valid in
1690 a symbol (e.g. whitespace or puncuation); optionally, the name may be enclosed in
1691 curly-braces. The names must be symbols appearing on the formal argument list,
1692 or a single decimal digit (``\1`` corresponds to the first argument, ``\2`` to the second,
1693 ``\9`` to the ninth, and ``\0`` to the tenth). It is possible for a macro to have more than
1694 ten formal arguments, but arguments 11 and on must be referenced by name, not
1697 Other special forms are:
1699 ============ ================================================
1700 Special Form Description
1701 ============ ================================================
1702 ``\\`` a single "\",
1703 ``\~`` a unique label of the form "Mn"
1704 ``\#`` the number of arguments actually specified
1705 ``\!`` the "dot-size" specified on the macro invocation
1706 ``\?name`` conditional expansion
1707 ``\?{name}`` conditional expansion
1708 ============ ================================================
1710 The last two forms are identical: if the argument is specified and is non-empty, the
1711 form expands to a "1", otherwise (if the argument is missing or empty) the form
1714 The form "``\!``" expands to the "dot-size" that was specified when the macro
1715 was invoked. This can be used to write macros that behave differently depending
1716 on the size suffix they are given, as in this macro which provides a synonym for the
1721 .macro deposit value
1724 deposit.b 1 ; byte of 1
1725 deposit.w 2 ; word of 2
1726 deposit.l 3 ; longvord of 3
1727 deposit 4 ; word of 4 (no explicit size)
1731 A previously-defined macro is called when its name appears in the operation field of
1732 a statement. Arguments may be specified following the macro name; each argument
1733 is seperated by a comma. Arguments may be empty. Arguments are stored for
1734 substitution in the macro body in the following manner:
1736 * Numbers are converted to hexadecimal.
1738 * All spaces outside strings are removed.
1740 * Keywords (such as register names, dot sizes and "^^" operators) are converted
1743 * Strings are enclosed in double-quote marks (").
1745 For example, a hypothetical call to the macro "``mymacro``", of the form:
1746 ``mymacro A0, , 'Zorch' / 32, "^^DEFINED foo, , , tick tock``
1748 will result in the translations:
1750 ======== ================= =================================================
1751 Argument Expansion Comment
1752 ======== ================= =================================================
1753 ``\1`` ``a0`` "``A0``" converted to lower-case
1755 ``\3`` ``"Zorch"/$20`` "``Zorch``" in double-quotes, 32 in hexadecimal
1756 ``\4`` ``^^defined foo`` "``^^DEFINED``" converted to lower-case
1759 ``\7`` ``ticktock`` spaces removed (note concatenation)
1760 ======== ================= =================================================
1762 The **.exitm** directive will cause an immediate exit from a macro body. Thus
1763 the macro definition:
1768 .iif !\?source, .exitm ; exit if source is empty
1769 move \source,d0 ; otherwise, deposit source
1772 will not generate the move instruction if the argument **"source"** is missing from
1773 the macro invocation.
1775 The **.end**, **.endif** and **.exitm** directives all pop-out of their include levels
1776 appropriately. That is, if a macro performs a **.include** to include a source file, an
1777 executed **.exitm** directive within the include-file will pop out of both the include-file
1780 Macros may be recursive or mutually recursive to any level, subject only to
1781 the availability of memory. When writing recursive macros, take care in the coding
1782 of the termination condition(s). A macro that repeatedly calls itself will cause the
1783 assembler to exhaust its memory and abort the assembly.
1788 The Gemdos macro is used to make file system calls. It has two parameters, a
1789 function number and the number of bytes to clean off the stack after the call. The
1790 macro pushes the function number onto the stack and does the trap to the file
1791 system. After the trap returns, conditional assembly is used to choose an addq or
1792 an **add.w** to remove the arguments that were pushed.
1796 .macro Gemdos trpno, clean
1797 move.w #\trpno,-(sp) ; push trap number
1798 trap #1 ; do GEMDOS trap
1800 addq #\clean,sp ; clean-up up to 8 bytes
1802 add.w #\clean,sp ; clean-up more than 8 bytes
1806 The Fopen macro is supplied two arguments; the address of a filename, and
1807 the open mode. Note that plain move instructions are used, and that the caller of
1808 the macro must supply an appropriate addressing mode (e.g. immediate) for each
1813 .macro Fopen file, mode
1814 movs.w \mode,-(sp) ;push open mode
1815 move.1 \file,-(sp) ;push address of tile name
1816 Gemdos $3d,8 ;do the GEMDOS call
1819 The **String** macro is used to allocate storage for a string, and to place the
1820 string's address somewhere. The first argument should be a string or other expres-
1821 sion acceptable in a dc.b directive. The second argument is optional; it specifies
1822 where the address of the string should be placed. If the second argument is omitted,
1823 the string's address is pushed onto the stack. The string data itself is kept in the
1828 .macro String str,loc
1829 .if \?loc ; if loc is defined
1830 move.l #.\~,\loc ; put the string's address there
1832 pea .\~ ; push the string's address
1834 .data ; put the string data
1835 .\~: dc.b \str,0 ; in the data segment
1836 .text ; and switch back to the text segment
1839 The construction "``.\~``" will expand to a label of the form "``.M``\ *n*" (where *n* is
1840 a unique number for every macro invocation), which is used to tag the location of
1841 the string. The label should be confined because the macro may be used along with
1842 other confined symbols.
1844 Unique symbol generation plays an important part in the art of writing fine
1845 macros. For instance, if we needed three unique symbols, we might write "``.a\~``",
1846 "``.b\~``" and "``.c\~``".
1850 Repeat-blocks provide a simple iteration capability. A repeat block allows a range
1851 of statements to be repeated a specified number of times. For instance, to generate
1852 a table consisting of the numbers 255 through 0 (counting backwards) you could
1857 .count set 255 ; initialize counter
1858 .rept 256 ; repeat 256 times:
1859 dc.b .count ; deposit counter
1860 .count set .count - 1 ; and decrement it
1861 .endr ; (end of repeat block)
1863 Repeat blocks can also be used to duplicate identical pieces of code (which are
1864 common in bitmap-graphics routines). For example:
1868 .rept 16 ; clear 16 words
1869 clr.w (a0)+ ; starting at AO
1872 `Jaguar GPU/DSP Mode`_
1873 ======================
1875 RMAC will generate code for the Atari Jaguar GPU and DSP custom RISC (Reduced
1876 Instruction Set Computer) processors. See the Atari Jaguar Software reference Manual - Tom
1877 & Jerry for a complete listing of Jaguar GPU and DSP assembler mnemonics and addressing
1882 The following condition codes for the GPU/DSP JUMP and JR instructions are built-in:
1886 CC (Carry Clear) = %00100
1887 CS (Carry Set) = %01000
1890 NE (Not Equal) = %00001
1892 HI (Higher) = %00101
1895 `Jaguar Object Processor Mode`_
1896 ===============================
1901 An assembler to generate object lists for the Atari Jaguar's Object processor.
1907 To really utilize the OP properly, it needs an assembler. Otherwise, what
1908 happens is you end up writing an assembler in your code to assemble the OP
1909 list, and that's a real drag--something that *should* be handled by a proper
1914 ''''''''''''''''''''
1916 The OP assembler works similarly to the RISC assembler; to enter the OP
1917 assembler, you put the .objproc directive in your code (N.B.: like the RISC
1918 assembler, it only works in a TEXT or DATA section). From there, you build
1919 the OP list how you want it and go from there. A few caveats: you will want
1920 to put a .org directive at the top of your list, and labels that you want to
1921 be able to address in 68xxx code (for moving from a data section to an
1922 address where it will be executed by the OP, for example) should be created
1926 `What are the opcodes?`_
1927 ''''''''''''''''''''''''
1929 They are **bitmap**, **scbitmap**, **gpuobj**, **branch**, **stop**, **nop**, and **jump**. **nop** and **jump**
1930 are psuedo-ops, they are there as a convenience to the coder.
1933 `What are the proper forms for these opcodes?`_
1934 '''''''''''''''''''''''''''''''''''''''''''''''
1936 They are as follows:
1938 **bitmap** *data addr*, *xloc*, *yloc*, *dwidth*, *iwidth*, *iheight*, *bpp*,
1939 *pallete idx*, *flags*, *firstpix*, *pitch*
1941 **scbitmap** *data addr*, *xloc*, *yloc*, *dwidth*, *iwidth*, *iheight*,
1942 *xscale*, *yscale*, *remainder*, *bpp*, *pallete idx*,
1943 *flags*, *firstpix*, *pitch*
1945 **gpuobj** *line #*, *userdata* (bits 14-63 of this object)
1947 **branch** VC *condition (<, =, >)* *line #*, *link addr*
1949 **branch** OPFLAG, *link addr*
1951 **branch** SECHALF, *link addr*
1957 **jump** *link addr*
1959 Note that the *flags* field in bitmap and scbitmap objects consist of the
1960 following: **REFLECT**, **RMW**, **TRANS**, **RELEASE**. They can be in any order (and
1961 should be separated by whitespace **only**), and you can only put a maximum of
1962 four of them in. Further note that with bitmap and scbitmap objects, all the
1963 parameters after *data addr* are optional--if they are omitted, they will
1964 use defaults (mostly 0, but 1 is the default for pitch). Also, in the
1965 scbitmap object, the *xscale*, *yscale*, and *remainder* fields can be
1966 floating point constants/expressions. *data addr* can refer to any address
1967 defined (even external!) and the linker (rln v1.6.0 or greater) will
1968 properly fix up the address.
1974 Pretty much what you expect. It's beyond the scope of this little note to
1975 explain the Jaguar's Object Processor and how it operates, so you'll have to
1976 seek explanations for how they work elsewhere.
1979 `Why do I want to put a *.org* directive at the top of my list?`_
1980 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
1982 You want to put a *.org* directive at the top of your list because otherwise
1983 the assembler will not know where in memory the object list is supposed
1984 go--then when you move it to its destination, the object link addresses will
1985 all be wrong and it won't work.
1988 `Why would I copy my object list to another memory location?`_
1989 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
1991 Simple: because the OP destroys the list as it uses it to render the screen.
1992 If you don't keep a fresh copy stashed away somewhere to refresh it before
1993 the next frame is rendered, what you see on the screen will not be what you
1994 expect, as the OP has scribbled all over it!
1997 `Does the assembler do anything behind my back?`_
1998 '''''''''''''''''''''''''''''''''''''''''''''''''
2000 Yes, it will emit **NOP** s to ensure that bitmaps and scbitmaps are on proper
2001 memory boundaries, and fixup link addresses as necessary. This is needed
2002 because of a quirk in how the OP works (it ORs constants on the address
2003 lines to get the phrases it needs and if they are not zeroes, it will fail
2004 in bizarre ways). It will also set all *ypos* constants on the correct
2005 half-line (as that's how the OP views them).
2008 `Why can't I define the link addresses for all the objects?`_
2009 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
2011 You really, *really* don't want to do this. Trust me on this one.
2013 `How about an example of an object list?`_
2014 ''''''''''''''''''''''''''''''''''''''''''
2022 objects: ; This is the label you will use to address this in 68K code
2023 .objproc ; Engage the OP assembler
2024 .org objList ; Tell the OP assembler where the list will execute
2026 branch VC < 69, .stahp ; Branch to the STOP object if VC < 69
2027 branch VC > 241, .stahp ; Branch to the STOP object if VC > 241
2028 bitmap bRAM, 22, 70, 24, 24, 22, 4
2029 bitmap bRAM, 20+96+96, 70, 24, 24, 22, 4, 0, REFLECT
2030 scbitmap tms, 20, 70, 1, 1, 8, 3.0, 3.0, 2.9999, 0, 0, TRANS
2031 scbitmap tmsShadow, 23, 73, 1, 1, 8, 3.0, 3.0, 2.9999, 0, 3, TRANS
2032 bitmap sbRelBM, 30, 108, 3, 3, 8, 0, 1, TRANS
2033 bitmap txt1BM, 46, 132, 3, 3, 8, 0, 2, TRANS
2034 bitmap txt2BM, 46, 148, 3, 3, 8, 0, 2, TRANS
2035 bitmap txt3BM, 22, 164, 3, 3, 8, 0, 2, TRANS
2046 RMAC fully supports Motorola's DSP56001 as used on the Atari Falcon and can output
2047 binary code in the two most popular formats: *.lod* (ASCII dump, supported by the
2048 Atari Falcon XBIOS) and *.p56* (binary equivalent of *.lod*)
2050 `Differences from Motorola's assembler`_
2051 ''''''''''''''''''''''''''''''''''''''''
2053 - Motorola's assembler aliases **and #xxx,reg** with **andi #xxx,reg** and can
2054 distinguish between the two. rmac needs the user to be explicit and will
2055 generate an error if the programmer tries to use syntax from one instruction
2057 - Similarly Motorola's assembler can alias **move** with **movec**, **movep**
2058 and **movem**. rmac also not accept such aliasing and generate an error.
2059 - Motorola's assembler uses the underscore character (*_*) to define local
2060 labels. In order for rmac to maintain a uniform syntax across all platforms,
2061 such labels will not be treated as local.
2062 - Macros syntax is different from Motorola's assembler. This includes local
2063 labels inside macros. The user is encouraged to study the `Macros`_ section
2064 and compare syntactical differences.
2065 - Motorola's assembler allows reordering of addressing modes **x:**, **x:r**,
2066 **r:y**, **x:y**. rmac will only accept syntax as is defined on the reference
2068 - In **L:** section a dc value cannot be 12 hex digits like Motorola's assmebler.
2069 Instead, the value needs to be split into two parts separated by **:**.
2073 RMAC will generate code for the MOS 6502 microprocessor. This chapter
2074 describes extra addressing modes and directives used to support the 6502.
2076 As the 6502 object code is not linkable (currently there is no linker) external
2077 references may not be made. (Nevertheless, RMAC may reasonably be used for
2078 large assemblies because of its blinding speed.)
2080 Currently there is no support for undocumented opcodes. This will be addressed
2081 in a future release.
2083 `6502 Addressing Modes`_
2084 ''''''''''''''''''''''''
2085 All standard 6502 addressing modes are supported, with the exception of the
2086 accumulator addressing form, which must be omitted (e.g. "ror a" becomes "ror").
2087 Five extra modes, synonyms for existing ones, are included for compatibility with
2088 the Atari Coinop assembler.
2090 ============== ========================================
2091 *empty* implied or accumulator (e.g. tsx or ror)
2092 *expr* absolute or zeropage
2094 #<\ *expr* immediate low byte of a word
2095 #>\ *expr* immediate high byte of a word
2096 (*expr*,x) indirect X
2097 (*expr*),y indirect Y
2101 @\ *expr*\ (x) indirect X
2102 @\ *expr*\ (y) indirect Y
2104 x,\ *expr* indexed X
2105 y,\ *expr* indexed Y
2106 ============== ========================================
2111 This directive enters the 6502 section. The location counter is undefined, and
2112 must be set with ".org" before any code can be generated.
2114 The "``dc.w``" directive will produce 6502-format words (low byte first). The
2115 68000's reserved keywords (``d0-d7/a0-a7/ssp/usp`` and so on) remain reserved
2116 (and thus unusable) while in the 6502 section. The directives **globl**, **dc.l**,
2117 **dcb.l**, **text**, **data**, **bss**, **abs**, **even** and **comm** are illegal in the 6502 section.
2118 It is permitted, though probably not useful, to generate both 6502 and 68000
2119 code in the same object file.
2121 This directive leaves the 6502 segment and returns to the 68000's text segment.
2122 68000 instructions may be assembled as normal.
2124 This directive sets the value of the location
2125 counter (or **pc**) to location, an expression that must be defined, absolute, and
2130 It is possible to assemble "beyond" the microprocessor's 64K address space, but
2131 attempting to do so will probably screw up the assembler. DO NOT attempt
2132 to generate code like this:
2141 the third NOP in this example, at location $10000, may cause the assembler
2142 to crash or exhibit spectacular schizophrenia. In any case, RMAC will give
2143 no warning before flaking out.
2145 `6502 Object Code Format`_
2146 ''''''''''''''''''''''''''
2147 Traditionally Madmac had a very kludgy way of storing object files. This has been
2148 replaced with a more standard *.exe* (or *.com* or *.xex* if you prefer). Briefly,
2149 the *.exe* format consists of chunks of this format (one after the other):
2154 00-01 $FFFF - Indicates a binary load file. Mandatory for first segment, optional for any other segment
2155 02-03 Start Address. The segment will load at this address
2156 04-05 End Address. The last byte to load for this segment
2157 06-.. The actual segment data to load (End Address-Start Address + 1 bytes)
2159 In addition there is the standard output format for Commodore 64 binaries (.PRG).
2164 `When Things Go Wrong`_
2165 '''''''''''''''''''''''
2166 Most of RMAC's error messages are self-explanatory. They fall into four classes:
2167 warnings about situations that you (or the assembler) may not be happy about,
2168 errors that cause the assembler to not generate object files, fatal errors that cause
2169 the assembler to abort immediately, and internal errors that should never happen.\ [3]_
2171 You can write editor macros (or sed or awk scripts) to parse the error messages
2172 RMAC generates. When a message is printed, it is of the form:
2174 "*filename*" , ``line`` *line-number*: *message*
2176 The first element, a filename enclosed in double quotes, indicates the file that generated
2177 the error. The filename is followed by a comma, the word "``line``", and a line
2178 number, and finally a colon and the text of the message. The filename "**(\*top\*)**"
2179 indicates that the assembler could not determine which file had the problem.
2181 The following sections list warnings, errors and fatal errors in alphabetical
2182 order, along with a short description of what may have caused the problem.
2184 .. [3] If you come across an internal error, we would appreciate it if you would contact the rmac development team and let us know about the problem.
2188 **bad backslash code in string**
2189 You tried to follow a backslash in a string with a character that the assembler
2190 didn't recognize. Remember that RMAC uses a C-style escape system in
2193 You specified a label before a macro, **rept** or **endm** directive. The assembler
2194 is warning you that the label will not be defined in the assembly.
2195 **unoptimized short branch**
2196 This warning is only generated if the -s switch is specified on the command
2197 line. The message refers to a forward, unsized long branch that you could have
2204 As a result of previous errors, the assembler cannot continue processing. The
2205 assembly is aborted.
2206 **line too long as a result of macro expansion**
2207 When a source line within a macro was expanded, the resultant line was too
2208 long for RMAC (longer than 200 characters or so).
2211 **memory exhausted**
2212 The assembler ran out of memory. You should (1) split up your source files
2213 and assemble them seperately, or (2) if you have any ramdisks or RAM-resident
2214 programs (like desk accessories) decrease their size so that the assembler has
2215 more RAM to work with. As a rule of thumb, pure 68000 code will use up to
2216 twice the number of bytes contained in the source files, whereas 6502 code will
2217 use 64K of ram right away, plus the size of the source files. The assembler itself
2218 uses about 80K bytes. Get out your calculator...
2220 The assembler ran across an **endm** directive when it wasn't expecting to see
2221 one. The assembly is aborted. Check the nesting of your macro definitions -
2222 you probably have an extra **endm**.
2230 Syntax error in **.cargs** directive.
2232 **.comm symbol already defined**
2234 You tried to ``.comm`` a symbol that was already defined.
2236 **.init not permitted in BSS or ABS**
2238 You tried to use ``.init`` in the BSS or ABS section.
2240 **Cannot create:** *filename*
2242 The assembler could not create the indicated filename.
2244 **External quick reference**
2246 You tried to make the immediate operand of a **moveq**, **subq** or **addq** instruction external.
2248 **PC-relative expr across sections**
2250 You tried to make a PC-relative reference to a location contained in another
2253 **[bwsl] must follow '.' in symbol**
2255 You tried to follow a dot in a symbol name with something other than one of
2256 the four characters 'B', 'W', 'S' or 'L'.
2258 **addressing mode syntax**
2260 You made a syntax error in an addressing mode.
2264 One of your **.assert** directives failed!
2266 **bad (section) expression**
2268 You tried to mix and match sections in an expression.
2270 **bad 6502 addressing mode**
2272 The 6502 mnemonic will not work with the addressing mode you specified.
2276 There's a syntax error in the expression you typed.
2278 **bad size specified**
2280 You tried to use an inappropriate size suffix for the instruction. Check your
2281 68000 manual for allowable sizes.
2285 You can't use .b (byte) mode with the **movem** instruction.
2287 **cannot .globl local symbol**
2289 You tried to make a confined symbol global or common.
2291 **cannot initialize non-storage (BSS) section**
2293 You tried to generate instructions (or data, with dc) in the BSS or ABS section.
2295 **cannot use '.b' with an address register**
2297 You tried to use a byte-size suffix with an address register. The 68000 does not
2298 perform byte-sized address register operations.
2300 **directive illegal in .6502 section**
2302 You tried to use a 68000-oriented directive in the 6502 section.
2306 The expression you typed involves a division by zero.
2308 **expression out of range**
2310 The expression you typed is out of range for its application.
2312 **external byte reference**
2314 You tried to make a byte-sized reference to an external symbol, which the
2315 object file format will not allow.
2317 **external short branch**
2319 You tried to make a short branch to an external symbol, which the linker cannot
2322 **extra (unexpected) text found after addressing mode**
2324 RMAC thought it was done processing a line, but it ran up against "extra"
2325 stuff. Be sure that any comment on the line begins with a semicolon, and check
2326 for dangling commas, etc.
2328 **forward or undefined .assert**
2330 The expression you typed after a **.assert** directive had an undefined value.
2331 Remember that RMAC is one-pass.
2333 **hit EOF without finding matching .endif**
2335 The assembler fell off the end of last input file without finding a **.endif** to
2336 match an . it. You probably forgot a **.endif** somewhere.
2338 **illegal 6502 addressing mode**
2340 The 6502 instruction you typed doesn't work with the addressing mode you
2343 **illegal absolute expression**
2345 You can't use an absolute-valued expression here.
2347 **illegal bra.s with zero offset**
2349 You can't do a short branch to the very next instruction (read your 68000
2352 **illegal byte-sized relative reference**
2354 The object file format does not permit bytes contain relocatable values; you
2355 tried to use a byte-sized relocatable expression in an immediate addressing
2358 **illegal character**
2360 Your source file contains a character that RMAC doesn't allow. (most
2361 control characters fall into this category).
2363 **illegal initialization of section**
2365 You tried to use .dc or .dcb in the BSS or ABS sections.
2367 **illegal relative address**
2369 The relative address you specified is illegal because it belongs to a different
2372 **illegal word relocatable (in .PRG mode)**
2374 You can't have anything other than long relocatable values when you're gener-
2375 ating a **.PRG** file.
2377 **inappropriate addressing mode**
2379 The mnemonic you typed doesn't work with the addressing modes you specified.
2380 Check your 68000 manual for allowable combinations.
2382 **invalid addressing mode**
2384 The combination of addressing modes you picked for the **movem** instruction
2385 are not implemented by the 68000. Check your 68000 reference manual for
2388 **invalid symbol following ^^**
2390 What followed the ^^ wasn't a valid symbol at all.
2392 **mis-nested .endr**
2394 The assembler found a **.endr** directive when it wasn't prepared to find one.
2395 Check your repeat-block nesting.
2397 **mismatched .else**
2399 The assembler found a **.else** directive when it wasn't prepared to find one.
2400 Check your conditional assembly nesting.
2402 **mismatched .endif**
2404 The assembler found a **.endif** directive when it wasn't prepared to find one.
2405 Check your conditional assembly nesting.
2411 **missing argument name**
2413 **missing close parenthesis ')'**
2415 **missing close parenthesis ']'**
2419 **missing filename**
2425 **missing symbol or string**
2427 The assembler expected to see a symbol/filename/string (etc...), but found
2428 something else instead. In most cases the problem should be obvious.
2430 **misuse of '.', not allowed in symbols**
2432 You tried to use a dot (.) in the middle of a symbol name.
2436 The expression you typed involves a modulo by zero.
2438 **multiple formal argument definition**
2440 The list of formal parameter names you supplied for a macro definition includes
2441 two identical names.
2443 **multiple macro definition**
2445 You tried to define a macro which already had a definition.
2447 **non-absolute byte reference**
2449 You tried to make a byte reference to a relocatable value, which the object file
2450 format does not allow.
2452 **non-absolute byte value**
2454 You tried to dc.b or dcb.b a relocatable value. Byte relocatable values are
2455 not permitted by the object file format.
2457 **register list order**
2459 You tried to specify a register list like **D7-D0**, which is illegal. Remember
2460 that the first register number must be less than or equal to the second register
2463 **register list syntax**
2465 You made an error in specifying a register list for a **.reg** directive or a **.movem**
2468 **symbol list syntax**
2470 You probably forgot a comma between the names of two symbols in a symbol
2471 list, or you left a comma dangling on the end of the line.
2475 This is a "catch-all" error.
2477 **undefined expression**
2479 The expression has an undefined value because of a forward reference, or an
2480 undefined or external symbol.
2482 **unimplemented directive**
2484 You have found a directive that didn't appear in the documentation. It doesn't
2487 **unimplemented mnemonic**
2491 **unknown symbol following ^^**
2493 You followed a ^^ with something other than one of the names defined, referenced
2496 **unterminated string**
2498 You specified a string starting with a single or double quote, but forgot to type
2503 The assembler had a problem writing an object file. This is usually caused by
2504 a full disk, or a bad sector on the media.