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.*
20 *Copyright © 2011-2017, Reboot*
22 *All rights reserved.*
24 *Reboot Document number F00000K-001 Rev. A.*
36 This document describes RMAC, a fast macro assembler for the 68000. RMAC currently
37 runs on the any POSIX compatible platform and the Atari ST. It was initially written
38 at Atari Corporation by programmers who needed a high performance assembler
39 for their work. Then, more than 20 years later, because there was still a need for
40 such an assembler and what was available wasn't up to expectations, Subqmod
41 and eventually Reboot continued work on the freely released source, adding Jaguar extensions
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!
62 =>Write protect your distribution disk and make a backup of it now. Put the
63 original disk in a safe place.
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.
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.
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).
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
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.
92 The assembler is called "**rmac**" or "**rmac.prg**". The command line takes the form:
94 **rmac** [*switches*] [*files* ...]
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.
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.
106 If the command line is entirely empty then RMAC prints a copyright message
107 along with usage info and exit.
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.
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.
118 =================== ===========
120 =================== ===========
121 -dname\ *[=value]* Define symbol, with optional value.
122 -e\ *[file[.err]]* Direct error messages to the specified file.
123 -fa ALCYON output object file format (implied with **-ps** is enabled).
124 -fb BSD COFF output object file format.
125 -fe ELF output object file format.
126 -fx Atari 800 com/exe/xex output object file format.
127 -i\ *path* Set include-file directory search path.
128 -l\ *[file[prn]]* Construct and direct assembly listing to the specified file.
129 -l\ *\*[filename]* Create an output listing file without pagination
130 -o\ *file[.o]* Direct object code output to the specified file.
131 +/~oall Turn all optimisations on/off
132 +o\ *0-3* Enable specific optimisation
133 ~o\ *0-3* Disable specific optimisation
135 `0: Absolute long adddresses to word`
137 `1: move.l #x,dn/an to moveq`
139 `2: Word branches to short
141 `3: Outer displacement 0(an) to (an)`
142 -p Produce an executable (**.prg**) output file.
143 -ps Produce an executable (**.prg**) output file with symbols.
144 -q Make RMAC resident in memory (Atari ST only).
145 -r *size* automatically pad the size of each
146 segment in the output file until the size is an integral multiple of the
147 specified boundary. Size is a letter that specifies the desired boundary.
149 `-rw Word (2 bytes, default alignment)`
153 `-rp Phrase (8 bytes)`
155 `-rd Double Phrase (16 bytes)`
157 `-rq Quad Phrase (32 bytes)`
158 -s Warn about unoptimized long branches and applied optimisations.
159 -u Force referenced and undefined symbols global.
160 -v Verbose mode (print running dialogue).
161 -x Turn on debugging mode
162 -yn Set listing page size to n lines.
163 file\ *[s]* Assemble the specified file.
164 =================== ===========
166 The switches are described below. A summary of all the switches is given in
170 The **-d** switch permits symbols to be defined on the command line. The name
171 of the symbol to be defined immediately follows the switch (no spaces). The
172 symbol name may optionally be followed by an equals sign (=) and a decimal
173 number. If no value is specified the symbol's value is zero. The symbol at-
174 tributes are "defined, not referenced, and absolute". This switch is most useful
175 for enabling conditionally-assembled debugging code on the command line; for
180 -dDEBUG -dLoopCount=999 -dDebugLevel=55
183 The -e switch causes RMAC to send error messages to a file, instead of the
184 console. If a filename immediately follows the switch character, error messages
185 are written to the specified file. If no filename is specified, a file is created with
186 the default extension "**.err**" and with the root name taken from the first input
187 file name (e.g. error messages are written to "**file.err**" if "**file**" or "**file.s**" is
188 the first input file name). If no errors are encountered, then no error listing
189 file is created. Beware! If an assembly produces no errors, any error file from
190 a previous assembly is not removed.
193 The **-i** switch allows automatic directory searching for include files. A list of
194 semi-colon seperated directory search paths may be mentioned immediately
195 following the switch (with no spaces anywhere). For example:
199 -im:;c:include;c:include\sys
201 will cause the assembler to search the current directory of device **M**, and the
202 directories include and include\sys on drive **C**. If *-i* is not specified, and the
203 enviroment variable "**RMACPATH**" exists, its value is used in the same manner.
204 For example, users of the Mark Williams shell could put the following line in
205 their profile script to achieve the same result as the **-i** example above:
209 setenv RMACPATH="m:;c:include;c:include\sys"
211 The -l switch causes RMAC to generate an assembly listing file. If a file-
212 name immediately follows the switch character, the listing is written to the
213 specified file. If no filename is specified, then a listing file is created with the
214 default extension "**.prn**" and with the root name taken from the first input file
215 name (e.g. the listing is written to "**file.prn**" if "**file**" or "**file.s**" is the first
218 The -o switch causes RMAC to write object code on the specified file. No
219 default extension is applied to the filename. For historical reasons the filename
220 can also be seperated from the switch with a space (e.g. "**-o file**").
225 The **-p** and **-ps** switches cause RMAC to produce an Atari ST executable
226 file with the default extension of "**.prg**". If there are any external references
227 at the end of the assembly, an error message is emitted and no executable file
228 is generated. The **-p** switch does not write symbols to the executable file. The
229 **-ps** switch includes symbols (Alcyon format) in the executable file.
231 The **-q** switch is aimed primarily at users of floppy-disk-only systems. It causes
232 RMAC to install itself in memory, like a RAMdisk. Then the program
233 **m.prg** (which is very short - less than a sector) can be used instead of
234 **mac.prg**, which can take ten or twelve seconds to load. (**NOTE** not available
235 for now, might be re-implemented in the future).
237 The **-s** switch causes RMAC to generate a list of unoptimized forward
238 branches as warning messages. This is used to point out branches that could
239 have been short (e.g. "bra" could be "bra.s").
241 The **-u** switch takes effect at the end of the assembly. It forces all referenced
242 and undefined symbols to be global, exactly as if they had been made global
243 with a **.extern** or **.globl** directive. This can be used if you have a lot of
244 external symbols, and you don't feel like declaring them all external.
246 The **-v** switch turns on a "verbose" mode in which RMAC prints out (for
247 example) the names of the files it is currently processing. Verbose mode is
248 automatically entered when RMAC prompts for input with a star.
250 The **-y** switch, followed immediately by a decimal number (with no intervening
251 space), sets the number of lines in a page. RMAC will produce *N* lines
252 before emitting a form-feed. If *N* is missing or less than 10 an error message is
258 Let's assemble and link some example programs. These programs are included
259 on the distribution disk in the "**EXAMPLES**" directory - you should copy them to
260 your work area before continuing. In the following examples we adopt the conven-
261 tions that the shell prompt is a percent sign (%) and that your input (the stuff you
262 type) is presented in **bold face**.
264 If you have been reading carefully, you know that RMAC can generate
265 an executable file without linking. This is useful for making small, stand alone
266 programs that don't require externals or library routines. For example, the following
274 could be replaced by the single command:
280 since you don't need the linker for stand-alone object files.
282 Successive source files named in the command line are are concatenated, as in
283 this example, which assembles three files into a single executable, as if they were
288 % rmac -p bugs shift images
290 Of course you can get the same effect by using the **.include** directive, but sometimes
291 it is convenient to do the concatenation from the command line.
293 Here we have an unbelievably complex command line:
297 % rmac -lzorf -y95 -o tmp -ehack -Ddebug=123 -ps example
299 This produces a listing on the file called "**zorf.prn**" with 95 lines per page, writes
300 the executable code (with symbols) to a file called "**tmp.prg**", writes an error listing
301 to the file "**hack.err**", specifies an include-file path that includes the current
302 directory on the drive "**M:**," defines the symbol "**debug**" to have the value 123, and
303 assembles the file "**example.s**". (Take a deep breath - you got all that?)
305 One last thing. If there are any assembly errors, RMAC will terminate
306 with an exit code of 1. If the assembly succeeds (no errors, although there may be
307 warnings) the exit code will be 0. This is primarily for use with "make" utilities.
309 Things You Should Be Aware Of
310 '''''''''''''''''''''''''''''
311 RMAC is a one pass assembler. This means that it gets all of its work done by
312 reading each source file exactly once and then "back-patching" to fix up forward
313 references. This one-pass nature is usually transparent to the programmer, with
314 the following important exceptions:
316 o in listings, the object code for forward references is not shown. Instead, lower-
317 case "xx"s are displayed for each undefined byte, as in the following example:
321 60xx 1: bra.s.2 ;forward branch
322 xxxxxxxx dc.l .2 ;forward reference
323 60FE .2: bra.s.2 ;backward reference
325 o Forward branches (including **BSR**\s) are never optimized to their short forms.
326 To get a short forward branch it is necessary to explicitly use the ".s" suffix in
328 o Error messages may appear at the end of the assembly, referring to earlier source
329 lines that contained undefined symbols.
330 o All object code generated must fit in memory. Running out of memory is a
331 fatal error that you must deal with by splitting up your source files, re-sizing
332 or eliminating memory-using programs such as ramdisks and desk accessories,
337 RMAC does not optimize forward branches for you, but it will tell you about
338 them if you use the -s (short branch) option:
343 "example.s", line 20: warning: unoptimized short branch
345 With the -e option you can redirect the error output to a file, and determine by
346 hand (or editor macros) which forward branches are safe to explicitly declare short.
348 `Notes for migrating from other 68000 assemblers`_
349 ''''''''''''''''''''''''''''''''''''''''''''''''''
350 RMAC is not entirely compatible with the other popular assemblers
351 like Devpac or vasm. This section
352 outlines the major differences. In practice, we have found that very few changes are
353 necessary to make other assemblers' source code assemble.
355 o A semicolon (;) must be used to introduce a comment,
356 except that a star (*)
357 may be used in the first column. AS68 treated anything following the operand
358 field, preceeded by whitespace, as a comment. (RMAC treats a star that
359 is not in column 1 as a multiplication operator).
360 o Labels require colons (even labels that begin in column 1).
362 o Conditional assembly directives are called **if**, **else** and **endif**.
363 Devpac and vasm called these
364 **ifne**, **ifeq** (etc.), and **endc**.
365 o The tilde (~) character is an operator, and back-quote (`) is an illegal character.
366 AS68 permitted the tilde and back-quote characters in symbols.
367 o There are no equivalents to org or section directives.
368 The **.xdef** and **.xref** directives are not implemented,
369 but **.globl** makes these unnecessary anyway.
371 o The location counter cannot be manipulated with a statement of the form:
377 o The **ds** directive is not permitted in the text or data segments;
378 an error message is issued. Use **dcb** instead to reserve large blocks of
380 o Back-slashes in strings are "electric" characters that are used to escape C-like
381 character codes. Watch out for GEMDOS path names in ASCII constants -
382 you will have to convert them to double-backslashes.
383 o Expression evaluation is done left-to-right without operator precedence. Use parentheses to
384 force the expression evaluation as you wish.
385 o Mark your segments across files.
386 Branching to a code segment that could be identified as BSS will cause a "Error: cannot initialize non-storage (BSS) section"
387 o rs.b/rs.w/rs.l/rscount/rsreset can be simulated in rmac using abs.
388 For example the following source:
398 size_so_far equ rscount
410 size_so_far equ ^^abscount
411 o A rare case: if your macro contains something like:
421 then by the assembler's design this will fail as the parameters are automatically converted to hex. Changing the code like this works:
433 For those using editors other than the "Emacs" style ones (Micro-Emacs, Mince,
434 etc.) this section documents the source file format that RMAC expects.
436 o Files must contain characters with ASCII values less than 128; it is not per-
437 missable to have characters with their high bits set unless those characters are
438 contained in strings (i.e. between single or double quotes) or in comments.
440 o Lines of text are terminated with carriage-return/line-feed, linefeed alone, or
441 carriage-return alone.
443 o The file is assumed to end with the last terminated line. If there is text beyond
444 the last line terminator (e.g. control-Z) it is ignored.
451 A statement may contain up to four fields which are identified by order of ap-
452 pearance and terminating characters. The general form of an assembler statement
457 label: operator operand(s) ; comment
459 The label and comment fields are optional. An operand field may not appear
460 without an operator field. Operands are seperated with commas. Blank lines are
461 legal. If the first character on a line is an asterisk (*) or semicolon (;) then the
462 entire line is a comment. A semicolon anywhere on the line (except in a string)
463 begins a comment field which extends to the end of the line.
465 The label, if it appears, must be terminated with a single or double colon. If
466 it is terminated with a double colon it is automatically declared global. It is illegal
467 to declare a confined symbol global (see: `Symbols and Scope`_).
471 A statement may also take one of these special forms:
473 *symbol* **equ** *expression*
475 *symbol* **=** *expression*
477 *symbol* **==** *expression*
479 *symbol* **set** *expression*
481 *symbol* **reg** *register list*
483 The first two forms are identical; they equate the symbol to the value of an
484 expression, which must be defined (no forward references). The third form, double-
485 equals (==), is just like an equate except that it also makes the symbol global. (As
486 with labels, it is illegal to make a confined equate global.) The fourth form allows
487 a symbol to be set to a value any number of times, like a variable. The last form
488 equates the symbol to a 16-bit register mask specified by a register list. It is possible
489 to equate confined symbols (see: `Symbols and Scope`_). For example:
493 cr equ 13 carriage-return
495 DEBUG == 1 global debug flag
497 count set count + 1 increment variable
498 .rags reg d3-d7/a3-a6 register list
499 .cr 13 confined equate
503 Symbols may start with an uppercase or lowercase letter (A-Z a-z), an underscore
504 (**_**), a question mark (**?**) or a period (**.**). Each remaining character may be an
505 upper or lowercase letter, a digit (**0-9**), an underscore, a dollar sign (**$**), or a question
506 mark. (Periods can only begin a symbol, they cannot appear as a symbol
507 continuation character). Symbols are terminated with a character that is not a
508 symbol continuation character (e.g. a period or comma, whitespace, etc.). Case is
509 significant for user-defined symbols, but not for 68000 mnemonics, assembler direc-
510 tives and register names. Symbols are limited to 100 characters. When symbols
511 are written to the object file they are silently truncated to eight (or sixteen) char-
512 acters (depending on the object file format) with no check for (or warnings about)
515 For example, all of the following symbols are legal and unique:
519 reallyLongSymbolName .reallyLongConfinedSymbolName
520 a10 ret move dc frog aa6 a9 ????
521 .a1 .ret .move .dc .frog .a9 .9 ????
522 .0 .00 .000 .1 .11. .111 . ._
523 _frog ?zippo? sys$syetem atari Atari ATARI aTaRi
525 while all of the following symbols are illegal:
529 12days dc.10 dc.z 'quote .right.here
530 @work hi.there $money$ ~tilde
533 Symbols beginning with a period (**.**) are *confined*; their scope is between two
534 normal (unconfined) labels. Confined symbols may be labels or equates. It is illegal
535 to make a confined symbol global (with the ".globl" directive, a double colon, or a
536 double equals). Only unconfined labels delimit a confined symbol's scope; equates
537 (of any kind) do not count. For example, all symbols are unique and have unique
538 values in the following:
549 .loop: move.w -1,(a0)+
553 Confined symbols are useful since the programmer has to be much less inventive
554 about finding small, unique names that also have meaning.
556 It is legal to define symbols that have the same names as processor mnemonics
557 (such as "**move**" or "**rts**") or assembler directives (such as "**.even**"). Indeed, one
558 should be careful to avoid typographical errors, such as this classic (in 6502 mode):
566 which equates a confined symbol to a hexadecimal value, rather than setting the
567 location counter, which the .org directive does (without the equals sign).
571 The following names, in all combinations of uppercase and lowercase, are keywords
572 and may not be used as symbols (e.g. labels, equates, or the names of macros):
578 d0 d1 d2 d3 d4 d5 d6 d7
579 a0 a1 a2 a3 a4 a5 a6 a7
580 r0 r1 r2 r3 r4 r5 r6 r7
581 r8 r9 r10 r11 r12 rl3 r14 ri5
585 Numbers may be decimal, hexadecimal, octal, binary or concatenated ASCII. The
586 default radix is decimal, and it may not be changed. Decimal numbers are specified
587 with a string of digits (**0-9**). Hexadecimal numbers are specified with a leading
588 dollar sign (**$**) followed by a string of digits and uppercase or lowercase letters (**A-F
589 a-f**). Octal numbers are specified with a leading at-sign (**@**) followed by a string
590 of octal digits (**0-7**). Binary numbers are specified with a leading percent sign
591 (**%**) followed by a string of binary digits (**0-1**). Concatenated ASCII constants are
592 specified by enclosing from one to four characters in single or double quotes. For
604 Negative numbers Are specified with a unary minus (**-**). For example:
613 Strings are contained between double (") or single ( ') quote marks. Strings may
614 contain non-printable characters by specifying "backslash" escapes, similar to the
615 ones used in the C programming language. RMAC will generate a warning if a
616 backslash is followed by a character not appearing below:
621 \n $0a line-feed (newline)
624 \r $0c1 carriage-return
630 It is possible for strings (but not symbols) to contain characters with their high
631 bits set (i.e. character codes 128...255).
633 You should be aware that backslash characters are popular in GEMDOS path
634 names, and that you may have to escape backslash characters in your existing source
635 code. For example, to get the file "'c:\\auto\\ahdi.s'" you would specify the string
636 "`c:\\\\auto\\\\ahdi.s`".
640 Register lists are special forms used with the **movem** mnemonic and the **.reg**
641 directive. They are 16-bit values, with bits 0 through 15 corresponding to registers
642 **D0** through **A7**. A register list consists of a series of register names or register
643 ranges seperated by slashes. A register range consists of two register names, Rm
644 and Rn,m<n, seperated by a dash. For example:
652 d0/d1/a0-a3/d7/a6-a7 $CF83
656 Register lists and register equates may be used in conjunction with the movem
657 mnemonic, as in this example:
661 temps reg d0-d2/a0-a2 ; temp registers
662 keeps reg d3-d7/d3-a6 ; registers to preserve
663 allregs reg d0-d7/a0-a7 ; all registers
664 movem.l #temps,-(sp) ; these two lines ...
665 movea.l d0-d2/a0-a2,-(sp) ; are identical
666 movem.l #keeps,-(sp) ; save "keep" registers
667 movem.l (sp)+,#keeps ; restore "keep" registers
672 `Order of Evaluation`_
673 ''''''''''''''''''''''
674 All values are computed with 32-bit 2's complement arithmetic. For boolean operations
675 (such as if or **assert**) zero is considered false, and non-zero is considered
678 **Expressions are evaluated strictly left-to-right, with no
679 regard for operator precedence.**
681 Thus the expression "1+2*3" evaluates to 9, not 7. However, precedence may be
682 forced with parenthesis (**()**) or square-brackets (**[]**).
686 Expressions belong to one of three classes: undefined, absolute or relocatable. An
687 expression is undefined if it involves an undefined symbol (e.g. an undeclared sym-
688 bol, or a forward reference). An expression is absolute if its value will not change
689 when the program is relocated (for instance, the number 0, all labels declared in
690 an abs section, and all Atari ST hardware register locations are absolute values).
691 An expression is relocatable if it involves exactly one symbol that is contained in a
692 text, data or BSS section.
694 Only absolute values may be used with operators other than addition (+) or
695 subtraction (-). It is illegal, for instance, to multiply or divide by a relocatable or
696 undefined value. Subtracting a relocatable value from another relocatable value in
697 the same section results in an absolute value (the distance between them, positive
698 or negative). Adding (or subtracting) an absolute value to or from a relocatable
699 value yeilds a relocatable value (an offset from the relocatable address).
701 It is important to realize that relocatable values belong to the sections they
702 are defined in (e.g. text, data or BSS), and it is not permissible to mix and match
703 sections. For example, in this code:
707 linel: dc.l line2, line1+8
708 line2: dc.l line1, line2-8
709 line3: dc.l line2-line1, 8
710 error: dc.l line1+line2, line2 >> 1, line3/4
712 Line 1 deposits two longwords that point to line 2. Line 2 deposits two longwords
713 that point to line 1. Line 3 deposits two longwords that have the absolute value
714 eight. The fourth line will result in an assembly error, since the expressions (re-
715 spectively) attempt to add two relocatable values, shift a relocatable value right by
716 one, and divide a relocatable value by four.
718 The pseudo-symbol "*****" (star) has the value that the current section's location
719 counter had at the beginning of the current source line. For example, these two
720 statements deposit three pointers to the label "**bar**":
727 Similarly, the pseudo-symbol "**$**" has the value that the current section's location
728 counter has, and it is kept up to date as the assembler deposits information
729 "across" a line of source code. For example, these two statements deposit four
730 pointers to the label "zip":
740 ================================ ========================================
742 ================================ ========================================
743 **-** Unary minus (2's complement).
744 **!** Logical (boolean) NOT.
745 **~** Tilde: bitwise not (l's complement).
746 **^^defined** *symbol* True if symbol has a value.
747 **^^referenced** *symbol* True if symbol has been referenced.
748 **^^streq** *stringl*,*string2* True if the strings are equal.
749 **^^macdef** *macroName* True if the macro is defined.
750 **^^abscount** Returns the size of current .abs section
751 ================================ ========================================
753 o The boolean operators generate the value 1 if the expression is true, and 0 if it is not.
755 o A symbol is referenced if it is involved in an expression.
757 any combination of attributes: undefined and unreferenced, defined and unref-
758 erenced (i.e. declared but never used), undefined and referenced (in the case
759 of a forward or external reference), or defined and referenced.
766 =========== ==============================================
768 =========== ==============================================
769 \ + - * / The usual arithmetic operators.
770 % Modulo. Do *not* attempt to modulo by 0 or 1.
771 & | ^ Bit-wise **AND**, **OR** and **Exclusive-OR**.
772 << >> Bit-wise shift left and shift right.
773 < <= >= > Boolean magnitude comparisons.
775 <> != Boolean inequality.
776 =========== ==============================================
778 o All binary operators have the same precedence:
779 expressions are evaluated strictly left to right.
781 o Division or modulo by zero yields an assembly error.
783 o The "<>" and "!=" operators are synonyms.
785 o Note that the modulo operator (%) is also used to introduce binary constants
786 (see: `Constants`_). A percent sign should be followed by at least one space if
787 it is meant to be a modulo operator, and is followed by a '0' or '1'.
792 ============ =========================================
793 Special Form Description
794 ============ =========================================
795 **^^date** The current system date (Gemdos format).
796 **^^time** The current system time (Gemdos format).
797 ============ =========================================
799 o The "**^^date**" special form expands to the current system date, in Gemdos
800 format. The format is a 16-bit word with bits 0 ...4 indicating the day of the
801 month (1...31), bits 5...8 indicating the month (1...12), and bits 9...15
802 indicating the year since 1980, in the range 0...119.
804 o The "**^^time**" special form expands to the current system time, in Gemdos
805 format. The format is a 16-bit word with bits 0...4 indicating the current
806 second divided by 2, bits 5...10 indicating the current minute 0...59. and
807 bits 11...15 indicating the current hour 0...23.
809 `Example Expressions`_
810 ''''''''''''''''''''''
814 line address contents source code
815 ---- ------- -------- -------------------------------
816 1 00000000 4480 lab1: neg.l d0
817 2 00000002 427900000000 lab2: clr.w lab1
818 3 =00000064 equ1 = 100
819 4 =00000096 equ2 = equ1 + 50
820 5 00000008 00000064 dc.l lab1 + equ1
821 6 0000000C 7FFFFFE6 dc.l (equl + ~equ2) >> 1
822 7 00000010 0001 dc.w ^^defined equl
823 8 00000012 0000 dc.w ^^referenced lab2
824 9 00000014 00000002 dc.l lab2
825 10 00000018 0001 dc.w ^^referenced lab2
826 11 0000001A 0001 dc.w lab1 = (lab2 - 6)
828 Lines 1 through four here are used to set up the rest of the example. Line 5 deposits
829 a relocatable pointer to the location 100 bytes beyond the label "**lab1**". Line 6 is
830 a nonsensical expression that uses the and right-shift operators. Line 7 deposits
831 a word of 1 because the symbol "**equ1**" is defined (in line 3).
833 Line 8 deposits a word of 0 because the symbol "**lab2**", defined in line 2, has
834 not been referenced. But the expression in line 9 references the symbol "**lab2**", so
835 line 10 (which is a copy of line-8) deposits a word of 1. Finally, line 11 deposits a
836 word of 1 because the Boolean equality operator evaluates to true.
838 The operators "**^^defined**" and "**^^referenced**" are particularly useful in
839 conditional assembly. For instance, it is possible to automatically include debugging
840 code if the debugging code is referenced, as in:
844 lea string,a0 ; AO -> message
845 jsr debug ; print a message
847 string: dc.b "Help me, Spock!",0 ; (the message)
851 .iif ^^defined debug, .include "debug.s"
853 The **jsr** statement references the symbol debug. Near the end of the source file, the
854 "**.iif**" statement includes the file "**debug.s**" if the symbol debug was referenced.
856 In production code, presumably all references to the debug symbol will be removed,
857 and the debug source file will not be included. (We could have as easily made the
858 symbol **debug** external, instead of including another source file).
864 Assembler directives may be any mix of upper- or lowercase. The leading periods
865 are optional, though they are shown here and their use is encouraged. Directives
866 may be preceeded by a label; the label is defined before the directive is executed.
867 Some directives accept size suffixes (**.b**, **.s**, **.w** or **.1**); the default is word (**.w**) if no
868 size is specified. The **.s** suffix is identical to **.b**. Directives relating to the 6502 are
869 described in the chapter on `6502 Support`_.
875 If the location counter for the current section is odd, make it even by adding
876 one to it. In text and data sections a zero byte is deposited if necessary.
879 Align the program counter to the next integral long boundary (4 bytes).
880 Note that GPU/DSP code sections are not contained in their own
881 segments and are actually part of the TEXT or DATA segments.
882 Therefore, to align GPU/DSP code, align the current section before and
883 after the GPU/DSP code.
886 Align the program counter to the next integral phrase boundary (8 bytes).
887 Note that GPU/DSP code sections are not contained in their own
888 segments and are actually part of the TEXT or DATA segments.
889 Therefore, to align GPU/DSP code, align the current section before and
890 after the GPU/DSP code.
893 Align the program counter to the next integral double phrase boundary (16
894 bytes). Note that GPU/DSP code sections are not contained in their own
895 segments and are actually part of the TEXT or DATA segments.
896 Therefore, to align GPU/DSP code, align the current section before and
897 after the GPU/DSP code.
900 Align the program counter to the next integral quad phrase boundary (32
901 bytes). Note that GPU/DSP code sections are not contained in their own
902 segments and are actually part of the TEXT or DATA segments.
903 Therefore, to align GPU/DSP code, align the current section before and
904 after the GPU/DSP code.
905 **.assert** *expression* [,\ *expression*...]
907 Assert that the conditions are true (non-zero). If any of the comma-seperated
908 expressions evaluates to zero an assembler warning is issued. For example:
912 .assert *-start = $76
913 .assert stacksize >= $400
921 Switch to the BSS, data or text segments. Instructions and data may not
922 be assembled into the BSS-segment, but symbols may be defined and storage
923 may be reserved with the **.ds** directive. Each assembly starts out in the text
925 **.abs** [*location*]
927 Start an absolute section, beginning with the specified location (or zero, if
928 no location is specified). An absolute section is much like BSS, except that
929 locations declared with .ds are based absolute. This directive is useful for
931 declaring structures or hardware locations.
932 For example, the following equates:
942 could be as easily defined as:
953 Another interesting example worth mentioning is the emulation of "C"'s "union" keyword
954 using *.abs*. For example, the following "C" code:
964 union { int spf_em_colour; int spf_emx_colour; };
965 union { int spf_em_psmask[16]; int spf_emx_colouropt; };
973 *-------------------------------------------------------*
974 spf_w: ds.w 1 ;<- common
979 *-------------------------------------------------------*
981 spf_em_colour: ds.l 1 ;<- union #1
982 spf_em_psmask: ds.l 16
983 *-------------------------------------------------------*
987 spf_emx_colour: ds.l 1 ;<- union #2
988 spf_emx_colouropt: ds.l 1
989 spf_emx_psmask: ds.l 16
990 spf_emx_psmaskopt: ds.l 16
993 ;*-------------------------------------------------------*
995 move #spf_em_colour,d0
996 move #spf_emx_colour,d0
998 In this example, *spf_em_colour* and *spf_emx_colour* will have the same value.
1000 **.comm** *symbol*, *expression*
1002 Specifies a label and the size of a common region. The label is made global,
1003 thus confined symbols cannot be made common. The linker groups all common
1004 regions of the same name; the largest size determines the real size of the
1005 common region when the file is linked.
1006 **.ccdef** *expression*
1008 Allows you to define names for the condition codes used by the JUMP
1009 and JR instructions for GPU and DSP code. For example:
1015 jump Always,(r3) ; ‘Always’ is actually 0
1017 **.ccundef** *regname*
1019 Undefines a register name (regname) previously assigned using the
1020 .CCDEF directive. This is only implemented in GPU and DSP code
1022 **.dc.i** *expression*
1024 This directive generates long data values and is similar to the DC.L
1025 directive, except the high and low words are swapped. This is provided
1026 for use with the GPU/DSP MOVEI instruction.
1027 **.dc**\ [.\ *size*] *expression* [, *expression*...]
1029 Deposit initialized storage in the current section. If the specified size is word
1030 or long, the assembler will execute a .even before depositing data. If the size
1031 is .b, then strings that are not part of arithmetic expressions are deposited
1032 byte-by-byte. If no size is specified, the default is .w. This directive cannot be
1033 used in the BSS section.
1034 **.dcb**\ [.\ *size*] *expression1*, *expression2*
1036 Generate an initialized block of *expression1* bytes, words or longwords of the
1037 value *expression2*. If the specified size is word or long, the assembler will
1038 execute .even before generating data. If no size is specified, the default is **.w**.
1039 This directive cannot be used in the BSS section.
1040 **.ds**\ [.\ *size*] *expression*
1042 Reserve space in the current segment for the appropriate number of bytes,
1043 words or longwords. If no size is specified, the default size is .w. If the size
1044 is word or long, the assembler will execute .even before reserving space. This
1045 directive can only be used in the BSS or ABS sections (in text or data, use
1046 .dcb to reserve large chunks of initialized storage.)
1049 Switch to Jaguar DSP assembly mode. This directive must be used
1050 within the TEXT or DATA segments.
1051 **.init**\ [.\ *size*] [#\ *expression*,]\ *expression*\ [.\ *size*] [,...]
1053 Generalized initialization directive. The size specified on the directive becomes
1054 the default size for the rest of the line. (The "default" default size is **.w**.) A
1055 comma-seperated list of expressions follows the directive; an expression may be
1056 followed by a size to override the default size. An expression may be preceeded
1057 by a sharp sign, an expression and a comma, which specifies a repeat count to
1058 be applied to the next expression. For example:
1062 .init.l -1, 0.w, #16,'z'.b, #3,0, 11.b
1064 will deposit a longword of -1, a word of zero, sixteen bytes of lower-case 'z',
1065 three longwords of zero, and a byte of 11.
1067 No auto-alignment is performed within the line, but a **.even** is done once
1068 (before the first value is deposited) if the default size is word or long.
1069 **.cargs** [#\ *expression*,] *symbol*\ [.\ *size*] [, *symbol*\ [.\ *size*].. .]
1071 Compute stack offsets to C (and other language) arguments. Each symbol is
1072 assigned an absolute value (like equ) which starts at expression and increases
1073 by the size of each symbol, for each symbol. If the expression is not supplied,
1074 the default starting value is 4. For example:
1078 .cargs #8, .fileliams.1, .openMode, .butPointer.l
1080 could be used to declare offsets from A6 to a pointer to a filename, a word
1081 containing an open mode, and a pointer to a buffer. (Note that the symbols
1082 used here are confined). Another example, a C-style "string-length" function,
1083 could be written as:
1087 _strlen:: .cargs .string ; declare arg
1088 move.l .string(sp),a0 ; a0 -> string
1089 moveq #-1,d0 ; initial size = -1
1090 .1: addq.1 #1,d0 ; bump size
1091 tst.b (a0)+ ; at end of string?
1092 bne .1 ; (no -- try again)
1093 rts ; return string length
1097 End the assembly. In an include file, end the include file and resume assembling
1098 the superior file. This statement is not required, nor are warning messages
1099 generated if it is missing at the end of a file. This directive may be used inside
1100 conditional assembly, macros or **.rept** blocks.
1101 **.equr** *expression*
1103 Allows you to name a register. This is only implemented for GPU/DSP
1104 code sections. For example:
1110 add ClipW,r0 ; ClipW actually is r19
1112 **.if** *expression*
1118 Start a block of conditional assembly. If the expression is true (non-zero) then
1119 assemble the statements between the .if and the matching **.endif** or **.else**.
1120 If the expression is false, ignore the statements unless a matching .else is
1121 encountered. Conditional assembly may be nested to any depth.
1123 It is possible to exit a conditional assembly block early from within an include
1124 file (with **end**) or a macro (with **endm**).
1126 **.iif** *expression*, *statement*
1128 Immediate version of **.if**. If the expression is true (non-zero) then the state-
1129 ment, which may be an instruction, a directive or a macro, is executed. If
1130 the expression is false, the statement is ignored. No **.endif** is required. For
1135 .iif age < 21, canDrink = 0
1136 .iif weight > 500, dangerFlag = 1
1137 .iif !(^^defined DEBUG), .include dbsrc
1139 **.macro** *name* [*formal*, *formal*,...]
1145 Define a macro called name with the specified formal arguments. The macro
1146 definition is terminated with a **.endm** statement. A macro may be exited early
1147 with the .exitm directive. See the chapter on `Macros`_ for more information.
1149 **.undefmac** *macroName* [, *macroName*...]
1151 Remove the macro-definition for the specified macro names. If reference is
1152 made to a macro that is not defined, no error message is printed and the name
1155 **.rept** *expression*
1159 The statements between the **.rept** and **.endr** directives will be repeated *expression*
1160 times. If the expression is zero or negative, no statements will be
1161 assembled. No label may appear on a line containing either of these directives.
1163 **.globl** *symbol* [, *symbol*...]
1165 **.extern** *symbol* [, *symbol*...]
1167 Each symbol is made global. None of the symbols may be confined symbols
1168 (those starting with a period). If the symbol is defined in the assembly, the
1169 symbol is exported in the object file. If the symbol is undefined at the end
1170 of the assembly, and it was referenced (i.e. used in an expression), then the
1171 symbol value is imported as an external reference that must be resolved by the
1172 linker. The **.extern** directive is merely a synonym for **.globl**.
1174 **.include** "*file*"
1176 Include a file. If the filename is not enclosed in quotes, then a default extension
1177 of "**.s**" is applied to it. If the filename is quoted, then the name is not changed
1180 Note: If the filename is not a valid symbol, then the assembler will generate an
1181 error message. You should enclose filenames such as "**atari.s**" in quotes,
1182 because such names are not symbols.
1184 If the include file cannot be found in the current directory, then the directory
1185 search path, as specified by -i on the commandline, or' by the 'RMACPATH'
1186 enviroment string, is traversed.
1190 Issue a page eject in the listing file.
1192 **.title** "*string*"
1194 **.subttl** [-] "*string*"
1196 Set the title or subtitle on the listing page. The title should be specified on
1197 the the first line of the source program in order to take effect on the first page.
1198 The second and subsequent uses of **.title** will cause page ejects. The second
1199 and subsequent uses of .subttl will cause page ejects unless the subtitle string
1200 is preceeded by a dash (-).
1206 Enable or disable source code listing. These directives increment and decrement
1207 an internal counter, so they may be appropriately nested. They have no effect
1208 if the **-l** switch is not specified on the commandline.
1212 This directive provides unstructured flow of control within a macro definition.
1213 It will transfer control to the line of the macro containing the specified goto
1214 label. A goto label is a symbol preceeded by a colon that appears in the first
1215 column of a source line within a macro definition:
1219 where the label itself can be any valid symbol name, followed immediately by
1220 whitespace and a valid source line (or end of line). The colon **must** appear in
1223 The goto-label is removed from the source line prior to macro expansion -
1224 to all intents and purposes the label is invisible except to the .goto directive
1225 Macro expansion does not take place within the label.
1227 For example, here is a silly way to count from 1 to 10 without using **.rept**:
1235 iif count <= 10, goto loop
1240 Switch to Jaguar GPU assembly mode. This directive must be used
1241 within the TEXT or DATA segments.
1244 No. Just... no. Don't ask about it. Ever.
1245 **.prgflags** *value*
1247 Sets ST executable .PRG field *PRGFLAGS* to *value*. *PRGFLAGS* is a bit field defined as follows:
1249 ============ ====== =======
1250 Definition Bit(s) Meaning
1251 ============ ====== =======
1252 PF_FASTLOAD 0 If set, clear only the BSS area on program load, otherwise clear the entire heap.
1253 PF_TTRAMLOAD 1 If set, the program may be loaded into alternative RAM, otherwise it must be loaded into standard RAM.
1254 PF_TTRAMMEM 2 If set, the program's Malloc() requests may be satisfied from alternative RAM, otherwise they must be satisfied from standard RAM.
1255 -- 3 Currently unused.
1256 See left. 4 & 5 If these bits are set to 0 (PF_PRIVATE), the processes' entire memory space will be considered private (when memory protection is enabled).If these bits are set to 1 (PF_GLOBAL), the processes' entire memory space will be readable and writable by any process (i.e. global).If these bits are set to 2 (PF_SUPERVISOR), the processes' entire memory space will only be readable and writable by itself and any other process in supervisor mode.If these bits are set to 3 (PF_READABLE), the processes' entire memory space will be readable by any application but only writable by itself.
1257 -- 6-15 Currently unused.
1258 ============ ====== =======
1260 **.regequ** *expression*
1261 Essentially the same as **.EQUR.** Included for compatibility with the GASM
1264 Essentially the same as **.EQURUNDEF.** Included for compatibility with
1273 All of the standard Motorola 68000 mnemonics and addressing modes are supported;
1274 you should refer to **The Motorola M68000 Programmer's Reference Manual**
1275 for a description of the instruction set and the allowable addressing modes for each
1276 instruction. With one major exception (forward branches) the assembler performs
1277 all the reasonable optimizations of instructions to their short or address register
1280 Register names may be in upper or lower case. The alternate forms ``R0`` through
1281 ``R15`` may be used to specify ``D0`` through ``A7``. All register names are keywords, and
1282 may not be used as labels or symbols. None of the 68010 or 68020 register names
1283 are keywords (but they may become keywords in the future).
1288 ===================================== ===========================================
1289 Assembler Syntax Description
1290 ===================================== ===========================================
1291 *Dn* Data register direct
1292 *An* Address register direct
1293 (*An*) Address register indirect
1294 (*An*)+ Address register indirect postincrement
1295 -(*An*) Address register indirect predecrement
1296 *disp*\ (*An*) Address register indirect with displacement
1297 *bdisp*\ (*An*, *Xi*\ [.\ *size*]) Address register indirect indexed
1298 *abs*.w Absolute short
1299 *abs* Absolute (long or short)
1300 *abs*.l Forced absolute long
1301 *disp*\ (PC) Program counter with displacement
1302 *bdisp*\ (PC, *Xi*\ ) Program counter indexed
1304 ===================================== ===========================================
1308 Since RMAC is a one pass assembler, forward branches cannot be automatically
1309 optimized to their short form. Instead, unsized forward branches are assumed to
1310 be long. Backward branches are always optimized to the short form if possible.
1312 A table that lists "extra" branch mnemonics (common synonyms for the Motorola
1313 defined mnemonics) appears below.
1315 `Linker Constraints`_
1316 '''''''''''''''''''''
1317 It is not possible to make an external reference that will fix up a byte. For example:
1322 move.l frog(pc,d0),d1
1324 is illegal (and generates an assembly error) when frog is external, because the
1325 displacement occupies a byte field in the 68000 offset word, which the object file
1330 ============== ========
1331 Alternate name Becomes:
1332 ============== ========
1342 ============== ========
1344 `Optimizations and Translations`_
1345 '''''''''''''''''''''''''''''''''
1346 The assembler provides "creature comforts" when it processes 68000 mnemonics:
1348 o **CLR.x An** will really generate **SUB.x An,An**.
1350 o **ADD**, **SUB** and **CMP** with an address register will really generate **ADDA**,
1351 **SUBA** and **CMPA**.
1353 o The **ADD**, **AND**, **CMP**, **EOR**, **OR** and **SUB** mnemonics with immediate
1354 first operands will generate the "I" forms of their instructions (**ADDI**, etc.) if
1355 the second operand is not register direct.
1357 o All shift instructions with no count value assume a count of one.
1359 o **MOVE.L** is optimized to **MOVEQ** if the immediate operand is defined and
1360 in the range -128...127. However, **ADD** and **SUB** are never translated to
1361 their quick forms; **ADDQ** and **SUBQ** must be explicit.
1363 o In GPU/DSP code sections, you can use JUMP (Rx) in place of JUMP T, (Rx) and JR
1364 (Rx) in place of JR T,(Rx).
1365 o RMAC tests all GPU/DSP restrictions and corrects them wherever possible (such as
1366 inserting a NOP instruction when needed).
1367 o The “(Rx+N)” addressing mode for GPU/DSP instructions is optimized to “(Rx)”
1372 `Macro declaration`_
1373 ''''''''''''''''''''
1374 A macro definition is a series of statements of the form:
1377 .macro name [ formal-arg, ...]
1381 statements making up the macro body
1387 The name of the macro may be any valid symbol that is not also a 68000 instruction
1388 or an assembler directive. (The name may begin with a period - macros cannot
1389 be made confined the way labels or equated symbols can be). The formal argument
1390 list is optional; it is specified with a comma-seperated list of valid symbol names.
1391 Note that there is no comma between the name of the macro and the name of the
1392 first formal argument.
1394 A macro body begins on the line after the **.macro** directive. All instructions
1395 and directives, except other macro definitions, are legal inside the body.
1397 The macro ends with the **.endm** statement. If a label appears on the line with
1398 this directive, the label is ignored and a warning is generated.
1400 `Parameter Substitution`_
1401 '''''''''''''''''''''''''
1402 Within the body, formal parameters may be expanded with the special forms:
1408 The second form (enclosed in braces) can be used in situations where the characters
1409 following the formal parameter name are valid symbol continuation characters. This
1410 is usually used to force concatentation, as in:
1415 \(godzilla}vs\{reagan}
1417 The formal parameter name is terminated with a character that is not valid in
1418 a symbol (e.g. whitespace or puncuation); optionally, the name may be enclosed in
1419 curly-braces. The names must be symbols appearing on the formal argument list,
1420 or a single decimal digit (``\1`` corresponds to the first argument, ``\2`` to the second,
1421 ``\9`` to the ninth, and ``\0`` to the tenth). It is possible for a macro to have more than
1422 ten formal arguments, but arguments 11 and on must be referenced by name, not
1425 Other special forms are:
1427 ============ ================================================
1428 Special Form Description
1429 ============ ================================================
1430 ``\\`` a single "\",
1431 ``\~`` a unique label of the form "Mn"
1432 ``\#`` the number of arguments actually specified
1433 ``\!`` the "dot-size" specified on the macro invocation
1434 ``\?name`` conditional expansion
1435 ``\?{name}`` conditional expansion
1436 ============ ================================================
1438 The last two forms are identical: if the argument is specified and is non-empty, the
1439 form expands to a "1", otherwise (if the argument is missing or empty) the form
1442 The form "``\!``" expands to the "dot-size" that was specified when the macro
1443 was invoked. This can be used to write macros that behave differently depending
1444 on the size suffix they are given, as in this macro which provides a synonym for the
1449 .macro deposit value
1452 deposit.b 1 ; byte of 1
1453 deposit.w 2 ; word of 2
1454 deposit.l 3 ; longvord of 3
1455 deposit 4 ; word of 4 (no explicit size)
1459 A previously-defined macro is called when its name appears in the operation field of
1460 a statement. Arguments may be specified following the macro name; each argument
1461 is seperated by a comma. Arguments may be empty. Arguments are stored for
1462 substitution in the macro body in the following manner:
1464 o Numbers are converted to hexadecimal.
1466 o All spaces outside strings are removed.
1468 o Keywords (such as register names, dot sizes and "^^" operators) are converted
1471 o Strings are enclosed in double-quote marks (").
1473 For example, a hypothetical call to the macro "``mymacro``", of the form:
1474 ``mymacro A0, , 'Zorch' / 32, "^^DEFINED foo, , , tick tock``
1476 will result in the translations:
1478 ======== ================= =================================================
1479 Argument Expansion Comment
1480 ======== ================= =================================================
1481 ``\1`` ``a0`` "``A0``" converted to lower-case
1483 ``\3`` ``"Zorch"/$20`` "``Zorch``" in double-quotes, 32 in hexadecimal
1484 ``\4`` ``^^defined foo`` "``^^DEFINED``" converted to lower-case
1487 ``\7`` ``ticktock`` spaces removed (note concatenation)
1488 ======== ================= =================================================
1490 The **.exitm** directive will cause an immediate exit from a macro body. Thus
1491 the macro definition:
1496 .iif !\?source, .exitm ; exit if source is empty
1497 move \source,d0 ; otherwise, deposit source
1500 will not generate the move instruction if the argument **"source"** is missing from
1501 the macro invocation.
1503 The **.end**, **.endif** and **.exitm** directives all pop-out of their include levels
1504 appropriately. That is, if a macro performs a **.include** to include a source file, an
1505 executed **.exitm** directive within the include-file will pop out of both the include-file
1508 Macros may be recursive or mutually recursive to any level, subject only to
1509 the availability of memory. When writing recursive macros, take care in the coding
1510 of the termination condition(s). A macro that repeatedly calls itself will cause the
1511 assembler to exhaust its memory and abort the assembly.
1516 The Gemdos macro is used to make file system calls. It has two parameters, a
1517 function number and the number of bytes to clean off the stack after the call. The
1518 macro pushes the function number onto the stack and does the trap to the file
1519 system. After the trap returns, conditional assembly is used to choose an addq or
1520 an **add.w** to remove the arguments that were pushed.
1524 .macro Gemdos trpno, clean
1525 move.w #\trpno,-(sp) ; push trap number
1526 trap #1 ; do GEMDOS trap
1528 addq #\clean,sp ; clean-up up to 8 bytes
1530 add.w #\clean,sp ; clean-up more than 8 bytes
1534 The Fopen macro is supplied two arguments; the address of a filename, and
1535 the open mode. Note that plain move instructions are used, and that the caller of
1536 the macro must supply an appropriate addressing mode (e.g. immediate) for each
1541 .macro Fopen file, mode
1542 movs.w \mode,-(sp) ;push open mode
1543 move.1 \file,-(sp) ;push address of tile name
1544 Gemdos $3d,8 ;do the GEMDOS call
1547 The **String** macro is used to allocate storage for a string, and to place the
1548 string's address somewhere. The first argument should be a string or other expres-
1549 sion acceptable in a dc.b directive. The second argument is optional; it specifies
1550 where the address of the string should be placed. If the second argument is omitted,
1551 the string's address is pushed onto the stack. The string data itself is kept in the
1556 .macro String str,loc
1557 .if \?loc ; if loc is defined
1558 move.l #.\~,\loc ; put the string's address there
1560 pea .\~ ; push the string's address
1562 .data ; put the string data
1563 .\~: dc.b \str,0 ; in the data segment
1564 .text ; and switch back to the text segment
1567 The construction "``.\~``" will expand to a label of the form "``.M``\ *n*" (where *n* is
1568 a unique number for every macro invocation), which is used to tag the location of
1569 the string. The label should be confined because the macro may be used along with
1570 other confined symbols.
1572 Unique symbol generation plays an important part in the art of writing fine
1573 macros. For instance, if we needed three unique symbols, we might write "``.a\~``",
1574 "``.b\~``" and "``.c\~``".
1578 Repeat-blocks provide a simple iteration capability. A repeat block allows a range
1579 of statements to be repeated a specified number of times. For instance, to generate
1580 a table consisting of the numbers 255 through 0 (counting backwards) you could
1585 .count set 255 ; initialize counter
1586 .rept 256 ; repeat 256 times:
1587 dc.b .count ; deposit counter
1588 .count set .count - 1 ; and decrement it
1589 .endr ; (end of repeat block)
1591 Repeat blocks can also be used to duplicate identical pieces of code (which are
1592 common in bitmap-graphics routines). For example:
1596 .rept 16 ; clear 16 words
1597 clr.w (a0)+ ; starting at AO
1600 `Jaguar GPU/DSP Mode`_
1601 ======================
1603 RMAC will generate code for the Atari jaguar GPU and DSP custom RISC (Reduced
1604 Instruction Set Computer) processors. See the Atari Jaguar Software reference Manual – Tom
1605 & Jerry for a complete listing of Jaguar GPU and DSP assembler mnemonics and addressing
1610 The following condition codes for the GPU/DSP JUMP and JR instructions are built-in:
1614 CC (Carry Clear) = %00100
1615 CS (Carry Set) = %01000
1618 NE (Not Equal) = %00001
1620 HI (Higher) = %00101
1626 RMAC will generate code for the Motorola 6502 microprocessor. This chapter
1627 describes extra addressing modes and directives used to support the 6502.
1629 As the 6502 object code is not linkable (currently there is no linker) external
1630 references may not be made. (Nevertheless, RMAC may reasonably be used for
1631 large assemblies because of its blinding speed.)
1633 `6502 Addressing Modes`_
1634 ''''''''''''''''''''''''
1635 All standard 6502 addressing modes are supported, with the exception of the
1636 accumulator addressing form, which must be omitted (e.g. "ror a" becomes "ror").
1637 Five extra modes, synonyms for existing ones, are included for compatibility with
1638 the Atari Coinop assembler.
1640 ============== ========================================
1641 *empty* implied or accumulator (e.g. tsx or ror)
1642 *expr* absolute or zeropage
1644 #<\ *expr* immediate low byte of a word
1645 #>\ *expr* immediate high byte of a word
1646 (*expr*,x) indirect X
1647 (*expr*),y indirect Y
1651 @\ *expr*\ (x) indirect X
1652 @\ *expr*\ (y) indirect Y
1654 x,\ *expr* indexed X
1655 y,\ *expr* indexed Y
1656 ============== ========================================
1661 This directive enters the 6502 section. The location counter is undefined, and
1662 must be set with ".org" before any code can be generated.
1664 The "``dc.w``" directive will produce 6502-format words (low byte first). The
1665 68000's reserved keywords (``d0-d7/a0-a7/ssp/usp`` and so on) remain reserved
1666 (and thus unusable) while in the 6502 section. The directives **globl**, **dc.l**,
1667 **dcb.l**, **text**, **data**, **bss**, **abs**, **even** and **comm** are illegal in the 6502 section.
1668 It is permitted, though probably not useful, to generate both 6502 and 68000
1669 code in the same object file.
1671 This directive leaves the 6502 segment and returns to the 68000's text segment.
1672 68000 instructions may be assembled as normal.
1674 This directive is only legal in the 6502 section. It sets the value of the location
1675 counter (or **pc**) to location, an expression that must be defined, absolute, and
1680 It is possible to assemble "beyond" the microprocessor's 64K address space, but
1681 attempting to do so will probably screw up the assembler. DO NOT attempt
1682 to generate code like this:
1691 the third NOP in this example, at location $10000, may cause the assembler
1692 to crash or exhibit spectacular schizophrenia. In any case, RMAC will give
1693 no warning before flaking out.
1695 `6502 Object Code Format`_
1696 ''''''''''''''''''''''''''
1697 Traditionally Madmac had a very kludgy way of storing object files. This has been
1698 replaced with a more standard *.exe* (or *.com* or *.xex* if you prefer). Briefly,
1699 the *.exe* format consists of chunks of this format (one after the other):
1704 00-01 $FFFF - Indicates a binary load file. Mandatory for first segment, optional for any other segment
1705 02-03 Start Address. The segment will load at this address
1706 04-05 End Address. The last byte to load for this segment
1707 06-.. The actual segment data to load (End Address-Start Address + 1 bytes)
1712 `When Things Go Wrong`_
1713 '''''''''''''''''''''''
1714 Most of RMAC's error messages are self-explanatory. They fall into four classes:
1715 warnings about situations that you (or the assembler) may not be happy about,
1716 errors that cause the assembler to not generate object files, fatal errors that cause
1717 the assembler to abort immediately, and internal errors that should never happen.\ [3]_
1719 You can write editor macros (or sed or awk scripts) to parse the error messages
1720 RMAC generates. When a message is printed, it is of the form:
1722 "*filename*" , ``line`` *line-number*: *message*
1724 The first element, a filename enclosed in double quotes, indicates the file that generated
1725 the error. The filename is followed by a comma, the word "``line``", and a line
1726 number, and finally a colon and the text of the message. The filename "**(\*top\*)**"
1727 indicates that the assembler could not determine which file had the problem.
1729 The following sections list warnings, errors and fatal errors in alphabetical
1730 order, along with a short description of what may have caused the problem.
1732 .. [3] If you come across an internal error, we would appreciate it if you would contact Atari Technical Support and let us know about the problem.
1736 **bad backslash code in string**
1737 You tried to follow a backslash in a string with a character that the assembler
1738 didn't recognize. Remember that RMAC uses a C-style escape system in
1741 You specified a label before a macro, **rept** or **endm** directive. The assembler
1742 is warning you that the label will not be defined in the assembly.
1743 **unoptimized short branch**
1744 This warning is only generated if the -s switch is specified on the command
1745 line. The message refers to a forward, unsized long branch that you could have
1752 As a result of previous errors, the assembler cannot continue processing. The
1753 assembly is aborted.
1754 **line too long as a result of macro expansion**
1755 When a source line within a macro was expanded, the resultant line was too
1756 long for RMAC (longer than 200 characters or so).
1759 **memory exhausted**
1760 The assembler ran out of memory. You should (1) split up your source files
1761 and assemble them seperately, or (2) if you have any ramdisks or RAM-resident
1762 programs (like desk accessories) decrease their size so that the assembler has
1763 more RAM to work with. As a rule of thumb, pure 68000 code will use up to
1764 twice the number of bytes contained in the source files, whereas 6502 code will
1765 use 64K of ram right away, plus the size of the source files. The assembler itself
1766 uses about 80K bytes. Get out your calculator...
1768 The assembler ran across an **endm** directive when it wasn't expecting to see
1769 one. The assembly is aborted. Check the nesting of your macro definitions -
1770 you probably have an extra **endm**.
1778 Syntax error in **.cargs** directive.
1779 **.comm symbol already defined**
1781 You tried to ``.comm`` a symbol that was already defined.
1782 **.ds permitted only in BSS**
1784 You tried to use ``.ds`` in the text or data section.
1785 **.init not permitted in BSS or ABS**
1787 You tried to use ``.init`` in the BSS or ABS section.
1788 **.org permitted only in .6502 section**
1790 You tried to use ``.org`` in a 68000 section.
1791 **Cannot create:** *filename*
1793 The assembler could not create the indicated filename.
1794 **External quick reference**
1796 You tried to make the immediate operand of a **moveq**, **subq** or **addq** instruction external.
1797 **PC-relative expr across sections**
1799 You tried to make a PC-relative reference to a location contained in another
1801 **[bwsl] must follow '.' in symbol**
1803 You tried to follow a dot in a symbol name with something other than one of
1804 the four characters 'B', 'W', 'S' or 'L'.
1805 **addressing mode syntax**
1807 You made a syntax error in an addressing mode.
1810 One of your **.assert** directives failed!
1811 **bad (section) expression**
1813 You tried to mix and match sections in an expression
1814 **bad 6502 addressing mode**
1816 The 6502 mnemonic will not work with the addressing mode you specified.
1819 There's a syntax error in the expression you typed.
1820 **bad size specified**
1822 You tried to use an inappropriate size suffix for the instruction. Check your
1823 68000 manual for allowable sizes.
1826 You can't use .b (byte) mode with the **movem** instruction.
1827 **cannot .globl local symbol**
1829 You tried to make a confined symbol global or common.
1830 **cannot initialize non-storage (BSS) section**
1832 You tried to generate instructions (or data, with dc) in the BSS or ABS section.
1833 **cannot use '.b' with an address register**
1835 You tried to use a byte-size suffix with an address register. The 68000 does not
1836 perform byte-sized address register operations.
1837 **directive illegal in .6502 section**
1839 You tried to use a 68000-oriented directive in the 6502 section.
1842 The expression you typed involves a division by zero.
1843 **expression out of range**
1845 The expression you typed is out of range for its application.
1846 **external byte reference**
1848 You tried to make a byte-sized reference to an external symbol, which the
1849 object file format will not allow
1850 **external short branch**
1852 You tried to make a short branch to an external symbol, which the linker cannot
1854 **extra (unexpected) text found after addressing mode**
1856 RMAC thought it was done processing a line, but it ran up against "extra"
1857 stuff. Be sure that any comment on the line begins with a semicolon, and check
1858 for dangling commas, etc.
1859 **forward or undefined .assert**
1861 The expression you typed after a **.assert** directive had an undefined value.
1862 Remember that RMAC is one-pass.
1863 **hit EOF without finding matching .endif**
1865 The assembler fell off the end of last input file without finding a **.endif** to
1866 match an . it. You probably forgot a **.endif** somewhere.
1867 **illegal 6502 addressing mode**
1869 The 6502 instruction you typed doesn't work with the addressing mode you
1871 **illegal absolute expression**
1873 You can't use an absolute-valued expression here.
1874 **illegal bra.s with zero offset**
1876 You can't do a short branch to the very next instruction (read your 68000
1878 **illegal byte-sized relative reference**
1880 The object file format does not permit bytes contain relocatable values; you
1881 tried to use a byte-sized relocatable expression in an immediate addressing
1883 **illegal character**
1885 Your source file contains a character that RMAC doesn't allow. (most
1886 control characters fall into this category).
1887 **illegal initialization of section**
1889 You tried to use .dc or .dcb in the BSS or ABS sections.
1890 **illegal relative address**
1892 The relative address you specified is illegal because it belongs to a different
1894 **illegal word relocatable (in .PRG mode)**
1896 You can't have anything other than long relocatable values when you're gener-
1897 ating a **.PRG** file.
1898 **inappropriate addressing mode**
1900 The mnemonic you typed doesn't work with the addressing modes you specified.
1901 Check your 68000 manual for allowable combinations.
1902 **invalid addressing mode**
1904 The combination of addressing modes you picked for the **movem** instruction
1905 are not implemented by the 68000. Check your 68000 reference manual for
1907 **invalid symbol following ^^**
1909 What followed the ^^ wasn't a valid symbol at all.
1910 **mis-nested .endr**
1912 The assembler found a **.endr** directive when it wasn't prepared to find one.
1913 Check your repeat-block nesting.
1914 **mismatched .else**
1916 The assembler found a **.else** directive when it wasn't prepared to find one.
1917 Check your conditional assembly nesting.
1918 **mismatched .endif**
1920 The assembler found a **.endif** directive when it wasn't prepared to find one.
1921 Check your conditional assembly nesting.
1927 **missing argument name**
1929 **missing close parenthesis ')'**
1931 **missing close parenthesis ']'**
1935 **missing filename**
1941 **missing symbol or string**
1943 The assembler expected to see a symbol/filename/string (etc...), but found
1944 something else instead. In most cases the problem should be obvious.
1945 **misuse of '.', not allowed in symbols**
1947 You tried to use a dot (.) in the middle of a symbol name.
1950 The expression you typed involves a modulo by zero.
1951 **multiple formal argument definition**
1953 The list of formal parameter names you supplied for a macro definition includes
1954 two identical names.
1955 **multiple macro definition**
1957 You tried to define a macro which already had a definition.
1958 **non-absolute byte reference**
1960 You tried to make a byte reference to a relocatable value, which the object file
1961 format does not allow.
1962 **non-absolute byte value**
1964 You tried to dc.b or dcb.b a relocatable value. Byte relocatable values are
1965 not permitted by the object file format.
1966 **register list order**
1968 You tried to specify a register list like **D7-D0**, which is illegal. Remember
1969 that the first register number must be less than or equal to the second register
1971 **register list syntax**
1973 You made an error in specifying a register list for a **.reg** directive or a **.movem**
1975 **symbol list syntax**
1977 You probably forgot a comma between the names of two symbols in a symbol
1978 list, or you left a comma dangling on the end of the line.
1981 This is a "catch-all" error.
1982 **undefined expression**
1984 The expression has an undefined value because of a forward reference, or an
1985 undefined or external symbol.
1986 **unimplemented addressing mode**
1988 You tried to use 68020 "square-bracket" notation for a 68020 addressing mode.
1989 RMAC does not support 68020 addressing modes.
1990 **unimplemented directive**
1992 You have found a directive that didn't appear in the documentation. It doesn't
1994 **unimplemented mnemonic**
1996 You've found an assembler for documentation) bug.
1997 **unknown symbol following ^^**
1999 You followed a ^^ with something other than one of the names defined, ref-
2001 **unsupported 68020 addressing mode**
2003 The assembler saw a 68020-type addressing mode. RMAC does not assem-
2004 ble code for the 68020 or 68010.
2005 **unterminated string**
2007 You specified a string starting with a single or double quote, but forgot to type
2011 The assembler had a problem writing an object file. This is usually caused by
2012 a full disk, or a bad sector on the media.