From 00555c26fa8bcc0b15be6b4bf73856eb98b9b2d6 Mon Sep 17 00:00:00 2001
From: cuz <cuz@b7a2c559-68d2-44c3-8de9-860c34a00d81>
Date: Sun, 24 Jul 2005 13:59:02 +0000
Subject: [PATCH] Updated the linker docs

git-svn-id: svn://svn.cc65.org/cc65/trunk@3542 b7a2c559-68d2-44c3-8de9-860c34a00d81
---
 doc/ld65.sgml | 73 ++++++++++++++++++++++++++++++++-------------------
 1 file changed, 46 insertions(+), 27 deletions(-)

diff --git a/doc/ld65.sgml b/doc/ld65.sgml
index c1ac2dd1e..3cd238f3f 100644
--- a/doc/ld65.sgml
+++ b/doc/ld65.sgml
@@ -91,7 +91,7 @@ Long options:
 Here is a description of all the command line options:
 
 <descrip>
-  
+
   <label id="option--start-group">
   <tag><tt>-(, --start-group</tt></tag>
 
@@ -560,7 +560,11 @@ names here. Segments that go into <tt/ROM1/ will be written to a file named
 named "rom2.bin". The name given on the command line is ignored in both cases.
 
 Assigning an empty file name for a memory area will discard the data written
-to it.
+to it. This is useful, if the a memory area has segments assigned that are
+empty (for example because they are of type bss). In that case, the linker
+will create an empty output file. This may be suppressed by assigning an empty
+file name to that memory area.
+
 
 <sect1>LOAD and RUN addresses (ROMable code)<p>
 
@@ -675,6 +679,11 @@ you don't like this, you may specify a byte value that is used to fill these
 areas with the "<tt/fillval/" attribute. This value is also used to fill unfilled
 areas generated by the assemblers <tt/.ALIGN/ and <tt/.RES/ directives.
 
+The symbol <tt/%S/ may be used to access the default start address (that is,
+the one defined in the <ref id="FEATURES" name="FEATURES"> section, or the
+value given on the command line with the <tt><ref id="option-S" name="-S"></tt>
+option).
+
 
 <sect1>Other SEGMENT attributes<p>
 
@@ -742,18 +751,6 @@ segment attribute. Be careful when using this attribute, because a missing
 segment may be a sign of a problem, and if you're suppressing the warning,
 there is no one left to tell you about it.
 
-File names may be empty, data from segments assigned to a memory area with
-an empty file name is discarded. This is useful, if the a memory area has
-segments assigned that are empty (for example because they are of type
-bss). In that case, the linker will create an empty output file. This may
-be suppressed by assigning an empty file name to that memory area.
-
-The symbol <tt/%S/ may be used to access the default start address (that is,
-$200 or the value given on the command line with the <tt><ref id="option-S"
-name="-S"></tt> option).
-
-
-
 <sect1>The FILES section<p>
 
 The <tt/FILES/ section is used to support other formats than straight binary
@@ -803,12 +800,17 @@ several attributes that may be defined here.
 
 
 
-<sect1>Features<p>
+<sect1>Features<label id="FEATURES"><p>
 
 In addition to the <tt/MEMORY/ and <tt/SEGMENTS/ sections described above, the
 linker has features that may be enabled by an additional section labeled
-<tt/FEATURES/. Currently, one such feature is available: <tt/CONDES/ is used
-to tell the linker to emit module constructor/destructor tables.
+<tt/FEATURES/.
+
+
+<sect2>The CONDES feature<p>
+
+<tt/CONDES/ is used to tell the linker to emit module constructor/destructor
+tables.
 
 <tscreen><verb>
 	FEATURES {
@@ -831,24 +833,23 @@ The <tt/CONDES/ feature has several attributes:
 
   <tag><tt>type</tt></tag>
 
-  Describes the type of the routines to place in the table. Type may be
-  one of the predefined types <tt/constructor/ or <tt/destructor/, or a
-  numeric value between 0 and 6.
+  Describes the type of the routines to place in the table. Type may be one of
+  the predefined types <tt/constructor/, <tt/destructor/, <tt/interruptor/, or
+  a numeric value between 0 and 6.
 
 
   <tag><tt>label</tt></tag>
 
-  This specifies the label to use for the table. The label points to the
-  start of the table in memory and may be used from within user written
-  code.
+  This specifies the label to use for the table. The label points to the start
+  of the table in memory and may be used from within user written code.
 
 
   <tag><tt>count</tt></tag>
 
-  This is an optional attribute. If specified, an additional symbol is
-  defined by the linker using the given name. The value of this symbol
-  is the number of entries (<em/not/ bytes) in the table. While this
-  attribute is optional, it is often useful to define it.
+  This is an optional attribute. If specified, an additional symbol is defined
+  by the linker using the given name. The value of this symbol is the number
+  of entries (<em/not/ bytes) in the table. While this attribute is optional,
+  it is often useful to define it.
 
 
   <tag><tt>order</tt></tag>
@@ -873,6 +874,24 @@ For more information see the <tt/.CONDES/ command in the <htmlurl
 url="ca65.html" name="ca65 manual">.
 
 
+<sect2>The STARTADDRESS feature<p>
+
+<tt/STARTADDRESS/ is used to set the default value for the start address,
+which can be referenced by the <tt/%S/ symbol. The builtin default for the
+linker is &dollar;200.
+
+<tscreen><verb>
+	FEATURES {
+            # Default start address is $1000
+	    STARTADDRESS:       default = $1000;
+	}
+</verb></tscreen>
+
+Please note that order is important: The default start address must be defined
+<em/before/ the <tt/%S/ symbol is used in the config file. This does usually
+mean, that the <tt/FEATURES/ section has to go to the top of the config file.
+
+
 
 <sect1>Builtin configurations<p>
 
-- 
2.39.5