=====================
Reference Manual
================
-version 2.0.4
-=============
+version 2.0.23
+==============
© and notes
===========
disclaims liability for changes, errors or omissions.*
-*Copyright © 2011-2019, Reboot*
+*Copyright © 2011-2020, Reboot*
*All rights reserved.*
-fa ALCYON output object file format (implied when **-ps** is enabled).
-fb BSD COFF output object file 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.
-i\ *path* Set include-file directory search path.
-l\ *[file[prn]]* Construct and direct assembly listing to the specified file.
-o\ *file[.o]* Direct object code output to the specified file.
+/~oall Turn all optimisations on/off
-+o\ *0-7* Enable specific optimisation
-~o\ *0-7* 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)`
- `0: Absolute long adddresses to word`
-
- `1: move.l #x,Dn/An to moveq`
+ `1: move.l #x,Dn/An to moveq (on by default)`
+
+ `2: Word branches to short (on by default)`
- `2: Word branches to short`
-
`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: 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`_
r0 r1 r2 r3 r4 r5 r6 r7
r8 r9 r10 r11 r12 rl3 r14 ri5
6502:
- **TODO**
+ x y a
DSP56001:
- **TODO**
+ x x0 x1 x2 y y0 y1 y2
+ a a0 a1 a2 b b0 b1 b2 ab ba
+ mr omr la lc ssh ssl ss
+ 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).
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. 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.
+
**.abs** [*location*]
Start an absolute section, beginning with the specified location (or zero, if
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
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.
============ ====== =======
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.
============ ====== =======
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.
`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,
- Motorola's assembler allows reordering of addressing modes **x:**, **x:r**,
**r:y**, **x:y**. rmac will only accept syntax as is defined on the reference
manual.
-- In **l:** section a dc value cannot be 12 hex digits like Motorola's assmebler.
+- In **L:** section a dc value cannot be 12 hex digits like Motorola's assmebler.
Instead, the value needs to be split into two parts separated by **:**.
`6502 Support`_
This directive leaves the 6502 segment and returns to the 68000's text segment.
68000 instructions may be assembled as normal.
**.org** *location*
- This directive is only legal in the 6502 section. It sets the value of the location
+ This directive sets the value of the location
counter (or **pc**) to location, an expression that must be defined, absolute, and
less than $10000.
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`_
'''''''''''
You tried to use ``.init`` in the BSS or ABS section.
-**.org permitted only in .6502 section**
-
- You tried to use ``.org`` in a 68000 section.
-
**Cannot create:** *filename*
The assembler could not create the indicated filename.
**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