11 LOCATOR

This chapter contains the following sections:

Overview

Invocation
Detailed Description of Locator Options
Format Suboptions

Getting Started

Locator Target Board Support

Force Const Sections

Calling the Locator via the Control Program

Locator Output

Locator Messages

Address Space

Locator Labels
Locator Labels References

11.1 Overview

This chapter describes the locator and its control language for the DSP5600x (lc56) and DSP563xx/DSP566xx (lc563). lc563 is used to describe all three locators, unless explicitly stated otherwise.

The task of the locator is to locate a .out file, made by lk563, 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 DSP56xxx used. The locator uses a special language for this description: DELFEE, which stands for DEscriptive Language For Embedded Environments. This control language is used in a special file, which is called the description file. See Appendix G 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 def_targ.dsc in the current directory or in directory etc in the product tree.

Figure 11-1: Locator

11.2 Invocation

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 PC 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)
-Sspace Generate specific space
-V Display version header only
-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
-r Romable application
-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 11-1: Options summary

11.2.1 Detailed Description of Locator Options

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

-?/-H

Option:

-?
-H

Description:

Display an explanation of options at stdout.

Example:

lc563  -?

-c

Option:

Select the Project | Project Options... menu item. Expand the Linker/Locator entry and select Locator Miscellaneous.
Disable the Generate copy table for re-initializing data memory check box.

-c

Description:

Do not generate ROM-copy for re-initializing data memory. In some special situations target memory usage can be minimized by not generating a ROM copy of the initialized data variables in program memory. The drawback of using this option is that program initialization is done during object image loading. So, restarting the program requires downloading the whole program again. Also, when the program runs from an EPROM, no attempt is made to clear or fill data sections, so a program depending on cleared or initialized RAM variables will fail then.

Here is a C example to demonstrate this:

The flag global variable will read 1 on the first run and 0 on all subsequent runs, because it has been reset in main() and is never restored unless the program is downloaded again.

Normally, when running from an EPROM, the startup code will take care of clearing and initializing RAM data memory by using a ROM-copy of the initialized data variables. 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. The used bootstrap loader only needs to be able to fill program memory.

Using the -c option will initialize the object image with all required data values directly. So, when loading the object image, no additional copy action is required. This will save the memory space for the ROM copy at the cost of not being able to restart the program with the same initial values. Every program restart requires downloading the object image first.

The -c option is of great use when loading the object image 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 additional variable images in ROM is required). To allow this, the bootstrap loader must be capable of handling data for different memory spaces.

To get a maximum decrease in memory usage, make sure to compile your C startup code without the code for initializing the data memory. Otherwise the locator will generate a copy table with zero entries to prevent unresolved references. For the Motorola DSP56xxx toolchain this means compiling the startup code with the define NOCOPY set.

-d

Option:

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

-d file

Arguments:

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

Description:

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

Example:

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

-e

Option:

EDE always removes the output files on errors.

-e

Description:

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

Example:

lc563 -e test.out

-em

Option:

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

-emmacro[=def]

Arguments:

The macro you want to define and optionally its definition.

Description:

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.

Example:

lc563 myproject.out -o myproject.abs -emEDE=\"myproject.i\" -M

-err

Option:

In EDE this option is not useful.

-err

Description:

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.

Example:

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

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

-f

Option:

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

-f file

Arguments:

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

file may not be a number in the range 0-4, because these numbers are used to specify an output format.

Description:

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

More than one -f option is allowed.

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

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

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

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

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

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

Example:

or

or

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

Example:

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

Example:

Suppose the file mycmds contains the following line:

The command line can now be:

-f format

Option:

Select the Project | Project Options... menu item. Expand the Linker/Locator entry and select Output Format.
Select one of the output formats.

-fformat

Arguments:

format can be one of the following output formats:

Description:

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 I, IEEE-695 Object Format,
Appendix J, Motorola S-Records,
Appendix K, Intel Hex Records.

-M

Option:

Select the Project | Project Options... menu item. Expand the Linker/Locator entry and select Locator Miscellaneous.
Enable the Produce a memory map file (.map) check box.

-M[n]

Arguments:

Optionally the maximum line width (n > 132). If you omit the width, the default is 132 characters.

Description:

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.

Example:

To create the map file a.map, enter:

-o

Option:

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

-ofilename

Arguments:

An output filename.

Default:

The default filename depends on the output format specified:

Description:

Use filename as output filename of the locator.

Example:

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

-p

Option:

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

-p

Description:

Make a proposal for a software part in a description file on standard output.

-r

Option:

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

-r

Description:

By default locator generated sections, like the copy table, are writable, so they can be placed in RAM. Setting the -r option makes them read-only, which is reuired for a romable application.

-S

Option:

Select the Project | Project Options... menu item. Expand the Linker/Locator entry and select Locator Miscellaneous.
Select a code space from the Generate code for space list box.

-Sspace

Arguments:

The name of a space from a .dsc file.

Default:

For the IEEE-695 format, by default code is generated for all spaces.

Description:

With this option you can generate a specific output file for a specified space instead of generating an output file containing all spaces.

For the Motorola S-record and Intel Hex format, the locator can only generate records for one space at a time, because the formats do not make a distinction between memory spaces.

Example:

To generate code for space P instead of all spaces, enter:

-s

Option:

Select the Project | Project Options... menu item. Expand the Linker/Locator entry and select Locator Miscellaneous.
Disable the Include symbolic debug information check box.

-s

Description:

Strip debug information from the input file.

-V

Option:

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

-V

Description:

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

Example:

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

-v

Option:

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

-v

Description:

Verbose option. Print the name of each file as it is processed.

Example:

lc563 -v test.out

-w

Option:

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

-w level

Arguments:

A warning level between 0 and 9 (inclusive).

Default:

-w8

Description:

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

Example:

To suppresses warnings above level 5, enter:

Using the control program:

11.2.2 Format Suboptions

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 Intel Hex file for each chip 2, 3
s Emit start address record 3
S1, S2, S3 Force Motorola S1, S2 or S3 records 2
u Unsorted addresses (default) 2

Table 11-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:

11.3 Getting Started

The locator invocation is normally done via EDE or the control program. In this section you will invoke the locator as a separate tool in order to get a better understanding of the use of options and the description file.

You can find a more detailed description of the descriptive language for embedded environments (DELFEE) in Appendix G DEscriptive Language For Embedded Environments.

If you want to locate the calc demo, you need the relocatable demo file calc.out as input for the locator. You can generate this file by copying the contents of the directory examples\asm (examples/asm for UNIX) to your working directory, and invoke the control program:

Be sure that the bin directory of the DSP56xxx tools is in the search path. The option -cl tells the control program to stop after linking and to suppress the locating phase. The file you made by this command is the complete demo, but still in a relocatable form. Now, you can locate this relocatable file calc.out to absolute addresses by typing:

The -M option causes lc563 to make a map file. The default output file format is IEEE-695 (-f1 option). Since you did not specify an output name, the default output name a.abs will be generated. (For -f0 and -f1 the default is a.abs, for -f2 the default is a.sre, for -f3 the default is a.hex and for -f4 the default is a.cld.) After the invocation, the locator has generated two files:

- a.abs, The IEEE 695 output file

- a.map, The locate map file

If you want to give the output file a specific name, you must use the -ofile option:

You may need to adjust the description file. In a description file you can change the locating algorithm of the locator. If you do not specify a description file, the locator uses the file def_targ.dsc from the etc sub directory (in the DSP56xxx product tree). If you do not want to change this original description file (which is advisable), make a copy of file def_targ.dsc to your working directory.

You can change the copy of the description file. Everything after a comment (//) until the end of the line is ignored. As an example, change the lines:

into:

The effect will be that the location order of the sections .text and .ptext is now forced to be fixed.

Locate again to see the effect. The modified description file def_targ.dsc in your working directory will be found before the original version in the etc directory. Because you want to compare the map files, choose another output name:

Now you can compare calc.map and calc_o.map.

If you want to choose between a description file with and without the changes you made, you must rename the def_targ.dsc in your working directory to, for example, order.dsc. If you want the changed version of the description, you can invoke the locator as follows:

The space between -d and order is optional. If you do install order.dsc in the etc subdirectory, you can use the option -dorder from any working directory.

If you want to know more about the locate language DELFEE, read Appendix G.

11.4 Locator Target Board Support

The locator description files that are supplied with the tool set contain conditional parts to place the stack in the desired memory space. The control variables for this selection are automatically generated when compiling with the control program cc563 or from EDE, and are set to the normal defaults when no memory space options are supplied.

To set the stack size and the heap size, all description files contain STACKSIZE and HEAPSIZE defines that can be set from the locator command line (with -em) or from EDE. Default values that are supplied are 0.75k (or 1k for non-L-stack models) stack and 4k heap; some smaller targets have other appropriate values. See the description file that is concerned.

A problem that arises with the stack in L-memory is that L-memory is allocated first, and only after that X- and Y-memory. Therefore L-memory takes precedence, and the stack area will normally block the allocation of near X- and Y-variables. A define NEARXYSIZE is provided in the description files to reserve space for such variables; it is set to zero if not defined externally.

The .cpu files have defines for the memory switch and the cache size (SWITCH_SELECT and CACHE_SELECT) that can be set from the locator command line. These defines are set to default values if they are not specified on the command line.

An overview of the defines is given in the following table.

Locator control Default Description
STACKSIZE 768 or 1K Stack size (bytes)
HEAPSIZE 4K Heap size (bytes)
NEARXYSIZE 0 Area size for near X/Y variables
CACHE_SELECT 0 or 1 Enable/disable cache
SWITCH_SELECT 0 or 1 Enable/disable memory switch

Table 11-3: Locator controls

11.5 Force Const Sections

Previous toolchain versions handled initialized P memory data sections incorrectly, and wasted a lot of P memory on intializers for constant data sections. Two modifiers have been added to the org statement, to define constant (const) and initialized (int) data sections. The const data sections that were previously generated (for string literals only) were named ".xstring" (or any other memory), but these were still copied from the copy table. The new const data sections are named ".xconst" etc., and they are not copied anymore; instead, the debugger places them in the appropriate memory directly. This saves a lot of memory in applications that use large tables or a lot of strings. Applications that were previously contained in P memory only at startup, are now spread over several memory spaces.

There are two ways to attack this problem:

1. Force the ".xconst" etcetera sections back to the copytable. This brings back the waste of P memory, but if that is not a problem it is possible you can do this by using the locator description file. You have to specify the read-only sections in the description file and change their attributes:

These lines must be placed right under every position in X and Y memory spaces where,

is written in the .dsc file.

2. Use a bootstrap loader that can handle the different memory spaces. The bootrom example contains such a loader and tools to generate a file for it, that you have to extend to match your application. This is the more elegant solution that we especially recommend if you are low on memory.

11.6 Calling the Locator via the Control Program

It is recommended to call the locator via the control program cc563. The control program translates certain options for the locator (e.g., -clas to -f4). 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:

builds an absolute demo file called calc.abs ready for running via the CrossView debugger.

11.7 Locator Output

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, Motorola CLAS object format or in IEEE-695 format, depending on the usage of the -f option. The default output name is a.hex, a.sre, a.cld or a.abs, respectively. Note that the debug information is not supported in the Motorola CLAS object format.

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 per space with their absolute address, both sorted on address and sorted on symbol.

The map file also contains a part showing the sections defined in each source file (with their address and size).

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.

11.8 Locator Messages

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:

 DSP563xx/6xx locator vx.y rz              SN00000000-127 (c) year TASKING, Inc.
 lc563 W112 (3) calc.out: Copy table not referenced, initial data is not copied

11.9 Address Space

Figures 11-2 and 11-3 show the different address space mappings of the DSP5600x .

Figure 11-2: DSP5600x physical address space mapping

Figure 11-3: DSP5600x virtual address space mapping

11.10 Locator Labels

The locator assigns addresses to the following labels when they are referenced:

F_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.

F_lc_bs : Begin of stack space (using keyword stack).

F_lc_es : End of stack space.

F_lc_bh : Begin of heap space (using keyword heap).

F_lc_eh : End of heap space.

F_lc_b_name : Begin of section name.

F_lc_e_name : End of section name.

F_lc_cb_name : Begin of copy of section name.

F_lc_ce_name : End of copy of section name.

F_lc_u_name : User defined label. The label must be defined in the description file. For example:

F_lc_ub_name : Begin of user defined label. The label must be defined in the description file. For example:

F_lc_ue_name : End of user defined label.

At C level, all locator labels start with one underscore (the compiler adds an 'F').

11.10.1 Locator Labels Reference

This section contains a description of all locator labels. Locator labels are labels starting with F_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.

At C level, all locator labels start with one leading underscore (the compiler adds an 'F').

F_lc_b_ section, F_lc_e_section

Syntax:

extern _X unsigned char _lc_b_section[ ];
extern _X unsigned char _lc_e_section[ ];

Description:

You can use the general locator labels F_lc_b_section and F_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 F_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.

Example:

printf( "Text size is 0x%x\n",
  _lc_e__text - _lc_b__text );

F_lc_bh, F_lc_eh

Syntax:

extern _X unsigned char _lc_bh[ ];
extern _X unsigned char _lc_eh[ ];

Description:

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.

F_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. F_lc_eh represents the end of the heap.

Example:

Heap definition:

Sbrk code:

F_lc_bs, F_lc_es

Syntax:

extern _X unsigned char _lc_bs[ ];
extern _X unsigned char _lc_es[ ];

Description:

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.

F_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. F_lc_es represents the end of the stack.

Example:

Stack definition:

Stack initialization:

F_lc_cb_ section, F_lc_ce_section

Syntax:

extern _X unsigned char _lc_cb_section[ ];
extern _X unsigned char _lc_ce_section[ ];

Description:

You can use the general locator labels F_lc_cb_section and F_lc_ce_section to obtain the addresses of the copy of section section in a program. The b version points to the start of the copy 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_copy and _text_copy exist, the general label F_lc_cb__text is set to the start of of _text_copy. The label for section .text_copy 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.

Example:

printf( "Text size is 0x%x\n",
  _lc_ce__text - _lc_cb__text );

F_lc_cp

Syntax:

extern char _X *_lc_cp;

Description:

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

F_lc_u_identifier

Syntax:

extern _X int _lc_u_identifier[ ];

Description:

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 F_lc_u_. From assembly the label can be referenced with the prefix F_lc_u_, from C with the prefix _lc_u_ (only the leading underscore).

Example:

In description file:

From C:

From assembler:

F_lc_ub_identifier, F_lc_ue_identifier

Syntax:

extern _X int _lc_ub_identifier[ ];
extern _X int _lc_ue_identifier[ ];

Description:

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 F_lc_ub_ or F_lc_ue_. From assembly the labels can be referenced with the prefix F_lc_ub_ and F_lc_ue_, from C with the prefix _lc_ub_ and _lc_ue_ (only the leading underscore).

Example:

In description file:

From C:

From assembler:


Copyright © 2002 Altium BV