=====================
Reference Manual
================
-version 2.0.8
-=============
+version 2.0.23
+==============
© and notes
===========
disclaims liability for changes, errors or omissions.*
-*Copyright © 2011-2019, Reboot*
+*Copyright © 2011-2020, Reboot*
*All rights reserved.*
-o\ *file[.o]* Direct object code output to the specified file.
+/~oall Turn all optimisations on/off
-+o\ *0-9* Enable specific optimisation
-~o\ *0-9* Disable specific optimisation
++o\ *0-10*/*p* Enable specific optimisation
+~o\ *0-10*/*p* Disable specific optimisation
`0: Absolute long adddresses to word (on by default)`
-
+
`1: move.l #x,Dn/An to moveq (on by default)`
`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`
`9: Convert adda.w/l #x,Dy to lea x(Dy),Dy`
- 'p: Enforce PC relative'
+ `p: Force PC-Relative mode (alternative: o10)`
-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.
-r *size* automatically pad the size of each
segment in the output file until the size is an integral multiple of the
specified boundary. Size is a letter that specifies the desired boundary.
-
+
`-rw Word (2 bytes, default alignment)`
`-rl Long (4 bytes)`
`-rp Phrase (8 bytes)`
-
+
`-rd Double Phrase (16 bytes)`
-
+
`-rq Quad Phrase (32 bytes)`
-s Warn about unoptimized long branches and applied optimisations.
-u Force referenced and undefined symbols global.
**ifne**, **ifeq** (etc.), and **endc**.
* The tilde (~) character is an operator, and back-quote (`) is an illegal character.
AS68 permitted the tilde and back-quote characters in symbols.
-* There are no equivalents to org or section directives.
+* There are no equivalents to org or section directives apart from .text, .data, .bss.
The **.xdef** and **.xref** directives are not implemented,
but **.globl** makes these unnecessary anyway.
* = expression
+ Exceptions to this rule are when outputting a binary using the **-fr** switch,
+ 6502 mode, and Jaguar GPU/DSP.
* Back-slashes in strings are "electric" characters that are used to escape C-like
character codes. Watch out for GEMDOS path names in ASCII constants -
you will have to convert them to double-backslashes.
* 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.
-* rs.b/rs.w/rs.l/rscount/rsreset can be simulated in rmac using abs.
+* rs.b/rs.w/rs.l/rscount/rsreset can be simulated in rmac using **.abs**.
For example the following source:
::
label2: rs.w 10
label3: rs.l 5
label4: rs.b 2
-
+
size_so_far equ rscount
can be converted to:
label2: ds.w 10
label3: ds.l 5
label4: ds.b 2
-
+
size_so_far equ ^^abscount
* A rare case: if your macro contains something like:
character of a line to disbale all optimisations for that specific line, i.e.
::
-
+
!label: operator operand(s) ; comment
`Equates`_
n0 n1 n2 n3 n4 n5 n6 n7
m0 m1 m2 m3 m4 m5 m6 m7
r0 r1 r2 r3 r4 r5 r6 r7
-
+
`Constants`_
''''''''''''
**~** Tilde: bitwise not (l's complement).
**^^defined** *symbol* True if symbol has a value.
**^^referenced** *symbol* True if symbol has been referenced.
-**^^streq** *stringl*,*string2* True if the strings are equal.
+**^^streq** *string1*, *string2* True if the strings are equal.
**^^macdef** *macroName* True if the macro is defined.
**^^abscount** Returns the size of current .abs section
**^^filesize** *string_filename* Returns the file size of supplied filename
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.
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.
+**.print**
+ This directive is similar to the standard ‘C’ library printf() function
+ and is used to print user messages from the assembly process. You can
+ print any string or valid expression. Several format flags that can be used
+ to format your output are also supported.
+
+ ::
+
+ /x hexadecimal
+ /d signed decimal
+ /u unsigned decimal
+ /w word
+ /l long
+
+ For example:
+
+ ::
+
+ MASK .equ $FFF8
+ VALUE .equ -100000
+ .print “Mask: $”,/x/w MASK
+ .print “Value: “,/d/l VALUE
+
**.phrase**
Align the program counter to the next integral phrase boundary (8 bytes).
**.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.
+
+ **all**, as expected, turns all available optimisations on or off. An exception to this
+ is *o10*/*op* as this is not an optimisation that should be turned on unless the user
+ absolutely needs it.
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.
spf_emx_colouropt: ds.l 1
spf_emx_psmask: ds.l 16
spf_emx_psmaskopt: ds.l 16
-
+
.68000
;*-------------------------------------------------------*
-
+
move #spf_em_colour,d0
move #spf_emx_colour,d0
In this example, *spf_em_colour* and *spf_emx_colour* will have the same value.
-
+
**.comm** *symbol*, *expression*
Specifies a label and the size of a common region. The label is made global,
and JR instructions for GPU and DSP code. For example:
::
-
+
Always .ccdef 0
. . .
jump Always,(r3) ; 'Always' is actually 0
Undefines a register name (regname) previously assigned using the
.CCDEF directive. This is only implemented in GPU and DSP code
- sections.
+ sections.
**.dc.i** *expression*
bne .1 ; (no -- try again)
rts ; return string length
+**.error** ["*string*"]
+
+ Aborts the build, optionally printing a user defined string. Can be useful
+ inside conditional assembly blocks in order to catch errors. For example:
+
+ ::
+
+ .if ^^defined JAGUAR
+ .error "TOS cannot be built on Jaguar, don't be silly"
+ .endif
+
**.end**
End the assembly. In an include file, end the include file and resume assembling
**.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
+ 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
============ ====== =======
Definition Bit(s) Meaning
============ ====== =======
-PF_FASTLOAD 0 If set, clear only the BSS area on program load, otherwise clear the entire heap.
-PF_TTRAMLOAD 1 If set, the program may be loaded into alternative RAM, otherwise it must be loaded into standard RAM.
-PF_TTRAMMEM 2 If set, the program's Malloc() requests may be satisfied from alternative RAM, otherwise they must be satisfied from standard RAM.
+PF_FASTLOAD 0 If set, clear only the BSS area on program load, otherwise clear the entire heap.
+PF_TTRAMLOAD 1 If set, the program may be loaded into alternative RAM, otherwise it must be loaded into standard RAM.
+PF_TTRAMMEM 2 If set, the program's Malloc() requests may be satisfied from alternative RAM, otherwise they must be satisfied from standard RAM.
-- 3 Currently unused.
-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.
+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.
-- 6-15 Currently unused.
============ ====== =======
their quick forms; **ADDQ** and **SUBQ** must be explicit.
* All optimisations are controllable using the **.opt** directive. Refer to its
- description in section `Directives`_.
+ 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.
`Condition Codes`_
''''''''''''''''''
The following condition codes for the GPU/DSP JUMP and JR instructions are built-in:
-
+
::
CC (Carry Clear) = %00100
distinguish between the two. rmac needs the user to be explicit and will
generate an error if the programmer tries to use syntax from one instruction
to the other.
-- Similarly Motorola's assembler can alias **move** with **movec**, **movep**
+- Similarly Motorola's assembler can alias **move** with **movec**, **movep**
and **movem**. rmac also not accept such aliasing and generate an error.
- Motorola's assembler uses the underscore character (*_*) to define local
labels. In order for rmac to maintain a uniform syntax across all platforms,
The following sections list warnings, errors and fatal errors in alphabetical
order, along with a short description of what may have caused the problem.
-.. [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.
+.. [3] If you come across an internal error, we would appreciate it if you would contact the rmac development team and let us know about the problem.
`Warnings`_
'''''''''''
**unknown symbol following ^^**
- You followed a ^^ with something other than one of the names defined, ref-
- erenced or streq.
+ 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 assem-
- ble code for the 68020 or 68010.
+ The assembler saw a 68020-type addressing mode. RMAC does not assemble
+ code for the 68020 or 68010.
**unterminated string**
projects / rmac / blobdiff