=====================
Reference Manual
================
-version 2.0.8
-=============
+version 2.0.18
+==============
© and notes
===========
disclaims liability for changes, errors or omissions.*
-*Copyright © 2011-2019, Reboot*
+*Copyright © 2011-2020, Reboot*
*All rights reserved.*
+o\ *0-9* Enable specific optimisation
~o\ *0-9* Disable specific optimisation
- `0: Absolute long adddresses to word`
+ `0: Absolute long adddresses to word (on by default)`
- `1: move.l #x,Dn/An to moveq`
+ `1: move.l #x,Dn/An to moveq (on by default)`
- `2: Word branches to short`
+ `2: Word branches to short (on by default)`
`3: Outer displacement 0(An) to (An)`
`4: lea to addq`
- `5: Base displacement ([bd,An,Xn],od) etc to ([An,Xn],od)`
+ `5: 68020+ Absolute long base/outer displacement to word`
`6: Convert null short branches to NOP`
`8: Convert adda.w/l #x,Dy to addq.w/l #x,Dy`
`9: Convert adda.w/l #x,Dy to lea x(Dy),Dy`
+
+ 'p: Enforce PC relative'
-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.
lea string,a0 ; AO -> message
jsr debug ; print a message
- its ; and return
+ rts ; and return
string: dc.b "Help me, Spock!",0 ; (the message)
.
.
.
- .iif ^^defined debug, .include "debug.s"
+ .iif ^^referenced debug, .include "debug.s"
The **jsr** statement references the symbol debug. Near the end of the source file, the
"**.iif**" statement includes the file "**debug.s**" if the symbol debug was referenced.
Switch to Motorola DSP56001 mode.
**.org** *location* [*X:*/*Y:*/*P:*/*L:*]
+
This directive sets the value of the location counter (or **pc**) to location, an
expression that must be defined and absolute. It is legal to use the directive in
the following modes: 6502, Tom, Jerry, OP, 56001 and 680x0 (only with -fr switch).
Especially for the 56001 mode the *location* field **must** be prefixed with the
intended section (*X:*, *Y:*, *P:* or *L:*).
+
+**.opt** *"+On"*
+**.opt** *"~On"*
+**.opt** *"+Oall"*
+**.opt** *"~Oall"*
+ These directives control the optimisations that rmac applies to the source
+ automatically. Each directive is applied immediately from the line encountered
+ onwards. So it is possible to turn specific optimisations on and off globally
+ (when placed at the start of the first file) or locally (by turning desired
+ optimisations on and off at certain parts of the source). For a list of the
+ optimisations (*n*) available please consult the table in section `The Command Line`_.
+ **all**, as expected, turns all available optimisations on or off.
+
+ Lastly, as a "creature comfort" feature, if the first column of any line is prefixed
+ with an exclamation mark (*!*) then for that line all optimisations are turned off.
+
**.abs** [*location*]
Start an absolute section, beginning with the specified location (or zero, if
search path, as specified by -i on the commandline, or' by the 'RMACPATH'
enviroment string, is traversed.
+**.incbin** "*file*" [, [*size*], [*offset*]]
+
+ Include a file as a binary. This can be thought of a series of **dc.b** statements
+ that match the binary bytes of the included file, inserted at the location of the
+ directive. The directive is not allowed in a BSS section. Optional parameters
+ control the amount of bytes to be included and offset from the start of the file.
+ All the following lines are valid:
+
+ ::
+ .incbin "test.bin" ; Include the whole file
+ .incbin "test.bin",,$30 ; Skip the first 48 bytes
+ .incbin "test.bin",$70,$30 ; Include $70 bytes starting at offset $30
+ .incbin "test.bin",$48 ; Include the file starting at offset 48 till the end
+ .incbin "test.bin",, ; Include the whole file
+
**.eject**
Issue a page eject in the listing file.
in the range -128...127. However, **ADD** and **SUB** are never translated to
their quick forms; **ADDQ** and **SUBQ** must be explicit.
+ * All optimisations are controllable using the **.opt** directive. Refer to its
+ description in section `Directives`_.
+
+ * 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.
+ 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).
+ (Rx) in place of JR T,(Rx).
* RMAC tests all GPU/DSP restrictions and corrects them wherever possible (such as
- inserting a NOP instruction when needed).
+ inserting a NOP instruction when needed).
* The *(Rx+N)* addressing mode for GPU/DSP instructions is optimized to *(Rx)*
when *N* is zero.
projects / rmac / blobdiff