6502/cc65
1
0
Fork 0
mirror of https://github.com/cc65/cc65.git synced 2025-01-12 17:30:50 +00:00
Code Issues Projects Releases Wiki Activity

Add docs for the FEATURES section

Browse Source 
git-svn-id: svn://svn.cc65.org/cc65/trunk@528 b7a2c559-68d2-44c3-8de9-860c34a00d81
This commit is contained in:
cuz 2000-12-03 10:46:01 +00:00
parent a51c27f542
commit c26903e302
1 changed files with 96 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

113
doc/ld65.sgml
View File

@ -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
later.
segment. We will cover run addresses
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
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
@ -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">.