Overlays

The linker supports both static and dynamic overlays.

Static overlays

In the static case, a simple 2-dimensional overlay scheme is supported. There is one root segment, and as many memory partitions as specified by the user (called, for example, 1_, 2_, etc.). Within each partition, some number of overlay segments (called, for example, 1_1, 1_2, ...) share the same area of memory. The user specifies the contents of each overlay segment and the linker calculates the size of each partition, allowing sufficient space for the largest segment in it. All addresses are calculated at link time so statically overlaid programs are not relocatable. A hypothetical example of the memory map for a statically overlaid program might be:

-----------------------------------------------------------
2_1        |2_2       |2_3       |          |high address  
-----------------------------------------------------------
1_1        |1_2       |1_3       |1_4       |              
-----------------------------------------------------------
segment                          |root      |low address   
-----------------------------------------------------------

Segments 1_1, 1_2, 1_3 and 1_4 share the same area of memory. Only one of these segments can be loaded at any given instant; the remainder must be on backing store.

Similarly, segments 2_1, 2_2 and 2_3 share the 2_ area of memory, but this is entirely separate from the 1_ partition.

It is a current restriction that an overlay segment name is of the form partition_segment and contains 10 or fewer characters. However, it is not required that partition and segment be numeric as shown here in the example: any alphanumeric characters are acceptable.

Dynamic overlays

A dynamic or relocatable overlay scheme is obtained by specifying the -Relocatable command line option. In this case:

the root segment is a (load-time) relocatable AIF image;
each overlay segment is a plain binary image with relocation directives appended.

When using relocatable overlays, it is expected that:

the overlay manager will allocate memory for a segment when it is first referenced;
a segment will be unloaded, and the memory it occupies freed, by an explicit call to the overlay manager.

In this case, it suffices to give each overlay segment a simple name (no embedded underscore), and let the linker link each as if it were in its own partition (which is dynamically allocated by the overlay manager).

Nevertheless, if a 2-dimensional naming scheme is used, the linker will generate segment clash tables (see below), and segments can be unloaded implicitly by the overlay manager when a clashing segment is loaded. In effect, this supports the classification of dynamic overlay segments into disjoint sets of not co-resident objects.

A dynamic overlay segment (including a root segment) is followed by a sequence of relocation directives. The sequence is terminated by a word containing -1. Each directive is a 28-bit byte offset of a word or instruction to be relocated, together with a flag nibble in the most significant 4 bits of the word. Flag nibbles have the following meanings:

--------------------------------------------------------
0:  |relocate a word in the root segment by the         
    |difference between the address at which the root   
    |was loaded and the address at which it was linked; 
--------------------------------------------------------
1:  |relocate a word in an overlay segment by the       
    |address of the root;                               
--------------------------------------------------------
2:  |relocate a word in an overlay segment by the       
    |address of the segment;                            
--------------------------------------------------------
3:  |relocate a B or BL from an overlay segment to the  
    |root segment, by the difference (in words) between 
    |the segments address and the roots address;        
--------------------------------------------------------
7:  |relocate a B or BL from the root segment to an     
    |overlay segment, by the difference (in words)      
    |between the root's address and the segment's       
    |address, (such relocation directives always refer  
    |to a PCIT entry in an overlay segment, which is    
    |used to initialise a PCIT section in the root when 
    |the overlay segment is loaded).                    
--------------------------------------------------------

Assignment of AREAs to overlay segments

The linker assigns AOF AREAs to overlay segments under user control (see below). Usually, a compiler produces one code AREA and one data AREA for each source file (called C$$code and C$$data when generated by the C compiler). The C compiler option -ZO allows each separate function to be compiled into a separate code AREA, allowing finer control of the assignment of functions to overlay segments, (but at the cost of slightly enlarged code and enlarged object files). The user controls the overlay structure by describing the assignment of certain AREAs to overlay segments. For each remaining AREA in the link list, the linker will act as follows:

if all references to the AREA are from the same overlay segment, the AREA is included in that segment; otherwise,
the AREA is included in the root segment.

This strategy can never make an overlaid program use more memory than if the linker put all remaining AREAs in the root, but it can sometimes make it smaller.

By default, only code AREAs are included in overlay segments. Data AREAs can be forcibly included, but it is the user's responsibility to ensure that doing so is meaningful and safe.

On disc, an overlaid program is organised as a directory containing a root image and a collection of overlay segments. The name of the directory is specified to the Linker as the argument to its -Output flag. The linker creates the following components within the application directory:

root

the root segment, which is an AIF image, and (for example):

1_1
1_2
...
2_1
...

overlay segments, which are plain binary image fragments.

Describing an overlay structure to the linker

The overlay file, named as argument to the -OVerlay option, describes the required overlay structure. It is a sequence of logical lines:

a '' immediately before the end of a physical line continues the logical line on the next physical line;
any text from a ';' to end of the logical line inclusive is a comment (for documentation purposes) which is ignored by the linker.

Each logical line has the following structure:

segment-name                module-name                    [ "(" list-of-AREA-names ")" ]
                module-name                    ...

For example:

1_1    edit1 edit2 editdata(C$$code,C$$data) sort

list-of-AREA-names is a comma-separated list. If omitted, all AREAs with the CODE attribute are included.

module-name is either the name of an object file (with all leading pathname components and file name extensions removed), or the name of a library member (again, with all leading pathname components and file name extensions removed).

In the example above, sort would match the C library module of the same name.

Note that these rules require that, within a link list, modules have unique names. For example, it is not possible to overlay a program made up from test/thing.o and thing.o (two modules called thing). This is a restriction on overlaid programs only.

To help partition a program between overlay segments the linker can generate a list of inter-AREA references. This is requested by using the -Xref option. In general, if area A refers to area B, for example because fx in area A calls fy in area B, then A and B should not share the same area of memory. Otherwise, every time fx calls fy, or fy returns to fx, there will be an overlay segment swap.

The -MAP option requests the linker to print the base address and size of every AREA in the output program. Although not restricted to use with overlaid programs, -MAP is most useful with them, as it shows how AREAs might be packed more efficiently into overlay segments.