4 Linking C/C++ Code. Texas Instruments MSP430 Optimizing C/C++ Compiler v 3.2
Annonce
Annonce
Chapter 4
SLAU132D – June 2009
Linking C/C++ Code
The C/C++ compiler and assembly language tools provide two methods for linking your programs:
•
You can compile individual modules and link them together. This method is especially useful when you have multiple source files.
•
You can compile and link in one step. This method is useful when you have a single source module.
This chapter describes how to invoke the linker with each method. It also discusses special requirements of linking C/C++ code, including the run-time-support libraries, specifying the type of initialization, and allocating the program into memory. For a complete description of the linker, see the MSP430 Assembly
Language Tools User's Guide.
Topic
..................................................................................................
Page
4.1
Invoking the Linker Through the Compiler (-z Option)
4.2
..........................................................................
4.3
Linker Code Optimizations
.........................................................
4.4
Controlling the Linking Process
..................................................
SLAU132D – June 2009
Submit Documentation Feedback
Linking C/C++ Code
59
Invoking the Linker Through the Compiler (-z Option)
www.ti.com
4.1
Invoking the Linker Through the Compiler (-z Option)
This section explains how to invoke the linker after you have compiled and assembled your programs: as a separate step or as part of the compile step.
4.1.1 Invoking the Linker Separately
This is the general syntax for linking C/C++ programs as a separate step:
cl430 --run_linker {--rom_model | --ram_model} filenames
[options] [--output_file=name.out] --library=library [lnk.cmd]
cl430 --run_linker
--rom_model | --ram_model
filenames options
--output_file= name.out
--library= library
The command that invokes the linker.
Options that tell the linker to use special conventions defined by the
C/C++ environment. When you use cl430 --run_linker, you must use
--rom_model or --ram_model. The --rom_model option uses automatic variable initialization at run time; the --ram_model option uses variable initialization at load time.
Names of object files, linker command files, or archive libraries. The default extension for all input files is .obj; any other extension must be explicitly specified. The linker can determine whether the input file is an object or ASCII file that contains linker commands. The default output filename is a.out, unless you use the --output_file option to name the output file.
Options affect how the linker handles your object files. Linker options can only appear after the --run_linker option on the command line, but otherwise may be in any order. (Options are discussed in
.)
Names the output file.
Identifies the appropriate archive library containing C/C++ run-time-support and floating-point math functions, or linker command files. If you are linking C/C++ code, you must use a run-time-support library. You can use the libraries included with the compiler, or you can create your own run-time-support library. If you have specified a run-time-support library in a linker command file, you do not need this parameter. The --library option's short form is -l.
Contains options, filenames, directives, or commands for the linker.
lnk.cmd
When you specify a library as linker input, the linker includes and links only those library members that resolve undefined references. The linker uses a default allocation algorithm to allocate your program into memory. You can use the MEMORY and SECTIONS directives in the linker command file to customize the allocation process. For information, see the MSP430 Assembly Language Tools User's Guide.
You can link a C/C++ program consisting of modules prog1.obj, prog2.obj, and prog3.obj, with an executable filename of prog.out with the command: cl430 --run_linker --rom_model prog1 prog2 prog3 --output_file=prog.out
--library=rts430.lib
60
Linking C/C++ Code
SLAU132D – June 2009
Submit Documentation Feedback
www.ti.com
Invoking the Linker Through the Compiler (-z Option)
4.1.2 Invoking the Linker as Part of the Compile Step
This is the general syntax for linking C/C++ programs as part of the compile step:
cl430 filenames [options] --run_linker {--rom_model | --ram_model} filenames
[options] [--output_file=name.out] --library=library [lnk.cmd]
The --run_linker option divides the command line into the compiler options (the options before
--run_linker) and the linker options (the options following --run_linker). The --run_linker option must follow all source files and compiler options on the command line.
All arguments that follow --run_linker on the command line are passed to the linker. These arguments can be linker command files, additional object files, linker options, or libraries. These arguments are the same as described in
All arguments that precede --run_linker on the command line are compiler arguments. These arguments can be C/C++ source files, assembly files, or compiler options. These arguments are described in
.
You can compile and link a C/C++ program consisting of modules prog1.c, prog2.c, and prog3.c, with an executable filename of prog.out with the command: cl430 prog1.c prog2.c prog3.c --run_linker --rom_model --output_file=prog.out --library=rts430.lib
Note: Order of Processing Arguments in the Linker
The order in which the linker processes arguments is important. The compiler passes arguments to the linker in the following order:
1.
Object filenames from the command line
2.
Arguments following the --run_linker option on the command line
3.
Arguments following the --run_linker option from the MSP430_C_OPTION environment variable
4.1.3 Disabling the Linker (--compile_only Compiler Option)
You can override the --run_linker option by using the --compile_only compiler option. The -run_linker option's short form is -z and the --compile_only option's short form is -c.
The --compile_only option is especially helpful if you specify the --run_linker option in the
MSP430_C_OPTION environment variable and want to selectively disable linking with the --compile_only option on the command line.
SLAU132D – June 2009
Submit Documentation Feedback
Linking C/C++ Code
61
Linker Options
www.ti.com
4.2
Linker Options
All command-line input following the --run_linker option (aliased as -z) is passed to the linker as parameters and options. Following are the options that control the linker, along with descriptions of their effects.
--absolute_exe
-ar
--arg_size=size
--compress_dwarf
--define=name[=val]
--diag_error=num
--diag_remark=num
--diag_suppress=num
--diag_warning=num
--disable_auto_rts
--disable_clink
--disable_pp
--display_error_number=num
--entry_point=global_symbol
--fill_value=value
--generate_dead_funcs_list
--globalize='pattern'
--heap_size=size
Produces an absolute, executable module. This is the default; if neither
--absolute_exe nor --relocatable is specified, the linker acts as if
--absolute_exe is specified.
Produces a relocatable, executable object module. The output module contains the special linker symbols, an optional header, and all symbol references. The relocation information is retained.
Allocates memory to be used by the loader to pass arguments from the command line of the loader to the program. The linker allocates size bytes in an uninitialized .args section. The __c_args__ symbol contains the address of the .args section.
Aggressively reduces the size of DWARF information from input object files
Predefines name as a preprocessor macro. This option is distinct from the compiler --define option.
Categorizes the diagnostic identified by num as an error. See
for details.
Categorizes the diagnostic identified by num as a remark. See
for details.
Suppresses the diagnostic identified by num. See
for details.
Categorizes the diagnostic identified by num as a warning. See
for details.
Disables the automatic selection of a run-time-support library. See
for more information.
Disables conditional linking that has been set up with the assembler
.clink directive for COFF object files. By default, all sections are unconditionally linked.
Disables preprocessing for command files. By default, the linker now preprocesses link command files using a standard C preprocessor.
Displays a diagnostic's identifiers along with its text. See
for more information.
Defines a global_symbol that specifies the primary entry point for the output module
Sets the default fill value for null areas within output sections; value is a
16-bit constant
Writes a list of the dead functions that were removed by the linker to file fname for object files
Changes the symbol linkage to global for symbols that match pattern.
The --globalize option only affects symbols that are localized by the
--localize option.
Sets the heap size (for dynamic memory allocation) to size bytes and defines a global symbol that specifies the heap size. The default is 128 bytes.
62
Linking C/C++ Code
SLAU132D – June 2009
Submit Documentation Feedback
www.ti.com
--hide="pattern"
--issue_remarks
--library= libraryname
--linker_help
--localize='pattern'
--make_global=global_symbol
--make_static
--map_file=filename
--mapfile_contents=filter[,filter]
--no_demangle
--no_sym_merge
--no_sym_table
--no_warnings
--output_file=filename
--priority
--ram_model
--relocatable
--reread_libs
--rom_model
--run_abs
--runtime={c95|cpp|rts}
--scan_libraries
Linker Options
Hides global symbols that match pattern by changing the name to an empty string
Issues remarks (nonserious warnings). See
for more information.
Names an archive library file or linker command filename as linker input.
The libraryname is an archive library name and must follow operating system conventions. The --library option's short form is -l.
Produces a help listing displaying syntax and available options
Changes the symbol linkage to local for symbols that match pattern
Defines global_symbol as global even if the global symbol has been made static with the --make_static option
Makes all global symbols static; global symbols are essentially hidden.
This allows external symbols with the same name (in different files) to be treated as unique.
Produces a map or listing of the input and output sections, including null areas, and places the listing in filename. The filename must follow operating system conventions.
Controls the information that appears in the map file. Enter
--mapfile_contents=help on the command line to produce a listing of available options.
Disables demangling of symbol names in diagnostics
Disables merge of symbolic debugging information in COFF object files.
The linker keeps the duplicate entries of symbolic debugging information commonly generated when a C program is compiled for debugging. (Deprecated option; use the strip utility described in the
MSP430 Assembly Language Tools User's Guide.
Creates a smaller output section by stripping symbol table information and line number entries from the output module.
Suppresses warning diagnostics (errors are still issued). See
for more information.
Names the executable output module. The filename must follow operating system conventions. If the --output_file option is not used, the default filename is a.out.
Satisfies each unresolved reference by the first library that contains a definition for that symbol
Initializes variables at load time. See
for more information.
Retains relocation entries in the output module.
Forces rereading of libraries. The linker continues to reread libraries until no more references can be resolved.
Autoinitializes variables at run time. See
for more information.
Produces an absolute listing file.
Designates the header file include path to use for different libraries
(default is rts). See for more information.
Scans all libraries during a link to look for duplicate symbol definitions to those symbols that are actually included in the link.
SLAU132D – June 2009
Submit Documentation Feedback
Linking C/C++ Code
63
Linker Options
--search_path=directory
--set_error_limit=num
--stack_size=size
--strict_compatibility
--symbol_map=refname=defname
--undef_sym=symbol
--undefine=name
--unhide="pattern"
--use_hw_mpy[={16|32|F5}]
--verbose_diagnostics
--warn_sections
--xml_link_info=file www.ti.com
Alters the library-search algorithm to look in directory before looking in the default location. This option must appear before the --library option.
The directory must follow operating system conventions. You can specify up to 128 --search_path options. The --search_path option's short form is -
I
.
Sets the error limit to num. The linker abandons linking after this number of errors. (The default is 100.) See
for more information.
Sets the C/C++ system stack size to size bytes and defines a global symbol that specifies the stack size. The default is 128 bytes.
Performs more conservative and rigorous compatibility checking of input object files.
Enables symbol mapping, which allows a symbol reference to be resolved by a symbol with a different name.
Places the unresolved external symbol symbol into the output module's symbol table. This forces the linker to search a library and include the member that defines the symbol.
Removes the preprocessor macro name. This option is distinct from the compiler --undefine option.
Reveals (un-hides) global symbols that match pattern that are hidden by the --hide option
Replaces all references to the default integer/long multiply routine with the version of the multiply routine that uses hardware multiplier support.
The optional argument can be 16 for 16-bit hardware multiplier (default);
32 for F4xxx 32-bit hardware multiplier; or F5 for F5xxx 32-bit hardware multiplier.
Provides verbose diagnostics that display the original source with line-wrap. See
for more information.
Displays a message when the linker encounters one or more input sections that do not have a corresponding output section defined in the
SECTIONS directive.
Generates an XML link information file. This option causes the linker to generate a well-formed XML file containing detailed information about the result of a link. The information included in this file includes all of the information that is currently produced in a linker generated map file.
For more information on linker options, see the MSP430 Assembly Language Tools User's Guide.
64
Linking C/C++ Code
SLAU132D – June 2009
Submit Documentation Feedback
www.ti.com
Linker Code Optimizations
4.3
Linker Code Optimizations
These options are used to further optimize your code.
4.3.1 Generate List of Dead Functions (--generate_dead_funcs_list Option)
In order to facilitate the removal of unused code, the linker generates a feedback file containing a list of functions that are never referenced. The feedback file must be used the next time you compile the source files. The syntax for the --generate_dead_funcs_list option is:
--generate_dead_funcs_list= filename
If filename is not specified, a default filename of dead_funcs.txt is used.
Proper creation and use of the feedback file entails the following steps:
1. Compile all source files using the --gen_func_subsections compiler option. For example: cl430 file1.c file2.c --gen_func_subsections
2. During the linker, use the --generate_dead_funcs_list option to generate the feedback file based on the generated object files. For example: cl430 --run_linker file1.obj file2.obj
--generate_dead_funcs_list=feedback.txt
Alternatively, you can combine steps 1 and 2 into one step. When you do this, you are not required to specify --gen_func_subsections when compiling the source files as this is done for you automatically.
For example: cl430 file1.c file2.c --run_linker --generate_dead_funcs_list=feedback.txt
3. Once you have the feedback file, rebuild the source. Give the feedback file to the compiler using the
--use_dead_funcs_list option. This option forces each dead function listed in the file into its own subsection. For example: cl430 file1.c file2.c --use_dead_funcs_list=feedback.txt
4. Invoke the linker with the newly built object files. The linker removes the subsections. For example: cl430 --run_linker file1.obj file2.obj
Alternatively, you can combine steps 3 and 4 into one step. For example: cl430 file1.c file2.c --use_dead_funcs_list=feedback.txt --run_linker
Note: Dead Functions Feedback
The feedback file generated with the -gen_dead_funcs_list option is version controlled. It must be generated by the linker in order to be processed correctly by the compiler.
4.3.2 Generating Function Subsections (--gen_func_subsections Compiler Option)
When the linker places code into an executable file, it allocates all the functions in a single source file as a group. This means that if any function in a file needs to be linked into an executable, then all the functions in the file are linked in. This can be undesirable if a file contains many functions and only a few are required for an executable.
This situation may exist in libraries where a single file contains multiple functions, but the application only needs a subset of those functions. An example is a library .obj file that contains a signed divide routine and an unsigned divide routine. If the application requires only signed division, then only the signed divide routine is required for linking. By default, both the signed and unsigned routines are linked in since they exist in the same .obj file.
The --gen_func_subsections compiler option remedies this problem by placing each function in a file in its own subsection. Thus, only the functions that are referenced in the application are linked into the final executable. This can result in an overall code size reduction.
SLAU132D – June 2009
Submit Documentation Feedback
Linking C/C++ Code
65
Controlling the Linking Process
4.4
Controlling the Linking Process
www.ti.com
Regardless of the method you choose for invoking the linker, special requirements apply when linking
C/C++ programs. You must:
•
Include the compiler's run-time-support library
•
Specify the type of initialization
•
Determine how you want to allocate your program into memory
This section discusses how these factors are controlled and provides an example of the standard default linker command file.
For more information about how to operate the linker, see the linker description in the MSP430 Assembly
Language Tools User's Guide.
4.4.1 Including the Run-Time-Support Library
You must include a run-time-support library in the linker process. The following sections describe two methods for including the run-time-support library.
4.4.1.1
Manual Run-Time-Support Library Selection
You must link all C/C++ programs with a run-time-support library. The library contains standard C/C++ functions as well as functions used by the compiler to manage the C/C++ environment. You must use the
--library linker option to specify which MSP430 run-time-support library to use. The --library option also tells the linker to look at the --search_path options and then the MSP430_C_DIR environment variable to find an archive path or object file. To use the --library linker option, type on the command line:
cl430 --run_linker {--rom_model | --ram_model} filenames --library=libraryname
Generally, you should specify the run-time-support library as the last name on the command line because the linker searches libraries for unresolved references in the order that files are specified on the command line. If any object files follow a library, references from those object files to that library are not resolved.
You can use the --reread_libs option to force the linker to reread all libraries until references are resolved.
Whenever you specify a library as linker input, the linker includes and links only those library members that resolve undefined references.
By default, if a library introduces an unresolved reference and multiple libraries have a definition for it, then the definition from the same library that introduced the unresolved reference is used. Use the --priority option if you want the linker to use the definition from the first library on the command line that contains the definition.
4.4.1.2
Automatic Run-Time-Support Library Selection
If the --rom_model or --ram_model option is specified during the linker and the entry point for the program
(normally c_int00) is not resolved by any specified object file or library, the linker attempts to automatically include the best compatible run-time-support library for your program. The chosen run-time-support library is linked in as if it was specified with the --library option last on the command line. Alternatively, you can always force the linker to choose an appropriate run-time-support library by specifying “libc.a” as an argument to the --library option, or when specifying the run-time-support library name explicitly in a linker command file.
The automatic selection of a run-time-support library can be disabled with the --disable_auto_rts option.
If the --issue_remarks option is specified before the --run_linker option during the linker, a remark is generated indicating which run-time support library was linked in. If a different run-time-support library is desired, you must specify the name of the desired run-time-support library using the --library option and in your linker command files when necessary.
66
Linking C/C++ Code
SLAU132D – June 2009
Submit Documentation Feedback
www.ti.com
For example: cl430 --issue_remarks main.c --run_linker --rom_model
<Linking> remark: linking in "libc.a" remark: linking in "rts430.lib" in place of "libc.a"
Controlling the Linking Process
4.4.2 Run-Time Initialization
You must link all C/C++ programs with code to initialize and execute the program called a bootstrap routine. The bootstrap routine is responsible for the following tasks:
•
Set up the stack
•
Process the .cinit run-time initialization table to autoinitialize global variables (when using the
--rom_model option)
•
Call all global constructors (.pinit) for C++
•
Call main.com
•
Call exit when main returns
A sample bootstrap routine is _c_int00, provided in boot.obj in the run-time support object libraries. The entry point is usually set to the starting address of the bootstrap routine.
Note: The _c_int00 Symbol
If you use the --ram_model or --rom_model link option, _c_int00 is automatically defined as the entry point for the program.
4.4.3 Initialization by the Interrupt Vector
If your program begins running from load time, you must set up the reset vector to branch to _c_int00.
This causes boot.obj to be loaded from the library and your program is initialized correctly. The boot.obj
places the address of _c_int00 into a section named .reset. This section can then be allocated at the reset vector location using the linker.
4.4.4 Global Object Constructors
Global C++ variables that have constructors and destructors require their constructors to be called during program initialization and their destructors to be called during program termination. The C++ compiler produces a table of constructors to be called at startup.
The constructors are invoked in the order that they occur in the table.
Global constructors are called after initialization of other global variables and before main( ) is called.
Global destructors are invoked during exit( ), similar to functions registered through atexit( ).
discusses the format of the global constructor table.
SLAU132D – June 2009
Submit Documentation Feedback
Linking C/C++ Code
67
Controlling the Linking Process
www.ti.com
4.4.5 Specifying the Type of Global Variable Initialization
The C/C++ compiler produces data tables for initializing global variables. discusses the format of these initialization tables. The initialization tables are used in one of the following ways:
•
Global variables are initialized at run time. Use the --rom_model linker option (see
•
Global variables are initialized at load time. Use the --ram_model linker option (see
).
When you link a C/C++ program, you must use either the --rom_model or --ram_model option. These options tell the linker to select initialization at run time or load time.
When you compile and link programs, the --rom_model option is the default. If used, the --rom_model option must follow the --run_linker option (see
). The following list outlines the linking conventions used with --rom_model or --ram_model:
•
The symbol _c_int00 is defined as the program entry point; it identifies the beginning of the C/C++ boot routine in boot.obj. When you use --rom_model or --ram_model, _c_int00 is automatically referenced, ensuring that boot.obj is automatically linked in from the run-time-support library.
•
The initialization output section is padded with a termination record so that the loader (load-time initialization) or the boot routine (run-time initialization) knows when to stop reading the initialization tables.
•
The global constructor output section is padded with a termination record.
•
When initializing at load time (the --ram_model option), the following occur:
– The linker sets the initialization table symbol to -1. This indicates that the initialization tables are not in memory, so no initialization is performed at run time.
– The STYP_COPY flag is set in the initialization table section header. STYP_COPY is the special attribute that tells the loader to perform autoinitialization directly and not to load the initialization table into memory. The linker does not allocate space in memory for the initialization table.
•
When autoinitializing at run time (--rom_model option), the linker defines the initialization table symbol as the starting address of the initialization table. The boot routine uses this symbol as the starting point for autoinitialization.
•
The linker defines the starting address of the global constructor table. The boot routine uses this symbol as the beginning of the table of global constructors.
Note: Boot Loader
A loader is not included as part of the C/C++ compiler tools.
4.4.6 Specifying Where to Allocate Sections in Memory
The compiler produces relocatable blocks of code and data. These blocks, called sections, are allocated in memory in a variety of ways to conform to a variety of system configurations.
The compiler creates two basic kinds of sections: initialized and uninitialized.
summarizes the initialized sections.
summarizes the uninitialized sections.
Name
.cinit
.const
Table 4-1. Initialized Sections Created by the Compiler
Contents
Tables for explicitly initialized global and static variables
Global and static const variables that are explicitly initialized and contain string literals
.econst
.pinit
.text
Table of constructors to be called at startup
Executable code and constants
68
Linking C/C++ Code
SLAU132D – June 2009
Submit Documentation Feedback
www.ti.com
Controlling the Linking Process
Name
.args
.bss
.stack
.sysmem
Table 4-2. Uninitialized Sections Created by the Compiler
Contents
Linker-created section used to pass arguments from the command line of the loader to the program
Global and static variables
Stack
Memory for malloc functions (heap)
When you link your program, you must specify where to allocate the sections in memory. In general, initialized sections are linked into ROM or RAM; uninitialized sections are linked into RAM. With the exception of .text, the initialized and uninitialized sections created by the compiler cannot be allocated into internal program memory. See
for a complete description of how the compiler uses these sections.
The linker provides MEMORY and SECTIONS directives for allocating sections. For more information about allocating sections into memory, see the MSP430 Assembly Language Tools User's Guide.
4.4.7 A Sample Linker Command File
shows a typical linker command file that links a 32-bit C program. The command file in this example is named lnk32.cmd and lists several link options:
––rom_model
--stack_size
--heap_size
--library
Tells the linker to use autoinitialization at run time
Tells the linker to set the C stack size at 0x140 bytes
Tells the linker to set the heap size to 0x120 bytes
Tells the linker to use an archive library file, rts430.lib
To link the program, enter:
cl430 --run_linker object_file(s) --output_file=file --map_file=file lnk.cmd
SLAU132D – June 2009
Submit Documentation Feedback
Linking C/C++ Code
69
Controlling the Linking Process
Example 4-1. Linker Command File
--rom_model
--stack_size=0x0140
--heap_size=0x120
--library=rts430.lib
/*****************************************************************************/
/* SPECIFY THE SYSTEM MEMORY MAP */
/*****************************************************************************/
MEMORY
{
SFR(R) : origin = 0x0000, length = 0x0010
PERIPHERALS_8BIT : origin = 0x0010, length = 0x00F0
PERIPHERALS_16BIT: origin = 0x0100, length = 0x0100
RAM(RW) : origin = 0x0200, length = 0x0800
INFOA
INFOB
: origin = 0x1080, length = 0x0080
: origin = 0x1000, length = 0x0080
FLASH
VECTORS(R)
RESET
: origin = 0x1100, length = 0xEEE0
: origin = 0xFFE0, length = 0x001E
: origin = 0xFFFE, length = 0x0002
}
/****************************************************************************/
/* SPECIFY THE SECTIONS ALLOCATION INTO MEMORY */
/****************************************************************************/
SECTIONS
{
.bss
: {} > RAM
.sysmem
: {} > RAM
.stack
: {} > RAM
.text
: {} > FLASH
.cinit
: {} > FLASH
.const
: {} > FLASH
.cio
: {} > RAM
.pinit
: {} > RAM
.intvecs : {} > VECTORS
.reset
: {} > RESET
/* GLOBAL & STATIC VARS
/* DYNAMIC MEMORY ALLOCATION AREA
/* SOFTWARE SYSTEM STACK
/* CODE
/* INITIALIZATION TABLES
/* CONSTANT DATA
/* C I/O BUFFER
/* C++ CONSTRUCTOR TABLES
/* MSP430 INTERRUPT VECTORS
/* MSP430 RESET VECTOR
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/ www.ti.com
70
Linking C/C++ Code
SLAU132D – June 2009
Submit Documentation Feedback
Download
Offentligt link opdateret
Det offentlige link til din chat er blevet opdateret. You may view and manage your chat links after registration here.
Dokument offentligt link
Annonce