makelcf

makelcf.TWL

Description

The TWL-SDK has a tool to support a technique called overlay that divides a program too big to fit in memory into files, stores these as ROM images, and then loads code into memory from the ROM images, as needed, upon 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.

If you changed the default placement destinations of the Static, ITCM, and DTCM regions using the LSF file, you must change the addresses of check.MAIN/ITCM/DTCM in the LCF template file.

Using the Tool

Start Command

% 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.

Linker Spec File Format

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 [section name]
{
  [section parameter description part]
  ....
}
 
Static  main
{
  Address   0x02004000
  Object    $(OBJS_STATIC)
  Library $(LLIBS) $(GLIBS) $(CW_LIBS)
  StackSize 1024
}
Autoload
Module
(Autoload)		 
Autoload [section name]
{
  [section parameter description part]
  ....
}
 
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		 
Ltdautoload [section name]
{
  [section parameter description part]
  ....
}
 
Ltdautoload LTDMAIN
{
  After     main
  After     overlay_1
  Force     (function, main.o)
  Object    $(OBJDIR)/main.o (.text)
  Object    *                (.ltdmain)
  Object $(OBJS_LTDAUTOLOAD)
  Library $(LLIBS_EX) $(GLIBS_EX)
}
LTD Overlay
Module
(Ltdoverlay)

Available only in TWL environment		 
Ltdoverlay [section name]
{
  [section parameter description part]
  ....
}
 
Ltdoverlay  ltdoverlay_1
{
  After     LTDMAIN
  Object    $(OBJDIR)/ltdoverlay.o
}
Incidental
information
(Property)		 
Property
{
  [Incidental information parameter description part]
  ....
}
 
Property
{
  OverlayDefs  %_defs
  OverlayTable %_table
  Suffix       .sbin
}


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.

Section Parameters

Static Section (Static Module Definitions 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 to makelcf as $(OBJDIR), so you can specify the object path in the following format.
Object $(OBJDIR)/main.o
　As a result of compiling the source file specified by the makefile's SRCS variable, the generated object file is given with a path to makelcf as $(OBJS_STATIC). If it is not necessary to specify successive object files, you can use the following format.
Object $(OBJS_STATIC)
The object file specified by Object is passed with a path to the response file (*.response). Similar to executable binaries, makelcf creates response files in the $(BINDIR) directory.

Specify library files with the new Library statement instead of the Object statement.

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.
Object * (.itcm)
　This specification refers to all files defined in the .itcm section. 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 make system, library groups specified with the variable LLIBRARIES in 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.
Library $(LLIBS) $(GLIBS) $(CW_LIBS)
The library file described in Library is passed with the -1 option 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 run makelcf with the -V2 option 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.


The Force statement corresponds to the FORCE_OBJECT keyword used in LCF files, so the object files specified using Force must be placed in the same section using the Object statement.

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 NitroMain function 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 depends on the sign 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 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 is 0x800 bytes.

Autoload Section (Autoload Module Definitions Section)

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 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 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's SRCS_AUTOLOAD variable, the generated object file is given with a path to makelcf as $(OBJS_AUTOLOAD). If it is not necessary to specify successive object files, use the following format.
Object $(OBJS_AUTOLOAD)
　 Otherwise, the behavior is the same as the Object parameter in the Static section.
Library [library filename...]
　Same as the Library parameter in the Static section.
SearchSymbol [Other section name or overlay group name...]
　 Same as the SearchSymbol parameter in the Static section.
Force [symbol name, object filename, or library name]
　Same as the Force parameter in the Static section.

Overlay Section (Overlay Module Definitions Section)

Address [address]
See the Address parameter in the Static section.
After [other section name...]
See the After parameter in the Autoload section.
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's SRCS_OVERLAY variable, the generated object file is given with a path to makelcf as $(OBJS_OVERLAY). If it is not necessary to specify successive object files, use the following format.
Object $(OBJS_OVERLAY)
　 Otherwise, the behavior is the same as the Object parameter in the Static section.
Library [library filename...]
　 See 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 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 SearchSymbol parameter in the Static section.
Force [symbol name, object filename, or library name]
　 Same as the Force parameter in the Static section.
Compress [Smart|Exclusion]
　 Specifies whether to exclude the target from compression when compressing the static module using compstatic (compstatic.TWL).

The following values can be specified.
Smart When the -c option is passed to compstatic (compstatic.TWL), the specified compression is applied.
This operation results even if the Compress option has not been specified.
Exclusion When the -c option is passed to compstatic (compstatic.TWL), the target is excluded from compression.

Ltdautoload Section (LTD Autoload Module Definitions Section)

　This section can be used only in the TWL environment.
　When NITRO or TWL shared overlays exist, this section must be placed after those overlays.

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 Address parameter in the Static section.
After [other section name...]
See the After parameter in the Autoload section.
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's SRCS_LTDAUTOLOAD variable, the generated object file is given with a path to makelcf as $(OBJS_LTDAUTOLOAD). If it is not necessary to specify successive object files, use the following format.
Object $(OBJS_LTDAUTOLOAD)
　 Otherwise, the behavior is the same as the Object parameter in the Static section.
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_EX variable, the compiled group and SDK library groups are given to makelcf as $(LLIBS_EX) and $(GLIBS_EX), respectively. Use the following format to specify the libraries.
Library $(LLIBS_EX) $(GLIBS_EX)
The library file described in Library is passed with the -1 option to the response file.
SearchSymbol [Other section name or overlay group name...]
　 Same as the SearchSymbol parameter in the Static section.
Force [symbol name, object filename, or library name]
　Same as the Force parameter in the Static section.

Ltdoverlay Section (LTD Overlay Module Definitions Section)

　This section can be used only in the TWL environment.
Address [address]
See the Address parameter in the Static section.
After [other section name...]
See the After parameter in the Autoload section.
Object [object filename...]
　 Specifies the object files that are included in the Overlay Module.

As a result of compiling source code files specified by the makefile's SRCS_LTDOVERLAY variable, the generated object file and path are given to makelcf as $(OBJS_LTDOVERLAY). If it is not necessary to specify successive object files, use the following format.
Object $(OBJS_LTDOVERLAY)
　 Otherwise, the behavior is the same as the Object parameter in the Static section.
Library [library filename...]
　 See the Library parameter in the Static section.
Group [overlay_group_name]
　Same as the Overlay section's Group parameter.
SearchSymbol [Other section name or overlay group name...]
　 Same as the SearchSymbol parameter in the Static section.
Force [symbol name, object filename, or library name]
　 Same as the Force parameter in the Static section.
Compress [Smart|Exclusion]
　 Specifies whether to exclude the target from compression when compressing static modules using compstatic.TWL.

The following values can be specified.
Smart When the -C option is passed to compstatic.TWL, the specified compression is applied.
This operation results even if the Compress option has not been specified.
Exclusion When the -C option is passed to compstatic.TWL, the target is excluded from compression.

Property Section (Incidental Information Definitions Section)

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 the Static section. 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 the Static section. It can be omitted, in which case %_table is 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 .sbin is 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 the Static section. 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 the Static section. It can be omitted, in which case %_table is 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.sbin is 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.sbin is used.

Variable References and Modifier Options

　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:
:h The portion of the path before the final path delimiter. $(FILE:h)=C:/home/Twl/
:t The portion of the path after the final path delimiter. $(FILE:t)=readme.txt
:r The path, excluding the file extension. $(FILE:r)=C:/home/Twl/readme
:e The file extension. $(FILE:e)=txt

Other Formats

　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
{
   ....
}

Location

$TwlSDK/tools/bin/makelcf.exe
$TwlSDK/tools/bin/makelcf.TWL.exe

See Also

makerom
compstatic
compstatic.TWL
FSOverlayID

Revision History

2010/04/02 Added a note that it is necessary to revise the LCF template file if the default placement destinations for Static, ITCM, and DTCM regions are changed.
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