# HG changeset patch
# User lost@l-w.ca
# Date 1314426095 21600
# Node ID a26b045c4e18123aa7d2665d62233b015f2d4d81
# Parent  3b58d76ea0324f7c61b93af47b45d27ded9d295b
Added documentation about OS9 module support in lwlink

diff -r 3b58d76ea032 -r a26b045c4e18 docs/manual.docbook.sgml
--- a/docs/manual.docbook.sgml	Fri Aug 26 23:44:44 2011 -0600
+++ b/docs/manual.docbook.sgml	Sat Aug 27 00:21:35 2011 -0600
@@ -137,8 +137,7 @@
 
 <para>
 
-LWLINK does not, yet, have the ability to create OS9 modules from object
-files.
+As of version 4.5, LWLINK also supports creation of OS9 modules.
 
 </para>
 </section>
@@ -1976,6 +1975,87 @@
 
 </section>
 
+<section>
+<title>Format Specific Linking Notes</title>
+
+<para>Some formats require special information to be able to generate actual
+binaries.  If the specific format you are interested in is not listed in
+this section, then there is nothing special you need to know about to create
+a final binary.</para>
+
+<section>
+<title>OS9 Modules</title>
+
+<para>OS9 modules need to embed several items into the module header. These
+items are the type of module, the langauge of the module, the module
+attributes, the module revision number, the data size (bss), and the
+execution offset.  These are all either calculated or default to reasonable
+values.</para>
+
+<para>The data size is calcuated as the sum of all sections named "bss" or
+".bss" in all object files that are linked together.</para>
+
+<para>The execution offset is calculated from the address of the special
+symbol "__start" which must be an exported (external) symbol in one of the
+objects to be linked.</para>
+
+<para>The type defaults to "Prgrm" or "Program module". The language
+defaults to "Objct" or "6809 object code".  Attributes default to enabling
+the re-entrant flag.  And finally, the revision defaults to zero.</para>
+
+<para>The embedded module name is the output filename. If the output
+filename includes more than just the filename, this will probably not be
+what you want.</para>
+
+<para>The type, language, attributes, revision, and module name can all be
+overridden by providing a special section in exactly one of the object files
+to be linked.  This section is called "__os9" (note the two underscores). 
+To override the type, language, attributes, or revision values, define a
+non-exported symbol in this section called "type", "lang", "attr", or "rev"
+respectively.  Any other symbols defined are ignored.  To override the
+module name, include as the only actual code in the section a NUL terminated
+string (the FCN directive is useful for this).  If there is no code in the
+section or it beings with a NUL, the default name will be used.  Any of the
+preceeding that are not defined in the special section will retain their
+default values.</para>
+
+<para>The built-in link script for OS9 modules will place the following
+sections, in order, in the module: "code", ".text", "data", ".data".  It
+will merge all sections with the name "bss" or ".bss" into the "data"
+section.  All other section names are ignored.  What this means is that you
+must define your data variables in the a section called "bss" or ".bss" even
+though you will be refencing them all as offsets from U.  This does have the
+unpleasant side effect that all BSS references will end up being 16 bit
+offsets because the assembler cannot know what the offset will be once the
+linker is finished its work.  Thus, if the tightest possible code is
+required, having LWASM directly output the module is a better choice.</para>
+
+<para>While the built-in link script is probably sufficient for most
+purposes, you can provide your own script.  If you provide a custom link
+script, you must start your code and data sections at location 000D to
+accommodate the module header.  Otherwise, you will have an incorrect
+location for the execution offset.  You must use the ENTRY directive in the
+script to define the entry point for the module.</para>
+
+<para>It should also be obvious from the above that you cannot mix the bss
+(rmb) definitions with the module code when linking separately.  Those
+familiar with typical module creation will probably find this an unpleasant
+difference but it is unavoidable.</para>
+
+<para>It should also be noted that direct page references should also be
+avoided because you cannot know ahead of time whether the linker is going to
+end up putting a particular variable in the first 256 bytes of the module's
+data space.  If, however, you know for certain you will have less than 256
+bytes of defined data space across all of the object files that will be
+linked, you can instead use forced DP addressing for your data addresses
+instead of the ,u notation.  When linking with 3rd party libraries, this
+practice should be avoided.  Also, when creating libraries, always use the
+offset from U technique.</para>
+
+</section>
+
+</section>
+
 </chapter>
 
 <chapter>