# makelcf

## Description

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:

- Added a support system called AUTOLOAD to load the program into several regions.
- Made changes to use `makelcf` to generate the linker response file (command line option passed to a linker is described in a file).

## How to Use

### Start Command

``% makelcf [-DNAME=VALUE...] [-MDEFINES_FILE] 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 those 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. The 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.

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

Subject of section definition | Format for section definition | 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)`

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

    Autoload ITCM
    {
    Address   0x01ff8000
    Object    *                (.itcm)
    Object    $(OBJS_AUTOLOAD) (.text)
    }

Overlay
module
`(Overlay)`

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

    Overlay  overlay_1
    {
    After     main
    Object    $(OBJDIR)/overlay.o
    }

Incidental
information
`(Property)`

    Property
    {
    {
    [Incidental information parameter description part]
      ....
    }

    Property
    {
    {
    {
    OverlayDefs  %_defs

    OverlayTable %_table

    Suffix       .sbin
    }

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.

### Section Parameters

#### Static section (Resident Module definitions 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 to `makelcf`, and the path name for the object can be specified in the following format.

>   > `Object $(OBJDIR)/main.o`

>   After the source file which was specified in the makefile as the variable `SRCS` was compiled, the generated object file is given to `makelcf` as `$(OBJS_STATIC)` with paths. When it is not necessary to specify the object file every time, it can be expressed as the following.

>   > `Object $(OBJS_STATIC)`

>   The object file described in object is passed with path to the response file (`*.response`). Like the execution binaries, `makelcf` generates 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 utilize the special section to support loading into ITCM/DTCM/VRAM.

>   > `Object * (.itcm)`

>   This indicates all files defined in the `.itcm` section. 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 SDK `make` system, library groups specified with the variable `LLIBRARIES` in 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:

>   > `Library $(LLIBS) $(GLIBS) $(CW_LIBS)`

>   Library file described in Library will be passed to the response file along with the -1 options.
> `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 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...]
>   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.

#### Overlay section (Overlay Module definitions 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.) 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 `Static` section's `Object` parameter.
> Library [library module name...]
>   Same as the Library parameter in the Static section.
> `Group` [OVERLAY _group]
>   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 calling inline functions occur, it may be possible to resolve the problem using the overlay group setting during the DEBUG build.
>   The group with the same name as the current section name is set if the overlay group specification is omitted to maintain compatibility.
>   This overlay group specification is supported with versions including and after SDK 3.0RC1.

#### Property section (Incidental Information definitions section)

> `OverlayDefs`[Filename (without extension) for Overlay Name file)]
>   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. It can be omitted, in which case `".sbin"` gets 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. 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`:

> `:h` | The portion of the path before the final path delimiter | `$(FILE:h)=C:/home/Nitro/`
> `:t` | The portion of the path after the final path delimiter | `$(FILE:t)=readme.txt`
> `:r` | The portion of the path excluding the file extension | `$(FILE:r)=C:/home/Nitro/readme`
> `:e` | The path file-extension portion | `$(FILE:e)=txt`

### Other formats

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

## Location

`$NitroSDK/tools/bin/makelcf.exe`

## See Also

`makerom, FSOverlayID`

## Revision History

09/02/2005 Made revisions in line with overlay group support.
07/20/2004 Made revisions in line with changes to overlay operations under SDK2.0.
05/25/2004 Initial version.