This chapter contains the following sections:
Overview
Invocation
Detailed Description of Locator Options
Format Suboptions
Building an Application for an Execution Environment
Calling the Locator via the Control Program
Locator Labels
Locator Labels References
This chapter describes the XA locator.
The task of the locator is to locate a .out file, made by lkxa, 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 XA 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 I 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 xa.dsc in the current directory or in directory etc in the XA 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) | ||||||||||||||||||||||||||
-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 |
-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.
lcxa -?
Select the EDE | Processor Options... menu item. Disable the Initialized and cleared C variables check box in the Initialization 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 EDE | Linker/Locator Options... menu item. Select the Use project specific locator control file (.dsc) radio button in the Locator tab. Enter the basename of the description file in the Locator control file field.
-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 xa_t.dsc), enter:
lcxa -dxa_t.dsc test.out
EDE always calls the locator with the -e
option.
-e
Remove all locate products such as temporary files, the resulting output file and the map file, in case an error occurred.
lcxa -e test.out
EDE generates a locator control file and the proper invocation for you using the EDE macro.
-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.
Using the EDE macro this option is mainly used to specify a locator control file.
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. For example:
lcxa 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:
lcxa -err test.out
To write errors to the file test.elc instead of stderr, enter:
lcxa -err test.out -otest.abs
Select the EDE | Linker/Locator Options... menu item. Add the option to the Additional options field in the Locator tab.
-f file
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-3, 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:
lcxa -f mycmds
Select the EDE | Linker/Locator Options... menu item. Choose an Output Format option from the Format tab.
-f format
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 K,
IEEE-695 Object Format,
Appendix L,
Intel Hex Records,
Appendix M,
Motorola S-Records.
Select the EDE | 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:
lcxa -M test.out
Select the EDE | Linker/Locator Options... menu item. Add the option to the Additional options field in the Locator tab.
-o filename
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:
lcxa test.out -otest.abs
Select the EDE | 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 EDE | Linker/Locator Options... menu item. Select a code space from the Generate code for space list box in the Locator tab.
-S space
The name of an XA space from a .dsc file.
Code is generated for all spaces.
With this option you can generate a specific output file for a specified space instead of generating an output file containing all spaces.
To generate code for space XA_code instead of all spaces, enter:
lcxa test.out -S XA_code
Select the EDE | 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.
Select the EDE | Linker/Locator Options... menu item. Add the option to the Additional options field in the Locator tab.
-V
With this option you can display the version header of the locator. This option must be the only argument of lcxa. Other options are ignored. The locator exits after displaying the version header.
lcxa -V
XA locator va.b rc SN00000000-015 (c) year TASKING, Inc.
Select the EDE | Linker/Locator Options... menu item. Enable the Print the name of each file as it is processed check box in the Locator tab.
-v
Verbose option. Print the name of each file as it is processed.
lcxa -v test.out
lcxa V001 (1): Output format: IEEE 695 lcxa V004 (1): Warning level 8 lcxa V007 (1): Found file <xa_t.dsc> via path \cxa\etc\xa_t.dsc lcxa V002 (1): Starting pass 1 lcxa V000 (1): File currently in progress: test.out
Select the EDE | 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:
lcxa -w5 test.out
Using the control program:
ccxa -Wlc-w5 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 | 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 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 (*.dsc, *.cpu and *.mem), 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 you use 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
EDE | Linker/Locator Options... and EDE | Processor 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. Therefore, there are no longer different DELFEE files for every execution environment, but only one set, as delivered in the etc directory of the product: xa.dsc, xa.cpu and xa.mem. For the SmartXA a separate set is available: smart.dsc and smart.cpu. You can, of course, still inspect (and even edit) these files, 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):
All controls apply to both the core XA and the SmartXA,
unless explicitly stated otherwise.
Locator control | Default | Description |
Compiler and derivative used: | ||
_REGSFR | regxag3.dat | Special Function Register file for CrossView Pro Debugger (core XA) |
regsmart.dat | Special Function Register file for CrossView Pro Debugger (smartXA) | |
Processor configuration: | ||
_IRAM | 200H | Internal RAM size (core XA) |
0A20H | Internal RAM size (smartXA) | |
_SSS | _IRAM- _FAME | Internal RAM in segment 0 (smartXA) |
_USS | 128 | Internal RAM in segment 1..N (smartXA) |
_FAME | 544 | Internal RAM in segment 15 (smartXA) |
_ICODE | 32k | Internal ROM size |
_EEPROM | 32k-64 | Internal EEPROM size (smartXA) |
_MUBLKHI0 | 255 |
Internal ROM window 0 (in 256 by te blocks) 0..255 (smartXA) |
_MUBLKHI1 | 255 |
Internal ROM window 1 (in 256 by te blocks) 0..255 (smartXA) |
_ZPAGE | 1 |
Page zero mode (core XA) 0: No Page Zero mode 1: Page Zero mode |
_SM | 1 |
System mode (smartXA) 0: User mode 1: System mode |
Memory Model: | ||
_MODEL_TINY | True | Define if you are using the tiny memory model |
_MODEL_COMPACT | False | Define if you are using the compact memory model |
_MODEL_SMALL | False | Define if you are using the small memory model |
_MODEL_MEDIUM | False | Define if you are using the medium memory model |
_MODEL_LARGE | False | Define if you are using the large memory model |
External memory (core XA only): | ||
_UNIFIED_BUS | 0 | 0: Separate external code and data bus (Harvard) 1: Unified external code and data bus (linear) |
_XMEM | 1 | 0: Single chip solution (no external memory) 1: External memory areas specified by (one or more) _XRAM and _XROM macros |
_X_DATA_RAM( name, addr, size) | 0,64k | External Data RAM area: chip-name, start-address, size. Must be within #ifdef _X_DATA_RAM and #endif |
_X_DATA_ROM( name, addr, size) | 64k,128k | External Data ROM area: chip-name, start-address, size. Must be within #ifdef _X_DATA_ROM and #endif |
_X_CODE_ROM( name, addr, size) | 32k,96k | External Code ROM area: chip-name, start-address, size. Must be within #ifdef _X_CODE_ROM and #endif |
Internal memory: | ||
_DRESERVES | False | Define if you want to reserve some memory area on the DATA bus |
_DRESERVED( startaddr,endaddr) | -- | Reserve memory area on the DATA bus: start-address, end-address |
_ERESERVES | False | Define if you want to reserve some memory area on the EEPROM bus (SmartXA only) |
_ERESERVED( startaddr,endaddr) | -- | Reserve memory area on the EEPROM bus: start-address, end-address (SmartXA only) |
_CRESERVES | False | Define if you want to reserve some memory area on the CODE bus |
_CRESERVED( startaddr,endaddr) | -- | Reserve memory area on the CODE bus: start-address, end-address |
_CODEPAGE | 0H | Map code page (64k) to this page number (core XA only) |
_RESET_VECTOR | 0H | Allocate reset vector (section in startup code) at this address |
Group sections: | ||
_DGROUP | False | Define if you want to use the _DGROUPNR control |
_DGROUPNR(name, number) | -- | Specifed RAM data group with name must be alllocated in page number. Must be within #ifdef _DGROUP and #endif |
_RGROUP | False | Define if you want to use the _RGROUPNR control |
_RGROUPNR(name, number) | -- | Specifed ROM data group with name must be alllocated in page number. Must be within #ifdef _RGROUP and #endif |
_CGROUP | False | Define if you want to use the _CGROUPNR control |
_CGROUPNR(name, number) | -- | Specifed ROM code group with name must be alllocated in page number. Must be within #ifdef _CGROUP and #endif |
_STACK_GP | DS | Define if you want to group the stack to a (default) data group |
_HEAP_GP | DS | Define if you want to group the heap to a (default) data group |
Special sections: | ||
_STACK_SZ | -- | System stack size |
_STACK_LC | -- | Location of the system stack |
_HEAP_SZ | -- | Heap size for malloc() and free() |
_HEAP_LC | -- | Location of the heap |
_XVWBUF | 8 | CrossView Pro buffer size (strings in target memory) |
Order (and optional address) of user sections: | ||
_BAORDER | False | Define if you want to use the _BITADDR control |
_BITADDR(name [addr=addr] ) | -- | Specify section with name must be located at address addr or before/after another _BITADDR control. Must be within #ifdef _BITADDR and #endif |
_BORDER | False | Define if you want to use the _BIT control |
_BIT(name [addr=addr] ) | -- | Specify section with name must be located at address addr or before/after another _BIT control. Must be within #ifdef _BIT and #endif |
_DORDER | False | Define if you want to use the _DATA control |
_DATA(name [addr=addr] ) | -- | Specify section with name must be located at address addr or before/after another _DATA control. Must be within #ifdef _DATA and #endif |
_EORDER | False | Define if you want to use the _EDATA control (SmartXA) |
_EDATA(name [addr=addr] ) | -- | Specify section with name must be located at address addr or before/after another _EDATA control. Must be within #ifdef _EDATA and #endif (SmartXA) |
_IORDER | False | Define if you want to use the _IDATA control |
_IDATA(name [addr=addr] ) | -- | Specify section with name must be located at address addr or before/after another _IDATA control. Must be within #ifdef _IDATA and #endif |
_HORDER | False | Define if you want to use the _HDATA control |
_HDATA(name [addr=addr] ) | -- | Specify section with name must be located at address addr or before/after another _HDATA control. Must be within #ifdef _HDATA and #endif |
_RDORDER | False | Define if you want to use the _RDATA control |
_RDATA(name [addr=addr] ) | -- | Specify section with name must be located at address addr or before/after another _RDATA control. Must be within #ifdef _RDATA and #endif |
_RIORDER | False | Define if you want to use the _RIDATA control |
_RIDATA(name [addr=addr] ) | -- | Specify section with name must be located at address addr or before/after another _RIDATA control. Must be within #ifdef _RIDATA and #endif |
_RHORDER | False | Define if you want to use the _RHDATA control |
_RHDATA(name [addr=addr] ) | -- | Specify section with name must be located at address addr or before/after another _RHDATA control. Must be within #ifdef _RHDATA and #endif |
_XSORDER | False | Define if you want to use the _XSHORT control |
_XSHORT(name | -- | Specify section with name must be located at address addr or before/after another _XSHORT control. Must be within #ifdef _XSHORT and #endif |
_CORDER | False | Define if you want to use the _CODE control |
_CODE(name [addr=addr] ) | -- | Specify section with name must be located at address addr or before/after another _CODE control. Must be within #ifdef _CODE and #endif |
_CCOPY(name [addr=addr] ) | -- | Specify section with name must be located at address addr or before/after another _CCOPY control. Must be within #ifdef _CCOPY and #endif |
_CTABLE(addr) | -- | Specify absolute address of the copy table. Must be within #ifdef _CTABLE and #endif |
_HCORDER | False | Define if you want to use the _HCODE control |
_HCODE(name [addr=addr] ) | -- | Specify section with name must be located at address addr or before/after another _HCODE control. Must be within #ifdef _HCODE and #endif |
_HTABLE(addr) | -- | Specify absolute address of the copy table. Must be within #ifdef _HTABLE and #endif |
Table 10-3: Locator controls
Below is an example locator control file of a standalone application. It can be executed on the CrossView Pro simulator and has been built with the C compiler, small memory model, using 32k of internal ROM, no external ROM and 64k of external RAM in the first half of the near page. The application needs a bit more heap and stack than the default values. There are two special code sections in this application, SPECIAL1_PR must be located at address 01000 in internal ROM and SPECIAL2_PR must be located after SPECIAL1_PR:
// // Example locator control file (extension .i) // #define _XMEM 1 #define _MODEL_SMALL // small memory model #ifdef _X_DATA_RAM _X_DATA_RAM(x_ram_data0,0,0FFFFH) // 64k external RAM #endif #define _STACK_SZ 2k // stack size 2k #define _HEAP_SZ 8k // heap size 8k #define _CORDER // specify order of CODE sections #ifdef _CODE _CODE(SPECIAL1_PR addr=01000H) // locate at absolute address _CODE(SPECIAL2_PR) #endif
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. For example:
lcxa myproject.out -o myproject.abs -emEDE=\"myproject.i\" -M
CrossView Pro ROM can be used with any XA evaluation board, running TASKING ROM monitor. This includes the existing XTEND boards. CrossView Pro communicates with the monitor on the target board via an RS-232 interface, using a very efficient binary protocol.
In EDE you can specify the internal and external ROM/RAM usage. In the Memory tab of the Processor Options you specify how the CPU is configured with regards to internal ROM/RAM as well as the external memory interface. For the XTEND board, specify the cpu to be ROM-less.
In the Memory tab of the Linker/Locator Options you can specify the external ROM and RAM areas. The XTEND board uses 32K from 8000H for downloading application code, and 32K from 0H for applicaion data. The ROM monitor expects the application and its interrupt vectors to be located at 8000H. When using the ROM monitor you must reserve memory from 0H to 020H and from FFFAH to FFFFH, since the ROM monitor uses this area. The last item to take care of is the reset vector. The ROM monitor assumes the application's reset vector to be at 8000H instead of 0000H, so you must specify this to the linker/locator.
It is recommended to call the locator via the control program ccxa. The control program translates certain options for the locator (e.g., -ihex to -f3). 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 or .obj files. The invocation:
ccxa -M calc.asm startup.asm initseg.asm -o calc.out
builds an absolute demo file called calc.abs ready for running via the CrossView simulator.
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:
XA locator vx.y rz SN00000000-127 (c) year TASKING, Inc. lcxa 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.
Figures 10-2, 10-3 , 10-4 and 10-5 show the different address space mappings of the XA.
Figure 10-2: XA physical address space mapping
Figure 10-3: XA virtual data/SFR address space mapping
Figure 10-4: XA virtual short address space mapping
Figure 10-5: XA virtual code address space mapping
Figures 10-6, 10-7, 10-8 and 10-9 show the different address space mappings of the SmartXA.
Figure 10-6: SmartXA physical address space mapping
Figure 10-7: SmartXA physical MMU window mapping
Figure 10-8: SmartXA virtual data/SFR address space mapping
Figure 10-9: SmartXA virtual EPROM/code address space mapping
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 (see init.src in the lib/src directory):
+10 length +9 length +8 length +7 source-address +6 source-address +5 source-address +4 destination-address +3 destination-address +2 destination-address +1 action (0 if last entry) cpt_entry -> +0 amode (0 if last entry)
The first member, amode, defines the copy table addressing mode for the current entry. The following values are allowed:
CP_LAST (value 0) Reached end of the table.
CP_HCODE (value 1) amode HCODE.
CP_HDATA (value 2) amode HDATA.
CP_XSHORT (value 3) amode XSHORT.
CP_BITADDR (value 4) amode BITADDR.
CP_SFR (value 5) amode SFR.
CP_BIT (value 6) amode BIT.
CP_IDATA (value 7) amode IDATA.
CP_DATA (value 8) amode DATA.
CP_XDATA (value 9) amode XDATA.
CP_CODE (value 10) amode CODE.
The second member, action, 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 assembly level, the copy table can be initalized as:
__INITSEG: IF MODEL_LARGE || MODEL_MEDIUM || MODEL_COMPACT MOV.B CS,#SEG(__lc_cp) ; set initial code segement ; of copy-table MOV.W InitL,#SOF(__lc_cp) ; now InitL points to first ; entry in the copy table IF MODEL_MEDIUM || MODEL_COMPACT SETB InitHSSEL ; access code space via ; InitL ENDIF ELSE MOV.W InitL,#__lc_cp ; now InitL points to first ; entry in the copy table ENDIF
See the file init.src for more information.
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.
__lc_gb_name : Base address of grouped sections with joined group name.
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.
At C level, all locator labels start with one leading
underscore (the compiler adds an extra underscore).
extern _huge unsigned char _lc_b_section[
];
extern _huge 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 _huge unsigned char _lc_bh[ ];
extern _huge 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 iram { . . cluster data { heap length = 200; . . } . . }
Sbrk code:
extern _huge unsigned char _lc_bh[ ]; extern _huge unsigned char _lc_eh[ ]; static char * sbrk( long length ) { . . if ( (lastmem + length) > _lc_eh ) { return (char *) -1; /* overflow */ }
extern _huge unsigned char _lc_bs[ ];
extern _huge 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 lowest address of the stack. At 'C' level _lc_bs represent the low address of the stack. The label is defined as a char array, but an array of any basic type will do. __lc_es represents the highest address of the stack.
Stack definition:
block iram { cluster data { stack length = 100; . . } }
Stack initialization:
__START: mov 081h, #__lc_bs
extern char _far *_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
extern _huge 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_, from C with the prefix _lc_u_ (one leading underscore).
In description file:
block iram { cluster clear { label bstart; section text; label bend; } . . . }
From C:
#include <stdio.h> extern _huge int _lc_u_bstart[]; extern _huge int _lc_u_bend[]; int main() { printf( "Size of cluster clear is %d\n", (long)_lc_u_bend - (long)_lc_u_bstart ); }
From assembler:
EXTRN NUMBER ( __lc_u_bstart ) EXTRN NUMBER ( __lc_u_bend ) mov r0, #__lc_u_bstart mov r1, #0 jmp __cleartst __clearnext: mov [r0+], r1 __cleartst: cjne r0, #__lc_u_bend+1, __clearnext
extern _huge int _lc_ub_identifier[ ];
extern _huge 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_, from C with the prefix _lc_ub_ and _lc_ue_ (one leading underscore).
In description file:
block address_range { cluster ram { attribute w; amode data { section selection=w; reserved label=buffer length=0x10; // Start address of reserved area is // label __lc_ub_buffer // End address of reserved area is // label __lc_ue_buffer } } }
From C:
#include <stdio.h> extern _huge int _lc_ub_buffer[]; extern _huge int _lc_ue_buffer[]; int main() { printf( "Size of reserved area buffer is %d\n", (long)_lc_ue_buffer - (long)_lc_ub_buffer ); }
extern char _far * _lc_gb_identifier;
This locator label is related to section groups. You can allocate a group of sections with name identifier in a data block description. See the group= keyword of the DELFEE language. The locator label specifies the base address of a data group. The identifier is the name of the data group. From assembly the label can be referenced with the prefix __lc_gb, from C with the prefix _lc_gb_ (one leading underscore).
In description file:
space XA_data { block data { cluster ram_data_clstr { attribute w; group DS page=1; ... } } }
See also the JOIN attribute in section
Grouped Sections in chapter Assembly Language.