# ELF Loader Overview

## Description

The EL library is a dynamic module system.
It uses main memory efficiently by dynamically reading and releasing the program module in the game application.
Unlike the dynamic link libraries of other operating systems, with this library games are responsible for allocating and deallocating memory and loading modules from ROM.
The EL library consists of one static module (the application), one static information module (created by `makelst`), and multiple dynamic modules (`.o` or `.a` files). Static modules can control the placement of dynamic modules in memory. Static modules are built as normal SRL files. The static module contains common functions and common variables referenced by the dynamic modules.
Dynamic modules can call functions and refer to the variables defined in static modules. For this to be possible, you must use the `makelst` tool to automatically generate a program that will pass function information for the static module to the EL library and, if necessary, add variable information and then call the program from the static module. In addition, dynamic modules can call functions and refer to variables in other dynamic modules loaded into memory.
Functions and variables of the dynamic module can be accessed by specifying the symbol name from the static module.
The program is thus aware of and uses the dynamic module, unlike when calling functions inside a static module.
A dynamic module application can be written in the same manner as a normal program written in C. Dynamic modules use `.o` and `.a` files, created by the compiler and linker, unchanged. However, items compiled normally contain debugging information that is unnecessary to run a program but required to run the debugger. In addition to files that are created by normal compilation, you need files with debugging information removed for embedding as a dynamic module in an application. If you want to debug the application, you also need files with debugging information. You can use the `stripdebug` tool in this case. To notify the debugger of the path to dynamic modules with debugging information, a `DllFile` must be added to the `RomSpec` section of the RSF file. For details, see `makerom`.
Note: The EL library does not support C++.

#### Making Dynamic Modules

##### 1. Compile the Dynamic Part of the Program and Generate Object (.o or .a) Files

The EL library treats object files themselves as dynamic modules, so it is possible to directly use either an `.o` or `.a` file to which multiple `.o` files have been linked. Run the `stripdebug` tool on a generated file to reduce its size and remove unnecessary debugging information, and prepare a file with debugging information to pass to the debugger. These files are embedded in the application as dynamic modules.

    % stripdebug.exe -o dll.a -O dll_debug.a a.a

##### 2. Compile the Static Part of the Program and Generate Object (.o) Files

Compile the static part of the program and convert it into an object file so that a static information module can be generated with `makelst`.

##### 3. Create a Program That Allows Every Dynamic Module to Access the Static Module

Use `makelst` to generate a static information module and statically link the program to allow all dynamic modules to access required functions in the static module.

    % makelst.exe -o staticsymlist.c --static obj/ARM9-TS/Release/main.o ../../../../lib/ARM9-TS/Release/libos.a --dll dll/dll.a

##### 4. Build the Program and Generate the ROM File

Link the object files compiled in steps 1 and 3 to generate an executable file. Complete the process by generating an SRL (static module) file with the dynamic modules (`.o` and `.a` files) embedded as ROM files.

Note: If you want to use the debugger on dynamic modules, you must use the `EL_LinkFile` function and add specifications to the RSF file for files that are passed to the debugger.

    RomSpec
    {
        File		dll.a
        DllFile		dll.a dll_debug.a ARM9
    }

In addition, embed dynamic module files as ROM files.

#### Using Dynamic Modules

The following section explains how to link dynamic modules in a ROM file.

Dynamic modules are general ELF-formatted data.

##### 1. Prepare to load individual modules.

Initialize the ROM file system; it is accessed using the FS library in the `EL_LinkFile` function.

    FS_Init( FS_DMA_NOT_USE );

##### 2. Initialize the EL Library

Use the `EL_Init` function to initialize the EL library.

    EL_Init(MY_Alloc, MY_Free);

##### 3. Add Dynamic Modules

Use the `EL_Link*` functions to register dynamic modules with the EL library. The `EL_LinkFile` function is used here so that the debugger can be used.

    my_dlld = EL_LinkFile( "rom:/data/dllA.a", lib_buf);

##### 4. Resolve Links

Use the `EL_AddStaticSym` function to register symbol information with the EL library for dynamic modules created by `makelst`. Afterward, use the `EL_ResolveAll` function to resolve links for the registered dynamic modules.

    EL_AddStaticSym();
    EL_ResolveAll();

##### 5. Call Dynamic Module Functions

Pass the name of the dynamic module function to call to `EL_GetGlobalAdr` and get a function pointer. You can call the intended functions through this function pointer.

    dll_func = EL_GetGlobalAdr( my_dlld, "global_func\0");
    (*dll_func)();

##### 6. Unlink the Dynamic Modules

Unused dynamic modules can be unlinked and removed from memory. Unlink with the `EL_Unlink` function and then release used memory from the application.

    EL_Unlink( my_dlld );

## See Also

EL Function List
`makerom`

## Revision History

2009/01/16 Noted the lack of support for C++ in the EL library.
2008/10/06 Added information on accessing static module variables from dynamic modules.
2008/04/22 Updated for the latest specifications.
2007/08/07 Initial version.

CONFIDENTIAL