You identify the sections in your code that are to become overlays by
giving them names of the form .ARM.overlayN
, where N
is an integer identifier. You then use
a scatter file to indicate those regions of memory where armlink is to assign the overlays for loading at runtime.
Each overlay region corresponds to an execution region that has the
attribute AUTO_OVERLAY
assigned in the scatter
file. armlink allocates one set of integer
identifiers to each of these overlay regions. It allocates another set of integer
identifiers to each overlaid section with the name .ARM.overlayN
that is defined in the object files.
Note:
The numbers assigned to the overlay sections in your object files
do not match up to the numbers that you put in the .ARM.overlayN
section
names.
Procedure
-
Declare the functions that you want the armlink automatic
overlay mechanism to process.
- In C, use a function attribute, for
example:
__attribute__((section(".ARM.overlay1"))) void foo(void) { ... }
__attribute__((section(".ARM.overlay2"))) void bar(void) { ... }
- In the armclang integrated assembler
syntax, use the
.section
directive, for
example: .section .ARM.overlay1,"ax",%progbits
.globl foo
.p2align 2
.type foo,%function
foo: @ @foo
...
.fnend
.section .ARM.overlay2,"ax",%progbits
.globl bar
.p2align 2
.type bar,%function
bar: @ @bar
...
.fnend
- In ARM syntax assembly, use the
AREA
directive, for
example: AREA |.ARM.overlay1|,CODE
foo PROC
...
ENDP
AREA |.ARM.overlay2|,CODE
bar PROC
...
ENDP
Note:
You can choose to overlay or not overlay code sections. Data sections
must never be overlaid.
-
Specify the locations to load the code sections from and to in
a scatter file. Use the
AUTO_OVERLAY
keyword on
one or more execution regions.
The execution regions must not have any section selectors. For example:
OVERLAY_LOAD_REGION 0x10000000
{
OVERLAY_EXECUTE_REGION_A 0x20000000 AUTO_OVERLAY 0x10000 { }
OVERLAY_EXECUTE_REGION_B 0x20010000 AUTO_OVERLAY 0x10000 { }
}
In this example, armlink
emits a program header table entry that loads all the overlay data starting
at address 0x10000000
.
Also, each overlay is relocated so that it runs correctly if copied to
address 0x20000000
or 0x20010000
. armlink chooses one of these addresses for
each overlay.
-
When linking, specify the
--overlay_veneers
command-line option.
This option causes armlink to arrange
function calls between two overlays, or between non-overlaid code and an
overlay, to be diverted through the entry point of an overlay manager.
To permit an overlay-aware debugger to track the overlay that is active,
specify the armlink
--emit_debug_overlay_section
command-line
option.