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-2015, 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 This manual was typeset with TEX and the Computer Modern fonts, and it
56 was printed on the Atari SLM-804 laser printer with a MEGA ST. Except for 200
57 lines of assembly language, the assembler is written entirely in C.
59 .. [1] It processes 30,000 lines a minute on a lightly loaded VAX 11/780; maybe 40,000 on a 520-ST with an SH-204 hard disk. Yet it could be sped up even more with some effort and without resorting to assembly language; C doesn't have to be slow!
64 =>Write protect your distribution disk and make a backup of it now. Put the
65 original disk in a safe place.
67 * The distribution disk contains a file called README that you should read.
68 This file contains important nays about the contents of the distribution disk
69 and summarizes the most recent changes to the tools.
71 * Hard disk users can simply copy the executable files to their work or binary
72 directories. People with floppy disks can copy the executables to ramdisks,
73 install the assembler with the -q option, or even work right off of the floppies.
75 * You will need an editor that can produce "normal" format text files. Micro
76 Emacs will work well, as will most other commercial program editors, but not
77 most word processors (such as First Word or Microsoft Write).
79 * You will probably want to examine or get a listing of the file "ATARI.S". It
80 contains lots of definitions for the Atari ST, including BIOS variables, most
81 BIOS, XBIOS and GEMDOS traps, and line-A equates. We (or you) could
82 split the file up into pieces (a file for line-A equates, a file for hardware and
83 BIOS variables and so on), but RMAC is so fast that it doesn't matter
86 * Read the rest of the manual, especially the first two chapters on The Command Line and Using RMAC.
87 Also, `Notes for migrating from other 68000 assemblers`_ will save a lot of time and frustration in the long run.
88 The distribution disk contains example
89 programs that you can look at, assemble and modify.
94 The assembler is called "**rmac**" or "**rmac.prg**". The command line takes the form:
96 **mac** [*switches*] [*files* ...]
98 A command line consists of any number of switches followed by the names of files
99 to assemble. A switch is specified with a dash (**-**) followed immediately by a key
100 character. Key characters are not case-sensitive, so "**-d**" is the same as "**-D**". Some
101 switches accept (or require) arguments to immediately follow the key character,
102 with no spaces in between.
104 Switch order is important. Command lines are processed from left to right in
105 one pass, and switches usually take effect when they are encountered. In general it
106 is best to specify all switches before the names of any input files.
108 If the command line is entirely empty then RMAC prints a copyright message
109 and enters an "interactive" mode, prompting for successive command lines
110 with a star (\*). An empty command line will exit (See the examples in the chapter
111 on `Using RMAC`_). After each assembly in interactive mode, the assembler
112 will print a summary of the amount of memory used, the amount of memory left,
113 the number of lines processed, and the number of seconds the assembly took.
115 Input files are assumed to have the extension "**.s**"; if a filename has no extension
116 (i.e. no dot) then "**.s**" will be appended to it. More than one source filename may be
117 specified: the files are assembled into one object file, as if they were concatenated.
119 RMAC normally produces object code in "**file.o**" if "**file.s**" is the first
120 input filename. If the first input file is a special character device, the output name
121 is noname.o. The **-o** switch (see below) can be used change the output file name.
124 =================== ===========
126 =================== ===========
127 -dname\ *[=value]* Define symbol, with optional value.
128 -e\ *[file[.err]]* Direct error messages to the specified file.
131 -i\ *path* Set include-file directory search path.
132 -l\ *[file[prn]]* Construct and direct assembly listing to the specified file.
133 -o\ *file[.o]* Direct object code output to the specified file.
134 -p Produce an executable (**.prg**) output file.
135 -ps Produce an executable (**.prg**) output file with symbols.
136 -q Make RMAC resident in memory (Atari ST only).
137 -r *size* automatically pad the size of each
138 segment in the output file until the size is an integral multiple of the
139 specified boundary. Size is a letter that specifies the desired boundary.
141 `-rw Word (2 bytes, default alignment)`
145 `-rp Phrase (8 bytes)`
147 `-rd Double Phrase (16 bytes)`
149 `-rq Quad Phrase (32 bytes)`
150 -s Warn about unoptimized long branches.
151 -u Assume that all undefined symbols are external.
152 -v Verbose mode (print running dialogue).
153 -yn Set listing page size to n lines.
154 -6 "Back end" mode for Alcyon C68.
155 file\ *[s]* Assemble the specified file.
156 =================== ===========
158 The switches are described below. A summary of all the switches is given in
162 The **-d** switch permits symbols to be defined on the command line. The name
163 of the symbol to be defined immediately follows the switch (no spaces). The
164 symbol name may optionally be followed by an equals sign (=) and a decimal
165 number. If no value is specified the symbol's value is zero. The symbol at-
166 tributes are "defined, not referenced, and absolute". This switch is most useful
167 for enabling conditionally-assembled debugging code on the command line; for
172 -dDEBUG -dLoopCount=999 -dDebugLevel=55
175 The -e switch causes RMAC to send error messages to a file, instead of the
176 console. If a filename immediately follows the switch character, error messages
177 are written to the specified file. If no filename is specified, a file is created with
178 the default extension "**.err**" and with the root name taken from the first input
179 file name (e.g. error messages are written to "**file.err**" if "**file**" or "**file.s**" is
180 the first input file name). If no errors are encountered, then no error listing
181 file is created. Beware! If an assembly produces no errors, any error file from
182 a previous assembly is not removed.
185 The **-i** switch allows automatic directory searching for include files. A list of
186 semi-colon seperated directory search paths may be mentioned immediately
187 following the switch (with no spaces anywhere). For example:
191 -im:;c:include;c:include\sys
193 will cause the assembler to search the current directory of device **M**, and the
194 directories include and include\sys on drive **C**. If *-i* is not specified, and the
195 enviroment variable "**MACPATH**" exists, its value is used in the same manner.
196 For example, users of the Mark Williams shell could put the following line in
197 their profile script to achieve the same result as the **-i** example above:
201 setenv MACPATH="m:;c:include;c:include\sys"
203 The -l switch causes RMAC to generate an assembly listing file. If a file-
204 name immediately follows the switch character, the listing is written to the
205 specified file. If no filename is specified, then a listing file is created with the
206 default extension "**.prn**" and with the root name taken from the first input file
207 name (e.g. the listing is written to "**file.prn**" if "**file**" or "**file.s**" is the first
210 The -o switch causes RMAC to write object code on the specified file. No
211 default extension is applied to the filename. For historical reasons the filename
212 can also be seperated from the switch with a space (e.g. "**-o file**").
217 The **-p** and **-ps** switches cause RMAC to produce an Atari ST executable
218 file with the default extension of "**.prg**". If there are any external references
219 at the end of the assembly, an error message is emitted and no executable file
220 is generated. The **-p** switch does not write symbols to the executable file. The
221 **-ps** switch includes symbols (Alcyon format) in the executable file.
223 The **-q** switch is aimed primarily at users of floppy-disk-only systems. It causes
224 RMAC to install itself in memory, like a RAMdisk. Then the program
225 **m.prg** (which is very short - less than a sector) can be used instead of
226 **mac.prg**, which can take ten or twelve seconds to load. (**NOTE** not available
227 for now, might be re-implemented in the future).
229 The **-s** switch causes RMAC to generate a list of unoptimized forward
230 branches as warning messages. This is used to point out branches that could
231 have been short (e.g. "bra" could be "bra.s").
233 The **-u** switch takes effect at the end of the assembly. It forces all referenced
234 and undefined symbols to be global, exactly as if they had been made global
235 with a **.extern** or **.globl** directive. This can be used if you have a lot of
236 external symbols, and you don't feel like declaring them all external.
238 The **-v** switch turns on a "verbose" mode in which RMAC prints out (for
239 example) the names of the files it is currently processing. Verbose mode is
240 automatically entered when RMAC prompts for input with a star.
242 The **-y** switch, followed immediately by a decimal number (with no intervening
243 space), sets the number of lines in a page. RMAC will produce *N* lines
244 before emitting a form-feed. If *N* is missing or less than 10 an error message is
250 Let's assemble and link some example programs. These programs are included
251 on the distribution disk in the "**EXAMPLES**" directory - you should copy them to
252 your work area before continuing. In the following examples we adopt the conven-
253 tions that the shell prompt is a percent sign (%) and that your input (the stuff you
254 type) is presented in **bold face**.
256 If you have been reading carefully, you know that RMAC can generate
257 an executable file without linking. This is useful for making small, stand alone
258 programs that don't require externals or library routines. For example, the following
266 could be replaced by the single command:
272 since you don't need the linker for stand-alone object files.
274 Successive source files named in the command line are are concatenated, as in
275 this example, which assembles three files into a single executable, as if they were
280 % rmac -p bugs shift images
282 Of course you can get the same effect by using the **.include** directive, but sometimes
283 it is convenient to do the concatenation from the command line.
285 Here we have an unbelievably complex command line:
289 % rmac -lzorf -y95 -o tmp -ehack -Ddebug=123 -ps example
291 This produces a listing on the file called "**zorf.prn**" with 95 lines per page, writes
292 the executable code (with symbols) to a file called "**tmp.prg**", writes an error listing
293 to the file "**hack.err**", specifies an include-file path that includes the current
294 directory on the drive "**M:**," defines the symbol "**debug**" to have the value 123, and
295 assembles the file "**example.s**". (Take a deep breath - you got all that?)
297 One last thing. If there are any assembly errors, RMAC will terminate
298 with an exit code of 1. If the assembly succeeds (no errors, although there may be
299 warnings) the exit code will be 0. This is primarily for use with "make" utilities.
303 If you invoke RMAC with an empty command line it will print a copyright
304 message and prompt you for more commands with a star (*****). This is useful if you
305 are used to working directly from the desktop, or if you want to assemble several files
306 in succession without having to reload the assembler from disk for each assembly.
308 In interactive mode, the assembler is also in verbose mode (just as if you had
309 specified **-v** on each command line):
315 MADMAC Atari Macro Assembler
316 Copyright 1987 Atari Corporation
317 Beta version 0.12 Jun 1987 lmd
320 [Including: example.s]
323 [Leaving; example. a]
324 [Writing executable tile: example.prg
325 36K used, 3868K left, 850 lines, 2.0 seconds
328 You can see that the assembler gave a "blow-by-blow" account of the files it processed,
329 as well as a summary of the assembly's memory usage, the number of lines
330 processed (including macro and repeat-block expansion), and how long the assembly
333 The assembler prompts for another command with the star. At this point you
334 can either type a new command line for the assembler to process, or you can exit
335 by typing control-C or an empty line.
337 Things You Should Be Aware Of
338 '''''''''''''''''''''''''''''
339 RMAC is a one pass assembler. This means that it gets all of its work done by
340 reading each source file exactly once and then "back-patching" to fix up forward
341 references. This one-pass nature is usually transparent to the programmer, with
342 the following important exceptions:
344 o in listings, the object code for forward references is not shown. Instead, lower-
345 case "xx"s are displayed for each undefined byte, as in the following example:
349 60xx 1: bra.s.2 ;forward branch
350 xxxxxxxx dc.l .2 ;forward reference
351 60FE .2: bra.s.2 ;backward reference
353 o Forward branches (including **BSR**\s) are never optimized to their short forms.
354 To get a short forward branch it is necessary to explicitly use the ".s" suffix in
356 o Error messages may appear at the end of the assembly, referring to earlier source
357 lines that contained undefined symbols.
358 o All object code generated must fit in memory. Running out of memory is a
359 fatal error that you must deal with by splitting up your source files, re-sizing
360 or eliminating memory-using programs such as ramdisks and desk accessories,
365 RMAC does not optimize forward branches for you, but it will tell you about
366 them if you use the -s (short branch) option:
371 "example.s", line 20: warning: unoptimized short branch
373 With the -e option you can redirect the error output to a file, and determine by
374 hand (or editor macros) which forward branches are safe to explicitly declare short.
376 `Notes for migrating from other 68000 assemblers`_
377 ''''''''''''''''''''''''''''''''''''''''''''''''''
378 RMAC is not entirely compatible with the other popular assemblers
379 like Devpac or vasm. This section
380 outlines the major differences. In practice, we have found that very few changes are
381 necessary to make other assemblers' source code assemble.
383 o A semicolon (;) must be used to introduce a comment, except that a star (*)
384 may be used in the first column. AS68 treated anything following the operand
385 field, preceeded by whitespace, as a comment. (RMAC treats a star that
386 is not in column 1 as a multiplication operator).
388 o Labels require colons (even labels that begin in column 1).
390 o Conditional assembly directives are called **if**, **else** and **endif**. Devpac and vasm called these
391 **ifne**, **ifeq** (etc.), and **endc**.
392 o The tilde (~) character is an operator, and back-quote (`) is an illegal character.
393 AS68 permitted the tilde and back-quote characters in symbols.
394 o There are no equivalents to org or section directives.
395 The **.xdef** and **.xref** directives are not implemented,
396 but **.globl** makes these unnecessary anyway.
398 o The location counter cannot be manipulated with a statement of the form:
404 o The **ds** directive is not permitted in the text or data segments;
405 an error message is issued. Use **dcb** instead to reserve large blocks of
407 o Back-slashes in strings are "electric" characters that are used to escape C-like
408 character codes. Watch out for GEMDOS path names in ASCII constants -
409 you will have to convert them to double-backslashes.
410 o Expression evaluation is done left-to-right without operator precedence. Use parentheses to
411 force the expression evaluation as you wish.
413 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"
414 o rs.b/rs.w/rs.l/rscount/rsreset can be simulated in rmac using abs. For example the following source:
424 size_so_far equ rscount
436 size_so_far equ ^^abscount
438 o A rare case: if your macro contains something like:
448 then by the assembler's design this will fail as the parameters are automatically converted to hex. Changing the code like his works:
460 For those using editors other than the "Emacs" style ones (Micro-Emacs, Mince,
461 etc.) this section documents the source file format that RMAC expects.
463 o Files must contain characters with ASCII values less than 128; it is not per-
464 missable to have characters with their high bits set unless those characters are
465 contained in strings (i.e. between single or double quotes) or in comments.
467 o Lines of text are terminated with carriage-return/line-feed, linefeed alone, or
468 carriage-return alone.
470 o The file is assumed to end with the last terminated line. If there is text beyond
471 the last line terminator (e.g. control-Z) it is ignored.
478 A statement may contain up to four fields which are identified by order of ap-
479 pearance and terminating characters. The general form of an assembler statement
484 label: operator operand(s) ; comment
486 The label and comment fields are optional. An operand field may not appear
487 without an operator field. Operands are seperated with commas. Blank lines are
488 legal. If the first character on a line is an asterisk (*) or semicolon (;) then the
489 entire line is a comment. A semicolon anywhere on the line (except in a string)
490 begins a comment field which extends to the end of the line.
492 The label, if it appears, must be terminated with a single or double colon. If
493 it is terminated with a double colon it is automatically declared global. It is illegal
494 to declare a confined symbol global (see: `Symbols and Scope`_).
498 A statement may also take one of these special forms:
500 *symbol* **equ** *expression*
502 *symbol* **=** *expression*
504 *symbol* **--** *expression*
506 *symbol* **set** *expression*
508 *symbol* **reg** *register list*
510 The first two forms are identical; they equate the symbol to the value of an
511 expression, which must be defined (no forward references). The third form, double-
512 equals (==), is just like an equate except that it also makes the symbol global. (As
513 with labels, it is illegal to make a confined equate global.) The fourth form allows
514 a symbol to be set to a value any number of times, like a variable. The last form
515 equates the symbol to a 16-bit register mask specified by a register list. It is possible
516 to equate confined symbols (see: `Symbols and Scope`_). For example:
520 cr equ 13 carriage-return
522 DEBUG == 1 global debug flag
524 count set count + 1 increment variable
525 .rags reg d3-d7/a3-a6 register list
526 .cr 13 confined equate
530 Symbols may start with an uppercase or lowercase letter (A-Z a-z), an underscore
531 (**_**), a question mark (**?**) or a period (**.**). Each remaining character may be an
532 upper or lowercase letter, a digit (**0-9**), an underscore, a dollar sign (**$**), or a question
533 mark. (Periods can only begin a symbol, they cannot appear as a symbol
534 continuation character). Symbols are terminated with a character that is not a
535 symbol continuation character (e.g. a period or comma, whitespace, etc.). Case is
536 significant for user-defined symbols, but not for 68000 mnemonics, assembler direc-
537 tives and register names. Symbols are limited to 100 characters. When symbols
538 are written to the object file they are silently truncated to eight (or sixteen) char-
539 acters (depending on the object file format) with no check for (or warnings about)
542 For example, all of the following symbols are legal and unique:
546 reallyLougSymbolliame .reallyLongConfinadSymbollame
547 al0 ret move dc frog aae a9 ????
548 .al .ret .move .dc .frog .a9 .9 ????
549 .0 .00 .000 .1 .11. .111 . ._
550 _frog ?zippo? sys$syetem atari Atari ATARI aTaRi
552 while all of the following symbols are illegal:
556 12days dc.10 dc.z 'quote .right.here
557 @work hi.there $money$ ~tilde
560 Symbols beginning with a period (**.**) are *confined*; their scope is between two
561 normal (unconfined) labels. Confined symbols may be labels or equates. It is illegal
562 to make a confined symbol global (with the ".globl" directive, a double colon, or a
563 double equals). Only unconfined labels delimit a confined symbol's scope; equates
564 (of any kind) do not count. For example, all symbols are unique and have unique
565 values in the following:
576 .loop: move.w -1,(a0)+
580 Confined symbols are useful since the programmer has to be much less inventive
581 about finding small, unique names that also have meaning.
583 It is legal to define symbols that have the same names as processor mnemonics
584 (such as "**move**" or "**rts**") or assembler directives (such as "**.even**"). Indeed, one
585 should be careful to avoid typographical errors, such as this classic (in 6502 mode):
593 which equates a confined symbol to a hexadecimal value, rather than setting the
594 location counter, which the .org directive does (without the equals sign).
598 The following names, in all combinations of uppercase and lowercase, are keywords
599 and may not be used as symbols (e.g. labels, equates, or the names of macros):
605 dO di d2 d3 d4 d5 d6 d7
606 a0 al a2 a3 a4 a5 a6 aT
607 r0 ri r2 r3 r4 r5 r6 r7
608 r8 r9 r10 1'11 r12 rl3 ri4 ri5
612 Numbers may be decimal, hexadecimal, octal, binary or concatenated ASCII. The
613 default radix is decimal, and it may not be changed. Decimal numbers are specified
614 with a string of digits (**0-9**). Hexadecimal numbers are specified with a leading
615 dollar sign (**$**) followed by a string of digits and uppercase or lowercase letters (**A-F
616 a-f**). Octal numbers are specified with a leading at-sign (**@**) followed by a string
617 of octal digits (**0-7**). Binary numbers are specified with a leading percent sign
618 (**%**) followed by a string of binary digits (**0-1**). Concatenated ASCII constants are
619 specified by enclosing from one to four characters in single or double quotes. For
631 Negative numbers Are specified with a unary minus (**-**). For example:
640 Strings are contained between double (") or single ( ') quote marks. Strings may
641 contain non-printable characters by specifying "backslash" escapes, similar to the
642 ones used in the C programming language. RMAC will generate a warning if a
643 backslash is followed by a character not appearing below:
648 \n $0a line-feed (newline)
651 \r $0c1 carriage-return
657 It is possible for strings (but not symbols) to contain characters with their high
658 bits set (i.e. character codes 128...255).
660 You should be aware that backslash characters are popular in GEMDOS path
661 names, and that you may have to escape backslash characters in your existing source
662 code. For example, to get the file "'c:\auto\ahdi.s'" you would specify the string
663 "`c:\\auto\\ahdi.s`".
667 Register lists are special forms used with the **movem** mnemonic and the **.reg**
668 directive. They are 16-bit values, with bits 0 through 15 corresponding to registers
669 **D0** through **A7**. A register list consists of a series of register names or register
670 ranges seperated by slashes. A register range consists of two register names, Rm
671 and Rn,m<n, seperated by a dash. For example:
679 d0/d1/a0-a3/d7/a6-a7 $CF83
683 Register lists and register equates may be used in conjunction with the movem
684 mnemonic, as in this example:
688 temps reg d0-d2/a0-a2 ; temp registers
689 keeps reg d3-d7/d3-a6 ; registers to preserve
690 allregs reg d0-d7/a0-a7 ; all registers
691 movem.l #temps, -(sp) ; these two lines ...
692 aovea.l dO -d2/a0 -a2, -(sp) ; are identical
693 movea.l #keeps, -(sp) ; save "keep" registers
694 noven.1 (sp)+,#keeps ; restore "keep" registers
699 `Order of Evaluation`_
700 ''''''''''''''''''''''
701 All values are computed with 32-bit 2's complement arithmetic. For boolean operations
702 (such as if or **assert**) zero is considered false, and non-zero is considered
705 **Expressions are evaluated strictly left-to-right, with no
706 regard for operator precedence.**
708 Thus the expression "1+2*3" evaluates to 9, not 7. However, precedence may be
709 forced with parenthesis (**()**) or square-brackets (**[]**).
713 Expressions belong to one of three classes: undefined, absolute or relocatable. An
714 expression is undefined if it involves an undefined symbol (e.g. an undeclared sym-
715 bol, or a forward reference). An expression is absolute if its value will not change
716 when the program is relocated (for instance, the number 0, all labels declared in
717 an abs section, and all Atari ST hardware register locations are absolute values).
718 An expression is relocatable if it involves exactly one symbol that is contained in a
719 text, data or BSS section.
721 Only absolute values may be used with operators other than addition (+) or
722 subtraction (-). It is illegal, for instance, to multiply or divide by a relocatable or
723 undefined value. Subtracting a relocatable value from another relocatable value in
724 the same section results in an absolute value (the distance between them, positive
725 or negative). Adding (or subtracting) an absolute value to or from a relocatable
726 value yeilds a relocatable value (an offset from the relocatable address).
728 It is important to realize that relocatable values belong to the sections they
729 are defined in (e.g. text, data or BSS), and it is not permissible to mix and match
730 sections. For example, in this code:
734 linel: dc.l line2, linel+8
735 line2: dc.l linel, line2-8
736 line3: dc.l line2-linel, 8
737 error: dc.l linel+line2, line2 >> 1, line3/4
739 Line 1 deposits two longwords that point to line 2. Line 2 deposits two longwords
740 that point to line 1. Line 3 deposits two longwords that have the absolute value
741 eight. The fourth line will result in an assembly error, since the expressions (re-
742 spectively) attempt to add two relocatable values, shift a relocatable value right by
743 one, and divide a relocatable value by four.
745 The pseudo-symbol "*****" (star) has the value that the current section's location
746 counter had at the beginning of the current source line. For example, these two
747 statements deposit three pointers to the label "**bar**":
754 Similarly, the pseudo-symbol "**$**" has the value that the current section's location
755 counter has, and it is kept up to date as the assembler deposits information
756 "across" a line of source code. For example, these two statements deposit four
757 pointers to the label "zip":
767 ================================ ========================================
769 ================================ ========================================
770 **-** Unary minus (2's complement).
771 **!** Logical (boolean) NOT.
772 **~** Tilde: bitwise not (l's complement).
773 **^^defined** *symbol* True if symbol has a value.
774 **^^referenced** *symbol* True if symbol has been referenced.
775 **^^streq** *stringl*,*string2* True if the strings are equal.
776 **^^macdef** *macroName* True if the macro is defined.
777 **^^abscount** Returns the size of current .abs section
778 ================================ ========================================
780 o The boolean operators generate the value 1 if the expression is true, and 0 if
783 o A symbol is referenced if it is involved in an expression. A symbol may have
784 any combination of attributes: undefined and unreferenced, defined and unref-
785 erenced (i.e. declared but never used), undefined and referenced (in the case
786 of a forward or external reference), or defined and referenced.
793 =========== ==============================================
795 =========== ==============================================
796 \ + - * / The usual arithmetic operators.
798 & | ^ Bit-wise **AND**, **OR** and **Exclusive-OR**.
799 << >> Bit-wise shift left and shift right.
800 < <= >= > Boolean magnitude comparisons.
802 <> != Boolean inequality.
803 =========== ==============================================
805 o All binary operators have the same precedence: expressions are evaluated
806 strictly left to right.
808 o Division or modulo by zero yields an assembly error
810 o The "<>" and "!=" operators are synonyms.
812 o Note that the modulo operator (%) is also used to introduce binary constants
813 (see: `Constants`_). A percent sign should be followed by at least one space if
814 it is meant to be a modulo operator, and is followed by a '0' or '1'.
819 ============ =========================================
820 Special Form Description
821 ============ =========================================
822 **^^date** The current system date (Gemdos format).
823 **^^time** The current system time (Gemdos format).
824 ============ =========================================
826 o The "**^^date**" special form expands to the current system date, in Gemdos
827 format. The format is a 16-bit word with bits 0 ...4 indicating the day of the
828 month (1...31), bits 5...8 indicating the month (1...12), and bits 9...15
829 indicating the year since 1980, in the range 0...119.
831 o The "**^^time**" special form expands to the current system time, in Gemdos
832 format. The format is a 16-bit word with bits 0...4 indicating the current
833 second divided by 2, bits 5...10 indicating the current minute 0...59. and
834 bits 11...15 indicating the current hour 0...23.
836 `Example Expressions`_
837 ''''''''''''''''''''''
841 line address contents source code
842 ---- ------- -------- -------------------------------
843 1 00000000 4480 lab1: neg.l d0
844 2 00000002 427900000000 lab2: clr.w lab1
845 3 =00000064 equ1 = 100
846 4 =00000096 equ2 = equ1 + 50
847 5 00000008 00000064 dc.l lab1 + equ1
848 6 0000000C 7FFFFFE6 dc.l (equl + ~equ2) >> 1
849 7 00000010 0001 dc.w ^^defined equl
850 8 00000012 0000 dc.w ^^referenced lab2
851 9 00000014 00000002 dc.l lab2
852 10 00000018 0001 dc.w ^^referenced lab2
853 11 0000001A 0001 dc.w lab1 = (lab2 - 6)
855 Lines 1 through four here are used to set up the rest of the example. Line 5 deposits
856 a relocatable pointer to the location 100 bytes beyond the label "**lab1**". Line 6 is
857 a nonsensical expression that uses the and right-shift operators. Line 7 deposits
858 a word of 1 because the symbol "**equ1**" is defined (in line 3).
860 Line 8 deposits a word of 0 because the symbol "**lab2**", defined in line 2, has
861 not been referenced. But the expression in line 9 references the symbol "**lab2**", so
862 line 10 (which is a copy of line-8) deposits a word of 1. Finally, line 11 deposits a
863 word of 1 because the Boolean equality operator evaluates to true.
865 The operators "**^^defined**" and "**^^referenced**" are particularly useful in
866 conditional assembly. For instance, it is possible to automatically include debugging
867 code if the debugging code is referenced, as in:
871 lea string,a0 ; AO -> message
872 jsr debug ; print a message
874 string: dc.b "Help me, Spock!",0 ; (the message)
878 .iif ^^defined debug, .include "debug.s"
880 The **jsr** statement references the symbol debug. Near the end of the source file, the
881 "**.iif**' statement includes the file "**debug.s**" if the symbol debug was referenced.
883 In production code, presumably all references to the debug symbol will be removed,
884 and the debug source file will not be included. (We could have as easily made the
885 symbol **debug** external, instead of including another source file).
891 Assembler directives may be any mix of upper- or lowercase. The leading periods
892 are optional, though they are shown here and their use is encouraged. Directives
893 may be preceeded by a label; the label is defined before the directive is executed.
894 Some directives accept size suffixes (**.b**, **.s**, **.w** or **.1**); the default is word (**.w**) if no
895 size is specified. The **.s** suffix is identical to **.b**. Directives relating to the 6502 are
896 described in the chapter on `6502 Support`_.
901 If the location counter for the current section is odd, make it even by adding
902 one to it. In text and data sections a zero byte is deposited if necessary.
904 Align the program counter to the next integral long boundary (4 bytes).
905 Note that GPU/DSP code sections are not contained in their own
906 segments and are actually part of the TEXT or DATA segments.
907 Therefore, to align GPU/DSP code, align the current section before and
908 after the GPU/DSP code.
910 Align the program counter to the next integral phrase boundary (8 bytes).
911 Note that GPU/DSP code sections are not contained in their own
912 segments and are actually part of the TEXT or DATA segments.
913 Therefore, to align GPU/DSP code, align the current section before and
914 after the GPU/DSP code.
916 Align the program counter to the next integral double phrase boundary (16
917 bytes). Note that GPU/DSP code sections are not contained in their own
918 segments and are actually part of the TEXT or DATA segments.
919 Therefore, to align GPU/DSP code, align the current section before and
920 after the GPU/DSP code.
922 Align the program counter to the next integral quad phrase boundary (32
923 bytes). Note that GPU/DSP code sections are not contained in their own
924 segments and are actually part of the TEXT or DATA segments.
925 Therefore, to align GPU/DSP code, align the current section before and
926 after the GPU/DSP code.
927 **.assert** *expression* [,\ *expression*...]
928 Assert that the conditions are true (non-zero). If any of the comma-seperated
929 expressions evaluates to zero an assembler warning is issued. For example:
933 .assert *-start = $76
934 .assert stacksize >= $400
941 Switch to the BSS, data or text segments. Instructions and data may not
942 be assembled into the BSS-segment, but symbols may be defined and storage
943 may be reserved with the **.ds** directive. Each assembly starts out in the text
945 **.abs** [*location*]
946 Start an absolute section, beginning with the specified location (or zero, if
947 no location is specified). An absolute section is much like BSS, except that
948 locations declared with .ds are based absolute. This directive is useful for
949 declaring structures or hardware locations.
950 For example, the following equates:
960 could be as easily defined as:
971 **.comm** *symbol*, *expression*
972 Specifies a label and the size of a common region. The label is made global,
973 thus confined symbols cannot be made common. The linker groups all common
974 regions of the same name; the largest size determines the real size of the
975 common region when the file is linked.
976 **.ccdef** *expression*
977 Allows you to define names for the condition codes used by the JUMP
978 and JR instructions for GPU and DSP code. For example:
984 jump Always,(r3) ; ‘Always’ is actually 0
986 **.ccundef** *regname*
987 Undefines a register name (regname) previously assigned using the
988 .CCDEF directive. This is only implemented in GPU and DSP code
990 **.dc.i** *expression*
991 This directive generates long data values and is similar to the DC.L
992 directive, except the high and low words are swapped. This is provided
993 for use with the GPU/DSP MOVEI instruction.
994 **.dc**\ [.\ *size*] *expression* [, *expression*...]
995 Deposit initialized storage in the current section. If the specified size is word
996 or long, the assembler will execute a .even before depositing data. If the size
997 is .b, then strings that are not part of arithmetic expressions are deposited
998 byte-by-byte. If no size is specified, the default is .w. This directive cannot be
999 used in the BSS section.
1000 **.dcb**\ [.\ *size*] *expression1*, *expression2*
1001 Generate an initialized block of *expression1* bytes, words or longwords of the
1002 value *expression2*. If the specified size is word or long, the assembler will
1003 execute .even before generating data. If no size is specified, the default is **.w**.
1004 This directive cannot be used in the BSS section.
1005 **.ds**\ [.\ *size*] *expression*
1006 Reserve space in the current segment for the appropriate number of bytes,
1007 words or longwords. If no size is specified, the default size is .w. If the size
1008 is word or long, the assembler will execute .even before reserving space. This
1009 directive can only be used in the BSS or ABS sections (in text or data, use
1010 .dcb to reserve large chunks of initialized storage.)
1012 Switch to Jaguar DSP assembly mode. This directive must be used
1013 within the TEXT or DATA segments.
1014 **.init**\ [.\ *size*] [#\ *expression*,]\ *expression*\ [.\ *size*] [,...]
1015 Generalized initialization directive. The size specified on the directive becomes
1016 the default size for the rest of the line. (The "default" default size is **.w**.) A
1017 comma-seperated list of expressions follows the directive; an expression may be
1018 followed by a size to override the default size. An expression may be preceeded
1019 by a sharp sign, an expression and a comma, which specifies a repeat count to
1020 be applied to the next expression. For example:
1024 .init.l -1, 0.w, #16,'z'.b, #3,0, 11.b
1026 will deposit a longword of -1, a word of zero, sixteen bytes of lower-case 'z',
1027 three longwords of zero, and a byte of 11.
1029 No auto-alignment is performed within the line, but a **.even** is done once
1030 (before the first value is deposited) if the default size is word or long.
1031 **.cargs** [#\ *expression*,] *symbol*\ [.\ *size*] [, *symbol*\ [.\ *size*].. .]
1032 Compute stack offsets to C (and other language) arguments. Each symbol is
1033 assigned an absolute value (like equ) which starts at expression and increases
1034 by the size of each symbol, for each symbol. If the expression is not supplied,
1035 the default starting value is 4. For example:
1039 .cargs #8, .fileliams.1, .openMode, .butPointer.l
1041 could be used to declare offsets from A6 to a pointer to a filename, a word
1042 containing an open mode, and a pointer to a buffer. (Note that the symbols
1043 used here are confined). Another example, a C-style "string-length" function,
1044 could be written as:
1048 _strlen:: .cargs .string ; declare arg
1049 move.l .string(sp),a0 ; a0 -> string
1050 moveq #-1,d0 ; initial size = -1
1051 .1: addq.1 #1,d0 ; bump size
1052 tst.b (a0)+ ; at end of string?
1053 bne .1 ; (no -- try again)
1054 rts ; return string length
1057 End the assembly. In an include file, end the include file and resume assembling
1058 the superior file. This statement is not required, nor are warning messages
1059 generated if it is missing at the end of a file. This directive may be used inside
1060 conditional assembly, macros or **.rept** blocks.
1061 **.equr** *expression*
1062 Allows you to name a register. This is only implemented for GPU/DSP
1063 code sections. For example:
1069 add ClipW,r0 ; ClipW actually is r19
1071 **.if** *expression*
1077 Start a block of conditional assembly. If the expression is true (non-zero) then
1078 assemble the statements between the .if and the matching **.endif** or **.else**.
1079 If the expression is false, ignore the statements unless a matching .else is
1080 encountered. Conditional assembly may be nested to any depth.
1082 It is possible to exit a conditional assembly block early from within an include
1083 file (with **end**) or a macro (with **endm**).
1085 **.iif** *expression*, *statement*
1087 Immediate version of **.if**. If the expression is true (non-zero) then the state-
1088 ment, which may be an instruction, a directive or a macro, is executed. If
1089 the expression is false, the statement is ignored. No **.endif** is required. For
1094 .iif age < 21, canDrink = 0
1095 .iif weight > 500, dangerFlag = 1
1096 .iif !(^^defined DEBUG), .include dbsrc
1098 **.macro** *name* [*formal*, *formal*,...]
1103 Define a macro called name with the specified formal arguments. The macro
1104 definition is terminated with a **.endm** statement. A macro may be exited early
1105 with the .exitm directive. See the chapter on `Macros`_ for more information.
1107 **.undefmac** *macroName* [, *macroName*...]
1108 Remove the macro-definition for the specified macro names. If reference is
1109 made to a macro that is not defined, no error message is printed and the name
1112 **.rept** *expression*
1115 The statements between the **.rept** and **.endr** directives will be repeated *expression*
1116 times. If the expression is zero or negative, no statements will be
1117 assembled. No label may appear on a line containing either of these directives.
1119 **.globl** *symbol* [, *symbol*...]
1121 **.extern** *symbol* [, *symbol*...]
1122 Each symbol is made global. None of the symbols may be confined symbols
1123 (those starting with a period). If the symbol is defined in the assembly, the
1124 symbol is exported in the object file. If the symbol is undefined at the end
1125 of the assembly, and it was referenced (i.e. used in an expression), then the
1126 symbol value is imported as an external reference that must be resolved by the
1127 linker. The **.extern** directive is merely a synonym for **.globl**.
1129 **.include** "*file*"
1130 Include a file. If the filename is not enclosed in quotes, then a default extension
1131 of "**.s**" is applied to it. If the filename is quoted, then the name is not changed
1134 Note: If the filename is not a valid symbol, then the assembler will generate an
1135 error message. You should enclose filenames such as "**atari.s**" in quotes,
1136 because such names are not symbols.
1138 If the include file cannot be found in the current directory, then the directory
1139 search path, as specified by -i on the commandline, or' by the 'MACPATH'
1140 enviroment string, is traversed.
1143 Issue a page eject in the listing file.
1145 **.title** "*string*"
1147 **.subttl** [-] "*string*"
1148 Set the title or subtitle on the listing page. The title should be specified on
1149 the the first line of the source program in order to take effect on the first page.
1150 The second and subsequent uses of **.title** will cause page ejects. The second
1151 and subsequent uses of .subttl will cause page ejects unless the subtitle string
1152 is preceeded by a dash (-).
1157 Enable or disable source code listing. These directives increment and decrement
1158 an internal counter, so they may be appropriately nested. They have no effect
1159 if the **-l** switch is not specified on the commandline.
1162 This directive provides unstructured flow of control within a macro definition.
1163 It will transfer control to the line of the macro containing the specified goto
1164 label. A goto label is a symbol preceeded by a colon that appears in the first
1165 column of a source line within a macro definition:
1169 where the label itself can be any valid symbol name, followed immediately by
1170 whitespace and a valid source line (or end of line). The colon **must** appear in
1173 The goto-label is removed from the source line prior to macro expansion -
1174 to all intents and purposes the label is invisible except to the .goto directive
1175 Macro expansion does not take place within the label.
1177 For example, here is a silly way to count from 1 to 10 without using **.rept**:
1185 iif count <= 10, goto loop
1189 Switch to Jaguar GPU assembly mode. This directive must be used
1190 within the TEXT or DATA segments.
1192 No. Just... no. Don't ask about it. Ever.
1193 **.prgflags** *value*
1194 Sets ST executable .PRG field *PRGFLAGS* to *value*. *PRGFLAGS* is a bit field defined as follows:
1196 ============ ====== =======
1197 Definition Bit(s) Meaning
1198 ============ ====== =======
1199 PF_FASTLOAD 0 If set, clear only the BSS area on program load, otherwise clear the entire heap.
1200 PF_TTRAMLOAD 1 If set, the program may be loaded into alternative RAM, otherwise it must be loaded into standard RAM.
1201 PF_TTRAMMEM 2 If set, the program's Malloc() requests may be satisfied from alternative RAM, otherwise they must be satisfied from standard RAM.
1202 -- 3 Currently unused.
1203 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.
1204 -- 6-15 Currently unused.
1205 ============ ====== =======
1207 **.regequ** *expression*
1208 Essentially the same as **.EQUR.** Included for compatibility with the GASM
1211 Essentially the same as **.EQURUNDEF.** Included for compatibility with
1220 All of the standard Motorola 68000 mnemonics and addressing modes are supported;
1221 you should refer to **The Motorola M68000 Programmer's Reference Manual**
1222 for a description of the instruction set and the allowable addressing modes for each
1223 instruction. With one major exception (forward branches) the assembler performs
1224 all the reasonable optimizations of instructions to their short or address register
1227 Register names may be in upper or lower case. The alternate forms ``R0`` through
1228 ``R15`` may be used to specify ``D0`` through ``A7``. All register names are keywords, and
1229 may not be used as labels or symbols. None of the 68010 or 68020 register names
1230 are keywords (but they may become keywords in the future).
1235 ===================================== ===========================================
1236 Assembler Syntax Description
1237 ===================================== ===========================================
1238 *Dn* Data register direct
1239 *An* Address register direct
1240 (*An*) Address register indirect
1241 (*An*)+ Address register indirect postincrement
1242 -(*An*) Address register indirect predecrement
1243 *disp*\ (*An*) Address register indirect with displacement
1244 *bdisp*\ (*An*, *Xi*\ [.\ *size*]) Address register indirect indexed
1245 *abs*.w Absolute short
1246 *abs* Absolute (long or short)
1247 *abs*.l Forced absolute long
1248 *disp*\ (PC) Program counter with displacement
1249 *bdisp*\ (PC, *Xi*\ ) Program counter indexed
1251 ===================================== ===========================================
1255 Since RMAC is a one pass assembler, forward branches cannot be automatically
1256 optimized to their short form. Instead, unsized forward branches are assumed to
1257 be long. Backward branches are always optimized to the short form if possible.
1259 A table that lists "extra" branch mnemonics (common synonyms for the Motorola
1260 defined mnemonics) appears below.
1262 `Linker Constraints`_
1263 '''''''''''''''''''''
1264 It is not possible to make an external reference that will fix up a byte. For example:
1269 move.l frog(pc,d0),d1
1271 is illegal (and generates an assembly error) when frog is external, because the
1272 displacement occupies a byte field in the 68000 offset word, which the object file
1277 ============== ========
1278 Alternate name Becomes:
1279 ============== ========
1289 ============== ========
1291 `Optimizations and Translations`_
1292 '''''''''''''''''''''''''''''''''
1293 The assembler provides "creature comforts" when it processes 68000 mnemonics:
1295 o **CLR.x An** will really generate **SUB.x An,An**.
1297 o **ADD**, **SUB** and **CMP** with an address register will really generate **ADDA**,
1298 **SUBA** and **CMPA**.
1300 o The **ADD**, **AND**, **CMP**, **EOR**, **OR** and **SUB** mnemonics with immediate
1301 first operands will generate the "I" forms of their instructions (**ADDI**, etc.) if
1302 the second operand is not register direct.
1304 o All shift instructions with no count value assume a count of one.
1306 o **MOVE.L** is optimized to **MOVEQ** if the immediate operand is defined and
1307 in the range -128...127. However, **ADD** and **SUB** are never translated to
1308 their quick forms; **ADDQ** and **SUBQ** must be explicit.
1310 o In GPU/DSP code sections, you can use JUMP (Rx) in place of JUMP T, (Rx) and JR
1311 (Rx) in place of JR T,(Rx).
1312 o RMAC tests all GPU/DSP restrictions and corrects them wherever possible (such as
1313 inserting a NOP instruction when needed).
1314 o The “(Rx+N)” addressing mode for GPU/DSP instructions is optimized to “(Rx)”
1319 `Macro declaration`_
1320 ''''''''''''''''''''
1321 A macro definition is a series of statements of the form:
1324 .macro name [ formal-arg, ...]
1328 statements making up the macro body
1334 The name of the macro may be any valid symbol that is not also a 68000 instruction
1335 or an assembler directive. (The name may begin with a period - macros cannot
1336 be made confined the way labels or equated symbols can be). The formal argument
1337 list is optional; it is specified with a comma-seperated list of valid symbol names.
1338 Note that there is no comma between the name of the macro and the name of the
1339 first formal argument.
1341 A macro body begins on the line after the **.macro** directive. All instructions
1342 and directives, except other macro definitions, are legal inside the body.
1344 The macro ends with the **.endm** statement. If a label appears on the line with
1345 this directive, the label is ignored and a warning is generated.
1347 `Parameter Substitution`_
1348 '''''''''''''''''''''''''
1349 Within the body, formal parameters may be expanded with the special forms:
1355 The second form (enclosed in braces) can be used in situations where the characters
1356 following the formal parameter name are valid symbol continuation characters. This
1357 is usually used to force concatentation, as in:
1362 \(godzilla}vs\{reagan}
1364 The formal parameter name is terminated with a character that is not valid in
1365 a symbol (e.g. whitespace or puncuation); optionally, the name may be enclosed in
1366 curly-braces. The names must be symbols appearing on the formal argument list,
1367 or a single decimal digit (``\1`` corresponds to the first argument, ``\2`` to the second,
1368 ``\9`` to the ninth, and ``\0`` to the tenth). It is possible for a macro to have more than
1369 ten formal arguments, but arguments 11 and on must be referenced by name, not
1372 Other special forms are:
1374 ============ ================================================
1375 Special Form Description
1376 ============ ================================================
1377 ``\\`` a single "\",
1378 ``\~`` a unique label of the form "Mn"
1379 ``\#`` the number of arguments actually specified
1380 ``\!`` the "dot-size" specified on the macro invocation
1381 ``\?name`` conditional expansion
1382 ``\?{name}`` conditional expansion
1383 ============ ================================================
1385 The last two forms are identical: if the argument is specified and is non-empty, the
1386 form expands to a "1", otherwise (if the argument is missing or empty) the form
1389 The form "``\!``" expands to the "dot-size" that was specified when the macro
1390 was invoked. This can be used to write macros that behave differently depending
1391 on the size suffix they are given, as in this macro which provides a synonym for the
1396 .macro deposit value
1399 deposit.b 1 ; byte of 1
1400 deposit.w 2 ; word of 2
1401 deposit.l 3 ; longvord of 3
1402 deposit 4 ; word of 4 (no explicit size)
1406 A previously-defined macro is called when its name appears in the operation field of
1407 a statement. Arguments may be specified following the macro name; each argument
1408 is seperated by a comma. Arguments may be empty. Arguments are stored for
1409 substitution in the macro body in the following manner:
1411 o Numbers are converted to hexadecimal.
1413 o All spaces outside strings are removed.
1415 o Keywords (such as register names, dot sizes and "^^" operators) are converted
1418 o Strings are enclosed in double-quote marks (").
1420 For example, a hypothetical call to the macro "``mymacro``", of the form:
1421 ``mymacro A0, , 'Zorch' / 32, "^^DEFINED foo, , , tick tock``
1423 will result in the translations:
1425 ======== ================= =================================================
1426 Argument Expansion Comment
1427 ======== ================= =================================================
1428 ``\1`` ``a0`` "``A0``" converted to lower-case
1430 ``\3`` ``"Zorch"/$20`` "``Zorch``" in double-quotes, 32 in hexadecimal
1431 ``\4`` ``^^defined foo`` "``^^DEFINED``" converted to lower-case
1434 ``\7`` ``ticktock`` spaces removed (note concatenation)
1435 ======== ================= =================================================
1437 The **.exitm** directive will cause an immediate exit from a macro body. Thus
1438 the macro definition:
1443 .iif !\?source, .exitm ; exit if source is empty
1444 move \source,d0 ; otherwise, deposit source
1447 will not generate the move instruction if the argument **"source"** is missing from
1448 the macro invocation.
1450 The **.end**, **.endif** and **.exitm** directives all pop-out of their include levels
1451 appropriately. That is, if a macro performs a **.include** to include a source file, an
1452 executed **.exitm** directive within the include-file will pop out of both the include-file
1455 Macros may be recursive or mutually recursive to any level, subject only to
1456 the availability of memory. When writing recursive macros, take care in the coding
1457 of the termination condition(s). A macro that repeatedly calls itself will cause the
1458 assembler to exhaust its memory and abort the assembly.
1463 The Gemdos macro is used to make file system calls. It has two parameters, a
1464 function number and the number of bytes to clean off the stack after the call. The
1465 macro pushes the function number onto the stack and does the trap to the file
1466 system. After the trap returns, conditional assembly is used to choose an addq or
1467 an **add.w** to remove the arguments that were pushed.
1471 .macro Gemdos trpno, clean
1472 move.w #\trpno,-(sp) ; push trap number
1473 trap #1 ; do GEMDOS trap
1475 addq #\clean,sp ; clean-up up to 8 bytes
1477 add.w #\clean,sp ; clean-up more than 8 bytes
1481 The Fopen macro is supplied two arguments; the address of a filename, and
1482 the open mode. Note that plain move instructions are used, and that the caller of
1483 the macro must supply an appropriate addressing mode (e.g. immediate) for each
1488 .macro Fopen file, mode
1489 movs.w \mode,-(sp) ;push open mode
1490 move.1 \file,-(sp) ;push address of tile name
1491 Gemdos $3d,8 ;do the GEMDOS call
1494 The **String** macro is used to allocate storage for a string, and to place the
1495 string's address somewhere. The first argument should be a string or other expres-
1496 sion acceptable in a dc.b directive. The second argument is optional; it specifies
1497 where the address of the string should be placed. If the second argument is omitted,
1498 the string's address is pushed onto the stack. The string data itself is kept in the
1503 .macro String str,loc
1504 .if \?loc ; if loc is defined
1505 move.l #.\~,\loc ; put the string's address there
1507 pea .\~ ; push the string's address
1509 .data ; put the string data
1510 .\~: dc.b \str,0 ; in the data segment
1511 .text ; and switch back to the text segment
1514 The construction "``.\~``" will expand to a label of the form "``.M``\ *n*" (where *n* is
1515 a unique number for every macro invocation), which is used to tag the location of
1516 the string. The label should be confined because the macro may be used along with
1517 other confined symbols.
1519 Unique symbol generation plays an important part in the art of writing fine
1520 macros. For instance, if we needed three unique symbols, we might write "``.a\~``",
1521 "``.b\~``" and "``.c\~``".
1525 Repeat-blocks provide a simple iteration capability. A repeat block allows a range
1526 of statements to be repeated a specified number of times. For instance, to generate
1527 a table consisting of the numbers 255 through 0 (counting backwards) you could
1532 .count set 255 ; initialize counter
1533 .rept 256 ; repeat 256 times:
1534 dc.b .count ; deposit counter
1535 .count set .count - 1 ; and decrement it
1536 .endr ; (end of repeat block)
1538 Repeat blocks can also be used to duplicate identical pieces of code (which are
1539 common in bitmap-graphics routines). For example:
1543 .rept 16 ; clear 16 words
1544 clr.w (a0)+ ; starting at AO
1547 `Jaguar GPU/DSP Mode`_
1548 ======================
1550 RMAC will generate code for the Atari jaguar GPU and DSP custom RISC (Reduced
1551 Instruction Set Computer) processors. See the Atari Jaguar Software reference Manual – Tom
1552 & Jerry for a complete listing of Jaguar GPU and DSP assembler mnemonics and addressing
1557 The following condition codes for the GPU/DSP JUMP and JR instructions are built-in:
1561 CC (Carry Clear) = %00100
1562 CS (Carry Set) = %01000
1565 NE (Not Equal) = %00001
1567 HI (Higher) = %00101
1573 RMAC will generate code for the Motorola 6502 microprocessor. This chapter
1574 describes extra addressing modes and directives used to support the 6502.
1576 As the 6502 object code is not linkable (currently there is no linker) external
1577 references may not be made. (Nevertheless, RMAC may reasonably be used for
1578 large assemblies because of its blinding speed.)
1580 `6502 Addressing Modes`_
1581 ''''''''''''''''''''''''
1582 All standard 6502 addressing modes are supported, with the exception of the
1583 accumulator addressing form, which must be omitted (e.g. "ror a" becomes "ror").
1584 Five extra modes, synonyms for existing ones, are included for compatibility with
1585 the Atari Coinop assembler.
1587 ============== ========================================
1588 *empty* implied or accumulator (e.g. tsx or ror)
1589 *expr* absolute or zeropage
1591 (*expr*,x) indirect X
1592 (*expr*),y indirect Y
1596 @\ *expr*\ (x) indirect X
1597 @\ *expr*\ (y) indirect Y
1599 x,\ *expr* indexed X
1600 y,\ *expr* indexed Y
1601 ============== ========================================
1603 While RMAC lacks "high" and "low" operators, high bytes of words may
1604 be extracted with the shift (``>>``) or divide (``/``) operators, and low bytes may be
1605 extracted with the bitwise AND (``&``) operator.
1610 This directive enters the 6502 section. The location counter is undefined, and
1611 must be set with ".org" before any code can be generated.
1613 The "``dc.w``" directive will produce 6502-format words (low byte first). The
1614 68000's reserved keywords (``d0-d7/a0-a7/ssp/usp`` and so on) remain reserved
1615 (and thus unusable) while in the 6502 section. The directives **globl**, **dc.l**,
1616 **dcb.l**, **text**, **data**, **bss**, **abs**, **even** and **comm** are illegal in the 6502 section.
1617 It is permitted, though probably not useful, to generate both 6502 and 68000
1618 code in the same object file.
1620 This directive leaves the 6502 segment and returns to the 68000's text segment.
1621 68000 instructions may be assembled as normal.
1623 This directive is only legal in the 6502 section. It sets the value of the location
1624 counter (or **pc**) to location, an expression that must be defined, absolute, and
1629 It is possible to assemble "beyond" the microprocessor's 64K address space, but
1630 attempting to do so will probably screw up the assembler. DO NOT attempt
1631 to generate code like this:
1640 the third NOP in this example, at location $10000, may cause the assembler
1641 to crash or exhibit spectacular schizophrenia. In any case, RMAC will give
1642 no warning before flaking out.
1644 `6502 Object Code Format`_
1645 ''''''''''''''''''''''''''
1646 This is a little bit of a kludge. An object file consists of a page map, followed by
1647 one or more page images, followed by a normal Alcyon 68000 object file. If the page
1648 map is all zero, it is not written.
1650 The page map contains a byte for each of the 256 256-byte pages in the 6502's
1651 64K address space. The byte is zero (``$00``) if the page contained only zero bytes, or
1652 one (``$01``) if the page contained any non-zero bytes. If a page is flagged with a one,
1653 then it is written (in order) following the page map.
1668 will generate a page map that looks (to a programmer) something like:
1674 <$7c more bytes of zero, for $100 total>
1679 Following the last page image is an Alcyon-format object file, starting with
1680 the magic number ``$601a``. It may contain 68000 code (although that is probably
1681 useless), but the symbol table is valid and available for debugging purposes. 6502
1682 symbols will be absolute (not in text, data or bss).
1687 `When Things Go Wrong`_
1688 '''''''''''''''''''''''
1689 Most of RMAC's error messages are self-explanatory. They fall into four classes:
1690 warnings about situations that you (or the assembler) may not be happy about,
1691 errors that cause the assembler to not generate object files, fatal errors that cause
1692 the assembler to abort immediately, and internal errors that should never happen.\ [3]_
1694 You can write editor macros (or sed or awk scripts) to parse the error messages
1695 RMAC generates. When a message is printed, it is of the form:
1697 "*filename*" , ``line`` *line-number*: *message*
1699 The first element, a filename enclosed in double quotes, indicates the file that generated
1700 the error. The filename is followed by a comma, the word "``line``", and a line
1701 number, and finally a colon and the text of the message. The filename "**(\*top\*)**"
1702 indicates that the assembler could not determine which file had the problem.
1704 The following sections list warnings, errors and fatal errors in alphabetical
1705 order, along with a short description of what may have caused the problem.
1707 .. [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.
1711 **bad backslash code in string**
1712 You tried to follow a backslash in a string with a character that the assembler
1713 didn't recognize. Remember that RMAC uses a C-style escape system in
1716 You specified a label before a macro, **rept** or **endm** directive. The assembler
1717 is warning you that the label will not be defined in the assembly.
1718 **unoptimized short branch**
1719 This warning is only generated if the -s switch is specified on the command
1720 line. The message refers to a forward, unsized long branch that you could have
1727 As a result of previous errors, the assembler cannot continue processing. The
1728 assembly is aborted.
1729 **line too long as a result of macro expansion**
1730 When a source line within a macro was expanded, the resultant line was too
1731 long for RMAC (longer than 200 characters or so).
1734 **memory exhausted**
1735 The assembler ran out of memory. You should (1) split up your source files
1736 and assemble them seperately, or (2) if you have any ramdisks or RAM-resident
1737 programs (like desk accessories) decrease their size so that the assembler has
1738 more RAM to work with. As a rule of thumb, pure 68000 code will use up to
1739 twice the number of bytes contained in the source files, whereas 6502 code will
1740 use 64K of ram right away, plus the size of the source files. The assembler itself
1741 uses about 80K bytes. Get out your calculator...
1743 The assembler ran across an **endm** directive when it wasn't expecting to see
1744 one. The assembly is aborted. Check the nesting of your macro definitions -
1745 you probably have an extra **endm**.
1752 Syntax error in **.cargs** directive.
1753 **.comm symbol already defined**
1754 You tried to ``.comm`` a symbol that was already defined.
1755 **.ds permitted only in BSS**
1756 You tried to use ``.ds`` in the text or data section.
1757 **.init not permitted in BSS or ABS**
1758 You tried to use ``.init`` in the BSS or ABS section.
1759 **.org permitted only in .6502 section**
1760 You tried to use ``.org`` in a 68000 section.
1761 **Cannot create:** *filename*
1762 The assembler could not create the indicated filename.
1763 **External quick reference**
1764 You tried to make the immediate operand of a **moveq**, **subq** or **addq** instruction external.
1765 **PC-relative expr across sections**
1766 You tried to make a PC-relative reference to a location contained in another
1768 **[bwsl] must follow '.' in symbol**
1769 You tried to follow a dot in a symbol name with something other than one of
1770 the four characters 'B', 'W', 'S' or 'L'.
1771 **addressing mode syntax**
1772 You made a syntax error in an addressing mode.
1774 One of your **.assert** directives failed!
1775 **bad (section) expression**
1776 You tried to mix and match sections in an expression
1777 **bad 6502 addressing mode**
1778 The 6502 mnemonic will not work with the addressing mode you specified.
1780 There's a syntax error in the expression you typed.
1781 **bad size specified**
1782 You tried to use an inappropriate size suffix for the instruction. Check your
1783 68000 manual for allowable sizes.
1785 You can't use .b (byte) mode with the **movem** instruction.
1786 **cannot .globl local symbol**
1787 You tried to make a confined symbol global or common.
1788 **cannot initialize non-storage (BSS) section**
1789 You tried to generate instructions (or data, with dc) in the BSS or ABS section.
1790 **cannot use '.b' with an address register**
1791 You tried to use a byte-size suffix with an address register. The 68000 does not
1792 perform byte-sized address register operations.
1793 **directive illegal in .6502 section**
1794 You tried to use a 68000-oriented directive in the 6502 section.
1796 The expression you typed involves a division by zero.
1797 **expression out of range**
1798 The expression you typed is out of range for its application.
1799 **external byte reference**
1800 You tried to make a byte-sized reference to an external symbol, which the
1801 object file format will not allow
1802 **external short branch**
1803 You tried to make a short branch to an external symbol, which the linker cannot
1805 **extra (unexpected) text found after addressing mode**
1806 RMAC thought it was done processing a line, but it ran up against "extra"
1807 stuff. Be sure that any comment on the line begins with a semicolon, and check
1808 for dangling commas, etc.
1809 **forward or undefined .assert**
1810 The expression you typed after a **.assert** directive had an undefined value.
1811 Remember that RMAC is one-pass.
1812 **hit EOF without finding matching .endif**
1813 The assembler fell off the end of last input file without finding a **.endif** to
1814 match an . it. You probably forgot a **.endif** somewhere.
1815 **illegal 6502 addressing mode**
1816 The 6502 instruction you typed doesn't work with the addressing mode you
1818 **illegal absolute expression**
1819 You can't use an absolute-valued expression here.
1820 **illegal bra.s with zero offset**
1821 You can't do a short branch to the very next instruction (read your 68000
1823 **illegal byte-sized relative reference**
1824 The object file format does not permit bytes contain relocatable values; you
1825 tried to use a byte-sized relocatable expression in an immediate addressing
1827 **illegal character**
1828 Your source file contains a character that RMAC doesn't allow. (most
1829 control characters fall into this category).
1830 **illegal initialization of section**
1831 You tried to use .dc or .dcb in the BSS or ABS sections.
1832 **illegal relative address**
1833 The relative address you specified is illegal because it belongs to a different
1835 **illegal word relocatable (in .PRG mode)**
1836 You can't have anything other than long relocatable values when you're gener-
1837 ating a **.PRG** file.
1838 **inappropriate addressing mode**
1839 The mnemonic you typed doesn't work with the addressing modes you specified.
1840 Check your 68000 manual for allowable combinations.
1841 **invalid addressing mode**
1842 The combination of addressing modes you picked for the **movem** instruction
1843 are not implemented by the 68000. Check your 68000 reference manual for
1845 **invalid symbol following ^^**
1846 What followed the ^^ wasn't a valid symbol at all.
1847 **mis-nested .endr**
1848 The assembler found a **.endr** directive when it wasn't prepared to find one.
1849 Check your repeat-block nesting.
1850 **mismatched .else**
1851 The assembler found a **.else** directive when it wasn't prepared to find one.
1852 Check your conditional assembly nesting.
1853 **mismatched .endif**
1854 The assembler found a **.endif** directive when it wasn't prepared to find one.
1855 Check your conditional assembly nesting.
1861 **missing argument name**
1863 **missing close parenthesis ')'**
1865 **missing close parenthesis ']'**
1869 **missing filename**
1875 **missing symbol or string**
1876 The assembler expected to see a symbol/filename/string (etc...), but found
1877 something else instead. In most cases the problem should be obvious.
1878 **misuse of '.', not allowed in symbols**
1879 You tried to use a dot (.) in the middle of a symbol name.
1881 The expression you typed involves a modulo by zero.
1882 **multiple formal argument definition**
1883 The list of formal parameter names you supplied for a macro definition includes
1884 two identical names.
1885 **multiple macro definition**
1886 You tried to define a macro which already had a definition.
1887 **non-absolute byte reference**
1888 You tried to make a byte reference to a relocatable value, which the object file
1889 format does not allow.
1890 **non-absolute byte value**
1891 You tried to dc.b or dcb.b a relocatable value. Byte relocatable values are
1892 not permitted by the object file format.
1893 **register list order**
1894 You tried to specify a register list like **D7-D0**, which is illegal. Remember
1895 that the first register number must be less than or equal to the second register
1897 **register list syntax**
1898 You made an error in specifying a register list for a **.reg** directive or a **.movem**
1900 **symbol list syntax**
1901 You probably forgot a comma between the names of two symbols in a symbol
1902 list, or you left a comma dangling on the end of the line.
1904 This is a "catch-all" error.
1905 **undefined expression**
1906 The expression has an undefined value because of a forward reference, or an
1907 undefined or external symbol.
1908 **unimplemented addressing mode**
1909 You tried to use 68020 "square-bracket" notation for a 68020 addressing mode.
1910 RMAC does not support 68020 addressing modes.
1911 **unimplemented directive**
1912 You have found a directive that didn't appear in the documentation. It doesn't
1914 **unimplemented mnemonic**
1915 You've found an assembler for documentation) bug.
1916 **unknown symbol following ^^**
1917 You followed a ^^ with something other than one of the names defined, ref-
1919 **unsupported 68020 addressing mode**
1920 The assembler saw a 68020-type addressing mode. RMAC does not assem-
1921 ble code for the 68020 or 68010.
1922 **unterminated string**
1923 You specified a string starting with a single or double quote, but forgot to type
1926 The assembler had a problem writing an object file. This is usually caused by
1927 a full disk, or a bad sector on the media.