Shamusworld >> Repos - rmac/blob - rmac.rst

   1 ATARI
   2 -----
   3 MADMAC
   4 ======
   5 68000 Macro Assembler
   6 =====================
   7 Reference Manual
   8 ================
   9 version 1.00
  10 ============
  11
  12 ::
  13
  14  MADMAC Version 1.07 release notes, January, 1990.
  15
  16
  17  Using .cargs used to cause subsequent global symbols to disappear from
  18  the symbol table. Now it doesn't.
  19
  20
  21  A movem instruction with no register list (i.e. "movem.l (sp)+,")
  22  assembled without error; it now reports "missing regsiter list."
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34 ::
  35
  36  MADMAC Version 1.05 release notes, August, 1988.
  37
  38
  39  This version of MadMac replaces version 1.00 and fixes some small bugs:
  40
  41
  42  Symbols beginning with a capital L were not included in the
  43  object file output. They should have been (and now are) excluded only
  44  in AS68 compatibility mode, to avoid cluttering the output with
  45  compiler-generated symbols.
  46
  47
  48  Forward branches declared "short" (such as bras, dbra.s, bsr.$)
  49  but whose targets were too far away did not cause an assembly-time
  50  error; incorrect machine code was silently generated. They now cause
  51  assembly-time errors.
  52
  53
  54  Symbols appeared in the object file symbol table in the order •
  55  they were referenced in the source, not the order they were declared.
  56  Now the order more nearly matches the order of declaration (but not
  57  perfectly).
  58
  59
  60  The disp(And(n.$) addressing mode produced correct machine code,
  61  but incorrect output in the listing file. Now the output is correct.
  62
  63
  64 *NOTE: Every effort has been made to ensure the accuracy and robustness of this
  65 manual and the associated software. However, because Atari Corporation is con-
  66 stantly improving and updating its computer software, it is unable to guarantee
  67 the accuracy of printed or duplicated material after the date of publication and
  68 disclaims liability for changes, errors or omissions.*
  69
  70
  71
  72
  73
  74
  75
  76
  77
  78
  79
  80
  81 ATARI, the Atari logo, MEGA, and ST are trademarks or registered trademarks of
  82 Atari Corporation.
  83 Mark Williams is a trademark of Mark Williams Company.
  84 Motorola is a trademark of Motorola Inc.
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96 *Copyright © 1986, 1987, Atari Corporation*
  97
  98 *All rights reserved.*
  99
 100 *Reproduction of this document or the associated software is not allowed without
 101 the specific written consent of Atari Corporation.*
 102
 103 *Printed in USA.*
 104
 105 *Atari Document number C300341-001 Rev. A.*
 106
 107 Contents
 108 ========
 109
 110 .. contents::
 111
 112 Introduction
 113 ============
 114
 115 Introduction
 116 ''''''''''''
 117 This document describes MADMAC, a fast macro assembler for the 68000. MADMAC currently
 118 runs on the Atari ST and under 4.2 BSD VAX UNIX. It was written
 119 at Atari Corporation by programmers who needed a high performance assembler
 120 for their work.
 121
 122 MADMAC is intended to be used by programmers who write mostly in assembly language.
 123 It was not originally a back-end to a C compiler, therefore it
 124 has creature comfort that are usually neglected in such back-end assemblers. It
 125 supports include files, macros, symbols with limited scope, some limited control
 126 structures, and other features. MADMAC is also blindingly fast, another feature
 127 often sadly and obviously missing in today's assemblers.[1]_
 128
 129 MADMAC is not entirely compatible with the AS68 assembler provided with
 130 the original Atari ST Developer's Kit, but most changes are minor and a few minutes
 131 with an editor should allow you to assemble your current source files. If you are an
 132 AS68 user, before you leap into the unknown please read the section on Notes for
 133 AS68 Users.
 134
 135 This manual was typeset with TEX and the Computer Modern fonts, and it
 136 was printed on the Atari SLM-804 laser printer with a MEGA ST. Except for 200
 137 lines of assembly language, the assembler is written entirely in C.
 138
 139 `Getting Started`_
 140 ''''''''''''''''''
 141
 142  =>Write protect your distribution disk and make a backup of it now. Put the
 143    original disk in a safe place.
 144
 145 * The distribution disk contains a file called README that you should read.
 146   This file contains important nays about the contents of the distribution disk
 147   and summarizes the most recent changes to the tools.
 148
 149 * Hard disk users can simply copy the executable files to their work or binary
 150   directories. People with floppy disks can copy the executables to ramdisks,
 151   install the assembler with the -q option, or even work right off of the floppies.
 152
 153 * You will need an editor that can produce "normal" format text files. Micro
 154   Emacs will work well, as will most other commercial program editors, but not
 155   most word processors (such as First Word or Microsoft Write).
 156
 157 * You will probably want to examine or get a listing of the file "ATARI.S". It
 158   contains lots of definitions for the Atari ST, including BIOS variables, most
 159   BIOS, XBIOS and GEMDOS traps, and line-A equates. We (or you) could
 160   split the file up into pieces (a file for line-A equates, a file for hardware and
 161   BIOS variables and so on), but MADMAC is so fast that it doesn't matter
 162   much.
 163
 164 * Read the rest of the manual, especially the first two chapters on The Com-
 165   mand Line and Using MADMAC. The distribution disk contains example
 166   programs that you can look at, assemble and modify.
 167
 168 .. [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!
 169
 170
 171 `The Command Line`_
 172 '''''''''''''''''''
 173
 174 The assembler is called "**mac.prg**". The command line takes the form:
 175
 176                           **mac** [*switches*] [*files* ...]
 177
 178 A command line consists of any number of switches followed by the names of files
 179 to assemble. A switch is specified with a dash (**-**) followed immediately by a key
 180 character. Key characters are not case-sensitive, so "**-d**" is the same as "**-D**". Some
 181 switches accept (or require) arguments to immediately follow the key character,
 182 with no spaces in between.
 183
 184 Switch order is important. Command lines are processed from left to right in
 185 one pass, and switches usually take effect when they are encountered. In general it
 186 is best to specify all switches before the names of any input files.
 187
 188 If the command line is entirely empty then MADMAC prints a copyright message
 189 and enters an "interactive" mode, prompting for successive command lines
 190 with a star (\*). An empty command line will exit (See the examples in the chapter
 191 on `Using MADMAC`_). After each assembly in interactive mode, the assembler
 192 will print a summary of the amount of memory used, the amount of memory left,
 193 the number of lines processed, and the number of seconds the assembly took.
 194
 195 Input files are assumed to have the extension "**.s**"; if a filename has no extension
 196 (i.e. no dot) then "**.s**" will be appended to it. More than one source filename may be
 197 specified: the files are assembled into one object file, as if they were concatenated.
 198
 199 MADMAC normally produces object code in "**file.o**" if "**file.s**" is the first
 200 input filename. If the first input file is a special character device, the output name
 201 is noname.o. The **-o** switch (see below) can be used change the output file name.
 202
 203
 204 ===================  ===========
 205 Switch               Description
 206 ===================  ===========
 207 -dname\ *[=value]*   Define symbol, with optional value.
 208 -e\ *[file[.err]]*   Direct error messages to the specified file.
 209 -fm                  Produce Mark Williams format object file.
 210 -fmu                 Like "**-fm**" , but move underscores to end of symbol names.
 211 -i\ *path*           Set include-file directory search path.
 212 -l\ *[file[prn]]*    Construct and direct assembly listing to the specified file.
 213 -o\ *file[.o]*       Direct object code output to the specified file.
 214 -p                   Produce an executable (**.prg**) output file.
 215 -ps                  Produce an executable (**.prg**) output file with symbols.
 216 -q                   Make MADMAC resident in memory (Atari ST only).
 217 -s                   Warn about unoptimized long branches.
 218 -u                   Assume that all undefined symbols are external.
 219 -v                   Verbose mode (print running dialogue).
 220 -yn                  Set listing page size to n lines.
 221 -6                   "Back end" mode for Alcyon C68.
 222 file\ *[s]*          Assemble the specified file.
 223 ===================  ===========
 224
 225 The switches are described below. A summary of all the switches is given in
 226 the table.
 227
 228 **-d**
 229  The **-d** switch permits symbols to be defined on the command line. The name
 230  of the symbol to be defined immediately follows the switch (no spaces). The
 231  symbol name may optionally be followed by an equals sign (=) and a decimal
 232  number. If no value is specified the symbol's value is zero. The symbol at-
 233  tributes are "defined, not referenced, and absolute". This switch is most useful
 234  for enabling conditionally-assembled debugging code on the command line; for
 235  example:
 236
 237   ::
 238
 239       -dDEBUG -dLoopCount=999 -dDebugLevel=55
 240
 241 **-e**
 242  The -e switch causes MADMAC to send error messages to a file, instead of the
 243  console. If a filename immediately follows the switch character, error messages
 244  are written to the specified file. If no filename is specified, a file is created with
 245  the default extension "**.err**" and with the root name taken from the first input
 246  file name (e.g. error messages are written to "**file.err**" if "**file**" or "**file.s**" is
 247  the first input file name). If no errors are encountered, then no error listing
 248  file is created. Beware! If an assembly produces no errors, any error file from
 249  a previous assembly is not removed.
 250
 251 **-fm**
 252
 253 **-fmu**
 254  The **-fm** and **-fmu** switches cause MADMAC to generate Mark Williams style
 255  object files instead of Alcyon object files. These files may be linked with the
 256  Mark Williams linker. The **-fmu** switch causes underscores on the first char-
 257  acter of a global symbol name to be moved to the end of the name, as per the
 258  Mark Williams C compiler naming convention. That is, "**_main**" will become
 259  "**main\_**" and "**__main**" will become "**_main_**".
 260 **-i**
 261  The **-i** switch allows automatic directory searching for include files. A list of
 262  semi-colon seperated directory search paths may be mentioned immediately
 263  following the switch (with no spaces anywhere). For example:
 264
 265   ::
 266
 267          -im:;c:include;c:include\sys
 268
 269  will cause the assembler to search the current directory of device **M**, and the
 270  directories include and include\sys on drive **C**. If *-i* is not specified, and the
 271  enviroment variable "**MACPATH**" exists, its value is used in the same manner.
 272  For example, users of the Mark Williams shell could put the following line in
 273  their profile script to achieve the same result as the **-i** example above:
 274
 275   ::
 276
 277       setenv MACPATH="m:;c:include;c:include\sys"
 278 **-l**
 279  The -l switch causes MADMAC to generate an assembly listing file. If a file-
 280  name immediately follows the switch character, the listing is written to the
 281  specified file. If no filename is specified, then a listing file is created with the
 282  default extension "**.prn**" and with the root name taken from the first input file
 283  name (e.g. the listing is written to "**file.prn**" if "**file**" or "**file.s**" is the first
 284  input file name).
 285 **-o**
 286  The -o switch causes MADMAC to write object code on the specified file. No
 287  default extension is applied to the filename. For historical reasons the filename
 288  can also be seperated from the switch with a space (e.g. "**-o file**").
 289
 290 **-p**
 291
 292 **-ps**
 293  The **-p** and **-ps** switches cause MADMAC to produce an Atari ST executable
 294  file with the default extension of "**.prg**". If there are any external references
 295  at the end of the assembly, an error message is emitted and no executable file
 296  is generated. The **-p** switch does not write symbols to the executable file. The
 297  **-ps** switch includes symbols (Alcyon format) in the executable file.
 298 **-q**
 299   The **-q** switch is aimed primarily at users of floppy-disk-only systems. It causes
 300   MADMAC to install itself in memory, like a RAMdisk. Then the program
 301   **m.prg** (which is very short - less than a sector) can be used instead of
 302   **mac.prg**, which can take ten or twelve seconds to load.
 303 **-s**
 304   The **-s** switch causes MADMAC to generate a list of unoptimized forward
 305   branches as warning messages. This is used to point out branches that could
 306   have been short (e.g. "bra" could be "bra.s").
 307 **-u**
 308   The **-u** switch takes effect at the end of the assembly. It forces all referenced
 309   and undefined symbols to be global, exactly as if they had been made global
 310   with a **.extern** or **.globl** directive. This can be used if you have a lot of
 311   external symbols, and you don't feel like declaring them all external.
 312 **-v**
 313   The **-v** switch turns on a "verbose" mode in which MADMAC prints out (for
 314   example) the names of the files it is currently processing. Verbose mode is
 315   automatically entered when MADMAC prompts for input with a star.
 316 **-y**
 317   The **-y** switch, followed immediately by a decimal number (with no intervening
 318   space), sets the number of lines in a page. MADMAC will produce *N* lines
 319   before emitting a form-feed. If *N* is missing or less than 10 an error message is
 320   generated.
 321 **-6**
 322   The **-6** switch takes effect when it is mentioned. It allows MADMAC to be
 323   used as a back end to the Alcyon C compiler.\ [2]_ **Note:** the assembler will
 324   produce code that is typically ten percent larger and ten percent slower than
 325   the output of the Alcyon assembler, therefore use of this switch for production
 326   code is discouraged.
 327
 328 .. [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.
 329
 330
 331 `Using MADMAC`_
 332 ===============
 333
 334 Let's assemble and link some example programs. These programs are included
 335 on the distribution disk in the "**EXAMPLES**" directory - you should copy them to
 336 your work area before continuing. In the following examples we adopt the conven-
 337 tions that the shell prompt is a percent sign (%) and that your input (the stuff you
 338 type) is presented in **bold face**.
 339
 340 If you have been reading carefully, you know that MADMAC can generate
 341 an executable file without linking. This is useful for making small, stand alone
 342 programs that don't require externals or library routines. For example, the following
 343 two commands:
 344
 345  ::
 346
 347       % mac examples
 348       % aln -s example.s
 349
 350 could be replaced by the single command:
 351
 352  ::
 353
 354       % mac -ps example.s
 355
 356 since you don't need the linker for stand-alone object files.
 357
 358 Successive source files named in the command line are are concatenated, as in
 359 this example, which assembles three files into a single executable, as if they were
 360 one big file:
 361
 362  ::
 363
 364       % mac -p bugs shift images
 365
 366 Of course you can get the same effect by using the **.include** directive, but sometimes
 367 it is convenient to do the concatenation from the command line.
 368
 369    Here we have an unbelievably complex command line:
 370
 371     ::
 372
 373       % mac -lzorf -y95 -o tmp -ehack -Ddebug=123 -ps example
 374
 375 This produces a listing on the file called "**zorf.prn**" with 95 lines per page, writes
 376 the executable code (with symbols) to a file called "**tmp.prg**", writes an error listing
 377 to the file "**hack.err**", specifies an include-file path that includes the current
 378 directory on the drive "**M:**," defines the symbol "**debug**" to have the value 123, and
 379 assembles the file "**example.s**". (Take a deep breath - you got all that?)
 380
 381 One last thing. If there are any assembly errors, MADMAC will terminate
 382 with an exit code of 1. If the assembly succeeds (no errors, although there may be
 383 warnings) the exit code will be 0. This is primarily for use with "make" utilities.
 384
 385 `Interactive Mode`_
 386 '''''''''''''''''''
 387 If you invoke MADMAC with an empty command line it will print a copyright
 388 message and prompt you for more commands with a star (*****). This is useful if you
 389 are used to working directly from the desktop, or if you want to assemble several files
 390 in succession without having to reload the assembler from disk for each assembly.
 391
 392 In interactive mode, the assembler is also in verbose mode (just as if you had
 393 specified **-v** on each command line):
 394
 395  ::
 396
 397      %. mac
 398
 399      MADMAC Atari Macro Assembler
 400      Copyright 1987 Atari Corporation
 401      Beta version 0.12 Jun 1987 lmd
 402
 403      * -ps example
 404      [Including: example.s]
 405      [Including: atari.s]
 406      [Leaving: atari.s]
 407      [Leaving; example. a]
 408      [Writing executable tile: example.prg
 409      36K used, 3868K left, 850 lines, 2.0 seconds
 410
 411
 412 You can see that the assembler gave a "blow-by-blow" account of the files it processed,
 413 as well as a summary of the assembly's memory usage, the number of lines
 414 processed (including macro and repeat-block expansion), and how long the assembly
 415 took
 416
 417 The assembler prompts for another command with the star. At this point you
 418 can either type a new command line for the assembler to process, or you can exit
 419 by typing control-C or an empty line.
 420
 421 Things You Should Be Aware Of
 422 '''''''''''''''''''''''''''''
 423 MADMAC is a one pass assembler. This means that it gets all of its work done by
 424 reading each source file exactly once and then "back-patching" to fix up forward
 425 references. This one-pass nature is usually transparent to the programmer, with
 426 the following important exceptions:
 427
 428  o in listings, the object code for forward references is not shown. Instead, lower-
 429    case "xx"s are displayed for each undefined byte, as in the following example:
 430
 431     ::
 432
 433      60xx   1: bra.s.2  ;forward branch
 434      xxxxxxxx  dc.l .2  ;forward reference
 435      60FE  .2: bra.s.2  ;backward reference
 436
 437  o Forward branches (including **BSR**\s) are never optimized to their short forms.
 438    To get a short forward branch it is necessary to explicitly use the ".s" suffix in
 439    the source code.
 440  o Error messages may appear at the end of the assembly, referring to earlier source
 441    lines that contained undefined symbols.
 442  o All object code generated must fit in memory. Running out of memory is a
 443    fatal error that you must deal with by splitting up your source files, re-sizing
 444    or eliminating memory-using programs such as ramdisks and desk accessories,
 445    or buying more RAM.
 446
 447 Forward Branches
 448 ''''''''''''''''
 449 MADMAC does not optimize forward branches for you, but it will tell you about
 450 them if you use the -s (short branch) option:
 451
 452  ::
 453
 454      % mac -s example.s
 455      "example.s", line 20: warning: unoptimized short branch
 456
 457 With the -e option you can redirect the error output to a file, and determine by
 458 hand (or editor macros) which forward branches are safe to explicitly declare short.
 459
 460 Notes for AS68 Users
 461 ''''''''''''''''''''
 462 MADMAC is not entirely compatible with the Alcyon assembler, AS68. This section
 463 outlines the major differences. In practice, we have found that very few changes are
 464 necessary to make AS68 source code assemble.
 465
 466   o A semicolon (;) must be used to introduce a comment, except that a star (*)
 467     may be used in the first column. AS68 treated anything following the operand
 468     field, preceeded by whitespace, as a comment. (MADMAC treats a star that
 469     is not in column 1 as a multiplication operator).
 470
 471   o Labels require colons (even labels that begin in column 1).
 472
 473   o Conditional assembly directives are called **if**, **else** and **endif**. AS68 called these
 474     **ifne**, **ifeq** (etc.), and **endc**.
 475   o The tilde (~) character is an operator, and back-quote (`) is an illegal character.
 476     AS68 permitted the tilde and back-quote characters in symbols.
 477   o There are no equivalents to AS68's org or section directives. AS68's page
 478     directive has become eject. The AS68 **.xdef** and **.xref** directives are not implemented,
 479     but **.globl** makes these unnecessary anyway. The directives **.comline**,
 480     **mask2**, **idnt** and **opt**, which were unimplemented and ignored in AS68, are
 481     not legal in MADMAC.
 482
 483   o The location counter cannot be manipulated with a statement of the form:
 484
 485     ::
 486
 487                                   * = expression
 488
 489   o The **ds** directive is not permitted in the text or data segments (except in **-6**
 490     mode); an error message is issued. Use **dcb** instead to reserve large blocks of
 491     initialized storage.
 492
 493   o Back-slashes in strings are "electric" characters that are used to escape C-like
 494     character codes. Watch out for GEMDOS path names in ASCII constants -
 495     you will have to convert them to double-backslashes.
 496
 497 Notes for Mark Williams C Users
 498 '''''''''''''''''''''''''''''''
 499 MADMAC will generate object code that the Mark Williams C linker, **ld**, will
 500 accept. This has been tested only with version 2.0 of the Mark Williams package.
 501 Some notable differences between MADMAC and the Mark Williams assembler, as,
 502 are:
 503
 504   o MWC permits 16-character symbol names in the object file, and MADMAC
 505     supports this;
 506   o MWC object files can contain more code and data sections than the MADMAC
 507     (Alcyon) object code format. MADMAC maps its code sections as follows:
 508
 509 ================================ ==================
 510 MWC Space                        MADMAC Space
 511 ================================ ==================
 512 shui (shared instruction)        text
 513 prvi (private instruction)       unsupported
 514 bssi (uninitialized instruction) unsupported
 515 shrd (shared data)               data
 516 prvd (private data)              unsupported
 517 bssd (uninitialized data)        bss
 518 debug information                unsupported
 519 symbols                          symbols
 520 absolute                         abs, equates, etc.
 521 ================================ ==================
 522
 523     It is not possible for MADMAC to generate code in the Mark Williams private
 524     instruction, private data or uninitialized instruction spaces.
 525
 526   o None of the Mark Williams assembler directives (e.g. "**.long**" and "**.odd**") are
 527     supported. None of the MWC non-standard addressing modes are supported.
 528   o The Mark Williams debugger, **db**, does not support the Alcyon-format symbols
 529     produced with the **-ps** switch; it complains about the format of the executable
 530     file and aborts.
 531   o MADMAC does not support the method by which the Mark Williams shell
 532     passes long command lines to programs. Command lines are truncated to 127
 533     characters.
 534
 535 Using MADMAC as a Back-End to the Alcyon C Compiler
 536 '''''''''''''''''''''''''''''''''''''''''''''''''''
 537 MADMAC can be used in place of the AS68 assembler as a back-end for the Alcyon
 538 version 4.14 C compiler. The "**-6**" switch turns on a mode that warps and perverts
 539 MADMAC's ordinary syntax into accepting what the Alcyon compiler dishes out.
 540 This can be used in a batch file (for instance) with a line that looks like:
 541
 542     ::
 543
 544       mac -6 -o %1.o m:%1
 545
 546 (Assuming that device "**M:**" is where the source was put by compiler phase **c168**).
 547 You should be aware that AS68 generally produces better and faster code than
 548 MADMAC, although it is slower to assemble.
 549
 550 `Text File Format`_
 551 '''''''''''''''''''
 552 For those using editors other than the "Emacs" style ones (Micro-Emacs, Mince,
 553 etc.) this section documents the source file format that MADMAC expects.
 554
 555  o Files must contain characters with ASCII values less than 128; it is not per-
 556    missable to have characters with their high bits set unless those characters are
 557    contained in strings (i.e. between single or double quotes) or in comments.
 558
 559  o Lines of text are terminated with carriage-return/line-feed, linefeed alone, or
 560    carriage-return alone.
 561
 562  o The file is assumed to end with the last terminated line. If there is text beyond
 563    the last line terminator (e.g. control-Z) it is ignored.
 564
 565 `Source Format`_
 566 ================
 567
 568 `Statements`_
 569 '''''''''''''
 570 A statement may contain up to four fields which are identified by order of ap-
 571 pearance and terminating characters. The general form of an assembler statement
 572 is:
 573
 574   ::
 575
 576       label: operator operand(s)  ; comment
 577
 578 The label and comment fields are optional. An operand field may not appear
 579 without an operator field. Operands are seperated with commas. Blank lines are
 580 legal. If the first character on a line is an asterisk (*) or semicolon (;) then the
 581 entire line is a comment. A semicolon anywhere on the line (except in a string)
 582 begins a comment field which extends to the end of the line.
 583
 584 The label, if it appears, must be terminated with a single or double colon. If
 585 it is terminated with a double colon it is automatically declared global. It is illegal
 586 to declare a confined symbol global (see: `Symbols and Scope`_).
 587
 588 `Equates`_
 589 ''''''''''
 590 A statement may also take one of these special forms:
 591
 592       *symbol* **equ** *expression*
 593
 594       *symbol* **=** *expression*
 595
 596       *symbol* **--** *expression*
 597
 598       *symbol* **set** *expression*
 599
 600       *symbol* **reg** *register list*
 601
 602 The first two forms are identical; they equate the symbol to the value of an
 603 expression, which must be defined (no forward references). The third form, double-
 604 equals (==), is just like an equate except that it also makes the symbol global. (As
 605 with labels, it is illegal to make a confined equate global.) The fourth form allows
 606 a symbol to be set to a value any number of times, like a variable. The last form
 607 equates the symbol to a 16-bit register mask specified by a register list. It is possible
 608 to equate confined symbols (see: `Symbols and Scope`_). For example:
 609
 610   ::
 611
 612       cr    equ    13          carriage-return
 613       if    =      10          line-feed
 614       DEBUG ==     1           global debug flag
 615       count set    0           variable
 616       count set    count + 1   increment variable
 617       .rags reg    d3-d7/a3-a6 register list
 618       .cr          13          confined equate
 619
 620 `Symbols and Scope`_
 621 ''''''''''''''''''''
 622 Symbols may start with an uppercase or lowercase letter (A-Z a-z), an underscore
 623 (**_**), a question mark (**?**) or a period (**.**). Each remaining character may be an
 624 upper or lowercase letter, a digit (**0-9**), an underscore, a dollar sign (**$**), or a question
 625 mark. (Periods can only begin a symbol, they cannot appear as a symbol
 626 continuation character). Symbols are terminated with a character that is not a
 627 symbol continuation character (e.g. a period or comma, whitespace, etc.). Case is
 628 significant for user-defined symbols, but not for 68000 mnemonics, assembler direc-
 629 tives and register names. Symbols are limited to 100 characters. When symbols
 630 are written to the object file they are silently truncated to eight (or sixteen) char-
 631 acters (depending on the object file format) with no check for (or warnings about)
 632 collisions.
 633
 634    For example, all of the following symbols are legal and unique:
 635
 636      ::
 637
 638       reallyLougSymbolliame .reallyLongConfinadSymbollame
 639       al0 ret move dc frog aae a9 ????
 640       .al .ret .move .dc .frog .a9 .9 ????
 641       .0  .00  .000 .1  .11. .111 . ._
 642       _frog ?zippo? sys$syetem atari Atari ATARI aTaRi
 643
 644 while all of the following symbols are illegal:
 645
 646      ::
 647
 648       12days dc.10   dc.z   'quote  .right.here
 649       @work hi.there $money$ ~tilde
 650
 651
 652 Symbols beginning with a period (**.**) are *confined*; their scope is between two
 653 normal (unconfined) labels. Confined symbols may be labels or equates. It is illegal
 654 to make a confined symbol global (with the ".globl" directive, a double colon, or a
 655 double equals). Only unconfined labels delimit a confined symbol's scope; equates
 656 (of any kind) do not count. For example, all symbols are unique and have unique
 657 values in the following:
 658
 659    ::
 660
 661       zero:: subq.w $1,d1
 662              bmi.s .ret
 663       .loop: clr.w (a0)+
 664              dbra  d0,.loop
 665       .ret:  rta
 666       FF::   subq.w #1,d1
 667              bmi.s .99
 668       .loop: move.w -1,(a0)+
 669              dbra  d0,.loop
 670       .99:   its
 671
 672 Confined symbols are useful since the programmer has to be much less inventive
 673 about finding small, unique names that also have meaning.
 674
 675 It is legal to define symbols that have the same names as processor mnemonics
 676 (such as "**move**" or "**rts**") or assembler directives (such as "**.even**"). Indeed, one
 677 should be careful to avoid typographical errors, such as this classic (in 6502 mode):
 678
 679     ::
 680
 681              .6502
 682       .org   =     $8000
 683
 684
 685 which equates a confined symbol to a hexadecimal value, rather than setting the
 686 location counter, which the .org directive does (without the equals sign).
 687
 688 `Keywords`_
 689 '''''''''''
 690 The following names, in all combinations of uppercase and lowercase, are keywords
 691 and may not be used as symbols (e.g. labels, equates, or the names of macros):
 692
 693    ::
 694
 695       equ set reg
 696       sr ccr pc sp ssp usp
 697       dO di d2 d3 d4 d5 d6 d7
 698       a0 al a2 a3 a4 a5 a6 aT
 699       r0 ri r2 r3 r4 r5 r6 r7
 700       r8 r9 r10 1'11 r12 rl3 ri4 ri5
 701
 702 `Constants`_
 703 ''''''''''''
 704 Numbers may be decimal, hexadecimal, octal, binary or concatenated ASCII. The
 705 default radix is decimal, and it may not be changed. Decimal numbers are specified
 706 with a string of digits (**0-9**). Hexadecimal numbers are specified with a leading
 707 dollar sign (**$**) followed by a string of digits and uppercase or lowercase letters (**A-F
 708 a-f**). Octal numbers are specified with a leading at-sign (**@**) followed by a string
 709 of octal digits (**0-7**). Binary numbers are specified with a leading percent sign
 710 (**%**) followed by a string of binary digits (**0-1**). Concatenated ASCII constants are
 711 specified by enclosing from one to four characters in single or double quotes. For
 712 example:
 713
 714     ::
 715
 716       1234   *decimal*
 717       $1234  *hexadecimal*
 718       @777   *octal*
 719       %10111 *binary*
 720       "z"    *ASCII*
 721       'frog' *ASCII*
 722
 723 Negative numbers Are specified with a unary minus (**-**). For example:
 724
 725     ::
 726
 727       -5678  -@334 -$4e71
 728       -%11011 -'z' -"WIND"
 729
 730 `Strings`_
 731 ''''''''''
 732 Strings are contained between double (") or single ( ') quote marks. Strings may
 733 contain non-printable characters by specifying "backslash" escapes, similar to the
 734 ones used in the C programming language. MADMAC will generate a warning if a
 735 backslash is followed by a character not appearing below:
 736
 737     ::
 738
 739       \\    $5c    backslash
 740       \n    $0a    line-feed (newline)
 741       \b    $08    backspace
 742       \t    $09    tab
 743       \r    $0c1   carriage-return
 744       \f    $0c    form-feed
 745       \e    $1b    escape
 746       \'    $27    single-quote
 747       \"    $22    double-quote
 748
 749 It is possible for strings (but not symbols) to contain characters with their high
 750 bits set (i.e. character codes 128...255).
 751
 752 You should be aware that backslash characters are popular in GEMDOS path
 753 names, and that you may have to escape backslash characters in your existing source
 754 code. For example, to get the file "'c:\auto\andi.s'" you would specify the string
 755 "`c:\\auto\\andi.s`".
 756
 757 `Register Lists`_
 758 '''''''''''''''''
 759 Register lists are special forms used with the **movem** mnemonic and the **.reg**
 760 directive. They are 16-bit values, with bits 0 through 15 corresponding to registers
 761 **D0** through **A7**. A register list consists of a series of register names or register
 762 ranges seperated by slashes. A register range consists of two register names, Rm
 763 and Rn,m<n, seperated by a dash. For example:
 764
 765      ::
 766
 767        register list           value
 768        -------------           -----
 769        40-d7/a0-a7             $FFFF
 770        d2-d7/a0/a3-a6          $39FC
 771        dO/d1/a0-a3/d7/a6-a7    $CF83
 772        d0                      $0001
 773        r0-r16                  $FFFF
 774
 775 Register lists and register equates may be used in conjunction with the movem
 776 mnemonic, as in this example:
 777
 778      ::
 779
 780        temps   reg     d0-d2/a0-a2     ; temp registers
 781        keeps   reg     d3-d7/d3-a6     ; registers to preserve
 782        allregs reg     d0-d7/a0-a7     ; all registers
 783                movem.l #temps, -(sp)   ; these two lines ...
 784                aovea.l dO -d2/a0 -a2, -(sp) ; are identical
 785                movea.l #keeps, -(sp)   ; save "keep" registers
 786                noven.1 (sp)+,#keeps    ; restore "keep" registers
 787
 788
 789 `Expressions`_
 790 ==============
 791 `Order of Evaluation`_
 792 ''''''''''''''''''''''
 793 All values are computed with 32-bit 2's complement arithmetic. For boolean operations
 794 (such as if or **assert**) zero is considered false, and non-zero is considered
 795 true.
 796
 797      **Expressions are evaluated strictly left-to-right, with no
 798      regard for operator precedence.**
 799
 800 Thus the expression "1+2*3" evaluates to 9, not 7. However, precedence may be
 801 forced with parenthesis (**()**) or square-brackets (**[]**).
 802
 803 `Types`_
 804 '''''''''
 805 Expressions belong to one of three classes: undefined, absolute or relocatable. An
 806 expression is undefined if it involves an undefined symbol (e.g. an undeclared sym-
 807 bol, or a forward reference). An expression is absolute if its value will not change
 808 when the program is relocated (for instance, the number 0, all labels declared in
 809 an abs section, and all Atari ST hardware register locations are absolute values).
 810 An expression is relocatable if it involves exactly one symbol that is contained in a
 811 text, data or BSS section.
 812
 813 Only absolute values may be used with operators other than addition (+) or
 814 subtraction (-). It is illegal, for instance, to multiply or divide by a relocatable or
 815 undefined value. Subtracting a relocatable value from another relocatable value in
 816 the same section results in an absolute value (the distance between them, positive
 817 or negative). Adding (or subtracting) an absolute value to or from a relocatable
 818 value yeilds a relocatable value (an offset from the relocatable address).
 819
 820 It is important to realize that relocatable values belong to the sections they
 821 are defined in (e.g. text, data or BSS), and it is not permissible to mix and match
 822 sections. For example, in this code:
 823
 824     ::
 825
 826      linel:  dc.l   line2, linel+8
 827      line2:  dc.l   linel, line2-8
 828      line3:  dc.l   line2-linel, 8
 829      error:  dc.l   linel+line2, line2 >> 1, line3/4
 830
 831 Line 1 deposits two longwords that point to line 2. Line 2 deposits two longwords
 832 that point to line 1. Line 3 deposits two longwords that have the absolute value
 833 eight. The fourth line will result in an assembly error, since the expressions (re-
 834 spectively) attempt to add two relocatable values, shift a relocatable value right by
 835 one, and divide a relocatable value by four.
 836
 837 The pseudo-symbol "*****" (star) has the value that the current section's location
 838 counter had at the beginning of the current source line. For example, these two
 839 statements deposit three pointers to the label "**bar**":
 840
 841     ::
 842
 843      too:    dc.l   *+4
 844      bar:    dc.l   *, *
 845
 846 Similarly, the pseudo-symbol "**$**" has the value that the current section's location
 847 counter has, and it is kept up to date as the assembler deposits information
 848 "across" a line of source code. For example, these two statements deposit four
 849 pointers to the label "zip":
 850
 851         ::
 852
 853           zip:      dc.l      $+8, $+4
 854           zop:      dc.l      $, $-4
 855
 856 `Unary Operators`_
 857 ''''''''''''''''''
 858
 859 ================================    ====================================
 860 Operator                            Description
 861 ================================    ====================================
 862 **-**                               Unary minus (2's complement).
 863 **!**                               Logical (boolean) NOT.
 864 **~**                               Tilde: bitwise not (l's complement).
 865 **^^defined** *symbol*              True if symbol has a value.
 866 **^^referenced** *symbol*           True if symbol has been referenced.
 867 **^^streq** *stringl*,*string2*     True if the strings are equal.
 868 **^^macdef** *macroName*            True if the macro is defined.
 869 ================================    ====================================
 870
 871    o The boolean operators generate the value 1 if the expression is true, and 0 if
 872      it is not.
 873
 874    o A symbol is referenced if it is involved in an expression. A symbol may have
 875      any combination of attributes: undefined and unreferenced, defined and unref-
 876      erenced (i.e. declared but never used), undefined and referenced (in the case
 877      of a forward or external reference), or defined and referenced.
 878
 879
 880
 881 `Binary Operators`_
 882 '''''''''''''''''''
 883
 884 -----------  ----------------------------------------------
 885 Operator     Description
 886 -----------  ----------------------------------------------
 887 + -  * /     The usual arithmetic operators.
 888 %            Modulo.
 889 & | ^        Bit-wise **AND**, **OR** and **Exclusive-OR**.
 890 << >>        Bit-wise shift left and shift right.
 891 < <=  >=  >  Boolean magnitude comparisons.
 892 =            Boolean equality.
 893 <>  !=       Boolean inequality.
 894 -----------  ----------------------------------------------
 895
 896    o All binary operators have the same precedence: expressions are evaluated
 897      strictly left to right.
 898
 899    o Division or modulo by zero yields an assembly error
 900
 901    o The "<>" and "!=" operators are synonyms.
 902
 903    o Note that the modulo operator (%) is also used to introduce binary constants
 904      (see: `Constants`_). A percent sign should be followed by at least one space if
 905      it is meant to be a modulo operator, and is followed by a '0' or '1'.
 906
 907 `Special Forms`_
 908 ''''''''''''''''
 909
 910 ============    =========================================
 911 Special Form    Description
 912 ============    =========================================
 913 **^^date**      The current system date (Gemdos format).
 914 **^^time**      The current system time (Gemdos format).
 915 ============    =========================================
 916
 917    o The "**^^date**" special form expands to the current system date, in Gemdos
 918      format. The format is a 16-bit word with bits 0 ...4 indicating the day of the
 919      month (1...31), bits 5...8 indicating the month (1...12), and bits 9...15
 920      indicating the year since 1980, in the range 0...119.
 921
 922    o The "**^^time**" special form expands to the current system time, in Gemdos
 923      format. The format is a 16-bit word with bits 0...4 indicating the current
 924      second divided by 2, bits 5...10 indicating the current minute 0...59. and
 925      bits 11...15 indicating the current hour 0...23.
 926
 927 `Example Expressions`_
 928 ''''''''''''''''''''''
 929
 930        ::
 931
 932         line address contents      source code
 933         ---- ------- --------      -------------------------------
 934            1 00000000 4480         lab1:  neg.l  d0
 935            2 00000002 427900000000 lab2:  clr.w  lab1
 936            3         =00000064     equ1   =      100
 937            4         =00000096     equ2   =      equ1 + 50
 938            5 00000008 00000064            dc.l   lab1 + equ1
 939            6 0000000C 7FFFFFE6            dc.l   (equl + ~equ2) >> 1
 940            7 00000010 0001                dc.w   ^^defined equl
 941            8 00000012 0000                dc.w   ^^referenced lab2
 942            9 00000014 00000002            dc.l   lab2
 943           10 00000018 0001                dc.w   ^^referenced lab2
 944           11 0000001A 0001                dc.w   lab1 = (lab2 - 6)
 945
 946 Lines 1 through four here are used to set up the rest of the example. Line 5 deposits
 947 a relocatable pointer to the location 100 bytes beyond the label "**lab1**". Line 6 is
 948 a nonsensical expression that uses the and right-shift operators. Line 7 deposits
 949 a word of 1 because the symbol "**equ1**" is defined (in line 3).
 950
 951 Line 8 deposits a word of 0 because the symbol "**lab2**", defined in line 2, has
 952 not been referenced. But the expression in line 9 references the symbol "**lab2**", so
 953 line 10 (which is a copy of line-8) deposits a word of 1. Finally, line 11 deposits a
 954 word of 1 because the Boolean equality operator evaluates to true.
 955
 956 The operators "**^^defined**" and "**^^referenced**" are particularly useful in
 957 conditional assembly. For instance, it is possible to automatically include debugging
 958 code if the debugging code is referenced, as in:
 959
 960       ::
 961
 962                lea    string,a0            ; AO -> message
 963                jsr    debug                ; print a message
 964                its                         ; and return
 965         string: dc.b  "Help me, Spock!",0  ; (the message)
 966                     .
 967                     .
 968                     .
 969                .iif ^^defined debug, .include "debug.s"
 970
 971 The **jsr** statement references the symbol debug. Near the end of the source file, the
 972 "**.iif**' statement includes the file "**debug.s**" if the symbol debug was referenced.
 973
 974 In production code, presumably all references to the debug symbol will be removed,
 975 and the debug source file will not be included. (We could have as easily made the
 976 symbol **debug** external, instead of including another source file).
 977
 978
 979 `Directives`_
 980 =============
 981
 982 Assembler directives may be any mix of upper- or lowercase. The leading periods
 983 are optional, though they are shown here and their use is encouraged. Directives
 984 may be preceeded by a label; the label is defined before the directive is executed.
 985 Some directives accept size suffixes (**.b**, **.s**, **.w** or **.1**); the default is word (**.w**) if no
 986 size is specified. The **.s** suffix is identical to **.b**. Directives relating to the 6502 are
 987 described in the chapter on `6502 Support`_.
 988
 989
 990
 991 **.even**
 992    If the location counter for the current section is odd, make it even by adding
 993    one to it. In text and data sections a zero byte is deposited if necessary.
 994 **.assert** *expression* [,\ *expression*...]
 995    Assert that the conditions are true (non-zero). If any of the comma-seperated
 996    expressions evaluates to zero an assembler warning is issued. For example:
 997
 998           ::
 999
1000            .assert *-start = $76
1001            .assert stacksize >= $400
1002
1003 **.bss**
1004
1005 **.data**
1006
1007 **.text**
1008    Switch to the BSS, data or text segments. Instructions and data may not
1009    be assembled into the BSS-segment, but symbols may be defined and storage
1010    may be reserved with the **.ds** directive. Each assembly starts out in the text
1011    segment.
1012 **.abs** [*location*]
1013    Start an absolute section, beginning with the specified location (or zero, if
1014    no location is specified). An absolute section is much like BSS, except that
1015    locations declared with .ds are based absolute. This directive is useful for
1016    declaring structures or hardware locations.
1017    For example, the following equates:
1018
1019           ::
1020
1021            VPLANES = 0
1022            VWRAP   = 2
1023            CONTRL  = 4
1024            INTIN   = 8
1025            PTSIN   = 12
1026
1027    could be as easily defined as:
1028
1029           ::
1030
1031                    .abs
1032            VPLANES: ds.w    1
1033            VWRAP:  ds.w     1
1034            CONTRL: ds.l     1
1035            INTIE:  ds.l     1
1036            PTSIN:  ds.l     1
1037
1038 **.comm** *symbol*, *expression*
1039   Specifies a label and the size of a common region. The label is made global,
1040   thus confined symbols cannot be made common. The linker groups all com-
1041   mon regions of the same name; the largest size determines the real size of the
1042   common region when the file is linked.
1043
1044 **.dc**\ [.\ *size*] *expression* [, *expression*...]
1045   Deposit initialized storage in the current section. If the specified size is word
1046   or long, the assembler will execute a .even before depositing data. If the size
1047   is .b, then strings that are not part of arithmetic expressions are deposited
1048   byte-by-byte. If no size is specified, the default is .w. This directive cannot be
1049   used in the BSS section.
1050
1051 **.dcb**\ [.\ *size*] *expression1*, *expression2*
1052   Generate an initialized block of *expression1* bytes, words or longwords of the
1053   value *expression2*. If the specified size is word or long, the assembler will
1054   execute .even before generating data. If no size is specified, the default is **.w**.
1055   This directive cannot be used in the BSS section.
1056
1057 **.ds**\ [.\ *size*] *expression*
1058   Reserve space in the current segment for the appropriate number of bytes,
1059   words or longwords. If no size is specified, the default size is .w. If the size
1060   is word or long, the assembler will execute .even before reserving space. This
1061   directive can only be used in the BSS or ABS sections (in text or data, use
1062   .dcb to reserve large chunks of initialized storage.)
1063
1064 **.init**\ [.\ *size*] [#\ *expression*,]\ *expression*\ [.\ *size*] [,...]
1065   Generalized initialization directive. The size specified on the directive becomes
1066   the default size for the rest of the line. (The "default" default size is **.w**.) A
1067   comma-seperated list of expressions follows the directive; an expression may be
1068   followed by a size to override the default size. An expression may be preceeded
1069   by a sharp sign, an expression and a comma, which specifies a repeat count to
1070   be applied to the next expression. For example:
1071
1072       ::
1073
1074        .init.l -1, 0.w, #16,'z'.b, #3,0, 11.b
1075
1076   will deposit a longword of -1, a word of zero, sixteen bytes of lower-case 'z',
1077   three longwords of zero, and a byte of 11.
1078
1079   No auto-alignment is performed within the line, but a **.even** is done once
1080   (before the first value is deposited) if the default size is word or long.
1081
1082 **.cargs** [#\ *expression*,] *symbol*\ [.\ *size*] [, *symbol*\ [.\ *size*].. .]
1083   Compute stack offsets to C (and other language) arguments. Each symbol is
1084   assigned an absolute value (like equ) which starts at expression and increases
1085   by the size of each symbol, for each symbol. If the expression is not supplied,
1086   the default starting value is 4. For example:
1087
1088     ::
1089
1090      .cargs #8, .fileliams.1, .openMode, .butPointer.l
1091
1092   could be used to declare offsets from A6 to a pointer to a filename, a word
1093   containing an open mode, and a pointer to a buffer. (Note that the symbols
1094   used here are confined). Another example, a C-style "string-length" function,
1095   could be written as:
1096
1097         ::
1098
1099          _strlen:: .cargs .string     ; declare arg
1100                move.l .string(sp),a0  ; a0 -> string
1101                moveq  #-1,d0          ; initial size = -1
1102          .1:   addq.1 #1,d0           ; bump size
1103                tst.b  (a0)+           ; at end of string?
1104                bne   .1               ; (no -- try again)
1105                rts                    ; return string length
1106
1107 **.end**
1108    End the assembly. In an include file, end the include file and resume assembling
1109    the superior file. This statement is not required, nor are warning messages
1110    generated if it is missing at the end of a file. This directive may be used inside
1111    conditional assembly, macros or **.rept** blocks.
1112
1113 **.if** *expression*
1114
1115 **.else**
1116
1117 **.endif**
1118
1119    Start a block of conditional assembly. If the expression is true (non-zero) then
1120    assemble the statements between the .if and the matching **.endif** or **.else**.
1121    If the expression is false, ignore the statements unless a matching .else is
1122    encountered. Conditional assembly may be nested to any depth.
1123
1124    It is possible to exit a conditional assembly block early from within an include
1125    file (with **end**) or a macro (with **endm**).
1126
1127 **.iif** *expression*, *statement*
1128
1129    Immediate version of **.if**. If the expression is true (non-zero) then the state-
1130    ment, which may be an instruction, a directive or a macro, is executed. If
1131    the expression is false, the statement is ignored. No **.endif** is required. For
1132    example:
1133
1134         ::
1135
1136          .iif age < 21, canDrink = 0
1137          .iif weight > 500, dangerFlag = 1
1138          .iif !(^^defined DEBUG), .include dbsrc
1139
1140 **.macro** *name* [*formal*, *formal*,...]
1141
1142 **.endm**
1143
1144 **.exitm**
1145    Define a macro called name with the specified formal arguments. The macro
1146    definition is terminated with a **.endm** statement. A macro may be exited early
1147    with the .exitm directive. See the chapter on `Macros`_ for more information.
1148
1149 **.undefmac** *macroName* [, *macroName*...]
1150    Remove the macro-definition for the specified macro names. If reference is
1151    made to a macro that is not defined, no error message is printed and the name
1152    is ignored.
1153
1154 **.rept** *expression*
1155
1156 **.endr**
1157    The statements between the **.rept** and **.endr** directives will be repeated *expression*
1158    times. If the expression is zero or negative, no statements will be
1159    assembled. No label may appear on a line containing either of these directives.
1160
1161 **.globl** *symbol* [, *symbol*...]
1162
1163 **.extern** *symbol* [, *symbol*...]
1164    Each symbol is made global. None of the symbols may be confined symbols
1165    (those starting with a period). If the symbol is defined in the assembly, the
1166    symbol is exported in the object file. If the symbol is undefined at the end
1167    of the assembly, and it was referenced (i.e. used in an expression), then the
1168    symbol value is imported as an external reference that must be resolved by the
1169    linker. The **.extern** directive is merely a synonym for **.globl**.
1170
1171 **.include** "*file*"
1172       Include a file. If the filename is not enclosed in quotes, then a default extension
1173       of "**.s**" is applied to it. If the filename is quoted, then the name is not changed
1174       in any way.
1175
1176   Note: If the filename is not a valid symbol, then the assembler will generate an
1177              error message. You should enclose filenames such as "**atari.s**" in quotes,
1178              because such names are not symbols.
1179
1180       If the include file cannot be found in the current directory, then the direc-
1181       tory search path, as specified by -i on the commandline, or' by the 'MACPATH'
1182       enviroment string, is traversed.
1183
1184 **.eject**
1185       Issue a page eject in the listing file.
1186
1187 **.title** "*string*"
1188
1189 **.subttl** [-] "*string*"
1190       Set the title or subtitle on the listing page. The title should be specified on
1191       the the first line of the source program in order to take effect on the first page.
1192       The second and subsequent uses of **.title** will cause page ejects. The second
1193       and subsequent uses of .subttl will cause page ejects unless the subtitle string
1194       is preceeded by a dash (-).
1195
1196 **.list**
1197
1198 **.nlist**
1199       Enable or disable source code listing. These directives increment and decrement
1200       an internal counter, so they may be appropriately nested. They have no effect
1201       if the **-l** switch is not specified on the commandline.
1202
1203 **.goto** *label*
1204       This directive provides unstructured flow of control within a macro definition.
1205       It will transfer control to the line of the macro containing the specified goto
1206       label. A goto label is a symbol preceeded by a colon that appears in the first
1207       column of a source line within a macro definition:
1208
1209                     :  *label*
1210
1211       where the label itself can be any valid symbol name, followed immediately by
1212       whitespace and a valid source line (or end of line). The colon **must** appear in
1213       the first column.
1214
1215       The goto-label is removed from the source line prior to macro expansion -
1216       to all intents and purposes the label is invisible except to the .goto directive
1217       Macro expansion does not take place within the label.
1218
1219       For example, here is a silly way to count from 1 to 10 without using **.rept**:
1220
1221                  ::
1222
1223                                   .macro Count
1224                     count         set     1
1225                     :loop         dc.w    count
1226                     count         set     count + 1
1227                                   iif count <= 10, goto loop
1228                                   .endm
1229
1230 `68000 Mnemonics`_
1231 ==================
1232
1233 `Mnemonics`_
1234 ''''''''''''
1235 All of the standard Motorola 68000 mnemonics and addressing modes are supported;
1236 you should refer to **The Motorola M68000 Programmer's Reference Manual**
1237 for a description of the instruction set and the allowable addressing modes for each
1238 instruction. With one major exception (forward branches) the assembler performs
1239 all the reasonable optimizations of instructions to their short or address register
1240 forms.
1241
1242 Register names may be in upper or lower case. The alternate forms ``R0`` through
1243 ``R15`` may be used to specify ``D0`` through ``A7``. All register names are keywords, and
1244 may not be used as labels or symbols. None of the 68010 or 68020 register names
1245 are keywords (but they may become keywords in the future).
1246
1247 `Addressing Modes`_
1248 '''''''''''''''''''
1249
1250 =====================================    ===========================================
1251 Assembler Syntax                         Description
1252 =====================================    ===========================================
1253 *Dn*                                     Data register direct
1254 *An*                                     Address register direct
1255 (*An*)                                   Address register indirect
1256 (*An*)+                                  Address register indirect postincrement
1257 -(*An*)                                  Address register indirect predecrement
1258 *disp*\ (*An*)                           Address register indirect with displacement
1259 *bdisp*\ (*An*, *Xi*\ [.\ *size*])       Address register indirect indexed
1260 *abs*.w                                  Absolute short
1261 *abs*                                    Absolute (long or short)
1262 *abs*.l                                  Forced absolute long
1263 *disp*\ (PC)                             Program counter with displacement
1264 *bdisp*\ (PC, *Xi*\ )                    Program counter indexed
1265 #\ *imm*                                 Immediate
1266 =====================================    ===========================================
1267
1268 `Branches`_
1269 '''''''''''
1270 Since MADMAC is a one pass assembler, forward branches cannot be automatically
1271 optimized to their short form. Instead, unsized forward branches are assumed to
1272 be long. Backward branches are always optimized to the short form if possible.
1273
1274 A table that lists "extra" branch mnemonics (common synonyms for the Motorola
1275 defined mnemonics) appears below.
1276
1277 `Linker Constraints`_
1278 '''''''''''''''''''''
1279 It is not possible to make an external reference that will fix up a byte. For example:
1280
1281                    ::
1282
1283                      extern frog
1284                     move.l frog(pc,d0),d1
1285
1286 is illegal (and generates an assembly error) when frog is external, because the
1287 displacement occupies a byte field in the 68000 offset word, which the object file
1288 cannot represent.
1289
1290 `Branch Synonyms`_
1291 ''''''''''''''''''
1292 ============== ========
1293 Alternate name Becomes:
1294 ============== ========
1295 bhs            bcc
1296 blo            bcs
1297 bse, bs        beq
1298 bns            bne
1299 dblo           dbcs
1300 dbse           dbeq
1301 dbra           dbf
1302 dbhs           dbhi
1303 dbns           dbne
1304 ============== ========
1305
1306 `Optimizations and Translations`_
1307 '''''''''''''''''''''''''''''''''
1308 The assembler provides "creature comforts" when it processes 68000 mnemonics:
1309
1310  o **CLR.x An** will really generate **SUB.x An,An**.
1311
1312  o **ADD**, **SUB** and **CMP** with an address register will really generate **ADDA**,
1313  **SUBA** and **CMPA**.
1314
1315  o The **ADD**, **AND**, **CMP**, **EOR**, **OR and **SUB** mnemonics with immediate
1316  first operands will generate the "I" forms of their instructions (**ADDI**, etc.) if
1317  the second operand is not register direct.
1318
1319  o All shift instructions with no count value assume a count of one.
1320
1321  o **MOVE.L** is optimized to **MOVEQ** if the immediate operand is defined and
1322  in the range -128...127. However, **ADD** and **SUB** are never translated to
1323  their quick forms; **ADDQ** and **SUBQ** must be explicit.
1324
1325 `Macros`_
1326 =========
1327 `Macro declaration`_
1328 ''''''''''''''''''''
1329 A macro definition is a series of statements of the form:
1330                               ::
1331
1332                                  .macro name [ formal-arg, ...]
1333                                     .
1334                                     .
1335                                     .
1336                                  statements making up the macro body
1337                                     .
1338                                     .
1339                                     .
1340                                  .endm
1341
1342 The name of the macro may be any valid symbol that is not also a 68000 instruction
1343 or an assembler directive. (The name may begin with a period - macros cannot
1344 be made confined the way labels or equated symbols can be). The formal argument
1345 list is optional; it is specified with a comma-seperated list of valid symbol names.
1346 Note that there is no comma between the name of the macro and the name of the
1347 first formal argument.
1348
1349 A macro body begins on the line after the **.macro** directive. All instructions
1350 and directives, except other macro definitions, are legal inside the body.
1351
1352 The macro ends with the **.endm** statement. If a label appears on the line with
1353 this directive, the label is ignored and a warning is generated.
1354
1355 `Parameter Substitution`_
1356 '''''''''''''''''''''''''
1357 Within the body, formal parameters may be expanded with the special forms:
1358               ::
1359
1360                 \name
1361                 \{name}
1362
1363 The second form (enclosed in braces) can be used in situations where the characters
1364 following the formal parameter name are valid symbol continuation characters. This
1365 is usually used to force concatentation, as in:
1366
1367                ::
1368
1369                 \{frog}star
1370                 \(godzilla}vs\{reagan}
1371
1372 The formal parameter name is terminated with a character that is not valid in
1373 a symbol (e.g. whitespace or puncuation); optionally, the name may be enclosed in
1374 curly-braces. The names must be symbols appearing on the formal argument list,
1375 or a single decimal digit (``\1`` corresponds to the first argument, ``\2`` to the second,
1376 ``\9`` to the ninth, and ``\0`` to the tenth). It is possible for a macro to have more than
1377 ten formal arguments, but arguments 11 and on must be referenced by name, not
1378 by number.
1379
1380         Other special forms are:
1381
1382 ============ ================================================
1383 Special Form Description
1384 ============ ================================================
1385 ``\\``       a single "\",
1386 ``\~``       a unique label of the form "Mn"
1387 ``\#``       the number of arguments actually specified
1388 ``\!``       the "dot-size" specified on the macro invocation
1389 ``\?name``   conditional expansion
1390 ``\?{name}`` conditional expansion
1391 ============ ================================================
1392
1393 The last two forms are identical: if the argument is specified and is non-empty, the
1394 form expands to a "1", otherwise (if the argument is missing or empty) the form
1395 expands to a "0".
1396
1397 The form "``\!``" expands to the "dot-size" that was specified when the macro
1398 was invoked. This can be used to write macros that behave differently depending
1399 on the size suffix they are given, as in this macro which provides a synonym for the
1400 "``dc``" directive:
1401
1402               ::
1403
1404                .macro deposit value
1405                dc\!   \value
1406                .endm
1407                deposit.b 1          ; byte of 1
1408                deposit.w 2          ; word of 2
1409                deposit.l 3          ; longvord of 3
1410                deposit   4          ; word of 4 (no explicit size)
1411
1412 `Macro Invocation`_
1413 '''''''''''''''''''
1414 A previously-defined macro is called when its name appears in the operation field of
1415 a statement. Arguments may be specified following the macro name; each argument
1416 is seperated by a comma. Arguments may be empty. Arguments are stored for
1417 substitution in the macro body in the following manner:
1418
1419   o Numbers are converted to hexadecimal.
1420
1421   o All spaces outside strings are removed.
1422
1423   o Keywords (such as register names, dot sizes and "^^" operators) are converted
1424     to lowercase.
1425
1426   o Strings are enclosed in double-quote marks (").
1427
1428 For example, a hypothetical call to the macro "``mymacro``", of the form:
1429        ``mymacro A0, , 'Zorch' / 32, "^^DEFINED foo, , , tick tock``
1430
1431 will result in the translations:
1432
1433 ========      ================= =================================================
1434 Argument      Expansion         Comment
1435 ========      ================= =================================================
1436 ``\1``        ``a0``            "``A0``" converted to lower-case
1437 ``\2``                          empty
1438 ``\3``        ``"Zorch"/$20``   "``Zorch``" in double-quotes, 32 in hexadecimal
1439 ``\4``        ``^^defined foo`` "``^^DEFINED``" converted to lower-case
1440 ``\5``                          empty
1441 ``\6``                          empty
1442 ``\7``        ``ticktock``      spaces removed (note concatenation)
1443 ========      ================= =================================================
1444
1445 The **.exitm** directive will cause an immediate exit from a macro body. Thus
1446 the macro definition:
1447
1448          ::
1449
1450           .macro foo source
1451               .iif !\?source, .exitm ; exit if source is empty
1452               move \source,d0        ; otherwise, deposit source
1453           .endm
1454
1455 will not generate the move instruction if the argument **"source"** is missing from
1456 the macro invocation.
1457
1458 The **.end**, **.endif** and **.exitm** directives all pop-out of their include levels
1459 appropriately. That is, if a macro performs a **.include** to include a source file, an
1460 executed **.exitm** directive within the include-file will pop out of both the include-file
1461 and the macro.
1462
1463 Macros may be recursive or mutually recursive to any level, subject only to
1464 the availability of memory. When writing recursive macros, take care in the coding
1465 of the termination condition(s). A macro that repeatedly calls itself will cause the
1466 assembler to exhaust its memory and abort the assembly.
1467
1468
1469 `Example Macros`_
1470 '''''''''''''''''
1471 The Gemdos macro is used to make file system calls. It has two parameters, a
1472 function number and the number of bytes to clean off the stack after the call. The
1473 macro pushes the function number onto the stack and does the trap to the file
1474 system. After the trap returns, conditional assembly is used to choose an addq or
1475 an **add.w** to remove the arguments that were pushed.
1476
1477      ::
1478
1479        .macro Gemdos trpno, clean
1480           move.w  #\trpno,-(sp)  ; push trap number
1481           trap    #1             ; do GEMDOS trap
1482           .if \clean <= 8        ;
1483           addq    #\clean,sp     ; clean-up up to 8 bytes
1484           .else                  ;
1485           add.w   #\clean,sp     ; clean-up more than 8 bytes
1486           .endif                 ;
1487        .endm
1488
1489 The Fopen macro is supplied two arguments; the address of a filename, and
1490 the open mode. Note that plain move instructions are used, and that the caller of
1491 the macro must supply an appropriate addressing mode (e.g. immediate) for each
1492 argument.
1493
1494      ::
1495
1496        .macro Fopen file, mode
1497           movs.w   \mode,-(sp)  ;push open mode
1498           move.1   \file,-(sp)  ;push address of tile name
1499           Gemdos   $3d,8        ;do the GEMDOS call
1500        .endm
1501
1502 The **String** macro is used to allocate storage for a string, and to place the
1503 string's address somewhere. The first argument should be a string or other expres-
1504 sion acceptable in a dc.b directive. The second argument is optional; it specifies
1505 where the address of the string should be placed. If the second argument is omitted,
1506 the string's address is pushed onto the stack. The string data itself is kept in the
1507 data segment.
1508
1509                   ::
1510
1511                    .macro String str,loc
1512                        .if \?loc                                        ; if loc is defined
1513                          move.l #.\~,\loc                               ; put the string's address there
1514                        .else                                            ; otherwise
1515                          pea .\~                                        ; push the string's address
1516                        .endif                                           ;
1517                        .data                                            ; put the string data
1518                    .\~: dc.b \str,0                                     ;  in the data segment
1519                        .text                                            ; and switch back to the text segment
1520                    .endm
1521
1522 The construction "``.\~``" will expand to a label of the form "``.M``\ *n*" (where *n* is
1523 a unique number for every macro invocation), which is used to tag the location of
1524 the string. The label should be confined because the macro may be used along with
1525 other confined symbols.
1526
1527 Unique symbol generation plays an important part in the art of writing fine
1528 macros. For instance, if we needed three unique symbols, we might write "``.a\~``",
1529 "``.b\~``" and "``.c\~``".
1530
1531 `Repeat Blocks`_
1532 ''''''''''''''''
1533 Repeat-blocks provide a simple iteration capability. A repeat block allows a range
1534 of statements to be repeated a specified number of times. For instance, to generate
1535 a table consisting of the numbers 255 through 0 (counting backwards) you could
1536 write:
1537
1538                   ::
1539
1540                    .count  set     255             ; initialize counter
1541                            .rept 256               ; repeat 256 times:
1542                            dc.b    .count          ;   deposit counter
1543                    .count  set     .count - 1      ;   and decrement it
1544                            .endr                   ; (end of repeat block)
1545
1546 Repeat blocks can also be used to duplicate identical pieces of code (which are
1547 common in bitmap-graphics routines). For example:
1548
1549                   ::
1550
1551                    .rept 16                        ; clear 16 words
1552                    clr.w (a0)+                     ;   starting at AO
1553                    .endr                           ;
1554
1555 `6502 Support`_
1556 ===============
1557 MADMAC will generate code for the Motorola 6502 microprocessor. This chapter
1558 describes extra addressing modes and directives used to support the 6502.
1559
1560 As the 6502 object code is not linkable (currently there is no linker) external
1561 references may not be made. (Nevertheless, MADMAC may reasonably be used for
1562 large assemblies because of its blinding speed.)
1563
1564 `6502 Addressing Modes`_
1565 ''''''''''''''''''''''''
1566 All standard 6502 addressing modes are supported, with the exception of the
1567 accumulator addressing form, which must be omitted (e.g. "ror a" becomes "ror").
1568 Five extra modes, synonyms for existing ones, are included for compatibility with
1569 the Atari Coinop assembler.
1570
1571 ============== ========================================
1572 *empty*        implied or accumulator (e.g. tsx or ror)
1573 *expr*         absolute or zeropage
1574 #\ *expr*      immediate
1575 (*expr*,x)     indirect X
1576 (*expr*),y     indirect Y
1577 (*expr*)       indirect
1578 *expr*,x       indexed X
1579 *expr*,y       indexed Y
1580 @\ *expr*\ (x) indirect X
1581 @\ *expr*\ (y) indirect Y
1582 @expr          indirect
1583 x,*expr*       indexed X
1584 y,*expr*       indexed Y
1585 ============== ========================================
1586
1587 While MADMAC lacks "high" and "low" operators, high bytes of words may
1588 be extracted with the shift (``>>``) or divide (``/``) operators, and low bytes may be
1589 extracted with the bitwise AND (``&``) operator.
1590
1591 `6502 Directives`_
1592 ''''''''''''''''''
1593 **.6502**
1594    This directive enters the 6502 section. The location counter is undefined, and
1595    must be set with ".org" before any code can be generated.
1596
1597    The "``dc.w``" directive will produce 6502-format words (low byte first). The
1598    68000's reserved keywords (``d0-d7/a0-a7/ssp/usp`` and so on) remain reserved
1599    (and thus unusable) while in the 6502 section. The directives **globl**, **dc.l**,
1600    **dcb.l**, **text**, **data**, **bss**, **abs**, **even** and **comm** are illegal in the 6502 section.
1601    It is permitted, though probably not useful, to generate both 6502 and 68000
1602    code in the same object file.
1603 **.68000**
1604    This directive leaves the 6502 segment and returns to the 68000's text segment.
1605    68000 instructions may be assembled as normal.
1606 **.org** *location*
1607    This directive is only legal in the 6502 section. It sets the value of the location
1608    counter (or **pc**) to location, an expression that must be defined, absolute, and
1609    less than $10000.
1610
1611    WARNING
1612
1613    It is possible to assemble "beyond" the microprocessor's 64K address space, but
1614    attempting to do so will probably screw up the assembler. DO NOT attempt
1615    to generate code like this:
1616
1617      ::
1618
1619       .org $fffe
1620       nop
1621       nop
1622       nop
1623
1624    the third NOP in this example, at location $10000, may cause the assembler
1625    to crash or exhibit spectacular schizophrenia. In any case, MADMAC will give
1626    no warning before flaking out.
1627
1628 `6502 Object Code Format`_
1629 ''''''''''''''''''''''''''
1630 This is a little bit of a kludge. An object file consists of a page map, followed by
1631 one or more page images, followed by a normal Alcyon 68000 object file. If the page
1632 map is all zero, it is not written.
1633
1634 The page map contains a byte for each of the 256 256-byte pages in the 6502's
1635 64K address space. The byte is zero (``$00``) if the page contained only zero bytes, or
1636 one (``$01``) if the page contained any non-zero bytes. If a page is flagged with a one,
1637 then it is written (in order) following the page map.
1638
1639 The following code:
1640
1641      ::
1642
1643       .6502
1644       .org  $8000
1645       .dc.b 1
1646       .org  $8100
1647       .dc.b 1
1648       .org  $8300
1649       .dc.b 1
1650       .end
1651
1652 will generate a page map that looks (to a programmer) something like:
1653
1654      ::
1655
1656       <80 bytes of zero>
1657       01 01 00 01
1658       <$7c more bytes of zero, for $100 total>
1659       <image of page $80>
1660       <image of page $81>
1661       <image of page $83>
1662
1663 Following the last page image is an Alcyon-format object file, starting with
1664 the magic number ``$601a``. It may contain 68000 code (although that is probably
1665 useless), but the symbol table is valid and available for debugging purposes. 6502
1666 symbols will be absolute (not in text, data or bss).
1667
1668 `Error Messages`_
1669 =================
1670
1671 `When Things Go Wrong`_
1672 '''''''''''''''''''''''
1673 Most of MADMAC's error messages are self-explanatory. They fall into four classes:
1674 warnings about situations that you (or the assembler) may not be happy about,
1675 errors that cause the assembler to not generate object files, fatal errors that cause
1676 the assembler to abort immediately, and internal errors that should never happen.\ [3]_
1677
1678 You can write editor macros (or sed or awk scripts) to parse the error messages
1679 MADMAC generates. When a message is printed, it is of the form:
1680
1681          "*filename*" , ``line`` *line-number*: *message*
1682
1683 The first element, a filename enclosed in double quotes, indicates the file that generated
1684 the error. The filename is followed by a comma, the word "``line``", and a line
1685 number, and finally a colon and the text of the message. The filename "**(\*top\*)**"
1686 indicates that the assembler could not determine which file had the problem.
1687
1688 The following sections list warnings, errors and fatal errors in alphabetical
1689 order, along with a short description of what may have caused the problem.
1690
1691 `Warnings`_
1692 '''''''''''
1693 **bad backslash code in string**
1694   You tried to follow a backslash in a string with a character that the assembler
1695   didn't recognize. Remember that MADMAC uses a C-style escape system in
1696   strings.
1697 **label ignored**
1698   You specified a label before a macro, **rept** or **endm** directive. The assembler
1699   is warning you that the label will not be defined in the assembly.
1700 **unoptimized short branch**
1701   This warning is only generated if the -s switch is specified on the command
1702   line. The message refers to a forward, unsized long branch that you could have
1703   made short (.s).
1704
1705 `Fatal Errors`_
1706 '''''''''''''''
1707
1708 **cannot continue**
1709   As a result of previous errors, the assembler cannot continue processing. The
1710   assembly is aborted.
1711 **line too long as a result of macro expansion**
1712   When a source line within a macro was expanded, the resultant line was too
1713   long for MADMAC (longer than 200 characters or so).
1714
1715
1716 .. [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.
1717
1718 **memory exhausted**
1719     The assembler ran out of memory. You should (1) split up your source files
1720     and assemble them seperately, or (2) if you have any ramdisks or RAM-resident
1721     programs (like desk accessories) decrease their size so that the assembler has
1722     more RAM to work with. As a rule of thumb, pure 68000 code will use up to
1723     twice the number of bytes contained in the source files, whereas 6502 code will
1724     use 64K of ram right away, plus the size of the source files. The assembler itself
1725     uses about 80K bytes. Get out your calculator...
1726 **too many ENDMs**
1727     The assembler ran across an **endm** directive when it wasn't expecting to see
1728     one. The assembly is aborted. Check the nesting of your macro definitions -
1729     you probably have an extra **endm**.
1730
1731
1732 `Errors`_
1733 '''''''''
1734
1735 **.cargs syntax**
1736     Syntax error in **.cargs** directive.
1737 **.comm symbol already defined**
1738     You tried to ``.comm`` a symbol that was already defined.
1739 **.ds permitted only in BSS**
1740     You tried to use ``.ds`` in the text or data section.
1741 **.init not permitted in BSS or ABS**
1742     You tried to use ``.init`` in the BSS or ABS section.
1743 **.org permitted only in .6502 section**
1744     You tried to use ``.org`` in a 68000 section.
1745 **Cannot create:** *filename*
1746     The assembler could not create the indicated filename.
1747 **External quick reference**
1748     You tried to make the immediate operand of a **moveq**, **subq** or **addq** instruction external.
1749 **PC-relative expr across sections**
1750     You tried to make a PC-relative reference to a location contained in another
1751     section.
1752 **[bwsl] must follow '.' in symbol**
1753     You tried to follow a dot in a symbol name with something other than one of
1754     the four characters 'B', 'W', 'S' or 'L'.
1755 **addressing mode syntax**
1756     You made a syntax error in an addressing mode.
1757 **assert failure**
1758     One of your **.assert** directives failed!
1759 **bad (section) expression**
1760     You tried to mix and match sections in an expression
1761 **bad 6502 addressing mode**
1762     The 6502 mnemonic will not work with the addressing mode you specified.
1763 **bad expression**
1764     There's a syntax error in the expression you typed.
1765 **bad size specified**
1766   You tried to use an inappropriate size suffix for the instruction. Check your
1767   68000 manual for allowable sizes.
1768 **bad size suffix**
1769   You can't use .b (byte) mode with the **movem** instruction.
1770 **cannot .globl local symbol**
1771   You tried to make a confined symbol global or common.
1772 **cannot initialize non-storage (BSS) section**
1773   You tried to generate instructions (or data, with dc) in the BSS or ABS section.
1774 **cannot use '.b' with an address register**
1775   You tried to use a byte-size suffix with an address register. The 68000 does not
1776   perform byte-sized address register operations.
1777 **directive illegal in .6502 section**
1778   You tried to use a 68000-oriented directive in the 6502 section.
1779 **divide by zero**
1780   The expression you typed involves a division by zero.
1781 expression out of range
1782   The expression you typed is out of range for its application.
1783 **external byte reference**
1784   You tried to make a byte-sized reference to an external symbol, which the
1785   object file format will not allow
1786 **external short branch**
1787   You tried to make a short branch to an external symbol, which the linker cannot
1788   handle.
1789 **extra (unexpected) text found after addressing mode**
1790   MADMAC thought it was done processing a line, but it ran up against "extra"
1791   stuff. Be sure that any comment on the line begins with a semicolon, and check
1792   for dangling commas, etc.
1793 **forward or undefined .assert**
1794   The expression you typed after a **.assert** directive had an undefined value.
1795   Remember that MADMAC is one-pass.
1796 **hit EOF without finding matching .endif**
1797   The assembler fell off the end of last input file without finding a **.endif** to
1798   match an . it. You probably forgot a **.endif** somewhere.
1799 **illegal 6502 addressing mode**
1800   The 6502 instruction you typed doesn't work with the addressing mode you
1801   specified.
1802 **illegal absolute expression**
1803   You can't use an absolute-valued expression here.
1804 **illegal bra.s with zero offset**
1805   You can't do a short branch to the very next instruction (read your 68000
1806   manual).
1807 **illegal byte-sized relative reference**
1808   The object file format does not permit bytes contain relocatable values; you
1809   tried to use a byte-sized relocatable expression in an immediate addressing
1810   mode.
1811 **illegal character**
1812  Your source file contains a character that MADMAC doesn't allow. (most
1813  control characters fall into this category).
1814 **illegal initialization of section**
1815  You tried to use .dc or .dcb in the BSS or ABS sections.
1816 **illegal relative address**
1817  The relative address you specified is illegal because it belongs to a different
1818  section.
1819 **illegal word relocatable (in .PRG mode)**
1820  You can't have anything other than long relocatable values when you're gener-
1821  ating a **.PRG** file.
1822 **inappropriate addressing mode**
1823  The mnemonic you typed doesn't work with the addressing modes you specified.
1824  Check your 68000 manual for allowable combinations.
1825 **invalid addressing mode**
1826  The combination of addressing modes you picked for the **movem** instruction
1827  are not implemented by the 68000. Check your 68000 reference manual for
1828  details.
1829 **invalid symbol following ^^**
1830  What followed the ^^ wasn't a valid symbol at all.
1831 **mis-nested .endr**
1832  The assembler found a **.endr** directive when it wasn't prepared to find one.
1833  Check your repeat-block nesting.
1834 **mismatched .else**
1835  The assembler found a **.else** directive when it wasn't prepared to find one.
1836  Check your conditional assembly nesting.
1837 **mismatched .endif**
1838  The assembler found a **.endif** directive when it wasn't prepared to find one.
1839  Check your conditional assembly nesting.
1840
1841 **missing '='**
1842
1843 **missing '}'**
1844
1845 **missing argument name**
1846
1847 **missing close parenthesis ')'**
1848
1849 **missing close parenthesis ']'**
1850
1851 **missing comma**
1852
1853 **missing filename**
1854
1855 **missing string**
1856
1857 **missing symbol**
1858
1859 **missing symbol or string**
1860  The assembler expected to see a symbol/filename/string (etc...), but found
1861  something else instead. In most cases the problem should be obvious.
1862 **misuse of '.', not allowed in symbols**
1863  You tried to use a dot (.) in the middle of a symbol name.
1864 **mod (%) by zero**
1865  The expression you typed involves a modulo by zero.
1866 **multiple formal argument definition**
1867   The list of formal parameter names you supplied for a macro definition includes
1868   two identical names.
1869 **multiple macro definition**
1870   You tried to define a macro which already had a definition.
1871 **non-absolute byte reference**
1872   You tried to make a byte reference to a relocatable value, which the object file
1873   format does not allow.
1874 **non-absolute byte value**
1875   You tried to dc.b or dcb.b a relocatable value. Byte relocatable values are
1876   not permitted by the object file format.
1877 **register list order**
1878   You tried to specify a register list like **D7-D0**, which is illegal. Remember
1879   that the first register number must be less than or equal to the second register
1880   number.
1881 **register list syntax**
1882   You made an error in specifying a register list for a **.reg** directive or a **.movem**
1883   instruction.
1884 **symbol list syntax**
1885   You probably forgot a comma between the names of two symbols in a symbol
1886   list, or you left a comma dangling on the end of the line.
1887 **syntax error**
1888   This is a "catch-all" error.
1889 **undefined expression**
1890   The expression has an undefined value because of a forward reference, or an
1891   undefined or external symbol.
1892 **unimplemented addressing mode**
1893   You tried to use 68020 "square-bracket" notation for a 68020 addressing mode.
1894   MADMAC does not support 68020 addressing modes.
1895 **unimplemented directive**
1896   You have found a directive that didn't appear in the documentation. It doesn't
1897   work.
1898 **unimplemented mnemonic**
1899   You've found an assembler for documentation) bug.
1900 **unknown symbol following ^^**
1901   You followed a ^^ with something other than one of the names defined, ref-
1902   erenced or streq.
1903 **unsupported 68020 addressing mode**
1904   The assembler saw a 68020-type addressing mode. MADMAC does not assem-
1905   ble code for the 68020 or 68010.
1906 **unterminated string**
1907   You specified a string starting with a single or double quote, but forgot to type
1908   the closing quote.
1909 **write error**
1910   The assembler had a problem writing an object file. This is usually caused by
1911   a full disk, or a bad sector on the media.