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.

Procedure

1. 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.
2. 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.

3. 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.