
		TOPPERS第3世代カーネル向け Ruby版コンフィギュレータ
		ユーザーズマニュアル

		対応バージョン: Release 1.6.0
		最終更新: 2020年9月16日

このドキュメントは，TOPPERS第3世代カーネル向けRuby版コンフィギュレータ
を使用するために必要な事項を説明するものである．Rubyについての知識があ
ることを前提に記述している．

----------------------------------------------------------------------
 TOPPERS Configurator by Ruby

 Copyright (C) 2015 by FUJI SOFT INCORPORATED, JAPAN
 Copyright (C) 2015-2019 by Embedded and Real-Time Systems Laboratory
             Graduate School of Information Science, Nagoya Univ., JAPAN

 上記著作権者は，以下の(1)〜(4)の条件を満たす場合に限り，本ソフトウェ
 ア（本ソフトウェアを改変したものを含む．以下同じ）を使用・複製・改
 変・再配布（以下，利用と呼ぶ）することを無償で許諾する．
 (1) 本ソフトウェアをソースコードの形で利用する場合には，上記の著作
     権表示，この利用条件および下記の無保証規定が，そのままの形でソー
     スコード中に含まれていること．
 (2) 本ソフトウェアを，ライブラリ形式など，他のソフトウェア開発に使
     用できる形で再配布する場合には，再配布に伴うドキュメント（利用
     者マニュアルなど）に，上記の著作権表示，この利用条件および下記
     の無保証規定を掲載すること．
 (3) 本ソフトウェアを，機器に組み込むなど，他のソフトウェア開発に使
     用できない形で再配布する場合には，次のいずれかの条件を満たすこ
     と．
   (a) 再配布に伴うドキュメント（利用者マニュアルなど）に，上記の著
       作権表示，この利用条件および下記の無保証規定を掲載すること．
   (b) 再配布の形態を，別に定める方法によって，TOPPERSプロジェクトに
       報告すること．
 (4) 本ソフトウェアの利用により直接的または間接的に生じるいかなる損
     害からも，上記著作権者およびTOPPERSプロジェクトを免責すること．
     また，本ソフトウェアのユーザまたはエンドユーザからのいかなる理
     由に基づく請求からも，上記著作権者およびTOPPERSプロジェクトを
     免責すること．
 
 本ソフトウェアは，無保証で提供されているものである．上記著作権者お
 よびTOPPERSプロジェクトは，本ソフトウェアに関して，特定の使用目的
 に対する適合性も含めて，いかなる保証も行わない．また，本ソフトウェ
 アの利用により直接的または間接的に生じたいかなる損害に関しても，そ
 の責任を負わない．
 
 $Id: cfg_user.txt 189 2020-12-20 04:54:05Z ertl-hiro $
----------------------------------------------------------------------

○目次

１．Ruby版コンフィギュレータの概要
	1.1 位置付けと概要
	1.2 パス1の処理の概要
	1.3 パス2の処理の概要
	1.4 パス3の処理の概要
	1.5 パス4の処理の概要
２．コンフィギュレータの起動
３．静的APIテーブル
	3.1 静的APIテーブルの文法
	3.2 静的APIテーブルの記述例
４．値取得シンボルテーブル
	4.1 値取得シンボルテーブルの文法
	4.2 値取得シンボルテーブルの記述例
５．生成スクリプト
	5.1 NumStrクラス
	5.2 コンフィギュレータから生成スクリプトに渡される変数
		5.2.1 値取得シンボル
		5.2.2 コンフィギュレーションデータ（$cfgData）
		5.2.3 ドメインデータ（$domData）
		5.2.4 その他の変数
	5.3 生成スクリプトからコンフィギュレータに渡す変数
	5.4 パス間で引き渡す変数
	5.5 コンフィギュレータが生成スクリプトに提供する機能
		5.5.1 エラー出力関数
		5.5.2 GenFileクラス
		5.5.3 Stringクラスの拡張
		5.5.4 ロードモジュール操作ライブラリ
		5.5.5 その他の機能
６．その他
	6.1 オブジェクトIDの指定
	6.2 システムサービスへの対応（パス2における処理フェーズ）
７．バージョン履歴


１．Ruby版コンフィギュレータの概要

1.1 位置付けと概要

TOPPERS第3世代カーネル向け Ruby版コンフィギュレータ（以下，単にコンフィ
ギュレータという）は，ユーザが記述したシステムコンフィギュレーションファ
イルから，カーネルやシステムサービスの構成・初期化情報を含むファイルな
どを生成するツールである．TOPPERS第3世代カーネルにおけるシステムコンフィ
ギュレーション手順については，「TOPPERS第3世代カーネル（ITRON系）統合仕
様書」の「2.12 システムコンフィギュレーション手順」の節を参照すること．

コンフィギュレータは，TOPPERS第3世代カーネルに属する各種のカーネルやそ
の上で動作するシステムサービスに適用できるように，各カーネル／システム
サービスで共通に利用できるコンフィギュレータ本体と，カーネル／システム
サービス毎の設定ファイルで構成される．生成すべきカーネルやシステムサー
ビスの構成・初期化情報が，ターゲットシステムによって異なる場合には，ター
ゲット毎の設定ファイルも用意する．このマニュアルでは，カーネル／ターゲッ
ト毎の設定ファイルの記述方法について説明する．

「TOPPERS第3世代カーネル（ITRON系）統合仕様書」の「2.12.5 コンフィギュ
レータの処理モデル」の節に説明がある通り，コンフィギュレータは，3つない
しは4つのパスにより処理を行う．以下では，各パスの処理概要を説明する．

1.2 パス1の処理の概要

コンフィギュレータのパス1は，システムコンフィギュレーションファイルを解
釈し，そこに含まれる静的APIの整数定数式パラメータの値などをCコンパイラ
を用いて求めるために，パラメータ計算用C言語ファイル（cfg1_out.c）を生成
する．また，パス2に引き渡す情報を，パス1データファイル（cfg1_out.db）に
出力する．

パス1は，静的APIテーブル（xxx_api.def）と値取得シンボルテーブル
（xxx_sym.def）の2つの設定ファイルを用いる．静的APIテーブルには，静的
APIの一覧と，各静的APIのパラメータに関する情報を記述する．値取得シンボ
ルテーブルには，静的APIの整数定数式パラメータ以外で，パラメータ計算用C
言語ファイルに出力して値を求めたいシンボル（一般には式）を記述する．静
的APIテーブルの記述方法は３章で，値取得シンボルテーブルの記述方法は４章
で説明する．

パス1が生成したパラメータ計算用C言語ファイルは，Cコンパイラおよび関連ツー
ルを用いてコンパイルし，ロードモジュールを生成する．また，それをSレコー
ドフォーマットの形に変換したSレコードファイル（cfg1_out.srec）と，その
中の各シンボルとアドレスの対応表を含むシンボルファイル（cfg1_out.syms）
を生成する．

1.3 パス2の処理の概要

コンフィギュレータのパス2は，パス1で生成されたロードモジュールのSレコー
ドファイル（cfg1_out.srec）とシンボルファイル（cfg1_out.syms）から，静的
APIの整数定数式パラメータの値と，値取得シンボルテーブルに記述したシンボ
ル（一般には式）の値を取り出す．また，パス1データファイル（cfg1_out.db）
を読み，パス1からの情報を受け取る．

パス2では，これらの情報から，カーネル／システムサービスの構成・初期化ファ
イル（カーネルの場合は，kernel_cfg.c）と構成・初期化ヘッダファイル（カー
ネルの場合は，kernel_cfg.h）を生成する．また，パス3に引き渡す情報を，パ
ス2データファイル（cfg2_out.db）に出力する．カーネル／システムサービス／
ターゲットによっては，その他のファイルを生成する場合もある．具体的には，
保護機能対応カーネルでは，仮のメモリ構成・初期化ファイル（kernel_mem2.c）
と仮のリンカスクリプト（自動メモリ配置の場合のみ）を生成する．

パス2におけるファイル生成の方法は，パス2の設定ファイルである生成スクリ
プト（カーネルであれば，target_kernel.trb）に記述する．生成スクリプトの
記述方法は５章で説明する．

パス2で生成されたファイルを，他のソースファイルとあわせてコンパイルし，
アプリケーションのロードモジュールを生成する．また，それをSレコードフォー
マットの形に変換したSレコードファイル（ASP3カーネルの場合は，asp.srec）
と，その中の各シンボルとアドレスの対応表を含むシンボルファイル（ASP3カー
ネルの場合は，asp.syms）を生成する．

1.4 パス3の処理の概要

保護機能対応でないカーネルの場合や，保護機能対応カーネルで手動メモリ配
置の場合には，コンフィギュレータのパス3では，パス2で生成されたロードモ
ジュールのSレコードファイルとシンボルファイルから，静的APIのパラメータ
の値などを取り出し，妥当性のチェックを行う．

パス3における妥当性チェックの方法は，パス3の設定ファイルである生成スク
リプト（カーネルであれば，target_check.trb）に記述する．生成スクリプト
の記述方法は５章で説明する．

保護機能対応カーネルで自動メモリ配置の場合には，パス3は最適化のためのパ
スで，オプションである．

パス3を使用する場合，パス2で生成されたロードモジュールのSレコードファイ
ルとシンボルファイルから，静的APIのパラメータの値やメモリオブジェクトが
配置された番地やサイズなどを取り出し，仮のメモリ構成・初期化ファイル
（kernel_mem3.c）を生成する．ターゲットによっては，仮のリンカスクリプト
も生成する．また，パス4に引き渡す情報を，パス3データファイル
（cfg3_out.db）に出力する．

1.5 パス4の処理の概要

保護機能対応カーネルで自動メモリ配置の場合には，パス4において，パス3で
生成されたロードモジュールのSレコードファイルとシンボルファイル（パス3
を省く場合には，パス2の生成物を使う）から，メモリオブジェクトが配置され
た番地やサイズなどを取り出し，メモリ構成・初期化ファイル（kernel_mem.c）
を生成する．ターゲットによっては，リンカスクリプトも生成する．


２．コンフィギュレータの起動

コンフィギュレータは，システムコンフィギュレーションファイル名（パス1で
のみ有効）をパラメータに取り，以下のオプションを持つ．

	-k［--kernel］<カーネル名>
		カーネルの名称を指定する．

	-p［--pass］<パス番号>
		パス番号を指定する．1〜4のいずれか．

	-I［--include-directory］<インクルードディレクトリ名>
		INCLUDEディレクティブによりインクルードするコンフィギュレーショ
		ンファイルを探すディレクトリ名を指定する．生成スクリプト（trbファ
		イル）を探す場合にも用いる．

	-T［--trb-file］<生成スクリプト名>
		生成スクリプト（trbファイル）の名称を指定する．パス2以降で有効．
		パス2において処理フェーズの機能（6.2節参照）を用いる場合には，
		<生成スクリプト名>として，ファイル名に":"と処理フェーズ名を付加
		したもの（途中に空白を入れてはならない）を指定する．

	--api-table <静的APIテーブルファイル名>
		静的APIテーブルのファイル名を指定する．パス1でのみ有効．
		パス2において処理フェーズの機能（6.2節参照）を用いる場合には，
		<静的APIテーブルファイル名>として，ファイル名に":"と処理フェー
		ズ名を付加したもの（途中に空白を入れてはならない）を指定する．

	--symval-table <値取得シンボルテーブルファイル名>
		値取得シンボルテーブルのファイル名を指定する．パス1でのみ有効．

	-r［--rom-image］<ロードモジュールのSレコードファイル名>
		ロードモジュールをSレコードフォーマットの形に変換したファイル
		の名称を指定する．生成スクリプトのためのBCOPY関数，BZERO関数，
		PEEK関数は，このオプションで指定したSレコードファイルを操作対
		象とする．パス2以降で有効．

	-s [--rom-symbol] <ロードモジュールのシンボルファイル名>
		ロードモジュール中の各シンボルとアドレスの対応表を含むシンボル
		ファイルの名称を指定する．生成スクリプトのためのSYMBOL関数は，
		このオプションで指定したシンボルファイルを操作対象とする．パス
		2以降で有効．

	--id-output-file <ID番号出力ファイル名>
		オブジェクトのID番号の割付け結果を，指定した名前のファイルに書
		き出す．パス2でのみ有効．

	--id-input-file <ID番号入力ファイル名>
		オブジェクトのID番号の割付けを，指定した名前のファイルから取り
		込む．パス1とパス2で有効．パス1ではドメインのID番号，パス2では
		その他のオブジェクトのID番号を用いる．

	-M［--print-dependencies］<依存関係ファイル名>
		システムコンフィギュレーションファイルの依存関係を出力する．パ
		ス1でのみ有効．GCCの-Mオプションと異なり，-Mオプションを付けた
		場合も，コンフィギュレータは通常の処理を行う（依存関係を出力す
		るだけという使い方はできない）．依存関係ファイル名を指定しない
		場合，標準出力に出力する．

	-O [--omit-output-db]
		次のパスに情報を引き渡すためのデータファイルを作成しない．

	--enable-domain
		ドメインの囲み記述を使用できるようにする．

	--enable-class
		クラスの囲み記述を使用できるようにする．

	-v［--version］
		コンフィギュレータのバージョンを表示する．

	-h [--help]
		オプションのリストと説明を表示する．


３．静的APIテーブル

静的APIテーブルは，静的APIの一覧と，各静的APIのパラメータに関する情報を
記述するファイルで，コンフィギュレータのパス1で用いる．

3.1 静的APIテーブルの文法

静的APIテーブルの各行には，静的API名に続けて，パラメータリストを記述す
る．静的API名と各パラメータは，空白文字で区切る．

静的API名を，以下の形式で記述すると，派生静的APIは，元静的APIとパラメー
タリストが異なるだけの同じ静的APIであると扱われる．

	<派生静的API名>[<元静的API名>]

パラメータリストには，静的APIの各パラメータの文字列記述を列挙する．また，
"{"および"}"もパラメータと同様に扱い，パラメータリストに列挙する．"{"お
よび"}"は，静的APIの構文解析のために必要となる．

各パラメータの文字列記述は，パラメータの種別を表す文字に続けて，パラメー
タ名を記述する．必要な場合には，それに続けて，パラメータの属性を表す文
字列（または文字）を記述する．

パラメータの種別を表す文字は次の通り．

	#		オブジェクト識別名（定義）
	%		オブジェクト識別名（参照）
	.		符号無し整数定数式パラメータ
	+		符号付き整数定数式パラメータ
	^		ポインタ整数定数式パラメータ
	&		一般定数式パラメータ
	$		文字列パラメータ

パラメータの属性を表す文字列（または文字）は次の通り．

	*		キーパラメータ
	?		オプションパラメータ（パラメータが無くても良い）
	...		リストパラメータ（パラメータが複数（0個以上）あっても良い）

キーパラメータ（*属性）とは，この静的APIに関するパラメータ情報をコンフィ
ギュレーションデータ（$cfgData）に格納する際に，このパラメータをハッシュ
のキーとして使用することを示す．パラメータリスト中の0または1つのパラメー
タを，キーパラメータに指定する（複数のパラメータをキーパラメータに指定
した場合，その中で最後のパラメータがキーパラメータとして使われる）．詳
しくは，「5.2.2 コンフィギュレーションデータ」の節を参照すること．

パラメータリストに記述した"{"に"?"を付加すると（つまり，"{?"と記述する
と），"{?"と"}"で囲まれたパラメータ群がオプションである（無くても良い）
ことを示す．

3.2 静的APIテーブルの記述例

----------------------------------------
CRE_SEM #semid* { .sematr .isemcnt .maxsem }
CFG_INT .intno* { .intatr +intpri }
DEF_ICS { .istksz &istk }
ATT_MEM { .mematr &base .size } {? .acptn1 .acptn2 .acptn3 .acptn4 }
ATT_PMA[ATT_MEM] { .mematr &base .size .paddr } {? .acptn1 .acptn2 .acptn3 .acptn4 }
----------------------------------------

この記述で，ATT_PMAの情報は，コンフィギュレーションデータ（$cfgData）に
格納する際に，ATT_MEMの情報に統合される．


４．値取得シンボルテーブル

4.1 値取得シンボルテーブルの文法

値取得シンボルテーブルの各行の文法と，各パラメータの意味は次の通り．

----------------------------------------
<変数名>, <式>, <式の型>, <条件>, <条件が成立しない時の式>
----------------------------------------

<変数名>
	値を取得する変数の名前（グローバル変数であることを示す$は記述しない）
	を記述する．<変数名>の記述は省略することができない．

<式>
	値を表す式を記述する．<式>の記述を省略した場合には，<変数名>の記述
	が式として使われる．式の中に","を含む場合には，式全体を"で囲む．

<式の型>
	値を真偽値で取得したい場合は"bool"，符号付き整数値で取得したい場合
	には"signed"，符号無し整数値で取得したい場合には"unsigned"，番地を
	整数値で取得したい場合には"intptr"を記述する．記述を省略した場合に
	は，符号無し整数値と扱われる．

<条件>
	値を取得する条件を記述する．<条件>中では，あるシンボルがマクロ定義
	されているかどうかを判別するために，defined(<シンボル>)を使用するこ
	とができる．

<条件が成立しない時の式>
	<条件>が成立しなかった場合に，変数に設定する値を表す式を記述する．
	記述を省略すると，<条件>が成立しなかった場合に，変数には値が設定さ
	れない

Rubyでは，値が設定されていない変数を参照すると，警告となる（値としては
nilが返る）．警告を避けるためには，変数を参照する前に，defined?を使っ
て値が設定されているかをチェックする必要がある．変数に，条件が成立しな
い場合のデフォルト値がある場合には，このチェックにより生成スクリプトの
記述が煩雑になる場合がある．そのような場合には，<条件が成立しない時の
式>を記述して，変数に必ず値が設定されるようにすることを推奨する．

変数に値を取得することに加えて，NumStrクラス（5.1節参照）のオブジェク
トも取得したい場合には，値取得シンボルテーブルの行の記述を次のようにす
る．

----------------------------------------
<変数名>[<変数名2>], <式>, <式の型>, <条件>
----------------------------------------

<変数名2>
	<変数名>の後に，"["と"]"で囲んで<変数名2>（グローバル変数であるこ
	とを示す$は記述しない）を記述すると，<変数名2>で指定する変数に，取
	得した値と<式>から作られるNumStrクラスのオブジェクトを設定する．

なお，行の最後に「, <条件が成立しない時の式>」を記述してもエラーとはな
らず，値は正しく取り出すことができる．しかし，NumStrオブジェクトの文字
列には<式>がそのまま設定され，<条件が成立しない時の式>の記述は反映され
ない．

4.2 値取得シンボルテーブルの記述例

値取得シンボルテーブルの記述例と，各記述の意味は次の通り．

(記述例1) 単純な定数値の取得

----------------------------------------
TA_ACT
----------------------------------------

変数$TA_ACTに，TA_ACTの値を取得する．

(記述例2) NumStrクラスのオブジェクトの取得

----------------------------------------
TA_ACT[atrActivate]
----------------------------------------

変数$TA_ACTに，TA_ACTの値を取得する．また，変数$atrActivateに，値を
TA_ACTの値，文字列を"TA_ACT"とするNumStrクラスのオブジェクトを設定する．

(記述例3) 式の値の取得

----------------------------------------
sizeof_uint_t,sizeof(uint_t)
----------------------------------------

変数$sizeof_uint_tに，sizeof(uint_t)の値を取得する．

(記述例4) 符号の指定

----------------------------------------
TMAX_TPRI,,signed
----------------------------------------

変数$TMAX_TPRIに，TMAX_TPRIの値を符号付きで取得する．

(記述例5) 値を取得する条件の記述

----------------------------------------
DEFAULT_ISTK,,intptr,defined(DEFAULT_ISTK)
----------------------------------------

DEFAULT_ISTKがマクロ定義されていた場合，変数$DEFAULT_ISTKに
DEFAULT_ISTKの値を取得する．定義されていなかった場合，変数
$DEFAULT_ISTKには値が設定されない．

(記述例6) 条件が成立しない時の式の記述

----------------------------------------
TARGET_TSKATR,,,defined(TARGET_TSKATR),0
----------------------------------------

TARGET_TSKATRがマクロ定義されていた場合，変数$TARGET_TSKATRに
TARGET_TSKATRの値を取得する．定義されていなかった場合，変数
$TARGET_TSKATRは0とする．

(記述例7) マクロが定義されているか否かの取得

----------------------------------------
USE_TSKINICTXB,true,bool,defined(USE_TSKINICTXB),false
----------------------------------------

USE_TSKINICTXBがマクロ定義されていた場合，変数$USE_TSKINICTXBにtrueを
設定し，定義されていなかった場合，falseを設定する．言い換えると，
USE_TSKINICTXBがマクロ定義されているか否かを，変数$USE_TSKINICTXBに真
偽値で取得する．


５．生成スクリプト

この章では，生成スクリプトを記述するにあたって必要な事項を説明する．

5.1 NumStrクラス

コンフィギュレータは，静的APIの整数定数式パラメータを評価し，値を求める．
生成スクリプトで条件分岐やエラーチェックを行う際には，求めた値を参照し
たい．一方，パラメータをkernel_cfg.cなどのファイルに出力する際には，パ
ラメータを評価して求めた値ではなく，元になった文字列を出力した方が可読
性が高い．つまり，各パラメータに対して，値と文字列の両方を保持したい．

これを実現するために，値と文字列の組を管理するNumStrクラスを用意してい
る．コンフィギュレータは，静的APIの各パラメータに対して，与えた文字列と
それを評価して求めた値から，NumStrクラスのオブジェクトを生成する．

NumStrクラスは，プリントするなど文字列に変換する場合以外は，数値として
扱うことができる．具体的には，四則演算などの数値に対するメソッドについ
ては，NumStrオブジェクトの値に対して適用される．プリントするなど文字列
に変換する場合には，NumStrオブジェクトの文字列が用いられる．明示的に数
値として扱う場合（例えば，数値としてプリントする場合）にはvalメソッド，
文字列として扱う場合にはstrメソッドを用いる．

5.2 コンフィギュレータから生成スクリプトに渡される変数

この節では，コンフィギュレータ本体が定義し，生成スクリプトに渡される変
数について説明する．

5.2.1 値取得シンボル

値を求めたいシンボル（一般には式）として，値取得シンボルテーブルに記述
したシンボルに対応する変数．

5.2.2 コンフィギュレーションデータ（$cfgData）

システムコンフィギュレーションファイルに記述され，条件ディレクティブに
よって除外されなかった静的APIとそのパラメータは，$cfgDataに格納して生成
スクリプトに渡される．$cfgDataは，3重のハッシュ（ハッシュのハッシュのハッ
シュ）で，具体的な構造は以下の通りである．

$cfgDataは，静的API名をシンボル化したもの（例えば，静的API名がCRE_SEMで
あれば，:CRE_SEM）をキーとし，同一種類のすべての静的API（例えば，システ
ムコンフィギュレーションファイル中にCRE_SEMが5つあれば，そのすべて）の
情報を値とするハッシュである．

同一種類のすべての静的APIの情報は，個々の静的APIの識別番号をキーとし，
パラメータ情報を値とするハッシュである．ハッシュのキーとなる静的APIの識
別番号には，静的APIテーブル中でキーパラメータに指定したパラメータの値が
使われる．キーパラメータがオブジェクト識別名である場合，そのID番号がキー
となる．また，整数定数式パラメータである場合には，その値がキーとなる．
キーパラメータが指定されていない場合には，同一種類の静的APIの中での出現
順序（1から開始）がキーとなる．同じキーを持った静的APIが複数記述されて
いた場合には，コンフィギュレータ本体でエラーを検出する．このハッシュは，
システムコンフィギュレーションファイル中での静的APIの出現順に格納されて
いる．

パラメータ情報は，パラメータ名をシンボル化したもの（例えば，パラメータ
名がisemcntであれば，:isemcnt）をキーとし，パラメータ値を値とするハッシュ
である．パラメータ値は，オブジェクト識別名か整数定数式パラメータの場合
にはNumStrクラスのオブジェクト，一般定数式パラメータか文字列パラメータ
の場合は文字列（Stringクラスのオブジェクト）で表す．パラメータがリスト
パラメータである場合には，各パラメータをNumStrクラスのオブジェクトまた
は文字列で表したものの配列を値とする．

静的APIがドメインの囲みに含まれている場合には，:domainをキーとして，ド
メインIDの数値を値としたハッシュエントリを，パラメータ情報に追加する．
また，クラスの囲みに含まれている場合には，:classをキーとして，クラスID
をNumStrクラスのオブジェクトとしたハッシュエントリを，パラメータ情報に
追加する．

さらに，その静的APIに関するエラーメッセージ出力のために，パラメータ情報
には，:apinameをキーとして静的API名を，:_file_と:_line_をキーとして，そ
れぞれ，その静的APIが記述されているファイル名と行番号を格納している．

$cfgDataの例として，静的APIテーブルが「3.2 静的APIテーブルの記述例」の
節に挙げた例の通りで，システムコンフィギュレーションファイルの内容が，

----------------------------------------
CRE_SEM(SEM1, { TA_TPRI, 0, 1 });
CFG_INT(INTNO1, { TA_NULL, INTPRI1 });
DEF_ICS { I_STACK_SIZE, i_stack }
----------------------------------------

である時，$cfgDataは次の内容となる（TA_TPRIは1，INTNO1は10，TA_NULLは0，
INTPRI1は-2，I_STACK_SIZEは4196に定義されていることを仮定している）．

----------------------------------------
{:CRE_SEM=>
  {1=>
    {:semid=>NumStr(1,"SEM1"),
     :sematr=>NumStr(1,"TA_TPRI"),
     :isemcnt=>NumStr(0,"0"),
     :maxsem=>NumStr(1,"1"),
     :apiname=>"CRE_SEM",
     :_file_=>"sample.cfg",
     :_line_=>1}},
 :CFG_INT=>
  {10=>
    {:intno=>NumStr(10,"INTNO1"),
     :intatr=>NumStr(0,"TA_NULL"),
     :intpri=>NumStr(-2,"INTPRI1"),
     :apiname=>"CFG_INT",
     :_file_=>"sample.cfg",
     :_line_=>2}},
 :DEF_ICS=>
  {1=>
    {:istksz=>NumStr(4196,"I_STACK_SIZE"),
     :istk=>"i_stack",
     :apiname=>"DEF_ICS",
     :_file_=>"sample.cfg",
     :_line_=>3}}}
----------------------------------------

同一種類のすべての静的APIに対して処理を行いたい場合には，次のようにルー
プを作るとよい（CRE_SEMの例）．

----------------------------------------
$cfgData[:CRE_SEM].each do |key, params|
	<個々の静的APIに対する処理>
end
----------------------------------------

ここで，同一種類の静的APIは，システムコンフィギュレーションファイル中で
の出現順序で格納されているため，上のループ内の処理は，静的APIの出現順で
行われる．

一方，6.1節で示すようにID番号の割付けを手動で行った場合，静的APIの出現
順は，ID番号順に一致しているとは限らない．そのため，オブジェクトの初期
化ブロックを生成する場合など，ID番号順に処理をしたい場合には，ハッシュ
をソートする必要がある．具体的には，次のようにループを作るとよい
（CRE_SEMの例）．

----------------------------------------
$cfgData[:CRE_SEM].sort.each do |key, params|
	<個々の静的APIに対する処理>
end
----------------------------------------

このループの中では，静的APIのパラメータの値と文字列は，NumStrクラスのオ
ブジェクトとして，params[:maxcnt]の形で取り出すことができる（CRE_SEMの
maxcntパラメータの例）．

なお，いずれの例でも，ループの中でkeyを参照しないと，Rubyでは警告とな
る．keyを参照しない場合には，"key"に代えて"_"を記述すると良い．

5.2.3 ドメインデータ（$domData）

ドメインの囲み記述が使用できる場合には，システムコンフィギュレーション
ファイルに記述されたドメインに関する情報は，$domDataに格納して生成スク
リプトに渡される．$domDataは，2重のハッシュ（ハッシュのハッシュ）で，
具体的な構造は以下の通りである．

$domDataは，ドメインIDの値をキーとし，パラメータ情報を値とするハッシュ
である．パラメータ情報としては，生成スクリプトに渡される時点では，ドメ
イン名とドメインIDの値を保持するNumStrクラスのオブジェクトを持つ:domid
のみを格納している．

$domDataの例として，DOM1とDOM2の2つのドメインの囲みが記述され，それら
にそれぞれID番号1と2が割り当てられた時，$domDataは次の内容となる．

----------------------------------------
{-1=>{:domid=>NumStr(-1,"TDOM_KERNEL")},
 -2=>{:domid=>NumStr(-2,"TDOM_NONE")},
 1=>{:domid=>NumStr(1,"DOM1")},
 2=>{:domid=>NumStr(2,"DOM2")}}
----------------------------------------

5.2.4 その他の変数

(5-2-4-1) $asmLabel

コンパイラがC言語の識別名からアセンブラのラベルを作る際に，先頭に"_"が
付く場合には，$asmLabelは"_"に設定される．そうでない場合には，""に設定
される．

(5-2-4-2) $endianLittle

$endianLittleは，ターゲットプロセッサがリトルエンディアンの場合には
true，ビッグエンディアンの場合にはfalseに設定される．

5.3 生成スクリプトからコンフィギュレータに渡す変数

この節では，生成スクリプトが定義し，コンフィギュレータ本体に渡される変
数について説明する．

(5-3-1) タイムスタンプファイル名（$timeStampFileName）

生成スクリプトにおいて$timeStampFileNameにファイル名を設定すると，コン
フィギュレータ本体は，コンフィギュレータの正常終了時に，設定したファイ
ル名で内容の空のファイルが作られる．

5.4 パス間で引き渡す変数

この節では，異なるパスの生成スクリプト間でデータを受け渡したい時に用い
る変数について説明する．

(5-4-1) パス間で引き渡す変数のリスト（$globalVars）

$globalVarsは，パス2以降のパス間で受け渡しする変数のリストである．コン
フィギュレータがパス間で受け渡ししたい変数のリストに初期化されているた
め，生成スクリプトで受け渡ししたい変数がある場合には，$globalVarsにそ
の変数名（文字列）を追加する．

5.5 コンフィギュレータが生成スクリプトに提供する機能

5.5.1 エラー出力関数

この節では，生成スクリプト中でエラーを検出した場合に呼び出すべきエラー
出力関数について説明する．

(5-5-1-1) error_exit(message, location="")
(5-5-1-2) error(message, location="")
(5-5-1-3) warning(message, location="")

messageとlocationから作成したエラーメッセージを出力する．error_exitは，
メッセージの出力後にコンフィギュレータの処理を中断する．errorは，メッセー
ジの出力後も処理を継続し，ファイルの生成処理前にコンフィギュレータの処
理を中断する．warningは，そのまま処理を継続する．locationを省略した場合
には，エラー発生箇所は出力されない．

(5-5-1-4) warning_api(params, message)

paramsに静的APIのパラメータ情報を渡すと，静的APIが記述されているファイ
ル名と行番号と，messageに渡したメッセージを出力する．

(5-5-1-5) error_ercd(errorCode, params, message)

errorCodeにエラーコードの文字列，paramsに静的APIのパラメータ情報を渡す
と，静的APIが記述されているファイル名と行番号と，エラーコード，message
に渡したメッセージを出力する．errorCodeにnilを渡すと，エラーコードは出
力されない．

(5-5-1-6) error_sapi(errorCode, params, message,
										objid=nil, objlabel=false)

errorCodeにエラーコードの文字列，paramsに静的APIのパラメータ情報を渡す
と，静的APIが記述されているファイル名と行番号と，エラーコード，message
に渡したメッセージ，静的API名を出力する．errorCodeにnilを渡すと，エラー
コードは出力されない．

エラーを起こした静的APIの識別を容易にするために，オブジェクトIDなど，
オブジェクトを識別するパラメータを出力したい場合には，objidに出力した
いパラメータ名をシンボル化したものを渡す．objlabelにtrueを渡すと，パラ
メータ名とパラメータ（の値）を出力する．

(5-5-1-7) error_wrong(errorCode, params, symbol, wrong,
										objid=nil, objlabel=false)

パラメータに関するエラーメッセージを出力する．errorCodeにエラーコード
の文字列，paramsに静的APIのパラメータ情報，symbolにエラーを起こしたパ
ラメータ名をシンボル化したもの，wrongにエラーの理由を渡す．オブジェク
トを識別するパラメータの出力方法は，error_sapiと同様．

(5-5-1-8) error_illegal(errorCode, params, symbol,
										objid=nil, objlabel=false)

不正パラメータのエラーメッセージを出力する．errorCodeにエラーコードの
文字列，paramsに静的APIのパラメータ情報，symbolに不正なパラメータ名を
シンボル化したものを渡す．オブジェクトを識別するパラメータの出力方法は，
error_sapiと同様．

(5-5-1-9) error_api(params, message)
(5-5-1-10) error_wrong_id(errorCode, params, symbol, objid, wrong)
(5-5-1-11) error_wrong_sym(errorCode, params, symbol, symbol2, wrong)
(5-5-1-12) error_illegal_id(errorCode, params, symbol, objid)
(5-5-1-13) error_illegal_sym(errorCode, params, symbol, symbol2)

過去のバージョンとの互換性のための関数．

5.5.2 GenFileクラス

GenFileクラスは，生成スクリプトによってファイルを作成するために用いるク
ラスである．生成スクリプトにおいてGenFileクラスを用いて作成したファイル
は，すぐにはファイルに書き出されず，生成スクリプトによってエラーが報告
されなかった場合にのみ，コンフィギュレータ本体がファイルに書き出す．

GenFileクラスを用いてファイルを作成した場合，同一ファイル名のファイルが
すでに存在し，新しく作成したファイルがそれと同じ内容であれば，ファイル
を書き出さない（そのため，タイムスタンプが更新されない）．

GenFileクラスの主なメソッドは，以下の通りである．

(5-5-2-1) new(<ファイル名>)

新しいファイルを作成する．同一のファイル名のファイルが作成済みの場合に
は，作成済みのファイルの内容に，それ以降の内容を追加する．

(5-5-2-2) add(<文字列>)
(5-5-2-3) add2(<文字列>)
(5-5-2-4) append(<文字列>)

ファイルに文字列を書き出す（追記する）．文字列を書き出した後に，addは改
行1つを，add2は改行2つを書き出す．

(5-5-2-5) comment_header(<文字列>)

ファイルにコメントヘッダを書き出す（追記する）．

5.5.3 Stringクラスの拡張

Stringクラスに次の2つのメソッドを追加している．また，NumStrクラスもこれ
らのメソッドを持つ．

(5-5-3-1) quote

二重引用符で囲まれた文字列を返す．

(5-5-3-2) unquote

二重引用符で囲まれた文字列を展開した文字列を返す．文字列が二重引用符で
囲まれていない場合には，文字列をそのまま返す．

5.5.4 ロードモジュール操作ライブラリ

--rom-imageオプションと--rom-symbolオプションで指定したロードモジュール
を操作するためのライブラリ関数を用意している．

(5-5-4-1) SYMBOL(<シンボル>[, <実行継続フラグ>])

--rom-symbolオプションで指定したシンボルファイルから，指定したシンボル
のアドレスを返す．シンボルファイル中に指定したシンボルがない場合には，
その旨のエラーメッセージを出力して，コンフィギュレータの処理を中断する．
ただし，実行継続フラグにtrueを渡した場合には，エラーメッセージを出力せ
ず，nilを返す．

(5-5-4-2) BCOPY(<コピー元先頭アドレス>, <コピー先先頭アドレス>, <サイズ>)

--rom-imageオプションで指定したSレコードファイル中で，指定したパラメー
タに従ってデータをコピーする．データは，コンフィギュレータのメモリ中で
コピーするだけで，Sレコードファイルを書き換えるわけではない．

(5-5-4-3) BZERO(<先頭アドレス>, <サイズ>)

--rom-imageオプションで指定したSレコードファイル中で，指定したパラメー
タに従って0を書き込む．コンフィギュレータのメモリ中に書き込むだけで，S
レコードファイルを書き換えるわけではない．

(5-5-4-4) PEEK(<先頭アドレス>, <サイズ>[, <符号付きフラグ>])

--rom-imageオプションで指定したSレコードファイルから，指定した先頭アド
レスおよびサイズでデータを取り出し，値に変換して返す．<符号付きフラグ>
を省略するかfalseにした場合には符号なしの値に，<符号付きフラグ>をtrueに
した場合には符号付きの値に変換する．Sレコードファイルに指定した先頭アド
レスおよびサイズのデータが含まれていない場合にはnilを返す．

5.5.5 その他の機能

(5-5-5-1) IncludeTrb(<生成スクリプト名>)

指定した生成スクリプトを処理する．生成スクリプトは，コンフィギュレータ
に対する--include-directoryオプションで指定したディレクトリから探す．

(5-5-5-2) GenerateIncludes(<出力先のファイルハンドル>)

システムコンフィギュレーションファイルに記述されたインクルードディレク
ティブ（#include）を，指定したファイルに生成する．


６．その他

6.1 オブジェクトIDの指定

TOPPERS第3世代カーネルでは，オブジェクトのID番号を，コンフィギュレータ
が割り付ける方法が基本となっているが，ID番号の割付けを手動で設定したい
場合のために，コンフィギュレータは，ID番号の割付けをファイルから取り込
む機能を持っている．

具体的には，ID番号の割付けを記述したファイルを用意し，コンフィギュレー
タのパス2に対する--id-input-fileオプションにより指定することで，コンフィ
ギュレータはそれに従ってオブジェクトにID番号を割り付ける．ただし，
TOPPERS第3世代カーネルでは，ID番号が連続していなければならないという制
約があるため，この制約を満たせない割付けをしようとした場合には，コンフィ
ギュレータ本体がエラーを報告する．

また，コンフィギュレータのパス2に対する--id-output-fileオプションを用い
ることで，割付け結果をファイルに書き出すことができる．前回のコンフィギュ
レーション時にファイルに書き出した割付け結果を，次回のコンフィギュレー
ション時に読み込むことで，システムコンフィギュレーションファイルの修正
によりID番号の割付けを変化させないことができる．

6.2 システムサービスへの対応（パス2における処理フェーズ）

TCP/IPミドルウェアなどのシステムサービスのコンフィギュレーションに対応
するために，パス2における処理フェーズの機能を設けている．

システムサービスによっては，そのコンフィギュレーション内容に応じて，カー
ネルオブジェクトの登録が必要になる場合がある．例えば，TCP/IPの通信端点
を生成するごとに，セマフォを生成したい場合が考えられる．このような場合，
まずシステムサービスのコンフィギュレーション処理を行い，その中でカーネ
ルオブジェクトの登録情報を生成した後で，カーネルのコンフィギュレーショ
ン処理を行いたい．これを可能にするために設けた機能が，パス2における処理
フェーズの機能である．

処理フェーズの機能を用いる場合には，静的APIテーブルファイルと生成スクリ
プトをフェーズ毎に作成する．また，コンフィギュレータのオプションでこれ
らのファイルを指定する際に，ファイル名に":"と処理フェーズ名を付加したも
のを指定する．

例えば，TCP/IPミドルウェアのコンフィギュレーション（処理フェーズ名を
tcpipとする）とカーネルのコンフィギュレーション（処理フェーズ名を
kernelとする）をこの順序で行う場合，パス1に渡すオプションを，

	--api-table tinet_api.def:tcpip --api-table kernel_api.def:kernel

のようにし，パス2に渡すオプションを，

	-T tinet.trb:tcpip -T target_kernel.trb:kernel

のようにする．-Tオプションの指定順序は，処理フェーズの処理順序に一致さ
せる．

システムサービスの生成スクリプトからカーネルオブジェクトを登録する場合
には，静的APIの情報を格納したハッシュである$cfgFileInfoに，カーネルオブ
ジェクトを生成する静的APIの情報を追加する．例えば，セマフォを追加登録し
たい場合には，次のような処理を行う．

----------------------------------------
cfgInfo = { APINAME: "CRE_SEM" }
cfgInfo["semid"] = "SEM1_FOR_SYSSVC1"
cfgInfo["sematr"] = NumStr.new($TA_TPRI, "TA_TPRI")
cfgInfo["isemcnt"] = 1
cfgInfo["maxsem"] = 1
$cfgFileInfo.push(cfgInfo)
----------------------------------------

上の処理でcfgInfoに登録する情報は，オブジェクト識別名（上の例では
"semid"）については文字列，整数定数式パラメータについてはNumStrクラス
のオブジェクト（上の例では"sematr"）または整数値（上の例では"isemcnt"
と"maxsem"），一般定数式パラメータと文字列パラメータについては文字列と
する．整数定数式パラメータに整数値を指定した場合，その整数値を値とし，
それを10進数の文字列に変換したものを文字列に持つNumStrクラスのオブジェ
クトを代入したのと同等に扱う．

なお，この方法で静的APIの情報を登録できるのは，後続の処理フェーズで処理
される静的APIのみである．

また，追加登録した情報が正しくない場合のエラーメッセージは，エラーの発
生箇所が表示されないため，注意すること．


７．バージョン履歴

	2016年2月8日	Release	1.0.0		最初の一般公開
	2016年2月14日	Release	1.1.0		ドメインとクラスをサポート
	2016年3月14日	Release	1.2.0		様々な改良．HRP3カーネルに対応
	2016年5月15日	Release	1.2.1		ASP3 R3.1.0に同梱してリリース
	2017年7月21日	Release	1.2.2		ASP3 R3.2.0に同梱してリリース
	2018年4月19日	Release	1.3.0		ASP3 R3.3.0，HRP3 R3.0.0に同梱
										してリリース
	2018年5月2日	Release	1.3.1
	2019年3月20日	Release	1.4.0		ASP3 R3.4.0等に同梱してリリース
	2019年6月19日	Release	1.4.1		不具合対応
	2019年10月3日	Release	1.5.0		長期サポートバージョン
	20__年__月_日	Release	1.6.0

以上
