{{{
#!html
<div style="border:3px solid black;text-align:center;font-size:30pt;width:500px;">
ABREXの使い方
</div>
}}}
[[PageOutline(1-2, Table of Contents, pullout)]]
[[BR]]

= はじめに =
* AUTOSARでは，コンポーネント間のデータのやりとりにXMLを用いる(拡張子はarxml)
* BSWのコンフィギュレーション情報もXMLで定義する
  * 基本的に人が読み書きすることは想定されておらず，ツールで生成するのが一般的である
* BSW単体でコンフィギュレーションを行いたい場合や，BSWを開発する際にはパラメータを直接指定して，arxmlファイルを作成したいニーズがある
* arxmlファイルを直接編集するのは効率的ではないので，簡略化したテキストデータからarxmlファイルを生成できるツールがあれば有用である
* TOPPERSでは，AUTOSARのRTE，BSWの開発に際し，[https://ja.wikipedia.org/wiki/YAML YAML]フォーマットで記述したデータを，arxmlファイルに変換するツールであるABREX(AUTOSAR BSW and RTE XML Generator)を使用している

----

= 入手方法 =
* ABREXは，[https://www.toppers.jp/atk2-download.html TOPPERS/ATK2]に同梱されている
  * どのパッケージにも同梱されているので，ABREXを使用したいだけの場合は，どれか1つのATK2をダウンロードすればよい
  * ABREXもバージョンアップしているので，最新版を使用するのが望ましい
* ATK2は，tar.gz形式で公開されているので，解凍ソフト等を使用して，解凍する
* 解答したフォルダの{{{utils\abrex\abrex.rb}}}がABREXの実行スクリプトである

----

= 使い方 =
== 実行環境 ==
* ABREXはRubyスクリプトで開発されているので，Rubyの実行環境が必要となる
* [https://www.cygwin.com/ Cygwin]に含まれる以下のバージョンのRubyで動作確認されている
  * {{{ruby 1.9.3p327 (2012-11-10 revision 37606) [i386-cygwin]}}}
* Windows環境であれば，[https://rubyinstaller.org/ Ruby Installer for Windows]を使うと簡単にRubyの実行環境が構築できる

== YAMLファイルの書き方 ==
* 最上位のレイヤがパッケージ名，その次がECUモジュール名となる
* ECUモジュール名の下に該当モジュールに含まれるパラメータ名をキーとして，パラメータコンテナと値をハッシュ形式で記述する
  * 複数の同一パラメータを定義する場合は，キーをショートネームとして，パラメータの1つとして{{{DefinitionRef}}}でパラメータ名を記述する
* サブコンテナは，ハッシュをネストすることで表現する
* コンテナへの参照は，YAMLファイルに定義したパッケージ名に従ってパスを記述する
* YAMLファイルに記載しないarxmlファイル内の情報は固定値でABREXが生成する
=== OSの例 ===
＜変換前(YAMLファイル)＞
{{{
Ecuc:
  Os:
    OsOS:
      OsStackMonitoring: true
      OsStatus: EXTENDED
      OsUseGetServiceId: true
      OsUseParameterAccess: true
      OsScalabilityClass: SC1
      OsHooks:
        OsErrorHook: false
        OsPostTaskHook: false
        OsPreTaskHook: false
        OsProtectionHook: false
        OsShutdownHook: false
        OsStartupHook: false
    TASK1:
      DefinitionRef: OsTask
      OsTaskActivation: 1
      OsTaskPriority: 10
      OsTaskSchedule: FULL
      OsTaskEventRef: /Os/Os/EVENT1
    EVENT1:
      DefinitionRef: OsEvent
}}}
＜変換後(arxmlファイル)＞
{{{
<?xml version="1.0" encoding="EUC-JP"?>
<AUTOSAR xmlns="http://autosar.org/schema/r4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://autosar.org/schema/r4.0 AUTOSAR_4-0-3_STRICT.xsd">
	<AR-PACKAGES>
		<AR-PACKAGE>
			<SHORT-NAME>Ecuc</SHORT-NAME>
			<ELEMENTS>
				<ECUC-MODULE-CONFIGURATION-VALUES>
					<SHORT-NAME>Os</SHORT-NAME>
					<DEFINITION-REF DEST="ECUC-MODULE-DEF">/AUTOSAR/EcucDefs/Os</DEFINITION-REF>
					<ECUC-DEF-EDITION>4.2.0</ECUC-DEF-EDITION>
					<IMPLEMENTATION-CONFIG-VARIANT>VARIANT-PRE-COMPILE</IMPLEMENTATION-CONFIG-VARIANT>
					<CONTAINERS>
						<ECUC-CONTAINER-VALUE>
							<SHORT-NAME>OsOS</SHORT-NAME>
							<DEFINITION-REF DEST="ECUC-PARAM-CONF-CONTAINER-DEF">/AUTOSAR/EcucDefs/Os/OsOS</DEFINITION-REF>
							<PARAMETER-VALUES>
								<ECUC-NUMERICAL-PARAM-VALUE>
									<DEFINITION-REF DEST="ECUC-BOOLEAN-PARAM-DEF">/AUTOSAR/EcucDefs/Os/OsOS/OsStackMonitoring</DEFINITION-REF>
									<VALUE>true</VALUE>
								</ECUC-NUMERICAL-PARAM-VALUE>
								<ECUC-TEXTUAL-PARAM-VALUE>
									<DEFINITION-REF DEST="ECUC-ENUMERATION-PARAM-DEF">/AUTOSAR/EcucDefs/Os/OsOS/OsStatus</DEFINITION-REF>
									<VALUE>EXTENDED</VALUE>
								</ECUC-TEXTUAL-PARAM-VALUE>
								<ECUC-NUMERICAL-PARAM-VALUE>
									<DEFINITION-REF DEST="ECUC-BOOLEAN-PARAM-DEF">/AUTOSAR/EcucDefs/Os/OsOS/OsUseGetServiceId</DEFINITION-REF>
									<VALUE>true</VALUE>
								</ECUC-NUMERICAL-PARAM-VALUE>
								<ECUC-NUMERICAL-PARAM-VALUE>
									<DEFINITION-REF DEST="ECUC-BOOLEAN-PARAM-DEF">/AUTOSAR/EcucDefs/Os/OsOS/OsUseParameterAccess</DEFINITION-REF>
									<VALUE>true</VALUE>
								</ECUC-NUMERICAL-PARAM-VALUE>
								<ECUC-TEXTUAL-PARAM-VALUE>
									<DEFINITION-REF DEST="ECUC-ENUMERATION-PARAM-DEF">/AUTOSAR/EcucDefs/Os/OsOS/OsScalabilityClass</DEFINITION-REF>
									<VALUE>SC1</VALUE>
								</ECUC-TEXTUAL-PARAM-VALUE>
							</PARAMETER-VALUES>
							<SUB-CONTAINERS>
								<ECUC-CONTAINER-VALUE>
									<SHORT-NAME>OsHooks</SHORT-NAME>
									<DEFINITION-REF DEST="ECUC-PARAM-CONF-CONTAINER-DEF">/AUTOSAR/EcucDefs/Os/OsOS/OsHooks</DEFINITION-REF>
									<PARAMETER-VALUES>
										<ECUC-NUMERICAL-PARAM-VALUE>
											<DEFINITION-REF DEST="ECUC-BOOLEAN-PARAM-DEF">/AUTOSAR/EcucDefs/Os/OsOS/OsHooks/OsErrorHook</DEFINITION-REF>
											<VALUE>false</VALUE>
										</ECUC-NUMERICAL-PARAM-VALUE>
										<ECUC-NUMERICAL-PARAM-VALUE>
											<DEFINITION-REF DEST="ECUC-BOOLEAN-PARAM-DEF">/AUTOSAR/EcucDefs/Os/OsOS/OsHooks/OsPostTaskHook</DEFINITION-REF>
											<VALUE>false</VALUE>
										</ECUC-NUMERICAL-PARAM-VALUE>
										<ECUC-NUMERICAL-PARAM-VALUE>
											<DEFINITION-REF DEST="ECUC-BOOLEAN-PARAM-DEF">/AUTOSAR/EcucDefs/Os/OsOS/OsHooks/OsPreTaskHook</DEFINITION-REF>
											<VALUE>false</VALUE>
										</ECUC-NUMERICAL-PARAM-VALUE>
										<ECUC-NUMERICAL-PARAM-VALUE>
											<DEFINITION-REF DEST="ECUC-BOOLEAN-PARAM-DEF">/AUTOSAR/EcucDefs/Os/OsOS/OsHooks/OsProtectionHook</DEFINITION-REF>
											<VALUE>false</VALUE>
										</ECUC-NUMERICAL-PARAM-VALUE>
										<ECUC-NUMERICAL-PARAM-VALUE>
											<DEFINITION-REF DEST="ECUC-BOOLEAN-PARAM-DEF">/AUTOSAR/EcucDefs/Os/OsOS/OsHooks/OsShutdownHook</DEFINITION-REF>
											<VALUE>false</VALUE>
										</ECUC-NUMERICAL-PARAM-VALUE>
										<ECUC-NUMERICAL-PARAM-VALUE>
											<DEFINITION-REF DEST="ECUC-BOOLEAN-PARAM-DEF">/AUTOSAR/EcucDefs/Os/OsOS/OsHooks/OsStartupHook</DEFINITION-REF>
											<VALUE>false</VALUE>
										</ECUC-NUMERICAL-PARAM-VALUE>
									</PARAMETER-VALUES>
								</ECUC-CONTAINER-VALUE>
							</SUB-CONTAINERS>
						</ECUC-CONTAINER-VALUE>
						<ECUC-CONTAINER-VALUE>
							<SHORT-NAME>TASK1</SHORT-NAME>
							<DEFINITION-REF DEST="ECUC-PARAM-CONF-CONTAINER-DEF">/AUTOSAR/EcucDefs/Os/OsTask</DEFINITION-REF>
							<PARAMETER-VALUES>
								<ECUC-NUMERICAL-PARAM-VALUE>
									<DEFINITION-REF DEST="ECUC-INTEGER-PARAM-DEF">/AUTOSAR/EcucDefs/Os/OsTask/OsTaskActivation</DEFINITION-REF>
									<VALUE>1</VALUE>
								</ECUC-NUMERICAL-PARAM-VALUE>
								<ECUC-NUMERICAL-PARAM-VALUE>
									<DEFINITION-REF DEST="ECUC-INTEGER-PARAM-DEF">/AUTOSAR/EcucDefs/Os/OsTask/OsTaskPriority</DEFINITION-REF>
									<VALUE>10</VALUE>
								</ECUC-NUMERICAL-PARAM-VALUE>
								<ECUC-TEXTUAL-PARAM-VALUE>
									<DEFINITION-REF DEST="ECUC-ENUMERATION-PARAM-DEF">/AUTOSAR/EcucDefs/Os/OsTask/OsTaskSchedule</DEFINITION-REF>
									<VALUE>FULL</VALUE>
								</ECUC-TEXTUAL-PARAM-VALUE>
							</PARAMETER-VALUES>
							<REFERENCE-VALUES>
								<ECUC-REFERENCE-VALUE>
									<DEFINITION-REF DEST="ECUC-REFERENCE-DEF">/AUTOSAR/EcucDefs/Os/OsTask/OsTaskEventRef</DEFINITION-REF>
									<VALUE-REF DEST="ECUC-CONTAINER-VALUE">/Os/Os/EVENT1</VALUE-REF>
								</ECUC-REFERENCE-VALUE>
							</REFERENCE-VALUES>
						</ECUC-CONTAINER-VALUE>
						<ECUC-CONTAINER-VALUE>
							<SHORT-NAME>EVENT1</SHORT-NAME>
							<DEFINITION-REF DEST="ECUC-PARAM-CONF-CONTAINER-DEF">/AUTOSAR/EcucDefs/Os/OsEvent</DEFINITION-REF>
						</ECUC-CONTAINER-VALUE>
					</CONTAINERS>
				</ECUC-MODULE-CONFIGURATION-VALUES>
			</ELEMENTS>
		</AR-PACKAGE>
	</AR-PACKAGES>
</AUTOSAR>
}}}

== 実行コマンド ==
* 作成したYAMLファイルを引数として，abrex.rbを実行する
{{{
$ ruby abrex.rb ./sample.yaml
}}}
* 入力したYAMLファイルの情報に対応するarxmlファイルが，入力ファイル名の拡張子をarxmlに変更したファイルに出力される
  * 上記実行例の場合，sample.arxmlが出力される

----

= コンテナ情報に関して =
* YAMLファイルに記載したパラメータが整数型かどうか等は，ABREXに同梱されているparam_info.yamlに定義されている
* ABREXに同梱されているparam_info.yamlでは，TOPPERSプロジェクトから公開されているモジュールで使用するパラメータのみ定義されている
* param_info.yamlに別のBSWのパラメータを定義したい場合，AUTOSARから公開されているECUコンフィギュレーションパラメータコンテナ情報ファイルを入力として，ABREXで作成することができる
== param_info.yaml作成方法 ==
* ECUコンフィギュレーションパラメータコンテナ情報ファイル(AUTOSAR_MOD_ECUConfigurationParameters.arxml)を入手する
  * [https://www.autosar.org/fileadmin/standards/classic/4-0/AUTOSAR_MOD_ECUConfigurationParameters.zip AUTOSAR_MOD_ECUConfigurationParameters.zip]に入っている
  * ABREX開発時に使用したのは，{{{Release 4.0}}}であり，これ以外のバージョンでは動作未確認である
* パラメータ情報を作成したいBSWモジュール名をABREXソースコードに設定する
  * {{{MakeParamInfo}}}メソッド内の配列{{{aTargetModule}}}に定義する
{{{
# 読み込み対象モジュール
aTargetModule = ["Rte", "Os", "Com", "PduR", "CanIf", "Can", "EcuC", "EcuM", "WdgM", "WdgIf", "Wdg", "Dem"]
}}}
* ABREXに-pオプションを付けて実行する
{{{
$ ruby abrex.rb -p AUTOSAR_MOD_ECUConfigurationParameters.arxml
}}}
  * 各パラメータコンテナのデータ型，外部参照型の参照先情報などが，param_info.yamlに出力される
== 注意事項 ==
* ABREXによるYAML→arxml変換実行時，param_info.yamlに含まれないキー名が登場した場合，エラー終了する
* サブコンテナ名はparam_info.yamlに含まれず，YAMLファイルに記述した名称が正しいものとして，サブコンテナを生成する
* 設定値の妥当性等のチェックは一切行わない

----

= 応用編 =
== 複数YAMLファイルの入力 ==
* 引数のYAMLファイルは複数指定することができ，すべてのYAMLファイルの情報をマージしたXMLファイルを生成する
* 同じパスのコンテナが異なるファイルに存在する場合，1つのコンテナにマージする
* 例えば，以下のa.yamlとb.yamlを入力した場合，MAIN_HW_COUNTERには両方のファイルに指定されたすべてのパラメータが設定されたarxmlファイルとなる
  * 同じパスのパラメータが複数のファイルに含まれる場合は，多重度が*と判断して，複数のコンテナを生成する(パラメータ毎の多重度情報は保持しない)
＜a.yaml＞
{{{
Ecuc:
  Os:
    MAIN_HW_COUNTER:
      DefinitionRef: OsCounter
      OsCounterMaxAllowedValue: 0x7FFFFFFF
      OsCounterTicksPerBase: 10
      OsCounterMinCycle: 4000
      OsCounterType: HARDWARE
      OsSecondsPerTick: 1.666666e-08
      OsCounterIsrRef: /Os/Os/ISR1
}}}
＜b.yaml＞
{{{
Ecuc:
  Os:
    MAIN_HW_COUNTER:
      OsCounterAccessingApplication: OSAP1
}}}

== arxmlファイルからYAMLファイルを作成する(逆変換) ==
* ABREXでは，作成済みのarxmlファイルから，YAMLファイルを作成することが出来る
* -iオプションに，arxmlファイルを引数として与え，実行する
{{{
$ ruby abrex.rb -i sample.arxml
}}}
* 入力したXMLファイルの情報に対応するYAMLファイルが，入力ファイル名の拡張子をyamlに変更したファイルに出力される
  * 上記例の場合，sample.yaml
* 逆変換において，複数のarxmlファイルを指定した場合は，入力されたarxmlファイル毎に，YAMLファイルを個別に出力する

== 出力するarxmlファイルでの整数，小数の表記 ==
* ABREXでは，Ruby標準のYAMLライブラリを使用して，YAMLファイルを読み込むが，整数，少数はそれぞれInteger，Floatクラスとして解釈される
* この結果，以下のように，16進数表記で記述した整数は10進数表記で出力され，0に近い小数は指数表記で出力される
＜入力するYAMLファイル＞
{{{
Ecuc:
  Os:
    MAIN_HW_COUNTER:
      DefinitionRef: OsCounter
      OsCounterMaxAllowedValue: 0x7FFFFFFF
      OsSecondsPerTick: 0.00000001666666
}}}
＜出力されるarxmlファイル＞
{{{
<ECUC-NUMERICAL-PARAM-VALUE>
	<DEFINITION-REF DEST="ECUC-INTEGER-PARAM-DEF">/AUTOSAR/EcucDefs/Os/OsCounter/OsCounterMaxAllowedValue</DEFINITION-REF>
	<VALUE>2147483647</VALUE>
</ECUC-NUMERICAL-PARAM-VALUE>
<ECUC-NUMERICAL-PARAM-VALUE>
	<DEFINITION-REF DEST="ECUC-FLOAT-PARAM-DEF">/AUTOSAR/EcucDefs/Os/OsCounter/OsSecondsPerTick</DEFINITION-REF>
	<VALUE>1.666666e-08</VALUE>
</ECUC-NUMERICAL-PARAM-VALUE>
}}}
* この現象を回避し，YAMLにファイルに書いた通りに出力したい場合は，以下のように文字列として記述する
＜入力するYAMLファイル＞
{{{
Ecuc:
  Os:
    MAIN_HW_COUNTER:
      DefinitionRef: OsCounter
      OsCounterMaxAllowedValue: "0x7FFFFFFF"
      OsSecondsPerTick: "0.00000001666666"
}}}
＜出力されるarxmlファイル＞
{{{
<ECUC-NUMERICAL-PARAM-VALUE>
	<DEFINITION-REF DEST="ECUC-INTEGER-PARAM-DEF">/AUTOSAR/EcucDefs/Os/OsCounter/OsCounterMaxAllowedValue</DEFINITION-REF>
	<VALUE>0x7FFFFFFF</VALUE>
</ECUC-NUMERICAL-PARAM-VALUE>
<ECUC-NUMERICAL-PARAM-VALUE>
	<DEFINITION-REF DEST="ECUC-FLOAT-PARAM-DEF">/AUTOSAR/EcucDefs/Os/OsCounter/OsSecondsPerTick</DEFINITION-REF>
	<VALUE>0.00000001666666</VALUE>
</ECUC-NUMERICAL-PARAM-VALUE>
}}}