# HG changeset patch
# User lost
# Date 1232225660 0
# Node ID 7a3d66e72a4ce94f3382821bbc24e9e5f108a21f
# Parent  0f488febdc2b3bc7c69578b7fa3b9af7bf28d14d
Added some basic documentation of the linker

diff -r 0f488febdc2b -r 7a3d66e72a4c doc/lwlink.txt
--- 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.
+
diff -r 0f488febdc2b -r 7a3d66e72a4c doc/scripts.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/scripts.txt	Sat Jan 17 20:54:20 2009 +0000
@@ -0,0 +1,46 @@
+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.
+
+A section may only be referenced once. Any subsequent references will have
+no effect.
+
+section <name> load at <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 at" 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> load after <name2>
+
+This will cause the section <name> to load after <name2>. This has the
+effect of essentially gluing <name> onto the end of <name2>. If multiple
+sections are specified to load after a particular section, they will load in
+the order specified.
+
+pad to <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
+
+