
		TOPPERS/ATK2-SC2
		ターゲット依存部 ポーティングガイド

このドキュメントは，TOPPERS/ATK2-SC2(以下，SC2)を，未サポートのターゲット
システムにポーティングするために必要となるターゲット依存部の実装方法を説明
するものである．
ATK2-SC1のポーティングガイドと内容が重複する部分については，記載を省略
する．

----------------------------------------------------------------------
TOPPERS ATK2
    Toyohashi Open Platform for Embedded Real-Time Systems
    Automotive Kernel Version 2

Copyright (C) 2011-2015 by Center for Embedded Computing Systems
            Graduate School of Information Science, Nagoya Univ., JAPAN
Copyright (C) 2011-2015 by FUJI SOFT INCORPORATED, JAPAN
Copyright (C) 2011-2013 by Spansion LLC, USA
Copyright (C) 2011-2015 by NEC Communication Systems, Ltd., JAPAN
Copyright (C) 2011-2015 by Panasonic Advanced Technology Development Co., Ltd., JAPAN
Copyright (C) 2011-2014 by Renesas Electronics Corporation, JAPAN
Copyright (C) 2011-2015 by Sunny Giken Inc., JAPAN
Copyright (C) 2011-2015 by TOSHIBA CORPORATION, JAPAN
Copyright (C) 2011-2015 by Witz Corporation
Copyright (C) 2014-2015 by AISIN COMCRUISE Co., Ltd., JAPAN
Copyright (C) 2014-2015 by eSOL Co.,Ltd., JAPAN
Copyright (C) 2014-2015 by SCSK Corporation, JAPAN

上記著作権者は，以下の (1)〜(3)の条件を満たす場合に限り，本ドキュメ
ント（本ドキュメントを改変したものを含む．以下同じ）を使用・複製・改
変・再配布（以下，利用と呼ぶ）することを無償で許諾する．
(1) 本ドキュメントを利用する場合には，上記の著作権表示，この利用条件
    および下記の無保証規定が，そのままの形でドキュメント中に含まれて
    いること．
(2) 本ドキュメントを改変する場合には，ドキュメントを改変した旨の記述
    を，改変後のドキュメント中に含めること．ただし，改変後のドキュメ
    ントが，TOPPERSプロジェクト指定の開発成果物である場合には，この限
    りではない．
(3) 本ドキュメントの利用により直接的または間接的に生じるいかなる損害
    からも，上記著作権者およびTOPPERSプロジェクトを免責すること．また，
    本ドキュメントのユーザまたはエンドユーザからのいかなる理由に基づ
    く請求からも，上記著作権者およびTOPPERSプロジェクトを免責すること．

本ドキュメントは，AUTOSAR（AUTomotive Open System ARchitecture）仕様
に基づいている．上記の許諾は，AUTOSARの知的財産権を許諾するものではな
い．AUTOSARは，AUTOSAR仕様に基づいたソフトウェアを商用目的で利用する
者に対して，AUTOSARパートナーになることを求めている．

本ドキュメントは，無保証で提供されているものである．上記著作権者およ
びTOPPERSプロジェクトは，本ドキュメントに関して，特定の使用目的に対す
る適合性も含めて，いかなる保証も行わない．また，本ドキュメントの利用
により直接的または間接的に生じたいかなる損害に関しても，その責任を負
わない．

$Id: porting.txt 906 2015-05-19 05:25:55Z t_ishikawa $
----------------------------------------------------------------------

○目次

０．ATK2-SC1とATK2-SC2の差分
１．タイミング保護用タイマドライバ
	1.1 タイミング保護用タイマに関する定数定義
	1.2 タイミング保護用タイマドライバ
２．プロセッサ依存モジュール
３．ディスパッチャ
４．割込みハンドラの出入口処理
５．SC2割込みハンドラの出入口処理
６．テンプレートファイルのターゲット依存部
７．リファレンス

０．ATK2-SC1とATK2-SC2の差分
SC2のポーティングでは，以下のターゲット依存部を新規で実装する必要がある
．
・タイミング保護用タイマドライバ

また，以下の既存ターゲット依存部の実装に変更を加える必要がある．
・プロセッサ依存モジュール
・ディスパッチャ
・タスク開始時処理
・割込みハンドラの出入口処理
・テンプレートファイルのターゲット依存部

１．タイミング保護用タイマドライバ
SC2のポーティングでは，タイミング保護用タイマドライバを新規で実装する必要
がある．タイミング保護用タイマとして以下のタイマがある．
・時間監視用タイマ
・到着間隔計測用タイマ

これらのタイマのドライバを呼び出すために必要な定義を含む
ヘッダファイルをtarget_timingprotection.hに用意する．
また，タイマドライバの実装ファイルを
target_timingprotection.cに用意する．

1.1 タイミング保護用タイマに関する定数定義

target_timingprotection.hに以下の定数定義を用意する．

(1-1-1) #define INTNO_TP_FAULT
時間監視用タイマの割込み番号

(1-1-2) #define INTNO_TP_TIMER
到着間隔計測用タイマの割込み番号

1.2 タイミング保護用タイマドライバ

SC2のポーティングでは，以下のタイマドライバを実装する必要がある．

(1-2-1) void target_tp_initialize(void);
タイミング保護用タイマの初期化処理を行う関数．以下の処理を行う．
・時間監視用タイマの初期設定
 ・割込み要求クリア
 ・ワンショットタイマ設定
 ・割り込み要求ライン属性の設定(INTNO_TP_FAULTの登録)
 ・タイマ停止
・到着間隔計測用タイマの初期設定および動作開始
 ・割込み要求クリア
 ・インターバルタイマ設定
 ・最大ティック数による周期設定
 ・割り込み要求ライン属性の設定(INTNO_TP_TIMERの登録)
 ・当該割込み要求ラインの割込みの許可
 ・タイマ動作開始

(1-2-2) void target_tp_terminate(void);
時間監視用タイマおよび到着間隔計測用タイマの停止
同タイマの割込み要求クリア

(1-2-3) void target_tp_start_timer(TickType tick)
・時間監視用タイマの動作開始
 ・割込み要求クリア
 ・当該割込み要求ラインの割込みの許可
 ・引数tickによるタイマカウント設定
 ・タイマ動作開始

(1-2-4) TickType target_tp_get_remaining_ticks(void)
時間監視用タイマの残り時間取得
時間監視用タイマのカウント値を返す．
割込み禁止状態でコールされることを考慮し，タイムアウト済みの場合，
1を返す．

(1-2-5) TickType target_tp_stop_timer(void)
時間監視用タイマの停止処理．
タイマ停止時の残り時間をtarget_tp_get_remaining_ticksで取得し返す．

(1-2-6) TickType target_tp_get_elapsed_ticks(void)
到着時間計測用タイマの経過時間読み出し処理．
到着時間計測用タイマの経過ティックを返す．
残り時間でなく，経過時間であることに注意．

(1-2-7) boolean target_tp_sense_interrupt(void)
到着時間計測用タイマで割込み要求が起きているかどうかを判定し，返す．

２．プロセッサ依存モジュール

SC2のポーティングでは，プロセッサ依存モジュールに対して，以下のモジュールは
不要であるため，削除する．
・void x_suspend_lock_os_int(void)
・void x_resume_unlock_os_int(void)

また，新たに以下のモジュールを追加する．
(2-1) boolean x_is_called_in_c1isr(void)
現在の割込みレベルからC1ISRかどうか判別し返す．

(2-2) x_set_ipm_c2isr_disable(void)
C2ISR禁止割込みレベルに設定する．

３．ディスパッチャ
SC2のポーティングでは，ディスパッチャに対して，以下の変更を加える必
要がある．

・exit_and_dispatch_nohookを追加する．
内部処理としてdispatcher_0に処理を切り替える．

・dispatcherのPostTaskHook呼び出し後にtp_stopを追加する．
内部処理として，tp_stop_task_monitorをコールする．

・dispatcherにおいて，CFG_USE_POSTTASKHOOK内の処理でポストタスクフックが
設定されていない場合，dispatcher_0に処理を切り替えている箇所をtp_stopに変更する．

・dispatcher_1でCFG_USE_PRETASKHOOKの処理前にtp_start_task_monitorをコールし，
タイミング保護タイマを設定する．

・タスクの強制終了があるため，start_rにマジックナンバー初期化処理を追加する．

以下に，上記変更を反映した擬似コードを示す．
行頭に+が記載された行がATK2-SC1から追加された差分である．
行頭に-が記載された行がATK2-SC1から削除された差分である．
----------------------------------------
  dispatcher:
	#ifdef CFG_USE_POSTTASKHOOK
-	ポストタスクフックが設定されていなければdispatcher_0に遷移
+	ポストタスクフックが設定されていなければtp_stopに遷移
  posttaskhook_call:
	ポストタスクフック呼び出し
	#endif /* CFG_USE_POSTTASKHOOK */
+ tp_stop:
+	tp_stop_task_monitor呼び出し
----------------------------------------

----------------------------------------
  dispatcher_1:
	…
	#ifdef LOG_DSP_LEAVE
	log_dsp_leave呼び出し
	#endif /* LOG_DSP_LEAVE */

+	タイミング保護タイマ呼び出し

  	#ifdef CFG_USE_PRETASKHOOK
	…
----------------------------------------

----------------------------------------
  start_r:
	runtsk取得
+	#ifdef CFG_USE_STACKMONITORING
+	マジックナンバー初期化
+	#endif /* CFG_USE_STACKMONITORING */
	TCB_p_tinib取得
----------------------------------------

４．割込みハンドラの出入口処理
・interruptの最後にtp_stop_task_monitorをコールし，タイミング保護タイマを停止する．
タイミング保護タイマの停止前後で，割込み要因と割込み・例外のネスト回数を保持している
レジスタの退避・復帰を行う．

・stack_monitoring_exitでp_runisrを設定している処理の後にtp_check_c2isr_arrival_time
をコールし，C2ISRの到着間隔を算出する．
C2ISRの到着間隔算出前後で，割込みオフセットの退避・復帰を行う．

・ret_int_taskでスタックポインタを戻した後，tp_start_task_monitorをコールし，
タイミング保護タイマを設定する．

５．SC2割込みハンドラの出入口処理
・SC2では割込みハンドラとしてint_tp_fault_handlerとint_tp_timer_handlerを追加する．
それぞれの処理は以下の通りである．
・int_tp_fault_handler
 ・多重割込み判定
 ・割込み・例外のネスト回数のインクリメント
 ・ネストしていない場合，スタックポインタの切り替え
  ・ネストしている場合，スタック切り替え無し
 ・OS割込み禁止状態に切り替え
 ・tp_fault_handlerの呼び出し

・int_tp_timer_handler
 ・レジスタ保存
 ・多重割込み判定
 ・割込み・例外のネスト回数のインクリメント
 ・ネストしていない場合，スタックポインタの切り替え
  ・ネストしている場合，スタック切り替え無し
 ・割込み禁止解除
 ・tp_timer_handlerの呼び出し
 ・全割込み禁止
 ・割込み・例外のネスト回数のデクリメント
 ・ネスト回数が0ならば，割込み元がタスクであるため，スタックポインタを戻す
 ・レジスタ復帰

６．テンプレートファイルのターゲット依存部
SC2のポーティングでは，テンプレートファイルのターゲット依存部への変更と
して以下のものが必要である，
・秒からクロック値への変換処理
・ベクタテーブルからSC2割込みハンドラの出入口処理への分岐処理

6.1 秒からクロック値への変換処理
テンプレートファイルのターゲット依存部に以下の関数を追加する．
(7-1-1)FUNCTION SEC_TO_CLOCK
引数で，秒数を表す浮動小数点型の文字列を受け取り，その秒数と一致するク
ロック値を返す関数．
タイマの最大カウント値を超えた場合は，エラーを出力する．

なお，SEC_TO_CLOCKの実装にあたり，テンプレートファイルのターゲット非依
存部で用意されているFLOAT_TO_FIXINT関数を利用しても良い．

FLOAT_TO_FIXINT関数は，浮動小数点型の値を文字列で受け取り，以下の値を
返す．
VALUE(文字列属性 = "x"，値属性 = 引数の値を10のx乗倍して得られた整数の
値)

例:"1.5"を引数で受け取った場合，VALUE("10",15)を返す．

以下に，SEC_TO_CLOCKの擬似コードを示す．
----------------------------------------
クロック値 SEC_TO_CLOCK("秒数") {
	fixint = FLOAT_TO_FIXINT("秒数");
	tmp = (タイマの動作周波数) * fixint;
	tick = tmp / (fixintの文字列属性);
	
	if (tickがカウント値の最大値より大きい) {
		エラー;
	}
	return tick;
}
----------------------------------------

6.2 C2ISRの優先度下限の変更
・SC2ではOS割込み禁止レベルをC2ISRの最高優先度レベルで設定するため，
C2ISRの優先度下限を1引き下げる．

6.3 ベクタテーブルからSC2割込みハンドラの出入口処理への分岐処理

ベクタテーブルを以下のように変更する．
----------------------------------------
・INTNO_TP_FAULTと等しい割込み番号の割込みが入った場合，int_tp_fault_handler
へ分岐するようにする．
・INTNO_TP_TIMERと等しい割込み番号の割込みが入った場合，int_tp_timer_handler
へ分岐するようにする．
----------------------------------------

また，上記の定数INTNO_TP_FAULTとINTNO_TP_TIMERをジェネ
レータで利用できるようにするため，Makefileのターゲット依存部に以下の内
容を追記する．
----------------------------------------
CFG_TABS := $(CFG_TABS) --cfg1-def-table $(TARGETDIR)/target_def.csv
cfg1_out.c: $(TARGETDIR)/target_def.csv
----------------------------------------

target_def.csvに下記のように記述する．
----------------------------------------
INTNO_TP_FAULT,INTNO_TP_FAULT
INTNO_TP_TIMER,INTNO_TP_TIMER
----------------------------------------

７．リファレンス

７.1 ターゲット依存部のファイル一覧

SC2のポーティングで追加される標準的なターゲット依存部の一般的なファイル
構成は次の通りである．

target_timingprotection.h		タイミング保護用タイマドライバのヘッダ
						ファイル．カーネルのみからインクルードされる．
target_timingprotection.c		タイミング保護用タイマドライバの実装
						ファイル．

以上
