<appendix>
<title>Relocating Macro Assembler Reference</title>
<para>
This appendix gives a summary of the operation of the "Relocating
Macro Assembler" (named c.asm as distributed with the C Compiler).
This appendix and the example assembly source files supplied with
the C compiler should provide the basic information on how to use the
"Relocating Macro Assembler" to create relocatable-object format
files (ROF). It is further assumed that you are familiar with the
6809 instruction set and mnemonics. See the Microware Relocating
Assembler Manual for a more detailed description. The main function
of this appendix is to enable the reader to understand the output
produced by c.asm. The Relocating Macro Assembler allows programs
to be compiled separately and then linked together, and it also
allows macros to be defined within programs.
</para>
<para>
Differences between the Relocating Macro Assembler (RMA) and the
Microware Interactive Assembler (MIA):
</para>
<blockquote>
<para>
RMA does not have an interactive mode. Only a disk file is
allowed as input.
</para>
<para>
RMA output is an ROF file. The ROF file must be processed by
the linker to produce an executable OS9 memory module. The
layout of the ROF file is described later.
</para>
<para>
RMA has a number of new directives to control the placement of
code and data in the executable module. Since RMA does not
produce memory modules, the MIA directives "mod" and "emod" are
not present. Instead, new directives PSECT and VSECT control
the allocation of code and data areas by the linker.
</para>
<para>
RMA has no equivalent to the MIA "setdp" directive. Data (and
DP) allocation is handled by the linker.
</para>
</blockquote>
<section>
<title>Symbolic Names</title>
<para>
A symbolic name is valid if it consists of from one to nine
uppercase or lowercase characters, decimal digits or the characters
"$", "_", "." or "@". RMA does not fold lowercase letters to
uppercase. The names "Hi.you" and "HI.YOU" are distinct names.
</para>
</section>

<section>
<title>Label field</title>
<para>
If a symbolic name in the label field of a source statement is
followed by a <quote>:</quote> (colon), the name will be known
<emphasis>globally</emphasis> (by all modules linked together).
If no colon appears, the name will be known only in the PSECT
in which it was defined. PSECT will be described later.
</para>
</section>

<section>
<title>Undefined names</title>
<para>
</para>
</section>

<section>
<title>Listing format</title>
<para>
</para>
</section>

<section>
<title>Section Location Counters</title>
<para>
</para>
</section>

<section>
<title>Section Directives</title>
<para>
</para>

<section>
<title>PSECT Directive</title>
<para>
The main difference between PSECT and MOD is that MOD sets up
information for OS-9 and PSECT sets up information for the
linker (c.link in the C compiler).
</para>
<informalexample>
<para>
PSECT {name,typelang,attrrev,edition,stacksize,entrypoint}
</para>
<informaltable frame="none">
<tgroup cols="2">
<colspec colwidth="1in">
<tbody>
<row>
<entry>name</entry>
<entry>Up to 20 bytes (any printable character except space
or comma) for a name to be used by the linker to
identify this PSECT. This name need not be distinct
from all other PSECTs linked together, but it helps
to identify PSECTs the linker has a problem with if
the names are different.</entry>
</row> 
<row>
<entry>typelang</entry>
<entry></entry>
</row> 
<row>
<entry>attrrev</entry>
<entry></entry>
</row> 
<row>
<entry>edition</entry>
<entry></entry>
</row> 
<row>
<entry>stacksize</entry>
<entry></entry>
</row> 
<row>
<entry>entrypoint</entry>
<entry>word expression entrypoint offset for this PSECT.
If the PSECT is not a mainline odule, this should
be set to zero.</entry>
</row> 
</tbody>
</tgroup>
</informaltable>
</informalexample>
</section>

<section>
<title>VSECT Directive</title>
<para>
</para>
</section>

<section>
<title>CSECT Directive</title>
<para>
</para>
</section>

<section>
<title>RZB statement</title>
<para>
</para>
</section>
</section>

<section>
<title>Comparison Between Assembly Programs for the Microware Interactive Assember
and the Relocating Macro Assembler</title>
<para>
The following two program examples simply fork a BASIC09. The
purpose of the examples are to show some of the differences in the
new relocating assembler. The differences are apparent.
</para>
<programlisting>
* this program forks a basic09
          ifp1
          use ..../defs/os9defs.a
          endc


</programlisting>
<section>
<title>Macro Interactive Assembler Source</title>
<programlisting>
          ifp1
          use defsfile

prmsize   equ *-prm

siz       equ
</programlisting>
</section>
</section>

<section>
<title>Introduction to Macros</title>
<para>
</para>
</section>

<section>
<title>Operations</title>

<section>
<title>Macro Definition</title>
<para>
</para>
</section>

<section>
<title>Nested Macro Calls</title>
<para>
</para>
</section>

<section>
<title>Labels</title>
<para>
Sometimes it is necessary to use labels within a macro. Labels are
specified by <quote>\@</quote>. Each time the macro is called, a unique label
will be generated to avoid multiple definition errors. Within the
expanded code <quote>\@</quote> will take on the form <quote>@xxx</quote>, where xxx
will be a decimal number between 000 to 999.
</para>
<para>
More...
</para>
</section>

<section>
<title>Additional Pseudo-Instructions</title>
<variablelist>
<varlistentry><term>\n</term>
<listitem>
<para>
will return the number of arguments passed to the macro.
</para>
</listitem>
</varlistentry>

<varlistentry><term>\L&lt;num&gt;</term>
<listitem>
<para>
will return the length of the ith argument
that is specified by &lt;num&gt;.
</para>
</listitem>
</varlistentry>

<varlistentry><term>FAIL</term>
<listitem>
<para>
Causes an error to be generated.
</para>
</listitem>
</varlistentry>

<varlistentry><term>REPT &lt;num&gt;</term>
<listitem>
<para>
will repeat an instruction or group of instructions &lt;num&gt; times.
ENDR terminates REPT.
</para>
</listitem>
</varlistentry>

</variablelist>
</section>
</section>
</appendix>