This chapter contains the following sections:
Overview
Invocation
Detailed Description of Locator Options
Format Suboptions
Calling the Locator via the Control Program
Locator Labels
Locator Labels References
This chapter describes the TriCore locator.
The task of the locator is to locate a .out file, made by lktri, to absolute addresses. In an embedded environment an accurate description of available memory and information about controlling the behavior of the locator is crucial for a successful application. For example, it may be necessary to port applications to processors with different memory configurations, or it may be necessary to tune the location of sections to take full advantage of fast memory chips. To perform its task the locator needs a description of the derivative of the TriCore used. The locator uses a special language for this description: DELFEE, which stands for DEscriptive Language For Embedded Environments. This steering language is used in a special file, which is called the description file. See Appendix F DEscriptive Language For Embedded Environments for detailed information.
The description file is an optional parameter in the locator invocation. Without a description file name on the command line, or without the -d option, the locator searches the file tri.dsc in the current directory or in directory etc in the TriCore product tree.
Figure 10-1: Locator
The invocation of the locator is:
When you use a UNIX shell (C-shell, Bourne shell), options containing special characters (such as '( )' ) must be enclosed with "". The invocations for UNIX and DOS are the same, except for the -? option in the C-shell:
Options may appear in any order. Options start with a '-'. They may be combined: -eM is equal to -e -M. Options that require a filename or a string may be separated by a space or not: -oname is equal to -o name. file may be any file with a .out or .dsc extension.
The locator recognizes the following options:
Option | Description | ||||||||||||||||||||||||||||
-H or -? | Display invocation syntax | ||||||||||||||||||||||||||||
-M[n] | Produce a locate map file (.map) with maximum width n (n > 132) | ||||||||||||||||||||||||||||
-N | Generate external part | ||||||||||||||||||||||||||||
-Sspace |
Generate specific space
-V |
Display version header only |
-WAE |
Treat warning messages as errors |
-c |
Don't generate ROM copy for re-initializing data memory |
-dfile |
Read description file information from file,
'-' means stdin |
-e |
Clean up if erroneous result |
-emmacro[=def] |
Define preprocessor macro |
-err |
Redirect error messages (.elc) |
-ffile |
Read command line information from file,
'-' means stdin |
-fformat |
Specify output format |
-o filename |
Specify name of output file |
-p |
Make a proposal for a software part on stdout
|
-s |
Strip debug info from the input |
-v |
Verbose option. Print name of each file as it is processed |
-wn |
Suppress messages above warning level n. | |
Table 10-1: Options summary
With options that can be set from within EDE, you will
find a mouse icon that describes the corresponding action.
-?
-H
Display an explanation of options at stdout.
lctri -?
Select the | Configure Selected CPU... menu item. Disable the Initialized and cleared C variables check box in the Startup
tab.
-c
Do not generate ROM-copy for re-initializing data memory.
Normally, when running an application from an EPROM, the startup code will take care of clearing and initializing RAM data memory by keeping a copy of the initialized data variables in ROM. During program startup this ROM-copy is copied from program memory to data memory, thus assuring the program will have the same initial values on every program restart.
In some special situations you can save target memory usage by not generating a ROM copy of the initialized data variables in program memory. When you use the -c option, the program will be initialized with all required data values directly (this also includes the clearing and filling of data sections). The program initialization is done during downloading of the program. So, when loading the program, no additional copy action is required.
The draw back of using this option is that when you want to restart the program with the same initial values you have to download the whole program again, because a ROM-copy with the initial values is not available. Also, when the program runs from an EPROM, on program restart no attempt is made to clear or fill data sections, which was normally done at startup. So, a program depending on cleared or initialized RAM variables will fail then.
The -c option is of great use when loading the progam from a host processor, because the program code and data can be loaded into a target system with the exact required memory space to run correctly (no extra space for copies in ROM is required).
Select the | Linker/Locator Options... menu item. Enter the basename of the description file in the
Locator control file (.dsc) field in the Locator tab.
-d file
A filename to read description file information from. If file is a '-', the information is read from standard input.
Read description file information from file instead of a .dsc file.
To read description file information from file tri.dsc, enter:
lctri -dtri.dsc test.out
EDE always removes the output files on errors.
-e
Remove all locate products such as temporary files, the resulting output file and the map file, in case an error occurred.
lctri -e test.out
-emmacro[=def]
The macro you want to define and optionally its definition.
Define macro to the preprocessor, as in #define. If def is not given ('=' is absent), '1' is assumed. Any number of symbols can be defined. The definition can be tested by the preprocessor with #if, #ifdef and #ifndef, for conditional locating. If the command line is getting longer than the limit of the operating system used, the -f option is needed.
lctri myproject.out -o myproject.abs -emEDE=\"myproject.i\" -M
In EDE this option is not so useful. If you would use
this option you would not see the error messages in the
Build tab.
-err
The locator redirects error messages to a file with the same basename as the output file and the extension .elc. The default filename is a.elc.
To write errors to the file a.elc instead of stderr, enter:
lctri -err test.out
To write errors to the file test.elc instead of stderr, enter:
lctri -err test.out -otest.abs
-f file
A filename for command line processing. If file is a '-', the information is read from standard input. You need to provide the EOF code to close stdin (usually Ctrl-Z or Ctrl-D on UNIX).
file must not be a number
in the range 0-4, because these numbers are used to specify an output format.
Use file for command line processing. To get around the limits on the size of the command line, it is possible to use command files. These command files contain the options that could not be part of the real command line. Command files can also be generated on the fly, for example by the make utility.
More than one -f option is allowed.
Some simple rules apply to the format of the command file:
1. It is possible to have multiple arguments on the same line in the command file.
2. To include whitespace in the argument, surround the argument with either single or double quotes.
3. If single or double quotes are to be used inside a quoted argument, we have to go by the following rules:
a. If the embedded quotes are only single or double quotes, use the opposite quote around the argument. Thus, if a argument should contain a double quote, surround the argument with single quotes.
b. If both types of quotes are used, we have to split the argument in such a way that each embedded quote is surrounded by the opposite type of quote.
Example:
"This has a single quote ' embedded"
or
'This has a double quote " embedded'
or
'This has a double quote " and \ a single quote '"' embedded"
4. Some operating systems impose limits on the length of lines within a text file. To circumvent this limitation it is possible to use continuation lines. These lines end with a backslash and newline. In a quoted argument, continuation lines will be appended without stripping any whitespace on the next line. For non-quoted arguments, all whitespace on the next line will be stripped.
Example:
"This is a continuation \ line" -> "This is a continuation line" control(file1(mode,type),\ file2(type)) -> control(file1(mode,type),file2(type))
5. It is possible to nest command line files up to 25 levels.
Suppose the file mycmds contains the following line:
-err test.out
The command line can now be:
lctri -f mycmds
Select the | Linker/Locator Options... menu item. Choose an Output Format option from the Format tab.
-fformat
format can be one of the following output formats:
Specify an output format. The default output format is IEEE Std. 695 (-f1), which can directly be used by the CrossView Pro debugger. The other output formats can be used for loading into a PROM-programmer.
Section Format Suboptions.,
Appendix H,
IEEE-695 Object Format,
Appendix I,
Motorola S-Records,
Appendix J,
Intel Hex Records.
Select the | Linker/Locator Options... menu item. Enable the Produce a memory map file (.map) check box in the Locator tab.
-M[n]
Optionally the maximum line width (n > 132). If you omit the width, the default is 132 characters.
Produce a locate map (.map). If no output filename is specified the default name is a.map. The map file shows the absolute position of each section. External symbols are listed with their absolute address, both sorted on address and sorted on symbol.
To create the map file a.map, enter:
lctri -M test.out
Select the | Linker/Locator Options... menu item. Add the option to the Additional options field in the Locator tab.
-N
Generate external part. The external part contains all global symbol references.
Select the | Linker/Locator Options... menu item. Add the option to the Additional options field in the Locator tab.
-ofilename
An output filename.
The default filename depends on the output format specified:
Use filename as output filename of the locator.
To create the output file test.abs instead of a.abs, enter:
lctri test.out -otest.abs
Select the | Linker/Locator Options... menu item. Add the option to the Additional options field in the Locator tab.
-p
Make a proposal for a software part in a description file on standard output.
Select the | Linker/Locator Options... menu item. Add the option to the Additional options field in the Locator tab.
-Sspace
The name of a space from a .dsc file.
With this option you can generate a specific output file for a specified space instead of generating an output file containing all spaces.
Select the | Linker/Locator Options... menu item. Disable the Include symbolic debug information check box in the Locator tab.
-s
Strip debug information from the input file.
-V
With this option you can display the version header of the locator. This option must be the only argument of lctri. Other options are ignored. The locator exits after displaying the version header.
lctri -V
TASKING TriCore locator vx.yrz Build nnn Copyright 1996-year Altium BV Serial# 00000000
Select the | Linker/Locator Options... menu item. Add the option to the Additional options field in the Locator tab.
-v
Verbose option. Print the name of each file as it is processed.
lctri -v test.out
lctri V001 (1): Output format: IEEE 695 lctri V004 (1): Warning level 8 lctri V007 (1): Found file <tri.dsc> via path \ctri\etc\tri.dsc lctri V002 (1): Starting pass 1 lctri V000 (1): File currently in progress: test.out
Select the | Linker/Locator Options... menu item. Select a warning level from the Suppress warning messages above list box in the Locator tab.
-w level
A warning level between 0 and 9 (inclusive).
-w8
Give a warning level between 0 and 9 (inclusive). All warnings with a level above level are suppressed. The level of a message is printed between parentheses after the warning number. If you do not use the -w option, the default warning level is 8.
To suppresses warnings above level 5, enter:
lctri -w5 test.out
Using the control program:
cctri -Wlc-w5 test.out
Select the | Linker/Locator Options... menu item. Enable the Treat warnings as if they were errors check box in the Locator
tab.
-WAE
Treat warning messages as errors. This also affects the return value of the application when only errors occur. A build process will now stop when warnings occur.
lctri -WAE test.out
The layout of the -fformat switch as shown in the previous section has some extra capabilities. The general form of format is:
The first character is a single digit known as the format specifier. This format specifier can be followed by one or more format_options. These format_options are in principle output format dependent. Currently the following format_options are known:
Suboption | Description | Valid Formats |
a | Sort addresses in ascending order | 2 |
bsize | Specify the output buffer size | 1, 2, 3 |
c | Generate file for each chip | 3 |
s | Emit start address record | 3 |
S1, S2, S3 | Force Motorola S1, S2 or S3 records | 2 |
u | Unsorted addresses (default) | 2 |
Table 10-2: Format suboptions
For format 2 and 3 the buffer size sets the length of an output record exclusive record code, address and checksum. The following Intel Hex record has a buffer size of 32 bytes:
:20004000 ( Record code and address ) 000028A101002925FBFF6015FFFF6B25DDFF001000000000000020A101002925 (32 data bytes) 8F ( Checksum )
For format 1, size is the maximum number of bytes in one LD command.
Examples:
To ease the locating process a set of locator controls has been developed. Instead of manually adapting the DELFEE files (tri.cpu, tri.def and tri.dsc), you can now write a simple and quite straightforward locator control file. The locator control file is passed to the locator on the command line.
When using EDE, the locating process is even simpler,
since EDE generates a locator control file for you. This control file, project.i, is the result of your (graphical) selections in the
| Linker/Locator options... tabs.
The locator still uses the DELFEE files. However, the contents of the DELFEE files are now controlled by the new locator control file (tri.i). You can, of course, still inspect (and even edit) the files tri.cpu, tri.def and tri.dsc, but it is recommended not to touch them. You can specify the locating behavior and your memory configuration (such as ROM and RAM areas) using EDE.
The locator supports the following controls (which are implemented as C language macros):
Locator control | Default | Description |
RESET | 0x30000000 | Reset start address |
USTACK | 12K | User stack size |
ISTACK | 4K | Interrupt stack size |
HEAP | 32K | Heap size |
CSA | 256 | Number of context blocks |
XVWBUF | 32 | CrossView Pro buffer size |
RAM(name,start,end) | -- | Define RAM memory area |
ROM(name,start,end) | -- | Define ROM memory area |
RESERVED(start,end) | -- | Exclude memory range from section allocation |
ROM_LINEAR(name [addr=address] ) | -- | Specify section with name must be located at address addr or before/after another ROM_LINEAR control. |
ROM_ABS24(name [addr=address] ) | -- | Specify section with name must be located at address addr or before/after another ROM_ABS24 control. |
ROM_ABS18(name [addr=address] ) | -- | Specify section with name must be located at address addr or before/after another ROM_ABS18 control. |
RAM_LINEAR(name [addr=address] ) | -- | Specify section with name must be located at address addr or before/after another RAM_LINEAR control. |
RAM_ABS18(name [addr=address] ) | -- | Specify section with name must be located at address addr or before/after another RAM_ABS18 control. |
Table 10-3: Locator controls
Below is an example locator control file.
#define RESET 0x30000000 /* reset start address */ #define USTACK 12k /* user stack size */ #define ISTACK 4k /* interrupt stack size */ #define HEAP 32k /* heap size */ #define CSA 256 /* number of context blocks */ #define XVWBUF 32 /* size of CrossView Pro buffer */ RAM( sdata , 0x00000000 , 0x000007ff ) // 2k RAM( ddata , 0x10000000 , 0x1000ffff ) // 64k ROM( dcode , 0x20000000 , 0x2001ffff ) // 128k ROM( scode , 0x28000000 , 0x280003ff ) // 1k ROM( boot , 0xd0000000 , 0xdfffffff ) ROM( fpi1 , 0x2ffeff00 , 0x7fffffff ) RAM( fpi2 , 0x80000000 , 0xcfffffff ) // RESERVED( 0x28000000, 0x280003ff ) // ROM_ABS24( code.cstart )
EDE generates the locator control file and the proper invocation for you.
If you do not use EDE, you must create a locator control file yourself (for example, myproject.i) and specify it on the command line. The default name is tri.i. For example:
lctri myproject.out -o myproject.abs -emEDE=\"myproject.i\" -M
It is recommended to call the locator via the control program cctri. The control program translates certain options for the locator (e.g., -srec to -f2). Other options (such as -M) are passed directly to the locator. Typical, you can use the control program to get an .abs file directly from .c, .src, .asm or .obj files. The invocation:
cctri -M -g addone.src demo.c -o demo.abs tri.dsc
builds an absolute demo file called demo.abs ready for running via the CrossView Pro debugger.
The locator produces an absolute file and, if requested, a map file and/or an error file. The output file is absolute and in Intel Hex format, Motorola S-record format or in IEEE-695 format, depending on the usage of the -f option. The default output name is a.hex, a.sre or a.abs, respectively.
The map file (-M option) always has the same basename as the output object file, with an extension .map. The map file shows the absolute position of each section. External symbols are listed with their absolute address, both sorted on address and sorted on symbol.
The error output file (-err option) has the same name as the object output file, but with extension .elc. Errors occurred before the -err option is evaluated are printed on stderr.
There are four kinds of messages: fatal messages, error messages, warning messages and verbose messages. Fatal messages are generated if the locator is not able to continue with its task due to the severity of the error. In those situations, the exit code will be 2. Error messages will be reported if an error occurred, not fatal for the locator. However, the output of the locator is not usable. The exit code in case of one or more error messages will be 1. Warning messages are generated if the locator detects potential errors, but the locator is unable to judge those errors. The exit code will be 0 in this case, indicating a usable .abs file. Of course, if the locator reports no messages, the exit code is also 0.
Each locator message has a built-in warning level. With option -wx it is possible to suppress messages with a warning level above x.
Verbose messages are generated only if the verbose option (-v) is on. They report the progress of the locate process.
Locator messages have the following layout:
TASKING TriCore locator vx.yrz Build nnn Copyright 1996-year Altium BV Serial# 00000000 lctri W112 (3) calc.out: Copy table not referenced, initial data is not copied
The first line shows the locator banner. (Suppressed if the locator invocation is done by the control program.) The second line shows the warning. The number after the warning number shows the warning level.
One of the actions with the process initialization is copy data from ROM to RAM, and initialize memory with the CLEAR attribute. The locator generates a copy table for each process. The copy table can be referenced by label _lc_cp. One entry in the copy table has the following layout:
typedef struct cp_entry { int cp_actions; /* 4 bytes */ unsigned char *cp_destin; /* 4 byte address */ unsigned char *cp_source; /* 4 byte address */ int cp_length; /* 4 byte length */ } cp_entry_t;
The first member, cp_actions, defines what action you must perform with the current entry. Actions are organized as a bit per action:
value 0 Reached end of the table.
CP_COPY (value 1) Copy from cp_source to cp_destin over cp_length bytes.
CP_BSS (value 2) Clear memory from cp_destin over cp_length bytes.
Table entries are generated as follows:
If there is nothing to do (no sections to clear and no data to copy) the copy table has only one action entry with value zero.
At C level, the copy table can be declared as:
cpt_t _lc_cp;
And accessing a member of entry X becomes:
_lc_cp[ X ].cp_actions;
If label _lc_cp is not used, the table is not generated.
The locator assigns addresses to the following labels when they are referenced:
_lc_cp : Start of copy table The copy table gives the source and destination addresses of sections to be copied. This table will be generated by the locator only if this label is used.
_lc_bs : Begin of stack space (using keyword stack).
_lc_es : End of stack space.
_lc_b_name : Begin of section name.
_lc_e_name : End of section name.
_lc_u_name : User defined label. The label must be defined in the description file. For example:
label mylab;
_lc_ub_name : Begin of user defined label. The label must be defined in the description file. For example:
label mybuffer length=100;
_lc_ue_name : End of user defined label.
This section contains a description of all locator labels. Locator labels are labels starting with _lc_. They are ignored by the linker and resolved at locate time. Some of these labels are real labels at the beginning or the end of a section. Other labels have a second function, these labels are used to address locator generated data. The data is only generated if the label is used.
Because labels that start with _lc_ are treated differently in both the linker and the locator, you can only use this type of labels as references, not as definitions.
extern unsigned char _lc_b_section[
];
extern unsigned char _lc_e_section[
];
You can use the general locator labels _lc_b_section and _lc_e_section to obtain the addresses of section section in a program. The b version points to the start of the section, while the e version points to its end.
You can replace the dot before a section name by an underscore ( _ ), making it possible to access these labels from 'C'. This convention introduces a possible name conflict. If, for example, both sections .text and _text exist, the general label _lc_b__text is set to the start of _text. The label for section .text is only usable at assembly level with its real name. Of course, you should avoid such a conflict by not using section names with a leading underscore.
printf( "Text size is 0x%x\n", _lc_e__text - _lc_b__text );
extern unsigned char _lc_bh[ ];
extern unsigned char _lc_eh[ ];
All locator h labels are related to the heap. You can allocate a heap by defining it in a cluster description. See also the Delfee keyword heap.
_lc_bh is a label at the begin of the heap. At 'C' level _lc_bh represent the heap. The label is defined as a char array, but an array of any basic type will do. _lc_eh represents the end of the heap.
Heap definition:
block total_range { . . cluster ram { amode data { heap length = 200; . } } . }
Sbrk code:
extern unsigned char _lc_bh[ ]; extern unsigned char _lc_eh[ ]; static char * sbrk( long length ) { . . if ( (lastmem + length) > _lc_eh ) { return (char *) -1; /* overflow */ }
extern unsigned char _lc_bs[ ];
extern unsigned char _lc_es[ ];
All locator s labels are related to the stack. You can allocate a stack by defining it in a cluster description. See also the Delfee keyword stack.
_lc_bs is a label at the begin of the stack. At 'C' level _lc_bs represent the stack. The label is defined as a char array, but an array of any basic type will do. _lc_es represents the end of the stack. Because _lc_es is on a higher address than _lc_bs and because the stack for the TriCore grows to lower addresses, the stack actually starts at the label _lc_es and ends at _lc_bs.
Stack definition:
block total_range { cluster ram { amode data { stack length = 100; . } } }
Stack initialization:
_START: LD SP,#_lc_es ; set stack pointer to ; begin of stack space
extern char *_lc_cp;
The copy table is generated per process. Each entry in this table represents a copy or clearing action. Entries for the table are automatically generated by the locator for:
- All sections with attribute b, which must be cleared at startup time : a clearing action.
- All sections with attribute i, which must be copied from rom to ram at program startup: a copy action
The layout of the copy table is described in 10.7 , Copy Table. Type cpt_t is defined in locate.h.
extern int _lc_u_identifier[ ];
This locator label can be defined by the user by means of the Delfee keyword label. This label must be defined in the Delfee file without the prefix _lc_u_. From assembly the label can be referenced with the prefix _lc_u_,.
In description file:
block total_range { cluster ram { amode data { label bstart; section text; label bend; } } . . . }
From C:
#include <stdio.h> extern int _lc_u_bstart[]; extern int _lc_u_bend[]; int main() { printf( "Size of cluster ram is %d\n", (long)_lc_u_bend - (long)_lc_u_bstart ); }
extern int _lc_ub_identifier[ ];
extern int _lc_ue_identifier[ ];
These locator labels can be defined by the user by means of the Delfee keywords reserved label=. The locator labels specify the begin and end of a reserved area. The identifier is the name for the reserved area and must be defined in the Delfee file without the prefix _lc_ub_ or _lc_ue_. From assembly the labels can be referenced with the prefix _lc_ub_ and _lc_ue_,.
In description file:
block total_range { cluster ram { attribute w; amode data { section selection=w; reserved label=xvwbuffer length=0x10; // Start address of reserved area is // label _lc_ub_xvwbuffer // End address of reserved area is // label _lc_ue_xvwbuffer } } }
From C:
#include <stdio.h> extern int _lc_ub_xvwbuffer[]; extern int _lc_ue_xvwbuffer[]; int main() { printf( "Size of reserved area xvwbuffer is %d\n", (long)_lc_ue_xvwbuffer - (long)_lc_ub_xvwbuffer ); }