makelcf

makelcf.TWL

説明

　TWL-SDK では、メモリに入りきらない大きなアプリケーションプログラムを実行するために、アプリケーションプログラムをファイルに分割、そしてROM イメージとして保持しておき、ROM イメージ上のコードが必要となったときにアプリケーションの指示でメモリ上にロード、初期化して実行する、いわゆるオーバーレイと呼ばれるテクニックと AUTOLOAD と呼ばれる起動時に複数の領域へプログラムをロードするための仕組みを支援するためのツールを用意しています。

　makelcf は NITRO 実行ファイル、makelcf.TWL は TWL 実行ファイルにおいてオーバーレイをサポートするためのリンカコマンドファイル(LCF)を自動的に作成するためのツールです。 makelcf[.TWL] は、リンカスペックファイル(LSF) と呼ばれるファイルの記述を元にして、LCF のテンプレートファイルから各アプリケーション用の LCF を生成します。

LSF ファイルで Static, ITCM, DTCM 領域の配置先を、それぞれデフォルトの配置先から変更した場合は、LCF テンプレートファイルの check.MAIN/ITCM/DTCM のアドレスを変更する必要がありますので、注意してください。

使用方法

起動コマンド

% makelcf [-DNAME=VALUE...] [-MDEFINES_FILE] [-V1|-V2] SPECFILE LCF-TEMPLATE [LCFILE]

　SPECFILE で指定されたリンカスペックファイル(LSF) の記述にしたがって、LCF-TEMPLATE で指定された LCF テンプレートファイルから、リンカコマンドファイル(LCF) を LCFILE で指定された名前で作成します。LCFILE は省略可能です。省略時には生成されたLCFの内容を標準出力へ書き出します。

-D オプションにより変数とその値を定義することができます。この変数の値はリンカスペックファイルの記述時に参照することができます。

-M オプションは -D オプションと同様に変数とその値を定義するものです。[NAME=VALUE] の列から成るテキストファイルを引数として受けます。このオプションによりコマンドラインの制限を超えてしまうような長さの変数とその値の定義の記述を行なうことができます。

CodeWarrior for NINTENDO DS(以下 CodeWarrior) のバージョン 2.0 以降において拡張された LCF ファイルによるオーバーレイ使用時におけるリンクシンボルを指定する機能（SEARCH_SYMBOL 記述）に対応するため、 lsf ファイル書式が拡張されています。-V1 および -V2 オプションは、makelcf が LCF のテンプレートファイルから LCF ファイルを出力する際に、CodeWarrior の 1.x または 2.x のどちらの書式を選択するかを指定するためのものです。-V1 が指定される、あるいは -Vオプションの指定がない場合は 1.x 用の書式が、-V2 が指定されると 2.x 用の書式が採用されます。

リンカスペックファイルフォーマット

　オーバーレイにおいては、プログラムコードを、ブートアップ時に IPL によってメモリへ転送される“常駐モジュール”と、アプリケーションの指示に応じてメモリ上に展開される“オーバーレイモジュール”に分類します。オーバーレイモジュールはメモリなどの資源が許すならば必要に応じて複数個作成することができます。

　リンカスペックファイル(LSF) は、このオーバーレイに関する諸設定を定義するためのファイルです。これを使って、アプリケーションプログラムを構成するコードの各オブジェクトファイルをどのように分類し、ファイル化するかを定義します。

　LSF は、以下に示したセクション定義から構成されるテキストファイルです。セクション定義の書式は、セクション定義開始の宣言部の後に引き続いて各セクションに関するパラメータが中括弧{ } で囲まれて記載されるという形式になっています。

セクションの
定義対象		 セクション定義の書式 定義例
常駐
モジュール
(Static)		 
Static [セクション名]
{
  [セクションパラメータ記述部]
  ....
}
 
Static  main
{
  Address   0x02004000
  Object    $(OBJS_STATIC)
  Library   $(LLIBS) $(GLIBS) $(CW_LIBS)
  StackSize 1024
}
オートロード
モジュール
(Autoload)		 
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)		 
Overlay [セクション名]
{
  [セクションパラメータ記述部]
  ....
}
 
Overlay  overlay_1
{
  After     main
  Object    $(OBJDIR)/overlay.o
}
LTD オートロード
モジュール
(Ltdautoload)

TWL 環境でのみ使用可能		 
Ltdautoload [セクション名]
{
  [セクションパラメータ記述部]
  ....
}
 
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 オーバーレイ
モジュール
(Ltdoverlay)

TWL 環境でのみ使用可能		 
Ltdoverlay [セクション名]
{
  [セクションパラメータ記述部]
  ....
}
 
Ltdoverlay  ltdoverlay_1
{
  After     LTDMAIN
  Object    $(OBJDIR)/ltdoverlay.o
}
付帯情報
(Property)		 
Property
{
  [付帯情報パラメータ記述部]
  ....
}
 
Property
{
  OverlayDefs  %_defs
  OverlayTable %_table
  Suffix       .sbin
}


　Static,Overlay のセクションそれぞれについてセクションを識別するためのセクション名を指定します(上のサンプル参照)。このセクション名を使って、オーバーレイID などを取得することができます。具体的な方法は、FS ライブラリのオーバーレイ ID に関する説明などを参考にしてください。

　一つのLSFにおいて常駐モジュールセクションは必ず一つ必要で、オーバーレイを使用しない場合でも省略はできません。オーバーレイモジュールセクションは分割したいオーバーレイモジュールの数と同数必要です。もしオーバーレイを使用しない場合は、オーバーレイモジュールセクションは必要ありません。付帯情報セクションは省略可能です。省略されたときは全ての付帯情報パラメータに対してそれぞれのデフォルト値が適用されます。

以下に各セクションで設定するパラメータについて解説します。

セクションパラメータ

Static セクション (常駐モジュール定義セクション)

Address [アドレス]
　セクションが指定したアドレスに配置されるよう設定します。アドレスの指定には10進数のほか C 言語と同様に先頭に"0x"や"0"を付けることで16進数や8進数が使用できます。
Object [オブジェクトファイル名...] [(セクション選択)]
　常駐モジュール内に含むオブジェクトファイルを指定します。

　リンカのレスポンスファイルの生成を行なう必要があるため、オブジェクトファイルの指定において、ファイル名とパスの指定が必須です。SDK の make システムを使用している場合、オブジェクトへのパスは $(OBJDIR) として makelcf に与えられるために以下のような書式によりオブジェクトのパスの指定ができます。
Object $(OBJDIR)/main.o
　またMakefile 内で変数 SRCS に指定したソースファイルをコンパイルした結果、生成されるオブジェクトファイルが $(OBJS_STATIC) としてパス付きで makelcf に与えられるため、上記のように逐次オブジェクトファイルを指定する必要のない場合には、以下のように表記することができます。
Object $(OBJS_STATIC)
　Object に記述されたオブジェクトファイルはパス付きでレスポンスファイル(*.response)へ渡されます。レスポンスファイルは makelcf によって実行バイナリと同様に $(BINDIR)ディレクトリに作成されます。

　ライブラリは Object 文には記述せずに、新設された Library 文に記述してください。

　その他にも、ITCM / DTCM / WRAM へのロードをサポートする等の用途のために特殊なセクションをサポートできるように"*"を使った、以下のような指定方法が使用できます。
Object * (.itcm)
　これは .itcm という名のセクション内で定義されている全てのファイルを意味します。この記述はオートロードセクションで使用されることが多いです。
Library [ライブラリファイル名...]
　常駐モジュール内に含むライブラリファイルを指定します。

　SDK の make システムを使用している場合、Makefile 内で変数 LLIBRARIES に指定したライブラリ群、SDK のライブラリ群、および CodeWarrior のライブラリ群がそれぞれ、$(LLIBS),$(GLIBS),$(CW_LIBS) として makelcf に与えられるために以下のような書式によりライブラリの指定ができます。
Library $(LLIBS) $(GLIBS) $(CW_LIBS)
　Library に記述されたライブラリファイルは -l オプションと共にレスポンスファイルへ渡されます。
SearchSymbol [他のセクション名またはオーバーレイグループ名...]
　同一名のシンボルが複数のセクションに渡って存在している場合に、その中のどのシンボルとリンクするのかを指定する為に設定します。この指定はセクション毎に設定することができます。

　リンカは現在のセクションから参照するシンボルを探すのに、まず自身のセクションの中を検索し、次に、この指定で記述されたセクションあるいはオーバーレイグループを順に検索していきます。もし、ここに記述されたセクションあるいはオーバーレイグループからは見つからなかった場合、リンクエラーとなります。

　省略時は、全てのセクションがシンボル検索対象になります。この場合、全体として該当する名前のシンボルが１つしか存在していない場合はそのシンボルがリンクされますが、全体として該当する名前のシンボルが複数存在している場合はリンカがどのシンボルを使用すれば良いのか判断出来ないのでリンクエラーとなります。

　本機能を使用する場合には makelcf を CodeWarrior for NINTENDO DS バージョン 2.0 対応モード(⇒オプション -V2) で起動させる必要があります。
Force [シンボル名, オブジェクトファイル名またはライブラリ名]
　特定のシンボルを任意のセクションに配置するために指定します。

　Force 文は LCF ファイルに記述できるキーワードである FORCE_OBJECT に対応しているだけとなるため、実際に配置するためには Force で指定したオブジェクトファイルを同じセクションに Object 文等で配置しておく必要があります。
　詳しくは CodeWarrior の説明を参照してください。

　本機能は CodeWarrior for DSi v.1.2 patch1 以降の対応となります。
StackSize [スタックサイズ(byte数)]
　または
StackSize [スタックサイズ(byte数)] [IRQ スタックサイズ(byte数)]
　常駐モジュールで最初に実行される NitroMain() 関数のスタックサイズと IRQ のスタックサイズを指定します。それぞれのサイズ指定には 16/10/8 進数が使用できます。

　スタックサイズ値は、数値の符号により以下のような意味となります。
正のとき この値で指定されるバイト数をスタックに割り当てます。
0 のとき 確保できる最大サイズをスタックに割り当てます。
負のとき 確保できる最大サイズからこの値の絶対値を引いた分をスタックに割り当てます。

　IRQ スタックサイズはそのままの値が IRQ で使用するスタックサイズとして割り当てられます。
このスタックサイズ、IRQスタックサイズのそれぞれの指定は、省略可能です。省略時にはスタックサイズは0(最大限度まで確保)、IRQ スタックサイズは 0x800 バイトとなります。

Autoload セクション (オートロードモジュール定義セクション)

オートロードとはプログラムの起動時に複数の領域へモジュールを転送するための機構です。転送処理はcrt0.o 内において通常のライブラリの呼び出しの前に処理されるため、OS や FS などのシステムライブラリでさえ ITCM / DTCM へ転送を行なうことが可能です。ITCM / DTCM へオートロードされるセクションの名前として、ITCM または DTCM が予約されています。このうちのどちらかを指定してください。

Address [アドレス]
　Static セクションでの Address パラメータと同様です。
After [他のセクション名...]
　指定した他のセクションの直後に、現セクションが配置されます。After に複数のセクションが指定されている場合は、それらの全てのセクションと領域が重ならないように、最も終了アドレスが大きいセクションの直後に、現セクションが配置されます。同一セクション内でAddressとAfterは同時には有効にはなりません。先に記述されているほうが優先されます。
Object [オブジェクトファイル名...] [(セクション選択)]
　オートロードモジュール内に含むオブジェクトファイルを指定します。

　SDK の make システムを使用している場合、Makefile 内で変数 SRCS_AUTOLOAD に指定したソースファイルをコンパイルした結果、生成されるオブジェクトファイルが $(OBJS_AUTOLOAD) としてパス付きで makelcf に与えられるため、逐次オブジェクトファイルを指定する必要のない場合には、以下のように表記することができます。
Object $(OBJS_AUTOLOAD)
　上記以外はStatic セクションでの Object パラメータと同様です。
Library [ライブラリファイル名...]
　Static セクションでの Library パラメータと同様です。
SearchSymbol [他のセクション名またはオーバーレイグループ名...]
　Static セクションでの SearchSymbol パラメータと同様です。
Force [シンボル名, オブジェクトファイル名またはライブラリ名]
　Static セクションでの Force パラメータと同様です。

Overlay セクション (オーバーレイモジュール定義セクション)

Address [アドレス]
Static セクションでの Address パラメータと同様です。
After [他のセクション名...]
Autoload セクションでの After パラメータと同様です。
Object [オブジェクトファイル名...]
　オーバーレイモジュール内に含むオブジェクトファイルを指定します。

　SDK の make システムを使用している場合、Makefile 内で変数 SRCS_OVERLAY に指定したソースファイルをコンパイルした結果、生成されるオブジェクトファイルが $(OBJS_OVERLAY) としてパス付きで makelcf に与えられるため、逐次オブジェクトファイルを指定する必要のない場合には、以下のように表記することができます。
Object $(OBJS_OVERLAY)
　上記以外はStatic セクションでの Object パラメータと同様です。
Library [ライブラリファイル名...]
　Static セクションでの Library パラメータと同様です。
Group [オーバーレイグループ名]
　現セクションが属するオーバーレイグループを指定します。

　リンカは同一グループに属するオーバーレイが、同じメモリ領域上に配置されていると仮定します。互いに排他的なオーバーレイモジュールを同一のグループに指定しておくことで、そのオーバーレイ間の関数呼び出しをリンク時にエラーとして検出できます。また、コンパイラが inline 宣言された関数を実際に inline 化する、あるいは inline 化しないの判断において、各オーバーレイモジュールのオーバーレイグループの設定も参照されます。DEBUG ビルド時のみにおいて inline 関数の呼び出しに関する問題が発生している場合、オーバーレイグループの設定により問題を解決できる可能性があります。

　このオーバーレイグループの指定機能は SDK 3.0RC1 からサポートされました。互換性保持のため、オーバーレイグループ省略時には現セクション名と同じ名のグループが設定されます。
SearchSymbol [他のセクション名またはオーバーレイグループ名...]
　Static セクションでの SearchSymbol パラメータと同様です。
Force [シンボル名, オブジェクトファイル名またはライブラリ名]
　Static セクションでの Force パラメータと同様です。
Compress [Smart|Exclusion]
　常駐モジュールを compstatic(compstatic.TWL) で圧縮するときに、圧縮対象から除外するかを指定します。

　指定できる値と意味は以下の通りです。
Smart compstatic(compstatic.TWL) に -c オプションが渡されたとき、それに従い圧縮をかけます。
Compress オプションを指定しなかった場合もこの動作になります。
Exclusion compstatic(compstatic.TWL) に -c オプションが渡されたとき、その圧縮対象から除外します。

Ltdautoload セクション (LTD オートロードモジュール定義セクション)

　このセクションは TWL 環境でのみ使用可能です。
　NITRO/TWL 共有のオーバーレイが存在する場合は、このセクションをさらにその後ろに配置する必要があります。

LTD オートロードとはプログラムの起動時に LTD 領域へモジュールを転送するための機構です。転送処理はcrt0.o 内において通常のライブラリの呼び出しの前に処理されます。LTD 領域へオートロードされるセクションの名前として、LTDMAIN が予約されています。これを指定してください。

Address [アドレス]
　Static セクションでの Address パラメータと同様です。
After [他のセクション名...]
Autoload セクションでの After パラメータと同様です。
Object [オブジェクトファイル名...]
　LTD オートロードモジュール内に含むオブジェクトファイルを指定します。

　SDK の make システムを使用している場合、Makefile 内で変数 SRCS_LTDAUTOLOAD に指定したソースファイルをコンパイルした結果、生成されるオブジェクトファイルが $(OBJS_LTDAUTOLOAD) としてパス付きで makelcf に与えられるため、逐次オブジェクトファイルを指定する必要のない場合には、以下のように表記することができます。
Object $(OBJS_LTDAUTOLOAD)
　上記以外はStatic セクションでの Object パラメータと同様です。
Library [ライブラリファイル名...]
　LTD オートロードモジュール内に含むライブラリファイルを指定します。

　SDK の make システムを使用している場合、Makefile 内で変数 LLIBRARIES_EX に指定したライブラリ群、および SDK のライブラリ群がそれぞれ、$(LLIBS_EX),$(GLIBS_EX) として makelcf に与えられるために以下のような書式によりライブラリの指定ができます。
Library $(LLIBS_EX) $(GLIBS_EX)
　Library に記述されたライブラリファイルは -l オプションと共にレスポンスファイルへ渡されます。
SearchSymbol [他のセクション名またはオーバーレイグループ名...]
　Static セクションでの SearchSymbol パラメータと同様です。
Force [シンボル名, オブジェクトファイル名またはライブラリ名]
　Static セクションでの Force パラメータと同様です。

Ltdoverlay セクション (LTD オーバーレイモジュール定義セクション)

　このセクションは TWL 環境でのみ使用可能です。
Address [アドレス]
Static セクションでの Address パラメータと同様です。
After [他のセクション名...]
Autoload セクションでの After パラメータと同様です。
Object [オブジェクトファイル名...]
　オーバーレイモジュール内に含むオブジェクトファイルを指定します。

　SDK の make システムを使用している場合、Makefile 内で変数 SRCS_LTDOVERLAY に指定したソースファイルをコンパイルした結果、生成されるオブジェクトファイルが $(OBJS_LTDOVERLAY) としてパス付きで makelcf に与えられるため、逐次オブジェクトファイルを指定する必要のない場合には、以下のように表記することができます。
Object $(OBJS_LTDOVERLAY)
　上記以外はStatic セクションでの Object パラメータと同様です。
Library [ライブラリファイル名...]
　Static セクションでの Library パラメータと同様です。
Group [オーバーレイグループ名]
　Overlay セクションでの Group パラメータと同様です。
SearchSymbol [他のセクション名またはオーバーレイグループ名...]
　Static セクションでの SearchSymbol パラメータと同様です。
Force [シンボル名, オブジェクトファイル名またはライブラリ名]
　Static セクションでの Force パラメータと同様です。
Compress [Smart|Exclusion]
　常駐モジュールを compstatic.TWL で圧縮するときに、圧縮対象から除外するかを指定します。

　指定できる値と意味は以下の通りです。
Smart compstatic.TWL に -C オプションが渡されたとき、それに従い圧縮をかけます。
Compress オプションを指定しなかった場合もこの動作になります。
Exclusion compstatic.TWL に -C オプションが渡されたとき、その圧縮対象から除外します。

Property セクション (付帯情報定義セクション)

OverlayDefs [オーバーレイネームファイル名(拡張子抜き)]
　リンク時に生成されるオーバーレイネームファイルのファイル名の拡張子を除いた部分を指定します。ファイル名の先頭が"%"になっている場合は、"%"の部分がStatic セクション開始部で指定された[常駐部分のセクション名称] に置換されます。省略可能で、省略時は "%_defs" が使われます。
OverlayTable [オーバーレイテーブルファイル名]
　リンク時に生成されるオーバーレイテーブルファイルのファイル名の拡張子を除いた部分を指定します。ファイル名の先頭が"%"になっている場合は、"%"の部分がStatic セクション開始部で指定された[常駐部分のセクション名称] に置換されます。省略可能で、省略時は "%_table" が使われます。
Suffix [アプリケーションバイナリファイルの拡張子]
　NITRO ビルドのリンク時に生成される各バイナリファイルの拡張子を指定します。省略可能で、省略時は ".sbin" が使われます。
LtdoverlayDefs [LTD オーバーレイネームファイル名(拡張子抜き)]
リンク時に生成される LTD オーバーレイネームファイルのファイル名の拡張子を除いた部分を指定します。ファイル名の先頭が"%"になっている場合は、"%"の部分がStatic セクション開始部で指定された[常駐部分のセクション名称] に置換されます。省略可能で、省略時は "%_defs" が使われます。
LtdoverlayTable [LTD オーバーレイテーブルファイル名]
　リンク時に生成されるオーバーレイテーブルファイルのファイル名の拡張子を除いた部分を指定します。ファイル名の先頭が"%"になっている場合は、"%"の部分がStatic セクション開始部で指定された[常駐部分のセクション名称] に置換されます。省略可能で、省略時は "%_table" が使われます。
Flxsuffix [アプリケーションバイナリファイルの拡張子]
　TWL ビルドのリンク時に生成される NITRO/TWL 互換領域のバイナリファイルの拡張子を指定します。省略可能で、省略時は ".TWL.FLX.sbin" が使われます。
Ltdsuffix [アプリケーションバイナリファイルの拡張子]
　TWL ビルドのリンク時に生成される TWL 専用領域のバイナリファイルの拡張子を指定します。省略可能で、省略時は ".TWL.LTD.sbin" が使われます。

変数参照と修飾オプション

　リンカスペックファイルの記述において $([変数名])という記述により、ファイル外部で定義された変数の値を参照することができます。変数はコマンドラインオプションの -D[変数名]=[値] あるいは環境変数で値を設定することができます。-D オプションと環境変数で同じ変数が定義された場合は -D オプションの定義が優先されます。以下は変数参照の記述例です。

Static $(TARGET_NAME)
{
    Address    $(START_ADDRESS)
    Object     *
}

　また変数の値がファイルパスの形式であった場合に、変数名の直後に:h,:t,:r,:e という修飾オプションをつけることによって、以下のような値を参照することができます。

$(FILE)=C:/home/Twl/readme.txt の場合：
:h パスの最後のパス区切り文字以前の部分 $(FILE:h)=C:/home/Twl/
:t パスの最後のパス区切り文字より後ろの部分 $(FILE:t)=readme.txt
:r パスのファイル拡張子を除いた部分 $(FILE:r)=C:/home/Twl/readme
:e パスのファイル拡張子の部分 $(FILE:e)=txt

その他の書式について

　セクション定義で使用される "Static" などのキーワードは "STATIC" のように全て大文字でも、あるいは "static" のように全て小文字でも同じものとして動作します。また '#' 以降の記述はコメントとして扱われます。

#
# '#' で始まるとコメント
#
STATIC my_app  # 大文字でも OK
{
   ....
}

場所

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

参照

makerom, compstatic, compstatic.TWL, FSOverlayID

履歴

2010/04/02 Static, ITCM, DTCM 領域の配置場所をデフォルトから変更した場合に、LCF のテンプレートファイルを修正する必要がある点を追記。
2009/11/11 Static, Autoload, Overlay, Ltdautoload, Ltdoverlay セクションに Force パラメータを追加。
2009/10/20 Overlay セクション、及び Ltdoverlay セクション に Compress パラメータを追加。
2008/12/16 常駐モジュール定義例の Address を 0x02000400 から 0x02004000 に修正
2008/09/12 makelcf.TWL に関する説明の追記
2007/04/11 makelcf の引数 LCFILE 省略時の動作解説の変更。Overlay セクション以外への SearchSymbol の解説追加。
2007/01/19 デフォルト IRQ スタックサイズ変更
2006/05/09 リンク処理時において、シンボルを検索するオーバーレイグループを選択できるようにする
2005/09/02 オーバーレイグループのサポートにともなう修正
2004/07/20 SDK2.0 オーバーレイ動作変更にともなう修正
2004/05/25 初版作成