--- a/doc/manual.docbook.sgml	Fri Jan 30 01:51:41 2009 +0000
+++ b/doc/manual.docbook.sgml	Fri Jan 30 02:55:30 2009 +0000
@@ -174,6 +174,17 @@
 </varlistentry>
 
 <varlistentry>
+<term><option>--output=FILE</option></term>
+<term><option>-o FILE</option></term>
+<listitem>
+<para>
+This option specifies the name of the output file. If not specified, the
+default is <option>a.out</option>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
 <term><option>--pragma=pragma</option></term>
 <term><option>-p pragma</option></term>
 <listitem>
@@ -1040,7 +1051,263 @@
 <chapter>
 <title>LWLINK</title>
 <para>
+The LWTOOLS linker is called LWLINK. This chapter documents the various features
+of the linker.
 </para>
+
+<section>
+<title>Command Line Options</title>
+<para>
+The binary for LWLINK is called "lwlink". Note that the binary is in lower
+case. lwlink takes the following command line arguments.
+</para>
+<variablelist>
+<varlistentry>
+<term><option>--decb</option></term>
+<term><option>-b</option></term>
+<listitem>
+<para>
+Selects the DECB output format target. This is equivalent to <option>--format=decb</option>
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--output=FILE</option></term>
+<term><option>-o FILE</option></term>
+<listitem>
+<para>
+This option specifies the name of the output file. If not specified, the
+default is <option>a.out</option>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--format=TYPE</option></term>
+<term><option>-f TYPE</option></term>
+<listitem>
+<para>
+This option specifies the output format. Valid values are <option>decb</option>
+and <option>raw</option>
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--raw</option></term>
+<term><option>-r</option></term>
+<listitem>
+<para>
+This option specifies the raw output format.
+It is equivalent to <option>--format=raw</option>.
+and <option>raw</option>
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--script=FILE</option></term>
+<term><option>-s</option></term>
+<listitem>
+<para>
+This option allows specifying a linking script to override the linker's
+built in defaults.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--debug</option></term>
+<term><option>-d</option></term>
+<listitem>
+<para>
+This option increases the debugging level. It is only useful for LWTOOLS
+developers.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--help</option></term>
+<term><option>-?</option></term>
+<listitem>
+<para>
+This provides a listing of command line options and a brief description
+of each.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--usage</option></term>
+<listitem>
+<para>
+This will display a usage summary.
+of each.
+</para>
+</listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><option>--version</option></term>
+<term><option>-V</option></term>
+<listitem>
+<para>
+This will display the version of LWLINK.
+of each.
+</para>
+</listitem>
+</varlistentry>
+
+</section>
+
+<section>
+<title>Linker Operation</title>
+
+<para>
+LWLINK takes one or more files in the LWTOOLS object file format and links
+them into a single binary. While the precise method is slightly different,
+linking can be conceptualized as the following steps.
+</para>
+
+<orderedlist>
+<listitem>
+<para>
+First, the linker loads a linking script. If no script is specified, it
+loads a built-in default script based on the output format selected. This
+script tells the linker how to lay out the various sections in the final
+binary.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Next, the linker reads all the input files into memory. At this time, it
+flags any format errors in those files. It constructs a table of symbols
+for each object at this time.
+</para>
+</listitem>
+
+<listitem>
+<para>
+The linker then proceeds with organizing the sections loaded from each file
+according to the linking script. As it does so, it is able to assign addresses
+to each symbol defined in each object file. At this time, the linker may
+also collapse different instances of the same section name into a single
+section by appending the data from each subsequent instance of the section
+to the first instance of the section.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Next, the linker looks through every object file for every incomplete reference.
+It then attempts to fully resolve that reference. If it cannot do so, it
+throws an error. Once a reference is resolved, the value is placed into
+the binary code at the specified section. It should be noted that an
+incomplete reference can reference either a symbol internal to the object
+file or an external symbol which is in the export list of another object
+file.
+</para>
+</listitem>
+
+<listitem>
+<para>
+If all of the above steps are successful, the linker opens the output file
+and actually constructs the binary.
+</para>
+</listitem>
+</orderedlist>
+
+</section>
+
+<section
+<title>Linking Scripts</title>
+<para>
+A linker script is used to instruct the linker about how to assemble the
+various sections into a completed binary. It consists of a series of
+directives which are considered in the order they are encountered.
+</para>
+<para>
+The sections will appear in the resulting binary in the order they are
+specified in the script file. If a referenced section is not found, the linker will behave as though the
+section did exist but had a zero size, no relocations, and no exports.
+A section should only be referenced once. Any subsequent references will have
+an undefined effect.
+</para>
+
+<para>
+All numbers are in linking scripts are specified in hexadecimal. All directives
+are case sensitive although the hexadecimal numbers are not.
+</para>
+
+<para>A section name can be specified as a "*", then any section not
+already matched by the script will be matched. The "*" can be followed
+by a comma and a flag to narrow the section down slightly, also.
+If the flag is "!bss", then any section that is not flagged as a bss section
+will be matched. If the flag is "bss", then any section that is flagged as
+bss will be matched.
+</para>
+
+<para>The following directives are understood in a linker script.</para>
+<variablelist>
+<varlistentry>
+<term>section <parameter>name</parameter> load <parameter>addr</parameter></term>
+<listitem><para>
+
+This causes the section <parameter>name</parameter> to load at
+<parameter>addr</parameter>. For the raw target, only one "load at" entry is
+allowed for non-bss sections and it must be the first one. For raw targets,
+it affects the addresses the linker assigns to symbols but has no other
+affect on the output. bss sections may all have separate load addresses but
+since they will not appear in the binary anyway, this is okay.
+</para><para>
+For the decb target, each "load" entry will cause a new "block" to be
+output to the binary which will contain the load address. It is legal for
+sections to overlap in this manner - the linker assumes the loader will sort
+everything out.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>section <parameter>name</parameter></term>
+<listitem><para>
+
+This will cause the section <parameter>name</parameter> to load after the previously listed
+section.
+</para></listitem></varlistentry>
+<varlistentry>
+<term>exec <parameter>addr or sym</parameter></term>
+<listitem>
+<para>
+This will cause the execution address (entry point) to be the address
+specified (in hex) or the specified symbol name. The symbol name must
+match a symbol that is exported by one of the object files being linked.
+This has no effect for targets that do not encode the entry point into the
+resulting file. If not specified, the entry point is assumed to be address 0
+which is probably not what you want. The default link scripts for targets
+that support this directive automatically starts at the beginning of the
+first section (usually "init" or "code") that is emitted in the binary.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>pad <parameter>size</parameter></term>
+<listitem><para>
+This will cause the output file to be padded with NUL bytes to be exactly
+<parameter>size</parameter> bytes in length. This only makes sense for a raw target.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+
+
+</section>
+
 </chapter>
 
 <chapter id="objchap">
@@ -1051,6 +1318,192 @@
 hard to keep it hidden in an open source tool chain anyway. This chapter
 documents the object file format.
 </para>
+
+<para>
+An object file consists of a series of sections each of which contains a
+list of exported symbols, a list of incomplete references, and a list of
+"local" symbols which may be used in calculating incomplete references. Each
+section will obviously also contain the object code.
+</para>
+
+<para>
+Exported symbols must be completely resolved to an address within the
+section it is exported from. That is, an exported symbol must be a constant
+rather than defined in terms of other symbols.</para>
+
+<para>
+Each object file starts with a magic number and version number. The magic
+number is the string "LWOBJ16" for this 16 bit object file format. The only
+defined version number is currently 0. Thus, the first 8 bytes of the object
+file are <code>4C574F424A313600</code>
+</para>
+
+<para>
+Each section has the following items in order:
+</para>
+
+<itemizedlist>
+<listitem><para>section name</para></listitem>
+<listitem><para>flags</para></listitem>
+<listitem><para>list of local symbols (and addresses within the section)</para></listitem>
+<listitem><para>list of exported symbols (and addresses within the section)</para></listitem>
+<listitem><para>list of incomplete references along with the expressions to calculate them</para></listitem>
+<listitem><para>the actual object code (for non-BSS sections)</para></listitem>
+</itemizedlist>
+
+<para>
+The section starts with the name of the section with a NUL termination
+followed by a series of flag bytes terminated by NUL. There are only two
+flag bytes defined. A NUL (0) indicates no more flags and a value of 1
+indicates the section is a BSS section. For a BSS section, no actual
+code is included in the object file.
+</para>
+
+<para>
+Either a NULL section name or end of file indicate the presence of no more
+sections.
+</para>
+
+<para>
+Each entry in the exported and local symbols table consists of the symbol
+(NUL terminated) followed by two bytes which contain the value in big endian
+order. The end of a symbol table is indicated by a NULL symbol name.
+</para>
+
+<para>
+Each entry in the incomplete references table consists of an expression
+followed by a 16 bit offset where the reference goes. Expressions are
+defined as a series of terms up to an "end of expression" term. Each term
+consists of a single byte which identifies the type of term (see below)
+followed by any data required by the term. Then end of the list is flagged
+by a NULL expression (only an end of expression term).
+</para>
+
+<table frame="all"><title>Object File Term Types</title>
+<tgroup cols="2">
+<thead>
+<row>
+<entry>TERMTYPE</entry>
+<entry>Meaning</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry>00</entry>
+<entry>end of expression</entry>
+</row>
+
+<row>
+<entry>01</entry>
+<entry>integer (16 bit in big endian order follows)</entry>
+</row>
+<row>
+<entry>02</entry>
+<entry>	external symbol reference (NUL terminated symbol name follows)</entry>
+</row>
+
+<row>
+<entry>03</entry>
+<entry>local symbol reference (NUL terminated symbol name follows)</entry>
+</row>
+
+<row>
+<entry>04</entry>
+<entry>operator (1 byte operator number)</entry>
+</row>
+<row>
+<entry>05</entry>
+<entry>section base address reference</entry>
+</row>
+</tbody>
+</tgroup>
+</table>
+
+<para>
+External references are resolved using other object files while local
+references are resolved using the local symbol table(s) from this file. This
+allows local symbols that are not exported to have the same names as
+exported symbols or external references.
+</para>
+
+<table frame="all"><title>Object File Operator Numbers</title>
+<tgroup cols="2">
+<thead>
+<row>
+<entry>Number</entry>
+<entry>Operator</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry>01</entry>
+<entry>addition (+)</entry>
+</row>
+<row>
+<entry>02</entry>
+<entry>subtraction (-)</entry>
+</row>
+<row>
+<entry>03</entry>
+<entry>multiplication (*)</entry>
+</row>
+<row>
+<entry>04</entry>
+<entry>division (/)</entry>
+</row>
+<row>
+<entry>05</entry>
+<entry>modulus (%)</entry>
+</row>
+<row>
+<entry>06</entry>
+<entry>integer division (\) (same as division)</entry>
+</row>
+
+<row>
+<entry>07</entry>
+<entry>bitwise and</entry>
+</row>
+
+<row>
+<entry>08</entry>
+<entry>bitwise or</entry>
+</row>
+
+<row>
+<entry>09</entry>
+<entry>bitwise xor</entry>
+</row>
+
+<row>
+<entry>0A</entry>
+<entry>boolean and</entry>
+</row>
+
+<row>
+<entry>0B</entry>
+<entry>boolean or</entry>
+</row>
+
+<row>
+<entry>0C</entry>
+<entry>unary negation, 2's complement (-)</entry>
+</row>
+
+<row>
+<entry>0D</entry>
+<entry>unary 1's complement (^)</entry>
+</row>
+</tbody>
+</tgroup>
+</table>
+
+<para>
+An expression is represented in a postfix manner with both operands for
+binary operators preceding the operator and the single operand for unary
+operators preceding the operator.
+</para>
+
 </chapter>
 </book>