X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fld65.sgml;h=457893ffc33a467ff9e8828827f118b0f76777b0;hb=7ab3ede933ca2307b948cd6a218d1f49a4a8aa72;hp=3faecbb6a8ec684148d9104a85de860b47b036e1;hpb=758757d9217d531597fea1be9b4a01c001afdb08;p=cc65 diff --git a/doc/ld65.sgml b/doc/ld65.sgml index 3faecbb6a..457893ffc 100644 --- a/doc/ld65.sgml +++ b/doc/ld65.sgml @@ -67,6 +67,7 @@ Short options: -m name Create a map file -o name Name the default output file -t sys Set the target system + -u sym Force an import of symbol `sym' -v Verbose mode -vm Verbose map file @@ -77,6 +78,7 @@ Long options: --define sym=val Define a symbol --dump-config name Dump a builtin configuration --end-group End a library group + --force-import sym Force an import of symbol `sym' --help Help (this text) --lib file Link this library --lib-path path Specify a library search path @@ -152,26 +154,47 @@ Here is a description of all the command line options: none + module apple2 + apple2enh atari atmos c16 (works also for the c116 with memory up to 32K) c64 c128 - plus4 cbm510 (CBM-II series with 40 column video) cbm610 (all CBM series-II computers with 80 column video) - pet (all CBM PET systems except the 2001) - geos + geos-apple + geos-cbm lunix - atmos + lynx nes + pet (all CBM PET systems except the 2001) + plus4 + supervision + vic20 There are a few more targets defined but neither of them is actually supported. + -u sym[:addrsize], --force-import sym[:addrsize] + + Force an import of a symbol. While object files are always linked to the + output file, regardless if there are any references, object modules from + libraries get only linked in if an import can be satisfied by this module. + The -v, --verbose @@ -230,8 +253,8 @@ Here is a description of all the command line options: Using -S you may define the default starting address. If and how this address is used depends on the config file in use. For the builtin - configurations, only the "none" system honors an explicit start address, - all other builtin config provide their own. + configurations, only the "none", "apple2" and "apple2enh" systems honor an + explicit start address, all other builtin config provide their own. -V, --version @@ -258,7 +281,7 @@ Here is a description of all the command line options: written to this file. Using the --lib file @@ -304,9 +327,8 @@ The library search path contains in this order: A compiled in library path which is often /usr/lib/cc65/lib on Linux systems. The value of the environment variable The value of the environment variable A subdirectory named Any directory added with the option on the command line. @@ -318,12 +340,11 @@ The object file search path contains in this order: The current directory. -A compiled in directory which is often /usr/lib/cc65/lib on +A compiled in directory which is often /usr/lib/cc65/obj on Linux systems. The value of the environment variable The value of the environment variable A subdirectory named Any directory added with the option on the command line. @@ -335,9 +356,11 @@ The config file search path contains in this order: The current directory. -A compiled in directory which is often /usr/lib/cc65/lib on +A compiled in directory which is often /usr/lib/cc65/cfg on Linux systems. The value of the environment variable A subdirectory named Any directory added with the option on the command line. @@ -379,7 +402,7 @@ for the segments and define any linker symbols (see ). After that, the linker is ready to produce an output file. Before doing that, -it checks it's data for consistency. That is, it checks for unresolved +it checks its data for consistency. That is, it checks for unresolved externals (if the output format is not relocatable) and for symbol type mismatches (for example a zero page symbol is imported by a module as absolute symbol). @@ -486,15 +509,13 @@ What we are doing here is telling the linker, that all segments go into the the linker will first write the ro means readonly - wprot same as ro but will be marked as write protected in - the VICE label file if -Lp is given - rw means read/write - bss means that this is an uninitialized segment - zp a zeropage segment + rw means read/write + bss means that this is an uninitialized segment + zp a zeropage segment So, because we specified that the segment with the name BSS is of type bss, @@ -547,7 +568,7 @@ example above. Let's have a look at it now. The "file" attribute (the keyword may also be written as "FILE" if you like that better) takes a string enclosed in double quotes (`"') that specifies the -file, where the data is written. You may specifiy the same file several times, +file, where the data is written. You may specify the same file several times, in that case the data for all memory areas having this file name is written into this file, in the order of the memory areas defined in the + MEMORY { + ROM1: start = $A000, size = $2000, file = "%O-1.bin"; + ROM2: start = $E000, size = $2000, file = "%O-2.bin"; + } + + +would write two files that start with the name of the output file specified on +the command line, with "-1.bin" and "-2.bin" appended respectively. Because +'%' is used as an escape char, the sequence "%%" has to be used if a single +percent sign is required. LOAD and RUN addresses (ROMable code)

@@ -602,7 +636,7 @@ about -This will define three external symbols that may be used in your code: +This will define some external symbols that may be used in your code: __STACK_START__ This is set to the start of the memory - area, $C000 in this example. + area, $C000 in this example. __STACK_SIZE__ The size of the area, here $1000. __STACK_LAST__ This is NOT the same as START+SIZE. - Instead, it it defined as the first - address that is not used by data. If we - don't define any segments for this area, - the value will be the same as START. + Instead, it it defined as the first + address that is not used by data. If we + don't define any segments for this area, + the value will be the same as START. + __STACK_FILEOFFS__ The binary offset in the output file. This + is not defined for relocatable output file + formats (o65). A memory section may also have a type. Valid types are @@ -699,6 +736,13 @@ the one defined in the section, or the value given on the command line with the option). +To support systems with banked memory, a special attribute named Other SEGMENT attributes

@@ -717,14 +761,14 @@ page boundary, use If an alignment is requested, the linker will add enough space to the output -file, so that the new segment starts at an address that is divideable by the +file, so that the new segment starts at an address that is dividable by the given number without a remainder. All addresses are adjusted accordingly. To fill the unused space, bytes of zero are used, or, if the memory area has a " The only other available output format is the o65 format specified by Andre -Fachat. It is defined like this: +Fachat (see the ). It is defined like this: FILES { @@ -800,8 +845,9 @@ The necessary o65 attributes are defined in a special section labeled The , +has several attributes that may be defined here. FORMATS { @@ -909,12 +955,41 @@ mean, that the The SYMBOLS section

The configuration file may also be used to define symbols used in the link -stage. The mandatory attribute for a symbol is its value. A second, boolean -attribute named + + addrsize + + The + + +Without this attribute, the default address size is type + + This attribute is mandatory. Its value is one of value + + This must only be given for symbols of type The following example defines the stack size for an application, but allows the programmer to override the value by specifying SYMBOLS { # Define the stack size for the application - __STACKSIZE__: value = $800, weak = yes; + __STACKSIZE__: type = weak, value = $800; } @@ -931,12 +1006,51 @@ __STACKSIZE__=xxx/ on the command line. Builtin configurations

-The builtin configurations are part of the linker source. They are also -distributed together with the machine specific binary packages (usually in the -doc directory) and don't have a special format. So if you need a special -configuration, it's a good idea to start with the builtin configuration for -your system. In a first step, just replace Secondary configurations

+ +Several machine specific binary packages are distributed together with secondary +configurations (in the cfg directory). These configurations can be used with +Special segments

+ +The builtin config files do contain segments that have a special meaning for +the compiler and the libraries that come with it. If you replace the builtin +config files, you will need the following information. + +INIT

+ +The INIT segment is used for initialization code that may be reused once +execution reaches main() - provided that the program runs in RAM. You +may for example add the INIT segment to the heap in really memory +constrained systems. + +LOWCODE

+ +For the LOWCODE segment, it is guaranteed that it won't be banked out, so it +is reachable at any time by interrupt handlers or similar. + +STARTUP

+ +This segment contains the startup code which initializes the C software stack +and the libraries. It is placed in its own segment because it needs to be +loaded at the lowest possible program address on several platforms. + +ZPSAVE

+ +The ZPSAVE segment contains the original values of the zeropage locations used +by the ZEROPAGE segment. It is placed in its own segment because it must not be +initialized.