===========
*NOTE: Every effort has been made to ensure the accuracy and robustness of this
-manual and the associated software. However, because Reboot is constantly improving
-and updating its computer software, it is unable to guarantee
+manual and the associated software. However, the authors are constantly improving
+and updating its computer software, we is unable to guarantee
the accuracy of printed or duplicated material after the date of publication and
disclaims liability for changes, errors or omissions.*
-*Copyright © 2011-2020, Reboot*
+*Copyright © 2011-2022, the rmac authors*
*All rights reserved.*
-*Reboot Document number F00000K-001 Rev. A.*
-
Contents
========
at Atari Corporation by programmers who needed a high performance assembler
for their work. Then, more than 20 years later, because there was still a need for
such an assembler and what was available wasn't up to expectations, Subqmod
-and eventually Reboot continued work on the freely released source, adding Jaguar
+and eventually the rmac authors continued work on the freely released source, adding Jaguar
extensions and fixing bugs. Over time the assembler has been extended by adding
support for Motorola's 68020/30/40/60, 68881/2, DSP56001 CPUs as well as Atari's
Object Processor (OP) found on the Atari Jaguar.
-e\ *[file[.err]]* Direct error messages to the specified file.
-fa ALCYON output object file format (implied when **-ps** is enabled).
-fb BSD COFF output object file format.
+-fb Commodore 64 PRG format.
-fe ELF output object file format.
-fr Absolute address. Source code is required to have one .org statement.
-fx Atari 800 com/exe/xex output object file format.
+-g Generate source level debug info. Requires BSD COFF object file format.
-i\ *path* Set include-file directory search path.
-l\ *[file[prn]]* Construct and direct assembly listing to the specified file.
--l\ *\*[filename]* Create an output listing file without pagination
+-l\ *\*[filename]* Create an output listing file without pagination.
-m\ *cpu* Switch CPU type
`68000 - MC68000`
`jerry - Jaguar DSP JRISC`
-o\ *file[.o]* Direct object code output to the specified file.
-+/~oall Turn all optimisations on/off
-+o\ *0-10*/*p* Enable specific optimisation
-~o\ *0-10*/*p* Disable specific optimisation
++/~oall Turn all optimisations on/off
++o\ *0-30*/*p* Enable specific optimisation
+~o\ *0-30*/*p* Disable specific optimisation
- `0: Absolute long adddresses to word (on by default)`
+ `0: Absolute long adddresses to word`
- `1: move.l #x,Dn/An to moveq (on by default)`
+ `1: move.l #x,Dn/An to moveq`
- `2: Word branches to short (on by default)`
+ `2: Word branches to short`
`3: Outer displacement 0(An) to (An)`
`9: Convert adda.w/l #x,Dy to lea x(Dy),Dy`
- `p: Force PC-Relative mode (alternative: o10)`
+ `10: 56001 Use short format for immediate values if possible`
+
+ `11: 56001 Auto convert short addressing mode to long (default: on)`
+
+ `30: Enforce PC relative (alternative name: op)`
+
-p Produce an executable (**.prg**) output file.
-ps Produce an executable (**.prg**) output file with symbols.
-px Produce an executable (**.prg**) output file with extended symbols.
-s Warn about unoptimized long branches and applied optimisations.
-u Force referenced and undefined symbols global.
-v Verbose mode (print running dialogue).
--x Turn on debugging mode
+-x Turn on debugging mode.
-yn Set listing page size to n lines.
+-4 Use C style operator precedence.
file\ *[s]* Assemble the specified file.
=================== ===========
file is created. Beware! If an assembly produces no errors, any error file from
a previous assembly is not removed.
+**-g**
+ The **-g** switch causes RMAC to generate source-level debug symbols using the
+ stabs format. When linked with a compatible linker such as RLN, these symbols
+ can be used by source-level debuggers such as rdbjag, wdb, or gdb to step
+ through assembly code line-by-line with all the additional context of labels,
+ macros, constants, register equates, etc. available in the original assembly
+ listings rather than relying on the simple disassembly or raw machine code
+ available when stepping through instruction-by-instruction. This option only
+ works with the BSD COFF object file format, as the others do not use the
+ a.out-style symbol tables required by stabs, and RMAC does not currently
+ support placing stabs debug symbols in their own dedicated section in ELF
+ format object files.
+
**-i**
The **-i** switch allows automatic directory searching for include files. A list of
semi-colon seperated directory search paths may be mentioned immediately
space), sets the number of lines in a page. RMAC will produce *N* lines
before emitting a form-feed. If *N* is missing or less than 10 an error message is
generated.
+**-4**
+ Use C style order of precedence in expressions. See `Order of Evaluation`_ for more
+ information.
`Using RMAC`_
===============
character codes. Watch out for GEMDOS path names in ASCII constants -
you will have to convert them to double-backslashes.
* Expression evaluation is done left-to-right without operator precedence. Use parentheses to
- force the expression evaluation as you wish.
+ force the expression evaluation as you wish. Alternatively, use the **-4** switch to switch
+ to C style precedence. For more information refer to `Order of Evaluation`_.
* 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"
* In 68020+ mode **Zan** and **Zri** (register suppression) is not supported.
a0 a1 a2 a3 a4 a5 a6 a7
Tom/Jerry:
r0 r1 r2 r3 r4 r5 r6 r7
- r8 r9 r10 r11 r12 rl3 r14 ri5
+ r8 r9 r10 r11 r12 r13 r14 r15
6502:
x y a
DSP56001:
Thus the expression "1+2*3" evaluates to 9, not 7. However, precedence may be
forced with parenthesis (**()**) or square-brackets (**[]**).
+All the above behavior is the default. However if the command line switch **-4**
+is used, then C style of operator precedence is enforced. The following list
+shows the order of precedence in this mode, from lowest to highest:
+
+ * bitwise XOR ^
+
+ * bitwise OR |
+
+ * bitwise AND &
+
+ * relational = < <= >= > !=
+
+ * shifts << >>
+
+ * sum + -
+
+ * product * /
+
`Types`_
'''''''''
Expressions belong to one of three classes: undefined, absolute or relocatable. An
=========== ==============================================
* All binary operators have the same precedence:
- expressions are evaluated strictly left to right.
+ expressions are evaluated strictly left to right,
+ with the exception of the **-4** switch. For more information
+ refer to `Order of Evaluation`_.
* Division or modulo by zero yields an assembly error.
Assembler directives may be any mix of upper- or lowercase. The leading periods
are optional, though they are shown here and their use is encouraged. Directives
may be preceeded by a label; the label is defined before the directive is executed.
-Some directives accept size suffixes (**.b**, **.s**, **.w** or **.1**); the default is word (**.w**) if no
-size is specified. The **.s** suffix is identical to **.b**. Directives relating to the 6502 are
-described in the chapter on `6502 Support`_.
+Some directives accept size suffixes (**.b**, **.s**, **.w**, **.1**, **.d**, **.x**, **.p**, or **.q**);
+the default is word (**.w**) if no size is specified. The **.s** suffix is identical to **.b**,
+with the exception of being used in a **dc** statement. In that case the **.s**
+refers to single precision floating point numbers.
+Directives relating to the 6502 are described in the chapter on `6502 Support`_.
Therefore, to align GPU/DSP code, align the current section before and
after the GPU/DSP code.
- **.assert** *expression* [,\ *expression*...]
+**.align** *expression*
+
+ A generalised version of the above directives, this will align the program
+ counter to the boundary of the specified value. Note that there is not much
+ error checking happening (only values 0 and 1 are rejected). Also note that
+ in DSP56001 mode the align value is assumed to be in DSP words, i.e. 24 bits.
+
+**.assert** *expression* [,\ *expression*...]
Assert that the conditions are true (non-zero). If any of the comma-seperated
expressions evaluates to zero an assembler warning is issued. For example:
Start an absolute section, beginning with the specified location (or zero, if
no location is specified). An absolute section is much like BSS, except that
locations declared with .ds are based absolute. This directive is useful for
-
declaring structures or hardware locations.
For example, the following equates:
**.equr** *expression*
- Allows you to name a register. This is only implemented for GPU/DSP
- code sections. For example:
+ Allows you to name a register. For example:
::
+ .gpu
Clipw .equr r19
. . .
add ClipW,r0 ; ClipW actually is r19
* All optimisations are turned off for any source line that has an exclamation mark
(*!*) on their first column.
- * Optimisation switches 0, 1 and 2 are turned on by default for legacy reasons.
+ * Optimisation switch 11 is turned on by default for compatibility with the
+ Motorola reference 56001 DSP assembler.
All other levels are off by default. (refer to section `The Command Line`_
for a description of all the switches).
* Optimisation warnings are off by default. Invoke RMAC with the *-s* switch to
turn on warnings in console and listing output.
- * In DSP56001 mode size optimisations are on by default. Currently there is no
- way to disable this behaviour.
-
* In GPU/DSP code sections, you can use JUMP (Rx) in place of JUMP T, (Rx) and JR
(Rx) in place of JR T,(Rx).
`6502 Support`_
===============
-RMAC will generate code for the Motorola 6502 microprocessor. This chapter
+RMAC will generate code for the MOS 6502 microprocessor. This chapter
describes extra addressing modes and directives used to support the 6502.
As the 6502 object code is not linkable (currently there is no linker) external
references may not be made. (Nevertheless, RMAC may reasonably be used for
large assemblies because of its blinding speed.)
+Currently there is no support for undocumented opcodes. This will be addressed
+in a future release.
+
`6502 Addressing Modes`_
''''''''''''''''''''''''
All standard 6502 addressing modes are supported, with the exception of the
04-05 End Address. The last byte to load for this segment
06-.. The actual segment data to load (End Address-Start Address + 1 bytes)
+In addition there is the standard output format for Commodore 64 binaries (.PRG).
+
`Error Messages`_
=================
You tried to ``.comm`` a symbol that was already defined.
-**.ds permitted only in BSS**
-
- You tried to use ``.ds`` in the text or data section.
-
**.init not permitted in BSS or ABS**
You tried to use ``.init`` in the BSS or ABS section.
The expression has an undefined value because of a forward reference, or an
undefined or external symbol.
-**unimplemented addressing mode**
-
- You tried to use 68020 "square-bracket" notation for a 68020 addressing mode.
- RMAC does not support 68020 addressing modes.
-
**unimplemented directive**
You have found a directive that didn't appear in the documentation. It doesn't
You followed a ^^ with something other than one of the names defined, referenced
or streq.
-**unsupported 68020 addressing mode**
-
- The assembler saw a 68020-type addressing mode. RMAC does not assemble
- code for the 68020 or 68010.
-
**unterminated string**
You specified a string starting with a single or double quote, but forgot to type
projects / rmac / blobdiff