

The TWL-SDK has a tool to support a technique called overlay that divides the program too big to fit in memory into files, stores them as ROM images, and loads code into memory from given ROM images, as needed, on instruction from the program to initialize and execute the code. This tool also supports the AUTOLOAD mechanism, which is able to load a program into multiple regions at start time.
The makelcf tool automatically creates a Linker Command File (LCF) that gives NITRO execution files support for these overlay techniques, and the makelcf.TWL tool does the same for TWL execution files. Based on the description in the Linker Spec File (LSF), makelcf[.TWL] creates Linker Command Files for each application from an LCF template 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 omitted, the contents of LCF are written to the standard output.
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.
You can define a variable and its value with the -M option, as you would with 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 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 (hereafter called 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 is used. If -V2 is designated, the format for the 2.x version is used.
The ARM9 and ARM7 processors both can have only one static module, but they can have numerous overlay modules if there is a need, memory and other resources permitting. If memory and other resources permit, it is possible to create multiple overlay modules as needed.
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 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 |
|---|---|---|
| Static module (Static) |
|
Static main
{
Address 0x02004000
Object $(OBJS_STATIC)
Library $(LLIBS) $(GLIBS) $(CW_LIBS)
StackSize 1024
}
|
| Autoload Module (Autoload) |
|
Autoload ITCM
{
Address 0x01FF8000
Object * (.itcm)
Object $(OBJS_AUTOLOAD) (.text)
Object $(OBJS_AUTOLOAD) (.rodata)
Object $(OBJS_AUTOLOAD) (.init)
Object $(OBJS_AUTOLOAD) (.ctor)
Object $(OBJS_AUTOLOAD) (.sinit)
}
|
| Overlay Module (Overlay) |
Overlay [section name]
{
[section parameter description part]
....
}
|
Overlay overlay_1
{
After main
Object $(OBJDIR)/overlay.o
}
|
| LTD Autoload Module (Ltdautoload)Available only in TWL environment |
|
|
| LTD Overlay Module (Ltdoverlay)Available only in TWL environment |
|
|
| Incidental information (Property) |
|
|
This section name can be used to get the Overlay ID and other information. This section name can be used to get 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 static-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 addresses, you can specify hexadecimal or octal addresses by prefixing the value with
"0x"or"0"(C-language notation).Object[object filename...] [(selected sections)]- This specifies the object files to include in the static module.
You must specify the object filename and path, because a linker response file must be created. When using the SDK make system, the object path is given tomakelcfas$(OBJDIR), so you can specify the object path in the following format.As a result of compiling the source file specified by the makefile'sObject $(OBJDIR)/main.oSRCSvariable, the generated object file is given with a path tomakelcfas$(OBJS_STATIC). If it is not necessary to specify successive object files, you can use the following format.The object file specified byObject $(OBJS_STATIC)Objectis passed with a path to the response file (*.response). Similar to executable binaries,makelcfcreates response files in the$(BINDIR)directory.
Specify library files with the newLibrarystatement instead of theObjectstatement.
You can add an asterisk to specifications, as shown in the following example, to support special sections for purposes such as loading to ITCM, DTCM, and WRAM.This specification refers to all files defined in theObject * (.itcm).itcmsection. Statements similar to this are often used in the autoload section.Library[library filename...]- Specify the library file in the static module. When using the SDK
makesystem, library groups specified with the variableLLIBRARIESin the makefile, SDK library groups, and CodeWarrior library groups are identified as$(LLIBS),$(GLIBS), and$(CW_LIBS), respectively. Use the following format to specify the library.The library file described inLibrary $(LLIBS) $(GLIBS) $(CW_LIBS)Libraryis passed with the-1option to the response file.SearchSymbol[Other section name or overlay group name...]- If multiple symbols with the same name exist over multiple sections, this allows you to designate which of those symbols to link to. This specification can be set for each section.
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 defined by this specification. A link error results if the symbol cannot be found in the overlay group or section given here.
If the specification is omitted, all sections are targeted for symbol search. In this case, if overall there is only one symbol with the relevant name, that symbol is linked, but if there is more than one symbol with the relevant name, a link error results because the linker does not know which symbol to use.
When using this feature, you must runmakelcfwith the-V2option to achieve compatibility with CodeWarrior for Nintendo DS version 2.0.Force[symbol name, object file name, or library name]- This is specified when placing a particular symbol in any section.
TheForcestatement corresponds to theFORCE_OBJECTkeyword used in LCF files, so the object files specified usingForcemust be placed in the same section using theObjectstatement.
For more information, see the CodeWarrior documentation.
This feature is supported by CodeWarrior for DSi v.1.2 patch 1 and later.StackSize[stack size (in bytes)]
or
StackSize[stack size (in bytes)] [IRQ stack size (in bytes)]]- Specifies the stack size of the
NitroMainfunction when it is first executed in the static module and the IRQ stack size. Both of these sizes can be specified in base 8, base 10, or base 16.
The stack size value has the following meaning depending on the sign of the numeric value.
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 is assigned as the stack size. The specifications for stack size and IRQ stack size can be omitted. In that case, the stack size setting is 0 (maximum possible size), and the IRQ stack size is0x800bytes.
Autoload is a system that transfers the module to several regions at the program startup. The transfer process occurs 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 and DTCM are reserved as section names to be auto-loaded to ITCM or DTCM. Specify one of these.
Address[address]- See the
Addressparameter in theStaticsection.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 filename...] [(selected sections)]- This specifies the object files that are included in the Autoload Module.
As a result of compiling the source file specified by the makefile'sSRCS_AUTOLOADvariable, the generated object file is given with a path tomakelcfas$(OBJS_AUTOLOAD). If it is not necessary to specify successive object files, use the following format.Everything aside from what appears above is the same as theObject $(OBJS_AUTOLOAD)Objectparameter in theStaticsection.Library[library filename...]- Same as the
Libraryparameter in theStaticsection.SearchSymbol[Other section name or overlay group name...]- Same as the
SearchSymbolparameter in theStaticsection.
Force[symbol name, object filename, or library name]- Same as the
Forceparameter in theStaticsection.
Address[address]- See the
Addressparameter in theStaticsection.After[other section name...]- See the
Afterparameter in theAutoloadsection.Object[object filename...]- Specifies the object files that are included in the Overlay Module.
As a result of compiling the source file specified by the makefile'sSRCS_OVERLAYvariable, the generated object file is given with a path tomakelcfas$(OBJS_OVERLAY). If it is not necessary to specify successive object files, use the following format.Everything aside from what appears above is the same as theObject $(OBJS_OVERLAY)Objectparameter in theStaticsection.Library[library filename...]- See the
Libraryparameter in theStaticsection.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 calling inline functions causes problems during a debug build, try using the overlay group setting to resolve the problem.
This overlay group specification is supported with versions including and after SDK 3.0 RC 1.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...]- Same as the
SearchSymbolparameter in theStaticsection.
Force[symbol name, object filename, or library name]- Same as the
Forceparameter in theStaticsection.
Compress[Smart|Exclusion]- Specifies whether to exclude the target from compression when compressing the resident module using
compstatic (compstatic.TWL).
The following values can be specified.
SmartWhen the -coption is passed tocompstatic (compstatic.TWL), the specified compression is applied.This operation results even if theCompressoption has not been specified.ExclusionWhen the -coption is passed tocompstatic (compstatic.TWL), the target is excluded from compression.
LTD Autoload is a system that transfers the module to the LTD region at program startup. The transfer process takes place prior to calling the standard libraries in crt0.o . LTDMAIN is reserved as the name of the section to autoload to the LTD region, so specify LTDMAIN.
Address[address]- See the
Addressparameter in theStaticsection.After[other section name...]- See the
Afterparameter in theAutoloadsection.Object[object filename...]- Specifies the object files that are included in the LTD Autoload Module.
As a result of compiling the source file specified by the makefile'sSRCS_LTDAUTOLOADvariable, the generated object file is given with a path tomakelcfas$(OBJS_LTDAUTOLOAD). If it is not necessary to specify successive object files, use the following format.Everything aside from what appears above is the same as theObject $(OBJS_LTDAUTOLOAD)Objectparameter in theStaticsection.Library[library filename...]- This specifies the library files that are included in the LTD Autoload Module. As a result of compiling library groups specified by the makefile's
LLIBRARIES_EXvariable, the compiled group and SDK library groups are given tomakelcfas$(LLIBS_EX)and$(GLIBS_EX), respectively. Use the following format to specify the libraries.The library file described inLibrary $(LLIBS_EX) $(GLIBS_EX)Libraryis passed with the-1option to the response file.SearchSymbol[Other section name or overlay group name...]- Same as the
SearchSymbolparameter in theStaticsection.
Force[symbol name, object filename, or library name]- Same as the
Forceparameter in theStaticsection.
Address[address]- See the
Addressparameter in theStaticsection.After[other section name...]- See the
Afterparameter in theAutoloadsection.Object[object filename...]- Specifies the object files that are included in the Overlay Module.
As a result of compiling the source file specified by the makefile'sSRCS_LTDOVERLAYvariable, the generated object file is given with a path tomakelcfas$(OBJS_LTDOVERLAY). If it is not necessary to specify successive object files, use the following format.Everything other than what appears above is the same as theObject $(OBJS_LTDOVERLAY)Objectparameter in theStaticsection.Library[library filename...]- See the
Libraryparameter in theStaticsection.Group[overlay_group_name]- Same as the
Overlaysection'sGroupparameter.SearchSymbol[Other section name or overlay group name...]- Same as the
SearchSymbolparameter in theStaticsection.
Force[symbol name, object filename, or library name]- Same as the
Forceparameter in theStaticsection.
Compress[Smart|Exclusion]- Specifies whether to exclude the target from compression when compressing the resident module using
compstatic.TWL.
The following values can be specified.
SmartWhen the -Coption is passed tocompstatic.TWL, the specified compression is applied.This operation results even if theCompressoption has not been specified.ExclusionWhen the -Coption is passed tocompstatic.TWL, the target is excluded from compression.
OverlayDefs[Overlay Name Filename (without extension)]- Specifies the filename (excluding extension) for the Overlay Name file that gets created at link time. If the filename starts with
%, the%sign is replaced with the [name of the static module section] specified at the start of theStaticsection. It can be omitted, in which case"%_defs"gets used.OverlayTable[OverlayTable filename]- Specifies the filename (excluding an extension) for the Overlay Table file that gets created at the time of linking. If the filename starts with
%, the%sign is replaced with the [name of the static module section] specified at the start of theStaticsection. It can be omitted, in which case%_tableis used.Suffix[File extension for application binary files]- Specifies the filename extension for the binary files that get created at the time of linking a NITRO build. It can be omitted, in which case
.sbinis used.LtdoverlayDefs[LTD Overlay Name Filename (without extension)]- Specifies the filename (excluding an extension) for the LTD Overlay Name file that is created at the time of linking. If the filename starts with
%, the%sign is replaced with the [name of the static module section] specified at the start of theStaticsection. It can be omitted, in which case"%_defs"gets used.LtdoverlayTable[LTD OverlayTable filename]- Specifies the filename (excluding an extension) for the Overlay Table file that gets created at the time of linking. If the filename starts with
%, the%sign is replaced with the [name of the static module section] specified at the start of theStaticsection. It can be omitted, in which case%_tableis used.Flxsuffix[Extension for application binary files]- Specifies the filename extension for the binary files in the NITRO/TWL-compatible region that is created at the time of linking a TWL build. It can be omitted, in which case
.TWL.FLX.sbinis used.Ltdsuffix[Extension for application binary files]- Specifies the filename extension for the binary files in the TWL-exclusive region that get created at the time of linking a TWL build. It can be omitted, in which case
.TWL.LTD.sbinis 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. The following is an example of a description for a variable reference.
Static $(TARGET_NAME)
{ Address $(START_ADDRESS) Object * }
If the variable value is in 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/Twl/readme.txt:
:hThe portion of the path before the final path delimiter. $(FILE:h)=C:/home/Twl/:tThe portion of the path after the final path delimiter. $(FILE:t)=readme.txt:rThe path, excluding the file extension. $(FILE:r)=C:/home/Twl/readme:eThe file extension. $(FILE:e)=txt
Keywords such as "Static" used in section definitions can be written this way, all in uppercase ("STATIC"), or all in lowercase ("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 { .... }
$TwlSDK/tools/bin/makelcf.exe
$TwlSDK/tools/bin/makelcf.TWL.exe
makerom
compstatic
compstatic.TWL
FSOverlayID
2009/11/11 Added the Force parameter to the Static, Autoload, Overlay, Ltdautoload, and Ltdoverlay sections.
2009/10/20 Added the Compress parameter to the Overlay and Ltdoverlay sections.
2008/12/16 Changed the address in the static-module definition example from 0x02000400 to 0x02004000.
2008/09/12 Added a description of makelcf.TWL.
2007/04/11 Changed the description of operations when the makelcf argument LCFILE is omitted. Added a description of SearchSymbol in other than Overlay Section.
2007/01/19 Changed the default IRQ stack size.
2006/05/09 Made it possible to select overlay groups to find symbols during linking.
2005/09/02 Made revisions in line with added support for overlay groups.
2004/07/20 Revisions in line with SDK 2.0 overlay operation changes.
2004/05/25 Initial version.
CONFIDENTIAL