Table 8-1 Basic Options Summary

Table 8-2 File Search Path Options Summary

Table 8-3 Command File Preprocessing Options Summary

Table 8-4 Diagnostic Options Summary

Table 8-5 Linker Output Options Summary

Table 8-6 Symbol Management Options Summary

Table 8-7 Run-Time Environment Options Summary

Table 8-8 Link-Time Optimization Options Summary

Table 8-9 Miscellaneous Options Summary

8.4.1 Wildcards in File, Section, and Symbol Patterns

The linker allows file, section, and symbol names to be specified using the asterisk (*) and question mark (?) wildcards. Using * matches any number of characters and using ? matches a single character. Using wildcards can make it easier to handle related objects, provided they follow a suitable naming convention.

For example:

8.4.2 Specifying C/C++ Symbols with Linker Options

For COFF ABI, the compiler prepends an underscore _ to the beginning of all C/C++ identifiers. That is, for a function named foo2(), foo2() is prefixed with _ and _foo2 becomes the link-time symbol. For example, the --localize and --globalize options accept link-time symbols. Thus, you specify --localize='_foo2' to localize the C function _foo2(). For more information on linknames see the C/C++ Language Implementation chapter in the TMS320C28x Optimizing C/C++ Compiler User's Guide.

See Section 8.6.1 for information about referring to linker symbols in C/C++ code.

8.4.3 Relocation Capabilities (--absolute_exe and --relocatable Options)

The linker performs relocation, which is the process of adjusting all references to a symbol when the symbol's address changes (Section 2.6).

The linker supports two options (--absolute_exe and --relocatable) that allow you to produce an absolute or a relocatable output module. The linker also supports a third option (-ar) that allows you to produce an executable, relocatable output module.

When the linker encounters a file that contains no relocation or symbol table information, it issues a warning message (but continues executing). Relinking an absolute file can be successful only if each input file contains no information that needs to be relocated (that is, each file has no unresolved references and is bound to the same virtual address that it was bound to when the linker created it).

8.4.4 Allocate Memory for Use by the Loader to Pass Arguments (--arg_size Option)

The --arg_size option instructs the linker to allocate memory to be used by the loader to pass arguments from the command line of the loader to the program. The syntax of the --arg_size option is:

--arg_size=size

The size is the number of bytes to be allocated in target memory for command-line arguments.

By default, the linker creates the __c_args__ symbol and sets it to -1. When you specify --arg_size=size, the following occur:

• The linker creates an uninitialized section named .args of size bytes.
• The __c_args__ symbol contains the address of the .args section.

The loader and the target boot code use the .args section and the __c_args__ symbol to determine whether and how to pass arguments from the host to the target program. See the TMS320C28x Optimizing C/C++ Compiler User's Guide for information about the loader.

8.4.5 Control Linker Diagnostics

The linker uses certain C/C++ compiler options to control linker-generated diagnostics. The diagnostic options must be specified before the --run_linker option.

8.4.6 Disable Automatic Library Selection (--disable_auto_rts Option)

The --disable_auto_rts option disables the automatic selection of a run-time-support library. See the TMS320C28x Optimizing C/C++ Compiler User's Guide for details on the automatic selection process.

8.4.7 Disable Conditional Linking (--disable_clink Option)

The --disable_clink option disables removal of unreferenced sections in COFF object modules. Only sections marked as candidates for removal with the .clink assembler directive are affected by conditional linking. See Conditionally Leave Section Out of Object Module Output for details on setting up conditional linking using the .clink directive.

8.4.8 Linker Command File Preprocessing (--disable_pp, --define and --undefine Options)

The linker preprocesses linker command files using a standard C preprocessor. Therefore, the command files can contain well-known preprocessing directives such as #define, #include, and #if / #endif.

Three linker options control the preprocessor:

The compiler has --define and --undefine options with the same meanings. However, the linker options are distinct; only --define and --undefine options specified after --run_linker are passed to the linker. For example:

The linker sees only the --define for BAR; the compiler only sees the --define for FOO.

When one command file #includes another, preprocessing context is carried from parent to child in the usual way (that is, macros defined in the parent are visible in the child). However, when a command file is invoked other than through #include, either on the command line or by the typical way of being named in another command file, preprocessing context is not carried into the nested file. The exception to this is --define and --undefine options, which apply globally from the point they are encountered. For example:

Two cautions apply to the use of --define and --undefine in command files. First, they have global effect as mentioned above. Second, since they are not actually preprocessing directives themselves, they are subject to macro substitution, probably with unintended consequences. This effect can be defeated by quoting the symbol name. For example:

The linker uses the same search paths to find #include files as it does to find libraries. That is, #include files are searched in the following places:

1. If the #include file name is in quotes (rather than <brackets>), in the directory of the current file
2. In the list of directories specified with --Iibrary options or environment variables (see Section 8.4.14)

There are two exceptions: relative pathnames (such as "../name") always search the current directory; and absolute pathnames (such as "/usr/tools/name") bypass search paths entirely.

The linker provides the built-in macro definitions listed in Table 8-10. The availability of these macros within the linker is determined by the command-line options used, not the build attributes of the files being linked. If these macros are not set as expected, confirm that your project's command line uses the correct compiler option settings.

8.4.9 Error Correcting Code Testing (--ecc Options)

Error Correcting Codes (ECC) can be generated and placed in separate sections through the linker command file. ECC uses extra bits to allow errors to be detected and/or corrected by a device. The ECC support provided by the linker is compatible with the ECC support in TI Flash memory on various TI devices. TI Flash memory uses a modified Hamming(72,64) code, which uses 8 parity bits for every 64 bits. Check the documentation for your Flash memory to see if ECC is supported. (ECC for read-write memory is handled completely in hardware at run time.)

See Section 8.5.10 for details on linker command file syntax for ECC support.

To test ECC error detection and handling, you can use two command-line options that inject bit errors into the linked executable. These options let you specify an address where an error should appear and a bitmask of bits in the code/data at that address to flip. You can specify the address of the error absolutely or as an offset from a symbol.

When a data error is injected, the ECC parity bits for the data are calculated as if the error were not present. This simulates bit errors that might actually occur and test ECC's ability to correct different levels of errors.

The --ecc:data_error option injects errors into the load image at the specified location. The syntax is:

The address is the location of the minimum addressable unit where the error is to be injected. A symbol+offset can be used to specify the location of the error to be injected with a signed offset from that symbol. The page number is needed to make the location non-ambiguous if the address occurs on multiple memory pages. The bitmask is a mask of the bits to flip; its width should be the width of an addressable unit.

For example, the following command line flips the least-significant bit in the byte at the address 0x100, making it inconsistent with the ECC parity bits for that byte:

The following command flips two bits in the third byte of the code for main():

The --ecc:ecc_error option injects errors into the ECC parity bits that correspond to the specified location. Note that the ecc_error option can therefore only specify locations inside ECC input ranges, whereas the data_error option can also specify errors in the ECC output memory ranges. The syntax is:

The parameters for this option are the same as for --ecc:data_error, except that the bitmask must be exactly 8 bits. Mirrored copies of the affected ECC byte will also contain the same injected error.

An error injected into an ECC byte with --ecc:ecc_error may cause errors to be detected at run time in any of the 8 data bytes covered by that ECC byte.

For example, the following command flips every bit in the ECC byte that contains the parity information for the byte at 0x200:

The linker disallows injecting errors into memory ranges that are neither an ECC range nor the input range for an ECC range. The compiler can only inject errors into initialized sections.

8.4.10 Define an Entry Point (--entry_point Option)

The memory address at which a program begins executing is called the entry point. When a loader loads a program into target memory, the program counter (PC) must be initialized to the entry point; the PC then points to the beginning of the program.

The linker can assign one of four values to the entry point. These values are listed below in the order in which the linker tries to use them. If you use one of the first three values, it must be an external symbol in the symbol table.

• The value specified by the --entry_point option. The syntax is:

--entry_point=global_symbol

where global_symbol defines the entry point and must be defined as an external symbol of the input files. The external symbol name of C or C++ objects may be different than the name as declared in the source language; refer to the TMS320C28x Optimizing C/C++ Compiler User's Guide.

• The value of symbol _c_int00 (if present). The _c_int00 symbol must be the entry point if you are linking code produced by the C compiler.
• The value of symbol _main (if present)
• 0 (default value)

This example links file1.obj and file2.obj. The symbol begin is the entry point; begin must be defined as external in file1 or file2.

See Section 8.6.1 for information about referring to linker symbols in C/C++ code.

8.4.11 Set Default Fill Value (--fill_value Option)

The --fill_value option fills the holes formed within output sections. The syntax for the option is:

--fill_value=value

The argument value is a 32-bit constant (up to eight hexadecimal digits). If you do not use --fill_value, the linker uses 0 as the default fill value.

This example fills holes with the hexadecimal value ABCDABCD:

8.4.12 Define Heap Size (--heap_size Option)

The C/C++ compiler uses an uninitialized section called .esysmem for the C run-time memory pool used by malloc(). You can set the size of this memory pool at link time by using the --heap_size option. The syntax for the --heap_size option is:

--heap_size=size

The size must be a constant. This example defines a 4K word heap:

The linker creates the .esysmem section only if there is a .esysmem section in an input file.

The linker also creates a global symbol __SYSMEM_SIZE (COFF) and assigns it a value equal to the size of the heap. The default size is 1K words. See Section 8.6.1 for information about referring to linker symbols in C/C++ code. For more about C/C++ linking, see Section 8.11.

8.4.13 Hiding Symbols

Symbol hiding prevents the symbol from being listed in the output file's symbol table. While localization is used to prevent name space clashes in a link unit, symbol hiding is used to obscure symbols which should not be visible outside a link unit. Such symbol’s names appear only as empty strings or “no name” in object file readers. The linker supports symbol hiding through the --hide and --unhide options.

The syntax for these options are:

--hide='pattern'

--unhide='pattern'

The pattern is a string with optional wildcards ? or *. Use ? to match a single character and use * to match zero or more characters.

The --hide option hides global symbols with a linkname matching the pattern. It hides symbols matching the pattern by changing the name to an empty string. A global symbol that is hidden is also localized.

The --unhide option reveals (un-hides) global symbols that match the pattern that are hidden by the --hide option. The --unhide option excludes symbols that match pattern from symbol hiding provided the pattern defined by --unhide is more restrictive than the pattern defined by --hide.

These options have the following properties:

• The --hide and --unhide options can be specified more than once on the command line.
• The order of --hide and --unhide has no significance.
• A symbol is matched by only one pattern defined by either --hide or --unhide.
• A symbol is matched by the most restrictive pattern. Pattern A is considered more restrictive than Pattern B, if Pattern A matches a narrower set than Pattern B.
• It is an error if a symbol matches patterns from --hide and --unhide and one does not supersede the other. Pattern A supersedes pattern B if A can match everything B can and more. If Pattern A supersedes Pattern B, then Pattern B is said to more restrictive than Pattern A.
• These options affect final and partial linking.

In map files these symbols are listed under the Hidden Symbols heading.

8.4.14 Alter the Library Search Algorithm (--library Option, --search_path Option, and C2000_C_DIR Environment Variable)

Usually, when you want to specify a file as linker input, you simply enter the filename; the linker looks for the file in the current directory. For example, suppose the current directory contains the library object.lib. If this library defines symbols that are referenced in the file file1.obj, this is how you link the files:

If you want to use a file that is not in the current directory, use the --library linker option. The --library option's short form is -l. The syntax for this option is:

--library=[pathname] filename

The filename is the name of an archive, an object file, or linker command file. You can specify up to 128 search paths.

The --library option is not required when one or more members of an object library are specified for input to an output section. For more information about allocating archive members, see Section 8.5.5.5.

You can augment the linker's directory search algorithm by using the --search_path linker option or the C2000_C_DIR environment variable. The linker searches for object libraries and command files in the following order:

1. It searches directories named with the --search_path linker option. The --search_path option must appear before the --Iibrary option on the command line or in a command file.
2. It searches directories named with C2000_C_DIR.
3. If C2000_C_DIR is not set, it searches directories named with the assembler's C2000_A_DIR environment variable.
4. It searches the current directory.

8.4.15 Change Symbol Localization

Symbol localization changes symbol linkage from global to local (static). This is used to obscure global symbols in a library which should not be visible outside the library, but must be global because they are accessed by several modules in the library. The linker supports symbol localization through the --localize and --globalize linker options.

The syntax for these options are:

--localize='pattern'

--globalize='pattern'

The pattern is a string with optional wildcards ? or *. Use ? to match a single character and use * to match zero or more characters.

The --localize option changes the symbol linkage to local for symbols matching the pattern.

The --globalize option changes the symbol linkage to global for symbols matching the pattern. The --globalize option only affects symbols that are localized by the --localize option. The --globalize option excludes symbols that match the pattern from symbol localization, provided the pattern defined by --globalize is more restrictive than the pattern defined by --localize.

See Section 8.4.2 for information about using C/C++ identifiers in linker options such as --localize and --globalize.

These options have the following properties:

• The --localize and --globalize options can be specified more than once on the command line.
• The order of --localize and --globalize options has no significance.
• A symbol is matched by only one pattern defined by either --localize or --globalize.
• A symbol is matched by the most restrictive pattern. Pattern A is considered more restrictive than Pattern B, if Pattern A matches a narrower set than Pattern B.
• It is an error if a symbol matches patterns from --localize and --globalize and if one does not supersede other. Pattern A supersedes pattern B if A can match everything B can, and some more. If Pattern A supersedes Pattern B, then Pattern B is said to more restrictive than Pattern A.
• These options affect final and partial linking.

In map files these symbols are listed under the Localized Symbols heading.

8.4.16 Create a Map File (--map_file Option)

The syntax for the --map_file option is:

--map_file=filename

The linker map describes:

• Memory configuration
• Input and output section allocation
• Linker-generated copy tables
• The addresses of external symbols after they have been relocated
• Hidden and localized symbols

The map file contains the name of the output module and the entry point; it can also contain up to three tables:

• A table showing the new memory configuration if any nondefault memory is specified (memory configuration). The table has the following columns; this information is generated on the basis of the information in the MEMORY directive in the linker command file:
  • Name. This is the name of the memory range specified with the MEMORY directive.
  • Origin. This specifies the starting address of a memory range.
  • Length. This specifies the length of a memory range.
  • Unused. This specifies the total amount of unused (available) memory in that memory area.
  • Attributes. This specifies one to four attributes associated with the named range:

  	R	specifies that the memory can be read.
  	W	specifies that the memory can be written to.
  	X	specifies that the memory can contain executable code.
  	I	specifies that the memory can be initialized.

For more information about the MEMORY directive, see Section 8.5.4.

• A table showing the linked addresses of each output section and the input sections that make up the output sections (section placement map). This table has the following columns; this information is generated on the basis of the information in the SECTIONS directive in the linker command file:
  • Output section. This is the name of the output section specified with the SECTIONS directive.
  • Origin. The first origin listed for each output section is the starting address of that output section. The indented origin value is the starting address of that portion of the output section.
  • Length. The first length listed for each output section is the length of that output section. The indented length value is the length of that portion of the output section.
  • Attributes/input sections. This lists the input file or value associated with an output section. If the input section could not be allocated, the map file will indicate this with "FAILED TO ALLOCATE".

For more information about the SECTIONS directive, see Section 8.5.5.

• A table showing each external symbol and its address sorted by symbol name.
• A table showing each external symbol and its address sorted by symbol address.

The following example links file1.obj and file2.obj and creates a map file called map.out:

Example 8-34 shows an example of a map file.

8.4.17 Managing Map File Contents (--mapfile_contents Option)

The --mapfile_contents option assists with managing the content of linker-generated map files. The syntax for the --mapfile_contents option is:

--mapfile_contents=filter[, filter]

When the --map_file option is specified, the linker produces a map file containing information about memory usage, placement information about sections that were created during a link, details about linker-generated copy tables, and symbol values.

The --mapfile_contents option provides a mechanism for you to control what information is included in or excluded from a map file. When you specify --mapfile_contents=help from the command line, a help screen listing available filter options is displayed. The following filter options are available:

The --mapfile_contents option controls display filter settings by specifying a comma-delimited list of display attributes. When prefixed with the word no, an attribute is disabled instead of enabled. For example:

By default, those sections that are currently included in the map file when the --map_file option is specified are included. The filters specified in the --mapfile_contents options are processed in the order that they appear in the command line. In the third example above, the first filter, none, clears all map file content. The second filter, entry, then enables information about entry points to be included in the generated map file. That is, when --mapfile_contents=none,entry is specified, the map file contains only information about entry points.

The load_addr and sym_defs attributes are both disabled by default.

If you turn on the load_addr filter, the map file includes the load address of symbols that are included in the symbol list in addition to the run address (if the load address is different from the run address).

You can use the sym_defs filter to include information sorted on a file by file basis. You may find it useful to replace the sym_name, sym_dp, and sym_runaddr sections of the map file with the sym_defs section by specifying the following --mapfile_contents option:

8.4.18 Disable Name Demangling (--no_demangle)

By default, the linker uses demangled symbol names in diagnostics. For example:

The --no_demangle option disables the demangling of symbol names in diagnostics. For example:

8.4.19 Disable Merging of Symbolic Debugging Information (--no_sym_merge Option)

By default, the linker eliminates duplicate entries of symbolic debugging information. Such duplicate information is commonly generated when a C program is compiled for debugging. For example:

When these files are compiled for debugging, both f1.obj and f2.obj have symbolic debugging entries to describe type XYZ. For the final output file, only one set of these entries is necessary. The linker eliminates the duplicate entries automatically.

Use the COFF only --no_sym_merge option if you want the linker to keep such duplicate entries in COFF object files. Using the --no_sym_merge option has the effect of the linker running faster and using less host memory during linking, but the resulting executable file may be very large due to duplicated debug information.

8.4.20 Strip Symbolic Information (--no_symtable Option)

The --no_symtable option creates a smaller output module by omitting symbol table information and line number entries. The --no_sym_table option is useful for production applications when you do not want to disclose symbolic information to the consumer.

This example links file1.obj and file2.obj and creates an output module, stripped of line numbers and symbol table information, named nosym.out:

Using the --no_symtable option limits later use of a symbolic debugger.

8.4.21 Name an Output Module (--output_file Option)

The linker creates an output module when no errors are encountered. If you do not specify a filename for the output module, the linker gives it the default name a.out. If you want to write the output module to a different file, use the --output_file option. The syntax for the --output_file option is:

--output_file=filename

The filename is the new output module name.

This example links file1.obj and file2.obj and creates an output module named run.out:

8.4.22 Prioritizing Function Placement (--preferred_order Option)

The compiler prioritizes the placement of a function relative to others based on the order in which --preferred_order options are encountered during the linker invocation. The syntax is:

Refer to the for details on the program cache layout tool, which is impacted by --preferred_option.

8.4.23 C Language Options (--ram_model and --rom_model Options)

The --ram_model and --rom_model options cause the linker to use linking conventions that are required by the C compiler.

• The --ram_model option tells the linker to initialize variables at load time.
• The --rom_model option tells the linker to autoinitialize variables at run time.

For more information, see Section 8.11, Section 3.3.2.1, and Section 3.3.2.2.

8.4.24 Create an Absolute Listing File (--run_abs Option)

The --run_abs option produces an output file for each file linked. These files are named with the input filenames and an extension of .abs. Header files, however, do not generate a corresponding .abs file.

8.4.25 Scan All Libraries for Duplicate Symbol Definitions (--scan_libraries)

The --scan_libraries option scans all libraries during a link looking for duplicate symbol definitions to those symbols that are actually included in the link. The scan does not consider absolute symbols or symbols defined in COMDAT sections. The --scan_libraries option helps determine those symbols that were actually chosen by the linker over other existing definitions of the same symbol in a library.

The library scanning feature can be used to check against unintended resolution of a symbol reference to a definition when multiple definitions are available in the libraries.

8.4.26 Define Stack Size (--stack_size Option)

The TMS320C28x C/C++ compiler uses an uninitialized section, .stack, to allocate space for the run-time stack. You can set the size of this section in words at link time with the --stack_size option. The syntax for the --stack_size option is:

--stack_size=size

The size must be a constant and is in words. This example defines a 4K word stack:

If you specified a different stack size in an input section, the input section stack size is ignored. Any symbols defined in the input section remain valid; only the stack size is different.

When the linker defines the .stack section, it also defines a global symbol, __STACK_SIZE (COFF), and assigns it a value equal to the size of the section. The default software stack size is 1K words. See Section 8.6.1 for information about referring to linker symbols in C/C++ code.

8.4.27 Enforce Strict Compatibility (--strict_compatibility Option)

The linker performs more conservative and rigorous compatibility checking of input object files when you specify the --strict_compatibility option. Using this option guards against additional potential compatibility issues, but may signal false compatibility errors when linking in object files built with an older toolset, or with object files built with another compiler vendor's toolset. To avoid issues with legacy libraries, the --strict_compatibility option is turned off by default.

8.4.28 Mapping of Symbols (--symbol_map Option)

Symbol mapping allows a symbol reference to be resolved by a symbol with a different name. Symbol mapping allows functions to be overridden with alternate definitions. This feature can be used to patch in alternate implementations, which provide patches (bug fixes) or alternate functionality. The syntax for the --symbol_map option is:

--symbol_map=refname=defname

For example, the following code makes the linker resolve any references to foo by the definition foo_patch:

The --symbol_map option is now supported even if --opt_level=4 was used when compiling.

8.4.29 Introduce an Unresolved Symbol (--undef_sym Option)

The --undef_sym option introduces the linkname for an unresolved symbol into the linker's symbol table. This forces the linker to search a library and include the member that defines the symbol. The linker must encounter the --undef_sym option before it links in the member that defines the symbol. The syntax for the --undef_sym option is:

--undef_sym=symbol

For example, suppose a library named rts2800_ml.lib contains a member that defines the symbol symtab; none of the object files being linked reference symtab. However, suppose you plan to relink the output module and you want to include the library member that defines symtab in this link. Using the --undef_sym option as shown below forces the linker to search rts2800_ml.lib for the member that defines symtab and to link in the member.

If you do not use --undef_sym, this member is not included, because there is no explicit reference to it in file1.obj or file2.obj.

8.4.30 Display a Message When an Undefined Output Section Is Created (--warn_sections)

In a linker command file, you can set up a SECTIONS directive that describes how input sections are combined into output sections. However, if the linker encounters one or more input sections that do not have a corresponding output section defined in the SECTIONS directive, the linker combines the input sections that have the same name into an output section with that name. By default, the linker does not display a message to tell you that this occurred.

You can use the --warn_sections option to cause the linker to display a message when it creates a new output section.

For more information about the SECTIONS directive, see Section 8.5.5. For more information about the default actions of the linker, see Section 8.7.

8.4.31 Generate XML Link Information File (--xml_link_info Option)

The linker supports the generation of an XML link information file through the --xml_link_info=file option. 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. See Section B-2 for specifics on the contents of the generated XML file.

8.5.1 Reserved Names in Linker Command Files

The following names (in both uppercase and lowercase) are reserved as keywords for linker directives. Do not use them as symbol or section names in a command file.

In addition, any section names used by the TI tools are reserved from being used as the prefix for other names, unless the section will be a subsection of the section name used by the TI tools. For example, section names may not begin with .debug.

8.5.2 Constants in Linker Command Files

You can specify constants with either of two syntax schemes: the scheme used for specifying decimal, octal, or hexadecimal constants (but not binary constants) used in the assembler (see Section 4.6) or the scheme used for integer constants in C syntax.

Examples:

8.5.3 Accessing Files and Libraries from a Linker Command File

Many applications use custom linker command files (or LCFs) to control the placement of code and data in target memory. For example, you may want to place a specific data object from a specific file into a specific location in target memory. This is simple to do using the available LCF syntax to reference the desired object file or library. However, a problem that many developers run into when they try to do this is a linker generated "file not found" error when accessing an object file or library from inside the LCF that has been specified earlier in the command-line invocation of the linker. Most often, this error occurs because the syntax used to access the file on the linker command-line does not match the syntax that is used to access the same file in the LCF.

Consider a simple example. Imagine that you have an application that requires a table of constants called "app_coeffs" to be defined in a memory area called "DDR". Assume also that the "app_coeffs" data object is defined in a .data section that resides in an object file, app_coeffs.obj. app_coeffs.obj is then included in the object file library app_data.lib. In your LCF, you can control the placement of the "app_coeffs" data object as follows:

Now assume that the app_data.lib object library resides in a sub-directory called "lib" relative to where you are building the application. In order to gain access to app_data.lib from the build command-line, you can use a combination of the –i and –l options to set up a directory search path which the linker can use to find the app_data.lib library:

The –i option adds the lib sub-directory to the directory search path and the –l option instructs the linker to look through the directories in the directory search path to find the app_data.lib library. However, if you do not update the reference to app_data.lib in mylnk.cmd, the linker will fail to find the app_data.lib library and generate a "file not found" error. The reason is that when the linker encounters the reference to app_data.lib inside the SECTIONS directive, there is no –l option preceding the reference. Therefore, the linker tries to open app_data.lib in the current working directory.  

In essence, the linker has a few different ways of opening files:

• If there is a path specified, the linker will look for the file in the specified location. For an absolute path, the linker will try to open the file in the specified directory. For a relative path, the linker will follow the specified path starting from the current working directory and try to open the file at that location.
• If there is no path specified, the linker will try to open the file in the current working directory.
• If a –l option precedes the file reference, then the linker will try to find and open the referenced file in one of the directories in the directory search path. The directory search path is set up via –i options and environment variables (like C_DIR and C6X_C_DIR).

As long as a file is referenced in a consistent manner on the command line and throughout any applicable LCFs, the linker will be able to find and open your object files and libraries.

Returning to the earlier example, you can insert a –l option in front of the reference to app_data.lib in mylnk.cmd to ensure that the linker will find and open the app_data.lib library when the application is built:

Another benefit to using the –l option when referencing a file from within an LCF is that if the location of the referenced file changes, you can modify the directory search path to incorporate the new location of the file (using –i option on the command line, for example) without having to modify the LCF.

8.5.4 The MEMORY Directive

The linker determines where output sections are allocated into memory; it must have a model of target memory to accomplish this. The MEMORY directive allows you to specify a model of target memory so that you can define the types of memory your system contains and the address ranges they occupy. The linker maintains the model as it allocates output sections and uses it to determine which memory locations can be used for object code.

The memory configurations of TMS320C28x systems differ from application to application. The MEMORY directive allows you to specify a variety of configurations. After you use MEMORY to define a memory model, you can use the SECTIONS directive to allocate output sections into defined memory.

For more information, see Section 2.4.

8.5.4.2 MEMORY Directive Syntax

The MEMORY directive identifies ranges of memory that are physically present in the target system and can be used by a program. Each range has several characteristics:

• Page
• Name
• Starting address
• Length
• Optional set of attributes
• Optional fill specification

TMS320C28x devices have separate memory spaces (pages) that occupy the same address ranges (overlay). In the default memory map, one space is dedicated to the program area, while a second is dedicated to the data area. (For detailed information about overlaying pages, see Section 8.5.5.2.7.)

In the linker command file, you configure the address spaces separately by using the MEMORY directive's PAGE option. The linker treats each page as a separate memory space. The TMS320C28x supports up to 255 address spaces, but the number of address spaces available depends on the customized configuration of your device (see the TMS320C2xx User's Guide for more information.)

When you use the MEMORY directive, be sure to identify all memory ranges that are available for the program to access at run time. Memory defined by the MEMORY directive is configured; any memory that you do not explicitly account for with MEMORY is unconfigured. The linker does not place any part of a program into unconfigured memory. You can represent nonexistent memory spaces by simply not including an address range in a MEMORY directive statement.

The MEMORY directive is specified in a command file by the word MEMORY (uppercase), followed by a list of memory range specifications enclosed in braces. The MEMORY directive in Example 8-3 defines a system that has 4K words of slow external memory at address 0x0000 0C00 in program memory, 32 words of fast external memory at address 0x0000 0060 in data memory, and 512 words of slow external memory at address 0x0000 0200 in data memory. It also demonstrates the use of memory range expressions as well as start/end/size address operators (see Example 8-4).

Example 8-3 The MEMORY Directive

/****************************************************************************/ /* Sample command file with MEMORY directive */ /****************************************************************************/ file1.obj file2.obj /* Input files */ --output_file=prog.out /* Options */ #define BUFFER 0 MEMORY { PAGE 0: PROG: origin = 0x00000C00, length = 0x00001000 + BUFFER PAGE 1: SCRATCH: origin = 0x00000060, length = 0x00000020 RAM1: origin = end(SCRATCH,1) + 0x00000180, length = 0x00000200 }

The general syntax for the MEMORY directive is:
MEMORY
{
	[PAGE 0:] name 1 [(attr)] : origin = expression, length = expression [, fill = constant]
	[PAGE 1:] name 2 [(attr)] : origin = expression, length = expression [, fill = constant];
	.
	.
	[PAGEn:] name n [(attr)] : origin = expression, length = expression [, fill = constant]
}

PAGE	identifies a memory space. You can specify up to 32 767 pages. Usually, PAGE 0 specifies program memory, and PAGE 1 specifies data memory. Each PAGE represents a completely independent address space. Configured memory on PAGE 0 can overlap configured memory on PAGE 1 and so on. If you do not specify PAGE for a memory space, the linker defaults to PAGE 0. If you do not specify PAGE in your allocation (see Section 8.5.5), the linker allocates initialized sections to PAGE 0 and uninitialized sections to PAGE 1.
name	names a memory range. A memory name can be one to 64 characters; valid characters include A-Z, a-z, $, ., and _. The names have no special significance to the linker; they simply identify memory ranges. Memory range names are internal to the linker and are not retained in the output file or in the symbol table. All memory ranges must have unique names and must not overlap.
attr	specifies one to four attributes associated with the named range. Attributes are optional; when used, they must be enclosed in parentheses. Attributes restrict the allocation of output sections into certain memory ranges. If you do not use any attributes, you can allocate any output section into any range with no restrictions. Any memory for which no attributes are specified (including all memory in the default model) has all four attributes. Valid attributes are:
	R	specifies that the memory can be read.
	W	specifies that the memory can be written to.
	X	specifies that the memory can contain executable code.
	I	specifies that the memory can be initialized.
origin	specifies the starting address of a memory range; enter as origin, org, or o. The value, specified in bytes, is a 32-bit integer constant expression, which can be decimal, octal, or hexadecimal.
length	specifies the length of a memory range; enter as length, len, or l. The value, specified in bytes, is a 22-bit integer constant expression, which can be decimal, octal, or hexadecimal.
fill	specifies a fill character for the memory range; enter as fill or f. Fills are optional. The value is an integer constant and can be decimal, octal, or hexadecimal. The fill value is used to fill areas of the memory range that are not allocated to a section. (See Section 8.5.10.3 for virtual filling of memory ranges when using Error Correcting Code (ECC).)

NOTE

Filling Memory Ranges

If you specify fill values for large memory ranges, your output file will be very large because filling a memory range (even with 0s) causes raw data to be generated for all unallocated blocks of memory in the range.

The following example specifies a memory range with the R and W attributes and a fill constant of 0FFFFFFFFh:

MEMORY { RFILE (RW) : o = 0x00000020, l = 0x00001000, f = 0xFFFFFFFF }

You normally use the MEMORY directive in conjunction with the SECTIONS directive to control placement of output sections. For more information about the SECTIONS directive, see Section 8.5.5.

Figure 8-2 illustrates the memory map shown in Example 8-3

Figure 8-2 Memory Map Defined in Example 8-3

8.5.5 The SECTIONS Directive

After you use MEMORY to specify the target system's memory model, you can use SECTIONS to allocate output sections into specific named memory ranges or into memory that has specific attributes. For example, you could allocate the .text and .data sections into the area named RAM1 and allocate the .ebss section into the area named PROG.

The SECTIONS directive controls your sections in the following ways:

• Describes how input sections are combined into output sections
• Defines output sections in the executable program
• Allows you to control where output sections are placed in memory in relation to each other and to the entire memory space (Note that the memory placement order is not simply the sequence in which sections occur in the SECTIONS directive.)
• Permits renaming of output sections

For more information, see Section 2.4, Section 2.6, and Section 2.3.6. Subsections allow you to manipulate sections with greater precision.

If you do not specify a SECTIONS directive, the linker uses a default algorithm for combining and allocating the sections. Section 8.7 describes this algorithm in detail.

8.5.5.1 SECTIONS Directive Syntax

The SECTIONS directive is specified in a command file by the word SECTIONS (uppercase), followed by a list of output section specifications enclosed in braces.

The general syntax for the SECTIONS directive is:

SECTIONS
{
	name : [property [, property] [, property] . . . ]
	name : [property [, property] [, property] . . . ]
	name : [property [, property] [, property] . . . ]
}

Each section specification, beginning with name, defines an output section. (An output section is a section in the output file.) Section names can refer to sections, subsections, or archive library members. (See Section 8.5.5.4 for information on multi-level subsections.) After the section name is a list of properties that define the section's contents and how the section is allocated. The properties can be separated by optional commas. Possible properties for a section are as follows:

Load allocation defines where in memory the section is to be loaded. See Section 3.5, Section 3.1.1, and Section 8.5.6.
	Syntax:	load = allocation	or
		> allocation
Run allocation defines where in memory the section is to be run.
	Syntax:	run = allocation	or
		run > allocation
Input sections defines the input sections (object files) that constitute the output section. See Section 8.5.5.3.
	Syntax:	{ input_sections }
Section type defines flags for special section types. See Section 8.5.9.
	Syntax:	type = COPY	or
		type = DSECT	or
		type = NOLOAD
Fill value defines the value used to fill uninitialized holes. See Section 8.5.12.
	Syntax:	fill = value

Example 8-5 shows a SECTIONS directive in a sample linker command file.

Example 8-5 The SECTIONS Directive

/**************************************************/ /* Sample command file with SECTIONS directive */ /**************************************************/ file1.obj file2.obj /* Input files */ --output_file=prog.out /* Options */ SECTIONS { .text: load = PROG, PAGE = 0, run = 0x0200, PAGE = 1 .econst: load = RAM1 .ebss: load = RAM1 .scratch: load = 0x0060, PAGE = 1 { t1.obj(.scratch1) t2.obj(.scratch2) endscratch = .; } .data:alpha: align = 16 .data:beta: align = 16 }

Figure 8-3 shows the output sections defined by the SECTIONS directive in Example 8-5 (.vectors, .text, .econst, .ebss, .data:alpha, and .data:beta) and shows how these sections are allocated in memory using the MEMORY directive given in Example 8-3.

Figure 8-3 Section Placement Defined by Example 8-5

8.5.6 Placing a Section at Different Load and Run Addresses

At times, you may want to load code into one area of memory and run it in another. For example, you may have performance-critical code in slow external memory. The code must be loaded into slow external memory, but it would run faster in fast external memory.

The linker provides a simple way to accomplish this. You can use the SECTIONS directive to direct the linker to allocate a section twice: once to set its load address and again to set its run address. For example:

Use the load keyword for the load address and the run keyword for the run address.

See Section 3.5 for an overview on run-time relocation.

The application must copy the section from its load address to its run address; this does not happen automatically when you specify a separate run address. (The TABLE operator instructs the linker to produce a copy table; see Section 8.8.4.1.)

Uninitialized sections (such as .ebss) are not loaded, so their only significant address is the run address. The linker allocates uninitialized sections only once: if you specify both run and load addresses, the linker warns you and ignores the load address. Otherwise, if you specify only one address, the linker treats it as a run address, regardless of whether you call it load or run.

This example specifies load and run addresses for an uninitialized section:

A warning is issued, load is ignored, and space is allocated in FAST_MEM. All of the following examples have the same effect. The .ebss section is allocated in FAST_MEM.

8.5.6.2 Referring to the Load Address by Using the .label Directive

Normally, any reference to a symbol refers to its run-time address. However, it may be necessary at run time to refer to a load-time address. Specifically, the code that copies a section from its load address to its run address must have access to the load address. The .label directive defines a special symbol that refers to the section's load address. Thus, whereas normal symbols are relocated with respect to the run address, .label symbols are relocated with respect to the load address. See Create a Load-Time Address Label for more information on the .label directive.

Example 8-10 and Example 8-11 show the use of the .label directive to copy a section from its load address in SLOW_MEM to its run address in FAST_MEM. Figure 8-4 illustrates the run-time execution of Example 8-10.

If you use the table operator, the .label directive is not needed. See Section 8.8.4.1.

Example 8-10 Moving a Function from Slow to Fast Memory at Run Time

;--------------------------------------------------------- ; define a section to be copied from SLOW_MEM to FAST_MEM ;--------------------------------------------------------- .sect ".fir" .label fir_src ; load address of section fir: ; run address of section <code here> ; code for the section .label fir_end ; load address of section end ;--------------------------------------------------------- ; copy .fir section from SLOW_MEM to FAST_MEM ;--------------------------------------------------------- .text MOV XAR6, fir_src MOV XAR7, #fir RPT #(fir_end - fir_src - 1) k PWRITE *XAR7, *XAR6++ ;--------------------------------------------------------- ; jump to section, now in FAST_MEM ;--------------------------------------------------------- B fir

Example 8-11 Linker Command File for Example 8-10

/*******************************************************************/ /* PARTIAL LINKER COMMAND FILE FOR FIR EXAMPLE */ /*******************************************************************/ MEMORY { PAGE 0 : FAST_MEM : origin = 0x00000800, length = 0x00002400 PAGE 0 : PROG : origin = 0x00002C00, length = 0x0000D200 PAGE 1 : SLOW_MEM : origin = 0x00000800, length = 0x0000F800 } SECTIONS { .text: load = PROG PAGE 0 .fir: load = SLOW_MEM PAGE 1, run = FAST_MEM PAGE 0 }

Figure 8-4 Run-Time Execution of Example 8-10

See Section 8.6.1 for information about referring to linker symbols in C/C++ code.

8.5.7 Using GROUP and UNION Statements

Two SECTIONS statements allow you to organize or conserve memory: GROUP and UNION. Grouping sections causes the linker to allocate them contiguously in memory. Unioning sections causes the linker to allocate them to the same run address.

8.5.7.2 Overlaying Sections With the UNION Statement

For some applications, you may want to allocate more than one section that occupies the same address during run time. For example, you may have several routines you want in fast external memory at different stages of execution. Or you may want several data objects that are not active at the same time to share a block of memory. The UNION statement within the SECTIONS directive provides a way to allocate several sections at the same run-time address.

In Example 8-13, the .ebss sections from file1.obj and file2.obj are allocated at the same address in FAST_MEM. In the memory map, the union occupies as much space as its largest component. The components of a union remain independent sections; they are simply allocated together as a unit.

Example 8-13 The UNION Statement

SECTIONS { .text: load = SLOW_MEM UNION: run = FAST_MEM { .ebss:part1: { file1.obj(.ebss) } .ebss:part2: { file2.obj(.ebss) } } .ebss:part3: run = FAST_MEM { globals.obj(.ebss) } }

Allocation of a section as part of a union affects only its run address. Under no circumstances can sections be overlaid for loading. If an initialized section is a union member (an initialized section, such as .text, has raw data), its load allocation must be separately specified. See Example 8-14.

Example 8-14 Separate Load Addresses for UNION Sections

UNION run = FAST_MEM { .text:part1: load = SLOW_MEM, { file1.obj(.text) } .text:part2: load = SLOW_MEM, { file2.obj(.text) } }

Figure 8-5 Memory Allocation Shown in Example 8-13 and Example 8-14

Since the .text sections contain raw data, they cannot load as a union, although they can be run as a union. Therefore, each requires its own load address. If you fail to provide a load allocation for an initialized section within a UNION, the linker issues a warning and allocates load space anywhere it can in configured memory.

Uninitialized sections are not loaded and do not require load addresses.

The UNION statement applies only to allocation of run addresses, so it is meaningless to specify a load address for the union itself. For purposes of allocation, the union is treated as an uninitialized section: any one allocation specified is considered a run address, and if both run and load addresses are specified, the linker issues a warning and ignores the load address.

NOTE

UNION and Overlay Page Are Not the Same

The UNION capability and the overlay page capability (see Section 8.5.8) may sound similar because they both deal with overlays. They are, in fact, quite different. UNION allows multiple sections to be overlaid within the same memory space. Overlay pages, on the other hand, define multiple memory spaces. It is possible to use the page facility to approximate the function of UNION, but this is cumbersome.

8.5.8 Overlaying Pages

Some devices use a memory configuration in which all or part of the memory space is overlaid by shadow memory. This allows the system to map different banks of physical memory into and out of a single address range in response to hardware selection signals. In other words, multiple banks of physical memory overlay each other at one address range. You may want the linker to load various output sections into each of these banks or into banks that are not mapped at load time.

The linker supports this feature by providing overlay pages. Each page represents an address range that must be configured separately with the MEMORY directive. You then use the SECTIONS directive to specify the sections to be mapped into various pages.

8.5.8.4 Memory Allocation for Overlaid Pages

Figure 8-6 shows overlay pages defined by the MEMORY directive in Example 8-16 and the SECTIONS directive in Example 8-17.

Figure 8-6 Overlay Pages Defined in Example 8-16 and Example 8-17

8.5.9 Special Section Types (DSECT, COPY, and NOLOAD)

You can assign the following special types to output sections: DSECT, COPY, and NOLOAD. These types affect the way that the program is treated when it is linked and loaded. You can assign a type to a section by placing the type after the section definition. For example:

• The DSECT type creates a dummy section with the following characteristics:
  • It is not included in the output section memory allocation. It takes up no memory and is not included in the memory map listing.
  • It can overlay other output sections, other DSECTs, and unconfigured memory.
  • Global symbols defined in a dummy section are relocated normally. They appear in the output module's symbol table with the same value they would have if the DSECT had actually been loaded. These symbols can be referenced by other input sections.
  • Undefined external symbols found in a DSECT cause specified archive libraries to be searched.
  • The section's contents, relocation information, and line number information are not placed in the output module.

In the preceding example, none of the sections from f1.obj are allocated, but all the symbols are relocated as though the sections were linked at address 0x2000. The other sections can refer to any of the global symbols in sec1.

• A COPY section is similar to a DSECT section, except that its contents and associated information are written to the output module. The .cinit section that contains initialization tables for the TMS320C28x C/C++ compiler has this attribute under the run-time initialization model.
• A NOLOAD section differs from a normal output section in one respect: the section's contents, relocation information, and line number information are not placed in the output module. The linker allocates space for the section, and it appears in the memory map listing.

8.5.10 Configuring Error Correcting Code (ECC) with the Linker

Error Correcting Codes (ECC) can be generated and placed in separate sections through the linker command file. ECC uses extra bits to allow errors to be detected and/or corrected by a device. The ECC support provided by the linker is compatible with the ECC support in TI Flash memory on various TI devices. TI Flash memory uses a modified Hamming(72,64) code, which uses 8 parity bits for every 64 bits. Check the documentation for your Flash memory to see if ECC is supported. (ECC for read-write memory is handled completely in hardware at run time.)

See Section 8.4.9 for command-line options that introduce bit errors into code that has a corresponding ECC section or into the ECC parity bits themselves. You can use these options to test your ECC error handling code.

ECC can be generated during linking. The ECC data is included in the resulting object file, alongside code and data, as a data section located at the appropriate address. No extra ECC generation step is required after compilation, and the ECC can be uploaded to the device along with everything else.

You can control the generation of ECC data using the ECC specifier in the memory map (Section 8.5.10.1) and the ECC directive (Section 8.5.10.2).

8.5.11 Assigning Symbols at Link Time

Linker assignment statements allow you to define external (global) symbols and assign values to them at link time. You can use this feature to initialize a variable or pointer to an allocation-dependent value. See Section 8.6.1 for information about referring to linker symbols in C/C++ code.

8.5.12 Creating and Filling Holes

The linker provides you with the ability to create areas within output sections that have nothing linked into them. These areas are called holes. In special cases, uninitialized sections can also be treated as holes. This section describes how the linker handles holes and how you can fill holes (and uninitialized sections) with values.

8.6.1 Using Linker Symbols in C/C++ Applications

Linker symbols have a name and a value. The value is a 32-bit unsigned integer, even if it represents a pointer value on a target that has pointers smaller than 32 bits.

The most common kind of symbol is generated by the compiler for each function and variable. The value represents the target address where that function or variable is located. When you refer to the symbol by name in the linker command file or in an assembly file, you get that 32-bit integer value.

However, in C and C++ names mean something different. If you have a variable named x that contains the value Y, and you use the name "x" in your C program, you are actually referring to the contents of variable x. If "x" is used on the right-hand side of an expression, the compiler fetches the value Y. To realize this variable, the compiler generates a linker symbol named x with the value &x. Even though the C/C++ variable and the linker symbol have the same name, they don't represent the same thing. In C, x is a variable name with the address &x and content Y. For linker symbols, x is an address, and that address contains the value Y.

Because of this difference, there are some tricks to referring to linker symbols in C code. The basic technique is to cause the compiler to creating a "fake" C variable or function and take its address. The details differ depending on the type of linker symbol.

Linker symbols that represent a function address: In C code, declare the function as an extern function. Then, refer to the value of the linker symbol using the same name. This works because function pointers "decay" to their address value when used without adornment. For example:

Suppose your linker command file defines the following linker symbol:

Your C application can refer to this symbol as follows:

Linker symbols that represent a data address: In C code, declare the variable as an extern variable. Then, refer to the value of the linker symbol using the & operator. Because the variable is at a valid data address, we know that a data pointer can represent the value.

Suppose your linker command file defines the following linker symbols:

Your C application can refer to these symbols as follows:

Linker symbols for an arbitrary address: In C code, declare this as an extern symbol. The type does not matter. If you are using GCC extensions, declare it as "extern void". If you are not using GCC extensions, declare it as "extern char". Then, refer to the value of the linker symbol mySymbol as _symval(&mySymbol). You must use the _symval operator, which is equivalent to a cast, because the 32-bit value of the linker symbol could be wider than a data pointer. The compiler treats _symval(&mySymbol) in a special way that can represent all 32 bits, even when pointers are 16 bits. Targets that have 32-bit pointers can usually use &mySymbol instead of the _symval operator. However, the portable way to access such linker symbols across TI targets is to use _symval(&mySymbol).

Suppose your linker command file defines the following linker symbol:

Your C application can refer to this symbol as follows:

8.6.2 Resolving Symbols with Object Libraries

An object library is a partitioned archive file that contains object files as members. Usually, a group of related modules are grouped together into a library. When you specify an object library as linker input, the linker includes any members of the library that define existing unresolved symbol references. You can use the archiver to build and maintain libraries. Section 7.1 contains more information about the archiver.

Using object libraries can reduce link time and the size of the executable module. Normally, if an object file that contains a function is specified at link time, the file is linked whether the function is used or not; however, if that same function is placed in an archive library, the file is included only if the function is referenced.

The order in which libraries are specified is important, because the linker includes only those members that resolve symbols that are undefined at the time the library is searched. The same library can be specified as often as necessary; it is searched each time it is included. Alternatively, you can use the --reread_libs option to reread libraries until no more references can be resolved (see Section 8.4.14.3). A library has a table that lists all external symbols defined in the library; the linker searches through the table until it determines that it cannot use the library to resolve any more references.

The following examples link several files and libraries, using these assumptions:

• Input files f1.obj and f2.obj both reference an external function named clrscr.
• Input file f1.obj references the symbol origin.
• Input file f2.obj references the symbol fillclr.
• Member 0 of library libc.lib contains a definition of origin.
• Member 3 of library liba.lib contains a definition of fillclr.
• Member 1 of both libraries defines clrscr.

If you enter:

then:

• Member 1 of liba.lib satisfies the f1.obj and f2.obj references to clrscr because the library is searched and the definition of clrscr is found.
• Member 0 of libc.lib satisfies the reference to origin.
• Member 3 of liba.lib satisfies the reference to fillclr.

If, however, you enter:

then the references to clrscr are satisfied by member 1 of libc.lib.

If none of the linked files reference symbols defined in a library, you can use the --undef_sym option to force the linker to include a library member. (See Section 8.4.29.) The next example creates an undefined symbol rout1 in the linker's global symbol table:

If any member of libc.lib defines rout1, the linker includes that member.

Library members are allocated according to the SECTIONS directive default allocation algorithm; see Section 8.5.5.

Section 8.4.14 describes methods for specifying directories that contain object libraries.

8.7.1 How the Allocation Algorithm Creates Output Sections

An output section can be formed in one of two ways:

If an output section is formed as a result of a SECTIONS directive, this definition completely determines the section's contents. (See Section 8.5.5 for examples of how to define an output section's content.)

If an output section is formed by combining input sections not specified by a SECTIONS directive, the linker combines all such input sections that have the same name into an output section with that name. For example, suppose the files f1.obj and f2.obj both contain named sections called Vectors and that the SECTIONS directive does not define an output section for them. The linker combines the two Vectors sections from the input files into a single output section named Vectors, allocates it into memory, and includes it in the output file.

By default, the linker does not display a message when it creates an output section that is not defined in the SECTIONS directive. You can use the --warn_sections linker option (see Section 8.4.30) to cause the linker to display a message when it creates a new output section.

After the linker determines the composition of all output sections, it must allocate them into configured memory. The MEMORY directive specifies which portions of memory are configured. If there is no MEMORY directive, the linker uses the default configuration as shown in Example 8-18. (See Section 8.5.4 for more information on configuring memory.)

8.7.2 Reducing Memory Fragmentation

The linker's allocation algorithm attempts to minimize memory fragmentation. This allows memory to be used more efficiently and increases the probability that your program will fit into memory. The algorithm comprises these steps:

1. Each output section for which you supply a specific binding address is placed in memory at that address.
2. Each output section that is included in a specific, named memory range or that has memory attribute restrictions is allocated. Each output section is placed into the first available space within the named area, considering alignment where necessary.
3. Any remaining sections are allocated in the order in which they are defined. Sections not defined in a SECTIONS directive are allocated in the order in which they are encountered. Each output section is placed into the first available memory space, considering alignment where necessary.

If you want to control the order in which code and data are placed in memory, see the FAQ topic on section placement.

8.8.1 Using Copy Tables for Boot Loading

In some embedded applications, there is a need to copy or download code and/or data from one location to another at boot time before the application actually begins its main execution thread. For example, an application may have its code and/or data in FLASH memory and need to copy it into on-chip memory before the application begins execution.

One way to develop such an application is to create a copy table in assembly code that contains three elements for each block of code or data that needs to be moved from FLASH to on-chip memory at boot time:

• The load location (load page id and address)
• The run location (load page id and address)
• The size

The process you follow to develop such an application might look like this:

1. Build the application to produce a .map file that contains the load and run addresses of each section that has a separate load and run placement.
2. Edit the copy table (used by the boot loader) to correct the load and run addresses as well as the size of each block of code or data that needs to be moved at boot time.
3. Build the application again, incorporating the updated copy table.
4. Run the application.

This process puts a heavy burden on you to maintain the copy table (by hand, no less). Each time a piece of code or data is added or removed from the application, you must repeat the process in order to keep the contents of the copy table up to date.

8.8.2 Using Built-in Link Operators in Copy Tables

You can avoid some of this maintenance burden by using the LOAD_START(), RUN_START(), and SIZE() operators that are already part of the linker command file syntax . For example, instead of building the application to generate a .map file, the linker command file can be annotated:

In this example, the LOAD_START(), RUN_START(), and SIZE() operators instruct the linker to create three symbols:

These symbols can then be referenced from the copy table. The actual data in the copy table will be updated automatically each time the application is linked. This approach removes step 1 of the process described in Section 8.8.1.

While maintenance of the copy table is reduced markedly, you must still carry the burden of keeping the copy table contents in sync with the symbols that are defined in the linker command file. Ideally, the linker would generate the boot copy table automatically. This would avoid having to build the application twice and free you from having to explicitly manage the contents of the boot copy table.

For more information on the LOAD_START(), RUN_START(), and SIZE() operators, see Section 8.5.11.6.

8.8.3 Overlay Management Example

Consider an application that contains a memory overlay that must be managed at run time. The memory overlay is defined using a UNION in the linker command file as illustrated in Example 8-19:

The application must manage the contents of the memory overlay at run time. That is, whenever any services from .task1 or .task2 are needed, the application must first ensure that .task1 and .task2 are resident in the memory overlay. Similarly for .task3 and .task4.

To affect a copy of .task1 and .task2 from ROM to RAM at run time, the application must first gain access to the load address of the tasks (_task12_load_start), the run address (_task_run_start), and the size (_task12_size). Then this information is used to perform the actual code copy.

8.8.4 Generating Copy Tables With the table() Operator

The linker supports extensions to the linker command file syntax that enable you to do the following:

• Identify any object components that may need to be copied from load space to run space at some point during the run of an application
• Instruct the linker to automatically generate a copy table that contains (at least) the load address, run address, and size of the component that needs to be copied
• Instruct the linker to generate a symbol specified by you that provides the address of a linker-generated copy table. For instance, Example 8-19 can be written as shown in Example 8-20:

Using the SECTIONS directive from Example 8-20 in the linker command file, the linker generates two copy tables named: _task12_copy_table and _task34_copy_table. Each copy table provides the load address, run address, and size of the GROUP that is associated with the copy table. This information is accessible from application source code using the linker-generated symbols, _task12_copy_table and _task34_copy_table, which provide the addresses of the two copy tables, respectively.

Using this method, you need not worry about the creation or maintenance of a copy table. You can reference the address of any copy table generated by the linker in C/C++ or assembly source code, passing that value to a general purpose copy routine, which will process the copy table and affect the actual copy.

8.8.5 Copy Table Contents

To use a copy table generated by the linker, you must know the contents of the copy table. This information is included in a run-time-support library header file, cpy_tbl.h, which contains a C source representation of the copy table data structure that is generated by the linker. Example 8-25 shows the copy table header file.

8.8.6 General Purpose Copy Routine

The cpy_tbl.h file in Example 8-25 also contains a prototype for a general-purpose copy routine, copy_in(), which is provided as part of the run-time-support library. The copy_in() routine takes a single argument: the address of a linker-generated copy table. The routine then processes the copy table data object and performs the copy of each object component specified in the copy table.

The copy_in() function definition is provided in the cpy_tbl.c run-time-support source file shown in Example 8-26.

The load (or source) page id and the run (or destination) page id are used to choose which low-level copy routine is called to move a word of data from the load location to the run location. A page id of 0 indicates that the specified address is in program memory, and a page id of 1 indicates that the address is in data memory. The hardware provides special instructions, PREAD and PWRITE, to move code/data into and out of program memory.

8.9.1 The crc_table() Operator

For any section that should be verified with a CRC, the linker command file must be modified to include the crc_table() operator. The specification of a CRC algorithm is optional. The syntax is:

crc_table(user_specified_table_name[, algorithm=xxx])

The linker uses the CRC algorithm from any specification given in a crc_table() operator. If that specification is omitted, the CRC32_PRIME algorithm is used. The linker includes CRC table information in the map file. This includes the CRC value as well as the algorithm used for the calculation.

The CRC table generated for a particular crc_table() instance can be accessed through the table name provided as an argument to the crc_table() operator. The linker creates a symbol with this name and assigns the address of the CRC table as the value of the symbol. The CRC table can then be accessed from the application using the linker-generated symbol.

The crc_table() operator can be applied to an output section, a GROUP, a GROUP member, a UNION, or a UNION member. If applied to a GROUP or UNION, the operator is applied to each member of the GROUP or UNION.

You can include calls in your application to a routine that will verify CRC values for relevant sections. You must provide this routine. See below for more details on the data structures and suggested interface.

8.9.2 Restrictions

It is important to note that the CRC generator used by the linker is parameterized as described in the crc_tbl.h header file (see Example 8-31). Any CRC calculation routine employed outside of the linker must function in the same way to ensure matching CRC values. The linker cannot detect a mismatch in the parameters. To understand these parameters, see A Painless Guide to CRC Error Detection Algorithms by Ross Williams, which is likely located at http://www.ross.net/crc/download/crc_v3.txt.

Only the CRC algorithm names and identifiers specified in crc_tbl.h are supported. All other names and ID values are reserved for future use. Your system may not include built-in hardware that computes all these CRC algorithms. Consult the documentation for your hardware for more detail. The following CRC algorithms are supported:

• CRC8_PRIME
• CRC16_ALT
• CRC16_802_15_4
• CRC_CCITT
• CRC24_FLEXRAY
• CRC32_PRIME
• CRC32_C
• CRC64_ISO

The supported CRC algorithms are specified by published standards, including the Powerline Related Intelligent Metering Evolution (PRIME) standard and IEEE 802.15.4. The Viterbi, Complex Math and CRC Unit (VCU) module available on some C28x devices provides efficient instructions for CRC calculation using these algorithms. You might want to take advantage of the VCU module to compute the CRC at run time. For details, see the VCU module documentation in TMS320x28xx, 28xxx DSP Peripherals Reference Guide (SPRU566).

There are also restrictions which will be enforced by the linker:

• CRC can only be requested at final link time.
• CRC can only be applied to initialized sections.
• CRC can be requested for load addresses only.
• Certain restrictions also apply to CRC table names.

8.9.3 Examples

The crc_table() operator is similar in syntax to the table() operator used for copy tables. A few simple examples of linker command files follow.

Example 8-27 defines a section named “.section_to_be_verified”, which contains the .text data from the a1.obj file. The crc_table() operator requests that the linker compute the CRC value for the .text data and store that value in a table named “my_crc_table_for_a1”. This table will contain all the information needed to invoke a user-supplied CRC calculation routine, and verify that the CRC calculated at run time matches the linker-generated CRC. The table can be accessed from application code using the symbol my_crc_table_for_a1, which should be declared of type “extern CRC_TABLE”. This symbol will be defined by the linker. The application code might resemble the following.

The my_check_CRC() routine is discussed in detail in Section 8.9.4, Example 8-32.

In Example 8-28, the CRC algorithm is specified in the crc_table() operator. The specified algorithm is used to compute the CRC of the text data from b1.obj. The CRC tables generated by the linker are created in the special section .TI.crctab, which can be placed in the same manner as other sections. In this case, the CRC table _my_crc_table_for_b1 is created in section .TI.crctab:_my_crc_table_for_b1, and that section is placed in the CRCMEM memory region.

In Example 8-29 the same identifier, _my_crc_table_for_a1_and_c1, is specified for both a1.obj and c1.obj. The linker creates a single table that contains entries for both text sections. Multiple CRC algorithms can occur in a single table. In this case, _my_crc_table_for_a1_and_c1 contains an entry for the text data from a1.obj using the default CRC algorithm, and an entry for the text data from c1.obj using the CRC16_802_15_4 algorithm. The order of the entries is unspecified.

When the crc_table() operator is applied to a GROUP or a UNION, the linker applies the table specification to the members of the GROUP or UNION.

In Example 8-30 the linker creates two CRC tables, table1 and table2. table1 contains one entry for section1, using algorithm CRC16_ALT. Because both sections are members of the UNION, table2 contains entries for section1 and section2, using algorithm CRC32_PRIME. The order of the entries in table2 is unspecified.

8.9.4 Interface

The CRC generation function uses a mechanism similar to the copy table functionality. Using the syntax shown above in the linker command file allows specification of code/data sections that have CRC values computed and stored in the run time image. This section describes the table data structures created by the linker, and how to access this information from application code.

The CRC tables contain entries as detailed in the run-time-support header file crc_tbl.h, as illustrated in Figure 8-7.

Figure 8-7 CRC_TABLE Conceptual Model

The crc_tbl.h header file is included in Example 8-31. This file specifies the C structures created by the linker to manage CRC information. It also includes the specifications of the supported CRC algorithms. A full discussion of CRC algorithms is beyond the scope of this document, and the interested reader should consult the referenced document for a description of the fields shown in the table. The following fields are relevant to this document.

• Name – text identifier of the algorithm, used by the programmer in the linker command file.
• ID – the numeric identifier of the algorithm, stored by the linker in the crc_alg_ID member of each table entry.
• Order – the number of bits used by the CRC calculation.
• Polynomial – used by the CRC computation engine.
• Initial Value – the initial value given to the CRC computation engine.

In the CRC_TABLE struct, the array recs[1] is dynamically sized by the linker to accommodate the number of records contained in the table (num_recs). A user-supplied routine to verify CRC values should take a table name and check the CRC values for all entries in the table. An outline of such a routine is shown in Example 8-32.

8.9.5 A Special Note Regarding 16-Bit char

C2000 is a 16-bit word addressable target, which means that its char data type is 16 bits. However, CRC algorithms operate on 8-bit units, which we shall call "octets". When computing a CRC on a C2000 section, the data cannot be fed to the CRC loop char-by-char, it must be fed octet-by-octet.

The data needs to be fed to the CRC in the order it would if the C2000 were a 8-bit machine, so we need to consider which of the two octets in the char to feed first. C2000 is a little-endian machine, but it does not make sense to talk about the endianness of the bits in an indivisible unit such as char. By convention, we consider the data in a char to be stored least-significant octet first, then most-significant octet.

Abstractly, the CRC algorithm computes the CRC bit-by-bit in the order the bits appear in the data. For a machine with 8-bit chars, this order is considered to proceed from the MSB through the LSB of each byte starting with byte 0. However, for C2000, the CRC starts with the MSB through LSB of the LEAST significant octet of byte 0, then the MSB through LSB of the MOST significant octet of byte 0, and so on for the rest of the bytes.

Figure 8-8 CRC Data Flow Example

8.11.1 Run-Time Initialization

All C/C++ programs must be linked with code to initialize and execute the program, called a bootstrap routine, also known as the boot.obj object module. The symbol _c_int00 is defined as the program entry point and is the start of the C boot routine in boot.obj; referencing _c_int00 ensures that boot.obj is automatically linked in from the run-time-support library. When a program begins running, it executes boot.obj first. The boot.obj symbol contains code and data for initializing the run-time environment and performs the following tasks:

• Sets up the system stack and configuration registers
• Processes the run-time .cinit initialization table and autoinitializes global variables (when the linker is invoked with the --rom_model option)
• Disables interrupts and calls _main

The run-time-support object libraries contain boot.obj. You can:

• Use the archiver to extract boot.obj from the library and then link the module in directly.
• Include the appropriate run-time-support library as an input file (the linker automatically extracts boot.obj when you use the --ram_model or --rom_model option).

8.11.2 Object Libraries and Run-Time Support

The TMS320C28x Optimizing C/C++ Compiler User's Guide describes additional run-time-support functions that are included in rts.src. If your program uses any of these functions, you must link the appropriate run-time-support library with your object files.

You can also create your own object libraries and link them. The linker includes and links only those library members that resolve undefined references.

8.11.3 Setting the Size of the Stack and Heap Sections

The C/C++ language uses two uninitialized sections called .esysmem and .stack for the memory pool used by the malloc( ) functions and the run-time stacks, respectively. You can set the size of these by using the --heap_size or --stack_size option and specifying the size of the section as a 4-byte constant immediately after the option. If the options are not used, the default size of the heap is 1K words and the default size of the stack is 1K words.

See Section 8.4.12 for setting heap sizes andSection 8.4.26 for setting stack sizes.

8.11.4 Initializing and AutoInitialzing Variables at Run Time

Autoinitializing variables at run time is the default method of autoinitialization. To use this method, invoke the linker with the --rom_model option. See Section 3.3.2.1 for details.

Initialization of variables at load time enhances performance by reducing boot time and by saving the memory used by the initialization tables. To use this method, invoke the linker with the --ram_model option. See Section 3.3.2.2 for details.

See Section 3.3.2.3 for information about the steps that are performed when you invoke the linker with the --ram_model or --rom_model option.