5 A Linker for ca65 Object modules
7 (C) Copyright 1998-1999 Ullrich von Bassewitz
21 4. Output configuration files
24 4.3 Builtin configurations
35 ld65 is a replacement for the link65 linker that was part of the cc65 C
36 compiler suite developed by John R. Dunning. link65 had some problems and
37 the copyright does not permit some things which I wanted to be possible,
38 so I decided to write a completely new assembler/linker/archiver suite
39 for the cc65 compiler. ld65 is part of this suite.
41 The ld65 linker combines several object modules, producing an executable
42 file. The object modules may be read from a library created by the ar65
43 archiver (this is somewhat faster and more convenient). The linker was
44 designed to be as flexible as possible. It complements the features that
45 are built into the ca65 macroassembler:
47 * Accept any number of segments to form an executable module.
49 * Resolve arbitrary expressions stored in the object files.
51 * In case of errors, use the meta information stored in the object
52 files to produce helpful error messages. In case of undefined
53 symbols, expression range errors, or symbol type mismatches, ld65 is
54 able to tell you the exact location in the source, where the symbol
57 * Flexible output. The output of ld65 is highly configurable by a
58 config file. More common platforms are supported by builtin
59 configurations that may be activated by naming the target system.
60 The output generation was designed with different output formats in
61 mind, so adding other formats shouldn't be a great problem.
68 The linker is called as follows:
70 Usage: ld65 [options] module ...
72 -m name Create a map file
73 -o name Name the default output file
74 -t type Type of target system
77 -C name Use linker config file
78 -Ln name Create a VICE label file
79 -Lp Mark write protected segments as such (VICE)
80 -S addr Set the default start address
81 -V Print linker version
83 The -m switch (which needs an argument that will used as a filename for
84 the generated map file) will cause the linker to generate a map file. The
85 map file does contain a detailed overview over the modules used, the
86 sizes for the different segments, and a table containing exported
89 The -o switch is used to give the name of the default output file.
90 Depending on your output configuration, this name may NOT be used as name
91 for the output file. However, for the builtin configurations, this name
92 is used for the output file name.
94 The argument for the -t switch is the name of the target system. Since
95 this switch will activate a builtin configuration, it may not be used
96 together with the -C option.
97 The following target systems are defined (* = currently unsupported):
110 See section 4.3 for more information about the builtin configurations.
112 Using the -v option, you may enable more output that may help you to
113 locate problems. If an undefined symbol is encountered, -v causes the
114 linker to print a detailed list of the references (that is, source file
115 and line) for this symbol.
117 -C gives the name of an output config file to use. See section 4 for more
118 information about config files. -C may not be used together with -t.
120 -L allows you to create a file that contains all global labels and may be
121 loaded into VICE emulator using the pb (playback) command. You may use
122 this to debug your code with VICE. Note: The label feature is very new in
123 VICE and has some bugs. If you have problems, please get the latest VICE
126 Using -S you may define the default starting address. If and how this
127 address is used depends on the config file in use. For the builtin
128 configurations, only the "none" system honors an explicit start address,
129 all other builtin config provide their own.
131 -V prints the version number of the linker. If you send any suggestions or
132 bugfixes, please include this number.
135 If one of the modules is not found in the current directory, and the
136 module name does not have a path component, the value of the environment
137 variable CC65_LIB is prepended to the name, and the linker tries to open
138 the module with this new name.
145 The linker does several things when combining object modules:
147 First, the command line is parsed from left to right. For each object file
148 encountered (object files are recognized by a magic word in the header, so
149 the linker does not care about the name), imported and exported
150 identifiers are read from the file and inserted in a table. If a library
151 name is given (libraries are also recognized by a magic word, there are no
152 special naming conventions), all modules in the library are checked if an
153 export from this module would satisfy an import from other modules. All
154 modules where this is the case are marked. If duplicate identifiers are
155 found, the linker issues a warning.
157 This procedure (parsing and reading from left to right) does mean, that a
158 library may only satisfy references for object modules (given directly or
159 from a library) named BEFORE that library. With the command line
161 ld65 crt0.o clib.lib test.o
163 the module test.o may not contain references to modules in the library
164 clib.lib. If this is the case, you have to change the order of the modules
167 ld65 crt0.o test.o clib.lib
169 Step two is, to read the configuration file, and assign start addresses
170 for the segments and define any linker symbols (see section 4).
172 After that, the linker is ready to produce an output file. Before doing
173 that, it checks it's data for consistency. That is, it checks for
174 unresolved externals (if the output format is not relocatable) and for
175 symbol type mismatches (for example a zero page symbol is imported by a
176 module as absolute symbol).
178 Step four is, to write the actual target files. In this step, the linker
179 will resolve any expressions contained in the segment data. Circular
180 references are also detected in this step (a symbol may have a circular
181 reference that goes unnoticed if the symbol is not used).
183 Step five is to output a map file with a detailed list of all modules,
184 segments and symbols encountered.
186 And, last step, if you give the -v switch twice, you get a dump of the
187 segment data. However, this may be quite unreadable if you're not a
192 4. Output configuration files
193 -----------------------------
195 Configuration files are used to describe the layout of the output file(s).
196 Two major topics are covered in a config file: The memory layout of the
197 target architecture, and the assignment of segments to memory areas. In
198 addition, several other attributes may be specified.
200 Case is ignored for keywords, that is, section or attribute names, but it
201 is NOT ignored for names and strings.
208 Memory areas are specified in a "MEMORY" section. Lets have a look at an
209 example (this one describes the usable memory layout of the C64):
212 RAM1: start = $0800, size = $9800;
213 ROM1: start = $A000, size = $2000;
214 RAM2: start = $C000, size = $1000;
215 ROM2: start = $E000, size = $2000;
218 As you can see, there are two ram areas and two rom areas. The names
219 (before the colon) are arbitrary names that must start with a letter, with
220 the remaining characters being letters or digits. The names of the memory
221 areas are used when assigning segments. As mentioned above, case is
222 significant for these names.
224 The syntax above is used in all sections of the config file. The name
225 ("ROM1" etc.) is said to be an identifier, the remaining tokens up to the
226 semicolon specify attributes for this identifier. You may use the equal
227 sign to assign values to attributes, and you may use a comma to separate
228 attributes, you may also leave both out. But you MUST use a semicolon to
229 mark the end of the attributes for one identifier. The section above may
230 also have looked like this:
232 # Start of memory section
249 There are of course more attributes for a memory section than just start
250 and size. Start and size are mandatory attributes, that means, each memory
251 area defined MUST have these attributes given (the linker will check
252 that). I will cover other attributes later. As you may have noticed, I've
253 used a comment in the example above. Comments start with a hash mark
254 (`#'), the remainder of the line is ignored if this character is found.
256 Let's assume you have written a program for your trusty old C64, and you
257 would like to run it. For testing purposes, it should run in the RAM area.
258 So we will start to assign segments to memory sections in the SEGMENTS
262 CODE: load = RAM1, type = ro;
263 RODATA: load = RAM1, type = ro;
264 DATA: load = RAM1, type = rw;
265 BSS: load = RAM1, type = bss, define = yes;
268 What we are doing here is telling the linker, that all segments go into
269 the RAM1 memory area in the order specified in the SEGMENTS section. So
270 the linker will first write the CODE segment, then the RODATA segment,
271 then the DATA segment - but it will not write the BSS segment. Why? Enter
272 the segment type: For each segment specified, you may also specify a
273 segment attribute. There are five possible segment attributes:
276 wprot same as ro but will be marked as write protected in
277 the VICE label file if -Lp is given
279 bss means that this is an uninitialized segment
280 empty will not go in any output file
282 So, because we specified that the segment with the name BSS is of type
283 bss, the linker knows that this is uninitialized data, and will not write
284 it to an output file. This is an important point: For the assembler, the
285 BSS segment has no special meaning. You specify, which segments have the
286 bss attribute when linking. This approach is much more flexible than
287 having one fixed bss segment, and is a result of the design decision to
288 supporting an arbitrary segment count.
290 If you specify "type = bss" for a segment, the linker will make sure that
291 this segment does only contain uninitialized data (that is, zeroes), and
292 issue a warning if this is not the case.
294 For a bss type segment to be useful, it must be cleared somehow by your
295 program (this happens usually in the startup code - for example the
296 startup code for cc65 generated programs takes care about that). But how
297 does your code know, where the segment starts, and how big it is? The
298 linker is able to give that information, but you must request it. This is,
299 what we're doing with the "define = yes" attribute in the BSS definitions.
300 For each segment, where this attribute is true, the linker will export
303 __NAME_LOAD__ This is set to the address where the segment is
305 __NAME_RUN__ This is set to the run address of the segment.
306 We will cover run addresses later.
307 __NAME_SIZE__ This is set to the segment size.
309 Replace "NAME" by the name of the segment, in the example above, this
310 would be "BSS". These symbols may be accessed by your code.
312 Now, as we've configured the linker to write the first three segments and
313 create symbols for the last one, there's only one question left: Where
314 does the linker put the data? It would be very convenient to have the data
315 in a file, wouldn't it?
317 We don't have any files specified above, and indeed, this is not needed in
318 a simple configuration like the one above. There is an additional
319 attribute "file" that may be specified for a memory area, that gives a
320 file name to write the area data into. If there is no file name given, the
321 linker will assign the default file name. This is "a.out" or the one given
322 with the -o option on the command line. Since the default behaviour is ok
323 for our purposes, I did not use the attribute in the example above. Let's
324 have a look at it now.
326 The "file" attribute (the keyword may also be written as "FILE" if you
327 like that better) takes a string enclosed in double quotes (`"') that
328 specifies the file, where the data is written. You may specifiy the same
329 file several times, in that case the data for all memory areas having this
330 file name is written into this file, in the order of the memory areas
331 defined in the MEMORY section. Let's specify some file names in the MEMORY
335 RAM1: start = $0800, size = $9800, file = %O;
336 ROM1: start = $A000, size = $2000, file = "rom1.bin";
337 RAM2: start = $C000, size = $1000, file = %O;
338 ROM2: start = $E000, size = $2000, file = "rom2.bin";
341 The %O used here is a way to specify the default behaviour explicitly: %O
342 is replaced by a string (including the quotes) that contains the default
343 output name, that is, "a.out" or the name specified with the -o option on
344 the command line. Into this file, the linker will first write any segments
345 that go into RAM1, and will append then the segments for RAM2, because the
346 memory areas are given in this order. So, for the RAM areas, nothing has
349 We've not used the ROM areas, but we will do that below, so we give the
350 file names here. Segments that go into ROM1 will be written to a file
351 named "rom1.bin", and segments that go into ROM2 will be written to a file
352 named "rom2.bin". The name given on the command line is ignored in both
355 Let us look now at a more complex example. Say, you've successfully tested
356 your new "Super Operating System" (SOS for short) for the C64, and you
357 will now go and replace the ROMs by your own code. When doing that, you
358 face a new problem: If the code runs in RAM, we need not to care about
359 read/write data. But now, if the code is in ROM, we must care about it.
360 Remember the default segments (you may of course specify your own):
363 RODATA read only data
365 BSS uninitialized data, read/write
367 Since the BSS is not initialized, we must not care about it now, but what
368 about DATA? DATA contains initialized data, that is, data that was
369 explicitly assigned a value. And your program will rely on these values on
370 startup. Since there's no other way to remember the contents of the data
371 segment, than storing it into one of the ROMs, we have to put it there.
372 But unfortunately, ROM is not writeable, so we have to copy it into RAM
373 before running the actual code.
375 The linker cannot help you copying the data from ROM into RAM (this must
376 be done by the startup code of your program), but it has some features
377 that will help you in this process.
379 First, you may not only specify a "load" attribute for a segment, but also
380 a "run" attribute. The "load" attribute is mandatory, and, if you don't
381 specify a "run" attribute, the linker assumes that load area and run area
382 are the same. We will use this feature for our data area:
385 CODE: load = ROM1, type = ro;
386 RODATA: load = ROM2, type = ro;
387 DATA: load = ROM2, run = RAM2, type = rw, define = yes;
388 BSS: load = RAM2, type = bss, define = yes;
391 Let's have a closer look at this SEGMENTS section. We specify that the
392 CODE segment goes into ROM1 (the one at $A000). The readonly data goes
393 into ROM2. Read/write data will be loaded into ROM2 but is run in RAM2.
394 That means that all references to labels in the DATA segment are relocated
395 to be in RAM2, but the segment is written to ROM2. All your startup code
396 has to do is, to copy the data from it's location in ROM2 to the final
399 So, how do you know, where the data is located? This is the second point,
400 where you get help from the linker. Remember the "define" attribute? Since
401 we have set this attribute to true, the linker will define three external
402 symbols for the data segment that may be accessed from your code:
404 __DATA_LOAD__ This is set to the address where the segment is
405 loaded, in this case, it is an address in ROM2.
406 __DATA_RUN__ This is set to the run address of the segment, in
407 this case, it is an address in RAM2.
408 __DATA_SIZE__ This is set to the segment size.
410 So, what your startup code must do, is to copy __DATA_SIZE__ bytes from
411 __DATA_LOAD__ to __DATA_RUN__ before any other routines are called. All
412 references to labels in the DATA segment are relocated to RAM2 by the
413 linker, so things will work properly.
415 There are some other attributes not covered above. Before starting the
416 reference section, I will discuss the remaining things here.
418 You may request symbols definitions also for memory areas. This may be
419 useful for things like a software stack, or an i/o area.
422 STACK: start = $C000, size = $1000, define = yes;
425 This will define three external symbols that may be used in your code:
427 __STACK_START__ This is set to the start of the memory
428 area, $C000 in this example.
430 __STACK_SIZE__ The size of the area, here $1000.
433 __STACK_LAST__ This is NOT the same as START+SIZE.
434 Instead, it it defined as the first
435 address that is not used by data. If we
436 don't define any segments for this area,
437 the value will be the same as START.
439 A memory section may also have a type. Valid types are
441 ro for readonly memory
442 and rw for read/write memory.
444 The linker will assure, that no segment marked as read/write or bss is put
445 into a memory area that is marked as readonly.
447 Unused memory in a memory area may be filled. Use the "fill = yes"
448 attribute to request this. The default value to fill unused space is zero.
449 If you don't like this, you may specify a byte value that is used to fill
450 these areas with the "fillval" attribute. This value is also used to fill
451 unfilled areas generated by the assemblers .ALIGN and .RES directives.
453 Segments may be aligned to some memory boundary. Specify "align = num" to
454 request this feature. Num must be a power of two. To align all segments on
458 CODE: load = ROM1, type = ro, align = $100;
459 RODATA: load = ROM2, type = ro, align = $100;
460 DATA: load = ROM2, run = RAM2, type = rw, define = yes,
462 BSS: load = RAM2, type = bss, define = yes, align = $100;
465 If an alignment is requested, the linker will add enough space to the
466 output file, so that the new segment starts at an address that is
467 divideable by the given number without a remainder. All addresses are
468 adjusted accordingly. To fill the unused space, bytes of zero are used,
469 or, if the memory area has a "fillval" attribute, that value. Alignment is
470 always needed, if you have the used the .ALIGN command in the assembler.
471 The alignment of a segment must be equal or greater than the alignment
472 used in the .ALIGN command. The linker will check that, and issue a
473 warning, if the alignment of a segment is lower than the alignment
474 requested in a .ALIGN command of one of the modules making up this
477 For a given segment you may also specify a fixed offset into a memory area or
478 a fixed start address. Use this if you want the code to run at a specific
479 address (a prominent case is the interrupt vector table which must go at
480 address $FFFA). Only one of ALIGN or OFFSET or START may be specified. If the
481 directive creates empty space, it will be filled with zero, of with the value
482 specified with the "fillval" attribute if one is given. The linker will warn
483 you if it is not possible to put the code at the specified offset (this may
484 happen if other segments in this area are too large). Here's an example:
487 VECTORS: load = ROM2, type = ro, start = $FFFA;
490 or (for the segment definitions from above)
493 VECTORS: load = ROM2, type = ro, offset = $1FFA;
496 File names may be empty, data from segments assigned to a memory area with
497 an empty file name is discarded. This is useful, if the a memory area has
498 segments assigned that are empty (for example because they are of type
499 bss). In that case, the linker will create an empty output file. This may
500 be suppressed by assigning an empty file name to that memory area.
502 The symbol %S may be used to access the default start address (that is,
503 $200 or the value given on the command line with the -S option).
512 4.3 Builtin configurations
513 --------------------------
515 Here is a list of the builin configurations for the different target
520 RAM: start = %S, size = $10000, file = %O;
523 CODE: load = RAM, type = rw;
524 RODATA: load = RAM, type = rw;
525 DATA: load = RAM, type = rw;
526 BSS: load = RAM, type = bss, define = yes;
534 RAM: start = $7FF, size = $c801, file = %O;
537 CODE: load = RAM, type = ro;
538 RODATA: load = RAM, type = ro;
539 DATA: load = RAM, type = rw;
540 BSS: load = RAM, type = bss, define = yes;
545 RAM: start = $1bff, size = $a401, file = %O;
548 CODE: load = RAM, type = ro;
549 RODATA: load = RAM, type = ro;
550 DATA: load = RAM, type = rw;
551 BSS: load = RAM, type = bss, define = yes;
559 RAM: start = $0fff, size = $7001, file = %O;
562 CODE: load = RAM, type = ro;
563 RODATA: load = RAM, type = ro;
564 DATA: load = RAM, type = rw;
565 BSS: load = RAM, type = bss, define = yes;
570 RAM: start = $0001, size = $FFF0, file = %O;
573 CODE: load = RAM, type = ro;
574 RODATA: load = RAM, type = ro;
575 DATA: load = RAM, type = rw;
576 BSS: load = RAM, type = bss, define = yes;
581 RAM: start = $03FF, size = $7BFF, file = %O;
584 CODE: load = RAM, type = ro;
585 RODATA: load = RAM, type = ro;
586 DATA: load = RAM, type = rw;
587 BSS: load = RAM, type = bss, define = yes;
592 RAM: start = $0200, size = $0600, file = "";
593 ROM: start = $8000, size = $8000, file = %O;
596 CODE: load = ROM, type = ro;
597 RODATA: load = ROM, type = ro;
598 DATA: load = ROM, run = RAM, type = rw, define = yes;
599 BSS: load = RAM, type = bss, define = yes;
600 VECTORS: load = ROM, type = ro, start = $FFFA;
605 RAM: start = $800, size = $8E00, file = %O;
608 CODE: load = RAM, type = ro;
609 RODATA: load = RAM, type = ro;
610 DATA: load = RAM, type = rw;
611 BSS: load = RAM, type = bss, define = yes;
614 The "start" attribute for the RAM memory area of the CBM systems is two
615 less than the actual start of the basic RAM to account for the two bytes
616 load address that is needed on disk and supplied by the startup code.
623 If you have problems using the linker, if you find any bugs, or if you're
624 doing something interesting with it, I would be glad to hear from you.
625 Feel free to contact me by email (uz@musoftware.de).
632 ld65 (and all cc65 binutils) are (C) Copyright 1998 Ullrich von Bassewitz.
633 For usage of the binaries and/or sources the following conditions do
636 This software is provided 'as-is', without any expressed or implied
637 warranty. In no event will the authors be held liable for any damages
638 arising from the use of this software.
640 Permission is granted to anyone to use this software for any purpose,
641 including commercial applications, and to alter it and redistribute it
642 freely, subject to the following restrictions:
644 1. The origin of this software must not be misrepresented; you must not
645 claim that you wrote the original software. If you use this software
646 in a product, an acknowledgment in the product documentation would be
647 appreciated but is not required.
648 2. Altered source versions must be plainly marked as such, and must not
649 be misrepresented as being the original software.
650 3. This notice may not be removed or altered from any source