In order to execute application programs that are too big to fit in memory, the NITRO-SDK has tools that support overlay techniques to divide the program into files and store them as ROM images, to load code into memory from given ROM images, as needed, on instruction from the program, and to initialize and execute the code.
makelcf is a tool that automatically creates a Linker Command File (LCF) that gives NITRO execution files support for these overlay techniques. Based on the description in the Linker Spec File (LSF), makelcf creates Linker Command files for each application from an LCF template file.
The following corrections were made in SDK 2.0 and later versions:
makelcf to generate the Linker Response File (command line option passed to a linker is described in a file).
% makelcf [-DNAME=VALUE...] [-MDEFINES_FILE] [-V1|-V2] SPECFILE LCF-TEMPLATE [LCFILE]
This creates a Linker Command File from the LCF template file specified by LCF-TEMPLATE in accordance with the description in the Linker Spec File specified by SPECFILE, naming it as specified by LCFILE. LCFILE can be omitted. If you omit it, a file will be used that has the same name as that specified by SPECFILE with the extension .lcf appended.
The -D option lets you define a variable and its value. The value of this variable can be referenced at the time of the Linker Spec File description.
The -M option lets you define a variable and its value just like the -D option. A text file that consists of the [NAME=VALUE] line is received as an argument. By using this option, the variables and their values that exceed the command line length restriction can be described in the definition.
The lsf file format has been expanded in order to support the feature for designating a linking symbol (described in SEARCH_SYMBOL) when using the overlay via the expanded LCF file in CodeWarrior for NINTENDO DS (henceforth known as CodeWarrior) versions 2.0 and later.The –V1 and –V2 options allow for the selection of either CodeWarrior version 1.x or 2.x when makelcf outputs an LCF file from an LCF template file. If the -V1 option is designated, or if there is no -V option designated, the format for the 1.x version will be used. If -V2 is designated, the format for the 2.x version will be used.
The ARM9 and ARM7 processors both can have only one Resident Module, but they can have numerous Overlay Modules if there is a need, memory and other resources permitting. The ARM9 and ARM7 processors both can have only one Resident Module, but they can have numerous Overlay Modules if there is a need, memory and other resources permitting.
The Linker Spec File (LSF) describes the various settings regarding these overlay tasks. The LSF defines how to divide up and create files from object files of the code that comprises the application program.
The LSF is a text file constructed from the three kinds of section definitions shown below. Each section definition has a declaration at the beginning, followed by section-related parameters enclosed in curly brackets.
| Section definition target | Section definition format | Example definition |
|---|---|---|
| Resident module (Static) |
Static [section name]
{
[section parameter description part]
....
}
|
Static main
{
Address 0x02000000
Object $(OBJS_STATIC)
Library $(LLIBS) $(GLIBS) $(CW_LIBS)
StackSize 1024
}
|
| Autoload module (autoload) |
|
|
| Overlay module (Overlay) |
|
|
| Incidental information (Property) |
|
|
This section name can be used to obtain the Overlay ID and other information. This section name can be used to obtain the Overlay ID and other information. For details about the method, see An Explanation About the FS Library's Overlay ID.
Each LSF must have a Resident Module section, even if overlays are not being used. If more than one Overlay Module has been allocated, there must be as many Overlay Module sections as there are Overlay Modules. If overlays are not being used, then there is no need for an Overlay Module section. The Incidental Information section can be omitted. In that case all incidental information parameters take their default values.
The following are explanations of the parameters set in each section.
Address[address]- The section gets placed at the specified address. In addition to decimal, the address can also be specified in hexadecimal or octal by prefixing the value with
"0x"or"0"(in the C-language fashion).- Object [object name...]
- This specifies the object files and library files that are included in the Resident Module. Because SDK 2.0 and later versions require the generation of the linker response files, it is necessary to specify the file name and path name to designate an object file. It is no longer valid by specifying with GROUP (
*). When using the make system of SDK, the path to the object is given tomakelcf, and the path name for the object can be specified in the following format.After the source file which was specified in the makefile as the variableObject $(OBJDIR)/main.oSRCSwas compiled, the generated object file is given tomakelcfas$(OBJS_STATIC)with paths. When it is not necessary to specify the object file every time, it can be expressed as the following.The object file described in Object is passed with path to the response file (Object $(OBJS_STATIC)*.response). Like the execution binaries,makelcfgenerates response files in the$(BINDIR)directory.
The library should not be described in the object statement but in the newly added library statement.
Additionally, you can use an asterisk (*) to use the special section to support loading into ITCM/DTCM/VRAM.This indicates all files defined in theObject * (.itcm).itcmsection. This description is commonly used in the autoload section.- Library [library module name...]
- Specify the library file in the resident module.
SDK 2.0 and later versions require generation of the linker response files, it is necessary to specify the file name and path name to designate an object file.
When using the SDKmakesystem, library groups specified with the variableLLIBRARIESin the makefile, SDK library groups, and CodeWarrior library groups are given as$(LLIBS),$(GLIBS)and$(CW_LIBS), respectively. Therefore, the following format can be used to specify the library:The library file described in Library will be passed to the response file along with theLibrary $(LLIBS) $(GLIBS) $(CW_LIBS)-1options.StackSize[stack size (in bytes)]
or
StackSize[stack size (in bytes)] [IRQ stack size (in bytes)]]- Specifies the stack size of the
NitroMain()function when it is first executed in the Resident Module and the IRQ stack size. Both of these sizes can be specified in base 8, base 10, or base 16. The stack size depends on the size of the numeral:
When positive The number of bytes specified by the value gets assigned to the stack. When 0 The maximum possible size gets assigned to the stack. When negative The absolute value gets subtracted from the maximum possible size, and the resulting size gets assigned to the stack.
For the IRQ stack size, the value itself gets assigned as the stack size used for IRQ. These specifications for stack size and IRQ stack size can be omitted. In that case the stack size setting is 0 (i.e., the maximum possible size is assigned) and the IRQ stack size is 0x400 bytes.
Autoload is a system that transfers the module to several regions at the program startup. The transfer process will be done before calling the common libraries in crt0.o, so it is possible to transfer the system libraries such as OS and FS to ITCM/DTCM. ITCM of DTCM is reserved as section names to be auto-loaded to ITCM/DTCM. Specify one of these.
Address[address]- The same as the Address parameter in the Static section.
- After [other section name...]
- The current section is placed immediately after the other specified section. When more than one section is specified in
After, the current section is placed immediately after the section with the largest final address. (This is done so there is no overlapping region with all of the sections.) Address and After are not enabled within the same section. The first one in the description has the priority.- Object [object name...]
- Same as the Object parameter in the Static section. For autoload, the description of Object "*" (section name) is commonly used.
- Library [library module name...]
- Same as the Library parameter in the Static section.
Address[address]- The same as the Address parameter in the Static section.
- After [other section name...]
- The current section is placed immediately after the other specified section. When more than one section is specified in
After, the current section is placed immediately after the section with the largest final address. (This is done so there is no overlapping region with all of the sections.)AddressandAfterare not enabled within the same section. The first one in the description has the priority.- Object [object name...]
- Same as the
Staticsection'sObjectparameter.- Library [library module name...]
- Same as the Library parameter in the Static section.
Group[overlay_group_name]- Specifies the overlay group to which the current section belongs. The linker assumes that overlays belonging to the same group are located in the same memory region. By specifying mutually exclusive overlay modules as belonging to the same group, you can detect function calls between the overlays as errors during linking. In addition, the overlay group setting for each overlay module is referenced to determine whether the compiler should treat functions with inline declarations as inline code. If problems related to calling inline functions occur during the DEBUG build, try o resolve the problem using the overlay group setting.
This overlay group specification is supported with versions including and after SDK 3.0RC1.The group with the same name as the current section name is set if the overlay group specification is omitted to maintain compatibility.
SearchSymbol[Other section name or overlay group name...]- If multiple symbols with the same name exist over multiple sections, this will allow you to designate which of those symbols to link to. This specification can be set for each section.
In order to search for symbols referenced by the current section, the linker first searches through its own section and then searches in order through the overlay group or section given by this specification. A linker error results if the symbol cannot be found in the overlay group or section given here.
If the specification is omitted, all sections become the target of the symbol search. In this case, if there is only one symbol overall having the name in question, that symbol is linked, but if there is more than one symbol overall having the name in question, a link error will result because the linker doesn't know which symbol to use.
When using this feature, you must runmakelcfin CodeWarrior for NINTENDO DS version 2.0 compatibility mode (option-V2).
OverlayDefs[Overlay Name Filename (without extension)]- This specifies the filename (excluding an extension) for the Overlay Name file that gets created at the time of linking. If the filename starts with
"%", that"%"part gets replaced with the [name of the resident part section] specified at the start of theStaticsection. It can be omitted, in which case"%_defs"gets used.OverlayTable[OverlayTable filename]- This specifies the filename (excluding an extension) for the Overlay Table file that gets created at the time of linking. If the filename starts with
"%", that"%"part gets replaced with the [name of the resident part section] specified at the start of theStaticsection. It can be omitted, in which case"%_table"gets used.Suffix[File extension for application binary files]- This specifies the filename extension for the binary files that get created at the time of linking. It can be omitted, in which case
".sbin"gets used.
You can reference the value of a variable that is defined outside of the Linker Spec file by specifying the variable in the format: $([variable name]). The variable's value can be set with the command line option like this: -D[variable name]=[value]. Alternately, you can set the value using an environment variable. If the same variable is defined with both the -D option and an environment variable, the -D option value takes priority. Following is an example of a description for a variable reference:
Static $(TARGET_NAME)
{ Address $(START_ADDRESS) Object * }
If the variable value takes the form of a file path, you can reference the value by attaching a modifier option immediately after the variable name. The following values can be referenced with the modifier options :h, :t, :r and :e
For$(FILE)=C:/home/Nitro/readme.txt:
:hThe portion of the path before the final path delimiter $(FILE:h)=C:/home/Nitro/:tThe portion of the path after the final path delimiter $(FILE:t)=readme.txt:rThe portion of the path excluding the file extension $(FILE:r)=C:/home/Nitro/readme:eThe path file-extension portion $(FILE:e)=txt
Keywords like "Static" used in section definitions can be written this way, or all in uppercase like "STATIC", or all in lowercase like "static". Anything than follows the pound sign (#) is treated as a comment.
# # Lines that begin with{ .... }#are comments
# STATIC my_app # Uppercase is also OK
{
....
}
$NitroSDK/tools/bin/makelcf.exe
05/09/2006 Made overlay groups selectable to search for symbols in the link process
09/02/2005 Made revisions along with the addition of support for overlay groups
07/20/2004 Made revisions along with the changes to the overlay operations
05/25/2004 Created initial version
CONFIDENTIAL