5 A Linker for ca65 Object modules
7 (C) Copyright 1998-2000 Ullrich von Bassewitz
21 4. Output configuration files
24 4.3 Builtin configurations
35 The ld65 linker combines several object modules created by the ca65
36 assembler, producing an executable file. The object modules may be read
37 from a library created by the ar65 archiver (this is somewhat faster and
38 more convenient). The linker was designed to be as flexible as possible.
39 It complements the features that are built into the ca65 macroassembler:
41 * Accept any number of segments to form an executable module.
43 * Resolve arbitrary expressions stored in the object files.
45 * In case of errors, use the meta information stored in the object files
46 to produce helpful error messages. In case of undefined symbols,
47 expression range errors, or symbol type mismatches, ld65 is able to
48 tell you the exact location in the original assembler source, where
49 the symbol was referenced.
51 * Flexible output. The output of ld65 is highly configurable by a
52 config file. More common platforms are supported by builtin
53 configurations that may be activated by naming the target system.
54 The output generation was designed with different output formats in
55 mind, so adding other formats shouldn't be a great problem.
62 The linker is called as follows:
64 ---------------------------------------------------------------------------
65 Usage: ld65 [options] module ...
68 -m name Create a map file
69 -o name Name the default output file
70 -t type Type of target system
73 -C name Use linker config file
74 -Ln name Create a VICE label file
75 -Lp Mark write protected segments as such (VICE)
76 -S addr Set the default start address
77 -V Print the linker version
80 --help Help (this text)
81 --version Print the linker version
82 ---------------------------------------------------------------------------
88 Print the short option summary shown above.
93 This option (which needs an argument that will used as a filename for
94 the generated map file) will cause the linker to generate a map file.
95 The map file does contain a detailed overview over the modules used, the
96 sizes for the different segments, and a table containing exported
102 The -o switch is used to give the name of the default output file.
103 Depending on your output configuration, this name may NOT be used as
104 name for the output file. However, for the builtin configurations, this
105 name is used for the output file name.
109 The argument for the -t switch is the name of the target system. Since
110 this switch will activate a builtin configuration, it may not be used
111 together with the -C option. The following target systems are currently
124 There are a few more targets defined but neither of them is actually
125 supported. See section 4.3 for more information about the builtin
132 Using the -v option, you may enable more output that may help you to
133 locate problems. If an undefined symbol is encountered, -v causes the
134 linker to print a detailed list of the references (that is, source file
135 and line) for this symbol.
140 Must be used in conjunction with -m (generate map file). Normally the
141 map file will not include empty segments and sections, or unreferenced
142 symbols. Using this option, you can force the linker to include all
143 this information into the map file.
148 This gives the name of an output config file to use. See section 4 for
149 more information about config files. -C may not be used together with
155 This option allows you to create a file that contains all global labels
156 and may be loaded into VICE emulator using the pb (playback) command.
157 You may use this to debug your code with VICE. Note: The label feature
158 is very new in VICE and has some bugs. If you have problems, please get
159 the latest VICE version.
169 Using -S you may define the default starting address. If and how this
170 address is used depends on the config file in use. For the builtin
171 configurations, only the "none" system honors an explicit start address,
172 all other builtin config provide their own.
178 This option print the version number of the linker. If you send any
179 suggestions or bugfixes, please include this number.
182 If one of the modules is not found in the current directory, and the
183 module name does not have a path component, the value of the environment
184 variable CC65_LIB is prepended to the name, and the linker tries to open
185 the module with this new name.
192 The linker does several things when combining object modules:
194 First, the command line is parsed from left to right. For each object file
195 encountered (object files are recognized by a magic word in the header, so
196 the linker does not care about the name), imported and exported
197 identifiers are read from the file and inserted in a table. If a library
198 name is given (libraries are also recognized by a magic word, there are no
199 special naming conventions), all modules in the library are checked if an
200 export from this module would satisfy an import from other modules. All
201 modules where this is the case are marked. If duplicate identifiers are
202 found, the linker issues a warning.
204 This procedure (parsing and reading from left to right) does mean, that a
205 library may only satisfy references for object modules (given directly or
206 from a library) named BEFORE that library. With the command line
208 ld65 crt0.o clib.lib test.o
210 the module test.o may not contain references to modules in the library
211 clib.lib. If this is the case, you have to change the order of the modules
214 ld65 crt0.o test.o clib.lib
216 Step two is, to read the configuration file, and assign start addresses
217 for the segments and define any linker symbols (see section 4).
219 After that, the linker is ready to produce an output file. Before doing
220 that, it checks it's data for consistency. That is, it checks for
221 unresolved externals (if the output format is not relocatable) and for
222 symbol type mismatches (for example a zero page symbol is imported by a
223 module as absolute symbol).
225 Step four is, to write the actual target files. In this step, the linker
226 will resolve any expressions contained in the segment data. Circular
227 references are also detected in this step (a symbol may have a circular
228 reference that goes unnoticed if the symbol is not used).
230 Step five is to output a map file with a detailed list of all modules,
231 segments and symbols encountered.
233 And, last step, if you give the -v switch twice, you get a dump of the
234 segment data. However, this may be quite unreadable if you're not a
239 4. Output configuration files
240 -----------------------------
242 Configuration files are used to describe the layout of the output file(s).
243 Two major topics are covered in a config file: The memory layout of the
244 target architecture, and the assignment of segments to memory areas. In
245 addition, several other attributes may be specified.
247 Case is ignored for keywords, that is, section or attribute names, but it
248 is NOT ignored for names and strings.
255 Memory areas are specified in a "MEMORY" section. Lets have a look at an
256 example (this one describes the usable memory layout of the C64):
259 RAM1: start = $0800, size = $9800;
260 ROM1: start = $A000, size = $2000;
261 RAM2: start = $C000, size = $1000;
262 ROM2: start = $E000, size = $2000;
265 As you can see, there are two ram areas and two rom areas. The names
266 (before the colon) are arbitrary names that must start with a letter, with
267 the remaining characters being letters or digits. The names of the memory
268 areas are used when assigning segments. As mentioned above, case is
269 significant for these names.
271 The syntax above is used in all sections of the config file. The name
272 ("ROM1" etc.) is said to be an identifier, the remaining tokens up to the
273 semicolon specify attributes for this identifier. You may use the equal
274 sign to assign values to attributes, and you may use a comma to separate
275 attributes, you may also leave both out. But you MUST use a semicolon to
276 mark the end of the attributes for one identifier. The section above may
277 also have looked like this:
279 # Start of memory section
296 There are of course more attributes for a memory section than just start
297 and size. Start and size are mandatory attributes, that means, each memory
298 area defined MUST have these attributes given (the linker will check
299 that). I will cover other attributes later. As you may have noticed, I've
300 used a comment in the example above. Comments start with a hash mark
301 (`#'), the remainder of the line is ignored if this character is found.
303 Let's assume you have written a program for your trusty old C64, and you
304 would like to run it. For testing purposes, it should run in the RAM area.
305 So we will start to assign segments to memory sections in the SEGMENTS
309 CODE: load = RAM1, type = ro;
310 RODATA: load = RAM1, type = ro;
311 DATA: load = RAM1, type = rw;
312 BSS: load = RAM1, type = bss, define = yes;
315 What we are doing here is telling the linker, that all segments go into
316 the RAM1 memory area in the order specified in the SEGMENTS section. So
317 the linker will first write the CODE segment, then the RODATA segment,
318 then the DATA segment - but it will not write the BSS segment. Why? Enter
319 the segment type: For each segment specified, you may also specify a
320 segment attribute. There are five possible segment attributes:
323 wprot same as ro but will be marked as write protected in
324 the VICE label file if -Lp is given
326 bss means that this is an uninitialized segment
327 empty will not go in any output file
329 So, because we specified that the segment with the name BSS is of type
330 bss, the linker knows that this is uninitialized data, and will not write
331 it to an output file. This is an important point: For the assembler, the
332 BSS segment has no special meaning. You specify, which segments have the
333 bss attribute when linking. This approach is much more flexible than
334 having one fixed bss segment, and is a result of the design decision to
335 supporting an arbitrary segment count.
337 If you specify "type = bss" for a segment, the linker will make sure that
338 this segment does only contain uninitialized data (that is, zeroes), and
339 issue a warning if this is not the case.
341 For a bss type segment to be useful, it must be cleared somehow by your
342 program (this happens usually in the startup code - for example the
343 startup code for cc65 generated programs takes care about that). But how
344 does your code know, where the segment starts, and how big it is? The
345 linker is able to give that information, but you must request it. This is,
346 what we're doing with the "define = yes" attribute in the BSS definitions.
347 For each segment, where this attribute is true, the linker will export
350 __NAME_LOAD__ This is set to the address where the segment is
352 __NAME_RUN__ This is set to the run address of the segment.
353 We will cover run addresses later.
354 __NAME_SIZE__ This is set to the segment size.
356 Replace "NAME" by the name of the segment, in the example above, this
357 would be "BSS". These symbols may be accessed by your code.
359 Now, as we've configured the linker to write the first three segments and
360 create symbols for the last one, there's only one question left: Where
361 does the linker put the data? It would be very convenient to have the data
362 in a file, wouldn't it?
364 We don't have any files specified above, and indeed, this is not needed in
365 a simple configuration like the one above. There is an additional
366 attribute "file" that may be specified for a memory area, that gives a
367 file name to write the area data into. If there is no file name given, the
368 linker will assign the default file name. This is "a.out" or the one given
369 with the -o option on the command line. Since the default behaviour is ok
370 for our purposes, I did not use the attribute in the example above. Let's
371 have a look at it now.
373 The "file" attribute (the keyword may also be written as "FILE" if you
374 like that better) takes a string enclosed in double quotes (`"') that
375 specifies the file, where the data is written. You may specifiy the same
376 file several times, in that case the data for all memory areas having this
377 file name is written into this file, in the order of the memory areas
378 defined in the MEMORY section. Let's specify some file names in the MEMORY
382 RAM1: start = $0800, size = $9800, file = %O;
383 ROM1: start = $A000, size = $2000, file = "rom1.bin";
384 RAM2: start = $C000, size = $1000, file = %O;
385 ROM2: start = $E000, size = $2000, file = "rom2.bin";
388 The %O used here is a way to specify the default behaviour explicitly: %O
389 is replaced by a string (including the quotes) that contains the default
390 output name, that is, "a.out" or the name specified with the -o option on
391 the command line. Into this file, the linker will first write any segments
392 that go into RAM1, and will append then the segments for RAM2, because the
393 memory areas are given in this order. So, for the RAM areas, nothing has
396 We've not used the ROM areas, but we will do that below, so we give the
397 file names here. Segments that go into ROM1 will be written to a file
398 named "rom1.bin", and segments that go into ROM2 will be written to a file
399 named "rom2.bin". The name given on the command line is ignored in both
402 Let us look now at a more complex example. Say, you've successfully tested
403 your new "Super Operating System" (SOS for short) for the C64, and you
404 will now go and replace the ROMs by your own code. When doing that, you
405 face a new problem: If the code runs in RAM, we need not to care about
406 read/write data. But now, if the code is in ROM, we must care about it.
407 Remember the default segments (you may of course specify your own):
410 RODATA read only data
412 BSS uninitialized data, read/write
414 Since the BSS is not initialized, we must not care about it now, but what
415 about DATA? DATA contains initialized data, that is, data that was
416 explicitly assigned a value. And your program will rely on these values on
417 startup. Since there's no other way to remember the contents of the data
418 segment, than storing it into one of the ROMs, we have to put it there.
419 But unfortunately, ROM is not writeable, so we have to copy it into RAM
420 before running the actual code.
422 The linker cannot help you copying the data from ROM into RAM (this must
423 be done by the startup code of your program), but it has some features
424 that will help you in this process.
426 First, you may not only specify a "load" attribute for a segment, but also
427 a "run" attribute. The "load" attribute is mandatory, and, if you don't
428 specify a "run" attribute, the linker assumes that load area and run area
429 are the same. We will use this feature for our data area:
432 CODE: load = ROM1, type = ro;
433 RODATA: load = ROM2, type = ro;
434 DATA: load = ROM2, run = RAM2, type = rw, define = yes;
435 BSS: load = RAM2, type = bss, define = yes;
438 Let's have a closer look at this SEGMENTS section. We specify that the
439 CODE segment goes into ROM1 (the one at $A000). The readonly data goes
440 into ROM2. Read/write data will be loaded into ROM2 but is run in RAM2.
441 That means that all references to labels in the DATA segment are relocated
442 to be in RAM2, but the segment is written to ROM2. All your startup code
443 has to do is, to copy the data from it's location in ROM2 to the final
446 So, how do you know, where the data is located? This is the second point,
447 where you get help from the linker. Remember the "define" attribute? Since
448 we have set this attribute to true, the linker will define three external
449 symbols for the data segment that may be accessed from your code:
451 __DATA_LOAD__ This is set to the address where the segment is
452 loaded, in this case, it is an address in ROM2.
453 __DATA_RUN__ This is set to the run address of the segment, in
454 this case, it is an address in RAM2.
455 __DATA_SIZE__ This is set to the segment size.
457 So, what your startup code must do, is to copy __DATA_SIZE__ bytes from
458 __DATA_LOAD__ to __DATA_RUN__ before any other routines are called. All
459 references to labels in the DATA segment are relocated to RAM2 by the
460 linker, so things will work properly.
462 There are some other attributes not covered above. Before starting the
463 reference section, I will discuss the remaining things here.
465 You may request symbols definitions also for memory areas. This may be
466 useful for things like a software stack, or an i/o area.
469 STACK: start = $C000, size = $1000, define = yes;
472 This will define three external symbols that may be used in your code:
474 __STACK_START__ This is set to the start of the memory
475 area, $C000 in this example.
477 __STACK_SIZE__ The size of the area, here $1000.
480 __STACK_LAST__ This is NOT the same as START+SIZE.
481 Instead, it it defined as the first
482 address that is not used by data. If we
483 don't define any segments for this area,
484 the value will be the same as START.
486 A memory section may also have a type. Valid types are
488 ro for readonly memory
489 and rw for read/write memory.
491 The linker will assure, that no segment marked as read/write or bss is put
492 into a memory area that is marked as readonly.
494 Unused memory in a memory area may be filled. Use the "fill = yes"
495 attribute to request this. The default value to fill unused space is zero.
496 If you don't like this, you may specify a byte value that is used to fill
497 these areas with the "fillval" attribute. This value is also used to fill
498 unfilled areas generated by the assemblers .ALIGN and .RES directives.
500 Segments may be aligned to some memory boundary. Specify "align = num" to
501 request this feature. Num must be a power of two. To align all segments on
505 CODE: load = ROM1, type = ro, align = $100;
506 RODATA: load = ROM2, type = ro, align = $100;
507 DATA: load = ROM2, run = RAM2, type = rw, define = yes,
509 BSS: load = RAM2, type = bss, define = yes, align = $100;
512 If an alignment is requested, the linker will add enough space to the
513 output file, so that the new segment starts at an address that is
514 divideable by the given number without a remainder. All addresses are
515 adjusted accordingly. To fill the unused space, bytes of zero are used,
516 or, if the memory area has a "fillval" attribute, that value. Alignment is
517 always needed, if you have the used the .ALIGN command in the assembler.
518 The alignment of a segment must be equal or greater than the alignment
519 used in the .ALIGN command. The linker will check that, and issue a
520 warning, if the alignment of a segment is lower than the alignment
521 requested in a .ALIGN command of one of the modules making up this
524 For a given segment you may also specify a fixed offset into a memory area or
525 a fixed start address. Use this if you want the code to run at a specific
526 address (a prominent case is the interrupt vector table which must go at
527 address $FFFA). Only one of ALIGN or OFFSET or START may be specified. If the
528 directive creates empty space, it will be filled with zero, of with the value
529 specified with the "fillval" attribute if one is given. The linker will warn
530 you if it is not possible to put the code at the specified offset (this may
531 happen if other segments in this area are too large). Here's an example:
534 VECTORS: load = ROM2, type = ro, start = $FFFA;
537 or (for the segment definitions from above)
540 VECTORS: load = ROM2, type = ro, offset = $1FFA;
543 File names may be empty, data from segments assigned to a memory area with
544 an empty file name is discarded. This is useful, if the a memory area has
545 segments assigned that are empty (for example because they are of type
546 bss). In that case, the linker will create an empty output file. This may
547 be suppressed by assigning an empty file name to that memory area.
549 The symbol %S may be used to access the default start address (that is,
550 $200 or the value given on the command line with the -S option).
559 4.3 Builtin configurations
560 --------------------------
562 Here is a list of the builin configurations for the different target
567 RAM: start = %S, size = $10000, file = %O;
570 CODE: load = RAM, type = rw;
571 RODATA: load = RAM, type = rw;
572 DATA: load = RAM, type = rw;
573 BSS: load = RAM, type = bss, define = yes;
578 HEADER: start = $0000, size = $6, file = %O;
579 RAM: start = $1F00, size = $6100, file = %O;
582 EXEHDR: load = HEADER, type = wprot;
583 CODE: load = RAM, type = wprot, define = yes;
584 RODATA: load = RAM, type = wprot;
585 DATA: load = RAM, type = rw;
586 BSS: load = RAM, type = bss, define = yes;
587 AUTOSTRT: load = RAM, type = wprot;
592 RAM: start = $7FF, size = $c801, file = %O;
595 CODE: load = RAM, type = ro;
596 RODATA: load = RAM, type = ro;
597 DATA: load = RAM, type = rw;
598 BSS: load = RAM, type = bss, define = yes;
603 RAM: start = $1bff, size = $a401, file = %O;
606 CODE: load = RAM, type = ro;
607 RODATA: load = RAM, type = ro;
608 DATA: load = RAM, type = rw;
609 BSS: load = RAM, type = bss, define = yes;
617 RAM: start = $0fff, size = $7001, file = %O;
620 CODE: load = RAM, type = ro;
621 RODATA: load = RAM, type = ro;
622 DATA: load = RAM, type = rw;
623 BSS: load = RAM, type = bss, define = yes;
628 RAM: start = $0001, size = $FFF0, file = %O;
631 CODE: load = RAM, type = ro;
632 RODATA: load = RAM, type = ro;
633 DATA: load = RAM, type = rw;
634 BSS: load = RAM, type = bss, define = yes;
639 RAM: start = $03FF, size = $7BFF, file = %O;
642 CODE: load = RAM, type = ro;
643 RODATA: load = RAM, type = ro;
644 DATA: load = RAM, type = rw;
645 BSS: load = RAM, type = bss, define = yes;
650 RAM: start = $800, size = $8E00, file = %O;
653 CODE: load = RAM, type = ro;
654 RODATA: load = RAM, type = ro;
655 DATA: load = RAM, type = rw;
656 BSS: load = RAM, type = bss, define = yes;
661 HEADER: start = $204, size = 508, file = %O;
662 RAM: start = $400, size = $7C00, file = %O;
665 HEADER: load = HEADER, type = ro;
666 CODE: load = RAM, type = ro;
667 RODATA: load = RAM, type = ro;
668 DATA: load = RAM, type = rw;
669 BSS: load = RAM, type = bss, define = yes;
672 The "start" attribute for the RAM memory area of the CBM systems is two
673 less than the actual start of the basic RAM to account for the two bytes
674 load address that is needed on disk and supplied by the startup code.
681 If you have problems using the linker, if you find any bugs, or if you're
682 doing something interesting with it, I would be glad to hear from you.
683 Feel free to contact me by email (uz@musoftware.de).
690 ld65 (and all cc65 binutils) are (C) Copyright 1998-2000 Ullrich von
691 Bassewitz. For usage of the binaries and/or sources the following
694 This software is provided 'as-is', without any expressed or implied
695 warranty. In no event will the authors be held liable for any damages
696 arising from the use of this software.
698 Permission is granted to anyone to use this software for any purpose,
699 including commercial applications, and to alter it and redistribute it
700 freely, subject to the following restrictions:
702 1. The origin of this software must not be misrepresented; you must not
703 claim that you wrote the original software. If you use this software
704 in a product, an acknowledgment in the product documentation would be
705 appreciated but is not required.
706 2. Altered source versions must be plainly marked as such, and must not
707 be misrepresented as being the original software.
708 3. This notice may not be removed or altered from any source