X-Git-Url: http://shamusworld.gotdns.org/cgi-bin/gitweb.cgi?p=rmac;a=blobdiff_plain;f=docs%2Frmac.rst;h=a562e85ff139a8fb2efaaf5b4db69380de8a313b;hp=32218e1aaf49a5e5b8b42330e7d37ad3b3da729e;hb=188ff8b3a5913738a310f25e4abef5cca40187a8;hpb=6c68569fbfe25f7edf7607615a2db5911584f0ce diff --git a/docs/rmac.rst b/docs/rmac.rst index 32218e1..a562e85 100644 --- a/docs/rmac.rst +++ b/docs/rmac.rst @@ -4,8 +4,8 @@ RMAC ===================== Reference Manual ================ -version 1.6.5 -============= +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-2017, Reboot* +*Copyright © 2011-2020, Reboot* *All rights reserved.* @@ -38,8 +38,10 @@ runs on the any POSIX compatible platform and the Atari ST. It was initially wri at Atari Corporation by programmers who needed a high performance assembler for their work. Then, more than 20 years later, because there was still a need for such an assembler and what was available wasn't up to expectations, Subqmod -and eventually Reboot continued work on the freely released source, adding Jaguar extensions -and fixing bugs. +and eventually Reboot continued work on the freely released source, adding Jaguar +extensions and fixing bugs. Over time the assembler has been extended by adding +support for Motorola's 68020/30/40/60, 68881/2, DSP56001 CPUs as well as Atari's +Object Processor (OP) found on the Atari Jaguar. RMAC is intended to be used by programmers who write mostly in assembly language. It was not originally a back-end to a C compiler, therefore it @@ -59,8 +61,6 @@ AS68 Users. `Getting Started`_ '''''''''''''''''' - =>Write protect your distribution disk and make a backup of it now. Put the - original disk in a safe place. * The distribution disk contains a file called README that you should read. This file contains important nays about the contents of the distribution disk @@ -120,32 +120,72 @@ Switch Description =================== =========== -dname\ *[=value]* Define symbol, with optional value. -e\ *[file[.err]]* Direct error messages to the specified file. --fa ALCYON output object file format (implied with **-ps** is enabled). +-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. -l\ *\*[filename]* Create an output listing file without pagination --o\ *file[.o]* Direct object code output to the specified file. +-m\ *cpu* Switch CPU type + + `68000 - MC68000` + + `68020 - MC68020` + + `68030 - MC68030` + + `68040 - MC68040` + + `68060 - MC68060` + + `68881 - MC68881` + + `68882 - MC68882` + + `56001 - DSP56001` + + `6502 - MOS 6502` + + `tom - Jaguar GPU JRISC` + + `jerry - Jaguar DSP JRISC` + + -o\ *file[.o]* Direct object code output to the specified file. +/~oall Turn all optimisations on/off -+o\ *0-3* Enable specific optimisation -~o\ *0-3* 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)` + `3: Outer displacement 0(An) to (An)` + + `4: lea to addq` + + `5: 68020+ Absolute long base/outer displacement to word` + + `6: Convert null short branches to NOP` + + `7: Convert clr.l Dn to moveq #0,Dn` + + `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. -q Make RMAC resident in memory (Atari ST only). -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)` @@ -313,21 +353,21 @@ reading each source file exactly once and then "back-patching" to fix up forward references. This one-pass nature is usually transparent to the programmer, with the following important exceptions: - o in listings, the object code for forward references is not shown. Instead, lower- + * In listings, the object code for forward references is not shown. Instead, lower- case "xx"s are displayed for each undefined byte, as in the following example: :: - 60xx 1: bra.s.2 ;forward branch - xxxxxxxx dc.l .2 ;forward reference - 60FE .2: bra.s.2 ;backward reference + 60xx 1: bra.s.2 ;forward branch + xxxxxxxx dc.l .2 ;forward reference + 60FE .2: bra.s.2 ;backward reference - o Forward branches (including **BSR**\s) are never optimized to their short forms. + * Forward branches (including **BSR**\s) are never optimized to their short forms. To get a short forward branch it is necessary to explicitly use the ".s" suffix in the source code. - o Error messages may appear at the end of the assembly, referring to earlier source + * Error messages may appear at the end of the assembly, referring to earlier source lines that contained undefined symbols. - o All object code generated must fit in memory. Running out of memory is a + * All object code generated must fit in memory. Running out of memory is a fatal error that you must deal with by splitting up your source files, re-sizing or eliminating memory-using programs such as ramdisks and desk accessories, or buying more RAM. @@ -352,95 +392,93 @@ like Devpac or vasm. This section outlines the major differences. In practice, we have found that very few changes are necessary to make other assemblers' source code assemble. -o A semicolon (;) must be used to introduce a comment, +* A semicolon (;) must be used to introduce a comment, except that a star (*) may be used in the first column. AS68 treated anything following the operand field, preceeded by whitespace, as a comment. (RMAC treats a star that is not in column 1 as a multiplication operator). -o Labels require colons (even labels that begin in column 1). +* Labels require colons (even labels that begin in column 1). -o Conditional assembly directives are called **if**, **else** and **endif**. - Devpac and vasm called these +* Conditional assembly directives are called **if**, **else** and **endif**. + Devpac and vasm call these **ifne**, **ifeq** (etc.), and **endc**. -o The tilde (~) character is an operator, and back-quote (`) is an illegal character. +* The tilde (~) character is an operator, and back-quote (`) is an illegal character. AS68 permitted the tilde and back-quote characters in symbols. -o There are no equivalents to org or section directives. +* There are no equivalents to org or section directives. The **.xdef** and **.xref** directives are not implemented, but **.globl** makes these unnecessary anyway. - o The location counter cannot be manipulated with a statement of the form: +* The location counter cannot be manipulated with a statement of the form: :: * = expression -o The **ds** directive is not permitted in the text or data segments; - an error message is issued. Use **dcb** instead to reserve large blocks of - initialized storage. -o Back-slashes in strings are "electric" characters that are used to escape C-like +* 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. -o Expression evaluation is done left-to-right without operator precedence. Use parentheses to +* Expression evaluation is done left-to-right without operator precedence. Use parentheses to force the expression evaluation as you wish. -o Mark your segments across files. +* 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" -o rs.b/rs.w/rs.l/rscount/rsreset can be simulated in rmac using abs. +* 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. For example the following source: - :: + :: - rsreset - label1: rs.w 1 - label2: rs.w 10 - label3: rs.l 5 - label4: rs.b 2 + rsreset + label1: rs.w 1 + label2: rs.w 10 + label3: rs.l 5 + label4: rs.b 2 - size_so_far equ rscount + size_so_far equ rscount can be converted to: - :: + :: - abs - label1: ds.w 1 - label2: ds.w 10 - label3: ds.l 5 - label4: ds.b 2 + abs + label1: ds.w 1 + label2: ds.w 10 + label3: ds.l 5 + label4: ds.b 2 - size_so_far equ ^^abscount -o A rare case: if your macro contains something like: + size_so_far equ ^^abscount +* A rare case: if your macro contains something like: - :: + :: - macro test - move.l #$\1,d0 - endm + macro test + move.l #$\1,d0 + endm - test 10 + test 10 then by the assembler's design this will fail as the parameters are automatically converted to hex. Changing the code like this works: - :: + :: - macro test - move.l #\1,d0 - endm + macro test + move.l #\1,d0 + endm - test $10 + test $10 `Text File Format`_ ''''''''''''''''''' For those using editors other than the "Emacs" style ones (Micro-Emacs, Mince, etc.) this section documents the source file format that RMAC expects. - o Files must contain characters with ASCII values less than 128; it is not per- + * Files must contain characters with ASCII values less than 128; it is not per- missable to have characters with their high bits set unless those characters are contained in strings (i.e. between single or double quotes) or in comments. - o Lines of text are terminated with carriage-return/line-feed, linefeed alone, or + * Lines of text are terminated with carriage-return/line-feed, linefeed alone, or carriage-return alone. - o The file is assumed to end with the last terminated line. If there is text beyond + * The file is assumed to end with the last terminated line. If there is text beyond the last line terminator (e.g. control-Z) it is ignored. `Source Format`_ @@ -466,6 +504,13 @@ The label, if it appears, must be terminated with a single or double colon. If it is terminated with a double colon it is automatically declared global. It is illegal to declare a confined symbol global (see: `Symbols and Scope`_). +As an addition, the exclamation mark character (**!**) can be placed at the very first +character of a line to disbale all optimisations for that specific line, i.e. + + :: + + !label: operator operand(s) ; comment + `Equates`_ '''''''''' A statement may also take one of these special forms: @@ -517,7 +562,7 @@ collisions. :: reallyLongSymbolName .reallyLongConfinedSymbolName - a10 ret move dc frog aa6 a9 ???? + a10 ret move dc frog aa6 a9 ???? .a1 .ret .move .dc .frog .a9 .9 ???? .0 .00 .000 .1 .11. .111 . ._ _frog ?zippo? sys$syetem atari Atari ATARI aTaRi @@ -573,12 +618,25 @@ and may not be used as symbols (e.g. labels, equates, or the names of macros): :: + Common: equ set reg + MC68000: sr ccr pc sp ssp usp d0 d1 d2 d3 d4 d5 d6 d7 a0 a1 a2 a3 a4 a5 a6 a7 + Tom/Jerry: r0 r1 r2 r3 r4 r5 r6 r7 r8 r9 r10 r11 r12 rl3 r14 ri5 + 6502: + x y a + DSP56001: + 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`_ '''''''''''' @@ -662,7 +720,7 @@ mnemonic, as in this example: keeps reg d3-d7/d3-a6 ; registers to preserve allregs reg d0-d7/a0-a7 ; all registers movem.l #temps,-(sp) ; these two lines ... - movea.l d0-d2/a0-a2,-(sp) ; are identical + movem.l d0-d2/a0-a2,-(sp) ; are identical movem.l #keeps,-(sp) ; save "keep" registers movem.l (sp)+,#keeps ; restore "keep" registers @@ -737,9 +795,9 @@ pointers to the label "zip": `Unary Operators`_ '''''''''''''''''' -================================ ======================================== +================================ ========================================== Operator Description -================================ ======================================== +================================ ========================================== **-** Unary minus (2's complement). **!** Logical (boolean) NOT. **~** Tilde: bitwise not (l's complement). @@ -748,11 +806,12 @@ Operator Description **^^streq** *stringl*,*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 +================================ ========================================== - o The boolean operators generate the value 1 if the expression is true, and 0 if it is not. + * The boolean operators generate the value 1 if the expression is true, and 0 if it is not. - o A symbol is referenced if it is involved in an expression. + * A symbol is referenced if it is involved in an expression. A symbol may have any combination of attributes: undefined and unreferenced, defined and unref- erenced (i.e. declared but never used), undefined and referenced (in the case @@ -775,16 +834,16 @@ Operator Description <> != Boolean inequality. =========== ============================================== - o All binary operators have the same precedence: + * All binary operators have the same precedence: expressions are evaluated strictly left to right. - o Division or modulo by zero yields an assembly error. + * Division or modulo by zero yields an assembly error. - o The "<>" and "!=" operators are synonyms. + * The "<>" and "!=" operators are synonyms. - o Note that the modulo operator (%) is also used to introduce binary constants - (see: `Constants`_). A percent sign should be followed by at least one space if - it is meant to be a modulo operator, and is followed by a '0' or '1'. + * Note that the modulo operator (%) is also used to introduce binary constants + (see: `Constants`_). A percent sign should be followed by at least one space if + it is meant to be a modulo operator, and is followed by a '0' or '1'. `Special Forms`_ '''''''''''''''' @@ -796,12 +855,12 @@ Special Form Description **^^time** The current system time (Gemdos format). ============ ========================================= - o The "**^^date**" special form expands to the current system date, in Gemdos + * The "**^^date**" special form expands to the current system date, in Gemdos format. The format is a 16-bit word with bits 0 ...4 indicating the day of the month (1...31), bits 5...8 indicating the month (1...12), and bits 9...15 indicating the year since 1980, in the range 0...119. - o The "**^^time**" special form expands to the current system time, in Gemdos + * The "**^^time**" special form expands to the current system time, in Gemdos format. The format is a 16-bit word with bits 0...4 indicating the current second divided by 2, bits 5...10 indicating the current minute 0...59. and bits 11...15 indicating the current hour 0...23. @@ -843,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. @@ -874,6 +933,7 @@ described in the chapter on `6502 Support`_. If the location counter for the current section is odd, make it even by adding one to it. In text and data sections a zero byte is deposited if necessary. + **.long** Align the program counter to the next integral long boundary (4 bytes). @@ -881,6 +941,7 @@ described in the chapter on `6502 Support`_. segments and are actually part of the TEXT or DATA segments. Therefore, to align GPU/DSP code, align the current section before and after the GPU/DSP code. + **.phrase** Align the program counter to the next integral phrase boundary (8 bytes). @@ -888,6 +949,7 @@ described in the chapter on `6502 Support`_. segments and are actually part of the TEXT or DATA segments. Therefore, to align GPU/DSP code, align the current section before and after the GPU/DSP code. + **.dphrase** Align the program counter to the next integral double phrase boundary (16 @@ -895,6 +957,7 @@ described in the chapter on `6502 Support`_. segments and are actually part of the TEXT or DATA segments. Therefore, to align GPU/DSP code, align the current section before and after the GPU/DSP code. + **.qphrase** Align the program counter to the next integral quad phrase boundary (32 @@ -902,7 +965,8 @@ described in the chapter on `6502 Support`_. segments and are actually part of the TEXT or DATA segments. Therefore, to align GPU/DSP code, align the current section before and after the GPU/DSP code. -**.assert** *expression* [,\ *expression*...] + + **.assert** *expression* [,\ *expression*...] Assert that the conditions are true (non-zero). If any of the comma-seperated expressions evaluates to zero an assembler warning is issued. For example: @@ -922,6 +986,51 @@ described in the chapter on `6502 Support`_. be assembled into the BSS-segment, but symbols may be defined and storage may be reserved with the **.ds** directive. Each assembly starts out in the text segment. + +**.68000** +**.68020** +**.68030** +**.68040** +**.68060** + + Enable different flavours of the MC68000 family of CPUs. Bear in mind that not all + instructions and addressing modes are available in all CPUs so the correct CPU + should be selected at all times. Notice that it is possible to switch CPUs + during assembly. + +**.68881** +**.68882** + + Enable FPU support. Note that *.68882* is on by default when selecting *.68030*. + +**.56001** + + 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 @@ -1003,6 +1112,7 @@ described in the chapter on `6502 Support`_. thus confined symbols cannot be made common. The linker groups all common regions of the same name; the largest size determines the real size of the common region when the file is linked. + **.ccdef** *expression* Allows you to define names for the condition codes used by the JUMP @@ -1012,18 +1122,20 @@ described in the chapter on `6502 Support`_. Always .ccdef 0 . . . - jump Always,(r3) ; ‘Always’ is actually 0 + jump Always,(r3) ; 'Always' is actually 0 **.ccundef** *regname* Undefines a register name (regname) previously assigned using the .CCDEF directive. This is only implemented in GPU and DSP code sections. + **.dc.i** *expression* This directive generates long data values and is similar to the DC.L directive, except the high and low words are swapped. This is provided for use with the GPU/DSP MOVEI instruction. + **.dc**\ [.\ *size*] *expression* [, *expression*...] Deposit initialized storage in the current section. If the specified size is word @@ -1031,23 +1143,25 @@ described in the chapter on `6502 Support`_. is .b, then strings that are not part of arithmetic expressions are deposited byte-by-byte. If no size is specified, the default is .w. This directive cannot be used in the BSS section. + **.dcb**\ [.\ *size*] *expression1*, *expression2* Generate an initialized block of *expression1* bytes, words or longwords of the value *expression2*. If the specified size is word or long, the assembler will execute .even before generating data. If no size is specified, the default is **.w**. This directive cannot be used in the BSS section. + **.ds**\ [.\ *size*] *expression* Reserve space in the current segment for the appropriate number of bytes, words or longwords. If no size is specified, the default size is .w. If the size - is word or long, the assembler will execute .even before reserving space. This - directive can only be used in the BSS or ABS sections (in text or data, use - .dcb to reserve large chunks of initialized storage.) + is word or long, the assembler will execute .even before reserving space. + **.dsp** Switch to Jaguar DSP assembly mode. This directive must be used within the TEXT or DATA segments. + **.init**\ [.\ *size*] [#\ *expression*,]\ *expression*\ [.\ *size*] [,...] Generalized initialization directive. The size specified on the directive becomes @@ -1066,6 +1180,7 @@ described in the chapter on `6502 Support`_. No auto-alignment is performed within the line, but a **.even** is done once (before the first value is deposited) if the default size is word or long. + **.cargs** [#\ *expression*,] *symbol*\ [.\ *size*] [, *symbol*\ [.\ *size*].. .] Compute stack offsets to C (and other language) arguments. Each symbol is @@ -1098,6 +1213,7 @@ described in the chapter on `6502 Support`_. the superior file. This statement is not required, nor are warning messages generated if it is missing at the end of a file. This directive may be used inside conditional assembly, macros or **.rept** blocks. + **.equr** *expression* Allows you to name a register. This is only implemented for GPU/DSP @@ -1185,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. @@ -1239,9 +1370,11 @@ described in the chapter on `6502 Support`_. Switch to Jaguar GPU assembly mode. This directive must be used within the TEXT or DATA segments. + **.gpumain** No. Just... no. Don't ask about it. Ever. + **.prgflags** *value* Sets ST executable .PRG field *PRGFLAGS* to *value*. *PRGFLAGS* is a bit field defined as follows: @@ -1249,7 +1382,7 @@ 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_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. @@ -1260,6 +1393,7 @@ See left. 4 & 5 If these bits are set to 0 (PF_PRIVATE), the processes' ent **.regequ** *expression* Essentially the same as **.EQUR.** Included for compatibility with the GASM assembler. + **.regundef** Essentially the same as **.EQURUNDEF.** Included for compatibility with the GASM assembler. @@ -1303,6 +1437,37 @@ Assembler Syntax Description #\ *imm* Immediate ===================================== =========================================== +`68020+ Addressing Modes`_ +'''''''''''''''''''''''''' + +The following addressing modes are only valid for 68020 and newer CPUs. In these +modes most of the parameters like Base Displacement (**bd**), Outer Displacement +(**od**), Base Register (**An**) and Index Register (**Xn**) can be omitted. RMAC +will detect this and *suppress* the registers in the produced code. + +Other assemblers +use a special syntax to denote register suppression like **Zan** to suppress the Base +Register and **Rin** to suppress the Index Register. RMAC has no support for this +behaviour nor needs it to suppress registers. + +In addition, other assemblers will allow reordering of the parameters (for example +([*An*,\ *bd*])). This is not allowed in RMAC. + +Also noteworthy is that the Index Register can be an address or data register. + +To avoid internal confusion the 68040/68060 registers *DC*, *IC* and *BC* are named +*DC40*, *IC40* and *BC40* respectively. + +====================================================== ============================================================= +Assembler Syntax Description +====================================================== ============================================================= +*bd*\ (*An*, *Xi*\ [.\ *size*][*\*scale*]) Address register indirect indexed +([*bd*,\ *An*],\ *Xn*\[.\ *siz*][*\*scale*],\ *od*) Register indirect preindexed with outer displacement +([*bd*,\ *An*,\ *Xn*\[.\ *siz*][*\*scale*],\ *od*) Register indirect postindexed with outer displacement +([*bd*,\ *PC*],\ *Xn*\[.\ *siz*][*\*scale*],\ *od*) Program counter indirect preindexed with outer displacement +([*bd*,\ *PC*,\ *Xn*\[.\ *siz*][*\*scale*],\ *od*) Program counter indirect postindexed with outer displacement +====================================================== ============================================================= + `Branches`_ ''''''''''' Since RMAC is a one pass assembler, forward branches cannot be automatically @@ -1345,27 +1510,45 @@ dbns dbne ''''''''''''''''''''''''''''''''' The assembler provides "creature comforts" when it processes 68000 mnemonics: - o **CLR.x An** will really generate **SUB.x An,An**. + * **CLR.x An** will really generate **SUB.x An,An**. + + * **ADD**, **SUB** and **CMP** with an address register will really generate **ADDA**, + **SUBA** and **CMPA**. + + * The **ADD**, **AND**, **CMP**, **EOR**, **OR** and **SUB** mnemonics with immediate + first operands will generate the "I" forms of their instructions (**ADDI**, etc.) if + the second operand is not register direct. + + * All shift instructions with no count value assume a count of one. - o **ADD**, **SUB** and **CMP** with an address register will really generate **ADDA**, - **SUBA** and **CMPA**. + * **MOVE.L** is optimized to **MOVEQ** if the immediate operand is defined and + in the range -128...127. However, **ADD** and **SUB** are never translated to + their quick forms; **ADDQ** and **SUBQ** must be explicit. - o The **ADD**, **AND**, **CMP**, **EOR**, **OR** and **SUB** mnemonics with immediate - first operands will generate the "I" forms of their instructions (**ADDI**, etc.) if - the second operand is not register direct. + * All optimisations are controllable using the **.opt** directive. Refer to its + description in section `Directives`_. - o All shift instructions with no count value assume a count of one. + * All optimisations are turned off for any source line that has an exclamation mark + (*!*) on their first column. - o **MOVE.L** is optimized to **MOVEQ** if the immediate operand is defined and - in the range -128...127. However, **ADD** and **SUB** are never translated to - their quick forms; **ADDQ** and **SUBQ** must be explicit. + * 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). - o 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). - o RMAC tests all GPU/DSP restrictions and corrects them wherever possible (such as - inserting a NOP instruction when needed). - o The “(Rx+N)” addressing mode for GPU/DSP instructions is optimized to “(Rx)” - when “N” is zero. + * 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). + + * RMAC tests all GPU/DSP restrictions and corrects them wherever possible (such as + inserting a NOP instruction when needed). + + * The *(Rx+N)* addressing mode for GPU/DSP instructions is optimized to *(Rx)* + when *N* is zero. `Macros`_ ========= @@ -1389,7 +1572,8 @@ or an assembler directive. (The name may begin with a period - macros cannot be made confined the way labels or equated symbols can be). The formal argument list is optional; it is specified with a comma-seperated list of valid symbol names. Note that there is no comma between the name of the macro and the name of the -first formal argument. +first formal argument. It is not advised to begin an argument name with a numeric +value. A macro body begins on the line after the **.macro** directive. All instructions and directives, except other macro definitions, are legal inside the body. @@ -1461,14 +1645,14 @@ a statement. Arguments may be specified following the macro name; each argument is seperated by a comma. Arguments may be empty. Arguments are stored for substitution in the macro body in the following manner: - o Numbers are converted to hexadecimal. + * Numbers are converted to hexadecimal. - o All spaces outside strings are removed. + * All spaces outside strings are removed. - o Keywords (such as register names, dot sizes and "^^" operators) are converted + * Keywords (such as register names, dot sizes and "^^" operators) are converted to lowercase. - o Strings are enclosed in double-quote marks ("). + * Strings are enclosed in double-quote marks ("). For example, a hypothetical call to the macro "``mymacro``", of the form: ``mymacro A0, , 'Zorch' / 32, "^^DEFINED foo, , , tick tock`` @@ -1600,8 +1784,8 @@ common in bitmap-graphics routines). For example: `Jaguar GPU/DSP Mode`_ ====================== -RMAC will generate code for the Atari jaguar GPU and DSP custom RISC (Reduced -Instruction Set Computer) processors. See the Atari Jaguar Software reference Manual – Tom +RMAC will generate code for the Atari Jaguar GPU and DSP custom RISC (Reduced +Instruction Set Computer) processors. See the Atari Jaguar Software reference Manual - Tom & Jerry for a complete listing of Jaguar GPU and DSP assembler mnemonics and addressing modes. @@ -1620,7 +1804,182 @@ The following condition codes for the GPU/DSP JUMP and JR instructions are built HI (Higher) = %00101 T (True) = %00000 - +`Jaguar Object Processor Mode`_ +=============================== + +`What is it?`_ +'''''''''''''' + +An assembler to generate object lists for the Atari Jaguar's Object processor. + + +`Why is it here?`_ +'''''''''''''''''' + +To really utilize the OP properly, it needs an assembler. Otherwise, what +happens is you end up writing an assembler in your code to assemble the OP +list, and that's a real drag--something that *should* be handled by a proper +assembler. + + +`How do I use it?`_ +'''''''''''''''''''' + +The OP assembler works similarly to the RISC assembler; to enter the OP +assembler, you put the .objproc directive in your code (N.B.: like the RISC +assembler, it only works in a TEXT or DATA section). From there, you build +the OP list how you want it and go from there. A few caveats: you will want +to put a .org directive at the top of your list, and labels that you want to +be able to address in 68xxx code (for moving from a data section to an +address where it will be executed by the OP, for example) should be created +in .68xxx mode. + + +`What are the opcodes?`_ +'''''''''''''''''''''''' + +They are **bitmap**, **scbitmap**, **gpuobj**, **branch**, **stop**, **nop**, and **jump**. **nop** and **jump** +are psuedo-ops, they are there as a convenience to the coder. + + +`What are the proper forms for these opcodes?`_ +''''''''''''''''''''''''''''''''''''''''''''''' + +They are as follows: + +**bitmap** *data addr*, *xloc*, *yloc*, *dwidth*, *iwidth*, *iheight*, *bpp*, +*pallete idx*, *flags*, *firstpix*, *pitch* + +**scbitmap** *data addr*, *xloc*, *yloc*, *dwidth*, *iwidth*, *iheight*, +*xscale*, *yscale*, *remainder*, *bpp*, *pallete idx*, +*flags*, *firstpix*, *pitch* + +**gpuobj** *line #*, *userdata* (bits 14-63 of this object) + +**branch** VC *condition (<, =, >)* *line #*, *link addr* + +**branch** OPFLAG, *link addr* + +**branch** SECHALF, *link addr* + +**stop** + +**nop** + +**jump** *link addr* + +Note that the *flags* field in bitmap and scbitmap objects consist of the +following: **REFLECT**, **RMW**, **TRANS**, **RELEASE**. They can be in any order (and +should be separated by whitespace **only**), and you can only put a maximum of +four of them in. Further note that with bitmap and scbitmap objects, all the +parameters after *data addr* are optional--if they are omitted, they will +use defaults (mostly 0, but 1 is the default for pitch). Also, in the +scbitmap object, the *xscale*, *yscale*, and *remainder* fields can be +floating point constants/expressions. *data addr* can refer to any address +defined (even external!) and the linker (rln v1.6.0 or greater) will +properly fix up the address. + + +`What do they do?`_ +''''''''''''''''''' + +Pretty much what you expect. It's beyond the scope of this little note to +explain the Jaguar's Object Processor and how it operates, so you'll have to +seek explanations for how they work elsewhere. + + +`Why do I want to put a *.org* directive at the top of my list?`_ +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +You want to put a *.org* directive at the top of your list because otherwise +the assembler will not know where in memory the object list is supposed +go--then when you move it to its destination, the object link addresses will +all be wrong and it won't work. + + +`Why would I copy my object list to another memory location?`_ +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Simple: because the OP destroys the list as it uses it to render the screen. +If you don't keep a fresh copy stashed away somewhere to refresh it before +the next frame is rendered, what you see on the screen will not be what you +expect, as the OP has scribbled all over it! + + +`Does the assembler do anything behind my back?`_ +''''''''''''''''''''''''''''''''''''''''''''''''' + +Yes, it will emit **NOP** s to ensure that bitmaps and scbitmaps are on proper +memory boundaries, and fixup link addresses as necessary. This is needed +because of a quirk in how the OP works (it ORs constants on the address +lines to get the phrases it needs and if they are not zeroes, it will fail +in bizarre ways). It will also set all *ypos* constants on the correct +half-line (as that's how the OP views them). + + +`Why can't I define the link addresses for all the objects?`_ +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +You really, *really* don't want to do this. Trust me on this one. + +`How about an example of an object list?`_ +'''''''''''''''''''''''''''''''''''''''''' + + :: + + objList = $10000 + bRam = $20000 + ; + .68000 + objects: ; This is the label you will use to address this in 68K code + .objproc ; Engage the OP assembler + .org objList ; Tell the OP assembler where the list will execute + ; + branch VC < 69, .stahp ; Branch to the STOP object if VC < 69 + branch VC > 241, .stahp ; Branch to the STOP object if VC > 241 + bitmap bRAM, 22, 70, 24, 24, 22, 4 + bitmap bRAM, 20+96+96, 70, 24, 24, 22, 4, 0, REFLECT + scbitmap tms, 20, 70, 1, 1, 8, 3.0, 3.0, 2.9999, 0, 0, TRANS + scbitmap tmsShadow, 23, 73, 1, 1, 8, 3.0, 3.0, 2.9999, 0, 3, TRANS + bitmap sbRelBM, 30, 108, 3, 3, 8, 0, 1, TRANS + bitmap txt1BM, 46, 132, 3, 3, 8, 0, 2, TRANS + bitmap txt2BM, 46, 148, 3, 3, 8, 0, 2, TRANS + bitmap txt3BM, 22, 164, 3, 3, 8, 0, 2, TRANS + jump .haha + .stahp: + stop + .haha: + jump .stahp + + +`DSP 56001 Mode`_ +================= + +RMAC fully supports Motorola's DSP56001 as used on the Atari Falcon and can output +binary code in the two most popular formats: *.lod* (ASCII dump, supported by the +Atari Falcon XBIOS) and *.p56* (binary equivalent of *.lod*) + +`Differences from Motorola's assembler`_ +'''''''''''''''''''''''''''''''''''''''' + +- Motorola's assembler aliases **and #xxx,reg** with **andi #xxx,reg** and can + 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** + 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, + such labels will not be treated as local. +- Macros syntax is different from Motorola's assembler. This includes local + labels inside macros. The user is encouraged to study the `Macros`_ section + and compare syntactical differences. +- 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. + Instead, the value needs to be split into two parts separated by **:**. + `6502 Support`_ =============== RMAC will generate code for the Motorola 6502 microprocessor. This chapter @@ -1671,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. @@ -1776,145 +2135,181 @@ order, along with a short description of what may have caused the problem. **.cargs syntax** Syntax error in **.cargs** directive. + **.comm symbol already defined** You tried to ``.comm`` a symbol that was already defined. + **.ds permitted only in BSS** You tried to use ``.ds`` in the text or data section. + **.init not permitted in BSS or ABS** 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. + **External quick reference** You tried to make the immediate operand of a **moveq**, **subq** or **addq** instruction external. + **PC-relative expr across sections** You tried to make a PC-relative reference to a location contained in another section. + **[bwsl] must follow '.' in symbol** You tried to follow a dot in a symbol name with something other than one of the four characters 'B', 'W', 'S' or 'L'. + **addressing mode syntax** You made a syntax error in an addressing mode. + **assert failure** One of your **.assert** directives failed! + **bad (section) expression** - You tried to mix and match sections in an expression + You tried to mix and match sections in an expression. + **bad 6502 addressing mode** The 6502 mnemonic will not work with the addressing mode you specified. + **bad expression** There's a syntax error in the expression you typed. + **bad size specified** You tried to use an inappropriate size suffix for the instruction. Check your 68000 manual for allowable sizes. + **bad size suffix** You can't use .b (byte) mode with the **movem** instruction. + **cannot .globl local symbol** You tried to make a confined symbol global or common. + **cannot initialize non-storage (BSS) section** You tried to generate instructions (or data, with dc) in the BSS or ABS section. + **cannot use '.b' with an address register** You tried to use a byte-size suffix with an address register. The 68000 does not perform byte-sized address register operations. + **directive illegal in .6502 section** You tried to use a 68000-oriented directive in the 6502 section. + **divide by zero** The expression you typed involves a division by zero. + **expression out of range** The expression you typed is out of range for its application. + **external byte reference** You tried to make a byte-sized reference to an external symbol, which the - object file format will not allow + object file format will not allow. + **external short branch** You tried to make a short branch to an external symbol, which the linker cannot handle. + **extra (unexpected) text found after addressing mode** RMAC thought it was done processing a line, but it ran up against "extra" stuff. Be sure that any comment on the line begins with a semicolon, and check for dangling commas, etc. + **forward or undefined .assert** The expression you typed after a **.assert** directive had an undefined value. Remember that RMAC is one-pass. + **hit EOF without finding matching .endif** The assembler fell off the end of last input file without finding a **.endif** to match an . it. You probably forgot a **.endif** somewhere. + **illegal 6502 addressing mode** The 6502 instruction you typed doesn't work with the addressing mode you specified. + **illegal absolute expression** You can't use an absolute-valued expression here. + **illegal bra.s with zero offset** You can't do a short branch to the very next instruction (read your 68000 manual). + **illegal byte-sized relative reference** The object file format does not permit bytes contain relocatable values; you tried to use a byte-sized relocatable expression in an immediate addressing mode. + **illegal character** Your source file contains a character that RMAC doesn't allow. (most control characters fall into this category). + **illegal initialization of section** You tried to use .dc or .dcb in the BSS or ABS sections. + **illegal relative address** The relative address you specified is illegal because it belongs to a different section. + **illegal word relocatable (in .PRG mode)** You can't have anything other than long relocatable values when you're gener- ating a **.PRG** file. + **inappropriate addressing mode** The mnemonic you typed doesn't work with the addressing modes you specified. Check your 68000 manual for allowable combinations. + **invalid addressing mode** The combination of addressing modes you picked for the **movem** instruction are not implemented by the 68000. Check your 68000 reference manual for details. + **invalid symbol following ^^** What followed the ^^ wasn't a valid symbol at all. + **mis-nested .endr** The assembler found a **.endr** directive when it wasn't prepared to find one. Check your repeat-block nesting. + **mismatched .else** The assembler found a **.else** directive when it wasn't prepared to find one. Check your conditional assembly nesting. + **mismatched .endif** The assembler found a **.endif** directive when it wasn't prepared to find one. @@ -1942,70 +2337,88 @@ order, along with a short description of what may have caused the problem. The assembler expected to see a symbol/filename/string (etc...), but found something else instead. In most cases the problem should be obvious. + **misuse of '.', not allowed in symbols** You tried to use a dot (.) in the middle of a symbol name. + **mod (%) by zero** The expression you typed involves a modulo by zero. + **multiple formal argument definition** The list of formal parameter names you supplied for a macro definition includes two identical names. + **multiple macro definition** You tried to define a macro which already had a definition. + **non-absolute byte reference** You tried to make a byte reference to a relocatable value, which the object file format does not allow. + **non-absolute byte value** You tried to dc.b or dcb.b a relocatable value. Byte relocatable values are not permitted by the object file format. + **register list order** You tried to specify a register list like **D7-D0**, which is illegal. Remember that the first register number must be less than or equal to the second register number. + **register list syntax** You made an error in specifying a register list for a **.reg** directive or a **.movem** instruction. + **symbol list syntax** You probably forgot a comma between the names of two symbols in a symbol list, or you left a comma dangling on the end of the line. + **syntax error** This is a "catch-all" error. + **undefined expression** The expression has an undefined value because of a forward reference, or an undefined or external symbol. + **unimplemented addressing mode** You tried to use 68020 "square-bracket" notation for a 68020 addressing mode. RMAC does not support 68020 addressing modes. + **unimplemented directive** You have found a directive that didn't appear in the documentation. It doesn't work. + **unimplemented mnemonic** - You've found an assembler for documentation) bug. + You've found a bug. + **unknown symbol following ^^** You followed a ^^ with something other than one of the names defined, ref- erenced 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. + **unterminated string** You specified a string starting with a single or double quote, but forgot to type the closing quote. + **write error** The assembler had a problem writing an object file. This is usually caused by