Add docs for the FEATURES section

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

doc/ld65.sgml

@@ -5,7 +5,7 @@
 <author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
 <date>02.12.2000
 
-<abstract> 
+<abstract>
 The ld65 linker combines object files into an executable file. ld65 is highly
 configurable and uses configuration files for high flexibility.
 </abstract>
@@ -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/
@@ -365,10 +368,10 @@ segment, where this attribute is true, the linker will export three symbols.
 
 <tscreen><verb>
      	__NAME_LOAD__  	This is set to the address where the
-			segment is loaded.
+		  	segment is loaded.
      	__NAME_RUN__   	This is set to the run address of the
-			segment. We will cover run addresses
+		  	segment. We will cover run addresses
-			later.
+		  	later.
      	__NAME_SIZE__  	This is set to the segment size.
 </verb></tscreen>
 
@@ -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
@@ -474,7 +482,7 @@ external symbols for the data segment that may be accessed from your code:
 <tscreen><verb>
        	__DATA_LOAD__	This is set to the address where the segment
 			is loaded, in this case, it is an address in
-			ROM2.
+		  	ROM2.
      	__DATA_RUN__	This is set to the run address of the segment,
 			in this case, it is an address in RAM2.
      	__DATA_SIZE__	This is set to the segment size.
@@ -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.
 
@@ -500,21 +511,21 @@ useful for things like a software stack, or an i/o area.
 This will define three external symbols that may be used in your code:
 
 <tscreen><verb>
-       	__STACK_START__		This is set to the start of the memory
+       	__STACK_START__	  	This is set to the start of the memory
-     				area, $C000 in this example.
+     	     		  	area, $C000 in this example.
-     	__STACK_SIZE__		The size of the area, here $1000.
+     	__STACK_SIZE__	  	The size of the area, here $1000.
         __STACK_LAST__		This is NOT the same as START+SIZE.
-     		    		Instead, it it defined as the first
+     	     	    		Instead, it it defined as the first
-     				address that is not used by data. If we
+     	     			address that is not used by data. If we
-     				don't define any segments for this area,
+     	     			don't define any segments for this area,
-     				the value will be the same as START.
+     	     			the value will be the same as START.
 </verb></tscreen>
 
 A memory section may also have a type. Valid types are
 
 <tscreen><verb>
-     	ro	for readonly memory
+     	ro   	for readonly memory
-	rw	for read/write memory.
+	rw   	for read/write memory.
 </verb></tscreen>
 
 The linker will assure, that no segment marked as read/write or bss is put
@@ -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
@@ -535,7 +549,7 @@ page boundary, use
      	    CODE:   load = ROM1, type = ro, align = $100;
      	    RODATA: load = ROM2, type = ro, align = $100;
      	    DATA:   load = ROM2, run = RAM2, type = rw, define = yes,
-     		    align = $100;
+     	     	    align = $100;
      	    BSS:    load = RAM2, type = bss, define = yes, align = $100;
      	}
 </verb></tscreen>
@@ -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">.