TOPPERS/ATK2-SC3 ユーザーズマニュアル このドキュメントは，TOPPERS/ATK2-SC3を使用するために必要な事項を説明 するものである． ---------------------------------------------------------------------- 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: user.txt 187 2015-06-25 03:39:04Z t_ishikawa $ ---------------------------------------------------------------------- ○目次 ◎０．本マニュアルの位置づけ １．TOPPERS/ATK2-SC3の概要 ○1.1 TOPPERS/ATK2-SC3の位置付け 1.2 TOPPERS/ATK2-SC3の仕様 1.3 既知の問題 1.4 Cygwin環境における注意事項 ２．ターゲット依存部 2.1 ターゲット依存部の概要 ３．クイックスタートガイド 3.1 開発環境の準備 3.2 ジェネレータの構築 3.3 XMLスキーマの入手 3.4 サンプルプログラムの構築と実行 3.5 カーネルを関数単位でライブラリ化する方法 3.6 アプリケーションとカーネルを別々に構築する方法 3.7 カウンタの循環チェックの省略 3.8 Rte_Type.hの用意 ４．ディレクトリ構成・ファイル構成 4.1 配布パッケージのディレクトリ構成 ○4.2 ターゲット非依存部のファイル構成 ５．コンフィギュレーションスクリプトの使い方 ６．Makefileの修正方法 6.1 Makefileの変数定義 6.2 コンパイルオプション ○７．ジェネレータの使い方 7.1 コンフィギュレーションファイル(arxml) ８．システムモジュール 8.1 システムログ機能 8.1.1 低レベル出力 8.1.2 ログ情報の種別 8.1.3 ログ情報の重要度 8.1.4 ログ情報のデータ構造 8.1.5 システムログ機能のサービスコール 8.1.6 システムログ機能のためのライブラリ関数とマクロ ○8.1.7 システムログ機能のその他のサービス 8.2 シリアルインタフェースドライバ 8.2.1 シリアルインタフェースドライバのサービスコール 8.3 カーネル起動メッセージの出力 ９．サポートライブラリ 9.1 基本的なライブラリ関数 9.2 キュー操作ライブラリ関数 9.3 システムログ出力用ライブラリ関数 9.4 実行時間分布集計モジュール １０．使用上の注意とヒント 10.1 タイマドライバの組込み 10.2 ASSERTマクロの処理 10.3 システムログ機能の扱い 10.4 オブジェクトIDの管理 10.5 トレースログ記録のサンプルコードの使用方法 10.6 システムの起動時の初期化処理 10.7 想定するプログラミング言語 10.8 ユーザスタック領域定義 ○10.9 スタックサイズを見積もる注意点 10.10 スタートアップ/シャットダウンフック無効時の注意点 ◎10.11 メモリ保護機能 ◎10.12 システムサービスの呼出し方法 ◎10.13 スタックについて ◎10.13.1 タスク ◎10.13.2 C2ISR ◎10.13.3 信頼フック ◎10.13.4 非信頼フック ◎10.14 本カーネル実装の機能レベル ◎10.15 タスク間でのスタック領域の共有 10.16 システムタイマの使用方法 １１．参考情報 11.1 利用条件と利用報告 11.2 保証・適用性・サポート 11.3 バグレポート 11.4 ウェブサイト 11.5 TOPPERSユーザーズメーリングリスト 11.6 TOPPERSプロジェクトのメンバ向けのサービス 11.7 TOPPERSプロジェクトへの参加 ○がついている項目はATK2-SC1から変更があった箇所を，◎はATK2-SC3で新規 に追加された箇所を示す． ０．本マニュアルの位置づけ TOPPERS/ATK2-SC3は，TOPPERS/ATK2-SC1をベースとしているため，多くの項目 はTOPPERS/ATK2-SC1と同一である．本ドキュメントでは，TOPPERS/ATK2-SC1と 異なる点について説明する．そのため，まずTOPPERS/ATK2-SC1のユーザーズマ ニュアルを参照の後，本ドキュメントを参照すること． １．TOPPERS/ATK2-SC3の概要 1.1 TOPPERS/ATK2-SC3の位置付け TOPPERS/ATK2-SC3は，TOPPERS/ATK2-SC1に対して，AUTOSAR OS仕様のSC3をベ ースとしてメモリ保護などのアクセス保護機能を追加したリアルタイムカーネ ルである． 1.2 TOPPERS/ATK2-SC3の仕様 ATK2-SC1から変更なし． 1.3 既知の問題 ATK2-SC1から変更なし． 1.4 Cygwin環境における注意事項 ATK2-SC1から変更なし． ２．ターゲット依存部 2.1 ターゲット依存部の概要 ATK2-SC1から変更なし． ３．クイックスタートガイド 3.1 開発環境の準備 ATK2-SC1から変更なし． 3.2 ジェネレータの構築 ATK2-SC1から変更なし． 3.3 XMLスキーマの入手 ATK2-SC1から変更なし． 3.4 サンプルプログラムの構築と実行 ATK2-SC1から変更なし． 3.5 カーネルを関数単位でライブラリ化する方法 ATK2-SC1から変更なし． 3.6 アプリケーションとカーネルを別々に構築する方法 ATK2-SC1から変更なし． 3.7 カウンタの循環チェックの省略 ATK2-SC1から変更なし． 3.8 Rte_Type.hの用意 ATK2-SC1から変更なし． ４．ディレクトリ構成・ファイル構成 4.1 配布パッケージのディレクトリ構成 ATK2-SC1から変更なし． 4.2 ターゲット非依存部のファイル構成 include/ svc_funccall.h システムサービス直接呼び出し（ソフトウェア割込みによる呼出しと区別）ための定義 kernel/ kernel_common.tf コンフィギュレーション各パス共通定義の非依存部テンプレートファイル kernel_mem.tf コンフィギュレーションパス2用の非依存部テンプレートファイル kernel_mem2.tf コンフィギュレーションパス3，パス4用の非依存部テンプレートファイル memory.h メモリオブジェクト管理機能関連の定義 memory.c メモリオブジェクト管理機能の内部関数 osap.h OSアプリケーション機能関連の定義 osap.c OSアプリケーション機能の内部関数 svc.def サービスコール定義ファイル（サービスコールインタフェース生成ツール用） svc_table.c システムサービスのソフトウェア割込みによる呼出すための起動番地テーブル ioc.tf IOC向けジェネレータのパス2のテンプレートファイル ioc_impl.h IOC実装用標準ヘッダファイル ioc_manage.c IOC機能 sysmod/ chkobj.c 非信頼OSアプリケーションのオブジェクトアクセス可否をチェックするためのシステムサービス定義 library/ ATK2-SC1から変更なし． arch/gcc/ ldscript.tf リンカスクリプトの生成のテンプレートファイル tool_svc.h システムサービスソフトウェア割込みによる呼出し（直接呼び出しと区別）ための定義 arch/logtrace/ ATK2-SC1から変更なし． utils/ gensvc_atk サービスコールインタフェース生成ツール sample/ sample1.h サンプルプログラム(1)に関する定義（信頼OSアプリケーション） sample1.c サンプルプログラム(1)（信頼OSアプリケーション） sample2.h サンプルプログラム(2)に関する定義（非信頼OSアプリケーション） sample2.c サンプルプログラム(2)（非信頼OSアプリケーション） sample1.arxml サンプルプログラム(1)(2)のコンフィギュレーションファイル（信頼/非信頼OSアプリケーション） doc/ ATK2-SC1から変更なし． ５．コンフィギュレーションスクリプトの使い方 ATK2-SC1から変更なし． ６．Makefileの修正方法 6.1 Makefileの変数定義 ATK2-SC1から変更なし． 6.2 コンパイルオプション ATK2-SC1から変更なし． ７．ジェネレータの使い方 ジェネレータ（cfg）は，4つのパスで構成される． -p［--pass］<パス番号> パス番号を指定する．1〜4のいずれか． -r［--rom-image］<ロードモジュール名> ロードモジュールをSレコードフォーマットの形に変換したファイルの 名称を指定する．パス3，パス4でのみ有効． 7.1 コンフィギュレーションファイル(arxml) ATK2-SC1から変更なし． ８．システムモジュール 8.1 システムログ機能 ATK2-SC1から変更なし． 8.1.1 低レベル出力 ATK2-SC1から変更なし． 8.1.2 ログ情報の種別 ATK2-SC1から変更なし． 8.1.3 ログ情報の重要度 ATK2-SC1から変更なし． 8.1.4 ログ情報のデータ構造 ATK2-SC1から変更なし． 8.1.5 システムログ機能のサービスコール ATK2-SC1から変更なし． 8.1.6 システムログ機能のためのライブラリ関数とマクロ ATK2-SC1から変更なし． 8.1.7 システムログ機能のその他のサービス (3)システムログ機能使用する/しない場合の設定 システムログ機能は，ターゲット追加システムサービスとして位置付け，使用 する場合，Makefileに以下のコンパイルオプションで記述する． CDEFS := $(CDEFS) -DUSE_KERNEL_LIBRARY_SYSLOG コンパイルオプションである-DUSE_KERNEL_LIBRARY_SYSLOGは，カーネルレベ ルでのシステムログ機能を使用する/しない設定である． -DUSE_KERNEL_LIBRARY_SYSLOGが指定された場合，カーネルにシステムログ機 能が追加され，各アプリに使用できる．-DUSE_KERNEL_LIBRARY_SYSLOGが指定さ れない場合，カーネルにシステムログ機能が無くなり，各アプリに使用できな い． また，各アプリ(ソースファイル)にシステムログ機能を使用する/しない設定を 個別にしたい場合は，抑止したいソースファイルにおいて，"t_syslog.h"をイン クルードする前に，TOPPERS_OMIT_SYSLOGマクロを定義する． 8.2 シリアルインタフェースドライバ 8.2.1 シリアルインタフェースドライバのサービスコール ATK2-SC1から変更なし． 8.3 カーネル起動メッセージの出力 ATK2-SC1から変更なし． ９．サポートライブラリ 9.1 基本的なライブラリ関数 ATK2-SC1から変更なし． 9.2 キュー操作ライブラリ関数 ATK2-SC1から変更なし． 9.3 システムログ出力用ライブラリ関数 ATK2-SC1から変更なし． 9.4 実行時間分布集計モジュール ATK2-SC1から変更なし． １０．使用上の注意とヒント 10.1 タイマドライバの組込み ATK2-SC1から変更なし． 10.2 ASSERTマクロの処理 ATK2-SC1から変更なし． 10.3 システムログ機能の扱い ATK2-SC1から変更なし． 10.4 オブジェクトIDの管理 ATK2-SC1から変更なし． 10.5 トレースログ記録のサンプルコードの使用方法 ATK2-SC1から変更なし． 10.6 システムの起動時の初期化処理 ATK2-SC1から変更なし． 10.7 想定するプログラミング言語 ATK2-SC1から変更なし． 10.8 ユーザスタック領域定義 ATK2-SC1から変更なし． 10.9 スタックサイズを見積もる注意点 本カーネルは，C2ISR/信頼フック用スタックは，合わせて1つのスタックで確 保され，非信頼フック用スタックは，システムに1つ確保される． 10.10 スタートアップ/シャットダウンフック無効時の注意点 ATK2-SC1から変更なし． 10.11 メモリ保護機能 システムには，信頼OSアプリケーションと非信頼OSアプリケーションが存在す る．信頼OSアプリケーションに属する処理単位は，プロセッサの特権モードで 実行され，全てのOSオブジェクトに対して，全ての種別のアクセスを行うこと が許可される．非信頼OSアプリケーションに属する処理単位は，プロセッサの 非特権モードで実行され，どのOSオブジェクトに対してどの種別のアクセスを 行えるかを制限することができる．カーネル自体は，信頼OSアプリケーション と同様な振る舞いをする． 信頼OSアプリケーションは，ハードウェアへのアクセスやシステムサービスの 使用に制限がなく，非信頼OSアプリケーションは，ハードウェアへのアクセス やシステムサービスの使用が制限されるため，信頼OSアプリケーションに属す る処理単位は，それなりに信頼されるように作成する必要がある． 10.12 システムサービスの呼出し方法 本カーネルでは，システムサービスは，ソフトウェア割込みによって呼出すの が基本である．システムサービス呼出しを通常の方法で記述した場合，ソフト ウェア割込みによって呼出すことが生成される． 一般に，ソフトウェア割込みによるシステムサービス呼出しはオーバヘッドが 大きい．そのため，信頼OSアプリケーションに属する処理単位からは，関数呼 出しによってシステムサービスを呼出すことで，オーバヘッドを削減すること ができる．そこで，信頼OSアプリケーションに属する処理単位から関数呼出し によってシステムサービスを呼出せるように，機能が用意されている． 信頼OSアプリケーションに属する処理単位が実行する関数のみを含んだソース ファイルでは，カーネルヘッダファイル（Os.h）をインクルードする前に，マ クロを定義することで，システムサービス呼出しを通常の方法で記述した場合 に，関数呼出しによって呼出すコードが生成される(「次世代車載システム向 けRTOS外部仕様書」を参照)． gensvc_atkツールの使い方の補足： gensvc_atkツールは，サービスコールインタフェース生成プログラムであり， サービスコール定義ファイル（svc.def）を読み込んで，ソフトウェア割込み によるサービスコール呼出すための一部ソースファイルを生成できる．以下の ファイルをカレントディレクトリに生成され，それぞれのディレクトリへの移 動は手動で行うこと． 実行例： gensvc_atk ../kernel/svc.def （svc.devの記述方法は，svc.dev参照） 生成ファイル： svc_table.c → kernel/ に置く kernel_fncode.h → include/ に置く svc_call.h → include/ に置く tool_svc.h→ arch/gcc/ に置く 10.13 スタックについて 本カーネルのスタックには，信頼タスク（信頼OSアプリケーションに属するタ スク）用スタック，非信頼タスク（非信頼OSアプリケーションに属するタスク ）用スタック，非信頼タスク用システムスタック，C2ISR用スタック，信頼フ ック（信頼OSアプリケーションに属するフック）用スタックと非信頼フック （非信頼OSアプリケーションに属するフック）用スタックがある． 10.13.1 タスク 本カーネルでは，非信頼タスクにおいて，非信頼タスク用スタックと非信頼タ スク用システムスタックの2本を確保される．基本的に自タスクの非信頼タス ク用スタックを使用するが，システムサービス及び信頼関数を呼出す際に非信 頼タスク用システムスタックを使用する． 一方，信頼タスクにおいて，タスク用スタックとシステム用スタックを合せて 1本で確保される． 10.13.2 C2ISR 本カーネルは，機能レベル2しか対応していないため，信頼C2ISR（信頼OSアプ リケーションに属するC2ISR）しかない．C2ISR実行時に使用するスタックは， C2ISR用スタックを使用する． 本カーネルでは，C2ISR用スタックとカーネル自身用スタックと後述信頼フッ クに対して，メモリ保護を行わないため，合せて1本のスタックを確保される． 10.13.3 信頼フック 本カーネルでは，信頼フック（システムフックを含む）実行時に，信頼フック 用スタックを使用する．前節の理由で，C2ISR用スタックとカーネル自身用ス タックと合せて1本のスタックを確保される． 10.13.4 非信頼フック 本カーネルでは，非信頼フック実行時に，非信頼フック用スタックを使用す る． 上記の説明のように，スタックを見積もる時に，スタック使用対象を確認し て，見積もればよい．また，各スタックのデフォルト値は，ターゲットによっ て，定義されているため，ターゲット依存設計書を参照する． 10.14 本カーネル実装の機能レベル 本カーネルは，メモリ保護の機能レベル2及び保護違反時処理の機能レベル2を 実装している．機能レベルについては，「次世代車載システム向けRTOS外部仕 様書」2.3.2機能レベルを参照する． 10.15 タスク間でのスタック領域の共有 本カーネルでは，同優先度基本タスクのスタック自動的に共有をサポートして いる．更に同じOSアプリケーションに所属するユーザスタックも1つのメモリ オブジェクトとして配置する．なので，タスクのユーザスタック領域が，同じ OSアプリケーションに属する他のタスクのユーザスタック領域と重なっていて も，エラーとならない． この機能を実装した制限として，CheckTaskMemoryAccessが正しくエラーフッ クを上がらない場合がある．具体的には，自タスクのスタック領域の境界をま たぐメモリ領域に対してCheckTaskMemoryAccessを発行した場合に，引数のエ ラーコードにE_OS_ILLEGAL_ADDRESSを上がるべきところを，エラーフックが上 がらない場合がある． 10.16 システムタイマの使用方法 ATK2-SC1から変更なし． １１．参考情報 11.1 利用条件と利用報告 ATK2-SC1から変更なし． 11.2 保証・適用性・サポート ATK2-SC1から変更なし． 11.3 バグレポート ATK2-SC1から変更なし． 11.4 ウェブサイト ATK2-SC1から変更なし． 11.5 TOPPERSユーザーズメーリングリスト ATK2-SC1から変更なし． 11.6 TOPPERSプロジェクトのメンバ向けのサービス ATK2-SC1から変更なし． 11.7 TOPPERSプロジェクトへの参加 ATK2-SC1から変更なし． 以上