--- a/doc/lwlink.txt	Sat Jan 17 16:55:53 2009 +0000
+++ b/doc/lwlink.txt	Sat Jan 17 20:54:20 2009 +0000
@@ -0,0 +1,51 @@
+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" and/or "text", 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.
+