<article>
<title>ld65 Users Guide
<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
-<date>2014-04-20
<abstract>
The ld65 linker combines object files into an executable file. ld65 is highly
<item>module
<item>apple2
<item>apple2enh
+ <item>atari2600
<item>atari
<item>atarixl
<item>atmos
<item>sim6502
<item>sim65c02
<item>supervision
+ <item>telestrat
<item>vic20
</itemize>
<tag><tt>-Ln</tt></tag>
This option allows you to create a file that contains all global labels and
- may be loaded into the VICE emulator using the <tt/ll/ (load label) command. You
+ may be loaded into the VICE emulator using the <tt/ll/ (load label) command
+ or into the Oricutron emulator using the <tt/sl/ (symbols load) command. You
may use this to debug your code with VICE. Note: Older versions had some
bugs in the label code. If you have problems, please get the latest <url
- url="http://vice-emu.sourceforge.net/" name="VICE"> version.
+ url="http://vice-emu.sourceforge.net" name="VICE"> version.
<label id="option-S">
the linker will first write the <tt/CODE/ segment, then the <tt/RODATA/
segment, then the <tt/DATA/ segment - but it will not write the <tt/BSS/
segment. Why? Here enters the segment type: For each segment specified, you may also
-specify a segment attribute. There are four possible segment attributes:
+specify a segment attribute. There are five possible segment attributes:
<tscreen><verb>
- ro means readonly
- rw means read/write
- bss means that this is an uninitialized segment
- zp a zeropage segment
+ ro means readonly
+ rw means read/write
+ bss means that this is an uninitialized segment
+ zp a zeropage segment
+ overwrite a segment that overwrites (parts of) another one
+
</verb></tscreen>
So, because we specified that the segment with the name BSS is of type bss,
'%' is used as an escape char, the sequence "%%" has to be used if a single
percent sign is required.
+<sect1>OVERWRITE segments<p>
+
+There are situations when you may wish to overwrite some part (or parts) of a
+segment with another one. Perhaps you are modifying an OS ROM that has its
+public subroutines at fixed, well-known addresses, and you want to prevent them
+from shifting to other locations in memory if your changed code takes less
+space. Or you are updating a block of code available in binary-only form with
+fixes that are scattered in various places. Generally, whenever you want to
+minimize disturbance to an existing code brought on by your updates, OVERWRITE
+segments are worth considering.
+
+Here is an example:
+
+<tscreen><verb>
+MEMORY {
+ RAM: file = "", start = $6000, size = $2000, type=rw;
+ ROM: file = %O, start = $8000, size = $8000, type=ro;
+}
+</verb></tscreen>
+
+Nothing unusual so far, just two memory blocks - one RAM, one ROM. Now let's
+look at the segment configuration:
+
+<tscreen><verb>
+SEGMENTS {
+ RAM: load = RAM, type = bss;
+ ORIGINAL: load = ROM, type = ro;
+ FASTCOPY: load = ROM, start=$9000, type = overwrite;
+ JMPPATCH1: load = ROM, start=$f7e8, type = overwrite;
+ DEBUG: load = ROM, start=$8000, type = overwrite;
+ VERSION: load = ROM, start=$e5b7, type = overwrite;
+}
+</verb></tscreen>
+
+Segment named ORIGINAL contains the original code, disassembled or provided in
+a binary form (i.e. using <tt/.INCBIN/ directive; see the <tt/ca65/ assembler
+document). Subsequent four segments will be relocated to addresses specified
+by their "start" attributes ("offset" can also be used) and then will overwrite
+whatever was at these locations in the ORIGINAL segment. In the end, resulting
+binary output file will thus contain original data with the exception of four
+sequences starting at $9000, $f7e8, $8000 and $e5b7, which will sport code from
+their respective segments. How long these sequences will be depends on the
+lengths of corresponding segments - they can even overlap, so think what you're
+doing.
+
+Finally, note that OVERWRITE segments should be the final segments loaded to a
+particular memory area, and that they need at least one of "start" or "offset"
+attributes specified.
+
<sect1>LOAD and RUN addresses (ROMable code)<p>
Let us look now at a more complex example. Say, you've successfully tested
the compiler and the libraries that come with it. If you replace the builtin
config files, you will need the following information.
-The INIT segment is used for initialization code that may be reused once
+The ONCE segment is used for initialization code run only once before
execution reaches main() - provided that the program runs in RAM. You
-may for example add the INIT segment to the heap in really memory
+may for example add the ONCE segment to the heap in really memory
constrained systems.
<sect1>LOWCODE<p>
projects / cc65 / blobdiff