X-Git-Url: http://shamusworld.gotdns.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=docs%2Frmac.rst;h=b3d25db0eab34c65016e5c4b8e9e14646d78038e;hb=e6e125acd974146ee369ab3613aaafe4df01f614;hp=9cddd4b2b9f6f5d0ec4adb5f09a6ec3aaabefbdf;hpb=7d748dc6e2259984c9093c48d84ae1ed280632ad;p=rmac diff --git a/docs/rmac.rst b/docs/rmac.rst index 9cddd4b..b3d25db 100644 --- a/docs/rmac.rst +++ b/docs/rmac.rst @@ -17,12 +17,10 @@ the accuracy of printed or duplicated material after the date of publication and disclaims liability for changes, errors or omissions.* -*Copyright © 2011-2020, Reboot* +*Copyright © 2011-2022, the rmac authors* *All rights reserved.* -*Reboot Document number F00000K-001 Rev. A.* - Contents ======== @@ -125,9 +123,10 @@ Switch Description -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. +-g Generate source level debug info. Requires BSD COFF 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 +-l\ *\*[filename]* Create an output listing file without pagination. -m\ *cpu* Switch CPU type `68000 - MC68000` @@ -157,11 +156,11 @@ Switch Description +o\ *0-30*/*p* Enable specific optimisation ~o\ *0-30*/*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 (on by default)` + `1: move.l #x,Dn/An to moveq` - `2: Word branches to short (on by default)` + `2: Word branches to short` `3: Outer displacement 0(An) to (An)` @@ -181,7 +180,7 @@ Switch Description `11: 56001 Auto convert short addressing mode to long (default: on)` - `o30: Enforce PC relative (alternative name: op)` + `30: Enforce PC relative (alternative name: op)` -p Produce an executable (**.prg**) output file. -ps Produce an executable (**.prg**) output file with symbols. @@ -203,8 +202,9 @@ Switch Description -s Warn about unoptimized long branches and applied optimisations. -u Force referenced and undefined symbols global. -v Verbose mode (print running dialogue). --x Turn on debugging mode +-x Turn on debugging mode. -yn Set listing page size to n lines. +-4 Use C style operator precedence. file\ *[s]* Assemble the specified file. =================== =========== @@ -234,6 +234,19 @@ the table. file is created. Beware! If an assembly produces no errors, any error file from a previous assembly is not removed. +**-g** + The **-g** switch causes RMAC to generate source-level debug symbols using the + stabs format. When linked with a compatible linker such as RLN, these symbols + can be used by source-level debuggers such as rdbjag, wdb, or gdb to step + through assembly code line-by-line with all the additional context of labels, + macros, constants, register equates, etc. available in the original assembly + listings rather than relying on the simple disassembly or raw machine code + available when stepping through instruction-by-instruction. This option only + works with the BSD COFF object file format, as the others do not use the + a.out-style symbol tables required by stabs, and RMAC does not currently + support placing stabs debug symbols in their own dedicated section in ELF + format object files. + **-i** The **-i** switch allows automatic directory searching for include files. A list of semi-colon seperated directory search paths may be mentioned immediately @@ -296,6 +309,9 @@ the table. space), sets the number of lines in a page. RMAC will produce *N* lines before emitting a form-feed. If *N* is missing or less than 10 an error message is generated. +**-4** + Use C style order of precedence in expressions. See `Order of Evaluation`_ for more + information. `Using RMAC`_ =============== @@ -425,7 +441,8 @@ necessary to make other assemblers' source code assemble. character codes. Watch out for GEMDOS path names in ASCII constants - you will have to convert them to double-backslashes. * Expression evaluation is done left-to-right without operator precedence. Use parentheses to - force the expression evaluation as you wish. + force the expression evaluation as you wish. Alternatively, use the **-4** switch to switch + to C style precedence. For more information refer to `Order of Evaluation`_. * 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. @@ -633,7 +650,7 @@ and may not be used as symbols (e.g. labels, equates, or the names of macros): 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 r15 + r8 r9 r10 r11 r12 r13 r14 r15 6502: x y a DSP56001: @@ -746,6 +763,24 @@ true. Thus the expression "1+2*3" evaluates to 9, not 7. However, precedence may be forced with parenthesis (**()**) or square-brackets (**[]**). +All the above behavior is the default. However if the command line switch **-4** +is used, then C style of operator precedence is enforced. The following list +shows the order of precedence in this mode, from lowest to highest: + + * bitwise XOR ^ + + * bitwise OR | + + * bitwise AND & + + * relational = < <= >= > != + + * shifts << >> + + * sum + - + + * product * / + `Types`_ ''''''''' Expressions belong to one of three classes: undefined, absolute or relocatable. An @@ -842,7 +877,9 @@ Operator Description =========== ============================================== * All binary operators have the same precedence: - expressions are evaluated strictly left to right. + expressions are evaluated strictly left to right, + with the exception of the **-4** switch. For more information + refer to `Order of Evaluation`_. * Division or modulo by zero yields an assembly error. @@ -998,7 +1035,14 @@ 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. - **.assert** *expression* [,\ *expression*...] +**.align** *expression* + + A generalised version of the above directives, this will align the program + counter to the boundary of the specified value. Note that there is not much + error checking happening (only values 0 and 1 are rejected). Also note that + in DSP56001 mode the align value is assumed to be in DSP words, i.e. 24 bits. + +**.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: