10.8.4. Generating Copy Tables With the table() Operator¶
The linker supports extensions to the linker command file syntax that enable you to do the following:
Identify any object components that may need to be copied from load space to run space at some point during the run of an application
Instruct the linker to automatically generate a copy table that contains (at least) the load address, run address, and size of the component that needs to be copied
Instruct the linker to generate a symbol specified by you that provides the address of a linker-generated copy table.
For instance, Overlay Management Example can be written as shown in the following example:
SECTIONS
{
...
UNION
{
GROUP
{
.task1: { task1.c.o(.text) }
.task2: { task2.c.o(.text) }
} load = ROM, table(_task12_copy_table)
GROUP
{
.task3: { task3.c.o(.text) }
.task4: { task4.c.o(.text) }
} load = ROM, table(_task34_copy_table)
} run = RAM
...
}
Using the SECTIONS directive from this example linker command file, the linker generates two copy tables named: _task12_copy_table and _task34_copy_table. Each copy table provides the load address, run address, and size of the GROUP that is associated with the copy table. This information is accessible from application source code using the linker-generated symbols, _task12_copy_table and _task34_copy_table, which provide the addresses of the two copy tables, respectively.
Using this method, you need not worry about the creation or maintenance of a copy table. You can reference the address of any copy table generated by the linker in C/C++or assembly source code, passing that value to a general purpose copy routine, which will process the copy table and affect the actual copy.
10.8.4.1. The table() Operator¶
You can use the table() operator to instruct the linker to produce a copy table. A table() operator can be applied to an output section, a GROUP, or a UNION member. The copy table generated for a particular table() specification can be accessed through a symbol specified by you that is provided as an argument to the table() operator. The linker creates a symbol with this name and assigns it the address of the copy table as the value of the symbol. The copy table can then be accessed from the application using the linker-generated symbol.
Each table() specification you apply to members of a given UNION must contain a unique name. If a table() operator is applied to a GROUP, then none of that GROUP’s members may be marked with a table() specification. The linker detects violations of these rules and reports them as warnings, ignoring each offending use of the table() specification. The linker does not generate a copy table for erroneous table() operator specifications.
Copy tables can be generated automatically; see Generating Copy Tables With the table() Operator. The table operator can be used with compression; see Compression.
10.8.4.2. Boot-Time Copy Tables¶
The linker supports a special copy table name, BINIT (or binit), that you can use to create a boot-time copy table. This table is handled before the .cinit section is used to initialize variables at startup. For example, the linker command file for the boot-loaded application described in Using Built-in Link Operators in Copy Tables can be rewritten as follows:
SECTIONS
{
.flashcode: { app_tasks.c.o(.text) }
load = FLASH, run = PMEM,
table(BINIT)
...
}
For this example, the linker creates a copy table that can be accessed through a special linker-generated symbol, __binit__, which contains the list of all object components that need to be copied from their load location to their run location at boot-time. If a linker command file does not contain any uses of table(BINIT), then the __binit__ symbol is given a value of -1 to indicate that a boot-time copy table does not exist for a particular application.
You can apply the table(BINIT) specification to an output section, GROUP, or UNION member. If used in the context of a UNION, only one member of the UNION can be designated with table(BINIT). If applied to a GROUP, then none of that GROUP’s members may be marked with table(BINIT).The linker detects violations of these rules and reports them as warnings, ignoring each offending use of the table(BINIT) specification.
10.8.4.3. Using the table() Operator to Manage Object Components¶
If you have several pieces of code that need to be managed together, then you can apply the same table() operator to several different object components. In addition, if you want to manage a particular object component in multiple ways, you can apply more than one table() operator to it. Consider the linker command file excerpt in the following example:
SECTIONS
{
UNION
{
.first: { a1.c.o(.text), b1.c.o(.text), c1.c.o(.text) }
load = EMEM, run = PMEM, table(BINIT), table(_first_ctbl)
.second: { a2.c.o(.text), b2.c.o(.text) }
load = EMEM, run = PMEM, table(_second_ctbl)
}
.extra: load = EMEM, run = PMEM, table(BINIT)
...
}
In this example, the output sections .first and .extra are copied from external memory (EMEM) into program memory (PMEM) at boot time while processing the BINIT copy table. After the application has started executing its main thread, it can then manage the contents of the overlay using the two overlay copy tables named: _first_ctbl and _second_ctbl.
10.8.4.4. Linker-Generated Copy Table Sections and Symbols¶
The linker creates and allocates a separate input section for each copy table that it generates. Each copy table symbol is defined with the address value of the input section that contains the corresponding copy table.
The linker generates a unique name for each overlay copy table input section. For example, table(_first_ctbl) would place the copy table for the .first section into an input section called .ovly:_first_ctbl. The linker creates a single input section, .binit, to contain the entire boot-time copy table.
The following example shows how you can control the placement of the linker-generated copy table sections using the input section names in the linker command file.
SECTIONS
{
UNION
{
.first: { a1.c.o(.text), b1.c.o(.text), c1.c.o(.text) }
load = EMEM, run = PMEM, table(BINIT), table(_first_ctbl)
.second: { a2.c.o(.text), b2.c.o(.text) }
load = EMEM, run = PMEM, table(_second_ctbl)
}
.extra: load = EMEM, run = PMEM, table(BINIT)
...
.ovly: { } > BMEM
.binit: { } > BMEM
}
For the linker command file in this example, the boot-time copy table is generated into a .binit input section, which is collected into the .binit output section, which is mapped to an address in the BMEM memory area. The _first_ctbl is generated into the .ovly:_first_ctbl input section and the _second_ctbl is generated into the .ovly:_second_ctbl input section. Since the base names of these input sections match the name of the .ovly output section, the input sections are collected into the .ovly output section, which is then mapped to an address in the BMEM memory area.
If you do not provide explicit placement instructions for the linker-generated copy table sections, they are allocated according to the linker’s default placement algorithm.
The linker does not allow other types of input sections to be combined with a copy table input section in the same output section. The linker does not allow a copy table section that was created from a partial link session to be used as input to a succeeding link session.
10.8.4.5. Splitting Object Components and Overlay Management¶
It is possible to split sections that have separate load and run placement instructions. The linker can access both the load address and run address of every piece of a split object component. Using the table() operator, you can tell the linker to generate this information into a copy table. The linker gives each piece of the split object component a COPY_RECORD entry in the copy table object.
For example, consider an application which has seven tasks. Tasks 1 through 3 are overlaid with tasks 4 through 7 (using a UNION directive). The load placement of all of the tasks is split among four different memory areas (LMEM1, LMEM2, LMEM3, and LMEM4). The overlay is defined as part of memory area PMEM. You must move each set of tasks into the overlay at run time before any services from the set are used.
You can use table() operators in combination with splitting operators, >>, to create copy tables that have all the information needed to move either group of tasks into the memory overlay as shown the following example:
SECTIONS
{
UNION
{
.task1to3: { *(.task1), *(.task2), *(.task3) }
load >> LMEM1 | LMEM2 | LMEM4, table(_task13_ctbl)
GROUP
{
.task4: { *(.task4) }
.task5: { *(.task5) }
.task6: { *(.task6) }
.task7: { *(.task7) }
} load >> LMEM1 | LMEM3 | LMEM4, table(_task47_ctbl)
} run = PMEM
...
.ovly: > LMEM4
}
The following example illustrates a possible driver for such an application.
#include <cpy_tbl.h>
extern far COPY_TABLE task13_ctbl;
extern far COPY_TABLE task47_ctbl;
extern void task1(void);
...
extern void task7(void);
main() {
...
copy_in(&task13_ctbl);
task1();
task2();
task3();
...
copy_in(&task47_ctbl);
task4();
task5();
task6();
task7();
...
}
You must declare a COPY_TABLE object as far to allow the overlay copy table section placement to be independent from the other sections containing data objects (such as .bss).
The contents of the .task1to3 section are split in the section’s load space and contiguous in its run space. The linker-generated copy table, _task13_ctbl, contains a separate COPY_RECORD for each piece of the split section .task1to3. When the address of _task13_ctbl is passed to copy_in(), each piece of .task1to3 is copied from its load location into the run location.
The contents of the GROUP containing tasks 4 through 7 are also split in load space. The linker performs the GROUP split by applying the split operator to each member of the GROUP in order. The copy table for the GROUP then contains a COPY_RECORD entry for every piece of every member of the GROUP. These pieces are copied into the memory overlay when the _task47_ctbl is processed by copy_in().
The split operator can be applied to an output section, GROUP, or the load placement of a UNION or UNION member. The linker does not permit a split operator to be applied to the run placement of either a UNION or of a UNION member. The linker detects such violations, emits a warning, and ignores the offending split operator usage.