makelcf[.TWL]

# makelcf

# makelcf.TWL

## Description

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.

## 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 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 (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 will be used. If `-V2` is designated, the format for the 2.x version will be used.

### Linker Spec File Format

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

Resident
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 Overload
Module
`(Ltdautoload)`
Available Only n a TWL Environment

    Ltdautoload [section name]
    {
      [section parameter description part]
      ....
    }

    Ltdautoload LTDMAIN
    {
      After     main
      After     overlay_1
      Object    *                (.ltdmain)
      Object    $(OBJS_LTDAUTOLOAD)
      Library $(LLIBS_EX) $(GLIBS_EX)
    }

LTD Overlay
Module
`(Ltdoverlay)`
Available Only in a 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 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.

### Section Parameters

#### Static section (Resident 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 name...]
>   This specifies the object files to include in the Resident 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 will be 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 module name...]
>   Specify the library file in the resident 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` will be passed to the response file along with the `-l` options.
> `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 will result 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.
> `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 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 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 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...]
>   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)`

>   Everything aside from that shown above is the same as the `Object` parameter in the `Static` section.
> `Library` [library module name...]
>   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.

#### Overlay Section (Overlay Module Definitions Section)

> `Address` [address]
>   See the `Address` parameter in the `Static` section.
> `After` [other section name...]
>   The same as the `After` parameter in the `Autoload` section.
> `Object` [object name...]
>   This 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)`

>   Everything aside from that shown above is the same as the `Object` parameter in the `Static` section.
> `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 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.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...]
>   Same as the `SearchSymbol` parameter in the `Static` section.

#### Ltdautoload Section (LTD Autoload Module Definitions Section)

This section can be used only in the TWL environment.
When NITRO/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 name...]
>   This 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)`

>   Everything aside from that shown above is the same as the `Object` parameter in the `Static` section.
> `Library` [library module name...]
>   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.

#### 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 name...]
>   Specifies the object files that are included in the Overlay Module.
>   When using the SDK's `make` system, the result of compiling the source files specified by the variable `SRCS_LTDOVERLAY` inside `Makefile` and the object files generated are given by `makelcf` with paths in the form `$(OBJS_LTDOVERLAY)`. The following type of coding can be used if specification of sequential object files is not necessary.

>   > `Object $(OBJS_LTDOVERLAY)`

>   Everything aside from that shown above is the same as the `Object` parameter in the `Static` section.
> `Library` [library module name...]
>   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.

#### Property Section (Incidental Information Definitions Section)

> `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 the `Static` section. 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 the `Static` section. 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 a NITRO build. It can be omitted, in which case `.sbin` is used.
> `LtdoverlayDefs` [LTD Overlay Name Filename (without extension)]
>   This 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 resident part section] specified at the start of the `Static` section. It can be omitted, in which case `"%_defs"` gets used.
> `LtdoverlayTable` [LTD 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 `%`, the `%` sign is replaced with the [name of the resident part 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]
>   This 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]
>   This 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`
`FSOverlayID`

## Revision History

2008/12/16 Changed the address in the resident 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