RPL Process

This section provides detail information about the RPL process and is not critical to understanding how to use RPL.

From Exports to Imports

An import library is constructed that emulates the presence of the symbols exported from the RPL file. These symbols live in a section with a unique name and type that cannot be moved or combined by the linker with any other section.

For RPLs that use the import library, the linker links against the import section, and generates relocations to code and data that reference the items in the import section. The RPLs are always relocatable, and so the final symbol locations are only known at runtime.

Linking at Runtime

In the example where FOO.RPL imports from BAR.RPL, any symbol in FOO.RPL that references an import section for BAR.RPL, that symbol is NOT searched for in FOO.RPL. The symbol is found in BAR.RPL. If BAR.RPL is not present, the system loads it automatically, and then links with it at runtime.

RPLs are referenced by their name without a path (for example, game.rpl and player.rpl). This means that there is one namespace for RPLs. Loading two RPLs with identical names is not possible.

Export Table Format

An export table that is created by preprpl[32|64] contains target locations for relocations of all exports, and an offset for each export to the export name within the export table section. This indicates that all exports are referenced and that their final positions in the loaded program are automatically known when the program is relocated.

All of the exports are sorted by name alphabetically. A Table CRC is generated that is the 32-bit CRC for all of the sorted names of all the exports strung together. Any change in the exports results in a different CRC. The CRC can be thought of as an API signature that is used later in dynamic linking. The export table is used as the basis for the creation of an import table, which goes into the import library (.a).

Import Table Format

An import table is created that has the same signature as the export table that is created by preprpl[32|64]. The name of the library is placed into the import section, so that the dynamic linker knows where to get the symbols from. Symbol table entries are generated for each symbol in the table. The location of each symbol is virtual and there is no data at the location.

The import section has a unique name and type that cannot be moved or combined by the linker with any other section.

RPLs are always relocatable. The final symbol locations are not known until runtime.

Linking One Symbol

When an RPL is loaded, it undergoes relocation and addresses of symbols are found. Symbols in an import section have virtual locations that are offsets into the import table. These virtual locations can be thought of as indexes.

If the import section signature matches an export section signature, then we know the precise index in the export table for an import. In this way, imports can be looked up in constant time. If signatures do not match imports, symbols can still be looked up using the symbol name and the sorted export table in Log2n time.

Linking One Symbol - Detail

If the Table signature matches the signature on the export table, the offset in the import table (8 in the Offset column of the table above) is divided by the size of a virtual import (for example 4), giving us the index in the export table =>> 1.

Using math, we index into the export table to find the actual location of the symbol that we are looking for. The operations occur in O(c) time. The final Effective Address (EA) is used in the relocation operation.

Fallback - Signatures Do Not Match

If the signatures do not match, we use the symbol name in the importing DLL to do a Log2n search in of the exports. This requires that symbol table string tables be present in the importing RPL.

The fallback option occurs when the API signatures of the exports and the imports do not match. The reason for this is that an RPL list of exports changes (extended or updated) and the importing module is not regenerated using the new .a import library. This can happen if a module is updated independently of another module.

Modules can be fixed, extended, and replaced independently, and the program will still work. For optimal performance, it is best to link with a version of the import library that has the same API.

Revision History

2013/05/08 Automated cleanup pass.
2013/03/15 Initial version.