ARM Technical Support Knowledge Articles

What are Overlays and how are they used?

Applies to: DS-5, RealView Development Suite (RVDS)


Overlay introduction

This FAQ introduces overlays and provides an example of writing a simple overlay manager.

What is an overlay? An overlay is one of two or more pieces of code (or data) that can be loaded to a pre-determined memory region on demand at runtime.  Initially, each overlay is stored in ROM/Flash, just like ordinary code/data. During runtime, an overlay can be copied to a known address in RAM and executed there when required. This can later be replaced by another overlay when required. Only one overlay can occupy that space in RAM at any time.

What are overlays used for? Overlays are useful where the system has some fast RAM or RAM resources are limited. RAM typically is faster than ROM/Flash so it can be beneficial to copy code there to execute. The system can be designed such that some portions of code/data share a certain RAM region. These code/data are independent to each other and are only required at specific times. Systems designed in this way may achieve higher runtime performance or RAM space saving.

The OVERLAY keyword

The ARM compilation tools provide the minimum support to enable overlays. Overlay regions are specified in the scatter-loading file. When two or more execution regions are marked as OVERLAY in the scatter file, these regions can have the same base address without causing a linker error. The code/data positioned in these regions will be linked to locate at that particular base address.

Note: Overlay regions will not be copied from their Load addresses to the Execution address automatically during initialisation (i.e. Overlay regions will not be scatter-loaded).

Before continuing it is advisable to read the related linker documentation to be familiar with scatter files, linker defined symbols and general linker terminology.

Overlay manager

The compiler and linker provide no other special support for overlays. Overlays are not automatically copied to their runtime location when a function within the overlay is called.

The programmer must write extra code, an overlay manager, that copies the required overlay to its execution address, and records which overlay is in use at any one time. The overlay manager will run throughout the application, and will be called whenever overlay loading is needed. For instance, the overlay manager may be called before every function call which might require a different overlay segment to be loaded.

It must be ensured that the correct overlay segment is loaded before calling any function in that segment. If a function from one overlay is called while a different overlay is loaded then some kind of runtime failure will occur. Neither the linker nor the compiler can warn you if this is a possibility since it is not statically determinable. The same is true for a data overlay.

Implementation example of an overlay manager

The implementation of the overlay manager will depend on exactly what is required in a system. This FAQ presents a simple method of implementing an overlay manager. The downloadable example contains a Readme.txt that describes details of each source file. There are two main tasks:

  1. Copy the correct overlay to the runtime addresses:

    The central component of this overlay manager is a routine to copy code/data from the load address to the execution address. This routine is based around the following linker defined symbols:

    Load$$execution_region_name$$Base : Load address
    Image$$execution_region_name$$Base : Execution address
    Image$$execution_region_name$$Length : Length of execution region

    The copy routine called load_overlay() is implemented in overlay_manager.c, where memcpy() and memset() functions are used to copy CODE/RW Data overlays and clear ZI Data overlays.

    Note: for RW data overlays, it is necessary to disable RW data compression (as provided by RVCT 2.1 and later) for the whole project using the linker switch --datacompressor off, or mark the execution region with the attribute NOCOMPRESS.

    All required symbols are listed in the assembly file overlay_list.s, where two common base addresses and a RAM space mapped to the overlay structure table are defined and exported:


  2. Determine which overlay to load:

    As specified in the scatter file, the two functions func1(), func2() and their corresponding data are placed in CODE_ONE, CODE_TWO, DATA_ONE, DATA_TWO regions, respectively. We use a special linker mechanism for replacing calls to functions with stubs. This involves writing a small stub for each function in the overlay that may be called from outside the overlay. In the example, two stub functions $Sub$$func1() and $Sub$$func2() are created for the two functions func1() and func2() in overlay_stubs.c. These stubs will call the overlay-loading function load_overlay() to load the corresponding overlay. After the overlay manager finishes its overlay loading task, the stub function can then call $Super$$func1 to call the loaded function func1() in the overlay.

    For more details of the $Sub/$Super mechanism, refer to the compiler linker documentation.

Zip file icon Download example source code


Article last edited on: 2011-08-30 15:19:45

Rate this article

Disagree? Move your mouse over the bar and click

Did you find this article helpful? Yes No

How can we improve this article?

Link to this article
Copyright © 2011 ARM Limited. All rights reserved. External (Open), Non-Confidential