Build System Development Guide (for High-Level DLLs)

Introduction

About This Document

This document provides the information necessary for those who are using the .ro format who want to create their own build system that is more advanced and surpasses the capabilities of the build system provided in the SDK.

• .xrl file specification
• Features of the makecro tool
  
• Detailed SDK build steps
• Important issues, SDK support, strategies, and tips
  

To make .ro easy to use, the build system provided in the SDK makes some features unavailable and also has a number of limitations. Creating your own build system allows for flexible adjustments without these limitations.

Unlike the Guide to Developing a Build System (for DLLs), this document is not intended to create a particular build system. Rather, it presents information on the parts that you would combine to create your own build system.

Prerequisites

This document assumes an understanding of the build flow with .cro that is used by the build system in the SDK. Before you proceed, please review the DLL Manual and the Build System Development Guide (for DLLs).

This document also assumes basic knowledge of CTR-SDK terminology. For a glossary of basic CTR-SDK terms, see CTR-SDK Terminology.

Finally, this document assumes some degree of familiarity with ELF. The CTR-SDK does not describe ELF. For more information about ELF, see one of the commercially available books.

Notation Used in This Document

In this document, the names of Windows tools contained in the tools/CommandLineTools directory are abbreviated by omitting the leading ctr_ and the ending file extension. For example, the abbreviation for ctr_makerom32.exe is makerom.

Components

Terminology presents descriptions of the terms used in this document.

The sections XRL File Specification, SDK Build Steps and Features of the makecro Tool all describe their topics in detail.

The sections Create CRO File、Issues and Support and Strategies and Tips present descriptions of the overall build system, including important considerations for creating .cro with your own build system.

Create .crr File describes how to create the .crr file.

Terminology

This section describes the terminology used in this document.

The meanings and usage of terms used in this document may differ from their general meanings and usage, as well as their meaning in other CTR-SDK documentation.

ELF file

The file created as a result of compiling or linking source code by the ARMCC compiler and linker.

Executable ELF

An ET_EXEC type ELF file.

Relocatable ELF

An ET_REL type ELF file.

Shared object ELF

An ET_DYN type ELF file.

Object file

A relocatable ELF file obtained as the result of compiling the source code by the compiler.

Partial link file

A relocatable ELF file obtained as the result of partial linking by the linker.

Command file

A file that specifies command-line options.
The ARMCC tools can read command-line options from a file, rather than from the command line. This feature is used when a number of command-line options are specified.

Steering file

A file that specifies operations on symbols with armlink.

Build system of the SDK

Refers to the procedure and mechanism for creating the .cro file, as explained in Build System Development Guide (for DLLs).

Build steps

The necessary step-by-step procedure for creating the .cro file and related resources.

.xrl File Specification

.xrl is an XML format file used by makecro.

Role of the .xrl File

The role of the .xrl file is to supplement the ELF file by storing information essential for .ro that is not stored in the ELF file. .ro requires one .xrl file for each module. The .xrl file contains information about the symbols exported by the module, and the symbols that are referenced. makero builds export and reference information based on the information in the .xrl file.

The .xrl file also contains information that helps automate referencing and exporting by tools. By using this information, makecro can realize features that are required to automate referencing and exporting.

Information in the .xrl File

The following information is held in the .xrl file.

• Module name.
  
• List of symbols to reference.
• List of symbols to export.
• Export types of symbols to export.
  
• Index numbers for symbols to export in index format.
• Information for automating referencing and exporting.
• Flag that indicates whether the tool performs automatic filtering.
• Flag that indicates whether to force the references.
• Flag that indicates whether symbols are functions.
• Flag that indicates whether an exported symbol is referenced.
  
• Cache for values that can be obtained from other .xrl files.
• Export types of the symbols to reference.
• Index numbers for the symbols to reference in index format.
• Module name that defines the symbols to reference in index or offset format.
  
• Cache for values that can be obtained from ELF files.
• Offset information for the symbols to export.
  

Elements and Structure of the .xrl File

The .xrl file has a simple structure, composed of the following six elements.

• module
• moduleInfo
• imports
• import
• exports
  
• export

module is the root element, and it contains the moduleInfo, imports, and exports elements. The imports element contains the import element, and the exports element contains the export element. This basic structure is fixed. The only differences between .xrl files are the attribute values, and the content and numbers of the import and export elements.

module
  ├ moduleInfo
  ├ imports
  │   └ import
  └ exports
      └ import

The module Element

The module element is the root element of the .xrl file. As a child element, it has at most one moduleInfo element and one imports element, and any number of exports elements. It does not have an attribute.

<module>
    <moduleInfo/>
    <imports>
        ...
    </imports>
    <exports>
        ...
    </exports>
</module>

The moduleInfo Element

The moduleInfo element stores information about the overall module. It does not have any child elements. It has the following attributes.

    ...
    <moduleInfo name="SampleModule" />
    ...

The imports Element

The imports element is a collection of import elements. As a child element, it can hold any number of import elements. It does not have an attribute.

    ...
    <imports>
        <import> ... </import>
        <import> ... </import>
        <import> ... </import>
    </imports>
    ...

The import Element

The import element specifies a symbol for which a reference is generated. As its content, the element specifies the name of the symbol for which a reference is generated. Each import element specifies one symbol. Symbol names must be mangled. It has the following attributes.

    ...
    <import auto="false" type="symbol" module="SampleModule" index="11" force="false">g_Variable</import>
    ...

The exports Element

The exports element is a collection of export elements. It has an arbitrary number of export child elements. It has the following attributes.

    ...
    <exports type="index">
        <export> ... </export>
        <export> ... </export>
        <export> ... </export>
    </exports>
    ...

The export Element

The export element specifies a symbol that is exported. This element specifies a symbol name to export. Each export element specifies one symbol. Symbol names must be mangled. It has the following attributes.

    ...
    <export auto="false" function="false" reference="true" section="1" offset="00123456">g_Variable</export>
    ...

SDK Build Steps

This section describes the purpose of each build step in the SDK-conforming build system that is described in the Build System Development Guide (for DLLs). 

Overall Summary

The SDK build system is designed for easy use of .ro. To that end, it completes the following tasks.

• It automatically determines which symbols should be exported, and exports them.
• It automatically determines which symbols should be referenced, and converts them to references.

To complete these tasks, the SDK build system performs the following steps.

• Create a list of all symbols defined by the modules.
  
• Create a list of all undefined symbols referenced by the modules.
• Search out and reference the modules that have the definitions for these undefined symbols.
• Export the symbols that are referenced from other modules.

The general flow is as follows:

1. Partially link module code.
   ↓
   
2. Create a list of symbols from the partial link file.
   ↓
3. Compare references among modules, and select the references to export.
   ↓
4. Create a command file with instructions for exporting and referencing for the linker.
   ↓
5. Use this created command file to link.
   ↓
6. Create the .cro file.

Partial Linking

Partially link the object files that include the modules and combine them into a single ELF file that you can use in the next step to create a list of symbols.

The goal is to create a list with all of the symbols, but some symbols will be missing because of optimization and dead-code stripping of executable ELF files (such as those created by linking static modules and linking dynamic modules) and shared object ELF files. That is why partial linking is necessary.

To shorten processing time in the next step, the SDK libraries are removed from the targets of the linking.

Create List of Symbols

Create an .xrl file from the partial link file that was created in the previous step.

Check for symbols defined in the partial link file, and for symbols with undefined references. Then create an .xrl file, with the defined symbols set in export elements, and the undefined elements set in import elements.

For automatic export and referencing of symbols, list the symbols that can be provided by the modules, and all necessary symbols.

Merge Undefined Symbols

Update the .xrl file of the static module so that symbols that are referenced but not defined in any module are exported in the static module.

Check the .xrl files for all modules. If there are symbols in the import elements that are not in the export elements of any of the modules, add those symbols to the export element of the static module .xrl file. The following symbols are targeted.

1. CRT symbols
2. SDK and other library symbols
   
3. Truly undefined symbols, because of a mistake or other reason

If the target symbols are from group 1 or 2, they can be exported in the static module, because in the later step to create a command file the symbols are incorporated into the static module. If the target symbols are from group 3, they generate a link error because they cannot be found among the symbols that are supposed to be exported when linking the static module. The generation of a link error helps to catch mistakes earlier in the process, because undefined symbols do not result in a link error when linking the dynamic module.

If CRT symbols cannot be listed when you create the list of symbols, or if you do not list SDK symbols to shorten processing time, then these symbols are undefined in the .xrl file even if they are referenced. As a result, when you resolve symbol references during the next step, an undefined symbol error occurs.

Assuming that CRT symbols are included in the static module, and that the undefined symbols are among the three groups mentioned previously, you can handle this error by updating the .xrl file of the static module so that these symbols can be provided from the static module.

This process also collects information for recognizing the CRT symbols that should be loaded by the static module when creating the command file.

Resolve Symbol References

For the symbols referenced by the various modules, determine the module that defines each symbol, and register these reference sources in the .xrl file. To reference a symbol you need its export type, so you should also register the export type in the .xrl file.

At the same time, register the symbols that are defined by a module that are referenced by another module. Only the symbols that are registered as referenced by a module are exported. Symbols that are not referenced by any module become the targets of dead-code stripping. If the export type is index, assign an index number to the symbol that is referenced.

To force the references, register the variable symbols that are defined in multiple modules. For variable symbols that are defined in multiple dynamic modules, delete the definitions in the export elements and add them to the import elements. In the static module, add the symbol definitions unconditionally to the export elements. This recommendation assumes that the static module holds the definitions for multiply-defined symbols.

Create Command File

Create a command file for the linker to load the CRT symbols into the static module.

Some CRT symbols cannot be exported in the same way as other symbols. To export these symbols, you need to specify the linker option --undefined_and_export for each symbol that you are exporting. An --undefined_and_export option is generated for each symbol and exported as a command file. The phrase "some CRT symbols" is indeterminate and could change. Further, specifying the --undefined_and_export option for normal export symbols has no adverse effect. For these reasons, set this option for all export symbols in the static module.

Create Steering Files

Create a steering file for the linker to export and reference symbols.

When symbols are exported and referenced automatically, the actual exporting and referencing occurs at link time. The steering file specifies the exporting and referencing of symbols to the linker at link time. In this step, the steering file is created for this purpose. In the steering file, EXPORT specifies a symbol for export, and IMPORT specifies a symbol for referencing.

Create the steering file based on the .xrl file after resolving symbol references. Specify EXPORT for the symbols in the export elements that were registered as referenced from a module, and specify IMPORT for the symbols in the import elements.

Link Static Module

Link and create the ELF file for the static module. Specify the created command file and the created steering file.

This step creates an ELF file that contains the appropriate definitions for CRT symbols and SDK library symbols, and the appropriate settings for symbol exporting and referencing.

The static module is created as an executable ELF file.

Link Dynamic Modules

Link and create an ELF file for the dynamic modules. Specify the created steering file.

This step creates an ELF file with the appropriate settings for symbol exporting and referencing.

The dynamic modules are created as a shared object ELF file.

Replace References

Replace code in the static module so that references to unlinked symbols reference nnroUnresolved instead.

Create Command File 2

Create a command file for fromelf to force the reference to the static modules for variable symbols that are multiply defined.

Variables such as class member variables for the template class have a definition in every module, and they are linked so that the definition inside a module is used from inside that module. Thus, what is essentially a single variable is defined as multiple variables, and processes do not work as expected. To avoid this problem, perform the next step to force the references so that every module references the definition in the static module. In this step, a command file is created for that purpose.

To force the references, specify the --force_import option for each symbol. A --force_import option is generated for every symbol marked in the Resolve Symbol References step, and this is exported as a command file.

Force References

Update the ELF file for the static module, specifying the command file that was created in the previous step (command file 2).

This step ensures that the symbols in the static module are referenced wherever multiply defined symbols are used.

Resolve Offsets

Get the offsets for exported symbols from each ELF file, and register them in the .xrl file.

To reference a symbol of export type offset, you need the symbol offset. In this step, you request cache the offset for each symbol so that it is available as needed from other modules.

This step ensures that even if symbols of export type offset are referenced, you can create the .cro file without the ELF file of the referencing module.

Create the .crs File

Create the .crs file from the ELF file of the static module, and also create the corresponding .xrl files and all other .xrl files.

The .xrl files that do not correspond to the static module are used to reference the offsets of the symbols that are referenced.

Create the .cro File

Create the .cro file from the ELF file of the dynamic modules, and also create the corresponding .xrl files and all other .xrl files. Create the .rlt file at the same time.

The .xrl files that do not correspond to the .cro file that is created are used to reference the offsets of the symbols that are referenced.

Create the .crr File

Create the .crr file from the .rlt file.

Features of the makecro Tool

This section provides a detailed description of the features of the makecro tool.

Create the .cro or .crs File

Creates a .cro file or .crs file from the ELF files and the .xrl files.

The type of the ELF file determines whether the created file is a .cro or .crs file. If it is an executable ELF file, the tool creates a .crs file. If it is a shared object ELF file, a .cro file is created.

The following symbols become export symbols.

• Symbols in the static symbol table of the ELF file that satisfy the following conditions.
• Not undefined.
• The binding is STB_GLOBAL or STB_WEAK.
  
• Visibility is STV_DEFAULT.
  

The following symbols become reference symbols.

• Symbols in the static symbol table of the ELF file that satisfy the following conditions.
  • Undefined.
  • Referenced from dynamic relocation tables.
  An error results if the import element of a corresponding symbol is not in the .xrl file.
  

Note that the .xrl file has nothing to do with whether a symbol is for export or for referencing. The .xrl file is used to reference the export types of symbols and their index or offset values.

In the SDK build system, this feature is used for the Create CRO File and Create CRS File steps.

Create the .xrl File (-l)

Creates an .xrl file from the ELF files, based on the symbols that are defined and referenced in the ELF files.

The following processes are performed.

1. Creates a list of symbols in the ELF symbol table, excluding the debugging symbols.
   
2. Creates a list of the symbols from the first list that are not set to STB_LOCAL binding and are undefined.
3. Creates a list of the symbols from the first list that are not set to STB_LOCAL binding and are not undefined.
4. Creates and exports the following kind of .xrl file.
1. The root contains the module element.
2. The module element contains one moduleInfo element, one imports element, and one exports element.
3. The name attribute of the moduleInfo element is set to the file name of the ELF file without the extension.
4. The imports element contains import elements that contain the names of each symbol that is listed in the second list.
5. For each import element, the auto attribute is set to FALSE if the corresponding symbol is set to STV_DEFAULT in the ELF symbol table. Otherwise, the auto attribute is set to TRUE.
6. The exports element has a type attribute that is set based on the specification of a command line option, and it contains export elements that contain the names of each symbol listed in the third list.
7. For each export element, the auto attribute is set to FALSE if the corresponding symbol is set to STV_PROTECTED in the ELF symbol table. Otherwise, the auto attribute is set to TRUE.
8. Each export element is set to TRUE if its corresponding symbol is type STT_FUNC. Otherwise, it is set to FALSE.

In the SDK build system, this feature is used for the Create List of Symbols step.

Replace Unresolved Symbols (-u)

Creates one ELF file from another ELF file, using a specified symbol address to replace parts of the code where the addresses of unresolved symbols were used.

In the SDK build system, this feature is used for the Replace References step.

Merge Undefined Symbols (-c)

Takes one .xrl file that serves as the base (the "base .xrl file") and several other .xrl files (the "reference .xrl files"), and uses them to create an .xrl file with many export elements added to the base.

The following processes are performed.

1. Creates a list of the import elements in the reference .xrl files that set their auto attribute to TRUE and do not exist with the same symbol name in the export elements of the specified base .xrl file.
2. Creates and exports an .xrl file that has the following kinds of additions to the base .xrl file.
   
1. Symbols from the list created in step 1 are added to the export elements. But the symbols are not added if they already exist as export elements in the base .xrl file.
   
2. import elements with their auto attribute set to TRUE are deleted.
   

In the SDK build system, this feature is used for the Merge Undefined Symbols step.

Resolve References (-f)

Takes one .xrl file that serves as the base (the "base .xrl file") and several other .xrl files (the "reference .xrl files"), and uses them to create an .xrl file with updated reference information and export information.

The following processes are performed.

1. Performs the following processes on all export elements that are contained in all specified .xrl files.
1. Search the specified .xrl files for symbols of the same names that are contained in the import elements.
2. If no symbols are found, set the reference attribute of the export elements to FALSE.
2. Performs the following processes on exports elements that are contained in all specified .xrl files for which the type attribute is set to index.
1. Create a list of all child export elements with a reference attribute set to TRUE.
2. Set the index attribute values for the export elements that are listed in step 1 to numeric values, starting with 0 and incrementing by one in the order that they are listed.
   
3. Performs the following processes on all import elements that are contained in all specified .xrl files.
   1. Search the specified .xrl files for symbols with the same names as the symbols contained in the export elements.
   2. Generate an error if no symbols are found in step 1.
      
   3. Set the type attribute of the original import element to the type attribute of the exports element that contains the export element found in step 1.
   4. If the type attribute of the exports element that contains the export element found in step 1 is index, then set the index attribute of the original import element to the index attribute of the export element.
   5. Set the value of the module attribute of the original import element to the value of the name attribute of the moduleInfo element in the .xrl file that contains the export element found in step 1.
4. Exports the .xrl file that results from making these changes to the base .xrl file.

In the SDK build system, this feature is used for the Resolve References step.

Merge (-m)

Merges the contents of two .xrl files.

The merging uses the following rules.

• If the name attribute of the moduleInfo element is specified on the command line, use that value. If not, use the value of the .xrl file that is specified first on the command line.
  
• If the -g option is specified and the same symbol is defined in both files, perform the following steps.
• If the auto attribute of the import element is TRUE in both files, set the value for the attribute of the merged file to TRUE. Otherwise, set the value to FALSE.
• If the auto attribute of the export element is TRUE in both files, set the value to TRUE. Otherwise, set the value to FALSE.
• For all other attributes, use the value in the .xrl file that is specified first on the command line.
  
• Generate an error if the reference attribute is set for the export element.

This feature is not used in the SDK build system.

Register Offsets (-p)

Creates an .xrl file with offsets provided from the ELF and .xrl files.

The following processes are performed.

1. Creates a list of export elements in the specified .xrl files that have the reference attribute set to TRUE.
2. For each symbol in this list, gets the section number and the offset from the start of the section, as defined for the symbol in the ELF file.
3. Creates an .xrl file from the specified .xrl files, with the values obtained in step 2 set for the section and offset attributes of the export element for each symbol in the list.

In the SDK build system, this feature is used for the Resolve Offsets step.

Create the Steering File (-s)

Creates a steering file for armlink from the .xrl file.

Creates an EXPORT command for the export elements in the .xrl file that have the reference attribute set to TRUE, and creates an IMPORT command for all import elements.

In the SDK build system, this feature is used for the Create Steering File step.

Create a Command File to Force Export (-x)

Creates a command file for armlink from the .xrl file.

Creates an --undefined_and_export command for the export elements in the .xrl file that have the reference attribute set to TRUE.

In the SDK build system, this feature is used for the Create Command File step.

Create a Command File to Force Import (-w)

Creates a command file for fromelf from the .xrl file.

Creates a --force_import command for the import elements in the .xrl file that have the force attribute set to TRUE.

In the SDK build system, this feature is used for the Create Command File 2 step.

Relationship Between .xrl and makecro Features

This section provides several tables of information that show how the makecro features use the attribute values of the elements in the .xrl files, and the kinds of values that are set as a result.

In these tables, Base shows how the attribute values of the base .xrl file are used. Input shows how the values of the other .xrl files are used. Output shows how the values that are inherited from Base and Input are changed in the .xrl file that is created by makecro. Added shows the values that are set for newly added elements.

A dashed line ( -- ) in a table indicates that a value is not referenced or not changed. None indicates that no explicit attribute value is set for the element.

import Elements

export Elements

moduleInfo Elements and exports Elements

Contents of the import elements and the export elements (symbol names).

Create the .cro File

Before reading the procedure for creating .cro files, review the following description of the structure of .cro files.

The CRO File Structure

The .cro file contains the following information. Values obtained from the .xrl files are denoted by [xrl]. Other values are obtained from the ELF file.

• [xrl] Module name.
• Executable code.
  
• Information for the symbols to export.
• Name and relocation information for symbols of export type name.
• [xrl] Relocation information for symbols of export type index.
• Information for the symbols to reference.
• Name for symbols of export type name.
• [xrl] Module name and index for symbols of export type index.
• [xrl] Module name, section number, and offset for symbols of export type offset.
• Internal relocation information.
• External relocation information.

In particular, note the information for the symbols to export and the information for the symbols to reference. You must consider how to configure this particular information. Normally, you do not need to worry about the executable code and the relocation information.

The .crs file structure is similar, but without the executable code or the internal relocation information.

The .cro file is created from a shared object ELF file. Typically the only export type for shared object ELF files is name. To make up for this limitation, you create the .cro file by getting the additional information that you need for export types index and offset from the .xrl files.

From a different perspective, you can consider the .cro file as a shared object ELF file, but with some or all of the symbol export types changed to index and offset.

Minimal Steps

If you have the appropriate .xrl files and the appropriate ELF file, you can create a .cro file by simply importing these files and performing the Create CRO step. All other tasks through Create CRO in the SDK build system are performed to create the appropriate .xrl files and the appropriate ELF file.

So the minimum build system performs the following steps.

1. Use NN_DLL_INPORT and NN_DLL_EXPORT in the source code.
2. Create a shared object ELF file.
3. Create an .xrl file with the symbols that are referenced listed in import elements.
4. Using the shared object ELF file and the .xrl file, perform the Create CRO step.

or

1. Create a steering file and an .xrl file from the symbols to export and the symbols to reference.
   
2. Use the steering file of step 1 to create a shared object ELF file.
3. Using the steering file and shared object ELF file, perform the Create CRO step.

This procedure can probably be used without trouble for small modules, but for large and complicated projects it is not realistic. The following section describes issues that arise when you construct a build system to create a .cro file. It also describes the support options in the SDK.

Issues and Support

If you are going to construct your own mechanism to create the .cro file, you must consider how to handle a number of issues.

Issues That Require Attention

You must deal with the following issues.

Management of Export Symbols and Reference Symbols

You need a way to specify which symbols are for export, and which symbols are for reference. The easiest method is to use NN_DLL_IMPORT and NN_DLL_EXPORT, but these must be managed manually.

Support for CRT Symbols and SDK Symbols

You cannot use NN_DLL_IMPORT and NN_DLL_EXPORT for CRT symbols and SDK symbols. Another procedure is required. Also, the steering file is insufficient for CRT symbols.

Export Types Other Than name

To use index and offset as export types, you must specify them in the .xrl file.

Support for nnroUnresolved in the Static Module

References to unresolved symbols from dynamic modules are replaced with references to nnroUnresolved when the modules are loaded. However, in the .ro format DLL mechanism, the static module is loaded in a detached state. This process of replacing references with nnroUnresolved does not occur.

Support for Symbols with Multiple Definitions

C++ allows for multiply defined symbols, and you must handle them.

Support in the SDK

The SDK build system handles these issues in the following ways.

Management of Export Symbols and Reference Symbols

The reference relationships of the various symbols are determined, and a steering file is created for exporting and importing the necessary symbols.

The general flow of the build system is as follows:

1. Perform partial linking. (Partial Linking)
2. List all defined or referenced symbols in the partially linked ELF file. (Create List of Symbols)
   
3. Check symbols that are referenced among modules. (Resolve Symbol References)
4. Create a steering file to export symbols that are referenced and to import symbols that are referenced. (Create Steering File)
5. Apply the linker command file at link time. (Link Dynamic Modules)
   

Support for CRT Symbols and SDK Symbols

The SDK symbols can be supported by using the previously described method to incorporate the static libraries when partially linking. However, because there are so many SDL libraries, acting to incorporate them all slow downs the process of partial linking and all subsequent steps. Moreover, this method does not support CRT symbols.

For these reasons, a different method is employed. A process is performed to update the .xrl file so that undefined symbols are set for export by the static module. This method treats undefined symbols as either SDK or CRT symbols, and presumes that the SDK libraries and CRT symbols are defined in the static module. In addition, a command line option is specified for the linker so that these symbols are actually included in the static module.

The flow in the build system is as follows:

1. Assume that symbols that are not defined in any module are defined by the static module. (Merge Undefined Symbols)
2. Create a command file for the linker so that symbols that are defined in the libraries are included in the static module. (Create Command File)
3. Apply the previously mentioned linker command file at link time. (Link Static Module)

Export Types Other Than name

Information about export types cannot be stored in the ELF file, so everything is done with .xrl files. To use export types other than name, the types must be specified in the .xrl file. In addition, the referencing .xrl file must store the same export type and related information as the exporting side.

The flow in the build system is as follows:

1. Specify the export type when listing symbols in the .xrl file. (Create List of Symbols)
2. Check and retain the export types of referenced symbols and the parameters for referencing. (Resolve Symbol References)
3. Get and retain the offset values from the ELF file. (Resolve Offsets)
4. Store the appropriate information for each export type from the information consolidated in the .xrl files. (Create CRS File, Create CRO File)
   

The SDK build system provides only a way to batch-specify export types when creating the list of symbols. By creating the .xrl files yourself, you can individually specify the export type for each symbol.

Support for nnroUnresolved in the Static Module

Undefined symbols might be referenced in the static module before any calls to the .ro library API. Handle this possibility by replacing references that are unresolved in the ELF file with references to nnroUnresolved. (Replace References)

Support for Symbols with Multiple Definitions

The simple way to deal with multiply defined symbols is to select one definition and use that definition for all references. However, when a symbol is defined inside a module, the ARMCC linker references that symbol inside that module and ignores the steering file, even if the steering file specifies the importing of references from inside that module. To handle this, the fromelf tool, which is included in ARMCC, is used to force import.

The flow in the build system is as follows:

1. Treat multiply defined symbols as targets for forced import that are defined in the static module. (Resolve Symbol References)
2. Create a command file for fromelf to force the import of force-import targets. (Create Command File 2)
3. Force import. (Force References)

With the SDK build system, the actual definitions for multiply-defined symbols are held in the static module. But the definitions can be held in another module by using the process that corresponds to Resolve Symbol References to change the module that performs the Force References step.

Classification of the SDK Build Steps

The table shows each SDK build step and its purpose.

SDK Limitations

The SDK build system has a number of limitations to make it simple to use. The following table lists the main limitations of the SDK build system, and the specifications that are possible with .ro. The specifications that are possible with .ro are not supported in the SDK build system, so a number of actions must be taken to use them.

Strategies and Tips

Steps

As mentioned in Create the .cro File, the symbols to reference and the symbols to export in the .cro file are determined by the contents of the ELF file. Your responsibility is to consider how to create an ELF file that meets the objective.

The created ELF file is adjusted by using NN_DLL_EXPORT and NN_DLL_IMPORT, or by using a steering file, but you must still handle special issues such as CRT symbols. You can automate part of these processes by using .xrl files and makecro. Consider how to create the .xrl files to achieve the intended results for this part.

When you create your build system, think about how you can use .xrl files, the fromelf tool, and other methods to create an ELF file that realizes your objective.

Library DLL

.ro can also be used as a library.

As a library, .ro can perform the following tasks.

• Begin creation of the static module after completing creation of the dynamic modules.
• Use a single dynamic module in multiple applications.
• Use dynamic modules without using the dynamic module source code.

Requirements

To use these tasks, you must satisfy the following conditions.

• Symbols that are referenced from the library dynamic module (such as symbols in the static module) must be of export type name.
  (This requirement is because index and offset values cannot be known ahead of time. The library dynamic modules can use export symbols of any export type.）
• The library dynamic modules must manually select which symbols to export.
  (This selection cannot be automated because the module that is referencing the symbols does not know what it is referencing.）

These tasks can be performed manually, or you can create a tool for automating the tasks and create the appropriate .xrl files to create the library dynamic modules.

Flow

The general process flow is as follows:

1. Determine which symbols to export.
2. Perform the Create List of Symbols step.
3. Delete symbols which are not exported from the .xrl file created in the previous step.
4. Perform the Create Steering File step.
5. Perform the Link Dynamic Modules step.
6. If necessary, perform the Resolve Offsets step.
   
7. Perform the Create the .cro File step.

The following procedure is the general procedure for using a library dynamic module.

1. Prepare header, .xrl, .cro and .rlt files for the library dynamic module.
2. Using the library dynamic module header, perform the Partial Linking step on the modules that use the library dynamic module.
3. Perform the Create List of Symbols and Merge Undefined Symbols steps on the modules that use the library dynamic module.
4. Perform the Resolve Symbol References step on the modules that use the library dynamic module, including in that step the .xrl file of the library dynamic module.
   However, do not resolve symbol references for the .xrl file of the library dynamic module.
5. All subsequent steps are the same as usual.
6. If necessary, use the .xrl file of the library dynamic module when performing the Create the .cro File step on the modules that use the library dynamic module.
7. Perform the Create the .crr File step, including the .rlt file of the library dynamic module.

Create the .crr File

The procedure for creating the .crr file is separated from .cro and has no flexibility. The procedure is very similar to the procedure of the SDK build system.

Relationship Between .crr and .cro

The .crr file is created with the makecrr tool by using the .rlt file, which is created at the same time as the .cro file. The .crr is made from the .rlt file that was generated when .cro was created. The .cro file cannot be loaded at execution time if the .crr file is not loaded first.

A number of .rlt files can be combined to create a single .crr file. Normally, it is fine to have just one .crr file, as long as it is made from all of the combined .rlt files.

Using Multiple .crr Files

The flexibility when creating .crr files depends on the correspondence between .rlt and .crr. As mentioned previously, it is normally fine to create just one .crr file by combining all of the .rlt files.

You can also create .crr files in a one-to-one relationship with .cro files, but this is not recommended because when you have many .crr files, it affects performance when loading .cro.

When sending .cro and .crr files to Download Play child devices when the parent device uses a different .cro file than the child devices, you can create one .crr file for the parent and a separate .crr file for the child devices, and send only the .crr file for the children from the parent to the children. Of course, in such cases the .crr file for the child devices is already included in the child ROM-FS.

Revision History

2012/06/22

Initial version.

CTR-06-0208-002-B
CONFIDENTIAL