Add docs for the FEATURES section

git-svn-id: svn://svn.cc65.org/cc65/trunk@528 b7a2c559-68d2-44c3-8de9-860c34a00d81

doc/ld65.sgml

@@ -259,7 +259,7 @@ Case is ignored for keywords, that is, section or attribute names, but it is
 
 
 
-<sect1>Introduction<p>
+<sect1>Memory areas<p>
 
 Memory areas are specified in a <tt/MEMORY/ section. Lets have a look at an
 example (this one describes the usable memory layout of the C64):
@@ -313,6 +313,9 @@ will cover other attributes later. As you may have noticed, I've used a
 comment in the example above. Comments start with a hash mark (`#'), the
 remainder of the line is ignored if this character is found.
 
+
+<sect1>Segments<p>
+
 Let's assume you have written a program for your trusty old C64, and you would
 like to run it. For testing purposes, it should run in the <tt/RAM/ area. So
 we will start to assign segments to memory sections in the <tt/SEGMENTS/
@@ -380,6 +383,8 @@ create symbols for the last one, there's only one question left: Where does
 the linker put the data? It would be very convenient to have the data in a
 file, wouldn't it?
 
+<sect1>Output files<p>
+
 We don't have any files specified above, and indeed, this is not needed in a
 simple configuration like the one above. There is an additional attribute
 "file" that may be specified for a memory area, that gives a file name to
@@ -418,6 +423,9 @@ names here. Segments that go into <tt/ROM1/ will be written to a file named
 "rom1.bin", and segments that go into <tt/ROM2/ will be written to a file
 named "rom2.bin". The name given on the command line is ignored in both cases.
 
+
+<sect1>LOAD and RUN addresses (ROMable code)<p>
+
 Let us look now at a more complex example. Say, you've successfully tested
 your new "Super Operating System" (SOS for short) for the C64, and you
 will now go and replace the ROMs by your own code. When doing that, you
@@ -485,6 +493,9 @@ So, what your startup code must do, is to copy <tt/__DATA_SIZE__/ bytes from
 All references to labels in the <tt/DATA/ segment are relocated to <tt/RAM2/
 by the linker, so things will work properly.
 
+
+<sect1>Other MEMORY area attributes<p>
+
 There are some other attributes not covered above. Before starting the
 reference section, I will discuss the remaining things here.
 
@@ -526,6 +537,9 @@ 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.
 
+
+<sect1>Other SEGMENT attributes<p>
+
 Segments may be aligned to some memory boundary. Specify "<tt/align = num/" to
 request this feature. Num must be a power of two. To align all segments on a
 page boundary, use
@@ -587,7 +601,72 @@ name="-S"></tt> option).
 
 
 
-<sect1>Reference<p>
+<sect1>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.
+
+<tscreen><verb>
+	FEATURES {
+	    CONDES: segment = RODATA,
+	       	    type = constructor,
+	       	    label = __CONSTRUCTOR_TABLE__,
+	       	    count = __CONSTRUCTOR_COUNT__;
+	}
+</verb></tscreen>
+
+The <tt/CONDES/ feature has several attributes:
+
+<descrip>
+
+  <tag><tt>segment</tt></tag>
+
+  This attribute tells the linker into which segment the table should be
+  placed. If the segment does not exist, it is created.
+
+
+  <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.
+
+
+  <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.
+
+
+  <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.
+
+
+  <tag><tt>order</tt></tag>
+
+  Optional attribute that takes one of the keywords <tt/increasing/ or
+  <tt/decreasing/ as an argument. Specifies the sorting order of the entries
+  within the table. The default is <tt/increasing/, which means that the
+  entries are sorted with increasing priority (the first entry has the lowest
+  priority). You may change this behaviour by specifying <tt/decreasing/ as
+  the argument, the order of entries is reversed in this case.
+
+  Please note that the order of entries with equal priority is undefined.
+
+</descrip>
+
+Without specifying the <tt/CONDES/ feature, the linker will not create any
+tables, even if there are <tt/condes/ entries in the object files.
+
+For more information see the <tt/.CONDES/ command in the <htmlurl
+url="ca65.html" name="ca65 manual">.