From 8b1dd903c42afb254e1bffcb42dff44c6e8ab43d Mon Sep 17 00:00:00 2001 From: Shamus Hammons Date: Mon, 9 Nov 2015 18:35:20 -0600 Subject: [PATCH] Complete MADMAC manuals. Thanks to ggn for contributing this! --- rmac.rst | 1911 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1911 insertions(+) create mode 100644 rmac.rst diff --git a/rmac.rst b/rmac.rst new file mode 100644 index 0000000..8e3ba74 --- /dev/null +++ b/rmac.rst @@ -0,0 +1,1911 @@ +ATARI +----- +MADMAC +====== +68000 Macro Assembler +===================== +Reference Manual +================ +version 1.00 +============ + +:: + + MADMAC Version 1.07 release notes, January, 1990. + + + Using .cargs used to cause subsequent global symbols to disappear from + the symbol table. Now it doesn't. + + + A movem instruction with no register list (i.e. "movem.l (sp)+,") + assembled without error; it now reports "missing regsiter list." + + + + + + + + + + + +:: + + MADMAC Version 1.05 release notes, August, 1988. + + + This version of MadMac replaces version 1.00 and fixes some small bugs: + + + Symbols beginning with a capital L were not included in the + object file output. They should have been (and now are) excluded only + in AS68 compatibility mode, to avoid cluttering the output with + compiler-generated symbols. + + + Forward branches declared "short" (such as bras, dbra.s, bsr.$) + but whose targets were too far away did not cause an assembly-time + error; incorrect machine code was silently generated. They now cause + assembly-time errors. + + + Symbols appeared in the object file symbol table in the order • + they were referenced in the source, not the order they were declared. + Now the order more nearly matches the order of declaration (but not + perfectly). + + + The disp(And(n.$) addressing mode produced correct machine code, + but incorrect output in the listing file. Now the output is correct. + + +*NOTE: Every effort has been made to ensure the accuracy and robustness of this +manual and the associated software. However, because Atari Corporation is con- +stantly 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.* + + + + + + + + + + + + +ATARI, the Atari logo, MEGA, and ST are trademarks or registered trademarks of +Atari Corporation. +Mark Williams is a trademark of Mark Williams Company. +Motorola is a trademark of Motorola Inc. + + + + + + + + + + + +*Copyright © 1986, 1987, Atari Corporation* + +*All rights reserved.* + +*Reproduction of this document or the associated software is not allowed without +the specific written consent of Atari Corporation.* + +*Printed in USA.* + +*Atari Document number C300341-001 Rev. A.* + +Contents +======== + +.. contents:: + +Introduction +============ + +Introduction +'''''''''''' +This document describes MADMAC, a fast macro assembler for the 68000. MADMAC currently +runs on the Atari ST and under 4.2 BSD VAX UNIX. It was written +at Atari Corporation by programmers who needed a high performance assembler +for their work. + +MADMAC 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. MADMAC is also blindingly fast, another feature +often sadly and obviously missing in today's assemblers.[1]_ + +MADMAC 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. + +`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 MADMAC is so fast that it doesn't matter + much. + +* Read the rest of the manual, especially the first two chapters on The Com- + mand Line and Using MADMAC. The distribution disk contains example + programs that you can look at, assemble and modify. + +.. [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! + + +`The Command Line`_ +''''''''''''''''''' + +The assembler is called "**mac.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 MADMAC 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 MADMAC`_). 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. + +MADMAC 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. +-fm Produce Mark Williams format object file. +-fmu Like "**-fm**" , but move underscores to end of symbol names. +-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 MADMAC resident in memory (Atari ST only). +-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 MADMAC 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. + +**-fm** + +**-fmu** + The **-fm** and **-fmu** switches cause MADMAC to generate Mark Williams style + object files instead of Alcyon object files. These files may be linked with the + Mark Williams linker. The **-fmu** switch causes underscores on the first char- + acter of a global symbol name to be moved to the end of the name, as per the + Mark Williams C compiler naming convention. That is, "**_main**" will become + "**main\_**" and "**__main**" will become "**_main_**". +**-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 MADMAC 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 MADMAC 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 MADMAC 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 + MADMAC 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. +**-s** + The **-s** switch causes MADMAC 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 MADMAC prints out (for + example) the names of the files it is currently processing. Verbose mode is + automatically entered when MADMAC 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. MADMAC will produce *N* lines + before emitting a form-feed. If *N* is missing or less than 10 an error message is + generated. +**-6** + The **-6** switch takes effect when it is mentioned. It allows MADMAC to be + used as a back end to the Alcyon C compiler.\ [2]_ **Note:** the assembler will + produce code that is typically ten percent larger and ten percent slower than + the output of the Alcyon assembler, therefore use of this switch for production + code is discouraged. + +.. [2] The -6 switch is not a compatibility mode for AS68 - it has been carefully tailored to accept the output of the Alcyon C compiler. + + +`Using MADMAC`_ +=============== + +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 MADMAC 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: + + :: + + % mac -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: + + :: + + % mac -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: + + :: + + % mac -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, MADMAC 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 MADMAC 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): + + :: + + %. mac + + 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 +''''''''''''''''''''''''''''' +MADMAC 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 +'''''''''''''''' +MADMAC 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 AS68 Users +'''''''''''''''''''' +MADMAC is not entirely compatible with the Alcyon assembler, AS68. This section +outlines the major differences. In practice, we have found that very few changes are +necessary to make AS68 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. (MADMAC 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**. AS68 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 AS68's org or section directives. AS68's page + directive has become eject. The AS68 **.xdef** and **.xref** directives are not implemented, + but **.globl** makes these unnecessary anyway. The directives **.comline**, + **mask2**, **idnt** and **opt**, which were unimplemented and ignored in AS68, are + not legal in MADMAC. + + 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 (except in **-6** + mode); 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. + +Notes for Mark Williams C Users +''''''''''''''''''''''''''''''' +MADMAC will generate object code that the Mark Williams C linker, **ld**, will +accept. This has been tested only with version 2.0 of the Mark Williams package. +Some notable differences between MADMAC and the Mark Williams assembler, as, +are: + + o MWC permits 16-character symbol names in the object file, and MADMAC + supports this; + o MWC object files can contain more code and data sections than the MADMAC + (Alcyon) object code format. MADMAC maps its code sections as follows: + +================================ ================== +MWC Space MADMAC Space +================================ ================== +shui (shared instruction) text +prvi (private instruction) unsupported +bssi (uninitialized instruction) unsupported +shrd (shared data) data +prvd (private data) unsupported +bssd (uninitialized data) bss +debug information unsupported +symbols symbols +absolute abs, equates, etc. +================================ ================== + + It is not possible for MADMAC to generate code in the Mark Williams private + instruction, private data or uninitialized instruction spaces. + + o None of the Mark Williams assembler directives (e.g. "**.long**" and "**.odd**") are + supported. None of the MWC non-standard addressing modes are supported. + o The Mark Williams debugger, **db**, does not support the Alcyon-format symbols + produced with the **-ps** switch; it complains about the format of the executable + file and aborts. + o MADMAC does not support the method by which the Mark Williams shell + passes long command lines to programs. Command lines are truncated to 127 + characters. + +Using MADMAC as a Back-End to the Alcyon C Compiler +''''''''''''''''''''''''''''''''''''''''''''''''''' +MADMAC can be used in place of the AS68 assembler as a back-end for the Alcyon +version 4.14 C compiler. The "**-6**" switch turns on a mode that warps and perverts +MADMAC's ordinary syntax into accepting what the Alcyon compiler dishes out. +This can be used in a batch file (for instance) with a line that looks like: + + :: + + mac -6 -o %1.o m:%1 + +(Assuming that device "**M:**" is where the source was put by compiler phase **c168**). +You should be aware that AS68 generally produces better and faster code than +MADMAC, although it is slower to assemble. + +`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 MADMAC 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. MADMAC 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\andi.s'" you would specify the string +"`c:\\auto\\andi.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. +================================ ==================================== + + 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. +**.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 com- + mon regions of the same name; the largest size determines the real size of the + common region when the file is linked. + +**.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.) + +**.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. + +**.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 direc- + tory 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 + +`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 MADMAC 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. + +`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 ; + +`6502 Support`_ +=============== +MADMAC 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, MADMAC 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 MADMAC 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, MADMAC 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 MADMAC'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 +MADMAC 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. + +`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 MADMAC 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 MADMAC (longer than 200 characters or so). + + +.. [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. + +**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** + MADMAC 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 MADMAC 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 MADMAC 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. + MADMAC 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. MADMAC 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. -- 2.37.2