11 *NOTE: Every effort has been made to ensure the accuracy and robustness of this
12 manual and the associated software. However, because Reboot is constantly improving
13 and updating its computer software, it is unable to guarantee
14 the accuracy of printed or duplicated material after the date of publication and
15 disclaims liability for changes, errors or omissions.*
18 *Copyright © 2011-2017, Reboot*
20 *All rights reserved.*
22 *Reboot Document number F00000K-001 Rev. A.*
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 Reboot continued work on the freely released source, adding Jaguar extensions
42 RMAC is intended to be used by programmers who write mostly in assembly language.
43 It was not originally a back-end to a C compiler, therefore it
44 has creature comfort that are usually neglected in such back-end assemblers. It
45 supports include files, macros, symbols with limited scope, some limited control
46 structures, and other features. RMAC is also blindingly fast, another feature
47 often sadly and obviously missing in today's assemblers.[1]_
49 RMAC is not entirely compatible with the AS68 assembler provided with
50 the original Atari ST Developer's Kit, but most changes are minor and a few minutes
51 with an editor should allow you to assemble your current source files. If you are an
52 AS68 user, before you leap into the unknown please read the section on Notes for
55 .. [1] It processes 30,000 lines a minute on a lightly loaded VAX 11/780; maybe 40,000 on a 520-ST with an SH-204 hard disk. Yet it could be sped up even more with some effort and without resorting to assembly language; C doesn't have to be slow!
60 =>Write protect your distribution disk and make a backup of it now. Put the
61 original disk in a safe place.
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 **mac** [*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 and enters an "interactive" mode, prompting for successive command lines
106 with a star (\*). An empty command line will exit (See the examples in the chapter
107 on `Using RMAC`_). After each assembly in interactive mode, the assembler
108 will print a summary of the amount of memory used, the amount of memory left,
109 the number of lines processed, and the number of seconds the assembly took.
111 Input files are assumed to have the extension "**.s**"; if a filename has no extension
112 (i.e. no dot) then "**.s**" will be appended to it. More than one source filename may be
113 specified: the files are assembled into one object file, as if they were concatenated.
115 RMAC normally produces object code in "**file.o**" if "**file.s**" is the first
116 input filename. If the first input file is a special character device, the output name
117 is noname.o. The **-o** switch (see below) can be used change the output file name.
120 =================== ===========
122 =================== ===========
123 -dname\ *[=value]* Define symbol, with optional value.
124 -e\ *[file[.err]]* Direct error messages to the specified file.
127 -i\ *path* Set include-file directory search path.
128 -l\ *[file[prn]]* Construct and direct assembly listing to the specified file.
129 -o\ *file[.o]* Direct object code output to the specified file.
130 -p Produce an executable (**.prg**) output file.
131 -ps Produce an executable (**.prg**) output file with symbols.
132 -q Make RMAC resident in memory (Atari ST only).
133 -r *size* automatically pad the size of each
134 segment in the output file until the size is an integral multiple of the
135 specified boundary. Size is a letter that specifies the desired boundary.
137 `-rw Word (2 bytes, default alignment)`
141 `-rp Phrase (8 bytes)`
143 `-rd Double Phrase (16 bytes)`
145 `-rq Quad Phrase (32 bytes)`
146 -s Warn about unoptimized long branches.
147 -u Assume that all undefined symbols are external.
148 -v Verbose mode (print running dialogue).
149 -yn Set listing page size to n lines.
150 -6 "Back end" mode for Alcyon C68.
151 file\ *[s]* Assemble the specified file.
152 =================== ===========
154 The switches are described below. A summary of all the switches is given in
158 The **-d** switch permits symbols to be defined on the command line. The name
159 of the symbol to be defined immediately follows the switch (no spaces). The
160 symbol name may optionally be followed by an equals sign (=) and a decimal
161 number. If no value is specified the symbol's value is zero. The symbol at-
162 tributes are "defined, not referenced, and absolute". This switch is most useful
163 for enabling conditionally-assembled debugging code on the command line; for
168 -dDEBUG -dLoopCount=999 -dDebugLevel=55
171 The -e switch causes RMAC to send error messages to a file, instead of the
172 console. If a filename immediately follows the switch character, error messages
173 are written to the specified file. If no filename is specified, a file is created with
174 the default extension "**.err**" and with the root name taken from the first input
175 file name (e.g. error messages are written to "**file.err**" if "**file**" or "**file.s**" is
176 the first input file name). If no errors are encountered, then no error listing
177 file is created. Beware! If an assembly produces no errors, any error file from
178 a previous assembly is not removed.
181 The **-i** switch allows automatic directory searching for include files. A list of
182 semi-colon seperated directory search paths may be mentioned immediately
183 following the switch (with no spaces anywhere). For example:
187 -im:;c:include;c:include\sys
189 will cause the assembler to search the current directory of device **M**, and the
190 directories include and include\sys on drive **C**. If *-i* is not specified, and the
191 enviroment variable "**MACPATH**" exists, its value is used in the same manner.
192 For example, users of the Mark Williams shell could put the following line in
193 their profile script to achieve the same result as the **-i** example above:
197 setenv MACPATH="m:;c:include;c:include\sys"
199 The -l switch causes RMAC to generate an assembly listing file. If a file-
200 name immediately follows the switch character, the listing is written to the
201 specified file. If no filename is specified, then a listing file is created with the
202 default extension "**.prn**" and with the root name taken from the first input file
203 name (e.g. the listing is written to "**file.prn**" if "**file**" or "**file.s**" is the first
206 The -o switch causes RMAC to write object code on the specified file. No
207 default extension is applied to the filename. For historical reasons the filename
208 can also be seperated from the switch with a space (e.g. "**-o file**").
213 The **-p** and **-ps** switches cause RMAC to produce an Atari ST executable
214 file with the default extension of "**.prg**". If there are any external references
215 at the end of the assembly, an error message is emitted and no executable file
216 is generated. The **-p** switch does not write symbols to the executable file. The
217 **-ps** switch includes symbols (Alcyon format) in the executable file.
219 The **-q** switch is aimed primarily at users of floppy-disk-only systems. It causes
220 RMAC to install itself in memory, like a RAMdisk. Then the program
221 **m.prg** (which is very short - less than a sector) can be used instead of
222 **mac.prg**, which can take ten or twelve seconds to load. (**NOTE** not available
223 for now, might be re-implemented in the future).
225 The **-s** switch causes RMAC to generate a list of unoptimized forward
226 branches as warning messages. This is used to point out branches that could
227 have been short (e.g. "bra" could be "bra.s").
229 The **-u** switch takes effect at the end of the assembly. It forces all referenced
230 and undefined symbols to be global, exactly as if they had been made global
231 with a **.extern** or **.globl** directive. This can be used if you have a lot of
232 external symbols, and you don't feel like declaring them all external.
234 The **-v** switch turns on a "verbose" mode in which RMAC prints out (for
235 example) the names of the files it is currently processing. Verbose mode is
236 automatically entered when RMAC prompts for input with a star.
238 The **-y** switch, followed immediately by a decimal number (with no intervening
239 space), sets the number of lines in a page. RMAC will produce *N* lines
240 before emitting a form-feed. If *N* is missing or less than 10 an error message is
246 Let's assemble and link some example programs. These programs are included
247 on the distribution disk in the "**EXAMPLES**" directory - you should copy them to
248 your work area before continuing. In the following examples we adopt the conven-
249 tions that the shell prompt is a percent sign (%) and that your input (the stuff you
250 type) is presented in **bold face**.
252 If you have been reading carefully, you know that RMAC can generate
253 an executable file without linking. This is useful for making small, stand alone
254 programs that don't require externals or library routines. For example, the following
262 could be replaced by the single command:
268 since you don't need the linker for stand-alone object files.
270 Successive source files named in the command line are are concatenated, as in
271 this example, which assembles three files into a single executable, as if they were
276 % rmac -p bugs shift images
278 Of course you can get the same effect by using the **.include** directive, but sometimes
279 it is convenient to do the concatenation from the command line.
281 Here we have an unbelievably complex command line:
285 % rmac -lzorf -y95 -o tmp -ehack -Ddebug=123 -ps example
287 This produces a listing on the file called "**zorf.prn**" with 95 lines per page, writes
288 the executable code (with symbols) to a file called "**tmp.prg**", writes an error listing
289 to the file "**hack.err**", specifies an include-file path that includes the current
290 directory on the drive "**M:**," defines the symbol "**debug**" to have the value 123, and
291 assembles the file "**example.s**". (Take a deep breath - you got all that?)
293 One last thing. If there are any assembly errors, RMAC will terminate
294 with an exit code of 1. If the assembly succeeds (no errors, although there may be
295 warnings) the exit code will be 0. This is primarily for use with "make" utilities.
299 If you invoke RMAC with an empty command line it will print a copyright
300 message and prompt you for more commands with a star (*****). This is useful if you
301 are used to working directly from the desktop, or if you want to assemble several files
302 in succession without having to reload the assembler from disk for each assembly.
304 In interactive mode, the assembler is also in verbose mode (just as if you had
305 specified **-v** on each command line):
311 MADMAC Atari Macro Assembler
312 Copyright 1987 Atari Corporation
313 Beta version 0.12 Jun 1987 lmd
316 [Including: example.s]
319 [Leaving; example. a]
320 [Writing executable tile: example.prg
321 36K used, 3868K left, 850 lines, 2.0 seconds
324 You can see that the assembler gave a "blow-by-blow" account of the files it processed,
325 as well as a summary of the assembly's memory usage, the number of lines
326 processed (including macro and repeat-block expansion), and how long the assembly
329 The assembler prompts for another command with the star. At this point you
330 can either type a new command line for the assembler to process, or you can exit
331 by typing control-C or an empty line.
333 Things You Should Be Aware Of
334 '''''''''''''''''''''''''''''
335 RMAC is a one pass assembler. This means that it gets all of its work done by
336 reading each source file exactly once and then "back-patching" to fix up forward
337 references. This one-pass nature is usually transparent to the programmer, with
338 the following important exceptions:
340 o in listings, the object code for forward references is not shown. Instead, lower-
341 case "xx"s are displayed for each undefined byte, as in the following example:
345 60xx 1: bra.s.2 ;forward branch
346 xxxxxxxx dc.l .2 ;forward reference
347 60FE .2: bra.s.2 ;backward reference
349 o Forward branches (including **BSR**\s) are never optimized to their short forms.
350 To get a short forward branch it is necessary to explicitly use the ".s" suffix in
352 o Error messages may appear at the end of the assembly, referring to earlier source
353 lines that contained undefined symbols.
354 o All object code generated must fit in memory. Running out of memory is a
355 fatal error that you must deal with by splitting up your source files, re-sizing
356 or eliminating memory-using programs such as ramdisks and desk accessories,
361 RMAC does not optimize forward branches for you, but it will tell you about
362 them if you use the -s (short branch) option:
367 "example.s", line 20: warning: unoptimized short branch
369 With the -e option you can redirect the error output to a file, and determine by
370 hand (or editor macros) which forward branches are safe to explicitly declare short.
372 `Notes for migrating from other 68000 assemblers`_
373 ''''''''''''''''''''''''''''''''''''''''''''''''''
374 RMAC is not entirely compatible with the other popular assemblers
375 like Devpac or vasm. This section
376 outlines the major differences. In practice, we have found that very few changes are
377 necessary to make other assemblers' source code assemble.
379 o A semicolon (;) must be used to introduce a comment, except that a star (*)
380 may be used in the first column. AS68 treated anything following the operand
381 field, preceeded by whitespace, as a comment. (RMAC treats a star that
382 is not in column 1 as a multiplication operator).
384 o Labels require colons (even labels that begin in column 1).
386 o Conditional assembly directives are called **if**, **else** and **endif**. Devpac and vasm called these
387 **ifne**, **ifeq** (etc.), and **endc**.
388 o The tilde (~) character is an operator, and back-quote (`) is an illegal character.
389 AS68 permitted the tilde and back-quote characters in symbols.
390 o There are no equivalents to org or section directives.
391 The **.xdef** and **.xref** directives are not implemented,
392 but **.globl** makes these unnecessary anyway.
394 o The location counter cannot be manipulated with a statement of the form:
400 o The **ds** directive is not permitted in the text or data segments;
401 an error message is issued. Use **dcb** instead to reserve large blocks of
403 o Back-slashes in strings are "electric" characters that are used to escape C-like
404 character codes. Watch out for GEMDOS path names in ASCII constants -
405 you will have to convert them to double-backslashes.
406 o Expression evaluation is done left-to-right without operator precedence. Use parentheses to
407 force the expression evaluation as you wish.
409 o Mark your segments across files. Branching to a code segment that could be identified as BSS will cause a "Error: cannot initialize non-storage (BSS) section"
410 o rs.b/rs.w/rs.l/rscount/rsreset can be simulated in rmac using abs. For example the following source:
420 size_so_far equ rscount
432 size_so_far equ ^^abscount
434 o A rare case: if your macro contains something like:
444 then by the assembler's design this will fail as the parameters are automatically converted to hex. Changing the code like his works:
456 For those using editors other than the "Emacs" style ones (Micro-Emacs, Mince,
457 etc.) this section documents the source file format that RMAC expects.
459 o Files must contain characters with ASCII values less than 128; it is not per-
460 missable to have characters with their high bits set unless those characters are
461 contained in strings (i.e. between single or double quotes) or in comments.
463 o Lines of text are terminated with carriage-return/line-feed, linefeed alone, or
464 carriage-return alone.
466 o The file is assumed to end with the last terminated line. If there is text beyond
467 the last line terminator (e.g. control-Z) it is ignored.
474 A statement may contain up to four fields which are identified by order of ap-
475 pearance and terminating characters. The general form of an assembler statement
480 label: operator operand(s) ; comment
482 The label and comment fields are optional. An operand field may not appear
483 without an operator field. Operands are seperated with commas. Blank lines are
484 legal. If the first character on a line is an asterisk (*) or semicolon (;) then the
485 entire line is a comment. A semicolon anywhere on the line (except in a string)
486 begins a comment field which extends to the end of the line.
488 The label, if it appears, must be terminated with a single or double colon. If
489 it is terminated with a double colon it is automatically declared global. It is illegal
490 to declare a confined symbol global (see: `Symbols and Scope`_).
494 A statement may also take one of these special forms:
496 *symbol* **equ** *expression*
498 *symbol* **=** *expression*
500 *symbol* **--** *expression*
502 *symbol* **set** *expression*
504 *symbol* **reg** *register list*
506 The first two forms are identical; they equate the symbol to the value of an
507 expression, which must be defined (no forward references). The third form, double-
508 equals (==), is just like an equate except that it also makes the symbol global. (As
509 with labels, it is illegal to make a confined equate global.) The fourth form allows
510 a symbol to be set to a value any number of times, like a variable. The last form
511 equates the symbol to a 16-bit register mask specified by a register list. It is possible
512 to equate confined symbols (see: `Symbols and Scope`_). For example:
516 cr equ 13 carriage-return
518 DEBUG == 1 global debug flag
520 count set count + 1 increment variable
521 .rags reg d3-d7/a3-a6 register list
522 .cr 13 confined equate
526 Symbols may start with an uppercase or lowercase letter (A-Z a-z), an underscore
527 (**_**), a question mark (**?**) or a period (**.**). Each remaining character may be an
528 upper or lowercase letter, a digit (**0-9**), an underscore, a dollar sign (**$**), or a question
529 mark. (Periods can only begin a symbol, they cannot appear as a symbol
530 continuation character). Symbols are terminated with a character that is not a
531 symbol continuation character (e.g. a period or comma, whitespace, etc.). Case is
532 significant for user-defined symbols, but not for 68000 mnemonics, assembler direc-
533 tives and register names. Symbols are limited to 100 characters. When symbols
534 are written to the object file they are silently truncated to eight (or sixteen) char-
535 acters (depending on the object file format) with no check for (or warnings about)
538 For example, all of the following symbols are legal and unique:
542 reallyLougSymbolliame .reallyLongConfinadSymbollame
543 al0 ret move dc frog aae a9 ????
544 .al .ret .move .dc .frog .a9 .9 ????
545 .0 .00 .000 .1 .11. .111 . ._
546 _frog ?zippo? sys$syetem atari Atari ATARI aTaRi
548 while all of the following symbols are illegal:
552 12days dc.10 dc.z 'quote .right.here
553 @work hi.there $money$ ~tilde
556 Symbols beginning with a period (**.**) are *confined*; their scope is between two
557 normal (unconfined) labels. Confined symbols may be labels or equates. It is illegal
558 to make a confined symbol global (with the ".globl" directive, a double colon, or a
559 double equals). Only unconfined labels delimit a confined symbol's scope; equates
560 (of any kind) do not count. For example, all symbols are unique and have unique
561 values in the following:
572 .loop: move.w -1,(a0)+
576 Confined symbols are useful since the programmer has to be much less inventive
577 about finding small, unique names that also have meaning.
579 It is legal to define symbols that have the same names as processor mnemonics
580 (such as "**move**" or "**rts**") or assembler directives (such as "**.even**"). Indeed, one
581 should be careful to avoid typographical errors, such as this classic (in 6502 mode):
589 which equates a confined symbol to a hexadecimal value, rather than setting the
590 location counter, which the .org directive does (without the equals sign).
594 The following names, in all combinations of uppercase and lowercase, are keywords
595 and may not be used as symbols (e.g. labels, equates, or the names of macros):
601 dO di d2 d3 d4 d5 d6 d7
602 a0 al a2 a3 a4 a5 a6 aT
603 r0 ri r2 r3 r4 r5 r6 r7
604 r8 r9 r10 1'11 r12 rl3 ri4 ri5
608 Numbers may be decimal, hexadecimal, octal, binary or concatenated ASCII. The
609 default radix is decimal, and it may not be changed. Decimal numbers are specified
610 with a string of digits (**0-9**). Hexadecimal numbers are specified with a leading
611 dollar sign (**$**) followed by a string of digits and uppercase or lowercase letters (**A-F
612 a-f**). Octal numbers are specified with a leading at-sign (**@**) followed by a string
613 of octal digits (**0-7**). Binary numbers are specified with a leading percent sign
614 (**%**) followed by a string of binary digits (**0-1**). Concatenated ASCII constants are
615 specified by enclosing from one to four characters in single or double quotes. For
627 Negative numbers Are specified with a unary minus (**-**). For example:
636 Strings are contained between double (") or single ( ') quote marks. Strings may
637 contain non-printable characters by specifying "backslash" escapes, similar to the
638 ones used in the C programming language. RMAC will generate a warning if a
639 backslash is followed by a character not appearing below:
644 \n $0a line-feed (newline)
647 \r $0c1 carriage-return
653 It is possible for strings (but not symbols) to contain characters with their high
654 bits set (i.e. character codes 128...255).
656 You should be aware that backslash characters are popular in GEMDOS path
657 names, and that you may have to escape backslash characters in your existing source
658 code. For example, to get the file "'c:\auto\ahdi.s'" you would specify the string
659 "`c:\\auto\\ahdi.s`".
663 Register lists are special forms used with the **movem** mnemonic and the **.reg**
664 directive. They are 16-bit values, with bits 0 through 15 corresponding to registers
665 **D0** through **A7**. A register list consists of a series of register names or register
666 ranges seperated by slashes. A register range consists of two register names, Rm
667 and Rn,m<n, seperated by a dash. For example:
675 d0/d1/a0-a3/d7/a6-a7 $CF83
679 Register lists and register equates may be used in conjunction with the movem
680 mnemonic, as in this example:
684 temps reg d0-d2/a0-a2 ; temp registers
685 keeps reg d3-d7/d3-a6 ; registers to preserve
686 allregs reg d0-d7/a0-a7 ; all registers
687 movem.l #temps, -(sp) ; these two lines ...
688 aovea.l dO -d2/a0 -a2, -(sp) ; are identical
689 movea.l #keeps, -(sp) ; save "keep" registers
690 noven.1 (sp)+,#keeps ; restore "keep" registers
695 `Order of Evaluation`_
696 ''''''''''''''''''''''
697 All values are computed with 32-bit 2's complement arithmetic. For boolean operations
698 (such as if or **assert**) zero is considered false, and non-zero is considered
701 **Expressions are evaluated strictly left-to-right, with no
702 regard for operator precedence.**
704 Thus the expression "1+2*3" evaluates to 9, not 7. However, precedence may be
705 forced with parenthesis (**()**) or square-brackets (**[]**).
709 Expressions belong to one of three classes: undefined, absolute or relocatable. An
710 expression is undefined if it involves an undefined symbol (e.g. an undeclared sym-
711 bol, or a forward reference). An expression is absolute if its value will not change
712 when the program is relocated (for instance, the number 0, all labels declared in
713 an abs section, and all Atari ST hardware register locations are absolute values).
714 An expression is relocatable if it involves exactly one symbol that is contained in a
715 text, data or BSS section.
717 Only absolute values may be used with operators other than addition (+) or
718 subtraction (-). It is illegal, for instance, to multiply or divide by a relocatable or
719 undefined value. Subtracting a relocatable value from another relocatable value in
720 the same section results in an absolute value (the distance between them, positive
721 or negative). Adding (or subtracting) an absolute value to or from a relocatable
722 value yeilds a relocatable value (an offset from the relocatable address).
724 It is important to realize that relocatable values belong to the sections they
725 are defined in (e.g. text, data or BSS), and it is not permissible to mix and match
726 sections. For example, in this code:
730 linel: dc.l line2, linel+8
731 line2: dc.l linel, line2-8
732 line3: dc.l line2-linel, 8
733 error: dc.l linel+line2, line2 >> 1, line3/4
735 Line 1 deposits two longwords that point to line 2. Line 2 deposits two longwords
736 that point to line 1. Line 3 deposits two longwords that have the absolute value
737 eight. The fourth line will result in an assembly error, since the expressions (re-
738 spectively) attempt to add two relocatable values, shift a relocatable value right by
739 one, and divide a relocatable value by four.
741 The pseudo-symbol "*****" (star) has the value that the current section's location
742 counter had at the beginning of the current source line. For example, these two
743 statements deposit three pointers to the label "**bar**":
750 Similarly, the pseudo-symbol "**$**" has the value that the current section's location
751 counter has, and it is kept up to date as the assembler deposits information
752 "across" a line of source code. For example, these two statements deposit four
753 pointers to the label "zip":
763 ================================ ========================================
765 ================================ ========================================
766 **-** Unary minus (2's complement).
767 **!** Logical (boolean) NOT.
768 **~** Tilde: bitwise not (l's complement).
769 **^^defined** *symbol* True if symbol has a value.
770 **^^referenced** *symbol* True if symbol has been referenced.
771 **^^streq** *stringl*,*string2* True if the strings are equal.
772 **^^macdef** *macroName* True if the macro is defined.
773 **^^abscount** Returns the size of current .abs section
774 ================================ ========================================
776 o The boolean operators generate the value 1 if the expression is true, and 0 if
779 o A symbol is referenced if it is involved in an expression. A symbol may have
780 any combination of attributes: undefined and unreferenced, defined and unref-
781 erenced (i.e. declared but never used), undefined and referenced (in the case
782 of a forward or external reference), or defined and referenced.
789 =========== ==============================================
791 =========== ==============================================
792 \ + - * / The usual arithmetic operators.
794 & | ^ Bit-wise **AND**, **OR** and **Exclusive-OR**.
795 << >> Bit-wise shift left and shift right.
796 < <= >= > Boolean magnitude comparisons.
798 <> != Boolean inequality.
799 =========== ==============================================
801 o All binary operators have the same precedence: expressions are evaluated
802 strictly left to right.
804 o Division or modulo by zero yields an assembly error
806 o The "<>" and "!=" operators are synonyms.
808 o Note that the modulo operator (%) is also used to introduce binary constants
809 (see: `Constants`_). A percent sign should be followed by at least one space if
810 it is meant to be a modulo operator, and is followed by a '0' or '1'.
815 ============ =========================================
816 Special Form Description
817 ============ =========================================
818 **^^date** The current system date (Gemdos format).
819 **^^time** The current system time (Gemdos format).
820 ============ =========================================
822 o The "**^^date**" special form expands to the current system date, in Gemdos
823 format. The format is a 16-bit word with bits 0 ...4 indicating the day of the
824 month (1...31), bits 5...8 indicating the month (1...12), and bits 9...15
825 indicating the year since 1980, in the range 0...119.
827 o The "**^^time**" special form expands to the current system time, in Gemdos
828 format. The format is a 16-bit word with bits 0...4 indicating the current
829 second divided by 2, bits 5...10 indicating the current minute 0...59. and
830 bits 11...15 indicating the current hour 0...23.
832 `Example Expressions`_
833 ''''''''''''''''''''''
837 line address contents source code
838 ---- ------- -------- -------------------------------
839 1 00000000 4480 lab1: neg.l d0
840 2 00000002 427900000000 lab2: clr.w lab1
841 3 =00000064 equ1 = 100
842 4 =00000096 equ2 = equ1 + 50
843 5 00000008 00000064 dc.l lab1 + equ1
844 6 0000000C 7FFFFFE6 dc.l (equl + ~equ2) >> 1
845 7 00000010 0001 dc.w ^^defined equl
846 8 00000012 0000 dc.w ^^referenced lab2
847 9 00000014 00000002 dc.l lab2
848 10 00000018 0001 dc.w ^^referenced lab2
849 11 0000001A 0001 dc.w lab1 = (lab2 - 6)
851 Lines 1 through four here are used to set up the rest of the example. Line 5 deposits
852 a relocatable pointer to the location 100 bytes beyond the label "**lab1**". Line 6 is
853 a nonsensical expression that uses the and right-shift operators. Line 7 deposits
854 a word of 1 because the symbol "**equ1**" is defined (in line 3).
856 Line 8 deposits a word of 0 because the symbol "**lab2**", defined in line 2, has
857 not been referenced. But the expression in line 9 references the symbol "**lab2**", so
858 line 10 (which is a copy of line-8) deposits a word of 1. Finally, line 11 deposits a
859 word of 1 because the Boolean equality operator evaluates to true.
861 The operators "**^^defined**" and "**^^referenced**" are particularly useful in
862 conditional assembly. For instance, it is possible to automatically include debugging
863 code if the debugging code is referenced, as in:
867 lea string,a0 ; AO -> message
868 jsr debug ; print a message
870 string: dc.b "Help me, Spock!",0 ; (the message)
874 .iif ^^defined debug, .include "debug.s"
876 The **jsr** statement references the symbol debug. Near the end of the source file, the
877 "**.iif**' statement includes the file "**debug.s**" if the symbol debug was referenced.
879 In production code, presumably all references to the debug symbol will be removed,
880 and the debug source file will not be included. (We could have as easily made the
881 symbol **debug** external, instead of including another source file).
887 Assembler directives may be any mix of upper- or lowercase. The leading periods
888 are optional, though they are shown here and their use is encouraged. Directives
889 may be preceeded by a label; the label is defined before the directive is executed.
890 Some directives accept size suffixes (**.b**, **.s**, **.w** or **.1**); the default is word (**.w**) if no
891 size is specified. The **.s** suffix is identical to **.b**. Directives relating to the 6502 are
892 described in the chapter on `6502 Support`_.
897 If the location counter for the current section is odd, make it even by adding
898 one to it. In text and data sections a zero byte is deposited if necessary.
900 Align the program counter to the next integral long boundary (4 bytes).
901 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.
906 Align the program counter to the next integral phrase boundary (8 bytes).
907 Note that GPU/DSP code sections are not contained in their own
908 segments and are actually part of the TEXT or DATA segments.
909 Therefore, to align GPU/DSP code, align the current section before and
910 after the GPU/DSP code.
912 Align the program counter to the next integral double phrase boundary (16
913 bytes). Note that GPU/DSP code sections are not contained in their own
914 segments and are actually part of the TEXT or DATA segments.
915 Therefore, to align GPU/DSP code, align the current section before and
916 after the GPU/DSP code.
918 Align the program counter to the next integral quad phrase boundary (32
919 bytes). Note that GPU/DSP code sections are not contained in their own
920 segments and are actually part of the TEXT or DATA segments.
921 Therefore, to align GPU/DSP code, align the current section before and
922 after the GPU/DSP code.
923 **.assert** *expression* [,\ *expression*...]
924 Assert that the conditions are true (non-zero). If any of the comma-seperated
925 expressions evaluates to zero an assembler warning is issued. For example:
929 .assert *-start = $76
930 .assert stacksize >= $400
937 Switch to the BSS, data or text segments. Instructions and data may not
938 be assembled into the BSS-segment, but symbols may be defined and storage
939 may be reserved with the **.ds** directive. Each assembly starts out in the text
941 **.abs** [*location*]
942 Start an absolute section, beginning with the specified location (or zero, if
943 no location is specified). An absolute section is much like BSS, except that
944 locations declared with .ds are based absolute. This directive is useful for
945 declaring structures or hardware locations.
946 For example, the following equates:
956 could be as easily defined as:
967 Another interesting example worth mentioning is the emulation of "C"'s "union" keyword
968 using *.abs*. For example, the following "C" code:
978 union { int spf_em_colour; int spf_emx_colour; };
979 union { int spf_em_psmask[16]; int spf_emx_colouropt; };
987 *-------------------------------------------------------*
988 spf_w: ds.w 1 ;<- common
993 *-------------------------------------------------------*
995 spf_em_colour: ds.l 1 ;<- union #1
996 spf_em_psmask: ds.l 16
997 *-------------------------------------------------------*
1001 spf_emx_colour: ds.l 1 ;<- union #2
1002 spf_emx_colouropt: ds.l 1
1003 spf_emx_psmask: ds.l 16
1004 spf_emx_psmaskopt: ds.l 16
1007 ;*-------------------------------------------------------*
1009 move #spf_em_colour,d0
1010 move #spf_emx_colour,d0
1012 In this example, *spf_em_colour* and *spf_emx_colour* will have the same value.
1014 **.comm** *symbol*, *expression*
1015 Specifies a label and the size of a common region. The label is made global,
1016 thus confined symbols cannot be made common. The linker groups all common
1017 regions of the same name; the largest size determines the real size of the
1018 common region when the file is linked.
1019 **.ccdef** *expression*
1020 Allows you to define names for the condition codes used by the JUMP
1021 and JR instructions for GPU and DSP code. For example:
1027 jump Always,(r3) ; ‘Always’ is actually 0
1029 **.ccundef** *regname*
1030 Undefines a register name (regname) previously assigned using the
1031 .CCDEF directive. This is only implemented in GPU and DSP code
1033 **.dc.i** *expression*
1034 This directive generates long data values and is similar to the DC.L
1035 directive, except the high and low words are swapped. This is provided
1036 for use with the GPU/DSP MOVEI instruction.
1037 **.dc**\ [.\ *size*] *expression* [, *expression*...]
1038 Deposit initialized storage in the current section. If the specified size is word
1039 or long, the assembler will execute a .even before depositing data. If the size
1040 is .b, then strings that are not part of arithmetic expressions are deposited
1041 byte-by-byte. If no size is specified, the default is .w. This directive cannot be
1042 used in the BSS section.
1043 **.dcb**\ [.\ *size*] *expression1*, *expression2*
1044 Generate an initialized block of *expression1* bytes, words or longwords of the
1045 value *expression2*. If the specified size is word or long, the assembler will
1046 execute .even before generating data. If no size is specified, the default is **.w**.
1047 This directive cannot be used in the BSS section.
1048 **.ds**\ [.\ *size*] *expression*
1049 Reserve space in the current segment for the appropriate number of bytes,
1050 words or longwords. If no size is specified, the default size is .w. If the size
1051 is word or long, the assembler will execute .even before reserving space. This
1052 directive can only be used in the BSS or ABS sections (in text or data, use
1053 .dcb to reserve large chunks of initialized storage.)
1055 Switch to Jaguar DSP assembly mode. This directive must be used
1056 within the TEXT or DATA segments.
1057 **.init**\ [.\ *size*] [#\ *expression*,]\ *expression*\ [.\ *size*] [,...]
1058 Generalized initialization directive. The size specified on the directive becomes
1059 the default size for the rest of the line. (The "default" default size is **.w**.) A
1060 comma-seperated list of expressions follows the directive; an expression may be
1061 followed by a size to override the default size. An expression may be preceeded
1062 by a sharp sign, an expression and a comma, which specifies a repeat count to
1063 be applied to the next expression. For example:
1067 .init.l -1, 0.w, #16,'z'.b, #3,0, 11.b
1069 will deposit a longword of -1, a word of zero, sixteen bytes of lower-case 'z',
1070 three longwords of zero, and a byte of 11.
1072 No auto-alignment is performed within the line, but a **.even** is done once
1073 (before the first value is deposited) if the default size is word or long.
1074 **.cargs** [#\ *expression*,] *symbol*\ [.\ *size*] [, *symbol*\ [.\ *size*].. .]
1075 Compute stack offsets to C (and other language) arguments. Each symbol is
1076 assigned an absolute value (like equ) which starts at expression and increases
1077 by the size of each symbol, for each symbol. If the expression is not supplied,
1078 the default starting value is 4. For example:
1082 .cargs #8, .fileliams.1, .openMode, .butPointer.l
1084 could be used to declare offsets from A6 to a pointer to a filename, a word
1085 containing an open mode, and a pointer to a buffer. (Note that the symbols
1086 used here are confined). Another example, a C-style "string-length" function,
1087 could be written as:
1091 _strlen:: .cargs .string ; declare arg
1092 move.l .string(sp),a0 ; a0 -> string
1093 moveq #-1,d0 ; initial size = -1
1094 .1: addq.1 #1,d0 ; bump size
1095 tst.b (a0)+ ; at end of string?
1096 bne .1 ; (no -- try again)
1097 rts ; return string length
1100 End the assembly. In an include file, end the include file and resume assembling
1101 the superior file. This statement is not required, nor are warning messages
1102 generated if it is missing at the end of a file. This directive may be used inside
1103 conditional assembly, macros or **.rept** blocks.
1104 **.equr** *expression*
1105 Allows you to name a register. This is only implemented for GPU/DSP
1106 code sections. For example:
1112 add ClipW,r0 ; ClipW actually is r19
1114 **.if** *expression*
1120 Start a block of conditional assembly. If the expression is true (non-zero) then
1121 assemble the statements between the .if and the matching **.endif** or **.else**.
1122 If the expression is false, ignore the statements unless a matching .else is
1123 encountered. Conditional assembly may be nested to any depth.
1125 It is possible to exit a conditional assembly block early from within an include
1126 file (with **end**) or a macro (with **endm**).
1128 **.iif** *expression*, *statement*
1130 Immediate version of **.if**. If the expression is true (non-zero) then the state-
1131 ment, which may be an instruction, a directive or a macro, is executed. If
1132 the expression is false, the statement is ignored. No **.endif** is required. For
1137 .iif age < 21, canDrink = 0
1138 .iif weight > 500, dangerFlag = 1
1139 .iif !(^^defined DEBUG), .include dbsrc
1141 **.macro** *name* [*formal*, *formal*,...]
1146 Define a macro called name with the specified formal arguments. The macro
1147 definition is terminated with a **.endm** statement. A macro may be exited early
1148 with the .exitm directive. See the chapter on `Macros`_ for more information.
1150 **.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*
1158 The statements between the **.rept** and **.endr** directives will be repeated *expression*
1159 times. If the expression is zero or negative, no statements will be
1160 assembled. No label may appear on a line containing either of these directives.
1162 **.globl** *symbol* [, *symbol*...]
1164 **.extern** *symbol* [, *symbol*...]
1165 Each symbol is made global. None of the symbols may be confined symbols
1166 (those starting with a period). If the symbol is defined in the assembly, the
1167 symbol is exported in the object file. If the symbol is undefined at the end
1168 of the assembly, and it was referenced (i.e. used in an expression), then the
1169 symbol value is imported as an external reference that must be resolved by the
1170 linker. The **.extern** directive is merely a synonym for **.globl**.
1172 **.include** "*file*"
1173 Include a file. If the filename is not enclosed in quotes, then a default extension
1174 of "**.s**" is applied to it. If the filename is quoted, then the name is not changed
1177 Note: If the filename is not a valid symbol, then the assembler will generate an
1178 error message. You should enclose filenames such as "**atari.s**" in quotes,
1179 because such names are not symbols.
1181 If the include file cannot be found in the current directory, then the directory
1182 search path, as specified by -i on the commandline, or' by the 'MACPATH'
1183 enviroment string, is traversed.
1186 Issue a page eject in the listing file.
1188 **.title** "*string*"
1190 **.subttl** [-] "*string*"
1191 Set the title or subtitle on the listing page. The title should be specified on
1192 the the first line of the source program in order to take effect on the first page.
1193 The second and subsequent uses of **.title** will cause page ejects. The second
1194 and subsequent uses of .subttl will cause page ejects unless the subtitle string
1195 is preceeded by a dash (-).
1200 Enable or disable source code listing. These directives increment and decrement
1201 an internal counter, so they may be appropriately nested. They have no effect
1202 if the **-l** switch is not specified on the commandline.
1205 This directive provides unstructured flow of control within a macro definition.
1206 It will transfer control to the line of the macro containing the specified goto
1207 label. A goto label is a symbol preceeded by a colon that appears in the first
1208 column of a source line within a macro definition:
1212 where the label itself can be any valid symbol name, followed immediately by
1213 whitespace and a valid source line (or end of line). The colon **must** appear in
1216 The goto-label is removed from the source line prior to macro expansion -
1217 to all intents and purposes the label is invisible except to the .goto directive
1218 Macro expansion does not take place within the label.
1220 For example, here is a silly way to count from 1 to 10 without using **.rept**:
1228 iif count <= 10, goto loop
1232 Switch to Jaguar GPU assembly mode. This directive must be used
1233 within the TEXT or DATA segments.
1235 No. Just... no. Don't ask about it. Ever.
1236 **.prgflags** *value*
1237 Sets ST executable .PRG field *PRGFLAGS* to *value*. *PRGFLAGS* is a bit field defined as follows:
1239 ============ ====== =======
1240 Definition Bit(s) Meaning
1241 ============ ====== =======
1242 PF_FASTLOAD 0 If set, clear only the BSS area on program load, otherwise clear the entire heap.
1243 PF_TTRAMLOAD 1 If set, the program may be loaded into alternative RAM, otherwise it must be loaded into standard RAM.
1244 PF_TTRAMMEM 2 If set, the program's Malloc() requests may be satisfied from alternative RAM, otherwise they must be satisfied from standard RAM.
1245 -- 3 Currently unused.
1246 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.
1247 -- 6-15 Currently unused.
1248 ============ ====== =======
1250 **.regequ** *expression*
1251 Essentially the same as **.EQUR.** Included for compatibility with the GASM
1254 Essentially the same as **.EQURUNDEF.** Included for compatibility with
1263 All of the standard Motorola 68000 mnemonics and addressing modes are supported;
1264 you should refer to **The Motorola M68000 Programmer's Reference Manual**
1265 for a description of the instruction set and the allowable addressing modes for each
1266 instruction. With one major exception (forward branches) the assembler performs
1267 all the reasonable optimizations of instructions to their short or address register
1270 Register names may be in upper or lower case. The alternate forms ``R0`` through
1271 ``R15`` may be used to specify ``D0`` through ``A7``. All register names are keywords, and
1272 may not be used as labels or symbols. None of the 68010 or 68020 register names
1273 are keywords (but they may become keywords in the future).
1278 ===================================== ===========================================
1279 Assembler Syntax Description
1280 ===================================== ===========================================
1281 *Dn* Data register direct
1282 *An* Address register direct
1283 (*An*) Address register indirect
1284 (*An*)+ Address register indirect postincrement
1285 -(*An*) Address register indirect predecrement
1286 *disp*\ (*An*) Address register indirect with displacement
1287 *bdisp*\ (*An*, *Xi*\ [.\ *size*]) Address register indirect indexed
1288 *abs*.w Absolute short
1289 *abs* Absolute (long or short)
1290 *abs*.l Forced absolute long
1291 *disp*\ (PC) Program counter with displacement
1292 *bdisp*\ (PC, *Xi*\ ) Program counter indexed
1294 ===================================== ===========================================
1298 Since RMAC is a one pass assembler, forward branches cannot be automatically
1299 optimized to their short form. Instead, unsized forward branches are assumed to
1300 be long. Backward branches are always optimized to the short form if possible.
1302 A table that lists "extra" branch mnemonics (common synonyms for the Motorola
1303 defined mnemonics) appears below.
1305 `Linker Constraints`_
1306 '''''''''''''''''''''
1307 It is not possible to make an external reference that will fix up a byte. For example:
1312 move.l frog(pc,d0),d1
1314 is illegal (and generates an assembly error) when frog is external, because the
1315 displacement occupies a byte field in the 68000 offset word, which the object file
1320 ============== ========
1321 Alternate name Becomes:
1322 ============== ========
1332 ============== ========
1334 `Optimizations and Translations`_
1335 '''''''''''''''''''''''''''''''''
1336 The assembler provides "creature comforts" when it processes 68000 mnemonics:
1338 o **CLR.x An** will really generate **SUB.x An,An**.
1340 o **ADD**, **SUB** and **CMP** with an address register will really generate **ADDA**,
1341 **SUBA** and **CMPA**.
1343 o The **ADD**, **AND**, **CMP**, **EOR**, **OR** and **SUB** mnemonics with immediate
1344 first operands will generate the "I" forms of their instructions (**ADDI**, etc.) if
1345 the second operand is not register direct.
1347 o All shift instructions with no count value assume a count of one.
1349 o **MOVE.L** is optimized to **MOVEQ** if the immediate operand is defined and
1350 in the range -128...127. However, **ADD** and **SUB** are never translated to
1351 their quick forms; **ADDQ** and **SUBQ** must be explicit.
1353 o In GPU/DSP code sections, you can use JUMP (Rx) in place of JUMP T, (Rx) and JR
1354 (Rx) in place of JR T,(Rx).
1355 o RMAC tests all GPU/DSP restrictions and corrects them wherever possible (such as
1356 inserting a NOP instruction when needed).
1357 o The “(Rx+N)” addressing mode for GPU/DSP instructions is optimized to “(Rx)”
1362 `Macro declaration`_
1363 ''''''''''''''''''''
1364 A macro definition is a series of statements of the form:
1367 .macro name [ formal-arg, ...]
1371 statements making up the macro body
1377 The name of the macro may be any valid symbol that is not also a 68000 instruction
1378 or an assembler directive. (The name may begin with a period - macros cannot
1379 be made confined the way labels or equated symbols can be). The formal argument
1380 list is optional; it is specified with a comma-seperated list of valid symbol names.
1381 Note that there is no comma between the name of the macro and the name of the
1382 first formal argument.
1384 A macro body begins on the line after the **.macro** directive. All instructions
1385 and directives, except other macro definitions, are legal inside the body.
1387 The macro ends with the **.endm** statement. If a label appears on the line with
1388 this directive, the label is ignored and a warning is generated.
1390 `Parameter Substitution`_
1391 '''''''''''''''''''''''''
1392 Within the body, formal parameters may be expanded with the special forms:
1398 The second form (enclosed in braces) can be used in situations where the characters
1399 following the formal parameter name are valid symbol continuation characters. This
1400 is usually used to force concatentation, as in:
1405 \(godzilla}vs\{reagan}
1407 The formal parameter name is terminated with a character that is not valid in
1408 a symbol (e.g. whitespace or puncuation); optionally, the name may be enclosed in
1409 curly-braces. The names must be symbols appearing on the formal argument list,
1410 or a single decimal digit (``\1`` corresponds to the first argument, ``\2`` to the second,
1411 ``\9`` to the ninth, and ``\0`` to the tenth). It is possible for a macro to have more than
1412 ten formal arguments, but arguments 11 and on must be referenced by name, not
1415 Other special forms are:
1417 ============ ================================================
1418 Special Form Description
1419 ============ ================================================
1420 ``\\`` a single "\",
1421 ``\~`` a unique label of the form "Mn"
1422 ``\#`` the number of arguments actually specified
1423 ``\!`` the "dot-size" specified on the macro invocation
1424 ``\?name`` conditional expansion
1425 ``\?{name}`` conditional expansion
1426 ============ ================================================
1428 The last two forms are identical: if the argument is specified and is non-empty, the
1429 form expands to a "1", otherwise (if the argument is missing or empty) the form
1432 The form "``\!``" expands to the "dot-size" that was specified when the macro
1433 was invoked. This can be used to write macros that behave differently depending
1434 on the size suffix they are given, as in this macro which provides a synonym for the
1439 .macro deposit value
1442 deposit.b 1 ; byte of 1
1443 deposit.w 2 ; word of 2
1444 deposit.l 3 ; longvord of 3
1445 deposit 4 ; word of 4 (no explicit size)
1449 A previously-defined macro is called when its name appears in the operation field of
1450 a statement. Arguments may be specified following the macro name; each argument
1451 is seperated by a comma. Arguments may be empty. Arguments are stored for
1452 substitution in the macro body in the following manner:
1454 o Numbers are converted to hexadecimal.
1456 o All spaces outside strings are removed.
1458 o Keywords (such as register names, dot sizes and "^^" operators) are converted
1461 o Strings are enclosed in double-quote marks (").
1463 For example, a hypothetical call to the macro "``mymacro``", of the form:
1464 ``mymacro A0, , 'Zorch' / 32, "^^DEFINED foo, , , tick tock``
1466 will result in the translations:
1468 ======== ================= =================================================
1469 Argument Expansion Comment
1470 ======== ================= =================================================
1471 ``\1`` ``a0`` "``A0``" converted to lower-case
1473 ``\3`` ``"Zorch"/$20`` "``Zorch``" in double-quotes, 32 in hexadecimal
1474 ``\4`` ``^^defined foo`` "``^^DEFINED``" converted to lower-case
1477 ``\7`` ``ticktock`` spaces removed (note concatenation)
1478 ======== ================= =================================================
1480 The **.exitm** directive will cause an immediate exit from a macro body. Thus
1481 the macro definition:
1486 .iif !\?source, .exitm ; exit if source is empty
1487 move \source,d0 ; otherwise, deposit source
1490 will not generate the move instruction if the argument **"source"** is missing from
1491 the macro invocation.
1493 The **.end**, **.endif** and **.exitm** directives all pop-out of their include levels
1494 appropriately. That is, if a macro performs a **.include** to include a source file, an
1495 executed **.exitm** directive within the include-file will pop out of both the include-file
1498 Macros may be recursive or mutually recursive to any level, subject only to
1499 the availability of memory. When writing recursive macros, take care in the coding
1500 of the termination condition(s). A macro that repeatedly calls itself will cause the
1501 assembler to exhaust its memory and abort the assembly.
1506 The Gemdos macro is used to make file system calls. It has two parameters, a
1507 function number and the number of bytes to clean off the stack after the call. The
1508 macro pushes the function number onto the stack and does the trap to the file
1509 system. After the trap returns, conditional assembly is used to choose an addq or
1510 an **add.w** to remove the arguments that were pushed.
1514 .macro Gemdos trpno, clean
1515 move.w #\trpno,-(sp) ; push trap number
1516 trap #1 ; do GEMDOS trap
1518 addq #\clean,sp ; clean-up up to 8 bytes
1520 add.w #\clean,sp ; clean-up more than 8 bytes
1524 The Fopen macro is supplied two arguments; the address of a filename, and
1525 the open mode. Note that plain move instructions are used, and that the caller of
1526 the macro must supply an appropriate addressing mode (e.g. immediate) for each
1531 .macro Fopen file, mode
1532 movs.w \mode,-(sp) ;push open mode
1533 move.1 \file,-(sp) ;push address of tile name
1534 Gemdos $3d,8 ;do the GEMDOS call
1537 The **String** macro is used to allocate storage for a string, and to place the
1538 string's address somewhere. The first argument should be a string or other expres-
1539 sion acceptable in a dc.b directive. The second argument is optional; it specifies
1540 where the address of the string should be placed. If the second argument is omitted,
1541 the string's address is pushed onto the stack. The string data itself is kept in the
1546 .macro String str,loc
1547 .if \?loc ; if loc is defined
1548 move.l #.\~,\loc ; put the string's address there
1550 pea .\~ ; push the string's address
1552 .data ; put the string data
1553 .\~: dc.b \str,0 ; in the data segment
1554 .text ; and switch back to the text segment
1557 The construction "``.\~``" will expand to a label of the form "``.M``\ *n*" (where *n* is
1558 a unique number for every macro invocation), which is used to tag the location of
1559 the string. The label should be confined because the macro may be used along with
1560 other confined symbols.
1562 Unique symbol generation plays an important part in the art of writing fine
1563 macros. For instance, if we needed three unique symbols, we might write "``.a\~``",
1564 "``.b\~``" and "``.c\~``".
1568 Repeat-blocks provide a simple iteration capability. A repeat block allows a range
1569 of statements to be repeated a specified number of times. For instance, to generate
1570 a table consisting of the numbers 255 through 0 (counting backwards) you could
1575 .count set 255 ; initialize counter
1576 .rept 256 ; repeat 256 times:
1577 dc.b .count ; deposit counter
1578 .count set .count - 1 ; and decrement it
1579 .endr ; (end of repeat block)
1581 Repeat blocks can also be used to duplicate identical pieces of code (which are
1582 common in bitmap-graphics routines). For example:
1586 .rept 16 ; clear 16 words
1587 clr.w (a0)+ ; starting at AO
1590 `Jaguar GPU/DSP Mode`_
1591 ======================
1593 RMAC will generate code for the Atari jaguar GPU and DSP custom RISC (Reduced
1594 Instruction Set Computer) processors. See the Atari Jaguar Software reference Manual "Tom
1595 & Jerry" for a complete listing of Jaguar GPU and DSP assembler mnemonics and addressing
1600 The following condition codes for the GPU/DSP JUMP and JR instructions are built-in:
1604 CC (Carry Clear) = %00100
1605 CS (Carry Set) = %01000
1608 NE (Not Equal) = %00001
1610 HI (Higher) = %00101
1616 RMAC will generate code for the Motorola 6502 microprocessor. This chapter
1617 describes extra addressing modes and directives used to support the 6502.
1619 As the 6502 object code is not linkable (currently there is no linker) external
1620 references may not be made. (Nevertheless, RMAC may reasonably be used for
1621 large assemblies because of its blinding speed.)
1623 `6502 Addressing Modes`_
1624 ''''''''''''''''''''''''
1625 All standard 6502 addressing modes are supported, with the exception of the
1626 accumulator addressing form, which must be omitted (e.g. "ror a" becomes "ror").
1627 Five extra modes, synonyms for existing ones, are included for compatibility with
1628 the Atari Coinop assembler.
1630 ============== ========================================
1631 *empty* implied or accumulator (e.g. tsx or ror)
1632 *expr* absolute or zeropage
1634 #<\ *expr* immediate low byte of a word
1635 #>\ *expr* immediate high byte of a word
1636 (*expr*,x) indirect X
1637 (*expr*),y indirect Y
1641 @\ *expr*\ (x) indirect X
1642 @\ *expr*\ (y) indirect Y
1644 x,\ *expr* indexed X
1645 y,\ *expr* indexed Y
1646 ============== ========================================
1651 This directive enters the 6502 section. The location counter is undefined, and
1652 must be set with ".org" before any code can be generated.
1654 The "``dc.w``" directive will produce 6502-format words (low byte first). The
1655 68000's reserved keywords (``d0-d7/a0-a7/ssp/usp`` and so on) remain reserved
1656 (and thus unusable) while in the 6502 section. The directives **globl**, **dc.l**,
1657 **dcb.l**, **text**, **data**, **bss**, **abs**, **even** and **comm** are illegal in the 6502 section.
1658 It is permitted, though probably not useful, to generate both 6502 and 68000
1659 code in the same object file.
1661 This directive leaves the 6502 segment and returns to the 68000's text segment.
1662 68000 instructions may be assembled as normal.
1664 This directive is only legal in the 6502 section. It sets the value of the location
1665 counter (or **pc**) to location, an expression that must be defined, absolute, and
1670 It is possible to assemble "beyond" the microprocessor's 64K address space, but
1671 attempting to do so will probably screw up the assembler. DO NOT attempt
1672 to generate code like this:
1681 the third NOP in this example, at location $10000, may cause the assembler
1682 to crash or exhibit spectacular schizophrenia. In any case, RMAC will give
1683 no warning before flaking out.
1685 `6502 Object Code Format`_
1686 ''''''''''''''''''''''''''
1687 Traditionally Madmac had a very kludgy way of storing object files. This has been
1688 replaced with a more standard *.exe* (or *.com* or *.xex* if you prefer). Briefly,
1689 the *.exe* format consists of chunks of this format (one after the other):
1694 00-01 $FFFF - Indicates a binary load file. Mandatory for first segment, optional for any other segment
1695 02-03 Start Address. The segment will load at this address
1696 04-05 End Address. The last byte to load for this segment
1697 06-.. The actual segment data to load (End Address-Start Address + 1 bytes)
1702 `When Things Go Wrong`_
1703 '''''''''''''''''''''''
1704 Most of RMAC's error messages are self-explanatory. They fall into four classes:
1705 warnings about situations that you (or the assembler) may not be happy about,
1706 errors that cause the assembler to not generate object files, fatal errors that cause
1707 the assembler to abort immediately, and internal errors that should never happen.\ [3]_
1709 You can write editor macros (or sed or awk scripts) to parse the error messages
1710 RMAC generates. When a message is printed, it is of the form:
1712 "*filename*" , ``line`` *line-number*: *message*
1714 The first element, a filename enclosed in double quotes, indicates the file that generated
1715 the error. The filename is followed by a comma, the word "``line``", and a line
1716 number, and finally a colon and the text of the message. The filename "**(\*top\*)**"
1717 indicates that the assembler could not determine which file had the problem.
1719 The following sections list warnings, errors and fatal errors in alphabetical
1720 order, along with a short description of what may have caused the problem.
1722 .. [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.
1726 **bad backslash code in string**
1727 You tried to follow a backslash in a string with a character that the assembler
1728 didn't recognize. Remember that RMAC uses a C-style escape system in
1731 You specified a label before a macro, **rept** or **endm** directive. The assembler
1732 is warning you that the label will not be defined in the assembly.
1733 **unoptimized short branch**
1734 This warning is only generated if the -s switch is specified on the command
1735 line. The message refers to a forward, unsized long branch that you could have
1742 As a result of previous errors, the assembler cannot continue processing. The
1743 assembly is aborted.
1744 **line too long as a result of macro expansion**
1745 When a source line within a macro was expanded, the resultant line was too
1746 long for RMAC (longer than 200 characters or so).
1749 **memory exhausted**
1750 The assembler ran out of memory. You should (1) split up your source files
1751 and assemble them seperately, or (2) if you have any ramdisks or RAM-resident
1752 programs (like desk accessories) decrease their size so that the assembler has
1753 more RAM to work with. As a rule of thumb, pure 68000 code will use up to
1754 twice the number of bytes contained in the source files, whereas 6502 code will
1755 use 64K of ram right away, plus the size of the source files. The assembler itself
1756 uses about 80K bytes. Get out your calculator...
1758 The assembler ran across an **endm** directive when it wasn't expecting to see
1759 one. The assembly is aborted. Check the nesting of your macro definitions -
1760 you probably have an extra **endm**.
1767 Syntax error in **.cargs** directive.
1768 **.comm symbol already defined**
1769 You tried to ``.comm`` a symbol that was already defined.
1770 **.ds permitted only in BSS**
1771 You tried to use ``.ds`` in the text or data section.
1772 **.init not permitted in BSS or ABS**
1773 You tried to use ``.init`` in the BSS or ABS section.
1774 **.org permitted only in .6502 section**
1775 You tried to use ``.org`` in a 68000 section.
1776 **Cannot create:** *filename*
1777 The assembler could not create the indicated filename.
1778 **External quick reference**
1779 You tried to make the immediate operand of a **moveq**, **subq** or **addq** instruction external.
1780 **PC-relative expr across sections**
1781 You tried to make a PC-relative reference to a location contained in another
1783 **[bwsl] must follow '.' in symbol**
1784 You tried to follow a dot in a symbol name with something other than one of
1785 the four characters 'B', 'W', 'S' or 'L'.
1786 **addressing mode syntax**
1787 You made a syntax error in an addressing mode.
1789 One of your **.assert** directives failed!
1790 **bad (section) expression**
1791 You tried to mix and match sections in an expression
1792 **bad 6502 addressing mode**
1793 The 6502 mnemonic will not work with the addressing mode you specified.
1795 There's a syntax error in the expression you typed.
1796 **bad size specified**
1797 You tried to use an inappropriate size suffix for the instruction. Check your
1798 68000 manual for allowable sizes.
1800 You can't use .b (byte) mode with the **movem** instruction.
1801 **cannot .globl local symbol**
1802 You tried to make a confined symbol global or common.
1803 **cannot initialize non-storage (BSS) section**
1804 You tried to generate instructions (or data, with dc) in the BSS or ABS section.
1805 **cannot use '.b' with an address register**
1806 You tried to use a byte-size suffix with an address register. The 68000 does not
1807 perform byte-sized address register operations.
1808 **directive illegal in .6502 section**
1809 You tried to use a 68000-oriented directive in the 6502 section.
1811 The expression you typed involves a division by zero.
1812 **expression out of range**
1813 The expression you typed is out of range for its application.
1814 **external byte reference**
1815 You tried to make a byte-sized reference to an external symbol, which the
1816 object file format will not allow
1817 **external short branch**
1818 You tried to make a short branch to an external symbol, which the linker cannot
1820 **extra (unexpected) text found after addressing mode**
1821 RMAC thought it was done processing a line, but it ran up against "extra"
1822 stuff. Be sure that any comment on the line begins with a semicolon, and check
1823 for dangling commas, etc.
1824 **forward or undefined .assert**
1825 The expression you typed after a **.assert** directive had an undefined value.
1826 Remember that RMAC is one-pass.
1827 **hit EOF without finding matching .endif**
1828 The assembler fell off the end of last input file without finding a **.endif** to
1829 match an . it. You probably forgot a **.endif** somewhere.
1830 **illegal 6502 addressing mode**
1831 The 6502 instruction you typed doesn't work with the addressing mode you
1833 **illegal absolute expression**
1834 You can't use an absolute-valued expression here.
1835 **illegal bra.s with zero offset**
1836 You can't do a short branch to the very next instruction (read your 68000
1838 **illegal byte-sized relative reference**
1839 The object file format does not permit bytes contain relocatable values; you
1840 tried to use a byte-sized relocatable expression in an immediate addressing
1842 **illegal character**
1843 Your source file contains a character that RMAC doesn't allow. (most
1844 control characters fall into this category).
1845 **illegal initialization of section**
1846 You tried to use .dc or .dcb in the BSS or ABS sections.
1847 **illegal relative address**
1848 The relative address you specified is illegal because it belongs to a different
1850 **illegal word relocatable (in .PRG mode)**
1851 You can't have anything other than long relocatable values when you're gener-
1852 ating a **.PRG** file.
1853 **inappropriate addressing mode**
1854 The mnemonic you typed doesn't work with the addressing modes you specified.
1855 Check your 68000 manual for allowable combinations.
1856 **invalid addressing mode**
1857 The combination of addressing modes you picked for the **movem** instruction
1858 are not implemented by the 68000. Check your 68000 reference manual for
1860 **invalid symbol following ^^**
1861 What followed the ^^ wasn't a valid symbol at all.
1862 **mis-nested .endr**
1863 The assembler found a **.endr** directive when it wasn't prepared to find one.
1864 Check your repeat-block nesting.
1865 **mismatched .else**
1866 The assembler found a **.else** directive when it wasn't prepared to find one.
1867 Check your conditional assembly nesting.
1868 **mismatched .endif**
1869 The assembler found a **.endif** directive when it wasn't prepared to find one.
1870 Check your conditional assembly nesting.
1876 **missing argument name**
1878 **missing close parenthesis ')'**
1880 **missing close parenthesis ']'**
1884 **missing filename**
1890 **missing symbol or string**
1891 The assembler expected to see a symbol/filename/string (etc...), but found
1892 something else instead. In most cases the problem should be obvious.
1893 **misuse of '.', not allowed in symbols**
1894 You tried to use a dot (.) in the middle of a symbol name.
1896 The expression you typed involves a modulo by zero.
1897 **multiple formal argument definition**
1898 The list of formal parameter names you supplied for a macro definition includes
1899 two identical names.
1900 **multiple macro definition**
1901 You tried to define a macro which already had a definition.
1902 **non-absolute byte reference**
1903 You tried to make a byte reference to a relocatable value, which the object file
1904 format does not allow.
1905 **non-absolute byte value**
1906 You tried to dc.b or dcb.b a relocatable value. Byte relocatable values are
1907 not permitted by the object file format.
1908 **register list order**
1909 You tried to specify a register list like **D7-D0**, which is illegal. Remember
1910 that the first register number must be less than or equal to the second register
1912 **register list syntax**
1913 You made an error in specifying a register list for a **.reg** directive or a **.movem**
1915 **symbol list syntax**
1916 You probably forgot a comma between the names of two symbols in a symbol
1917 list, or you left a comma dangling on the end of the line.
1919 This is a "catch-all" error.
1920 **undefined expression**
1921 The expression has an undefined value because of a forward reference, or an
1922 undefined or external symbol.
1923 **unimplemented addressing mode**
1924 You tried to use 68020 "square-bracket" notation for a 68020 addressing mode.
1925 RMAC does not support 68020 addressing modes.
1926 **unimplemented directive**
1927 You have found a directive that didn't appear in the documentation. It doesn't
1929 **unimplemented mnemonic**
1930 You've found an assembler for documentation) bug.
1931 **unknown symbol following ^^**
1932 You followed a ^^ with something other than one of the names defined, ref-
1934 **unsupported 68020 addressing mode**
1935 The assembler saw a 68020-type addressing mode. RMAC does not assem-
1936 ble code for the 68020 or 68010.
1937 **unterminated string**
1938 You specified a string starting with a single or double quote, but forgot to type
1941 The assembler had a problem writing an object file. This is usually caused by
1942 a full disk, or a bad sector on the media.