X-Git-Url: http://shamusworld.gotdns.org/cgi-bin/gitweb.cgi?p=rmac;a=blobdiff_plain;f=docs%2Frmac.rst;h=a562e85ff139a8fb2efaaf5b4db69380de8a313b;hp=12781f0c9247d683d47ec78e4b624d47d0f5198c;hb=188ff8b3a5913738a310f25e4abef5cca40187a8;hpb=2037569179a89c7ea99abf7c3e75f23448ff54ff diff --git a/docs/rmac.rst b/docs/rmac.rst index 12781f0..a562e85 100644 --- a/docs/rmac.rst +++ b/docs/rmac.rst @@ -4,8 +4,8 @@ RMAC ===================== Reference Manual ================ -version 2.0.0 -============= +version 2.0.18 +============== © 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-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` @@ -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: 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. @@ -625,9 +628,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`_ '''''''''''' @@ -893,12 +902,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. @@ -998,6 +1007,30 @@ 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. + + 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 @@ -1268,6 +1301,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. @@ -1477,11 +1525,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. @@ -1913,7 +1977,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 +2030,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. @@ -2084,10 +2148,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.