ld: Overlay Description
1
1 3.6.9 Overlay Description
1 -------------------------
1
1 An overlay description provides an easy way to describe sections which
1 are to be loaded as part of a single memory image but are to be run at
1 the same memory address. At run time, some sort of overlay manager will
1 copy the overlaid sections in and out of the runtime memory address as
1 required, perhaps by simply manipulating addressing bits. This approach
1 can be useful, for example, when a certain region of memory is faster
1 than another.
1
1 Overlays are described using the 'OVERLAY' command. The 'OVERLAY'
1 command is used within a 'SECTIONS' command, like an output section
1 description. The full syntax of the 'OVERLAY' command is as follows:
1 OVERLAY [START] : [NOCROSSREFS] [AT ( LDADDR )]
1 {
1 SECNAME1
1 {
1 OUTPUT-SECTION-COMMAND
1 OUTPUT-SECTION-COMMAND
1 ...
1 } [:PHDR...] [=FILL]
1 SECNAME2
1 {
1 OUTPUT-SECTION-COMMAND
1 OUTPUT-SECTION-COMMAND
1 ...
1 } [:PHDR...] [=FILL]
1 ...
1 } [>REGION] [:PHDR...] [=FILL] [,]
1
1 Everything is optional except 'OVERLAY' (a keyword), and each section
1 must have a name (SECNAME1 and SECNAME2 above). The section definitions
1 within the 'OVERLAY' construct are identical to those within the general
1 'SECTIONS' construct (⇒SECTIONS), except that no addresses and no
1 memory regions may be defined for sections within an 'OVERLAY'.
1
1 The comma at the end may be required if a FILL is used and the next
1 SECTIONS-COMMAND looks like a continuation of the expression.
1
1 The sections are all defined with the same starting address. The
1 load addresses of the sections are arranged such that they are
1 consecutive in memory starting at the load address used for the
1 'OVERLAY' as a whole (as with normal section definitions, the load
1 address is optional, and defaults to the start address; the start
1 address is also optional, and defaults to the current value of the
1 location counter).
1
1 If the 'NOCROSSREFS' keyword is used, and there are any references
1 among the sections, the linker will report an error. Since the sections
1 all run at the same address, it normally does not make sense for one
11 section to refer directly to another. ⇒NOCROSSREFS Miscellaneous
Commands.
1
1 For each section within the 'OVERLAY', the linker automatically
1 provides two symbols. The symbol '__load_start_SECNAME' is defined as
1 the starting load address of the section. The symbol
1 '__load_stop_SECNAME' is defined as the final load address of the
1 section. Any characters within SECNAME which are not legal within C
1 identifiers are removed. C (or assembler) code may use these symbols to
1 move the overlaid sections around as necessary.
1
1 At the end of the overlay, the value of the location counter is set
1 to the start address of the overlay plus the size of the largest
1 section.
1
1 Here is an example. Remember that this would appear inside a
1 'SECTIONS' construct.
1 OVERLAY 0x1000 : AT (0x4000)
1 {
1 .text0 { o1/*.o(.text) }
1 .text1 { o2/*.o(.text) }
1 }
1 This will define both '.text0' and '.text1' to start at address 0x1000.
1 '.text0' will be loaded at address 0x4000, and '.text1' will be loaded
1 immediately after '.text0'. The following symbols will be defined if
1 referenced: '__load_start_text0', '__load_stop_text0',
1 '__load_start_text1', '__load_stop_text1'.
1
1 C code to copy overlay '.text1' into the overlay area might look like
1 the following.
1
1 extern char __load_start_text1, __load_stop_text1;
1 memcpy ((char *) 0x1000, &__load_start_text1,
1 &__load_stop_text1 - &__load_start_text1);
1
1 Note that the 'OVERLAY' command is just syntactic sugar, since
1 everything it does can be done using the more basic commands. The above
1 example could have been written identically as follows.
1
1 .text0 0x1000 : AT (0x4000) { o1/*.o(.text) }
1 PROVIDE (__load_start_text0 = LOADADDR (.text0));
1 PROVIDE (__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0));
1 .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) { o2/*.o(.text) }
1 PROVIDE (__load_start_text1 = LOADADDR (.text1));
1 PROVIDE (__load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1));
1 . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1));
1