X-Git-Url: http://shamusworld.gotdns.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=docs%2Frmac.rst;h=50083e477deb6c6b058d20cec0f165fbcae356c3;hb=refs%2Ftags%2Fv2.1.11;hp=aeb1df423a68bf69439fe0811e3e4a75893a7564;hpb=c38505ee4b2a0de59926107e52fb8bb84041a0e4;p=rmac diff --git a/docs/rmac.rst b/docs/rmac.rst index aeb1df4..50083e4 100644 --- a/docs/rmac.rst +++ b/docs/rmac.rst @@ -4,8 +4,8 @@ RMAC ===================== Reference Manual ================ -version 2.0.4 -============= +version 2.0.23 +============== © and notes =========== @@ -17,7 +17,7 @@ the accuracy of printed or duplicated material after the date of publication and disclaims liability for changes, errors or omissions.* -*Copyright © 2011-2019, Reboot* +*Copyright © 2011-2020, Reboot* *All rights reserved.* @@ -123,6 +123,7 @@ Switch Description -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. @@ -153,20 +154,20 @@ Switch Description -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` @@ -175,6 +176,8 @@ Switch Description `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. @@ -182,15 +185,15 @@ Switch Description -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. @@ -401,7 +404,7 @@ necessary to make other assemblers' source code assemble. **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. @@ -411,6 +414,8 @@ necessary to make other assemblers' source code assemble. * = 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. @@ -419,7 +424,7 @@ necessary to make other assemblers' source code assemble. * 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: :: @@ -429,7 +434,7 @@ necessary to make other assemblers' source code assemble. label2: rs.w 10 label3: rs.l 5 label4: rs.b 2 - + size_so_far equ rscount can be converted to: @@ -441,7 +446,7 @@ necessary to make other assemblers' source code assemble. 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: @@ -505,7 +510,7 @@ As an addition, the exclamation mark character (**!**) can be placed at the very character of a line to disbale all optimisations for that specific line, i.e. :: - + !label: operator operand(s) ; comment `Equates`_ @@ -625,9 +630,15 @@ and may not be used as symbols (e.g. labels, equates, or the names of macros): 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`_ '''''''''''' @@ -794,7 +805,7 @@ Operator Description **~** 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 @@ -893,12 +904,12 @@ code if the debugging code is referenced, as in: 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. @@ -933,6 +944,29 @@ 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). @@ -998,6 +1032,33 @@ described in the chapter on `6502 Support`_. 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 @@ -1064,15 +1125,15 @@ described in the chapter on `6502 Support`_. 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, @@ -1086,7 +1147,7 @@ described in the chapter on `6502 Support`_. and JR instructions for GPU and DSP code. For example: :: - + Always .ccdef 0 . . . jump Always,(r3) ; 'Always' is actually 0 @@ -1095,7 +1156,7 @@ described in the chapter on `6502 Support`_. 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* @@ -1174,6 +1235,17 @@ described in the chapter on `6502 Support`_. 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 @@ -1268,6 +1340,21 @@ described in the chapter on `6502 Support`_. 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. @@ -1334,11 +1421,11 @@ described in the chapter on `6502 Support`_. ============ ====== ======= 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. ============ ====== ======= @@ -1477,11 +1564,27 @@ The assembler provides "creature comforts" when it processes 68000 mnemonics: 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. @@ -1728,7 +1831,7 @@ modes. `Condition Codes`_ '''''''''''''''''' The following condition codes for the GPU/DSP JUMP and JR instructions are built-in: - + :: CC (Carry Clear) = %00100 @@ -1902,7 +2005,7 @@ Atari Falcon XBIOS) and *.p56* (binary equivalent of *.lod*) 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, @@ -1913,7 +2016,7 @@ Atari Falcon XBIOS) and *.p56* (binary equivalent of *.lod*) - 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`_ @@ -1966,7 +2069,7 @@ y,\ *expr* indexed Y 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. @@ -2024,7 +2127,7 @@ indicates that the assembler could not determine which file had the problem. 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`_ ''''''''''' @@ -2084,10 +2187,6 @@ order, along with a short description of what may have caused the problem. 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. @@ -2346,13 +2445,13 @@ order, along with a short description of what may have caused the problem. **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**