--- a/doc/lwlink.txt	Fri Jan 30 01:51:41 2009 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,51 +0,0 @@
-This is the companion linker to LWASM. It reads object files generated by
-LWASM and combines them into an actual binary.
-
-During linking, each file is read into memory. A list of externally
-referenced symbols is made along with where these symbols are referenced.
-Each external reference is checked against all previously loaded files (in
-order of loading) and if a match is found, a note of that fact is made and a
-link between the previously loaded file and the current reference.
-
-Once all files are loaded, the symbol table is checked for any symbols which
-are still unresolved. If any are found, the linking process complains and
-bails out.
-
-Once all the object files have been read, the linker follows a
-pre-determined script for the specified target or a script supplied by the
-user to lay out the binary. The instructions from the script are followed
-blindly as it is assumed the user knows what he is doing.
-
-For each defined section, the linker begins constructing the section data by
-resolving each instance of that section in the order it was encountered. All
-symbols defined by that section (local or exported) are assigned addresses.
-The exact offset into the final section data is recorded for any incomplete
-references in that section. All section base address references are resolved
-to actual addresses at this stage.
-
-Once all sections have been laid out and addresses assigned to all symbols,
-all incomplete references are resolved and the resulting value placed into
-the appropriate data stream. If any references cannot be resolved at this
-stage, the linker will complain and bail out.
-
-Once all sections, symbols, and incomplete references have been resolved,
-the binary will output as appropriate for the specified target.
-
-See the file "scripts.txt" for information about linker scripts and the
-restrictions based on the output target.
-
-The following output targets are supported:
-
-Raw: this is a raw binary with no header information, etc. Suitable for ROM
-images, etc. By default, the raw target starts the binary at address 0, puts
-any section named "init" first, then "code", then all other non-bss
-sections, then all bss sections. Note that any "bss" type section that
-exists anywhere but at the end of the binary (i.e. is between or before one
-or more non-bss sections) will be included as a series of NUL bytes.
-
-DECB: this creates a LOADM style binary according to the linker script. By
-default, this target places the sections in the same order as the raw target
-but implements a load address of $2000. bss sections will not be included in
-the actual output. If a bss section appears between two non-bss sections, a
-new output block will be created in the output file.
-

--- 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>
 

--- a/doc/objectfiles.txt	Fri Jan 30 01:51:41 2009 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,79 +0,0 @@
-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.
-
-Exported symbols must be completely resolved to an address within the
-section it is exported from.
-
-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:
-
-4C574F424A313600
-
-Each section has the following items in order:
-
-* section name
-* flags
-* list of local symbols (and addresses within the section)
-* list of exported symbols (and addresses within the section)
-* list of incomplete references along with the expressions to calculate them
-* the actual object code
-
-The section starts with the name of the section with a NUL termination
-followed by a series of flag bytes terminated by NUL. The following flag
-bytes are defined:
-
-Byte	Meaning
-00		no more flags
-01		section is BSS - no actual code is present
-
-Either a NULL section name or end of file indicate the presence of no more
-sections.
-
-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.
-
-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).
-
-TERMTYPE	Meaning
-00			end of expression
-01			integer (16 bit in big endian order follows)
-02			external symbol reference (NUL term symbol)
-03			local symbol reference (NUL term symbol)
-04			operator (1 byte operator number - see below)
-05			section base address reference
-
-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.
-
-The operator numbers are:
-
-NUM	OP
-01	+ (plus)
-02	- (minus)
-03	* (times)
-04	/ (divide)
-05	% (modulus)
-06	\ (integer division)
-07	bitwise and
-08	bitwise or
-09	bitwise xor
-0A	boolean and
-0B	boolean or
-0C	- (unary negation, 2's complement)
-0D	^ (unary 1's complement)
-
-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.

--- a/doc/pseudoops.txt	Fri Jan 30 01:51:41 2009 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,51 +0,0 @@
-The following pseudo operations are understood by LWASM.
-
-SECTION <name>
-
-This introduces a section called <name>. This is only valid if assembling to
-an object file. Only one section can be open at any given time. Sections
-may be ended with ENDSECTION. Only one section can be open at any given
-time. A subsequent SECTION directive will end the previous section. It is
-important to note that an end of file does not close the currently open
-section. There cannot be a symbol on a SECTION line.
-
-ENDSECTION
-
-Specifies the end of a section. This is optional. There cannot be a symbol
-on an ENDSECTION line.
-
-ORG <addr>
-
-Specifies the assembly address. For the raw target, this is advisory and
-only affects the addresses of symbols. For the object file target, this can
-only appear outside of all sections. For the DECB target, each ORG statement
-after which any output is generated will generate a segment in the output
-file. <addr> must be completely resolved during pass 1 of the assembly
-process and thus may not refer to forward references or external symbols, or
-other symbols that refer to such.
-
-<symbol> EQU <value>
-
-Makes <symbol> equivalent to <value>. <value> may be an external reference
-in which case any references to <symbol> will also be external references.
-
-EXPORT <symbol>[ as <name>]
-
-Marks previously defined <symbol> for export. If <name> is specified, it
-will be exported as <name>. <symbol> must not be an external reference and
-must be defined before EXPORT.
-
-EXTERN <symbol>[ as <name>]
-IMPORT <symbol>[ as <name>]
-
-Marks <symbol> as an external reference. If <name> is specified, <name> is
-the local name the symbol is references as in this assembly file while
-<symbol> is the actual symbol to be referenced externally.
-
-END [<addr>]
-
-Marks the end of the assembly process. Immediately terminates assembly
-without processing any other lines in this file or any others. It is
-optional. <addr> is only allowed for the DECB target in which case it
-specifies the execution address. If it is not specified, the address
-defaults to 0.

--- a/doc/scripts.txt	Fri Jan 30 01:51:41 2009 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,63 +0,0 @@
-LWLINK linker scripts
-
-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. Any
-section not referenced by a directive is assumed to be loaded after the
-final section explicitly referenced.
-
-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 may only be referenced once. Any subsequent references will have
-no effect.
-
-All numbers are hexadecimal.
-
-section <name> load <addr>
-
-This causes the section <name> to load at <addr>. For 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.
-
-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.
-
-section <name>
-
-This will cause the section <name> to load after the previously listed
-section.
-
-exec <addr or sym>
-
-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.
-
-pad <size>
-
-This will cause the output file to be padded with NUL bytes to be exactly
-<size> bytes in length. This only makes sense for a raw target.
-
-
-If <name> is "*", then any section not already matched by the script will be
-matched. For format *,<flags> can be used to select sections which have
-particular flags set (or not set). For instance:
-
-*,!bss		This would match all sections that do not have the bss flag set
-*,bss		this would match all sections that do have the bss flag set
-
-