en_US/rso/intro.html

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<LINK rel="stylesheet" type="text/css" href="../CSS/revolution.css">
<base target="main">
<title>RSO Function Introduction</title>
</head>

<body>

<h1>RSO API</h1>

<h2>Introduction</h2>
<p>
The RSO Library is a relocatable module system.<BR><BR><BR> It can use main memory efficiently by dynamically reading and deallocating program modules in the game application.<BR><BR> In this library, unlike the dynamic link library of other operating systems, the game application is responsible for main memory allocation and deallocation and loading modules from the disk.<BR><BR> <BR>The RSO library consists of one static module (the <CODE>.elf</CODE> file), one static information module (the <CODE>.sel</CODE> file), and multiple dynamic (that is, relocatable) modules (the <CODE>.rso</CODE> files). After the boot ROM loads the static module of the program, the static module controls the memory location of the dynamic module. The static module is built as a normal <CODE>.elf</CODE> file. The static module contains common functions and common variables referenced by the dynamic modules.<BR><BR>Dynamic (relocatable) modules can call functions and refer to the variables defined in static modules. In addition, dynamic modules can call functions and refer to variables in other dynamic modules loaded into main memory. Referencing across modules is resolved by directly revising the code and data sections of a module when it is loaded.<BR><BR> Functions and variables of the dynamic (relocatable) module can be accessed by specifying the symbol name from the static module.<BR> Accordingly, the program must be aware of the dynamic modules that it uses, unlike when calling functions within static modules.<BR> <BR>A dynamic module (RSO) application is written in the same manner as the main C/C++ code, except that the dynamic module is built from a partially linked <CODE>.elf</CODE> file (PLF). A PLF file contains unresolved external symbols and debug information. The <CODE><a href="./tools/makerso.html">makerso</a></CODE> tool, provided with the Revolution SDK, will convert a PLF file into a dynamic module file used exclusively by the Wii console. These Wii-specific dynamic modules include, in addition to the standard application code and data section, a relocation instruction list, import information, and export information.<BR><BR><BR> Import information is used to reference external elements, and export information allows referencing by external elements.<BR><BR>

<h2>Differences from REL</h2>
<H3>Advantages</H3>
<UL>
<LI>The dynamic module functions and variables can be accessed from the static module by specifying symbol names.
<LI>As long as there are <CODE>.rso</CODE> files, the library can run, even if all the dynamic module <CODE>.plf</CODE> files have not been prepared first. (For example, you can run RSO files that have been pre-stored in NAND memory or other areas and update dynamic modules through downloading, etc.）
<LI>The user can specify links.
</UL>
<H3>Drawbacks</H3>
<UL>
<LI>Because the module includes symbol information, it is larger than REL. (By approximately the same number of bytes as the character count.)
<LI>The user must manage access to dynamic modules from static modules.
<LI>Because dynamic modules can be accessed from static modules, it is harder to delete code by optimizing compilation.
<LI>Because resolution is done using symbol names, more processing is required for linking than with REL.
</UL>
<H3>Procedural Differences</H3>
<UL>
<LI>The static module information (the <CODE>.sel</CODE> file) is required for initializing the link list.
</UL>

<h2>Making Relocatable Modules</h2>
<p>
<H3>1. Create the partially linked ELF files.</H3>
<P>The RSO library uses the static linker <B>partial link</B> option. Each dynamic (relocatable) module is made from a separate set of partially linked files. Using the partial link option (<CODE>-r</CODE>), the linker can create an <CODE>.elf</CODE> file that includes unresolved external reference symbols. The unresolved symbols of the dynamic module are resolved when the application is run.</P>
<P>Three functions can be defined for a dynamic module: <CODE>_prolog</CODE>, <CODE>_epilog</CODE>, and <CODE>_unresolved</CODE>. <CODE>_prolog</CODE> and <CODE>_epilog</CODE> can be called from static modules or from other dynamic modules loaded in main memory. <CODE>_unresolved</CODE> is automatically called when the module makes a function call to an external function that has not been linked into the main memory.</P>
<p>The linker command file for the dynamic modules consists of the <CODE>&lt;dolphin/eppc.lcf&gt;</CODE> file with <CODE>FORCEFILES</CODE> and <CODE>FORCEACTIVE</CODE> added to it. <CODE>FORCEFILES</CODE> includes the target files, and <CODE>FORCEACTIVE</CODE> includes <CODE>__global_destructor_chain</CODE>.
</p>
<p>In the sample this file is output in <CODE>.plf</CODE> format.
</p>
<P><STRONG><EM>Note: </EM></STRONG> A relocatable module cannot have a small data section. The small data section base registers (r2 and r13) are reserved for the static module. To prevent the compiler from generating small data sections, specify the compiler options <CODE>-sdata 0 -sdata2 0</CODE> when compiling the relocatable modules.</P>
<P>The RSO file is large when it is made from a PLF file with debugging information. If you want a smaller file size make the RSO file from a PLF file with no debugging information (for example, built using <CODE>NDEBUG</CODE>).</P>

<H3>2. Create a dynamic module file from the partially linked ELF files.</H3>
<p>
Run the <CODE><a href="./tools/makerso.html">makerso</a></CODE> tool to create a dynamic module file (<code>.rso</code>) from a partially linked <CODE>.plf</CODE> file.
</p>
<TABLE border="1" width="95%">
  <TBODY>
    <TR>
      <TD width="100%">
      <PRE><CODE>
% makerso.exe a.plf -a</CODE></PRE>
      </TD>
    </TR>
  </TBODY>
</TABLE>

<H3>3. Create a static module linker command file and symbol list from all dynamic module files.</H3>
<p>Run the <CODE><a href="./tools/makelcf.html">makelcf</a></CODE> tool to create a static module linker command file and symbol list from all dynamic module files.<br>The linker command file is generated by adding the <CODE>FORCEACTIVE</CODE> list to the <CODE>&lt;dolphin/eppc.lcf&gt;</CODE> file.<br>
</p>
<p>The following shows how to generate a static module linker command file as <CODE>static.lcf</CODE> and a symbol list as <CODE>symbol.lst</CODE>.
</p>
<TABLE border="1" width="95%">
  <TBODY>
    <TR>
      <TD width="100%">
      <PRE><CODE>
% makelcf.exe -o static.lcf -s symbol.lst -t eppc.lcf a.rso b.rso
</CODE></PRE>
      </TD>
    </TR>
  </TBODY>
</TABLE>
<H3>4. Build the program static modules.</H3>
<p>Link the static modules of the program with the linker command file generated in the previous section. Link all static libraries to the static module.
</p>
</p>
<H3>5. Generate static module information from the static ELF file.</H3>
<p>Use the <CODE><a href="./tools/makerso.html">makerso</a></CODE> tool to create static module information from the static <CODE>.elf</CODE> file and the symbol list generated in section 3.
</p>
<p>
The following shows how to generate a static module information as a <CODE>static.sel</CODE> file.
</p>
<TABLE border="1" width="95%">
  <TBODY>
    <TR>
      <TD width="100%">
      <PRE><CODE>
% makerso.exe static.elf -e symbol.lst
</CODE></PRE>
      </TD>
    </TR>
  </TBODY>
</TABLE>

</p>

<h2>Using Dynamic Modules</h2>
<p><B>Note:</B> The game application performs memory allocation and deallocation for loading dynamic modules and loading dynamic modules from game discs.<br>The dynamic module loaded into main memory has type <code>RSOObjectHeader</code> data, followed by the module code and data sections.<br>Static module information has the same data structure as dynamic modules, but without the code, the import information, or the internal processing information.
</p>
<H3>1. Loading Individual Modules</H3>
<p>The following is an example of loading modules.
</p>
<TABLE border="1" width="95%">
  <TBODY>
    <TR>
      <TD width="100%">
      <PRE><CODE>
DVDFileInfo     fileInfo;
s32             length;
RSOObjectHeader* module;

DVDOpen(&quot;a.rso&quot;, &fileInfo);
length = (s32) OSRoundUp32B(DVDGetLength(&fileInfo));
module = OSAllocFromArenaLo((u32) length, 32);
DVDRead(&fileInfo, module, length, 0);
DVDClose(&fileInfo);</CODE></PRE>
      </TD>
    </TR>
  </TBODY>
</TABLE>
<H3>2. Initializing the Linked List</H3>
<p>Use <code><a href="./RSOListInit.html">RSOListInit</a></code> to initialize the linked list.<br>Static module information is set at this time.<br>The static module information is used to obtain the address of a function or variable inside the static module when it is referenced by a dynamic module.
</p>
<TABLE border="1" width="95%">
  <TBODY>
    <TR>
      <TD width="100%">
      <PRE><CODE>
RSOListInit(staticModule);</CODE></PRE>
      </TD>
    </TR>
  </TBODY>
</TABLE>
<H3>3. Registering the Dynamic Module to the Linked List</H3>
<p>
Use <code><a href="./RSOLinkList.html">RSOLinkList</a></code> to link the dynamic module.<br>The <code><I>bss</I></code> argument is a pointer to the section used as a BSS section (a section initialized with 0s). It is allocated and specified by the programmer.<br>The required BSS section size is given by <CODE>RSOObjectHeader.bssSize</CODE>.<br>After linking a module, the game is given the choice to call the <code>prolog</code> function (a member variable of the <code>RSOObjectHeader</code> structure).
</p>
<TABLE border="1" width="95%">
  <TBODY>
    <TR>
      <TD width="100%">
      <PRE><CODE>
void *bss;
// Allocate BSS region
bss = OSAllocFromArenaLo(module-&gt;bssSize, 32);
RSOLinkList(module, bss);
((u32 (*)(void)) module-&gt;prolog)();</CODE></PRE>
      </TD>
    </TR>
  </TBODY>
</TABLE>
<H3>4. Removing the Dynamic Module from the Linked List</H3>
<p>
If the loaded module becomes unnecessary, call <code><a href="./RSOUnLinkList.html">RSOUnLinkList</a></code> to free the memory space for another purpose.<br>Immediately before unlinking a module, the game is given the choice to call the <code>epilog</code> function (a member variable of the <code>RSOObjectHeader</code> structure).
</p>
<TABLE border="1" width="95%">
  <TBODY>
    <TR>
      <TD width="100%">
      <PRE><CODE>
((void (*)(void)) module-&gt;epilog)();
RSOUnLinkList(module);</CODE></PRE>
      </TD>
    </TR>
  </TBODY>
</TABLE>

<h2>Partial Memory Deallocation of Relocatable Modules</h2>
<p>The <code><a href="./RSOLinkList.html">RSOLinkListFixed</a></code> function links the specified module and deallocates part of the memory occupied by the dynamic module.<br>Once the module is linked using the <code><a href="./RSOLinkList.html">RSOLinkListFixed</a></code> function, the memory space that comes after (specified by <code><a href="./RSOGetFixedSize.html">RSOGetFixedSize</a></code>) can be used for any purpose (for example, for the BSS area).<br>However, several restrictions may apply, depending on the deallocation timing. (See <code><a href="./RSOLinkList.html">RSOLinkListFixed</a></code> for details.)<br>Also note that the location specified by <code><a href="./RSOGetFixedSize.html">RSOGetFixedSize</a></code> is converted from the file offset to the virtual address when the module is linked. <br>
</p>
<p>
The following is an example of partial deallocation of module memory and its reuse as a BSS region.
</p>
<TABLE border="1" width="95%">
  <TBODY>
    <TR>
      <TD width="100%">
      <PRE><CODE>
int             fixed_level     // deallocation stage
RSOObjectHeader* module;        // Target dynamic module
u32             fixed_size;
u32             new_arenaLo;
u32             old_arenaLo;

//
fixed_size = RSOGetFixedSize(module,fixed_level);
//
bss = (u8 *)((u32)module + fixed_size);
// 32 byte alignment
bss = (u8*) OSRoundUp32B(bss);

new_arenaLo = ((u32)bss + (u32)module-&gt;bssSize);
new_arenaLo = OSRoundUp32B(new_arenaLo);
old_arenaLo = (u32)OSGetMEM1ArenaLo();
//
if (module-&gt;bssSize &gt; 0) {
    if(old_arenaLo &lt; new_arenaLo) {
        // If the region is to increase, increase before RSOLocateObjectFixed
        OSSetMEM1ArenaLo((void*)new_arenaLo);
    }
} else {
    bss = NULL;
}
// Link process
RSOLinkListFixed(module,bss,i_fixed_level);
// If the region is to decrease, decrease after RSOLocateObjectFixed
if(bss == NULL || old_arenaLo &gt; new_arenaLo) {
    OSSetMEM1ArenaLo((void*)new_arenaLo);
}</CODE></PRE>
      </TD>
    </TR>
  </TBODY>
</TABLE>

<h2>Required Alignment Conditions for Relocatable Modules</h2>
<p>
Dynamic modules and <CODE>bss</CODE> sections both have address-alignment constraints. The dynamic module must be aligned at the maximum alignment value required by the <CODE>.init</CODE>, <CODE>.text</CODE>, <CODE>.ctor</CODE>, <CODE>.dtor</CODE>, <CODE>.rodata</CODE>, and <CODE>.data</CODE> sections. A <CODE>bss</CODE> section must be aligned at the maximum alignment value required by the data item within the <CODE>bss</CODE> section. Typically, both dynamic modules and <CODE>bss</CODE> sections require 8-byte alignment.
</p>
<h2>Accessing a Dynamic Module's Functions and Variables from the Static Module</h2>
<p>
To access dynamic module functions and variables from the static module, the address is acquired by using <code><a href="./RSOFindExportSymbolAddr.html">RSOFindExportSymbolAddr</a></code> based on the linked module information and label name.<br>
</p>
<p>
The following example acquires and uses the addresses of the <code>int foo(int a);</code> function and the <code>int g_int;</code> variable from the dynamic module.<br>
</p>
<TABLE border="1" width="95%">
  <TBODY>
    <TR>
      <TD width="100%">
      <PRE><CODE>
int (*foo)(int);
int *g_int;

foo = (int (*)(int)) RSOFindExportSymbolAddr(module,&quot;foo&quot;);
g_int = (int *)RSOFindExportSymbolAddr(module,&quot;g_int&quot;);

*g_int += foo(3);
</CODE></PRE>
      </TD>
    </TR>
  </TBODY>
</TABLE>
<h2>Notes</h2>
<p>

</p>
<h2>Note: Using C++ Global Constructors in Dynamic Modules</h2>
<p>
If using C++ global constructors in relocatable modules, you must manually call global constructors and destructors from the module <code>_prolog</code> and <code>_epilog</code>, Code examples for each case follow below.
</p>
<TABLE border="1" width="95%">
  <TBODY>
    <TR>
      <TD width="100%">
      <PRE><CODE>#ifdef __cplusplus
extern &quot;C&quot; {
#endif

typedef void (*voidfunctionptr) (void); /* ptr to function returning void */
__declspec(section &quot;.init&quot;) extern voidfunctionptr _ctors[];
__declspec(section &quot;.init&quot;) extern voidfunctionptr _dtors[];

void _prolog(void);
void _epilog(void);
void _unresolved(void);

#ifdef __cplusplus
}
#endif

void _prolog(void)
{
    voidfunctionptr *constructor;

    /*
     *  call static initializers
     */
    for (constructor = _ctors; *constructor; constructor++) {
        (*constructor)();
    }
}

void _epilog(void)
{
    voidfunctionptr *destructor;

    /*
     *  call destructors
     */
    for (destructor = _dtors; *destructor; destructor++) {
        (*destructor)();
    }
}</CODE></PRE>
      </TD>
    </TR>
  </TBODY>
</TABLE>
<P>In addition, make sure that each dynamic module is linked to <code>global_destructor_chain.c</code> (in the <code>$(CWFOLDER)/PowerPC_EABI_Support/Runtime/Src</code> folder). Linking to this file guarantees that each global destructor is called every time the <code>_epilog</code> function of the module is called. Otherwise, module global variables in each module are linked to the global destructor chain in the <STRONG>static</STRONG> module, and if no static module exists, destructors are never called. <B>Note:</B> Since <CODE>Runtime.PPCEABI.H.a</CODE> uses small data sections and contains unnecessary functions, dynamic modules cannot be linked to it.</P>

<h2>Note: Use caution when placing a dynamic module in external main memory (the MEM2 region)</h2>
<p>
Typically, branch instructions (<CODE>bx</CODE>) have only a 28-bit offset (±32 MB). Therefore, when a relocatable module is placed in external main memory (<CODE>MEM2</CODE>), it cannot access functions or variables in internal main memory (<CODE>MEM1</CODE>).<br>Avoid this issue by using <CODE>pragma</CODE> or by using <code><a href="./RSOLinkFar.html">RSOLinkFar</a></code> and <code><a href="./RSOLinkJump.html">RSOLinkJump</a></code>.<BR>
</p>
<H3>1. Using Pragma</H3>
<p>
Indicate to the compiler that the module needs to be branched in a 32-bit absolute address, using <CODE>pragma</CODE>.<BR>An example is given of branching the <CODE>foo</CODE> function (located in <CODE>MEM1</CODE>) to an absolute address. This applies whether the target function is in a static module or a dynamic (relocatable) module.<BR>Also take similar precautions when calling functions in <CODE>MEM2</CODE> from a dynamic module in <CODE>MEM1</CODE>.
</p>
<TABLE border="1" width="95%">
  <TBODY>
    <TR>
      <TD width="100%">
      <PRE><CODE>
#pragma section code_type &quot;.text&quot; data_mode=far_abs code_mode=far_abs
#pragma section RX &quot;.init&quot; &quot;.init&quot; data_mode=far_abs code_mode=far_abs

void foo(void);

#pragma section code_type &quot;.text&quot; data_mode=far_abs code_mode=pc_rel
#pragma section RX &quot;.init&quot; &quot;.init&quot; data_mode=far_abs code_mode=pc_rel
</CODE></PRE>
      </TD>
    </TR>
  </TBODY>
</TABLE>
<p>
<B>Note</B> as of 2006/06/15:<br>Certain run-time codes may not be properly called in 32-bit codes in the release version.<br>As a temporary workaround, use the <CODE>use_lmw_stmw pragma</CODE> to avoid using those runtime codes.<br>The <CODE>pragma</CODE> directive should be applied to the source of modules placed in <CODE>MEM2</CODE>.<br>The compile option &quot;<code>-use_lmw_stmw on</code>&quot; may also be used for the same effect.<br>
</p>
<TABLE border="1" width="95%">
  <TBODY>
    <TR>
      <TD width="100%">
      <PRE><CODE>
// Tentatively set &quot;<CODE>use_lmw_stmw</CODE>&quot; to <CODE>ON</CODE>.
#pragma use_lmw_stmw on
</CODE></PRE>
      </TD>
    </TR>
  </TBODY>
</TABLE>
<H3>2. Using RSOLinkFar</H3>
<p>
Because using just the standard <code><a href="./RSOLink.html">RSOLink</a></code> causes this issue, re-link the modules located in main memory (both <CODE>MEM1</CODE> and <CODE>MEM2</CODE>) using <code><a href="./RSOLinkFar.html">RSOLinkFar</a></code>. <code><a href="./RSOLinkFar.html">RSOLinkFar</a></code> places relay jump codes in <code><I>buff</I></code>. The linking modules then link to these jump codes to access the referenced modules in <CODE>MEM2</CODE>.<br>In the following example function <code>LinkFar</code>, the linked module (<code>i_rsoImp</code>) and the referenced module (<code>i_rsoEx</code>) are linked using a relay jump code. The return value is a pointer to the allocated buffer.<br>The required buffer size is obtained using <code><a href="./RSOGetFarCodeSize.html">RSOGetFarCodeSize</a></code>, and then that region is allocated and linked using <code><a href="./RSOLinkFar.html">RSOLinkFar</a></code>.
</p>
<TABLE border="1" width="95%">
  <TBODY>
    <TR>
      <TD width="100%">
      <PRE><CODE>
static u32 *LinkFar(RSOObjectHeader *i_rsoImp,RSOObjectHeader *i_rsoExp)
{
    int a_size = RSOGetFarCodeSize(i_rsoImp,i_rsoExp);
    u32 *a_buff;

    //
    if(a_size == 0) {
        // not needed
        return NULL;
    }
    //
    a_buff = OSAllocFromArenaLo((u32)a_size,4);
    //
    RSOLinkFar(i_rsoImp,i_rsoExp,a_buff);
    return a_buff;
}
</CODE></PRE>
      </TD>
    </TR>
  </TBODY>
</TABLE>
<p>
<B>Note:</B> Allocate the buffer from the same main memory (<CODE>MEM2</CODE> or <CODE>MEM1</CODE>) as the module being linked (<CODE>i_rsoImp</CODE>).<br>In addition, the code in the module is overwritten normally after linking. Thus, when using <code><a href="./RSOLinkList.html">RSOLinkListFixed</a></code>, proceed to <code><a href="./RSOFixedLevel.html">RSO_FL_INTERNAL</a></code> at the release stage.
</p>

<H3>3. Using RSOLinkJump</H3>
<p>
<code><a href="./RSOLinkJump.html">RSOLinkJump</a></code> creates a relay code to the module being referenced. The referencing side then uses it to link.<br>To create a relay code, use <code><a href="./RSOGetJumpCodeSize.html">RSOGetJumpCodeSize</a></code> to obtain the necessary buffer size, and then use <code><a href="./RSOMakeJumpCode.html">RSOMakeJumpCode</a></code> to create the relay code.<br>

</p>
<TABLE border="1" width="95%">
  <TBODY>
    <TR>
      <TD width="100%">
      <PRE><CODE>
static u32 *MakeJumpCode(RSOObjectHeader *i_rsoExp)
{
    int a_size = RSOGetJumpCodeSize(i_rsoExp);
    u32 *a_buff;

    //
    if(a_size == 0) {
        // not needed
        return NULL;
    }
    //
    a_buff = OSAllocFromArenaLo((u32)a_size,4);
    //
    RSOMakeJumpCode(i_rsoExp,a_buff);
    return a_buff;
}
</CODE></PRE>
      </TD>
    </TR>
  </TBODY>
</TABLE>
<p>
Link with the created buffer and <code><a href="./RSOLinkJump.html">RSOLinkJump</a></code>.
</p>
<TABLE border="1" width="95%">
  <TBODY>
    <TR>
      <TD width="100%">
      <PRE><CODE>
{
    u32 *buff = MakeJumpCode(rsoExp);
    RSOLinkJump(rsoImp,rsoExp,buff);
}
</CODE></PRE>
      </TD>
    </TR>
  </TBODY>
</TABLE>

<H2>Revision History</H2>
<p>
2009/10/13 Revised the name of the LCF file used for partial linking.<br> 2009/07/21 Explained the relationship between RSO and PLF file sizes. <br> 2006/12/19 Explained <code>RSOLinkJump</code>.<br>2006/10/25 Added a description for <code>RSOLinkFar</code>.<br>2006/06/14 Initial version.<br>
</p>

<hr><p>CONFIDENTIAL</p></body>
</html>