makelcf


Location

$NitroSDK/tools/bin/makelcf.exe

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:

How to use makelcf

Run 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. This last parameter can be omitted, in which case the Linker Command file takes the same name as that of the file specified by SPECFILE, but with the extension changed to .lcf.

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

When the application boots up, the program code is divided by the IPL into code for the "Resident Module," which gets transferred to memory, and code for the "Overlay Module," which gets expanded in memory on instruction from the application. 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
}


For the Static and Overlay sections, a section name is specified to identify the section (see the examples above). 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 which 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

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

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. The current section is placed immediately after the end address with the largest section. 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 file name...]

Same as the Library parameter in the Static section.

Overlay section (Overlay Module definitions section)

Address[address]

Same as the Static section's Address parameter.

After[other section names ...]

Places the current section immediately after the specified other sections. 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 valid at the same time inside the same section. The one that is specified first has priority.

Object[object file names ...]

Same as the Static section's Object parameter.

Library [library file name...]

Same as the Library parameter in the Static section.

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

See Also

makerom, FSOverlayID

Revision History

07/20/2004 Correction due to the change in the SDK 2.0 Overlay operation 05/25/2004 Initial version