diff doc/manual.docbook.sgml @ 237:dca5938a64aa

Updated documentation to reflect recent udates to LWASM
author lost
date Fri, 14 Aug 2009 04:20:15 +0000
parents aa0056ca7319
children b43e3e23583c
line wrap: on
line diff
--- a/doc/manual.docbook.sgml	Fri Aug 14 03:22:26 2009 +0000
+++ b/doc/manual.docbook.sgml	Fri Aug 14 04:20:15 2009 +0000
@@ -92,6 +92,35 @@
 </section>
 
 <section>
+<title>OS9 Modules</title>
+<para>
+
+Since version 2.5, LWASM is able to generate OS9 modules. The syntax is
+basically the same as for other assemblers.  A module starts with the MOD
+directive and ends with the EMOD directive.  The OS9 directive is provided
+as a shortcut for writing system calls.
+
+</para>
+
+<para>
+
+LWASM does NOT provide an OS9Defs file. You must provide your own. Also note
+that the common practice of using "ifp1" around the inclusion of the OS9Defs
+file is discouraged as it is pointless and can lead to unintentional
+problems and phasing errors.  Because LWASM reads each file exactly once,
+there is no benefit to restricting the inclusion to the first assembly pass.
+
+</para>
+
+<para>
+
+LWLINK does not, yet, have the ability to create OS9 modules from object
+files.
+
+</para>
+</section>
+
+<section>
 <title>Object Files</title>
 <para>LWASM supports generating a proprietary object file format which is
 described in <xref linkend="objchap">. LWLINK is then used to link these
@@ -184,9 +213,10 @@
 <term><option>-f type</option></term>
 <listitem>
 <para>
-Select the output format. Valid values are <option>obj</option> for the object
-file target, <option>decb</option> for the DECB LOADM format, and <option>raw</option>
-for a raw binary.
+Select the output format. Valid values are <option>obj</option> for the
+object file target, <option>decb</option> for the DECB LOADM format,
+<option>os9</option> for creating OS9 modules, and <option>raw</option> for
+a raw binary.
 </para>
 </listitem>
 </varlistentry>
@@ -383,6 +413,14 @@
 a local symbol is restricted to the block of code it is defined within.
 </para>
 
+<para>
+By default, unless assembling to the os9 target, a "$" in the symbol will
+also make it local.  This can be controlled by the "dollarlocal" and
+"nodollarlocal" pragmas.  In the absence of a pragma to the contrary, For
+the os9 target, a "$" in the symbol will not make it considered local while
+for all other targets it will.
+</para>
+
 </section>
 
 <section>
@@ -792,6 +830,60 @@
 </section>
 
 <section>
+<title>OS9 Target Directives</title>
+
+<para>This section includes directives that apply solely to the OS9
+target.</para>
+
+<variablelist>
+
+<varlistentry>
+<term>OS9 <parameter>syscall</parameter></term>
+<listitem>
+<para>
+
+This directive generates a call to the specified system call. <parameter>syscall</parameter> may be an arbitrary expression.
+
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>MOD <parameter>size</parameter>,<parameter>name</parameter>,<parameter>type</parameter>,<parameter>flags</parameter>,<parameter>execoff</parameter>,<parameter>datasize</parameter></term>
+<listitem>
+<para>
+
+This tells LWASM that the beginning of the actual module is here. It will
+generate a module header based on the parameters specified.  It will also
+begin calcuating the module CRC.
+
+</para>
+
+<para>
+
+The precise meaning of the various parameters is beyond the scope of this
+document since it is not a tutorial on OS9 module programming.
+
+</para>
+
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>EMOD</term>
+<listitem>
+<para>
+
+This marks the end of a module and causes LWASM to emit the calculated CRC
+for the module.
+
+</para>
+</varlistentry>
+
+</variablelist>
+</section>
+
+<section>
 <title>Miscelaneous Directives</title>
 
 <para>This section includes directives that do not fit into the other
@@ -801,12 +893,18 @@
 
 <varlistentry>
 <term>INCLUDE <parameter>filename</parameter></term>
-<listitem>
+<term>USE <parameter>filename</parameter></term>
+
+<listitem> <para> Include the contents of <parameter>filename</parameter> at
+this point in the assembly as though it were a part of the file currently
+being processed.  Note that if whitespace appears in the name of the file,
+you must enclose <parameter>filename</parameter> in quotes.
+</para>
+
 <para>
-Include the contents of <parameter>filename</parameter> at this point in
-the assembly as though it were a part of the file currently being processed.
-Note that whitespace cannot appear in the name of the file.
-</para>
+Note that the USE variation is provided only for compatibility with other
+assemblers. It is recommended to use the INCLUDE variation.</para>
+
 </listitem>
 </varlistentry>
 
@@ -1217,6 +1315,29 @@
 </para>
 </listitem>
 </varlistentry>
+
+<varlistentry>
+<term>dollarlocal</term>
+<listitem>
+
+<para>When set, a "$" in a symbol makes it local. When not set, "$" does not
+cause a symbol to be local.  It is set by default except when using the OS9
+target.</para>
+
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>dollarnotlocal</term>
+<listitem>
+
+<para> This is the same as the "dollarlocal" pragma except its sense is
+reversed.  That is, "dollarlocal" and "nodollarnotlocal" are equivalent and
+"nodollarlocal" and "dollarnotlocal" are equivalent.  </para>
+
+</listitem>
+</varlistentry>
+
 </variablelist>
 
 </section>