1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<HTML>
3<HEAD>
4<META http-equiv="Content-Type" content="text/html; charset=windows-1252">
5<META name="GENERATOR" content="IBM WebSphere Studio Homepage Builder Version 7.0.0.0 for Windows">
6<META http-equiv="Content-Style-Type" content="text/css">
7<TITLE>ELF Loader Overview </TITLE>
8<LINK rel="stylesheet" href="../css/nitro.css" type="text/css">
9</HEAD>
10<BODY>
11<H1 align="left">ELF Loader Overview</H1>
12<H2>Description</H2>
13<P>
14
15The EL library is a dynamic module system.<BR><BR> It uses main memory efficiently by dynamically reading and releasing the program module in the game application.<BR> 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.<BR> <BR>The EL library consists of one static module (the application), one static information module (created by <CODE>makelst</CODE>), and multiple dynamic modules (<CODE>.o</CODE> or <CODE>.a</CODE> 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.<BR><BR>Dynamic modules can call functions and refer to the variables defined in static modules. For this to be possible, you must use the <CODE>makelst</CODE> 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.<BR><BR> Functions and variables of the dynamic module can be accessed by specifying the symbol name from the static module.<BR> The program is thus aware of and uses the dynamic module, unlike when calling functions inside a static module.<BR> <BR> A dynamic module application can be written in the same manner as a normal program written in C. Dynamic modules use <CODE>.o</CODE> and <CODE>.a</CODE> 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 <CODE>stripdebug</CODE> tool in this case. To notify the debugger of the path to dynamic modules with debugging information, a <CODE>DllFile</CODE> must be added to the <CODE>RomSpec</CODE> section of the RSF file. For details, see <A href="../tools/makerom.html"><CODE>makerom</CODE></A>.<br><br> <font color="red"><B>Note:</B> The EL library does not support C++.</font> <BR>
16
17</P>
18<HR>
19<P><H4>Making Dynamic Modules</H4></P>
20<p>
21<H5>1. Compile the Dynamic Part of the Program and Generate Object (.o or .a) Files</H5>
22<P>The EL library treats object files themselves as dynamic modules, so it is possible to directly use either an <CODE>.o</CODE> or <CODE>.a</CODE> file to which multiple <CODE>.o</CODE> files have been linked. Run the <CODE>stripdebug</CODE> 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.</P>
23<TABLE border="1" width="100%">
24  <TBODY>
25    <TR>
26      <TD width="100%">
27      <PRE><CODE>
28% stripdebug.exe -o dll.a -O dll_debug.a a.a</CODE></PRE>
29      </TD>
30    </TR>
31  </TBODY>
32</TABLE>
33
34<H5>2. Compile the Static Part of the Program and Generate Object (.o) Files</H5>
35<P>Compile the static part of the program and convert it into an object file so that a static information module can be generated with <CODE>makelst</CODE>.</P>
36
37<H5>3. Create a Program That Allows Every Dynamic Module to Access the Static Module</H5>
38<P>Use <CODE>makelst</CODE> to generate a static information module and statically link the program to allow all dynamic modules to access required functions in the static module.</P>
39<TABLE border="1" width="100%">
40  <TBODY>
41    <TR>
42      <TD width="100%">
43      <PRE><CODE>
44% makelst.exe -o staticsymlist.c --static obj/ARM9-TS/Release/main.o ../../../../lib/ARM9-TS/Release/libos.a --dll dll/dll.a</CODE></PRE>
45      </TD>
46    </TR>
47  </TBODY>
48</TABLE>
49
50<H5>4. Build the Program and Generate the ROM File</H5>
51<P>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 (<CODE>.o</CODE> and <CODE>.a</CODE> files) embedded as ROM files.</P>
52<P><B>Note:</B> If you want to use the debugger on dynamic modules, you must use the <A href="EL_Link.html"><CODE>EL_LinkFile</CODE></A> function and add specifications to the RSF file for files that are passed to the debugger.</P>
53<TABLE border="1" width="100%">
54  <TBODY>
55    <TR>
56      <TD width="100%">
57      <PRE><CODE>
58RomSpec
59{
60    File		dll.a
61    DllFile		dll.a dll_debug.a ARM9
62}
63      </CODE></PRE>
64      </TD>
65    </TR>
66  </TBODY>
67</TABLE>
68<P>In addition, embed dynamic module files as ROM files.</P>
69
70
71<HR>
72<P><H4>Using Dynamic Modules</H4></P>
73<P>The following section explains how to link dynamic modules in a ROM file.</P>
74
75<P>Dynamic modules are general ELF-formatted data.
76<H5>1. Prepare to load individual modules.</H5>
77<p>Initialize the ROM file system; it is accessed using the FS library in the <CODE>EL_LinkFile</CODE> function.
78</p>
79<TABLE border="1" width="100%">
80  <TBODY>
81    <TR>
82      <TD width="100%">
83      <PRE><CODE>
84FS_Init( FS_DMA_NOT_USE );
85      </CODE></PRE>
86      </TD>
87    </TR>
88  </TBODY>
89</TABLE>
90
91<H5>2. Initialize the EL Library</H5>
92<p>Use the <CODE>EL_Init</CODE> function to initialize the EL library.
93</p>
94<TABLE border="1" width="100%">
95  <TBODY>
96    <TR>
97      <TD width="100%">
98      <PRE><CODE>
99EL_Init(MY_Alloc, MY_Free);
100      </CODE></PRE>
101      </TD>
102    </TR>
103  </TBODY>
104</TABLE>
105
106<H5>3. Add Dynamic Modules</H5>
107<p>
108Use the <A href="EL_Link.html"><CODE>EL_Link*</CODE></A> functions to register dynamic modules with the EL library. The <CODE>EL_LinkFile</CODE> function is used here so that the debugger can be used.
109</p>
110<TABLE border="1" width="100%">
111  <TBODY>
112    <TR>
113      <TD width="100%">
114      <PRE><CODE>
115my_dlld = EL_LinkFile( &quot;rom:/data/dllA.a&quot;, lib_buf);
116      </CODE></PRE>
117      </TD>
118    </TR>
119  </TBODY>
120</TABLE>
121
122<H5>4. Resolve Links</H5>
123<p>
124Use the <CODE>EL_AddStaticSym</CODE> function to register symbol information with the EL library for dynamic modules created by <CODE>makelst</CODE>. Afterward, use the <CODE>EL_ResolveAll</CODE> function to resolve links for the registered dynamic modules.
125</p>
126<TABLE border="1" width="100%">
127  <TBODY>
128    <TR>
129      <TD width="100%">
130      <PRE><CODE>
131EL_AddStaticSym();
132EL_ResolveAll();
133      </CODE></PRE>
134      </TD>
135    </TR>
136  </TBODY>
137</TABLE>
138
139<H5>5. Call Dynamic Module Functions</H5>
140<p>
141Pass the name of the dynamic module function to call to <CODE>EL_GetGlobalAdr</CODE> and get a function pointer. You can call the intended functions through this function pointer.
142</p>
143<TABLE border="1" width="100%">
144  <TBODY>
145    <TR>
146      <TD width="100%">
147      <PRE><CODE>
148dll_func = EL_GetGlobalAdr( my_dlld, &quot;global_func\0&quot;);
149(*dll_func)();
150      </CODE></PRE>
151      </TD>
152    </TR>
153  </TBODY>
154</TABLE>
155
156<H5>6. Unlink the Dynamic Modules</H5>
157<p>
158Unused dynamic modules can be unlinked and removed from memory. Unlink with the <CODE>EL_Unlink</CODE> function and then release used memory from the application.
159</p>
160<TABLE border="1" width="100%">
161  <TBODY>
162    <TR>
163      <TD width="100%">
164      <PRE><CODE>
165EL_Unlink( my_dlld );
166      </CODE></PRE>
167      </TD>
168    </TR>
169  </TBODY>
170</TABLE>
171
172</P>
173
174
175<H2>See Also</H2>
176<P><A href="list_el.html">EL Function List</A><BR> <A href="../tools/makerom.html"><CODE>makerom</CODE></A>
177</P>
178<H2>Revision History</H2>
179<P>
1802009/01/16 Noted the lack of support for C++ in the EL library.<BR> 2008/10/06 Added information on accessing static module variables from dynamic modules.<BR> 2008/04/22 Updated for the latest specifications.<BR> 2007/08/07 Initial version.</P>
181<hr><p>CONFIDENTIAL</p></body>
182</HTML>