]> git.sur5r.net Git - cc65/blob - doc/ld65.sgml
Document the symbols section and the new -D and --define options
[cc65] / doc / ld65.sgml
1 <!doctype linuxdoc system>
2
3 <article>
4 <title>ld65 Users Guide
5 <author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
6 <date>02.12.2000, 02.10.2001
7
8 <abstract>
9 The ld65 linker combines object files into an executable file. ld65 is highly
10 configurable and uses configuration files for high flexibility.
11 </abstract>
12
13 <!-- Table of contents -->
14 <toc>
15
16 <!-- Begin the document -->
17
18 <sect>Overview<p>
19
20 The ld65 linker combines several object modules created by the ca65
21 assembler, producing an executable file. The object modules may be read
22 from a library created by the ar65 archiver (this is somewhat faster and
23 more convenient). The linker was designed to be as flexible as possible.
24 It complements the features that are built into the ca65 macroassembler:
25
26 <itemize>
27
28 <item>  Accept any number of segments to form an executable module.
29
30 <item>  Resolve arbitrary expressions stored in the object files.
31
32 <item>  In case of errors, use the meta information stored in the object files
33         to produce helpful error messages. In case of undefined symbols,
34         expression range errors, or symbol type mismatches, ld65 is able to
35         tell you the exact location in the original assembler source, where
36         the symbol was referenced.
37
38 <item>  Flexible output. The output of ld65 is highly configurable by a config
39         file. More common platforms are supported by builtin configurations
40         that may be activated by naming the target system. The output
41         generation was designed with different output formats in mind, so
42         adding other formats shouldn't be a great problem.
43
44 </itemize>
45
46
47 <sect>Usage<p>
48
49
50 <sect1>Command line option overview<p>
51
52 The linker is called as follows:
53
54 <tscreen><verb>
55 ---------------------------------------------------------------------------
56 Usage: ld65 [options] module ...
57 Short options:
58   -(                    Start a library group
59   -)                    End a library group
60   -C name               Use linker config file
61   -D sym=val            Define a symbol
62   -L path               Specify a library search path
63   -Ln name              Create a VICE label file
64   -S addr               Set the default start address
65   -V                    Print the linker version
66   -h                    Help (this text)
67   -m name               Create a map file
68   -o name               Name the default output file
69   -t sys                Set the target system
70   -v                    Verbose mode
71   -vm                   Verbose map file
72
73 Long options:
74   --cfg-path path       Specify a config file search path
75   --config name         Use linker config file
76   --dbgfile name        Generate debug information
77   --define sym=val      Define a symbol
78   --dump-config name    Dump a builtin configuration
79   --end-group           End a library group
80   --help                Help (this text)
81   --lib file            Link this library
82   --lib-path path       Specify a library search path
83   --mapfile name        Create a map file
84   --module-id id        Specify a module id
85   --obj file            Link this object file
86   --obj-path path       Specify an object file search path
87   --start-addr addr     Set the default start address
88   --start-group         Start a library group
89   --target sys          Set the target system
90   --version             Print the linker version
91 ---------------------------------------------------------------------------
92 </verb></tscreen>
93
94
95 <sect1>Command line options in detail<p>
96
97 Here is a description of all the command line options:
98
99 <descrip>
100
101   <label id="option--start-group">
102   <tag><tt>-(, --start-group</tt></tag>
103
104   Start a library group. The libraries specified within a group are searched
105   multiple times to resolve crossreferences within the libraries. Normally,
106   crossreferences are only resolved within a library, that is the library is
107   searched multiple times. Libraries specified later on the command line
108   cannot reference otherwise unreferenced symbols in libraries specified
109   earlier, because the linker has already handled them. Library groups are
110   a solution for this problem, because the linker will search repeatedly
111   through all libraries specified in the group, until all possible open
112   symbol references have been satisfied.
113
114
115   <tag><tt>-), --end-group</tt></tag>
116
117   End a library group. See the explanation of the <tt><ref
118   id="option--start-group" name="--start-group"></tt> option.
119
120
121   <tag><tt>-h, --help</tt></tag>
122
123   Print the short option summary shown above.
124
125
126   <label id="option-m">
127   <tag><tt>-m name, --mapfile name</tt></tag>
128
129   This option (which needs an argument that will used as a filename for
130   the generated map file) will cause the linker to generate a map file.
131   The map file does contain a detailed overview over the modules used, the
132   sizes for the different segments, and a table containing exported
133   symbols.
134
135
136   <label id="option-o">
137   <tag><tt>-o name</tt></tag>
138
139   The -o switch is used to give the name of the default output file.
140   Depending on your output configuration, this name may NOT be used as
141   name for the output file. However, for the builtin configurations, this
142   name is used for the output file name.
143
144
145   <label id="option-t">
146   <tag><tt>-t sys, --target sys</tt></tag>
147
148   The argument for the -t switch is the name of the target system. Since this
149   switch will activate a builtin configuration, it may not be used together
150   with the <tt><ref id="option-C" name="-C"></tt> option. The following target
151   systems are currently supported:
152
153   <itemize>
154   <item>none
155   <item>apple2
156   <item>atari
157   <item>atmos
158   <item>c16 (works also for the c116 with memory up to 32K)
159   <item>c64
160   <item>c128
161   <item>plus4
162   <item>cbm510 (CBM-II series with 40 column video)
163   <item>cbm610 (all CBM series-II computers with 80 column video)
164   <item>pet (all CBM PET systems except the 2001)
165   <item>geos
166   <item>lunix
167   <item>atmos
168   <item>nes
169   </itemize>
170
171   There are a few more targets defined but neither of them is actually
172   supported.
173
174
175   <label id="option-v">
176   <tag><tt>-v, --verbose</tt></tag>
177
178   Using the -v option, you may enable more output that may help you to
179   locate problems. If an undefined symbol is encountered, -v causes the
180   linker to print a detailed list of the references (that is, source file
181   and line) for this symbol.
182
183
184   <tag><tt>-vm</tt></tag>
185
186   Must be used in conjunction with <tt><ref id="option-m" name="-m"></tt>
187   (generate map file). Normally the map file will not include empty segments
188   and sections, or unreferenced symbols. Using this option, you can force the
189   linker to include all this information into the map file.
190
191
192   <label id="option-C">
193   <tag><tt>-C</tt></tag>
194
195   This gives the name of an output config file to use. See section 4 for more
196   information about config files. -C may not be used together with <tt><ref
197   id="option-t" name="-t"></tt>.
198
199
200   <label id="option-D">
201   <tag><tt>-D sym=value, --define sym=value</tt></tag>
202
203   This option allows to define an external symbol on the command line. Value
204   may start with a '&dollar;' sign or with <tt/0x/ for hexadecimal values,
205   otherwise a leading zero denotes octal values. See also the <ref
206   id="SYMBOLS" name="SYMBOLS section"> in the configuration file.
207
208
209   <label id="option--lib-path">
210   <tag><tt>-L path, --lib-path path</tt></tag>
211
212   Specify a library search path. This option may be used more than once. It
213   adds a directory to the search path for library files. Libraries specified
214   without a path are searched in current directory, in the directory given in
215   the <tt/LD65_LIB/ environment variable, and in the list of directories
216   specified using <tt/--lib-path/.
217
218
219   <tag><tt>-Ln</tt></tag>
220
221   This option allows you to create a file that contains all global labels and
222   may be loaded into VICE emulator using the <tt/ll/ (load label) command. You
223   may use this to debug your code with VICE. Note: Older versions had some
224   bugs in the label code. If you have problems, please get the latest VICE
225   version.
226
227
228   <label id="option-S">
229   <tag><tt>-S addr, --start-addr addr</tt></tag>
230
231   Using -S you may define the default starting address. If and how this
232   address is used depends on the config file in use. For the builtin
233   configurations, only the "none" system honors an explicit start address,
234   all other builtin config provide their own.
235
236
237   <tag><tt>-V, --version</tt></tag>
238
239   This option print the version number of the linker. If you send any
240   suggestions or bugfixes, please include this number.
241
242
243   <label id="option--cfg-path">
244   <tag><tt>--cfg-path path</tt></tag>
245
246   Specify a config file search path. This option may be used more than once.
247   It adds a directory to the search path for config files. A config file given
248   with the <tt><ref id="option-C" name="-C"></tt> option that has no path in
249   its name is searched in the current directory, in the directory given in the
250   <tt/LD65_CFG/ environment variable, and in the list of directories specified
251   using <tt/--cfg-path/.
252
253
254   <label id="option--dbgfile">
255   <tag><tt>--dbgfile name</tt></tag>
256
257   Specify an output file for debug information. Available information will be
258   written to this file. Using the <tt/-g/ option for the compiler and assembler
259   will increase the amount of information available. Please note that debug
260   information generation is currently being developed, so the format of the
261   file and it's contents are subject to change without further notice.
262
263
264   <tag><tt>--lib file</tt></tag>
265
266   Links a library to the output. Use this command line option instead of just
267   naming the library file, if the linker is not able to determine the file
268   type because of an unusual extension.
269
270
271   <tag><tt>--obj file</tt></tag>
272
273   Links an object file to the output. Use this command line option instead
274   of just naming the object file, if the linker is not able to determine the
275   file type because of an unusual extension.
276
277
278   <label id="option--obj-path">
279   <tag><tt>--obj-path path</tt></tag>
280
281   Specify an object file search path. This option may be used more than once.
282   It adds a directory to the search path for object files. An object file
283   passed to the linker that has no path in its name is searched in current
284   directory, in the directory given in the <tt/LD65_OBJ/ environment variable,
285   and in the list of directories specified using <tt/--obj-path/.
286
287 </descrip>
288
289
290
291 <sect>Search paths<p>
292
293 Starting with version 2.10 there are now several search paths for files needed
294 by the linker: One for libraries, one for object files and one for config
295 files.
296
297
298 <sect1>Library search path<p>
299
300 The library search path contains in this order:
301
302 <enum>
303 <item>The current directory.
304 <item>A compiled in library path which is often <tt>/usr/lib/cc65/lib</tt> on
305       Linux systems.
306 <item>The value of the environment variable <tt/LD65_LIB/ if it is defined.
307 <item>The value of the environment variable <tt/CC65_LIB/ if it is defined.
308       Please note that use of this environment variable is obsolete and may
309       get removed in future versions.
310 <item>Any directory added with the <tt><ref id="option--lib-path"
311       name="--lib-path"></tt> option on the command line.
312 </enum>
313
314
315 <sect1>Object file search path<p>
316
317 The object file search path contains in this order:
318
319 <enum>
320 <item>The current directory.
321 <item>A compiled in directory which is often <tt>/usr/lib/cc65/lib</tt> on
322       Linux systems.
323 <item>The value of the environment variable <tt/LD65_OBJ/ if it is defined.
324 <item>The value of the environment variable <tt/CC65_LIB/ if it is defined.
325       Please note that use of this environment variable is obsolete and may
326       get removed in future versions.
327 <item>Any directory added with the <tt><ref id="option--obj-path"
328       name="--obj-path"></tt> option on the command line.
329 </enum>
330
331
332 <sect1>Config file search path<p>
333
334 The config file search path contains in this order:
335
336 <enum>
337 <item>The current directory.
338 <item>A compiled in directory which is often <tt>/usr/lib/cc65/lib</tt> on
339       Linux systems.
340 <item>The value of the environment variable <tt/LD65_CFG/ if it is defined.
341 <item>Any directory added with the <tt><ref id="option--cfg-path"
342       name="--cfg-path"></tt> option on the command line.
343 </enum>
344
345
346
347 <sect>Detailed workings<p>
348
349 The linker does several things when combining object modules:
350
351 First, the command line is parsed from left to right. For each object file
352 encountered (object files are recognized by a magic word in the header, so
353 the linker does not care about the name), imported and exported
354 identifiers are read from the file and inserted in a table. If a library
355 name is given (libraries are also recognized by a magic word, there are no
356 special naming conventions), all modules in the library are checked if an
357 export from this module would satisfy an import from other modules. All
358 modules where this is the case are marked. If duplicate identifiers are
359 found, the linker issues a warning.
360
361 This procedure (parsing and reading from left to right) does mean, that a
362 library may only satisfy references for object modules (given directly or from
363 a library) named <em/before/ that library. With the command line
364
365 <tscreen><verb>
366         ld65 crt0.o clib.lib test.o
367 </verb></tscreen>
368
369 the module test.o may not contain references to modules in the library
370 clib.lib. If this is the case, you have to change the order of the modules
371 on the command line:
372
373 <tscreen><verb>
374         ld65 crt0.o test.o clib.lib
375 </verb></tscreen>
376
377 Step two is, to read the configuration file, and assign start addresses
378 for the segments and define any linker symbols (see <ref id="config-files"
379 name="Configuration files">).
380
381 After that, the linker is ready to produce an output file. Before doing that,
382 it checks it's data for consistency. That is, it checks for unresolved
383 externals (if the output format is not relocatable) and for symbol type
384 mismatches (for example a zero page symbol is imported by a module as absolute
385 symbol).
386
387 Step four is, to write the actual target files. In this step, the linker will
388 resolve any expressions contained in the segment data. Circular references are
389 also detected in this step (a symbol may have a circular reference that goes
390 unnoticed if the symbol is not used).
391
392 Step five is to output a map file with a detailed list of all modules,
393 segments and symbols encountered.
394
395 And, last step, if you give the <tt><ref id="option-v" name="-v"></tt> switch
396 twice, you get a dump of the segment data. However, this may be quite
397 unreadable if you're not a developer:-)
398
399
400
401 <sect>Configuration files<label id="config-files"><p>
402
403 Configuration files are used to describe the layout of the output file(s). Two
404 major topics are covered in a config file: The memory layout of the target
405 architecture, and the assignment of segments to memory areas. In addition,
406 several other attributes may be specified.
407
408 Case is ignored for keywords, that is, section or attribute names, but it is
409 <em/not/ ignored for names and strings.
410
411
412
413 <sect1>Memory areas<p>
414
415 Memory areas are specified in a <tt/MEMORY/ section. Lets have a look at an
416 example (this one describes the usable memory layout of the C64):
417
418 <tscreen><verb>
419         MEMORY {
420             RAM1:  start = $0800, size = $9800;
421             ROM1:  start = $A000, size = $2000;
422             RAM2:  start = $C000, size = $1000;
423             ROM2:  start = $E000, size = $2000;
424         }
425 </verb></tscreen>
426
427 As you can see, there are two ram areas and two rom areas. The names
428 (before the colon) are arbitrary names that must start with a letter, with
429 the remaining characters being letters or digits. The names of the memory
430 areas are used when assigning segments. As mentioned above, case is
431 significant for these names.
432
433 The syntax above is used in all sections of the config file. The name
434 (<tt/ROM1/ etc.) is said to be an identifier, the remaining tokens up to the
435 semicolon specify attributes for this identifier. You may use the equal sign
436 to assign values to attributes, and you may use a comma to separate
437 attributes, you may also leave both out. But you <em/must/ use a semicolon to
438 mark the end of the attributes for one identifier. The section above may also
439 have looked like this:
440
441 <tscreen><verb>
442         # Start of memory section
443         MEMORY
444         {
445             RAM1:
446                 start $0800
447                 size $9800;
448             ROM1:
449                 start $A000
450                 size $2000;
451             RAM2:
452                 start $C000
453                 size $1000;
454             ROM2:
455                 start $E000
456                 size $2000;
457         }
458 </verb></tscreen>
459
460 There are of course more attributes for a memory section than just start and
461 size. Start and size are mandatory attributes, that means, each memory area
462 defined <em/must/ have these attributes given (the linker will check that). I
463 will cover other attributes later. As you may have noticed, I've used a
464 comment in the example above. Comments start with a hash mark (`#'), the
465 remainder of the line is ignored if this character is found.
466
467
468 <sect1>Segments<p>
469
470 Let's assume you have written a program for your trusty old C64, and you would
471 like to run it. For testing purposes, it should run in the <tt/RAM/ area. So
472 we will start to assign segments to memory sections in the <tt/SEGMENTS/
473 section:
474
475 <tscreen><verb>
476         SEGMENTS {
477             CODE:   load = RAM1, type = ro;
478             RODATA: load = RAM1, type = ro;
479             DATA:   load = RAM1, type = rw;
480             BSS:    load = RAM1, type = bss, define = yes;
481         }
482 </verb></tscreen>
483
484 What we are doing here is telling the linker, that all segments go into the
485 <tt/RAM1/ memory area in the order specified in the <tt/SEGMENTS/ section. So
486 the linker will first write the <tt/CODE/ segment, then the <tt/RODATA/
487 segment, then the <tt/DATA/ segment - but it will not write the <tt/BSS/
488 segment. Why? Enter the segment type: For each segment specified, you may also
489 specify a segment attribute. There are five possible segment attributes:
490
491 <tscreen><verb>
492         ro      means readonly
493         wprot   same as ro but will be marked as write protected in
494                 the VICE label file if -Lp is given
495         rw      means read/write
496         bss     means that this is an uninitialized segment
497         zp      a zeropage segment
498 </verb></tscreen>
499
500 So, because we specified that the segment with the name BSS is of type bss,
501 the linker knows that this is uninitialized data, and will not write it to an
502 output file. This is an important point: For the assembler, the <tt/BSS/
503 segment has no special meaning. You specify, which segments have the bss
504 attribute when linking. This approach is much more flexible than having one
505 fixed bss segment, and is a result of the design decision to supporting an
506 arbitrary segment count.
507
508 If you specify "<tt/type = bss/" for a segment, the linker will make sure that
509 this segment does only contain uninitialized data (that is, zeroes), and issue
510 a warning if this is not the case.
511
512 For a <tt/bss/ type segment to be useful, it must be cleared somehow by your
513 program (this happens usually in the startup code - for example the startup
514 code for cc65 generated programs takes care about that). But how does your
515 code know, where the segment starts, and how big it is? The linker is able to
516 give that information, but you must request it. This is, what we're doing with
517 the "<tt/define = yes/" attribute in the <tt/BSS/ definitions. For each
518 segment, where this attribute is true, the linker will export three symbols.
519
520 <tscreen><verb>
521         __NAME_LOAD__   This is set to the address where the
522                         segment is loaded.
523         __NAME_RUN__    This is set to the run address of the
524                         segment. We will cover run addresses
525                         later.
526         __NAME_SIZE__   This is set to the segment size.
527 </verb></tscreen>
528
529 Replace <tt/NAME/ by the name of the segment, in the example above, this would
530 be <tt/BSS/. These symbols may be accessed by your code.
531
532 Now, as we've configured the linker to write the first three segments and
533 create symbols for the last one, there's only one question left: Where does
534 the linker put the data? It would be very convenient to have the data in a
535 file, wouldn't it?
536
537 <sect1>Output files<p>
538
539 We don't have any files specified above, and indeed, this is not needed in a
540 simple configuration like the one above. There is an additional attribute
541 "file" that may be specified for a memory area, that gives a file name to
542 write the area data into. If there is no file name given, the linker will
543 assign the default file name. This is "a.out" or the one given with the
544 <tt><ref id="option-o" name="-o"></tt> option on the command line. Since the
545 default behaviour is ok for our purposes, I did not use the attribute in the
546 example above. Let's have a look at it now.
547
548 The "file" attribute (the keyword may also be written as "FILE" if you like
549 that better) takes a string enclosed in double quotes (`"') that specifies the
550 file, where the data is written. You may specifiy the same file several times,
551 in that case the data for all memory areas having this file name is written
552 into this file, in the order of the memory areas defined in the <tt/MEMORY/
553 section. Let's specify some file names in the <tt/MEMORY/ section used above:
554
555 <tscreen><verb>
556         MEMORY {
557             RAM1:  start = $0800, size = $9800, file = %O;
558             ROM1:  start = $A000, size = $2000, file = "rom1.bin";
559             RAM2:  start = $C000, size = $1000, file = %O;
560             ROM2:  start = $E000, size = $2000, file = "rom2.bin";
561         }
562 </verb></tscreen>
563
564 The <tt/%O/ used here is a way to specify the default behaviour explicitly:
565 <tt/%O/ is replaced by a string (including the quotes) that contains the
566 default output name, that is, "a.out" or the name specified with the <tt><ref
567 id="option-o" name="-o"></tt> option on the command line. Into this file, the
568 linker will first write any segments that go into <tt/RAM1/, and will append
569 then the segments for <tt/RAM2/, because the memory areas are given in this
570 order. So, for the RAM areas, nothing has really changed.
571
572 We've not used the ROM areas, but we will do that below, so we give the file
573 names here. Segments that go into <tt/ROM1/ will be written to a file named
574 "rom1.bin", and segments that go into <tt/ROM2/ will be written to a file
575 named "rom2.bin". The name given on the command line is ignored in both cases.
576
577 Assigning an empty file name for a memory area will discard the data written
578 to it. This is useful, if the a memory area has segments assigned that are
579 empty (for example because they are of type bss). In that case, the linker
580 will create an empty output file. This may be suppressed by assigning an empty
581 file name to that memory area.
582
583
584 <sect1>LOAD and RUN addresses (ROMable code)<p>
585
586 Let us look now at a more complex example. Say, you've successfully tested
587 your new "Super Operating System" (SOS for short) for the C64, and you
588 will now go and replace the ROMs by your own code. When doing that, you
589 face a new problem: If the code runs in RAM, we need not to care about
590 read/write data. But now, if the code is in ROM, we must care about it.
591 Remember the default segments (you may of course specify your own):
592
593 <tscreen><verb>
594         CODE            read only code
595         RODATA          read only data
596         DATA            read/write data
597         BSS             uninitialized data, read/write
598 </verb></tscreen>
599
600 Since <tt/BSS/ is not initialized, we must not care about it now, but what
601 about <tt/DATA/? <tt/DATA/ contains initialized data, that is, data that was
602 explicitly assigned a value. And your program will rely on these values on
603 startup. Since there's no other way to remember the contents of the data
604 segment, than storing it into one of the ROMs, we have to put it there. But
605 unfortunately, ROM is not writeable, so we have to copy it into RAM before
606 running the actual code.
607
608 The linker cannot help you copying the data from ROM into RAM (this must be
609 done by the startup code of your program), but it has some features that will
610 help you in this process.
611
612 First, you may not only specify a "<tt/load/" attribute for a segment, but
613 also a "<tt/run/" attribute. The "<tt/load/" attribute is mandatory, and, if
614 you don't specify a "<tt/run/" attribute, the linker assumes that load area
615 and run area are the same. We will use this feature for our data area:
616
617 <tscreen><verb>
618         SEGMENTS {
619             CODE:   load = ROM1, type = ro;
620             RODATA: load = ROM2, type = ro;
621             DATA:   load = ROM2, run = RAM2, type = rw, define = yes;
622             BSS:    load = RAM2, type = bss, define = yes;
623         }
624 </verb></tscreen>
625
626 Let's have a closer look at this <tt/SEGMENTS/ section. We specify that the
627 <tt/CODE/ segment goes into <tt/ROM1/ (the one at $A000). The readonly data
628 goes into <tt/ROM2/. Read/write data will be loaded into <tt/ROM2/ but is run
629 in <tt/RAM2/. That means that all references to labels in the <tt/DATA/
630 segment are relocated to be in <tt/RAM2/, but the segment is written to
631 <tt/ROM2/. All your startup code has to do is, to copy the data from it's
632 location in <tt/ROM2/ to the final location in <tt/RAM2/.
633
634 So, how do you know, where the data is located? This is the second point,
635 where you get help from the linker. Remember the "<tt/define/" attribute?
636 Since we have set this attribute to true, the linker will define three
637 external symbols for the data segment that may be accessed from your code:
638
639 <tscreen><verb>
640         __DATA_LOAD__   This is set to the address where the segment
641                         is loaded, in this case, it is an address in
642                         ROM2.
643         __DATA_RUN__    This is set to the run address of the segment,
644                         in this case, it is an address in RAM2.
645         __DATA_SIZE__   This is set to the segment size.
646 </verb></tscreen>
647
648 So, what your startup code must do, is to copy <tt/__DATA_SIZE__/ bytes from
649 <tt/__DATA_LOAD__/ to <tt/__DATA_RUN__/ before any other routines are called.
650 All references to labels in the <tt/DATA/ segment are relocated to <tt/RAM2/
651 by the linker, so things will work properly.
652
653
654 <sect1>Other MEMORY area attributes<p>
655
656 There are some other attributes not covered above. Before starting the
657 reference section, I will discuss the remaining things here.
658
659 You may request symbols definitions also for memory areas. This may be
660 useful for things like a software stack, or an i/o area.
661
662 <tscreen><verb>
663         MEMORY {
664             STACK:  start = $C000, size = $1000, define = yes;
665         }
666 </verb></tscreen>
667
668 This will define three external symbols that may be used in your code:
669
670 <tscreen><verb>
671         __STACK_START__         This is set to the start of the memory
672                                 area, $C000 in this example.
673         __STACK_SIZE__          The size of the area, here $1000.
674         __STACK_LAST__          This is NOT the same as START+SIZE.
675                                 Instead, it it defined as the first
676                                 address that is not used by data. If we
677                                 don't define any segments for this area,
678                                 the value will be the same as START.
679 </verb></tscreen>
680
681 A memory section may also have a type. Valid types are
682
683 <tscreen><verb>
684         ro      for readonly memory
685         rw      for read/write memory.
686 </verb></tscreen>
687
688 The linker will assure, that no segment marked as read/write or bss is put
689 into a memory area that is marked as readonly.
690
691 Unused memory in a memory area may be filled. Use the "<tt/fill = yes/"
692 attribute to request this. The default value to fill unused space is zero. If
693 you don't like this, you may specify a byte value that is used to fill these
694 areas with the "<tt/fillval/" attribute. This value is also used to fill unfilled
695 areas generated by the assemblers <tt/.ALIGN/ and <tt/.RES/ directives.
696
697 The symbol <tt/%S/ may be used to access the default start address (that is,
698 the one defined in the <ref id="FEATURES" name="FEATURES"> section, or the
699 value given on the command line with the <tt><ref id="option-S" name="-S"></tt>
700 option).
701
702
703 <sect1>Other SEGMENT attributes<p>
704
705 Segments may be aligned to some memory boundary. Specify "<tt/align = num/" to
706 request this feature. Num must be a power of two. To align all segments on a
707 page boundary, use
708
709 <tscreen><verb>
710         SEGMENTS {
711             CODE:   load = ROM1, type = ro, align = $100;
712             RODATA: load = ROM2, type = ro, align = $100;
713             DATA:   load = ROM2, run = RAM2, type = rw, define = yes,
714                     align = $100;
715             BSS:    load = RAM2, type = bss, define = yes, align = $100;
716         }
717 </verb></tscreen>
718
719 If an alignment is requested, the linker will add enough space to the output
720 file, so that the new segment starts at an address that is divideable by the
721 given number without a remainder. All addresses are adjusted accordingly. To
722 fill the unused space, bytes of zero are used, or, if the memory area has a
723 "<tt/fillval/" attribute, that value. Alignment is always needed, if you have
724 the used the <tt/.ALIGN/ command in the assembler. The alignment of a segment
725 must be equal or greater than the alignment used in the <tt/.ALIGN/ command.
726 The linker will check that, and issue a warning, if the alignment of a segment
727 is lower than the alignment requested in a <tt/.ALIGN/ command of one of the
728 modules making up this segment.
729
730 For a given segment you may also specify a fixed offset into a memory area or
731 a fixed start address. Use this if you want the code to run at a specific
732 address (a prominent case is the interrupt vector table which must go at
733 address $FFFA). Only one of <tt/ALIGN/ or <tt/OFFSET/ or <tt/START/ may be
734 specified. If the directive creates empty space, it will be filled with zero,
735 of with the value specified with the "<tt/fillval/" attribute if one is given.
736 The linker will warn you if it is not possible to put the code at the
737 specified offset (this may happen if other segments in this area are too
738 large). Here's an example:
739
740 <tscreen><verb>
741         SEGMENTS {
742             VECTORS: load = ROM2, type = ro, start = $FFFA;
743         }
744 </verb></tscreen>
745
746 or (for the segment definitions from above)
747
748 <tscreen><verb>
749         SEGMENTS {
750             VECTORS: load = ROM2, type = ro, offset = $1FFA;
751         }
752 </verb></tscreen>
753
754 The "<tt/align/", "<tt/start/" and "<tt/offset/" attributes change placement
755 of the segment in the run memory area, because this is what is usually
756 desired. If load and run memory areas are equal (which is the case if only the
757 load memory area has been specified), the attributes will also work. There is
758 also a "<tt/align_load/" attribute that may be used to align the start of the
759 segment in the load memory area, in case different load and run areas have
760 been specified. There are no special attributes to set start or offset for
761 just the load memory area.
762
763 To suppress the warning, the linker issues if it encounters a segment that is
764 not found in any of the input files, use "<tt/optional=yes/" as additional
765 segment attribute. Be careful when using this attribute, because a missing
766 segment may be a sign of a problem, and if you're suppressing the warning,
767 there is no one left to tell you about it.
768
769 <sect1>The FILES section<p>
770
771 The <tt/FILES/ section is used to support other formats than straight binary
772 (which is the default, so binary output files do not need an explicit entry
773 in the <tt/FILES/ section).
774
775 The <tt/FILES/ section lists output files and as only attribute the format of
776 each output file. Assigning binary format to the default output file would
777 look like this:
778
779 <tscreen><verb>
780         FILES {
781             %O: format = bin;
782         }
783 </verb></tscreen>
784
785 The only other available output format is the o65 format specified by Andre
786 Fachat. It is defined like this:
787
788 <tscreen><verb>
789         FILES {
790             %O: format = o65;
791         }
792 </verb></tscreen>
793
794 The necessary o65 attributes are defined in a special section labeled
795 <tt/FORMAT/.
796
797
798
799 <sect1>The FORMAT section<p>
800
801 The <tt/FORMAT/ section is used to describe file formats. The default (binary)
802 format has currently no attributes, so, while it may be listed in this
803 section, the attribute list is empty. The second supported format, o65, has
804 several attributes that may be defined here.
805
806 <tscreen><verb>
807     FORMATS {
808         o65: os = lunix, version = 0, type = small,
809              import = LUNIXKERNEL,
810              export = _main;
811     }
812 </verb></tscreen>
813
814
815
816 <sect1>The FEATURES section<label id="FEATURES"><p>
817
818 In addition to the <tt/MEMORY/ and <tt/SEGMENTS/ sections described above, the
819 linker has features that may be enabled by an additional section labeled
820 <tt/FEATURES/.
821
822
823 <sect2>The CONDES feature<p>
824
825 <tt/CONDES/ is used to tell the linker to emit module constructor/destructor
826 tables.
827
828 <tscreen><verb>
829         FEATURES {
830             CONDES: segment = RODATA,
831                     type = constructor,
832                     label = __CONSTRUCTOR_TABLE__,
833                     count = __CONSTRUCTOR_COUNT__;
834         }
835 </verb></tscreen>
836
837 The <tt/CONDES/ feature has several attributes:
838
839 <descrip>
840
841   <tag><tt>segment</tt></tag>
842
843   This attribute tells the linker into which segment the table should be
844   placed. If the segment does not exist, it is created.
845
846
847   <tag><tt>type</tt></tag>
848
849   Describes the type of the routines to place in the table. Type may be one of
850   the predefined types <tt/constructor/, <tt/destructor/, <tt/interruptor/, or
851   a numeric value between 0 and 6.
852
853
854   <tag><tt>label</tt></tag>
855
856   This specifies the label to use for the table. The label points to the start
857   of the table in memory and may be used from within user written code.
858
859
860   <tag><tt>count</tt></tag>
861
862   This is an optional attribute. If specified, an additional symbol is defined
863   by the linker using the given name. The value of this symbol is the number
864   of entries (<em/not/ bytes) in the table. While this attribute is optional,
865   it is often useful to define it.
866
867
868   <tag><tt>order</tt></tag>
869
870   Optional attribute that takes one of the keywords <tt/increasing/ or
871   <tt/decreasing/ as an argument. Specifies the sorting order of the entries
872   within the table. The default is <tt/increasing/, which means that the
873   entries are sorted with increasing priority (the first entry has the lowest
874   priority). "Priority" is the priority specified when declaring a symbol as
875   <tt/.CONDES/ with the assembler, higher values mean higher priority. You may
876   change this behaviour by specifying <tt/decreasing/ as the argument, the
877   order of entries is reversed in this case.
878
879   Please note that the order of entries with equal priority is undefined.
880
881 </descrip>
882
883 Without specifying the <tt/CONDES/ feature, the linker will not create any
884 tables, even if there are <tt/condes/ entries in the object files.
885
886 For more information see the <tt/.CONDES/ command in the <htmlurl
887 url="ca65.html" name="ca65 manual">.
888
889
890 <sect2>The STARTADDRESS feature<p>
891
892 <tt/STARTADDRESS/ is used to set the default value for the start address,
893 which can be referenced by the <tt/%S/ symbol. The builtin default for the
894 linker is &dollar;200.
895
896 <tscreen><verb>
897         FEATURES {
898             # Default start address is $1000
899             STARTADDRESS:       default = $1000;
900         }
901 </verb></tscreen>
902
903 Please note that order is important: The default start address must be defined
904 <em/before/ the <tt/%S/ symbol is used in the config file. This does usually
905 mean, that the <tt/FEATURES/ section has to go to the top of the config file.
906
907
908
909 <sect1>The SYMBOLS section<label id="SYMBOLS"><p>
910
911 The configuration file may also be used to define symbols used in the link
912 stage. The mandatory attribute for a symbol is its value. A second, boolean
913 attribute named <tt/weak/ is available. If a symbol is marked as weak, it may
914 be overridden by defining a symbol of the same name from the command line. The
915 default for symbols is that they're strong, which means that an attempt to
916 define a symbol with the same name from the command line will lead to an
917 error.
918
919 The following example defines the stack size for an application, but allows
920 the programmer to override the value by specifying <tt/--define
921 __STACKSIZE__=xxx/ on the command line.
922
923 <tscreen><verb>
924         SYMBOLS {
925             # Define the stack size for the application
926             __STACKSIZE__:      value = $800, weak = yes;
927         }
928 </verb></tscreen>
929
930
931
932 <sect1>Builtin configurations<p>
933
934 The builtin configurations are part of the linker source. They are also
935 distributed together with the machine specific binary packages (usually in the
936 doc directory) and don't have a special format. So if you need a special
937 configuration, it's a good idea to start with the builtin configuration for
938 your system. In a first step, just replace <tt/-t target/ by <tt/-C
939 configfile/. The go on and modify the config file to suit your needs.
940
941
942
943 <sect>Bugs/Feedback<p>
944
945 If you have problems using the linker, if you find any bugs, or if you're
946 doing something interesting with it, I would be glad to hear from you. Feel
947 free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
948 name="uz@cc65.org">).
949
950
951
952 <sect>Copyright<p>
953
954 ld65 (and all cc65 binutils) are (C) Copyright 1998-2005 Ullrich von
955 Bassewitz. For usage of the binaries and/or sources the following
956 conditions do apply:
957
958 This software is provided 'as-is', without any expressed or implied
959 warranty.  In no event will the authors be held liable for any damages
960 arising from the use of this software.
961
962 Permission is granted to anyone to use this software for any purpose,
963 including commercial applications, and to alter it and redistribute it
964 freely, subject to the following restrictions:
965
966 <enum>
967 <item>  The origin of this software must not be misrepresented; you must not
968         claim that you wrote the original software. If you use this software
969         in a product, an acknowledgment in the product documentation would be
970         appreciated but is not required.
971 <item>  Altered source versions must be plainly marked as such, and must not
972         be misrepresented as being the original software.
973 <item>  This notice may not be removed or altered from any source
974         distribution.
975 </enum>
976
977
978
979 </article>