10 LINKER

This chapter contains the following sections:

Overview
Linker Invocation
Detailed Description of Linker Options
Libraries
Library Search Path
Linking with Libraries
Library Member Search Algorithm
Linking CLAS COFF Objects
Linker Output
Overlaying Sections
Type Checking
Introduction
Recursive Type Checking
Type Checking between Functions
Missing Types
Linker Messages

10.1 Overview

This section gives a global overview of the process of linking programs for the DSP56xxx and its derivatives. The linker executable name for the DSP5600x is lk56, the linker executable name for the DSP563xx/DSP566xx is lk563. The invocations and examples are given for the DSP563xx.

Unless explicitly stated otherwise, all invocations and examples are also valid for the other executables. Just replace lk563 with the appropriate executable name.

The linker combines relocatable object files, generated by the assembler, or object modules in CLAS COFF object file format into one new relocatable object file (preferred extension .out). This file may be used as input in subsequent linker calls: the linkage process may be incremental. Normally the linker complains about unresolved external references. With incremental linking it is normal to have unresolved references in the output file. Incremental linking must be selected separately.

The linker can read normal object files and libraries of object modules and also Motorola CLAS COFF formatted object files. Modules in a library are included only when they are referenced. At the end of the linkage process the generated object, without unresolved references, will be called: a load module.

For linking Motorola CLAS objects, see the section Linking CLAS COFF Objects

The DSP56xxx linker is an overlaying linker. The compiler generates overlayable sections. An overlayable section contains space reservations for variables which, at C level, are local to a function. If functions do not call each other, their local variables can be overlayed in memory. It is a task of the linker to combine function call information into a call graph and to determine upon the structure of this call graph how sections can be overlayed, using the smallest amount of RAM.

Incremental linkage disables overlaying, so the last link phase should not be incremental, even if the incremental phase resolves all externals.

The following diagram shows the input files and output files of the linker:

Figure 10-1: DSP563xx/DSP566xx Linker

10.2 Linker Invocation

The invocation of the DSP563xx/DSP566xx linker is (use lk56 for the DSP5600x family):

When you use a UNIX shell (C-shell, Bourne shell), options containing special characters (such as '( )' ) must be enclosed with "". The invocations for UNIX and PC are the same, except for the -? option in the C-shell:

Options may appear in any order. Options start with a '-'. Only the -lx option is position dependent. Option may be combined: -rM is equal to -r -M. Options that require a filename or a string may be separated by a space or not: -oname is equal to -o name.

file can be any object file (.obj), CLAS object file, object libraries (.a) or incrementally linker (.out) files. The files are linked in the same order as they appear on the command line.

The linker recognizes the following options:

Option Description
-C Link case insensitive (default case sensitive)
-H or -? Display invocation syntax
-Ldirectory Additional search path for system libraries
-L Skip system library search
-M Produce a linker map (.lnl)
-N Turn off overlaying (lk56 only)
-O name Specify basename of the resulting map files
-V Display version header only
-c Produce a separate call graph file (.cal)
-dfile Read description file information from file ,
'-' means stdin
-e Clean up if erroneous result
-err Redirect error messages to error file (.elk )
-ffile Read command line information from file,
'-' means stdin
-lx Search also in system library libx .a
-m Merge option for different object formats
-o filename Specify name of output file
-r Suppress undefined symbol diagnostics
-usymbol Enter symbol as undefined in the symbol table
-v or -t Verbose option. Print name of each file as it is processed
-wn Suppress messages above warning level n.

Table 10-1: Options summary

10.2.1 Detailed Description of Linker Options

With options that can be set from within EDE, you will find a mouse icon that describes the corresponding action.

-?/-H

Option:

-?
-H

Description:

Display an explanation of the invocation syntax at stdout.

Example:

lk563  -H

-C

Option:

Select the Project | Project Options... menu item. Expand the Linker/Locator entry and select Linker Miscellaneous.
Disable the Link case sensitive check box.

-C

Default:

Case sensitive

Description:

With this option the linker links case insensitive. The default is case sensitive linking.

Example:

To switch to case insensitive mode, enter:

Using the control program:

-c

Option:

Select the Project | Project Options... menu item. Expand the Linker/Locator entry and select Linker Miscellaneous.
Enable the Generate a separate function call graph file (.cal) check box.

-c

Description:

Generate separate call graph file (.cal).

Example:

To create a call graph file (test.cal), enter:

Using the control program:

Section Linker Output.

-d

Option:

Select the Project | Project Options... menu item. Expand the Linker/Locator entry and select Control File.
From the Target list, select a predefined target or select User supplied target definition and specify a target name, select the Use project specific linker/locator control file (.dsc) radio button and enter the name of the description file in the field below.

-d file

Arguments:

A filename to read description file information from. If file is a '-', the information is read from standard input.

Description:

Read description file information from file instead of a .dsc file.

Example:

To read description file information from file 56302evm.dsc, enter:

Using the control program:

-err

Option:

In EDE this option is not useful.

-err

Description:

The linker redirects error messages to a file with the same basename as the output file and the extension .elk. The default filename is a.elk.

Example:

To write errors to the file a.elk instead of stderr, enter:

To write errors to the file test.elk instead of stderr, enter:

-e

Option:

EDE always removes the output files when errors occur.

-e

Description:

Remove all link products such as temporary files, the resulting output file and the map file, in case an error occurred.

Example:

lk563 -e test.obj

-f

Option:

Select the Project | Project Options... menu item. Expand the Linker/Locator entry and select Linker Miscellaneous.
Add the option to the Additional options field.

-f file

Arguments:

A filename for command line processing. The filename "-" may be used to denote standard input.

Description:

Use file for command line processing. To get around the limits on the size of the command line, it is possible to use command files. These command files contain the options that could not be part of the real command line. Command files can also be generated on the fly, for example by the make utility.

More than one -f option is allowed.

Some simple rules apply to the format of the command file:

1. It is possible to have multiple arguments on the same line in the command file.

2. To include whitespace in the argument, surround the argument with either single or double quotes.

3. If single or double quotes are to be used inside a quoted argument, we have to go by the following rules:

a. If the embedded quotes are only single or double quotes, use the opposite quote around the argument. Thus, if a argument should contain a double quote, surround the argument with single quotes.

b. If both types of quotes are used, we have to split the argument in such a way that each embedded quote is surrounded by the opposite type of quote.

Example:

or

or

4. Some operating systems impose limits on the length of lines within a text file. To circumvent this limitation it is possible to use continuation lines. These lines end with a backslash and newline. In a quoted argument, continuation lines will be appended without stripping any whitespace on the next line. For non-quoted arguments, all whitespace on the next line will be stripped.

Example:

5. It is possible to nest command line files up to 25 levels.

Example:

Suppose the file mycmds contains the following line:

The command line can now be:

-L

Option:

Select the Project | Directories... menu item. Add one or more directory paths to the Library Files Path field.

-L[directory]

Arguments:

The name of the directory to search for system libraries.

Description:

Add directory to the list of directories that are searched for system libraries. Directories specified with -L are searched before the standard directories specified by the environment variable C563LIB (for the DSP563xx/DSP566xx, C56LIB for the DSP5600x). If you specify -L without a directory, the environment variable C563LIB (or C56LIB) is not searched for system libraries. You can use the -L option more than once to add several directories to the search path for system libraries. The search path is created in the same order as in which the directories are specified on the command line.

Example:

lk563 -Lc:\c563\lib\563xx test.obj

-l

Option:

Select the Project | Project Options... menu item. Expand the Linker/Locator entry and select Linker Miscellaneous.
Add the option to the Additional options field.

-lx

Arguments:

A string to form the name of the system library libx.a.

Description:

Search also in system library libx.a, where x is a string. The linker first searches for system libraries in any directories specified with -Ldirectory, then in the standard directories specified with the environment variable C563LIB (or C56LIB), unless the -L option is used without a directory specified.

This option is position dependent (see section Linking with Libraries).

Example:

To search in the system library libc16.a after the user object and library are linked, enter:

-M

Option:

Select the Project | Project Options... menu item. Expand the Linker/Locator entry and select Linker Miscellaneous.
Enable the Generate a linker listing file (.lnl) check box.

-M

Description:

Produce a linker map file (.lnl). If no output filename is specified the default name is a.lnl.

Example:

To create the map file a.lnl, enter:

Section Linker Output,
-O .

-m

Option:

Select the Project | Project Options... menu item. Expand the Linker/Locator entry and select Linker Miscellaneous.
Add the option to the Additional options field.

-m

Description:

Merge option to solve incompatibilities between different object formats.

-N (lk56 only)

Option:

Select the Project | Project Options... menu item. Expand the Linker/Locator entry and select Linker Miscellaneous.
Add the option to the Additional options field.

-N

Description:

Turn off overlaying. This can be useful for debugging.

-O

Option:

Select the Project | Project Options... menu item. Expand the Linker/Locator entry and select Linker Miscellaneous.
Add the option to the Additional options field.

-Oname

Arguments:

The basename to be used for map files.

Description:

Use name as the default basename for the resulting map files.

Example:

To create the map file test.lnl using the linker, enter:

Using the control program:

Section Linker Output,
-M .

-o

Option:

Select the Project | Project Options... menu item. Expand the Linker/Locator entry and select Linker Miscellaneous.
Add the option to the Additional options field.

-ofilename

Arguments:

An output filename.

Default:

a.out

Description:

Use filename as output filename of the linker. If this option is omitted, the default filename is a.out.

Example:

To create the output file test.out instead of a.out, enter:

-r

Option:

Select the Project | Project Options... menu item. Expand the Linker/Locator entry and select Linker Miscellaneous.
Add the option to the Additional options field.

-r

Description:

Specify incremental linking. No report is made for unresolved symbols, and the function overlaying is disabled.

Section Linker Output.

-u

Option:

Select the Project | Project Options... menu item. Expand the Linker/Locator entry and select Linker Miscellaneous.
Add the option to the Additional options field.

-usymbol

Arguments:

The name of a symbol to undefine.

Description:

Enter symbol as undefined in the symbol table. This is useful for linking from a library.

Example:

To force symbol main as undefined, enter:

Section Linking with Libraries.

-V

Option:

Select the Project | Project Options... menu item. Expand the Linker/Locator entry and select Linker Miscellaneous.
Add the option to the Additional options field.

-V

Description:

With this option you can display the version header of the linker. This option must be the only argument of lk563. Other options are ignored. The linker exits after displaying the version header.

Example:

lk56 -V
TASKING DSP5600x C linker       vx.yrz Build nnn
Copyright 1995-year Altium BV   Serial# 00000000
lk563 -V
TASKING DSP563xx/6xx linker     vx.yrz Build nnn
Copyright 1996-year Altium BV   Serial# 00000000

-v

Option:

Select the Project | Project Options... menu item. Expand the Linker/Locator entry and select Linker Miscellaneous.
Enable the Print the name of each file as it is processed check box.

-v
-t

Description:

Verbose option. Print the name of each file as it is processed. Also shows which objects are extracted from libraries.

Example:

lk563 -v test.obj

Using the control program:

-w

Option:

Select the Project | Project Options... menu item. Expand the Linker/Locator entry and select Linker Miscellaneous.
Select a warning level from the Suppress warning messages above list box.

-w level

Arguments:

A warning level between 0 and 9 (inclusive).

Default:

-w8

Description:

Give a warning level between 0 and 9 (inclusive). All warnings with a level above level are suppressed. The level of a message is printed between parentheses after the warning number. If you do not use the -w option, the default warning level is 8.

Example:

To suppresses warnings above level 5, enter:

Using the control program:

Section Type Checking.

10.3 Libraries

There are two kinds of libraries. One of them is the user library. If you make your own library of object modules, this library must be specified as an ordinary filename. The linker will not use any search path to find such a library. The file must have the extension .a or .clb. Example:

or, if the library resides in a sub directory:

The other kind of library is the system library. You must define system libraries with the -l option. With the option -lcm you specify the system library libcm.a.

10.3.1 Library Search Path

The linker searches for system library files according to the following algorithm:

1. Use the directories specified with the -Ldirectory options, in a left-to-right order. For example:

PC:

UNIX:

2. If the -L option is not specified without a directory, check if the environment variable C563LIB exists. If it does, use the contents as a directory specifier for library files. It is possible to specify more than one directory in the environment variable C563LIB by separating the directories with a directory separator. Valid directory separators are:

PC:

UNIX:

Instead of using -L as in the example above, the same directory can be specified using C563LIB :

PC:

UNIX:

3. Search in the lib directory relative to the installation directory of lk563 for library files.

PC:

UNIX:

The linker determines run-time which directory the binary is executed from to find this lib directory.

4. If the library is still not found, search in the processor specific subdirectory of the lib directory relative to the installation directory of lk563 for library files. For example:

PC:

UNIX:

A directory name specified with the -Ldirectory option or in C563LIB (or C56LIB for the DSP5600x) may or may not be terminated with a directory separator, because lk563 inserts this separator, if omitted.

10.3.2 Linking with Libraries

If you are linking from libraries, only those objects you need are extracted from the library. This implies that if you invoke the linker like:

nothing is linked and no output file will be produced, because there are no unresolved symbols when the linker searches through mylib.a.

It is possible to force a symbol as undefined with the option -u:

In this case the symbol main will be searched for in the library and (if found) the object containing main will be extracted. If this module contains new unresolved symbols, the linker looks again in mylib.a. This process repeats until no new unresolved symbols are found. See also the library member search algorithm in the next section.

The position of the library is important, if you specify:

the linker starts with searching the system library libc24.a without unresolved symbols, thus no module will be extracted. After that, the user object and library are linked. When finished, all symbols from the C library remain unresolved. So, the correct invocation is:

All symbols which remain unresolved after linking myobj.obj and mylib.a will be searched for in the system library libc24.a.

The link order for objects, user libraries and system libraries is the order in which they appear at the command line. Objects are always linked, object modules in libraries are only linked if they are needed.

10.3.3 Library Member Search Algorithm

A library built with ar563 always contains an index part at the beginning of the library. The linker scans this index while searching for unresolved externals. However, to keep the index as small as possible, only the defined symbols of the library members are recorded in this area.

When the linker finds a symbol that matches an unresolved external, the corresponding object file is extracted from the library and is processed. After processing the object file, the remaining library index is searched. If after a complete search unresolved externals are introduced, the library will be scanned again.

The -v option shows how libraries have been searched and which objects have been extracted.

10.4 Linking CLAS COFF Objects

The linker lk563 reads object files (and object libraries) in the Motorola CLAS COFF format used by the Motorola assembler. The output file of lk563 is always in the IEEE-695 based TIOF format. Output in Motorola CLAS format is not supported.

High level language debug information represented in the CLAS object module will not be placed in the output file of the linker lk563. High level source debugging can only be done on modules compiled with the TASKING c56 or c563 compiler.

The main reason of linking Motorola CLAS object files using lk563 is to be able to link existing object modules which are not available in source (otherwise these sources could be compiled/assembled by the TASKING compilers/assemblers).

Because of the differences in the handling of section scoping in the Motorola assembler and the TASKING assemblers, only public labels at the GLOBAL level can be matched.

Symbols in object files of the same type must match exactly.

As a result of this, it is possible that one external symbol definition matches one or more public symbols.

Overlaying is not supported for sections defined in the Motorola CLAS object format.

The Motorola section names of linked-in CLAS COFF files are converted into TASKING section names according to the following rules:

Absolute sections: motorola_name+'_'+address
Relocatable sections: motorola_name+'_'+section_attributes

Section attributes have the following syntax:

The access and init parts can be:

access init
Text sections: X
Data sections: W I
BSS sections: W B
Overlay sections: W B
Pad sections: W F
Block sections: W I

Table 10-2: Section attributes

All section type letters are explained in section ST Command of Appendix I, IEEE-695 Object Format.

An example Motorola (relocatable) section name is:

10.5 Linker Output

The linker produces an IEEE-695 object output file and, if requested, a linker map file, and/or a call graph file.

The linker output object is still relocatable. It is the task of the locator to determine the absolute addresses of the sections. The linker combines sections with the same name to one (bigger) output section.

The linker produces a map file if the option -M is specified. The name of the map file is the same as the name of the output file. The extension is .lnl. If no output filename is specified the default name is a.lnl. The map file is organized per linked object. Each object is divided in sections and symbols per section. The map file shows the relative position of each linked object from the start of the section.

The generated call graph will also be printed in the map file. The command line option -c forces the linker to generate a separate call graph file with a compressed call graph. The filename extension of this file is .cal.

If the linker is used for incremental linking, the -r option must be used. The effect is, that unresolved symbol diagnostics will not be generated, and overlaying is not done (see 10.6). In this case, the output of the linker can be used again as input object. A call graph will always be generated.

A (part of) sample map file:

The addresses in the map file are offsets relative to the start of the section in the output file. For instance, symbol F_START in the object module cstart.obj is at offset 0x3b from the output .ptext section. Function F_START also starts at offset 0x3b from the start of the resulting .ptext section. The E after the address indicates the label is external.

10.6 Overlay Sections

In order to make memory use in the static memory model more efficient, the compiler generates special sections, with the overlay attribute, which must be overlayed by the linker. Each C function has its own section with local variables, temporaries etc. The linker builds a call graph to determine a valid overlay of the sections of functions which do not call each other.

For example:

The linker detects that foo does not call printf, and printf does not call foo. The compiler generates an overlayable data section for the local, direct addressable, variable i. printf, which also has local variables, gets its own overlayable data section. The linker puts the overlay sections of these two functions at the same (direct addressable) memory area. The advantage is that the target memory is used more efficiently.

10.7 Type Checking

10.7.1 Introduction

By default the compiler and the assembler generate high-level type information. Unless you disable generation of type information (-g0), each object contains type information of high-level types. The linker compares this type information and warns you if there are conflicts. The linker distinguishes four types of conflicts:

1. Type not completely specified (W109). Occurs if you do not specify the depth of an array, or if you do not specify arguments in one of the function prototypes. The linker does not report this type of conflict unless you specify a warning level 9 (-w9), default is warning level 8.

2. Compatible types, different definitions (W110). Occurs if for instance you link a short with an int. The DSP566xx takes both as 16 bits, so there will not be a problem. However, the code is not portable. Also structures or types with different names produce this warning. The warning level for this message is 8, so you can switch off this kind of message by specifying warning level 7 or less (-w7).

3. Signed/unsigned conflict (W111). If you link a signed int with an unsigned int, you get this message. In many cases there will be no problem, but the unsigned version can hold a bigger integer. The warning level of this warning is 6 and can be suppressed by specifying a warning level of 5 or less (-w5).

4. All other type conflicts (W112). If you get warning 112, there is probably a more serious type conflict. This can be a conflict in a function return type, a conflict in length between two built in types (short/long) or a completely different type. This warning has a level of 4, and can be switched off with warning level 3 or less (-w3).

10.7.2 Recursive Type Checking

The linker compares types recursively. For instance, the type of foo:

If you compile this source and link it with another compiled source with only struct s2 different:

message W112 (type conflict) will be generated. Although struct s1 is the same in both cases, this is a real type conflict: For instance, the code "foo.s2_ptr->count++" produces different code in both objects.

If you have several conflicts in one symbol, the linker reports only the one with the lowest warning level. (The most serious one.)

10.7.3 Type Checking between Functions

If you use K&R style functions, it is not possible to check the type of the arguments and the number of arguments. Return types are 'int' if not specified. Prototypes are only needed if a function has a non-integer return type:

In this case, test1 (defined in another source) has a return type void, and test3 has a return type int, which is the default. At the default warning level, the linker does not report any conflict. If you should specify warning level 9 (-w9), the linker reports a 'not completely specified' type, because the linker is not able to check the arguments. Conflicts in return types cause real type conflicts at warning level 4.

If the source is ANSI style (which is recommended), the linker checks the types of all parameters, and the number of parameters. In this case the source of the example above looks like:

Another source, containing the definition of test1 and test3 may look like:

Prototypes are only needed for functions which are referenced before they are defined within one source. However, it is a good practice to include a prototype file with prototypes of all the functions in a file. If you do so, type checking for functions is done by the compiler. Nevertheless, if you do not compile all sources after you have changed the prototype file, the linker will report the type conflict.

It is possible to add ANSI style prototypes to K&R style C-code. In this case full type checking for functions becomes available. To accomplish this, make a new header file with all prototypes for all functions in your application. Include this file in each source, or tell the compiler to include it for you by means of the option -H:

10.7.4 Missing Types

In C you are allowed to define pointers to unspecified objects. The linker is not able to check such types. For instance:

The structure s2 is not specified. Because the linker is not able to check whether struct s2 is the same in all sources, a warning at level 9 will be generated:

It is possible that the struct s2 is known in an other source. If this source uses variable foo, a second message is generated, reporting a level 9 type conflict:

Because the type definition is not complete, the first warning reports that the linker cannot check the type, although this is allowed in C. This message is given once for each object for each incomplete type. The second warning reports a difference in types, an incomplete type versus a complete type.

All these warnings are only generated if you specify warning level 9 (-w9).

10.8 Linker Messages

There are four kinds of messages: fatal messages, error messages, warning messages and verbose messages. Fatal messages are generated if the linker is not able to perform its task due to the severity of the error. In those situations, the exit code will be 2. Error messages will be reported if an error occurred which is not fatal for the linker. However, the output of the linker is not usable. The exit code in case of one or more error messages will be 1. Warning messages are generated if the linker detects potential errors, but the linker is unable to judge those errors. The exit code will be 0 in this case, indicating a usable .out file. Of course, if the linker reports no messages at all, the exit code is 0 also.

Each linker message has a built-in warning level. With option -wx it is possible to suppress messages with a warning level above x.

Verbose messages are generated only if the verbose option (-v) is on. They report the progress of the link process.

Linker messages have the following layout:

  DSP563xx/6xx object linker vx.y rz    SN00000000-000 (c) year TASKING, Inc.
  lk563 W112 (4) a.o: Type conflict for symbol <f> in b.o

The first line shows the banner of the DSP56xxx linker. The second line reports a type conflict in the file a.obj. Apparently there is a conflicting type definition of the function f in module b.obj. The number between parentheses after the warning number, '(4)', shows the warning level.

There are four message groups:

1. Fatal (always level 0):

- Write error

- Out of memory

- Illegal input object

2. Error (always level 0):

- Unresolved symbols (and no incremental linking)

- Can't open input file

- Illegal recursive use of an non reentrant function

3. Warning (levels from 1 to 9):

- Type conflict between two symbols

- Illegal option (Ignored)

- No system library search path, and system library requested

4. Verbose (level not relevant, only given with option -v):

- Extracting files from a library

- Current file/library name

- Pass one or pass two

- Rescanning library for new unresolved symbols

- Cleaning up temp files

- warning level


Copyright © 2002 Altium BV