TechnicalNotes/Dll/DllManual.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML LANG="ja">

<HEAD>
    <META http-equiv="Content-Type" content="text/html; charset=utf-8">
    <META http-equiv="Content-Style-Type" content="text/css">

    <TITLE>DLL Manual</TITLE>

    <STYLE>
        h1.left
        {
            color: #46f;
            font-size: 100%;
        }
        ul.left, ul.left ul
        {
            margin: 0;
            padding: 0;
        }
        ul.left
        {
            font-size: 0.8em;
        }
        ul.left li
        {
            margin: 0;
            padding: 0;
            margin-left: 1em;
            line-height: 1.5em;
        }
        ul.left li a
        {
            margin: 0;
            padding: 0;
        }

        H1
        {
            font-weight         : bold;
            font-size           : 250%;
            text-align          : left;
            color               : #46f;
            margin-bottom       : 0px;
        }

        H2
        {
            font-weight         : normal;
            font-size           : 180%;
            margin              : 24pt 0pt 6pt 0pt;
            border-bottom-style : solid;
            border-bottom-width : 1px;
        }

        H3
        {
            font-weight         : bold;
            font-size           : 120%;
            border-bottom-style : solid;
            border-bottom-width : 1px;
            width: 75%;
            margin              : 18pt 0pt 6pt 30pt;
        }

        H4
        {
            font-weight         : bold;
            font-size           : 100%;
            margin              : 12pt 0pt 6pt 30pt;
        }

        H5
        {
            font-weight         : bold;
            margin              : 12pt 0pt 6pt 30pt;
        }

        H6
        {
            font-weight         : bold;
            margin              : 12pt 0pt 6pt 30pt;
        }

        DIV.date
        {
            text-align          : right;
            color               : #46f;
            margin-bottom       : 30pt;
            line-height         : 150%;
        }

        P
        {
            margin              : 0pt 0pt 12pt 30pt;
            line-height         : 150%;
        }

        OL,UL,DL
        {
            margin              : 6pt 0pt 6pt 50pt;
        }
        OL OL, UL UL
        {
            margin-left: 3em;
        }

        DT
        {
            font-family         : "Courier New", monospace;
            margin-top : 0.3em;
            margin-bottom : 0.3em;
        }
        DD
        {
            margin-top : 0.3em;
            margin-bottom : 0.6em;
        }

        PRE
        {
            font-family         : "Courier New", monospace;
            font-weight         : normal;

            margin              : 0pt 0pt 20pt 50pt;
            padding             : 2pt 8pt 2pt 8pt;
            background-color    : #eee;

            border-style        : solid;
            border-width        : 1px;
        }
        em
        {
            font-style: normal;
            color: red;
        }
        TABLE
        {
            margin-left         : 40pt;
            margin-bottom       : 20pt;
            border-color        : #aaa;
            border-width        : 1pt;
            border-style        : solid;
        }
        TD
        {
            font-style          : normal;
            padding             : 2pt 4pt 2pt 4pt;

            border-color        : #aaa;
            border-width        : 1pt;
            border-style        : solid;
        }
        div.footer
        {
            border-color: black;
            padding-top: 0.5em;
            border-top-style    : solid;
            border-top-width    : 1px;
            width:              100%;
            margin-top: 2em;;
        }
        div.footer span
        {
            color               : #46f;
            float: right;
        }
        table
        {
            border-collapse:    collapse;
        }
        table td
        {
        }
        table th
        {
            border              : solid 1px;
        }
        ul
        {
            margin-top: 1em;
            margin-bottom: 1em;
        }
        span.here
        {
            color: red;
        }
        DL.history
        {
            margin: 1em;
        }
        DL.history DT
        {
            font-family         : sans-serif;
            font-weight         : bold;
            font-size           : 0.8em;
            margin              : 0px;
        }
        DL.history DD
        {
            font-size           : 0.9em;
            margin              : 0px 0px 4px 0px;
        }

    </STYLE>
    <SCRIPT type="text/javascript">
    <!--
        function DeleteRule(index)
        {
            var ss = document.styleSheets.item(0);

            if( ss.removeRule )
            {
                ss.removeRule(index);
            }
            else
            {
                ss.deleteRule(index);
            }
        }
        function OnClickAnchor(e, anchor)
        {
            window.parent.frames[1].location.hash = anchor;

            if( e.preventDefault )
            {
                e.preventDefault();
            }
            else
            {
                e.returnValue = false;
            }
        }
        function TravLeft(obj)
        {
            var ary = new Array();
            var index = 0;

            for( var i = 0; i < obj.childNodes.length; ++i )
            {
                var c = obj.childNodes.item(i);

                if( c.nodeType == 1 )
                {
                    if( c.tagName == "H2" || c.tagName == "H3" )
                    {
                        var text  = "--no name--";

                        var anchor = "name-" + index;
                        index++;

                        if( c.hasChildNodes() )
                        {
                            var a = c.childNodes.item(0);

                            if( a && a.tagName == "A" )
                            {
                                text  = a.innerHTML;
                            }
                            else
                            {
                                text  = c.innerHTML;
                            }
                        }

                        ary.push([c.tagName.substr(1,1), "<a target=\"right\" href=\"?right#" + anchor + "\" onclick=\"OnClickAnchor(event, '" + anchor + "')\">" + text + "</a>"]);
                    }
                    else
                    {
                        ary = ary.concat(TravLeft(c));
                    }
                }
            }

            return ary;
        }
        function TravRight(obj)
        {
            var index = 0;

            for( var i = 0; i < obj.childNodes.length; ++i )
            {
                var c = obj.childNodes.item(i);

                if( c.nodeType == 1 )
                {
                    if( c.tagName == "H2" || c.tagName == "H3" )
                    {
                        var anchor = "name-" + index;
                        index++;

                        c.innerHTML = "<a name=\"" + anchor + "\">" + c.innerHTML + "</a>"
                    }
                    else
                    {
                        TravRight(c);
                    }
                }
            }
        }
        function OnLoad_Left()
        {
            var test = TravLeft(document.body);
            var test2 = "";
            var level = 2;

            test2 += "<h1 class='left'>" + document.title + "</h1>";
            test2 += "<ul class='left'>";
            for( var i in test )
            {
                while( test[i][0] > level )
                {
                    level++;
                    test2 += "<ul>";
                }
                while( test[i][0] < level )
                {
                    level--;
                    test2 += "</ul>";
                }

                test2 += "<li>" + test[i][1];
            }
            test2 += "</ul>";

            document.body.innerHTML = test2;
            DeleteRule(0);
        }
        function OnLoad_Right()
        {
            TravRight(document.body);
        }
        function OnLoad_Frame()
        {
            var myname = location.pathname.substr(location.pathname.lastIndexOf("/") + 1);

            var f = document.createElement("frameset");
            var l = document.createElement("frame");
            var r = document.createElement("frame");

            f.appendChild(l);
            f.appendChild(r);
            f.cols = "250,*";

            l.src  = myname + "?left"  + location.hash;
            r.src  = myname + "?right" + location.hash;
            l.name = "left";
            r.name = "right";

            var h = document.documentElement;
            var b = h.getElementsByTagName("body").item(0);

            h.replaceChild(f, b);
        }


        if( ! window.opera )
        {
            var search = location.search;

            if( search == "?left" )
            {
                window.onload = OnLoad_Left;
            }
            else if( search == "" )
            {
                window.onload = OnLoad_Frame;
            }
            else if( search == "?right" )
            {
                window.onload = OnLoad_Right;
            }

            if( search != "?right" )
            {
                var ss = document.styleSheets.item(0);

                if( ss.addRule )
                {
                    ss.addRule("body", "display: none", 0);
                }
                else
                {
                    ss.insertRule("body {display: none}", 0);
                }
            }
        }
    //-->
    </SCRIPT>
</HEAD>

<BODY>


<H1>DLL Manual</H1>
<DIV class="date">(2012.06.22)</DIV>


<H2>Introduction</H2>

<H3>About This Document</H3>
<P>
    This document provides information about the DLL mechanism that the CTR-SDK provides.
</P>
<ul>
    <li>DLL Basics
    <li>Features and Limitations of DLLs
    <li>Basic API Usage
    <li>Special Features
</ul>

<P>
    Information about the following can be found in the referenced documentation.
</P>
<ul>
    <li>Procedures for creating DLLs using the SDK build system:<br><a href="BuildSystemManualForDll.html" target="_parent">CTR-SDK Build System Manual (for DLLs)</a>
    <li>Information about developing your own build system:<br><a href="BuildSystemDevelopmentGuideForDll.html" target="_parent">Guide to Developing a Build System (for DLLs)</a>
<li>Information about developing a more sophisticated build system:<br><a href="BuildSystemDevelopmentGuideForDllAdvanced.html" target="_parent">Guide to Developing a Build System (for High-Level DLLs)</a>
</ul>

<P>
    This document assumes basic knowledge of <CODE>CTR-SDK</CODE> terminology. See <a href="../Glossary/Glossary.html" target="_parent">CTR-SDK Terminology</a> for a glossary of basic CTR-SDK terms.
</P>

<H3>Notation Used in This Document</H3>
<P>
    This document sometimes puts content in colored boxes like the one below to indicate that it is sample source code.
</P>
<pre>
nn::ro::Initialize(pCrs, crsSize);
</pre>

<P>
    Sample source code uses the following user-defined functions in order to make the code easier to understand. You must implement processing equivalent to these functions in your application.
</P>
<dl>
    <dt>s64 GetFileSize(const wchar_t* path)
    <dd>
    Returns the size of the file specified by <SPAN class="argument">path</SPAN>.

    <dt>void* AllocateMemory(size_t size, int alignment)
    <dd>
    Allocates a memory area of <SPAN class="argument">size</SPAN> bytes, in accordance with the alignment restrictions specified by <SPAN class="argument">alignment</SPAN>.

    <dt>void LoadFile(void* pBuffer, const wchar_t* path, size_t size)
    <dd>
    Reads <SPAN class="argument">size</SPAN> bytes from the file specified by <SPAN class="argument">path</SPAN> into <SPAN class="argument">pBuffer</SPAN>.
</dl>


<H2>Terminology</H2>
<P>
    This section defines terminology relating to the DLL mechanism provided by the CTR-SDK.
</P>
<P>
    The meanings and usage of terms used in this document and the CTR-SDK may differ from their general meanings and usage.
</P>


<dl>
    <dt>Executable code
    <dd>
    Sequences of machine code interpreted and executed by the CPU, and constants and variables referenced directly from it.

    <dt>Module
    <dd>
    A chunk of execution code divided into a meaningful unit.

    <dt>Static module
    <dd>
    The main application module, which contains <CODE>nnMain</CODE>. This is the first module that is executed when application execution begins.

    <dt>Dynamic module
    <dd>
    A module that can be loaded into memory and used dynamically.

    <dt>DLL
    <dd>
    The mechanism for implementing a dynamic module. It can also refer to a dynamic module itself.

    <dt>Symbol
    <dd>
    A meaningful location in a module. In most cases, the symbol is named, but sometimes it is not.

    <dt>See Also
    <dd>
    Use a symbol from another module. This refers to calling a function defined in another module, or reading/writing a variable defined in another module.

    <dt>Resolve
    <dd>
    Make the symbol being referenced available. It determines the address of a symbol so that a function can be called, or a variable read/written.

    <dt>Export
    <dd>
    Make a module's symbol available for reference from another module. A symbol can only be referenced if it has been exported.

    <dt>Export type
    <dd>
    Indicates the format in which information is referenced from other modules. Three export types are available in <CODE>ro</CODE>: <I>name</I>, <I>index</I>, and <I>offset</I>.

    <dt>Import
    <dd>
    Declares a reference. The linker attempts to resolve symbols that have not been imported at link time. This normally results in an undefined symbol error.

    <dt>Export
    <dd>
    Same as &quot;export.&quot;

<!--     <dt>基本スタイル     <dd>     このドキュメントおよび SDK のビルドシステムがサポートする     5 種類の DLL の使い方のこと。     標準スタイル、ライブラリスタイル、プラグインスタイル、RSO スタイル、REL スタイルの 5 種類。      <dt>共有ライブラリ     <dd>     複数の静的モジュールから単一の DLL を使用することを目的として構成した DLL のこと。     <br>     共有ライブラリ → 静的モジュールの順で開発が行われる。      <dt>RSO     <dd>     RVL-SDK で提供されている DLL 実装の一形式。      <dt>REL     <dd>     RVL-SDK で提供されている DLL 実装の一形式。      <dt>プラグイン     <dd>     単一の静的モジュールから同じ I/F をもつ複数の DLL を使用することを目的として構成した DLL のこと。     <br>     静的モジュール → プラグインの順で開発が行われる。 -->

    <dt><CODE>ro</CODE>
    <dd>
    A format for implementing DLLs provided by the CTR-SDK.

    <dt>CRO Files
    <dd>
    The dynamic-module file format used by <CODE>ro</CODE>.

    <dt>CRR Files
    <dd>
    A file storing DLL registration information. It can store information for one or more CRO files.

    <dt><CODE>cro.rlt</CODE>
    <dd>
    A file that stores DLL registration information. This file stores information for one CRO file. It is converted into a CRR file for use.

    <dt><CODE>edit</CODE>
    <dd>
    A steering file used by the <CODE>ARMCC</CODE> linker.

    <dt>CRS Files
    <dd>
    A file storing information about a static module.

    <dt><CODE>xrl</CODE>
    <dd>
    A file storing export/reference symbol information for a module.

    <dt><CODE>uae</CODE>
    <dd>
    A command-line option file specified to the <CODE>ARMCC</CODE> linker.

    <dt><CODE>ro</CODE> library
    <dd>
    The <a href="../../api/nn/ro/Overview.html">nn::ro namespace</a> section of the API provided by the CTR-SDK. It is a collection of functions for using DLLs.

    <dt>
    <dd>


</dl>


<H2>DLLs</H2>

<H3>Static and Dynamic Modules</H3>
<P>
    If an application does not use dynamic modules, then all its executable code is collected into a single file.

    When an application starts, all its executable code is loaded into memory and maintained there until the application exits. The executable code is never modified while the application is running.

    The executable code that is loaded upon startup is called the &quot;static module.&quot;
</P>
<P>
    Meanwhile, if the application uses dynamic modules, then it can split up its executable code into multiple modules.

    When the application starts, only the static module is loaded into memory. The static module is then able to load the dynamic modules, thus running executable code including dynamic modules that can be loaded into and released from memory during program execution.
</P>


<H3>What You Can Do with a DLL</H3>

<H4>Conserve Memory</H4>
<P>
    You can reduce the amount of memory that your code uses by breaking up your application into multiple modules, and loading them into memory only when needed, freeing them afterward.
</P>
<P>
    For example, you could put single-player mode and multiplayer mode into separate DLLs, and load just one of them depending on the play mode. This will reduce your application's memory footprint by the size of the other mode.
</P>

<H4>Shorten Startup Time</H4>
<P>
    When your application is launched, it starts running after all of its static modules have been loaded into memory. Thus the time it takes from the application's launch instruction until <code>nnMain</code> starts executing is proportional to the size of the static modules. You can shorten the time it takes for your application's first screen to appear by putting just the minimum code needed to show the first screen in your static module, and putting the other portions of your application into DLLs, and loading them after the first screen appears.
</P>

<!-- <H4>追加プログラムの配信</H4> <P>     DLL を配信することで、販売後のアプリケーションにプログラムを追加することができます。 </P> -->


<h3>Features and Limitations of the <CODE>ro</CODE> Format</h3>
<P>
The DLL mechanism provided by the CTR-SDK is called &quot;ro.&quot;
</P>

<h4>Features</h4>
<P>
    The <CODE>ro</CODE> format features the following differences from other DLL implementations.
</P>

<ul>
<li>Thee export types<br>One of three formats can be used for symbol resolution: <CODE>offset</CODE>, <CODE>index</CODE>, or <CODE>name</CODE>. Although you can select the format for each symbol individually, the SDK's build system only supports selection at the module level. See <a href="BuildSystemManualForDll.html" target="_parent">CTR-SDK Build System Manual (for DLLs)</a> or <a href="BuildSystemDevelopmentGuideForDll.html" target="_parent">Guide to Developing a Build System (for DLLs)</a> for information about specifying export types.

<li>Automatic resolution of references between modules<br>The build system automatically resolves references between modules just by loading them, making functions and variables available. You can also obtain pointers to symbols manually.

<li>The application developer loads DLLs into memory<br>The application developer is responsible for loading DLLs into memory and handling where they are allocated in memory.

<li>Support for C++<br>You can code DLLs in C++. You can also reference and resolve C++ symbols between modules. <br><STRONG>Note:</STRONG> If you get pointers to C++ symbols manually, you must use the mangled names.

<li>Ability to pass C++ exceptions across module boundaries<br>You can <CODE>throw</CODE> an exception from one module and <CODE>catch</CODE> it in another.

<li>Support for automating imports and exports<br>Although this is not a feature of the <CODE>ro</CODE> format itself, the SDK provides a tool to support automation of imports and exports. When you use the SDK's build system, it uses this tool to perform imports and exports automatically. You can also use this tool to strip dead code automatically.
</ul>

<h4>Upper Limit</h4>
<P>
    The limitations of the <CODE>ro</CODE> format are as follows.
</P>
<ul>
<li>Each module can export no more than 65,535 symbols by name.
<li>The maximum length of a symbol that can be exported by name is 8,192 characters.
</ul>

<h4><a name="restriction">Restrictions</a></h4>
<P>
    The <CODE>ro</CODE> format has the following restrictions:
</P>
<ul>
<li>Template class static member variables defined in a header and instances of static local variables in inline functions must be included in static modules. For details, see <a href="#vague_linkage">Handling of Symbols with Multiple Definitions</a>.
<li>You cannot include symbols belonging to the C Runtime (CRT) in dynamic modules. These are always included in static modules. The CRT includes standard C functions, as well as <CODE>new</CODE>, <CODE>delete</CODE>, and other language features implemented as internal function calls, such as integer division and 64-bit arithmetic.
<li>You cannot define static variables or constants specifying an alignment greater than 8 bytes. Alignment restrictions greater than 8 bytes are ignored.
<li>Behavior may not be as intended when you use <CODE>weak</CODE> symbols and other features that are not part of the  C/C++ language standards.
</ul>
<P>
    In the <CODE>ro</CODE> format, you can make and use any static library (.a)  as a DLL. But because of these restrictions, if you intend to use a static library as a DLL, be sure to confirm with the library's creator that it can be made and used as a DLL.
</P>
<P>
    The static libraries  (.a) provided in the SDK must not be made and used as DLLs. That is prohibited.
</P>


<h3><CODE>ro</CODE> File Structure</h3>
<P>
    If you did not use DLLs, you would develop CTR applications by creating CXI and CCI files from AXF files. If you use DLLs, you must additionally create CRS, CRR, and CRO files.
</P>

<h4>CRS Files</h4>
<P>
    A CRS file stores reference and export information for static modules. It is used to resolve symbols between DLLs. It does not contain executable code.
</P>

<h4>CRR Files</h4>
<P>
    A CRR file contains CRO management information. It also contains information necessary for debugging DLLs.
</P>
<P>
    CRR files have an important limitation: they must be stored on the ROM-FS, directly under the &quot;.crr&quot; directory, which is in turn directly under the ROM-FS root directory (if the ROM-FS root directory is <code>/</code>, this directory will be <code>/.crr</code>). The <code>.crr</code> directory must not contain any file other than the CRR file.
</P>

<h4>CRO Files</h4>
<P>
    A CRO file is a dynamic module. It stores executable code and information necessary to resolve symbols between the application's various modules.
</P>


<H2>Creating Dynamic Modules</H2>

<H3>Creating the Source Code</H3>
<P>
    There are no special requirements for the source code of a dynamic module, with the exception of a few limitations. You can create them in the same manner as static modules. As with ordinary code, the only things you need to do in order to call functions and reference variables across modules are to share headers and code the calls and references.
</P>
<P>
    To read about the restrictions on dynamic modules, see <a href="#restriction">Restrictions.</a>
</P>
<P>
    You must add extra code to use DLL features. See <a href="#other_feature">Special Uses</a> for details.
</P>


<H3>Building DLLs</H3>
<P>
    See <a href="BuildSystemManualForDll.html" target="_parent">CTR-SDK Build System Manual (for DLLs)</a> if you will be using the SDK's build system. If you will be developing your own build system, see <a href="BuildSystemDevelopmentGuideForDll.html" target="_parent">Guide to Developing a Build System (for DLLs)</a>.
</P>


<H3><a name="choose_type">Selecting the Export Type</a></H3>
<P>
    The <CODE>ro</CODE> format has three export types. You must select which export types to use when you create your CRO file. The table below shows the differences between the various export types.
</P>
<table>
<tr><th><th>Name<th>Index<th>Offset
<tr><th>Size of referencing CRO file<td>Large<td>Small<td>Small
<tr><th>Size of exporting CRO file<td>Large<td>Small<td>0
<tr><th>Time required by <CODE>LoadModule</CODE><td>Long<td>Medium<td>Short
<tr><th>Getting pointer manually<td>Possible<td>Possible<td>Impossible
<tr><th>Creating referencing module first<td>Possible<td>Impossible<td>Impossible
<tr><th>Build steps<td>Normal<td>Normal<td>Many
</table>
<P>
    <CODE>Name</CODE> has the greatest functionality, followed by <CODE>index</CODE> and then <CODE>offset</CODE>, and greater functionality comes at a correspondingly greater cost.
</P>
<P>
    Normally, it is fine to choose <CODE>offset</CODE> as the export type. If you want to get pointers manually (using <a href="../../api/nn/ro/Module/GetPointer.html"><code>GetPointer</code></a>) or use a DLL that functions as a library, you will choose <CODE>index</CODE> or <CODE>name</CODE>, depending on your needs.
</P>

<H3>Using Static Libraries</H3>
<P>
    Static libraries can be embedded into dynamic modules. However, in addition to the <a href="#restriction"><CODE>ro</CODE> restrictions </a>, you should also note the following precaution:
</P>
<ul>
<li><b>Do not embed the same static library into multiple DLLs. </b><br>If you embed the same static library into multiple DLLs, then there will be multiple global variables, where there should only be one. So the internal state in the library will not be what you intended. In particular, if you create a mutual exclusion object (mutex) as a global variable, it will be as if the library is not conducting mutual exclusion, even though it is treating the mutex correctly. In this case, sometimes a bug will arise and sometimes it will not (depending on the timing) so debugging will be difficult. Moreover, since the coding will be correct in the source code, it will be extremely difficult to find the bug.
</ul>


<H2>Creating Static Modules</H2>
<H3>Creating the Source Code</H3>
<P>
    Some variables require special treatment. For more information, see <a href="#vague_linkage">Handling Symbols with Multiple Definitions</a>.<br/> Other than symbols with multiple definitions, there is nothing special that must be done to reference DLL functions and variables. You simply share headers and reference the normal way.
</P>
<P>
    In the <CODE>ro</CODE> format, the management of DLLs is left entirely up to the application, so to  prepare memory for use by DLLs and to load DLLs you need to implement everything with code in the application. For details, see <a href="#use_dll">Using DLLs</a>.
</P>
<P>
    In addition, you need to add extra code to use DLL features. See <a href="#other_feature">Special Uses</a> for details.
</P>


<H3>Building</H3>
<P>
    See <a href="BuildSystemManualForDll.html" target="_parent">CTR-SDK Build System Manual (for DLLs)</a> if you will be using the SDK's build system. If you will be developing your own build system, see <a href="BuildSystemDevelopmentGuideForDll.html" target="_parent">Guide to Developing a Build System (for DLLs)</a>.
</P>


<H3>Selecting the Export Type</H3>
<P>
You can select the export type, so the static module also exports symbols for the dynamic module.<br/> Selecting export types for static modules is the same as selecting export types for dynamic modules. For more information, see the <a href="#choose_type">dynamic modules</a> section.
</P>


<H2><a name="vague_linkage">Handling of Symbols with Multiple Definitions</a></H2>
<P>
    Symbols with multiple definitions require special treatment.
</P>

<H3>Symbols with Multiple Definitions in C++</H3>
<P>
    Usually, having multiple instances of the same symbol in a single program is not permitted in the C/C++ programming languages. However, for the following elements in C++, the same symbol can be included in multiple object files and used normally.
</P>
<ul>
    <li>Template instances
    <li>Inline functions that were not inlined.
    <li>Template class class member variables
    <li>Static local variables in inline functions
    <li>Type information.
    <li>Virtual tables
</ul>
<P>
    Symbols for these are merged appropriately by the linker during linking, and an adjustment is made so that all the symbols become one in the overall program.
</P>

<H3>Handling of Symbols with Multiple Definitions in <CODE>ro</CODE></H3>
<P>
    Because the symbols are merged by a linker, they must be merged in each module. Also, because plug-in type use is supported in <CODE>ro</CODE>, multiple modules are permitted to contain the same symbol. As a result, an instance of the symbols for the elements listed above exists in each module that is referenced.
</P>
<P>
    However, because usually symbols that represent variables among the elements listed above are used with the assumption that all references are made to a unique instance, unintended results may occur if different instances are referenced in each module.
</P>
<P>
    Processes for variables and elements other than variables are separated in <CODE>ro</CODE> in order to handle both situations. Among symbols that are defined in multiple modules, for symbols that represent variables an instance in the static module is always referenced, and all other symbols can be contained in every module.
</P>

<H3>Support for Symbols with Multiple Definitions</H3>
<P>
    As described above, when symbols that represent variables are defined in multiple modules, <CODE>ro</CODE> assumes that those symbol definitions are in the static module and then references them in the static module.
</P>
<P>
    If a definition that is referenced is not in the static module, an error will occur when linking the static module. In such cases, the code must be revised so that the static module contains a definition for the referenced symbol.
</P>
<P>
    If multiple definitions are not created (intentionally or accidentally), support will be necessary for the following.
</P>
<ul>
    <li>Class member variables for the template class.
    <li>Static local variables in inline functions.
</ul>
<P>
    The definitions of symbols for the above are created in object files created from the source files that referenced those symbols. So, reference these symbols from the static module source files to make sure that the definitions are contained in the static module. Often these symbols cannot be directly referenced. The definitions can be included in the static module by using indirect methods such as referencing the function by using the variable represented by the symbol.<br/> <a href="../../api/nn_util/NN_UTIL_REFER_SYMBOL.html"><code>NN_UTIL_REFER_SYMBOL</code></a> can be used for this purpose.
</P>
<P>
    For example, when a header such as the following is used, the conditions described above apply because <code>ms_pInstance</code> is a template class class member variable. If the static module is not using a class <code>S</code> at all and the <code>S</code> class is used in multiple dynamic modules, <code>Singleton&lt;S&gt;::ms_pInstance</code> in the dynamic modules will cause an error at build time.
</P>
<P>
    　　 Header<br/> (Code from the very beginning)
</P>
<PRE>
... (omitted) ...

template &lt;class T&gt;
class Singleton
{
public:
    static T& GetInstance() { return *ms_pInstance; }

protected:
    Singleton()  { ms_pInstance = static_cast&lt;T*&gt;(this); }
    ~Singleton() { ms_pInstance = NULL; }

private:
    static T* ms_pInstance;
};

template &lt;class T&gt; T* Singleton &lt;T&gt;::ms_pInstance = NULL;

class S : public Singleton&lt;S&gt;
{
};

... (omitted) ...
</PRE>
<P>
    In this case, the following functions are added to source files and other files that include <code>nnMain</code>. These functions do not actually need to be called.
</P>
<P>
    　　 Any source files that are used in static modules <br/> (code added for <CODE>ro</CODE> support)
</P>
<PRE>
... (omitted) ...

void DummyReference()
{
    <span class="here">NN_UTIL_REFER_SYMBOL(S::GetInstance);</span>
}
</PRE>


<H2><a name="use_dll">Using DLLs</a></H2>

<H3>Basic Sequence</H3>
<P>
    The list below shows the sequence from loading a single CRO file, to using it, and then freeing all memory.
</P>

<ol>
<li>Load CRS file into memory<br> ↓
<li><code>nn::ro::Initialize(crs)</code><br> ↓
<li>Load CRR file into memory<br> ↓
<li><code>nn::ro::RegisterList(crr)</code><br> ↓
<li>Load CRO file into memory<br> ↓
<li><code>nn::ro::LoadModule(cro)</code><br> ↓
<li><code>pModule-&gt;DoInitialize()</code><br> ↓<br>Execute process using CRO file<br> ↓
<li><code>pModule-&gt;DoFinalize()</code><br> ↓
<li><code>pModule-&gt;Unload()</code><br> ↓
<li>Free memory for CRO file<br> ↓
<li><code>pRr-&gt;Unregister()</code><br> ↓
<li>Free memory for CRR file<br> ↓
<li><code>nn::ro::Finalize()</code><br> ↓
<li>Free memory for CRS file<br> ↓
</ol>

<P>
    If you use multiple CRO files at the same time, simply repeat steps 5 to 7 as many times as necessary. If you want to load and use another CRO file after freeing the first, continue to step 10, and then return to step 5.
</P>
<P>
    Normally, you will perform up to step 4 when the application starts, and 11 and beyond when it exits. You will only perform steps 5 to 10 as appropriate when the application is running.
</P>
<P>
    Below, each of these steps is described in detail.
</P>

<H3>Loading CRS File and Initializing <CODE>ro</CODE> Library</H3>
<P>
    You must first load the CRS file into memory (e.g., from ROM-FS), and then call <a href="../../api/nn/ro/Initialize.html"><code>nn::ro::Initialize</code></a> with this as the argument.
</P>
<PRE>
const wchar_t* crsPath = L"rom:/static.crs";

size_t crsSize  = GetFileSize(crsPath);
void* pCrs      = AllocateMemory(crsSize, 0x1000);

LoadFile(pCrs, crsPath, crsSize);
<span class="here">nn::ro::Initialize(pCrs, crsSize);
</span></PRE>
<P>
    There is a one-to-one relationship between CRS files and static modules; there can only be one of them per static module. Similarly, the CRS file of one static module will be different from the CRS file of another. Therefore, a single application will never have more than one CRS file, and applications never choose which CRS file to load.
</P>

<H3>Registering CRR Files</H3>
<P>
    You must first load the CRR file into memory (e.g., from ROM-FS), and then call <a href="../../api/nn/ro/RegisterList.html"><code>nn::ro::RegisterList</code></a> with this as the argument.
</P>
<PRE>
const wchar_t* crrPath = L"rom:/.crr/static.crr";

size_t crrSize  = GetFileSize(crrPath);
void* pCrr      = AllocateMemory(crrSize, 0x1000);

LoadFile(pCrr, crrPath, crrSize);
nn::ro::RegistrationList* pList = <span class="here">nn::ro::RegisterList(pCrr, crrSize);
</span></PRE>
<P>
    A CRR file contains information about multiple CRO files. Before loading a CRO file, you must register the CRR file that contains the information about it. Ordinarily, you will create a single CRR file containing the information for all CRO files that the application will use. It is therefore normally sufficient to register just that one file. Use multiple CRR files if you want to also optimize the memory used by CRR files, or if you will be distributing additional programs.
</P>

<H3>Loading the CRO File</H3>
<P>
    Load the CRO file, which is the actual dynamic module. Load the CRO file into memory (e.g., from ROM-FS), and then pass that as an argument to <a href="../../api/nn/ro/LoadModule.html"><code>nn::ro::LoadModule</code></a>. You must pass to <code>LoadModule</code> a memory area for the buffer required separately by the CRO file. Pass the CRO object as an argument to <a href="../../api/nn/ro/GetSizeInfo.html"><code>nn::ro::GetSizeInfo</code></a> to get the size of the buffer required by the CRO file.
</P>
<P>
    After <code>LoadModule</code> succeeds, you must call  <a href="../../api/nn/ro/Module/DoInitialize.html"><code>nn::ro::Module::DoInitialize</code></a> on the value returned by <code>LoadModule</code> before using the module.
</P>
<PRE>
const wchar_t* croPath = L"rom:/module1.cro";

size_t croSize  = GetFileSize(croPath);
void* pCro      = AllocateMemory(croSize, 0x1000);

LoadFile(pCro, croPath, croSize);

nn::ro::SizeInfo sizeInfo;
<span class="here">nn::ro::GetSizeInfo(&sizeInfo, pCro);

void* pBuffer   = AllocateMemory(sizeInfo.bufferSize, 8);
nn::ro::Module* pModule = <span class="here">nn::ro::LoadModule(
                            pCro, croSize, pBuffer, sizeInfo.bufferSize);</span>

<span class="here">pModule-&gt;DoInitialize();</span>
</span></PRE>
<P>
    <code>DoInitialize</code> builds global objects. If two modules reference each other in the global-objects building stage, first perform the steps up to <code>LoadModule</code> for each module, and then call <code>DoInitialize</code> after both calls to <code>LoadModule</code> complete.
</P>

<H3>Using CRO Files</H3>
<P>
    You have now resolved the references to the CRO file, and it is possible to call functions and read/write variables defined in it. However, this does not necessarily mean that all the references by the loaded CRO file to other modules have been resolved. The other CRO modules that this one references may not have been loaded yet, or the symbols that it references may not have been defined or exported at all. <br> You can use the <a href="../../api/nn/ro/Module/IsAllSymbolResolved.html"><code>nn::ro::Module::IsAllSymbolResolved</code></a> function to determine whether all references to other modules by the CRO file you've loaded are resolved.
</P>
<P>
    Although references are resolved automatically, you can also obtain pointers manually. To get a pointer to a function or variable manually, use <a href="../../api/nn/ro/GetPointer.html"><code>nn::ro::GetPointer</code></a> or <a href="../../api/nn/ro/Module/GetPointer.html"><code>nn::ro::Module::GetPointer</code></a>.
</P>
<PRE>
// Get a pointer to a function manually, and call it
int (*pFunc)(int) = <span class="here">pModule-&gt;GetPointer&lt;void (*)(int)&gt;("TestFunc");</span>
int ret = pFunc(0x1234);

// Get a pointer to a variable manually, and read/write it
int& var = *<span class="here">pModule-&gt;GetPointer&lt;int*&gt;("g_Variable");</span>
NN_LOG("%d\n", var);
var = ret;
</PRE>


<H3>Releasing CRO Files</H3>
<P>
    To release the memory used by a CRO object, call <a href="../../api/nn/ro/Module/DoFinalize.html"><code>nn::ro::Module::DoFinalize</code></a> and <a href="../../api/nn/ro/Module/Unload.html"><code>nn::ro::Module::Unload</code></a> on the value returned by <code>LoadModule</code>.
</P>
<PRE>
<span class="here">pModule-&gt;DoFinalize();
<span class="here">pModule-&gt;Unload();</span>

FreeMemory(pBuffer);
FreeMemory(pCro);
</span></PRE>
<P>
    Under certain conditions, you can call <code>LoadModule</code> again for the CRO object in the freed memory area, and use it again. See <a href="#reuse_cro">Reusing CRO Objects</a> for details.
</P>

<H3>Releasing CRR Files</H3>
<P>
    To release the memory used by a CRR object, call <a href="../../api/nn/ro/RegistrationList/Unregister.html"><code>nn::ro::RegistrationList::Unregister</code></a> on the value returned by <code>RegisterList</code>.
</P>
<PRE>
<span class="here">pList-&gt;Unregister();

FreeMemory(pCrr);
</span></PRE>

<H3>Releasing CRS Files</H3>
<P>
    To release the memory area used by a CRS object, call <a href="../../api/nn/ro/Finalize.html"><code>nn::ro::Finalize</code></a>.
</P>
<PRE>
<span class="here">nn::ro::Finalize();

FreeMemory(pCrs);
</span></PRE>
<P>
    Calling <code>nn::ro::Finalize</code> enables you to free the memory for the CRS object as well as all CRR and CRO objects.
</P>


<h2>Debug</h2>
<P>
    A <CODE>CRO</CODE> object can be used to debug source code in the debugger. You must include debugging information in the <CODE>CRR</CODE> object to debug source code.
</P>
<P>
    See <a href="BuildSystemManualForDll.html">CTR-SDK Build System Manual (for DLLs)</a> or <a href="BuildSystemDevelopmentGuideForDll.html">Guide to Developing a Build System (for DLLs)</a> for information about including debugging information in a <CODE>CRR</CODE> object.
</P>


<h2><a name="other_feature">Special Uses</a></h2>

<h3><a name="explicit_import_export">Explicit Imports and Exports</a></h3>
<p>
    Explicit imports and exports are mainly used in combination to enable use of plug-in type DLLs.
</p>

<H4>Explicit Imports</H4>
<P>
    To explicitly import a symbol, add <CODE>NN_DLL_IMPORT</CODE> to the beginning of the function or variable declaration.
</P>
<PRE>
extern NN_DLL_IMPORT int g_Variable;

extern NN_DLL_IMPORT void Function();
</PRE>
<P>
An explicitly imported symbol does not generate an error, even if this definition cannot be found at link time by the linker. <br> An explicitly exported symbol is not automatically imported, so you need to either explicitly import the symbol or get the pointer manually.
</P>


<H4>Explicit Exports</H4>
<P>
    To explicitly export a symbol, add <CODE>NN_DLL_EXPORT</CODE> to the beginning of the function or variable declaration.
</P>
<PRE>
NN_DLL_EXPORT int g_Variable;

NN_DLL_EXPORT void Function()
{
    ... (omitted) ...
}
</PRE>
<P>
    Explicitly exported symbols will be exported. If explicit exports are used in a dynamic module,  dead-code stripping will not remove the symbols, even if they are not referenced in the module.
</P>
<P>
    When variables are defined in multiple modules, processing is performed as if the variables are defined in static modules (see <a href="#vague_linkage">Handling of Symbols with Multiple Definitions</a>). However, variables exported explicitly in any module will not be included in that processing. In short, they will be treated as separate variables that have their own separate memory regions in each module.
</P>


<h3><a name="special_func">Special Functions</a></h3>
<P>
    Some of the names exported by a DLL are handled in a special way. There are three such names: <code>nnroProlog</code>, <code>nnroEpilog</code>, and <code>nnroUnresolved</code>. If a function with one of these names is defined in a DLL and exported, it will be handled as follows.
</P>
<P>
    <STRONG>Note:</STRONG> If it is a C++ function, you must add <CODE>extern &quot;C&quot;</CODE> to the definition. In order to export it, you must do so explicitly.
</P>

<h4><code>nnroProlog</code></h4>
<P>
    If you define a function with the name <code>nnroProlog</code> in a CRO file, then <code>nnroProlog</code> will be called when <a href="../../api/nn/ro/Module/DoInitialize.html"><code>nn::ro::Module::DoInitialize</code></a> is called on that CRO file. This enables you to implement initialization unique to that DLL.
</P>
<P>
    <code>nnroProlog</code> is called after <code>DoInitialize</code> has completed all initialization steps, including building global objects.
</P>
<PRE>
extern "C" NN_DLL_EXPORT void nnroProlog()
{
    ... (omitted) ...
}
</PRE>


<h4><code>nnroEpilog</code></h4>
<P>
    If you define a function with the name <code>nnroEpilog</code> in a CRO file and export it, then <code>nnroProlog</code> will be called when <a href="../../api/nn/ro/Module/DoFinalize.html"><code>nn::ro::Module::DoFinalize</code></a> is called on that CRO file. This enables you to implement finalization unique to that DLL.
</P>
<P>
    <code>nnroEpilog</code> is called before <code>DoFinalize</code> does any finalization, such as freeing global objects.
</P>
<PRE>
extern "C" NN_DLL_EXPORT void nnroEpilog()
{
    ... (omitted) ...
}
</PRE>


<h4><a name="nnroUnresolved"><CODE>nnroUnresolved</CODE></a></h4>
<P>
    If you define a function named <code>nnroUnresolved</code> in your CRO file and export it, then unresolved references from this file will be linked to this function. If you do so, <code>nnroUnresolved</code> will be called when a function is called, and the DLL in which it is defined has not been loaded.
</P>
<PRE>
extern "C" NN_DLL_EXPORT void nnroUnresolved()
{
    ... (omitted) ...
}
</PRE>
<P>
    This particular function can also be used in static modules.   However, there is a limitation. It will stop working if references, once they have been resolved, are reverted to the unresolved state.
</P>


<h3><a name="free_unused">Freeing Unneeded Memory</a></h3>
<P>
    In addition to executable code, a CRO file contains information about symbols referenced from other modules, and symbols exported to other modules. If you know that this information will not be needed after the CRO file is loaded, then you can free it and use it for other purposes after <CODE>LoadModule</CODE> by specifying a <SPAN class="argument">fixLevel</SPAN> argument to <a href="../../api/nn/ro/LoadModule.html"><code>nn::ro::LoadModule</code></a>. This can greatly reduce your memory usage, particularly when the module references and/or exports a large number of symbols. Conversely, if the module does not have much of this information, then freeing it may not increase the available memory size at all.
</P>
<PRE>
const wchar_t* croPath = L"rom:/module1.cro";

size_t croSize  = GetFileSize(croPath);
void* pCro      = AllocateMemory(croSize, 0x1000);

LoadFile(pCro, croPath, croSize);

nn::ro::SizeInfo sizeInfo;
nn::ro::GetSizeInfo(&sizeInfo, pCro);

void* pBuffer   = AllocateMemory(sizeInfo.bufferSize, 8);
nn::ro::Module* pModule = nn::ro::LoadModule(
                            pCro, croSize, pBuffer, sizeInfo.bufferSize,
                            true, <span class="here">nn::ro::FIX_LEVEL_3);

<span class="here">void* pFreeBuffer = reinterpret_cast<void*>(sizeInfo.fix3End)</span>;
<span class="here">size_t freeSize   = croSize - (sizeInfo.fix3End - reinterpret_cast<uptr>(pCro))</span>;
</span></PRE>
<P>
    The code above made the <code>freeSize</code> portion of <code>pFreeBuffer</code> available.
</P>
<P>
</P>

<h3><a name="reuse_cro">Reusing CRO Objects</a></h3>
<P>
    Normally, it is not possible to reuse a CRO module you passed to <a href="../../api/nn/ro/LoadModule.html"><code>nn::ro::LoadModule</code></a> after you have called <a href="../../api/nn/ro/Module/Unload.html"><code>nn::ro::Module::Unload</code></a> on it. However, it is possible to reuse them if the following conditions are met.
</P>
<ol>
<li>You use <code>FIX_LEVEL_0</code>
<li>It does not use initial values for static variables
</ol>
<P>
    Below are some ways you can satisfy condition 2 in your implementation:
</P>
<ul>
<li>Do not use static variables
<li>Initialize all static variables by using the <code>nnroProlog</code> function.
</ul>
<P>

</P>

<PRE>
const wchar_t* croPath = L"rom:/module1.cro";

size_t croSize  = GetFileSize(croPath);
void* pCro      = AllocateMemory(croSize, 0x1000);

LoadFile(pCro, croPath, croSize);

nn::ro::SizeInfo sizeInfo;
nn::ro::GetSizeInfo(&sizeInfo, pCro);

void* pBuffer   = AllocateMemory(sizeInfo.bufferSize, 8);

// Loaded first time
nn::ro::Module* pModule = nn::ro::LoadModule(
                            pCro, croSize, pBuffer, sizeInfo.bufferSize,
                            true, <span class="here">nn::ro::FIX_LEVEL_0);</span>
pModule-&gt;DoInitialize();

    ... (use cro module) ...

// Free it
pModule-&gt;DoFinalize();
pModule-&gt;Unload();

// It can be reloaded without reading it from memory again
<span class="here">pModule = nn::ro::LoadModule(pCro, croSize, pBuffer, sizeInfo.bufferSize);</span>
<span class="here">pModule-&gt;DoInitialize();</span>
</PRE>


<H2>Revision History</H2>
<dl class="history">
    <dt>2012/06/22</dt>
    <dd>
Added a link to <I>Guide to Developing a Build System (for High-Level DLLs)</I>.<br/>
    </dd>

    <dt>2012/04/23</dt>
    <dd>
        Added the &quot;Handling of Symbols with Multiple Definitions&quot; section.<br/> Updated description of handling of static variables in <B>Restrictions</B> section.<br/> Added description about support for multiple definitions in &quot;Creating the Source Code&quot; in the &quot;Creating Static Modules&quot; section.<br/> Added relationship with multiple definitions in the &quot;Explicit Imports and Exports&quot; section.<br/>
    </dd>

    <dt>2012/02/27</dt>
    <dd>
        Added specific descriptions to the <B>Restrictions</B> section regarding standard C functions and similar functions.
    </dd>

    <dt>2012/01/23</dt>
    <dd>
        Added note to the <B>Restrictions</B> section that static variables cannot be properly handled.
    </dd>

    <dt>2011/12/12</dt>
    <dd>
        Added the item &quot;Restrictions&quot; to the section &quot;Features and Limitations of the <CODE>ro</CODE>  format&quot; and moved the information about this topic to this item.<br> Clarified in &quot;Restrictions&quot; that the SDK's static libraries must not be made and used as DLLs.<br> Added the section &quot;Using Static Libraries&quot;.<br> Added the section &quot;Creating Static Modules&quot;.<br> Updated the section &quot;Special Functions&quot; to reflect fact that <CODE>nnroUnresolved</CODE> can be used in static modules.<br> Touched up the section &quot;Explicit Imports and Exports&quot;.<br> Corrected the &quot;Explicit Imports&quot; example.<br>
    </dd>

    <dt>2011/09/26</dt>
    <dd>
        Updated the &quot;Debugging&quot; section to reflect debugging source code. Added the Revision History section.
    </dd>

    <dt>2011/08/03</dt>
    <dd>
        Initial version.
    </dd>
</dl>


<div class="footer"><span>DLL Manual</span></div>

  <hr><p>CTR-06-0201-002-G<br>CONFIDENTIAL</p></body>
</HTML>