<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>
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):
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/
<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
- later.
+ segment. We will cover run addresses
+ later.
__NAME_SIZE__ This is set to the segment size.
</verb></tscreen>
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
"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
<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.
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.
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
- area, $C000 in this example.
- __STACK_SIZE__ The size of the area, here $1000.
+ __STACK_START__ This is set to the start of the memory
+ area, $C000 in this example.
+ __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
- address that is not used by data. If we
- don't define any segments for this area,
- the value will be the same as START.
+ Instead, it it defined as the first
+ address that is not used by data. If we
+ don't define any segments for this area,
+ 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
- rw for read/write memory.
+ ro for readonly memory
+ rw for read/write memory.
</verb></tscreen>
The linker will assure, that no segment marked as read/write or bss is put
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
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>
-<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">.
projects / cc65 / commitdiff