C2000 C/C++ CODE GENERATION TOOLS New Linker Release Notes 6.2.7 June 2014 =============================================================================== Contents =============================================================================== 1. Replacement COFF Linker 2. New Features 2.1 Linker Command File Preprocessing 2.2 Controlling Linker Diagnostics 2.3 Automatic Run-Time-Support Library Selection 2.4 Scan libraries for duplicate symbol definitions 2.5 Named UNION/GROUP support 2.6 Source Level Diagnostics 2.7 Symbol mapping 2.8 Wildcards in File, Section, and Symbol Patterns 2.9 Managing Map File Content ------------------------------------------------------------------------------- 1. Replacement COFF Linker ------------------------------------------------------------------------------- Starting with version 5.1.0B1, the toolset contains a new COFF linker. This COFF linker executable is named lnk2000 and replaces the previous version of the linker. The new COFF linker is a drop in replacement COFF linker. It supports all the current linker features and behaviors with the following exceptions: 1. The new COFF linker may not duplicate the exact allocation algorithm of the old linker. That is, use of the new linker may result in a slightly different input section layout into the memory compared to the old linker. Also, the --default_order option is not supported in the new linker. This option was added to the current COFF linker to support legacy section allocation behavior. The new COFF linker does not support this option. 2. The new linker uses most restrictive section specifier to match input sections, whereas the old linker uses the section specifier order in the linker command file. For example, consider the following linker command file: SECTIONS { .text: { *(.text) } > ROM .criticl_text: { critical.obj(.text) } > FASTROM } The new linker includes the input section critical.obj(.text) in the output section .criticl_text. The remaining .text input sections are placed in the .text output section. The old linker includes all .text sections in the output section .text. The output section .criticl_text becomes empty in this case. Use the new linker option --match_first_section_spec=on to get the old linker behavior. 3. During our alpha testing of the new linker for C6x, we have seen cases of users relying on undocumented old linker behavior that the new linker did not mimic. For all such cases seen so far, we determined that it made sense to mimic the old linker behavior, and have updated the new linker. There is a possibility that we might find similar issues in the future. We will address these issues by either updating the new linker behavior or suggesting an appropriate workaround. 4. The new linker supports a sophisticated diagnostic control feature. As an improvement, the diagnostics format and wording are different in most cases. If user is currently using scripts to parse the linker diagnostics, they may need to update the scripts to comprehend the changed format. The new diagnostic control makes it easy to grep on diagnostic id. See 2.2 for more details. ------------------------------------------------------------------------------- 2) New Features ------------------------------------------------------------------------------- The new COFF linker has the following new features. These features are NOT supported in the 5.0.x or older COFF linkers. 2.1 Linker Command File Preprocessing ------------------------------------- The linker now preprocesses linker command files using a standard C preprocessor. This means command files may contain the well-known preprocessing directives such as #define, #include, and #if/#endif. Three new linker options control the preprocessor. They are: --disable_pp - disables preprocessing for command files --defineNAME[=val] - predefine NAME as a preprocessor macro --undefineNAME - remove the macro NAME The shell also has --define and --undefine options with the same meaning. However, the linker options are distinct; only --define/--undefine following -z are passed to the linker. For example: cl2000 --define FOO=1 main.c -z --define BAR=2 lnk.cmd 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 (i.e. macros defined in the parent are visible in the child). However, when a command file is invoked other than via #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: --define GLOBAL #define LOCAL #include "incfile.cmd" /* sees GLOBAL and LOCAL */ nestfile.cmd /* only sees GLOBAL */ 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: --define MYSYM=123 --undefine MYSYM /* expands to --undefine 123 (!) */ --undefine "MYSYM" /* ahh, that's better */ 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 "quotes" (rather than ), in the directory of the current file 2. In the list of directories specified with -I options or environment variables There are two exceptions: relative pathnames (e.g. "../name") always search the current directory; and absolute pathnames (e.g. "/usr/tools/name") bypass search paths entirely. The linker has the standard built-in definitions for the macros __FILE__, __DATE__, and __TIME__. It does not, however, have the compiler specific options for the target (e.g. __TMS320C2000__), version (__TI_COMPILER_VERSION__), runtime model, and so on. 2.2 Controlling Linker Diagnostics ---------------------------------- The new COFF linker provides diagnostic options to control the linker generated diagnostics. This support is an extension of the current support to control compiler diagnostics as documented in the compiler user guide. The following compiler options also affect the linker diagnostics now. These options should be specified before the -z option. --diag_error=num Categorizes the diagnostic identified by num as an error. To determine the numeric identifier of a diagnostic message, use the --display_error_number option first in a separate compile. Then use --diag_error=num to recategorize the diagnostic as an error. You can only alter the severity of discretionary diagnostics. --diag_remark=num Categorizes the diagnostic identified by num as a remark. To determine the numeric identifier of a diagnostic message, use the --display_error_number option first in a separate compile. Then use --diag_remark=num to recategorize the diagnostic as a remark. You can only alter the severity of discretionary diagnostics. --diag_suppress=num Suppresses the diagnostic identified by num. To determine the numeric identifier of a diagnostic message, use the --display_error_number option first in a separate compile. Then use --diag_suppress=num to suppress the diagnostic. You can only suppress discretionary diagnostics. --diag_warning=num Categorizes the diagnostic identified by num as a warning. To determine the numeric identifier of a diagnostic message, use the --display_error_number option first in a separate compile. Then use --diag_warning=num to recategorize the diagnostic as a warning. You can only alter the severity of discretionary diagnostics. --display_error_number Displays a diagnostic's numeric identifier along with its text. Use this option in determining which arguments you need to supply to the diagnostic suppression options (--diag_suppress, --diag_error, --diag_remark, and --diag_warning). This option also indicates whether a diagnostic is discretionary. A discretionary diagnostic is one whose severity can be overridden. A discretionary diagnostic includes the suffix -D; otherwise, no suffix is present. --issue_remarks Issues remarks (non-serious warnings), which are suppressed by default. --no_warnings Suppresses warning diagnostics (errors are still issued). --set_error_limit=num Sets the error limit to num, which can be any decimal value. The compiler abandons compiling after this number of errors. (The default is 100.) --verbose_diagnostics Provides verbose diagnostics that display the original source with line-wrap and indicate the position of the error in the source line. --no_demangle By default, the linker uses demangled symbol names in diagnostics. For example, undefined first referenced symbol in file --------- ---------------- ANewClass::getValue() test.obj When the --no_demangle option is used, the mangled name is used by the linker: undefined first referenced symbol in file --------- ---------------- _ZN9ANewClass8getValueEv test.obj 2.3 Automatic Run-Time-Support Library Selection ------------------------------------------------ If --rom_model or --ram_model is specified during the link step, and the entry point for the program (normally c_int00) is not resolved by any specified object file or library, the link step will attempt to automatically include the best compatible run-time-support library for your program. The chosen run-time-support library will be linked in as if it was specified with the --library option last on the command line. Alternatively, you can always force the link step 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 link step command file. If the --issue_remarks option is specified before the --run_linker option during the link step, a remark will be 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 link step command files when necessary. Example: cl2000 --v --issue_remarks main.obj --run_linker --rom_model lnk2000 --"tm_feedback=/tmp/10266lypVdg" hi.obj --rom_model --issue_remarks remark: automatic RTS selection: linking in index library "libc.a" remark: automatic RTS selection: linking in "rts2700.lib" in place of index library "libc.a" 2.4 Scan libraries for duplicate symbol definitions --------------------------------------------------- The new option --scan_libraries (-scanlibs) will cause the linker to scan all libraries during a link to look for duplicate symbol definitions to those symbols that are actually included in a link. The scan will not consider absolute symbols or symbols defined in COMDAT sections. The option will help determine those symbols that were actually chosen by the linker over other existing definitions of the same symbol in a library. This feature can be used to check aginst unintended resolution of a symbol reference to a definition when multilple definitions are available in the libraries. 2.5 Named UNION/GROUP support ----------------------------- The linker now allows user to specify an optional name for UNIONs and GROUPs specifications in the linker command file. The name should be specified after the GROUP/UNION keyword: GROUP (BSS_SYSMEM_STACK_GROUP) { .bss : {} .sysmem : {} .stack : {} } load=D_MEM, run=D_MEM The user-given name is used in diagnostics for easy identification of the problem LCF area. For example, the above GROUP specification generates the following diagnostic: warning: LOAD placement ignored for "BSS_SYSMEM_STACK_GROUP": object is uninitialized UNION (PINIT_CINIT_UNION) { .const : {} load=D_MEM, table(table1) .pinit : {} load=D_MEM, table(table1) } run=P_MEM warning: table(table1) operator ignored: table(table1) has already been applied to a section in the UNION "PINIT_CINIT_UNION" in which ".pinit" is a descendant 2.6 Source Level Diagnostics ---------------------------- When reporting diagnostics that relate to section offsets in the object file, the linker uses any available debug information to provide the file name and the line number of the corresponding source code. For example, the test below contains a call to a function that is out of range, causing a relocation overflow: cl2000 --verbose_diagnostics -g -z foo.obj bar.obj "foo.c", line 8: warning: relocation from function "main" to symbol "_some_func" overflowed; the 29-bit relocated address 0x12345678 is too large to encode in the 24-bit field (type = 'R_REL24' (5), file = "foo.obj", offset = 0x00000003, section = ".text") some_func(); ^ 2.7 Symbol mapping ------------------ The following option was added to support symbol mapping. --symbol_map=refname=defname Symbol mapping allows a symbol reference to be resolved by a symbol with different name. This enables 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. For example, the option --symbol_map='foo=foo_patch' makes the linker resolve any references to foo by the definition foo_patch. 2.8 Wildcards in File, Section, and Symbol Patterns --------------------------------------------------- The linker allows file, section, and symbol names to be specified using '*' and '?' wild cards. This can make it easier to handle related objects, provided they follow a suitable naming convention. Examples: mp3*.obj /* matches anything .obj starting with "mp3" */ task?.o* /* matches "task1.o", "task2.obj", "taskX.o28", etc */ SECTIONS { .fast_code: { *.obj(*fast*) } > FAST_MEM .vectors : { vectors.obj(.vector:part1:*) > 0xFFFFFF00 .str_code : { rts*.lib(.text) } > S1ROM } 2.9 Managing Map File Content ----------------------------- The following option was added to assist with managing the content of a linker-generated map files: --mapfile_contents=filter[,filter] When the '-m' option is specified to the linker, the linker will produce 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 new '--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 linker (lnk2000) command line (or after the '-z' option on the cl2000 command line), you will see the following help screen: 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. The following attributes are available: copytables: copy tables (default: on) entry: entry point (default: on) load_addr: display load addresses (default: off) memory: memory ranges (default: on) sections: sections (default: on) sym_defs: defined symbols per file (default: off) sym_name: symbols sorted by name (default: on) sym_runaddr: symbols sorted by run address (default: on) all: enables all attributes none: disables all attributes Examples: --mapfile_contents=copytables,noentry --mapfile_contents=all,nocopytables --mapfile_contents=none,entry By default, those sections that are currently included in the map file when the '-m' option is specified will be included. The filters specified in the --mapfile_contents options will be 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', will then enable information about entry points to be included in the generated map file. That is, when '--mapfile_contents=none,entry' is specified, the map file will contain *only* information about entry points. There are two new filters included with the --mapfile_contents option, 'load_addr' and 'sym_defs'. These are both disabled by default. If you turn on the 'load_addr' filter, the map file will include 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). The 'sym_defs' filter can be used to include information about all static and global symbols defined in an application on a file by file basis. You may find it useful to replace the 'sym_name' and 'sym_runaddr' sections of the map file with the 'sym_defs' section by specifying the following --mapfile_contents option: --mapfile_contents=nosym_name,nosym_runaddr,sym_defs