X-Git-Url: http://shamusworld.gotdns.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=rmac.rst;fp=rmac.rst;h=0000000000000000000000000000000000000000;hb=2270aa01ead427399fa2a7b800da2a5397fc3069;hp=91571d9211d6284ee86edd5b8b7095f6f0d63a41;hpb=71cec8e7896b200c6ae63ebc428339bef147240a;p=rmac diff --git a/rmac.rst b/rmac.rst deleted file mode 100644 index 91571d9..0000000 --- a/rmac.rst +++ /dev/null @@ -1,1927 +0,0 @@ -RMAC ----- -68000 Macro Assembler -===================== -Reference Manual -================ -version 1.4.2 -============= - - -*NOTE: Every effort has been made to ensure the accuracy and robustness of this -manual and the associated software. However, because Reboot is constantly improving -and updating its computer software, it is unable to guarantee -the accuracy of printed or duplicated material after the date of publication and -disclaims liability for changes, errors or omissions.* - - -*Copyright © 2011-2015, Reboot* - -*All rights reserved.* - -*Reboot Document number F00000K-001 Rev. A.* - -Contents -======== - -.. contents:: - -Introduction -============ - -Introduction -'''''''''''' -This document describes RMAC, a fast macro assembler for the 68000. RMAC currently -runs on the any POSIX compatible platform and the Atari ST. It was initially written -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. - -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 -has creature comfort that are usually neglected in such back-end assemblers. It -supports include files, macros, symbols with limited scope, some limited control -structures, and other features. RMAC is also blindingly fast, another feature -often sadly and obviously missing in today's assemblers.[1]_ - -RMAC is not entirely compatible with the AS68 assembler provided with -the original Atari ST Developer's Kit, but most changes are minor and a few minutes -with an editor should allow you to assemble your current source files. If you are an -AS68 user, before you leap into the unknown please read the section on Notes for -AS68 Users. - -This manual was typeset with TEX and the Computer Modern fonts, and it -was printed on the Atari SLM-804 laser printer with a MEGA ST. Except for 200 -lines of assembly language, the assembler is written entirely in C. - -.. [1] It processes 30,000 lines a minute on a lightly loaded VAX 11/780; maybe 40,000 on a 520-ST with an SH-204 hard disk. Yet it could be sped up even more with some effort and without resorting to assembly language; C doesn't have to be slow! - -`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 - and summarizes the most recent changes to the tools. - -* Hard disk users can simply copy the executable files to their work or binary - directories. People with floppy disks can copy the executables to ramdisks, - install the assembler with the -q option, or even work right off of the floppies. - -* You will need an editor that can produce "normal" format text files. Micro - Emacs will work well, as will most other commercial program editors, but not - most word processors (such as First Word or Microsoft Write). - -* You will probably want to examine or get a listing of the file "ATARI.S". It - contains lots of definitions for the Atari ST, including BIOS variables, most - BIOS, XBIOS and GEMDOS traps, and line-A equates. We (or you) could - split the file up into pieces (a file for line-A equates, a file for hardware and - BIOS variables and so on), but RMAC is so fast that it doesn't matter - much. - -* Read the rest of the manual, especially the first two chapters on The Command Line and Using RMAC. - Also, `Notes for migrating from other 68000 assemblers`_ will save a lot of time and frustration in the long run. - The distribution disk contains example - programs that you can look at, assemble and modify. - -`The Command Line`_ -''''''''''''''''''' - -The assembler is called "**rmac**" or "**rmac.prg**". The command line takes the form: - - **mac** [*switches*] [*files* ...] - -A command line consists of any number of switches followed by the names of files -to assemble. A switch is specified with a dash (**-**) followed immediately by a key -character. Key characters are not case-sensitive, so "**-d**" is the same as "**-D**". Some -switches accept (or require) arguments to immediately follow the key character, -with no spaces in between. - -Switch order is important. Command lines are processed from left to right in -one pass, and switches usually take effect when they are encountered. In general it -is best to specify all switches before the names of any input files. - -If the command line is entirely empty then RMAC prints a copyright message -and enters an "interactive" mode, prompting for successive command lines -with a star (\*). An empty command line will exit (See the examples in the chapter -on `Using RMAC`_). After each assembly in interactive mode, the assembler -will print a summary of the amount of memory used, the amount of memory left, -the number of lines processed, and the number of seconds the assembly took. - -Input files are assumed to have the extension "**.s**"; if a filename has no extension -(i.e. no dot) then "**.s**" will be appended to it. More than one source filename may be -specified: the files are assembled into one object file, as if they were concatenated. - -RMAC normally produces object code in "**file.o**" if "**file.s**" is the first -input filename. If the first input file is a special character device, the output name -is noname.o. The **-o** switch (see below) can be used change the output file name. - - -=================== =========== -Switch Description -=================== =========== --dname\ *[=value]* Define symbol, with optional value. --e\ *[file[.err]]* Direct error messages to the specified file. --fa TODO: add me --fb BSD COFF --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. --p Produce an executable (**.prg**) output file. --ps Produce an executable (**.prg**) output file with 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)` - - `-rp Phrase (8 bytes)` - - `-rd Double Phrase (16 bytes)` - - `-rq Quad Phrase (32 bytes)` --s Warn about unoptimized long branches. --u Assume that all undefined symbols are external. --v Verbose mode (print running dialogue). --yn Set listing page size to n lines. --6 "Back end" mode for Alcyon C68. -file\ *[s]* Assemble the specified file. -=================== =========== - -The switches are described below. A summary of all the switches is given in -the table. - -**-d** - The **-d** switch permits symbols to be defined on the command line. The name - of the symbol to be defined immediately follows the switch (no spaces). The - symbol name may optionally be followed by an equals sign (=) and a decimal - number. If no value is specified the symbol's value is zero. The symbol at- - tributes are "defined, not referenced, and absolute". This switch is most useful - for enabling conditionally-assembled debugging code on the command line; for - example: - - :: - - -dDEBUG -dLoopCount=999 -dDebugLevel=55 - -**-e** - The -e switch causes RMAC to send error messages to a file, instead of the - console. If a filename immediately follows the switch character, error messages - are written to the specified file. If no filename is specified, a file is created with - the default extension "**.err**" and with the root name taken from the first input - file name (e.g. error messages are written to "**file.err**" if "**file**" or "**file.s**" is - the first input file name). If no errors are encountered, then no error listing - file is created. Beware! If an assembly produces no errors, any error file from - a previous assembly is not removed. - -**-i** - The **-i** switch allows automatic directory searching for include files. A list of - semi-colon seperated directory search paths may be mentioned immediately - following the switch (with no spaces anywhere). For example: - - :: - - -im:;c:include;c:include\sys - - will cause the assembler to search the current directory of device **M**, and the - directories include and include\sys on drive **C**. If *-i* is not specified, and the - enviroment variable "**MACPATH**" exists, its value is used in the same manner. - For example, users of the Mark Williams shell could put the following line in - their profile script to achieve the same result as the **-i** example above: - - :: - - setenv MACPATH="m:;c:include;c:include\sys" -**-l** - The -l switch causes RMAC to generate an assembly listing file. If a file- - name immediately follows the switch character, the listing is written to the - specified file. If no filename is specified, then a listing file is created with the - default extension "**.prn**" and with the root name taken from the first input file - name (e.g. the listing is written to "**file.prn**" if "**file**" or "**file.s**" is the first - input file name). -**-o** - The -o switch causes RMAC to write object code on the specified file. No - default extension is applied to the filename. For historical reasons the filename - can also be seperated from the switch with a space (e.g. "**-o file**"). - -**-p** - -**-ps** - The **-p** and **-ps** switches cause RMAC to produce an Atari ST executable - file with the default extension of "**.prg**". If there are any external references - at the end of the assembly, an error message is emitted and no executable file - is generated. The **-p** switch does not write symbols to the executable file. The - **-ps** switch includes symbols (Alcyon format) in the executable file. -**-q** - The **-q** switch is aimed primarily at users of floppy-disk-only systems. It causes - RMAC to install itself in memory, like a RAMdisk. Then the program - **m.prg** (which is very short - less than a sector) can be used instead of - **mac.prg**, which can take ten or twelve seconds to load. (**NOTE** not available - for now, might be re-implemented in the future). -**-s** - The **-s** switch causes RMAC to generate a list of unoptimized forward - branches as warning messages. This is used to point out branches that could - have been short (e.g. "bra" could be "bra.s"). -**-u** - The **-u** switch takes effect at the end of the assembly. It forces all referenced - and undefined symbols to be global, exactly as if they had been made global - with a **.extern** or **.globl** directive. This can be used if you have a lot of - external symbols, and you don't feel like declaring them all external. -**-v** - The **-v** switch turns on a "verbose" mode in which RMAC prints out (for - example) the names of the files it is currently processing. Verbose mode is - automatically entered when RMAC prompts for input with a star. -**-y** - The **-y** switch, followed immediately by a decimal number (with no intervening - 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. - -`Using RMAC`_ -=============== - -Let's assemble and link some example programs. These programs are included -on the distribution disk in the "**EXAMPLES**" directory - you should copy them to -your work area before continuing. In the following examples we adopt the conven- -tions that the shell prompt is a percent sign (%) and that your input (the stuff you -type) is presented in **bold face**. - -If you have been reading carefully, you know that RMAC can generate -an executable file without linking. This is useful for making small, stand alone -programs that don't require externals or library routines. For example, the following -two commands: - - :: - - % mac examples - % aln -s example.s - -could be replaced by the single command: - - :: - - % rmac -ps example.s - -since you don't need the linker for stand-alone object files. - -Successive source files named in the command line are are concatenated, as in -this example, which assembles three files into a single executable, as if they were -one big file: - - :: - - % rmac -p bugs shift images - -Of course you can get the same effect by using the **.include** directive, but sometimes -it is convenient to do the concatenation from the command line. - - Here we have an unbelievably complex command line: - - :: - - % rmac -lzorf -y95 -o tmp -ehack -Ddebug=123 -ps example - -This produces a listing on the file called "**zorf.prn**" with 95 lines per page, writes -the executable code (with symbols) to a file called "**tmp.prg**", writes an error listing -to the file "**hack.err**", specifies an include-file path that includes the current -directory on the drive "**M:**," defines the symbol "**debug**" to have the value 123, and -assembles the file "**example.s**". (Take a deep breath - you got all that?) - -One last thing. If there are any assembly errors, RMAC will terminate -with an exit code of 1. If the assembly succeeds (no errors, although there may be -warnings) the exit code will be 0. This is primarily for use with "make" utilities. - -`Interactive Mode`_ -''''''''''''''''''' -If you invoke RMAC with an empty command line it will print a copyright -message and prompt you for more commands with a star (*****). This is useful if you -are used to working directly from the desktop, or if you want to assemble several files -in succession without having to reload the assembler from disk for each assembly. - -In interactive mode, the assembler is also in verbose mode (just as if you had -specified **-v** on each command line): - - :: - - %. rmac - - MADMAC Atari Macro Assembler - Copyright 1987 Atari Corporation - Beta version 0.12 Jun 1987 lmd - - * -ps example - [Including: example.s] - [Including: atari.s] - [Leaving: atari.s] - [Leaving; example. a] - [Writing executable tile: example.prg - 36K used, 3868K left, 850 lines, 2.0 seconds - - -You can see that the assembler gave a "blow-by-blow" account of the files it processed, -as well as a summary of the assembly's memory usage, the number of lines -processed (including macro and repeat-block expansion), and how long the assembly -took - -The assembler prompts for another command with the star. At this point you -can either type a new command line for the assembler to process, or you can exit -by typing control-C or an empty line. - -Things You Should Be Aware Of -''''''''''''''''''''''''''''' -RMAC is a one pass assembler. This means that it gets all of its work done by -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- - 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 - - o 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 - lines that contained undefined symbols. - o 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. - -Forward Branches -'''''''''''''''' -RMAC does not optimize forward branches for you, but it will tell you about -them if you use the -s (short branch) option: - - :: - - % mac -s example.s - "example.s", line 20: warning: unoptimized short branch - -With the -e option you can redirect the error output to a file, and determine by -hand (or editor macros) which forward branches are safe to explicitly declare short. - -`Notes for migrating from other 68000 assemblers`_ -'''''''''''''''''''''''''''''''''''''''''''''''''' -RMAC is not entirely compatible with the other popular assemblers -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, 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). - -o Conditional assembly directives are called **if**, **else** and **endif**. Devpac and vasm called these - **ifne**, **ifeq** (etc.), and **endc**. -o 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. - 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: - - :: - - * = 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 - 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 - force the expression evaluation as you wish. - -o 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. For example the following source: - - :: - - rsreset - label1: rs.w 1 - label2: rs.w 10 - label3: rs.l 5 - label4: rs.b 2 - - 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 - - size_so_far equ ^^abscount - -o A rare case: if your macro contains something like: - - :: - - macro test - move.l #$\1,d0 - endm - - test 10 - - then by the assembler's design this will fail as the parameters are automatically converted to hex. Changing the code like his works: - - :: - - macro test - move.l #\1,d0 - endm - - 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- - 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 - carriage-return alone. - - o 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`_ -================ - -`Statements`_ -''''''''''''' -A statement may contain up to four fields which are identified by order of ap- -pearance and terminating characters. The general form of an assembler statement -is: - - :: - - label: operator operand(s) ; comment - -The label and comment fields are optional. An operand field may not appear -without an operator field. Operands are seperated with commas. Blank lines are -legal. If the first character on a line is an asterisk (*) or semicolon (;) then the -entire line is a comment. A semicolon anywhere on the line (except in a string) -begins a comment field which extends to the end of the line. - -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`_). - -`Equates`_ -'''''''''' -A statement may also take one of these special forms: - - *symbol* **equ** *expression* - - *symbol* **=** *expression* - - *symbol* **--** *expression* - - *symbol* **set** *expression* - - *symbol* **reg** *register list* - -The first two forms are identical; they equate the symbol to the value of an -expression, which must be defined (no forward references). The third form, double- -equals (==), is just like an equate except that it also makes the symbol global. (As -with labels, it is illegal to make a confined equate global.) The fourth form allows -a symbol to be set to a value any number of times, like a variable. The last form -equates the symbol to a 16-bit register mask specified by a register list. It is possible -to equate confined symbols (see: `Symbols and Scope`_). For example: - - :: - - cr equ 13 carriage-return - if = 10 line-feed - DEBUG == 1 global debug flag - count set 0 variable - count set count + 1 increment variable - .rags reg d3-d7/a3-a6 register list - .cr 13 confined equate - -`Symbols and Scope`_ -'''''''''''''''''''' -Symbols may start with an uppercase or lowercase letter (A-Z a-z), an underscore -(**_**), a question mark (**?**) or a period (**.**). Each remaining character may be an -upper or lowercase letter, a digit (**0-9**), an underscore, a dollar sign (**$**), or a question -mark. (Periods can only begin a symbol, they cannot appear as a symbol -continuation character). Symbols are terminated with a character that is not a -symbol continuation character (e.g. a period or comma, whitespace, etc.). Case is -significant for user-defined symbols, but not for 68000 mnemonics, assembler direc- -tives and register names. Symbols are limited to 100 characters. When symbols -are written to the object file they are silently truncated to eight (or sixteen) char- -acters (depending on the object file format) with no check for (or warnings about) -collisions. - - For example, all of the following symbols are legal and unique: - - :: - - reallyLougSymbolliame .reallyLongConfinadSymbollame - al0 ret move dc frog aae a9 ???? - .al .ret .move .dc .frog .a9 .9 ???? - .0 .00 .000 .1 .11. .111 . ._ - _frog ?zippo? sys$syetem atari Atari ATARI aTaRi - -while all of the following symbols are illegal: - - :: - - 12days dc.10 dc.z 'quote .right.here - @work hi.there $money$ ~tilde - - -Symbols beginning with a period (**.**) are *confined*; their scope is between two -normal (unconfined) labels. Confined symbols may be labels or equates. It is illegal -to make a confined symbol global (with the ".globl" directive, a double colon, or a -double equals). Only unconfined labels delimit a confined symbol's scope; equates -(of any kind) do not count. For example, all symbols are unique and have unique -values in the following: - - :: - - zero:: subq.w $1,d1 - bmi.s .ret - .loop: clr.w (a0)+ - dbra d0,.loop - .ret: rta - FF:: subq.w #1,d1 - bmi.s .99 - .loop: move.w -1,(a0)+ - dbra d0,.loop - .99: its - -Confined symbols are useful since the programmer has to be much less inventive -about finding small, unique names that also have meaning. - -It is legal to define symbols that have the same names as processor mnemonics -(such as "**move**" or "**rts**") or assembler directives (such as "**.even**"). Indeed, one -should be careful to avoid typographical errors, such as this classic (in 6502 mode): - - :: - - .6502 - .org = $8000 - - -which equates a confined symbol to a hexadecimal value, rather than setting the -location counter, which the .org directive does (without the equals sign). - -`Keywords`_ -''''''''''' -The following names, in all combinations of uppercase and lowercase, are keywords -and may not be used as symbols (e.g. labels, equates, or the names of macros): - - :: - - equ set reg - sr ccr pc sp ssp usp - dO di d2 d3 d4 d5 d6 d7 - a0 al a2 a3 a4 a5 a6 aT - r0 ri r2 r3 r4 r5 r6 r7 - r8 r9 r10 1'11 r12 rl3 ri4 ri5 - -`Constants`_ -'''''''''''' -Numbers may be decimal, hexadecimal, octal, binary or concatenated ASCII. The -default radix is decimal, and it may not be changed. Decimal numbers are specified -with a string of digits (**0-9**). Hexadecimal numbers are specified with a leading -dollar sign (**$**) followed by a string of digits and uppercase or lowercase letters (**A-F -a-f**). Octal numbers are specified with a leading at-sign (**@**) followed by a string -of octal digits (**0-7**). Binary numbers are specified with a leading percent sign -(**%**) followed by a string of binary digits (**0-1**). Concatenated ASCII constants are -specified by enclosing from one to four characters in single or double quotes. For -example: - - :: - - 1234 *decimal* - $1234 *hexadecimal* - @777 *octal* - %10111 *binary* - "z" *ASCII* - 'frog' *ASCII* - -Negative numbers Are specified with a unary minus (**-**). For example: - - :: - - -5678 -@334 -$4e71 - -%11011 -'z' -"WIND" - -`Strings`_ -'''''''''' -Strings are contained between double (") or single ( ') quote marks. Strings may -contain non-printable characters by specifying "backslash" escapes, similar to the -ones used in the C programming language. RMAC will generate a warning if a -backslash is followed by a character not appearing below: - - :: - - \\ $5c backslash - \n $0a line-feed (newline) - \b $08 backspace - \t $09 tab - \r $0c1 carriage-return - \f $0c form-feed - \e $1b escape - \' $27 single-quote - \" $22 double-quote - -It is possible for strings (but not symbols) to contain characters with their high -bits set (i.e. character codes 128...255). - -You should be aware that backslash characters are popular in GEMDOS path -names, and that you may have to escape backslash characters in your existing source -code. For example, to get the file "'c:\auto\ahdi.s'" you would specify the string -"`c:\\auto\\ahdi.s`". - -`Register Lists`_ -''''''''''''''''' -Register lists are special forms used with the **movem** mnemonic and the **.reg** -directive. They are 16-bit values, with bits 0 through 15 corresponding to registers -**D0** through **A7**. A register list consists of a series of register names or register -ranges seperated by slashes. A register range consists of two register names, Rm -and Rn,m> 1, line3/4 - -Line 1 deposits two longwords that point to line 2. Line 2 deposits two longwords -that point to line 1. Line 3 deposits two longwords that have the absolute value -eight. The fourth line will result in an assembly error, since the expressions (re- -spectively) attempt to add two relocatable values, shift a relocatable value right by -one, and divide a relocatable value by four. - -The pseudo-symbol "*****" (star) has the value that the current section's location -counter had at the beginning of the current source line. For example, these two -statements deposit three pointers to the label "**bar**": - - :: - - too: dc.l *+4 - bar: dc.l *, * - -Similarly, the pseudo-symbol "**$**" has the value that the current section's location -counter has, and it is kept up to date as the assembler deposits information -"across" a line of source code. For example, these two statements deposit four -pointers to the label "zip": - - :: - - zip: dc.l $+8, $+4 - zop: dc.l $, $-4 - -`Unary Operators`_ -'''''''''''''''''' - -================================ ======================================== -Operator Description -================================ ======================================== -**-** Unary minus (2's complement). -**!** Logical (boolean) NOT. -**~** 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. -**^^macdef** *macroName* True if the macro is defined. -**^^abscount** Returns the size of current .abs section -================================ ======================================== - - o 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 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 - of a forward or external reference), or defined and referenced. - - - -`Binary Operators`_ -''''''''''''''''''' - -=========== ============================================== -Operator Description -=========== ============================================== -\ + - * / The usual arithmetic operators. -% Modulo. -& | ^ Bit-wise **AND**, **OR** and **Exclusive-OR**. -<< >> Bit-wise shift left and shift right. -< <= >= > Boolean magnitude comparisons. -= Boolean equality. -<> != Boolean inequality. -=========== ============================================== - - o All binary operators have the same precedence: expressions are evaluated - strictly left to right. - - o Division or modulo by zero yields an assembly error - - o 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'. - -`Special Forms`_ -'''''''''''''''' - -============ ========================================= -Special Form Description -============ ========================================= -**^^date** The current system date (Gemdos format). -**^^time** The current system time (Gemdos format). -============ ========================================= - - o 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 - 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. - -`Example Expressions`_ -'''''''''''''''''''''' - - :: - - line address contents source code - ---- ------- -------- ------------------------------- - 1 00000000 4480 lab1: neg.l d0 - 2 00000002 427900000000 lab2: clr.w lab1 - 3 =00000064 equ1 = 100 - 4 =00000096 equ2 = equ1 + 50 - 5 00000008 00000064 dc.l lab1 + equ1 - 6 0000000C 7FFFFFE6 dc.l (equl + ~equ2) >> 1 - 7 00000010 0001 dc.w ^^defined equl - 8 00000012 0000 dc.w ^^referenced lab2 - 9 00000014 00000002 dc.l lab2 - 10 00000018 0001 dc.w ^^referenced lab2 - 11 0000001A 0001 dc.w lab1 = (lab2 - 6) - -Lines 1 through four here are used to set up the rest of the example. Line 5 deposits -a relocatable pointer to the location 100 bytes beyond the label "**lab1**". Line 6 is -a nonsensical expression that uses the and right-shift operators. Line 7 deposits -a word of 1 because the symbol "**equ1**" is defined (in line 3). - -Line 8 deposits a word of 0 because the symbol "**lab2**", defined in line 2, has -not been referenced. But the expression in line 9 references the symbol "**lab2**", so -line 10 (which is a copy of line-8) deposits a word of 1. Finally, line 11 deposits a -word of 1 because the Boolean equality operator evaluates to true. - -The operators "**^^defined**" and "**^^referenced**" are particularly useful in -conditional assembly. For instance, it is possible to automatically include debugging -code if the debugging code is referenced, as in: - - :: - - lea string,a0 ; AO -> message - jsr debug ; print a message - its ; and return - string: dc.b "Help me, Spock!",0 ; (the message) - . - . - . - .iif ^^defined 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. - -In production code, presumably all references to the debug symbol will be removed, -and the debug source file will not be included. (We could have as easily made the -symbol **debug** external, instead of including another source file). - - -`Directives`_ -============= - -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`_. - - - -**.even** - 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). - Note that GPU/DSP code sections are not contained in their own - 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). - Note that GPU/DSP code sections are not contained in their own - 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 - bytes). Note that GPU/DSP code sections are not contained in their own - 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 - bytes). Note that GPU/DSP code sections are not contained in their own - 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 that the conditions are true (non-zero). If any of the comma-seperated - expressions evaluates to zero an assembler warning is issued. For example: - - :: - - .assert *-start = $76 - .assert stacksize >= $400 - -**.bss** - -**.data** - -**.text** - Switch to the BSS, data or text segments. Instructions and data may not - 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. -**.abs** [*location*] - Start an absolute section, beginning with the specified location (or zero, if - no location is specified). An absolute section is much like BSS, except that - locations declared with .ds are based absolute. This directive is useful for - declaring structures or hardware locations. - For example, the following equates: - - :: - - VPLANES = 0 - VWRAP = 2 - CONTRL = 4 - INTIN = 8 - PTSIN = 12 - - could be as easily defined as: - - :: - - .abs - VPLANES: ds.w 1 - VWRAP: ds.w 1 - CONTRL: ds.l 1 - INTIE: ds.l 1 - PTSIN: ds.l 1 - -**.comm** *symbol*, *expression* - Specifies a label and the size of a common region. The label is made global, - 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 - and JR instructions for GPU and DSP code. For example: - - :: - - Always .ccdef 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 - or long, the assembler will execute a .even before depositing data. If the size - 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.) -**.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 - the default size for the rest of the line. (The "default" default size is **.w**.) A - comma-seperated list of expressions follows the directive; an expression may be - followed by a size to override the default size. An expression may be preceeded - by a sharp sign, an expression and a comma, which specifies a repeat count to - be applied to the next expression. For example: - - :: - - .init.l -1, 0.w, #16,'z'.b, #3,0, 11.b - - will deposit a longword of -1, a word of zero, sixteen bytes of lower-case 'z', - three longwords of zero, and a byte of 11. - - 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 - assigned an absolute value (like equ) which starts at expression and increases - by the size of each symbol, for each symbol. If the expression is not supplied, - the default starting value is 4. For example: - - :: - - .cargs #8, .fileliams.1, .openMode, .butPointer.l - - could be used to declare offsets from A6 to a pointer to a filename, a word - containing an open mode, and a pointer to a buffer. (Note that the symbols - used here are confined). Another example, a C-style "string-length" function, - could be written as: - - :: - - _strlen:: .cargs .string ; declare arg - move.l .string(sp),a0 ; a0 -> string - moveq #-1,d0 ; initial size = -1 - .1: addq.1 #1,d0 ; bump size - tst.b (a0)+ ; at end of string? - bne .1 ; (no -- try again) - rts ; return string length - -**.end** - End the assembly. In an include file, end the include file and resume assembling - 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 - code sections. For example: - - :: - - Clipw .equr r19 - . . . - add ClipW,r0 ; ClipW actually is r19 - -**.if** *expression* - -**.else** - -**.endif** - - Start a block of conditional assembly. If the expression is true (non-zero) then - assemble the statements between the .if and the matching **.endif** or **.else**. - If the expression is false, ignore the statements unless a matching .else is - encountered. Conditional assembly may be nested to any depth. - - It is possible to exit a conditional assembly block early from within an include - file (with **end**) or a macro (with **endm**). - -**.iif** *expression*, *statement* - - Immediate version of **.if**. If the expression is true (non-zero) then the state- - ment, which may be an instruction, a directive or a macro, is executed. If - the expression is false, the statement is ignored. No **.endif** is required. For - example: - - :: - - .iif age < 21, canDrink = 0 - .iif weight > 500, dangerFlag = 1 - .iif !(^^defined DEBUG), .include dbsrc - -**.macro** *name* [*formal*, *formal*,...] - -**.endm** - -**.exitm** - Define a macro called name with the specified formal arguments. The macro - definition is terminated with a **.endm** statement. A macro may be exited early - with the .exitm directive. See the chapter on `Macros`_ for more information. - -**.undefmac** *macroName* [, *macroName*...] - Remove the macro-definition for the specified macro names. If reference is - made to a macro that is not defined, no error message is printed and the name - is ignored. - -**.rept** *expression* - -**.endr** - The statements between the **.rept** and **.endr** directives will be repeated *expression* - times. If the expression is zero or negative, no statements will be - assembled. No label may appear on a line containing either of these directives. - -**.globl** *symbol* [, *symbol*...] - -**.extern** *symbol* [, *symbol*...] - Each symbol is made global. None of the symbols may be confined symbols - (those starting with a period). If the symbol is defined in the assembly, the - symbol is exported in the object file. If the symbol is undefined at the end - of the assembly, and it was referenced (i.e. used in an expression), then the - symbol value is imported as an external reference that must be resolved by the - linker. The **.extern** directive is merely a synonym for **.globl**. - -**.include** "*file*" - Include a file. If the filename is not enclosed in quotes, then a default extension - of "**.s**" is applied to it. If the filename is quoted, then the name is not changed - in any way. - - Note: If the filename is not a valid symbol, then the assembler will generate an - error message. You should enclose filenames such as "**atari.s**" in quotes, - because such names are not symbols. - - If the include file cannot be found in the current directory, then the directory - search path, as specified by -i on the commandline, or' by the 'MACPATH' - enviroment string, is traversed. - -**.eject** - Issue a page eject in the listing file. - -**.title** "*string*" - -**.subttl** [-] "*string*" - Set the title or subtitle on the listing page. The title should be specified on - the the first line of the source program in order to take effect on the first page. - The second and subsequent uses of **.title** will cause page ejects. The second - and subsequent uses of .subttl will cause page ejects unless the subtitle string - is preceeded by a dash (-). - -**.list** - -**.nlist** - Enable or disable source code listing. These directives increment and decrement - an internal counter, so they may be appropriately nested. They have no effect - if the **-l** switch is not specified on the commandline. - -**.goto** *label* - This directive provides unstructured flow of control within a macro definition. - It will transfer control to the line of the macro containing the specified goto - label. A goto label is a symbol preceeded by a colon that appears in the first - column of a source line within a macro definition: - - : *label* - - where the label itself can be any valid symbol name, followed immediately by - whitespace and a valid source line (or end of line). The colon **must** appear in - the first column. - - The goto-label is removed from the source line prior to macro expansion - - to all intents and purposes the label is invisible except to the .goto directive - Macro expansion does not take place within the label. - - For example, here is a silly way to count from 1 to 10 without using **.rept**: - - :: - - .macro Count - count set 1 - :loop dc.w count - count set count + 1 - iif count <= 10, goto loop - .endm - -**.gpu** - 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: - -============ ====== ======= -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. --- 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. --- 6-15 Currently unused. -============ ====== ======= - -**.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. - - -`68000 Mnemonics`_ -================== - -`Mnemonics`_ -'''''''''''' -All of the standard Motorola 68000 mnemonics and addressing modes are supported; -you should refer to **The Motorola M68000 Programmer's Reference Manual** -for a description of the instruction set and the allowable addressing modes for each -instruction. With one major exception (forward branches) the assembler performs -all the reasonable optimizations of instructions to their short or address register -forms. - -Register names may be in upper or lower case. The alternate forms ``R0`` through -``R15`` may be used to specify ``D0`` through ``A7``. All register names are keywords, and -may not be used as labels or symbols. None of the 68010 or 68020 register names -are keywords (but they may become keywords in the future). - -`Addressing Modes`_ -''''''''''''''''''' - -===================================== =========================================== -Assembler Syntax Description -===================================== =========================================== -*Dn* Data register direct -*An* Address register direct -(*An*) Address register indirect -(*An*)+ Address register indirect postincrement --(*An*) Address register indirect predecrement -*disp*\ (*An*) Address register indirect with displacement -*bdisp*\ (*An*, *Xi*\ [.\ *size*]) Address register indirect indexed -*abs*.w Absolute short -*abs* Absolute (long or short) -*abs*.l Forced absolute long -*disp*\ (PC) Program counter with displacement -*bdisp*\ (PC, *Xi*\ ) Program counter indexed -#\ *imm* Immediate -===================================== =========================================== - -`Branches`_ -''''''''''' -Since RMAC is a one pass assembler, forward branches cannot be automatically -optimized to their short form. Instead, unsized forward branches are assumed to -be long. Backward branches are always optimized to the short form if possible. - -A table that lists "extra" branch mnemonics (common synonyms for the Motorola -defined mnemonics) appears below. - -`Linker Constraints`_ -''''''''''''''''''''' -It is not possible to make an external reference that will fix up a byte. For example: - - :: - - extern frog - move.l frog(pc,d0),d1 - -is illegal (and generates an assembly error) when frog is external, because the -displacement occupies a byte field in the 68000 offset word, which the object file -cannot represent. - -`Branch Synonyms`_ -'''''''''''''''''' -============== ======== -Alternate name Becomes: -============== ======== -bhs bcc -blo bcs -bse, bs beq -bns bne -dblo dbcs -dbse dbeq -dbra dbf -dbhs dbhi -dbns dbne -============== ======== - -`Optimizations and Translations`_ -''''''''''''''''''''''''''''''''' -The assembler provides "creature comforts" when it processes 68000 mnemonics: - - o **CLR.x An** will really generate **SUB.x An,An**. - - o **ADD**, **SUB** and **CMP** with an address register will really generate **ADDA**, - **SUBA** and **CMPA**. - - 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. - - o All shift instructions with no count value assume a count of one. - - 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. - - 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. - -`Macros`_ -========= -`Macro declaration`_ -'''''''''''''''''''' -A macro definition is a series of statements of the form: - :: - - .macro name [ formal-arg, ...] - . - . - . - statements making up the macro body - . - . - . - .endm - -The name of the macro may be any valid symbol that is not also a 68000 instruction -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. - -A macro body begins on the line after the **.macro** directive. All instructions -and directives, except other macro definitions, are legal inside the body. - -The macro ends with the **.endm** statement. If a label appears on the line with -this directive, the label is ignored and a warning is generated. - -`Parameter Substitution`_ -''''''''''''''''''''''''' -Within the body, formal parameters may be expanded with the special forms: - :: - - \name - \{name} - -The second form (enclosed in braces) can be used in situations where the characters -following the formal parameter name are valid symbol continuation characters. This -is usually used to force concatentation, as in: - - :: - - \{frog}star - \(godzilla}vs\{reagan} - -The formal parameter name is terminated with a character that is not valid in -a symbol (e.g. whitespace or puncuation); optionally, the name may be enclosed in -curly-braces. The names must be symbols appearing on the formal argument list, -or a single decimal digit (``\1`` corresponds to the first argument, ``\2`` to the second, -``\9`` to the ninth, and ``\0`` to the tenth). It is possible for a macro to have more than -ten formal arguments, but arguments 11 and on must be referenced by name, not -by number. - - Other special forms are: - -============ ================================================ -Special Form Description -============ ================================================ -``\\`` a single "\", -``\~`` a unique label of the form "Mn" -``\#`` the number of arguments actually specified -``\!`` the "dot-size" specified on the macro invocation -``\?name`` conditional expansion -``\?{name}`` conditional expansion -============ ================================================ - -The last two forms are identical: if the argument is specified and is non-empty, the -form expands to a "1", otherwise (if the argument is missing or empty) the form -expands to a "0". - -The form "``\!``" expands to the "dot-size" that was specified when the macro -was invoked. This can be used to write macros that behave differently depending -on the size suffix they are given, as in this macro which provides a synonym for the -"``dc``" directive: - - :: - - .macro deposit value - dc\! \value - .endm - deposit.b 1 ; byte of 1 - deposit.w 2 ; word of 2 - deposit.l 3 ; longvord of 3 - deposit 4 ; word of 4 (no explicit size) - -`Macro Invocation`_ -''''''''''''''''''' -A previously-defined macro is called when its name appears in the operation field of -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. - - o All spaces outside strings are removed. - - o Keywords (such as register names, dot sizes and "^^" operators) are converted - to lowercase. - - o 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`` - -will result in the translations: - -======== ================= ================================================= -Argument Expansion Comment -======== ================= ================================================= -``\1`` ``a0`` "``A0``" converted to lower-case -``\2`` empty -``\3`` ``"Zorch"/$20`` "``Zorch``" in double-quotes, 32 in hexadecimal -``\4`` ``^^defined foo`` "``^^DEFINED``" converted to lower-case -``\5`` empty -``\6`` empty -``\7`` ``ticktock`` spaces removed (note concatenation) -======== ================= ================================================= - -The **.exitm** directive will cause an immediate exit from a macro body. Thus -the macro definition: - - :: - - .macro foo source - .iif !\?source, .exitm ; exit if source is empty - move \source,d0 ; otherwise, deposit source - .endm - -will not generate the move instruction if the argument **"source"** is missing from -the macro invocation. - -The **.end**, **.endif** and **.exitm** directives all pop-out of their include levels -appropriately. That is, if a macro performs a **.include** to include a source file, an -executed **.exitm** directive within the include-file will pop out of both the include-file -and the macro. - -Macros may be recursive or mutually recursive to any level, subject only to -the availability of memory. When writing recursive macros, take care in the coding -of the termination condition(s). A macro that repeatedly calls itself will cause the -assembler to exhaust its memory and abort the assembly. - - -`Example Macros`_ -''''''''''''''''' -The Gemdos macro is used to make file system calls. It has two parameters, a -function number and the number of bytes to clean off the stack after the call. The -macro pushes the function number onto the stack and does the trap to the file -system. After the trap returns, conditional assembly is used to choose an addq or -an **add.w** to remove the arguments that were pushed. - - :: - - .macro Gemdos trpno, clean - move.w #\trpno,-(sp) ; push trap number - trap #1 ; do GEMDOS trap - .if \clean <= 8 ; - addq #\clean,sp ; clean-up up to 8 bytes - .else ; - add.w #\clean,sp ; clean-up more than 8 bytes - .endif ; - .endm - -The Fopen macro is supplied two arguments; the address of a filename, and -the open mode. Note that plain move instructions are used, and that the caller of -the macro must supply an appropriate addressing mode (e.g. immediate) for each -argument. - - :: - - .macro Fopen file, mode - movs.w \mode,-(sp) ;push open mode - move.1 \file,-(sp) ;push address of tile name - Gemdos $3d,8 ;do the GEMDOS call - .endm - -The **String** macro is used to allocate storage for a string, and to place the -string's address somewhere. The first argument should be a string or other expres- -sion acceptable in a dc.b directive. The second argument is optional; it specifies -where the address of the string should be placed. If the second argument is omitted, -the string's address is pushed onto the stack. The string data itself is kept in the -data segment. - - :: - - .macro String str,loc - .if \?loc ; if loc is defined - move.l #.\~,\loc ; put the string's address there - .else ; otherwise - pea .\~ ; push the string's address - .endif ; - .data ; put the string data - .\~: dc.b \str,0 ; in the data segment - .text ; and switch back to the text segment - .endm - -The construction "``.\~``" will expand to a label of the form "``.M``\ *n*" (where *n* is -a unique number for every macro invocation), which is used to tag the location of -the string. The label should be confined because the macro may be used along with -other confined symbols. - -Unique symbol generation plays an important part in the art of writing fine -macros. For instance, if we needed three unique symbols, we might write "``.a\~``", -"``.b\~``" and "``.c\~``". - -`Repeat Blocks`_ -'''''''''''''''' -Repeat-blocks provide a simple iteration capability. A repeat block allows a range -of statements to be repeated a specified number of times. For instance, to generate -a table consisting of the numbers 255 through 0 (counting backwards) you could -write: - - :: - - .count set 255 ; initialize counter - .rept 256 ; repeat 256 times: - dc.b .count ; deposit counter - .count set .count - 1 ; and decrement it - .endr ; (end of repeat block) - -Repeat blocks can also be used to duplicate identical pieces of code (which are -common in bitmap-graphics routines). For example: - - :: - - .rept 16 ; clear 16 words - clr.w (a0)+ ; starting at AO - .endr ; - -`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 -& Jerry for a complete listing of Jaguar GPU and DSP assembler mnemonics and addressing -modes. - -`Condition Codes`_ -'''''''''''''''''' -The following condition codes for the GPU/DSP JUMP and JR instructions are built-in: - - :: - - CC (Carry Clear) = %00100 - CS (Carry Set) = %01000 - EQ (Equal) = %00010 - MI (Minus) = %11000 - NE (Not Equal) = %00001 - PL (Plus) = %10100 - HI (Higher) = %00101 - T (True) = %00000 - - -`6502 Support`_ -=============== -RMAC will generate code for the Motorola 6502 microprocessor. This chapter -describes extra addressing modes and directives used to support the 6502. - -As the 6502 object code is not linkable (currently there is no linker) external -references may not be made. (Nevertheless, RMAC may reasonably be used for -large assemblies because of its blinding speed.) - -`6502 Addressing Modes`_ -'''''''''''''''''''''''' -All standard 6502 addressing modes are supported, with the exception of the -accumulator addressing form, which must be omitted (e.g. "ror a" becomes "ror"). -Five extra modes, synonyms for existing ones, are included for compatibility with -the Atari Coinop assembler. - -============== ======================================== -*empty* implied or accumulator (e.g. tsx or ror) -*expr* absolute or zeropage -#\ *expr* immediate -(*expr*,x) indirect X -(*expr*),y indirect Y -(*expr*) indirect -*expr*,x indexed X -*expr*,y indexed Y -@\ *expr*\ (x) indirect X -@\ *expr*\ (y) indirect Y -@expr indirect -x,\ *expr* indexed X -y,\ *expr* indexed Y -============== ======================================== - -While RMAC lacks "high" and "low" operators, high bytes of words may -be extracted with the shift (``>>``) or divide (``/``) operators, and low bytes may be -extracted with the bitwise AND (``&``) operator. - -`6502 Directives`_ -'''''''''''''''''' -**.6502** - This directive enters the 6502 section. The location counter is undefined, and - must be set with ".org" before any code can be generated. - - The "``dc.w``" directive will produce 6502-format words (low byte first). The - 68000's reserved keywords (``d0-d7/a0-a7/ssp/usp`` and so on) remain reserved - (and thus unusable) while in the 6502 section. The directives **globl**, **dc.l**, - **dcb.l**, **text**, **data**, **bss**, **abs**, **even** and **comm** are illegal in the 6502 section. - It is permitted, though probably not useful, to generate both 6502 and 68000 - code in the same object file. -**.68000** - 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 - counter (or **pc**) to location, an expression that must be defined, absolute, and - less than $10000. - - WARNING - - It is possible to assemble "beyond" the microprocessor's 64K address space, but - attempting to do so will probably screw up the assembler. DO NOT attempt - to generate code like this: - - :: - - .org $fffe - nop - nop - nop - - the third NOP in this example, at location $10000, may cause the assembler - to crash or exhibit spectacular schizophrenia. In any case, RMAC will give - no warning before flaking out. - -`6502 Object Code Format`_ -'''''''''''''''''''''''''' -This is a little bit of a kludge. An object file consists of a page map, followed by -one or more page images, followed by a normal Alcyon 68000 object file. If the page -map is all zero, it is not written. - -The page map contains a byte for each of the 256 256-byte pages in the 6502's -64K address space. The byte is zero (``$00``) if the page contained only zero bytes, or -one (``$01``) if the page contained any non-zero bytes. If a page is flagged with a one, -then it is written (in order) following the page map. - -The following code: - - :: - - .6502 - .org $8000 - .dc.b 1 - .org $8100 - .dc.b 1 - .org $8300 - .dc.b 1 - .end - -will generate a page map that looks (to a programmer) something like: - - :: - - <80 bytes of zero> - 01 01 00 01 - <$7c more bytes of zero, for $100 total> - - - - -Following the last page image is an Alcyon-format object file, starting with -the magic number ``$601a``. It may contain 68000 code (although that is probably -useless), but the symbol table is valid and available for debugging purposes. 6502 -symbols will be absolute (not in text, data or bss). - -`Error Messages`_ -================= - -`When Things Go Wrong`_ -''''''''''''''''''''''' -Most of RMAC's error messages are self-explanatory. They fall into four classes: -warnings about situations that you (or the assembler) may not be happy about, -errors that cause the assembler to not generate object files, fatal errors that cause -the assembler to abort immediately, and internal errors that should never happen.\ [3]_ - -You can write editor macros (or sed or awk scripts) to parse the error messages -RMAC generates. When a message is printed, it is of the form: - - "*filename*" , ``line`` *line-number*: *message* - -The first element, a filename enclosed in double quotes, indicates the file that generated -the error. The filename is followed by a comma, the word "``line``", and a line -number, and finally a colon and the text of the message. The filename "**(\*top\*)**" -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. - -`Warnings`_ -''''''''''' -**bad backslash code in string** - You tried to follow a backslash in a string with a character that the assembler - didn't recognize. Remember that RMAC uses a C-style escape system in - strings. -**label ignored** - You specified a label before a macro, **rept** or **endm** directive. The assembler - is warning you that the label will not be defined in the assembly. -**unoptimized short branch** - This warning is only generated if the -s switch is specified on the command - line. The message refers to a forward, unsized long branch that you could have - made short (.s). - -`Fatal Errors`_ -''''''''''''''' - -**cannot continue** - As a result of previous errors, the assembler cannot continue processing. The - assembly is aborted. -**line too long as a result of macro expansion** - When a source line within a macro was expanded, the resultant line was too - long for RMAC (longer than 200 characters or so). - - -**memory exhausted** - The assembler ran out of memory. You should (1) split up your source files - and assemble them seperately, or (2) if you have any ramdisks or RAM-resident - programs (like desk accessories) decrease their size so that the assembler has - more RAM to work with. As a rule of thumb, pure 68000 code will use up to - twice the number of bytes contained in the source files, whereas 6502 code will - use 64K of ram right away, plus the size of the source files. The assembler itself - uses about 80K bytes. Get out your calculator... -**too many ENDMs** - The assembler ran across an **endm** directive when it wasn't expecting to see - one. The assembly is aborted. Check the nesting of your macro definitions - - you probably have an extra **endm**. - - -`Errors`_ -''''''''' - -**.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 -**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 -**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. - Check your conditional assembly nesting. - -**missing '='** - -**missing '}'** - -**missing argument name** - -**missing close parenthesis ')'** - -**missing close parenthesis ']'** - -**missing comma** - -**missing filename** - -**missing string** - -**missing symbol** - -**missing symbol or string** - 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. -**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 - a full disk, or a bad sector on the media.