Keil Logo

OVERLAY Linker Directive

Abbreviation

OL

Arguments

OVERLAY (* ! sfname)
OVERLAY (sfname ! *)
OVERLAY (sfname { ! | ~ } sfname 〚, ...〛)
OVERLAY (sfname { ! | ~ } (sfname, sfname 〚, ...〛) 〚, ...〛)

Default

The linker analyzes the program and creates a call tree from which it infers normal program flow.

µVision

Options — L251 Misc — Overlay.

Description

The OVERLAY directive modifies the call tree that is automatically generated by the linker. Adjustments to the call tree are required when your application uses function pointers or contains virtual program jumps (as is the case in the scheduler of a real-time operating system).

sfname is a segment or function name. In most cases, the linker allows you to specify the function name as shown in Manipulating the Call Tree.

 

  • The OVERLAY directive allows you to specify either the complete segment name or just the function name when specifying new references. You may not use wildcards with the OVERLAY directive.

There are several forms of the OVERLAY directive you may use depending on the type of references that must be altered.

Creating New Root Segments

OVERLAY (* ! sfname)

This form of the OVERLAY directive specifies that sfname is a root segment for overlay analysis purposes. This is typically how you would specify a task for an RTOS or for an interrupt service routine.

Note

  • Task functions in RTX51 and RTX51 Tiny are handled automatically by the linker and do not require use of the OVERLAY directive.
  • Interrupt functions you create with the C251 Compiler are handled automatically and do not require use of the OVERLAY directive.

Excluding Segments from Overlay Analysis

OVERLAY (sfname ! *)

This form of the OVERLAY directive specifies that sfname is to be excluded from overlay analysis. Its data and bit segments are located in non-overlaid memory. This does not influence data overlaying of other functions.

Note

  • The data areas of functions that call sfname and functions called by sfname are still overlaid. This may or may not be desirable.

Removing Call References Between Segments

OVERLAY (sfname-caller ~ sfname-callee)

OVERLAY (sfname-caller ~ (sfname-callee, sfname-callee))

This form of the OVERLAY directive specifies that references from sfname-caller to sfname-callee are to be removed from overlay analysis.

Function references are automatically added to overlay analysis when you reference one function inside another (typically, these references are function calls). If you reference the address of a function (without calling the function), the linker considers this to be a reference between the two functions and it is included in overlay analysis. You may remove this reference manually using this form of the OVERLAY directive.

Referring to the following overlay map:

SEGMENT                           DATA_GROUP
  +--> CALLED SEGMENT          START    LENGTH
----------------------------------------------
?PR?_FUNC?DMAIN                -----    -----
  +--> ?PR?_FUNC_A?DMAIN
  +--> ?PR?_FUNC_B?DMAIN

You may remove the references from ?PR?_FUNC?DMAIN to ?PR?_FUNC_A?DMAIN and ?PR?_FUNC_B?DMAIN with the following OVERLAY command:

OVERLAY(?PR?_FUNC?DMAIN ~ (?PR?_FUNC_A?DMAIN,?PR?_FUNC_B?DMAIN))

Note

  • In many cases, new call references must be added for call references you remove.

Adding Call References Between Segments

OVERLAY (sfname-caller ! sfname-callee)

OVERLAY (sfname-caller ! (sfname-callee, sfname-callee))

This form of the OVERLAY directive specifies that references from sfname-caller to sfname-callee are to be artificially added into the overlay analysis.

Function calls through function pointers are typically not included in overlay analysis. The reason is that the linker cannot determine what function the pointer is referencing. For calls through function pointers, you must manually add references into the overlay analysis.

For example, you may add references from ?PR?_MAIN?DMAIN to ?PR?_FUNC_A?DMAIN and ?PR?_FUNC_B?DMAIN with the following OVERLAY command:

OVERLAY(?PR?_MAIN?DMAIN ! (?PR?_FUNC_A?DMAIN,?PR?_FUNC_B?DMAIN))
See Also

NOOVERLAY, RECURSIONS

Example

None.

  Arm logo
Important information

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies.

Change Settings

Privacy Policy Update

Arm’s Privacy Policy has been updated. By continuing to use our site, you consent to Arm’s Privacy Policy. Please review our Privacy Policy to learn more about our collection, use and transfers
of your data.