
	    ＝ TOPPERS/JSPカーネル ユーザズマニュアル ＝
    		       （H8S ターゲット依存部）

	    （Release 1.4.1 対応，最終更新: 18-OCT-2004）

------------------------------------------------------------------------
 TOPPERS/JSP Kernel
     Toyohashi Open Platform for Embedded Real-Time Systems/
     Just Standard Profile Kernel

 Copyright (C) 2000-2004 by Embedded and Real-Time Systems Laboratory
                             Toyohashi Univ. of Technology, JAPAN
 Copyright (C) 2001-2004 by Dep. of Computer Science and Engineering
                    Tomakomai National College of Technology, JAPAN
 Copyright (C) 2001-2004 by Industrial Technology Institute,
                             Miyagi Prefectural Government, JAPAN

 上記著作権者は，Free Software Foundation によって公表されている
 GNU General Public License の Version 2 に記述されている条件か，以
 下の(1)〜(4)の条件を満たす場合に限り，本ソフトウェア（本ソフトウェ
 アを改変したものを含む．以下同じ）を使用・複製・改変・再配布（以下，
 利用と呼ぶ）することを無償で許諾する．
 (1) 本ソフトウェアをソースコードの形で利用する場合には，上記の著作
     権表示，この利用条件および下記の無保証規定が，そのままの形でソー
     スコード中に含まれていること．
 (2) 本ソフトウェアを再利用可能なバイナリコード（リロケータブルオブ
     ジェクトファイルやライブラリなど）の形で利用する場合には，利用
     に伴うドキュメント（利用者マニュアルなど）に，上記の著作権表示，
     この利用条件および下記の無保証規定を掲載すること．
 (3) 本ソフトウェアを再利用不可能なバイナリコードの形または機器に組
     み込んだ形で利用する場合には，次のいずれかの条件を満たすこと．
   (a) 利用に伴うドキュメント（利用者マニュアルなど）に，上記の著作
       権表示，この利用条件および下記の無保証規定を掲載すること．
   (b) 利用の形態を，別に定める方法によって，上記著作権者に報告する
       こと．
 (4) 本ソフトウェアの利用により直接的または間接的に生じるいかなる損
     害からも，上記著作権者を免責すること．

 本ソフトウェアは，無保証で提供されているものである．上記著作権者は，
 本ソフトウェアに関して，その適用可能性も含めて，いかなる保証も行わ
 ない．また，本ソフトウェアの利用により直接的または間接的に生じたい
 かなる損害に関しても，その責任を負わない．
------------------------------------------------------------------------

１．H8Sターゲット依存部の概要

1.1 ターゲットシステムと開発環境

H8Sファミリーのプロセッサをサポートしている。H8Sファミリーは、内蔵インタ
フェースなどの違いなどにより、様々なプロセッサがある。これら全てに、対応
可能なように設計を行った。

今回の実装においてサポートとしたターゲットボードは、以下である。

      ・株式会社ミスポ製 H8S/2350 評価ボード (H8S/2350搭載)

開発環境には、GCC などの GNU開発環境を用い、オブジェクトファイルフォーマッ
トは coff を標準とする。

1.2 サポートする機能の概要

H8Sターゲット依存部による機能としては、
      ・割込みマスクの変更・参照(chg_ipm、get_ipm)
      ・性能評価用システム時刻参照機能(vxget_tim)
をサポートしている。また、
      ・割込みの禁止と許可(dis_int、ena_int)
はサポートしていない。(2.2.4及び3.2参照。)

1.3 他のターゲットへのポーティング

H8Sファミリーであれば、ポーティングは容易に出来る。しかしながら、開発機材の
関係上、H8S/2350以外でのテストを行っていない。
（なお、この開発機材の関係から、下記においてはH8S/2350での状況を想定して
  いる。しかし、開発自体は、H8Sファミリー全体に有効な内容である。）

1.4 GDB スタブ

現在の TOPPERS/JSP カーネル H8S 版はROM化をサポートしている。

また、GDBスタブへ対応している。興味のある方は、別途お問い合わせください。
なお、デバッグ環境としてはICEを推奨する。

1.5 シリアルポート(SCI)

H8Sファミリーの全てのプロセッサが、２チャンネル以上のシリアルポートを内蔵
している。そこで、それらのうち、カーネルのログ出力用に１つ使用する。
シリアルポートの設定は
      ・8ビット
      ・パリティなし
      ・ストップビット：1ビット
      ・ボーレート：38400 bps
である。

なお、ボーレートについては、BAUD_RATEマクロにて定義しているので必要に応じて
変更することができる。
(sys_config.h)

(H8S/2350は２チャンネルのシリアルポートを内蔵している。これは、sys_config.h
 に定義しているNUM_PORTによりサポートするポート数が決まる。現在の実装では、
 ２チャンネルをサポートしている。
 また、JSPカーネルのログ出力用には、SCI0を使用している。)

２．H8Sターゲット依存部の機能

2.1 データ型

int型および unsigned int型のサイズは 32ビットである。

2.2 割込み管理機能と割込みハンドラ

カーネル管理外の割込みは NMI のみである。CPUロック状態や初期化ルーチン内では
NMI 以外の割込みは全て禁止される。具体的には、割込みマスクが７に設定される。

割込みハンドラの登録に関しては、コンフィグファイルに対する静的APIの記述と、
ベクタテーブルへの記述との、二つの記述を行わなければならない。
このベクタテーブルへの記述については、後述する。
（静的APIによる記述により、割込みハンドラ（割込み出入口処理を含む）が生成され、
  例外処理ベクタテーブルに登録することで、この割込みハンドラが呼び出される。）

2.2.1 割込み制御モード

H8Sファミリーは、モード０とモード２の２つの割込み制御モードの選択が可能で
ある。今回の実装では、モード２をサポートしている。

2.2.2 ベクタテーブルの記述方法

割込みハンドラを呼び出すためには、例外処理ベクタテーブルに登録する必要がある。
このとき、H8Sファミリーは、ROM領域に例外処理ベクタテーブルを配置してため、
ベクタテーブルは実行中は固定となる。

そのため、コンパイル前に、exception_vector.S に記載されているベクタテーブルに、
割込みハンドラの入口処理のラベル名を直接記述する必要がある。

このときに記述する、例外処理の入口処理のラベル名は，以下のように設定する。

      ・例外処理のＣ言語ルーチン名    ： *******
      ・例外処理の入り口処理のラベル名：_*******_entry
        (ここで、ラベル名に"_"が付いているのは、Ｃ言語ルーチンfoo()に対して
         アセンブルすると、_fooというラベルを対応付けられるためである。)

      例）SCI(シリアルコミュニケーションインターフェース）からの割込み
        例外処理のＣ言語ルーチン名    ： serial_in_handler
        例外処理の入り口処理のラベル名：_serial_in_handler_entry

なお、このルールに従ったラベルを生成する、_INT_ENTRYマクロを定義しているので、
利用してください。

      例）SCI(シリアルコミュニケーションインターフェース）からの割込み
        例外処理のＣ言語ルーチン名    ： serial_in_handler
        例外処理の入り口処理のラベル名：
          _INT_ENTRY(serial_in_handler) -> _serial_in_handler_entry を生成

なお、このマクロを、exception_vector.S で利用しているので、参考にしてください。

2.2.3 割込みマスク／割込み優先度制御

割込みマスク／割込み優先度制御のための、定義・APIは以下の通りである。

(1)IPM型
割込みマスクの値を示すデータ型である。割込みマスクは、EXR（エクステンドレジ
スタ）の割込みマスクビット(I2-0)の値である。そのため、EXR分の１バイトあれば
よいので、UB型で定義している。

(2)icu_set_ilv			割込みレベルの設定

【C言語API】
        icu_set_ilv( IPR, MASK, LEVEL )

【パラメータ】
        VP	IPR		設定するインタラプトプライオリティレジスタの
				アドレス ( IPRA - IPRK マクロで設定 )
        BOOL	MASK		設定するインタラプトプライオリティレジスタの
				設定範囲（上位部分または下位部分）の選択
				( IPR_UPR、または、IPR_LOW マクロで設定 )
        INT	LEVEL		設定する割込みレベル ( 0 - 7 )

【リターンパラメータ】
	なし

【機能】
インタラプトプライオリティレジスタの各例外要因別に、割込みレベル設定を行う。

【注意】
現在は、マクロを用いた実装を行っているため、エラー処理は特に行っていない。
(cpu_config.h)

なお、今回の実装において、割込みレベルは、
      （低）シリアル０ ＝ シリアル１ -> タイマ０（高）
と定義している。
(sys_config.h)

2.2.4 割込みマスク変更・参照のためのサービスコールについて

割込みマスク変更・参照のためのサービスコールは、タスクコンテキストかつ CPU
ロック解除状態の場合にのみ呼び出すことができる。chg_ipm により IPM を、
何らかの割込みが禁止されている状態（０以外の値の場合）にした場合でも、
ディスパッチは禁止されず、chg_ipm により変更した IPM の値は、ディスパッチ
後のタスクに引き継がれる。

chg_ipm をサポートするために、割込みハンドラの出入口処理などにオーバヘッド
を生じている。そこで、SUPPORT_CHG_IPM というマクロにより、これらのサービス
コールをサポートするかどうかを切り替えられるようにしている。
(SUPPORT_CHG_IPM は、cpu_config.h の中で #define されている。)

H8Sターゲット依存の割込みマスクの変更・参照のためのサービスコールの仕様は
次の通り。

(1) chg_ipm			割込みマスクの変更

【C言語API】
	ER ercd = chg_ipm(IPM ipm);

【パラメータ】
	IPM	ipm		設定すべき IPM の値

【リターンパラメータ】
	ER	ercd		エラーコード

【エラーコード】
	E_CTX		コンテキストエラー
	E_PAR		パラメータエラー(ipm が不正)

【機能】

割込みマスクをを ipm で指定した値に設定する。指定した値が、0〜6 に入って
いない場合、E_PARエラーを返す。割込みマスクを0以外（1〜MAX_IPM-1）に設定
した場合でも、ディスパッチは禁止されない。また、設定した割込みマスクの値は、
ディスパッチ禁止後も引き継がれる。

このサービスコールは、タスクコンテキストで CPUロック解除状態の時のみ呼び
出すことができる。非タスクコンテキストや CPUロック状態で呼び出した場合には、
E_CTXエラーとなる。

なお、このサービスコールを用いて、IPMをMAX_IPM（全ての割込みを禁止）に設定
することはできない。IPMをMAX_IPMにしたい場合には、loc_cpuを使用すべきである。

(2) get_ipm			割込みマスクの参照

【C言語API】
	ER ercd = get_ipm(IPM *p_ipm);

【パラメータ】
	なし

【リターンパラメータ】
	ER	ercd		エラーコード
	IPM	ipm		現在の IPM の値

【エラーコード】
	E_CTX		コンテキストエラー

【機能】

現在の割込みマスクの値を読み出し、ipm に返す。

このサービスコールは、タスクコンテキストで CPUロック解除状態の時のみ呼
び出すことができる。非タスクコンテキストや CPUロック状態で呼び出した場
合には、E_CTXエラーとなる。

2.3 CPU例外管理機能とCPU例外ハンドラ

DEF_EXC で指定する CPU例外ハンドラ番号（excno）は、H8Sファミリーにおける
ベクタテーブルのベクタ番号を表し、そのデータ型（EXCNO）は unsigned int 型
に定義されている。
DEF_EXC で、ベクタ番号として有効でない値や、CPU例外に対応しない番号を指定
した場合の動作は保証されない。

(1)変数p_excinf
CPU例外ハンドラに渡されるp_excinfは、CPU例外発生時のコンテキストを保存
したスタックへのポインタが渡される。スタックの構造を以下に示す。

      ----------------------
     |    er6 (32ビット)    |  <-- p_excinf
      ----------------------
     |    er5 (32ビット)    |
      ----------------------
     |    er4 (32ビット)    |
      ----------------------
     |    er3 (32ビット)    |
      ----------------------
     |    er2 (32ビット)    |
      ----------------------
     |    er1 (32ビット)    |
      ----------------------
     |    er0 (32ビット)    |
      ----------------------
     |    EXR ( 8ビット)    |
      ----------------------
     |    予約( 8ビット)    |
      ----------------------
     |    CCR ( 8ビット)    |
      ----------------------
     |    PC  (24ビット)    |
      ----------------------

     EXR : エクステンドレジスタ
     CCR : コンディションコードレジスタ
     PC  : プログラムカウンタ

また、CPU例外発生時のPCの値はインクリメントされる。そのため、CPU例外ハンドラ
から復帰を行うと、CPU例外が発生した命令の次の命令から実行を再開する。

2.4 割込み発生時のスタック消費量について

各タスクスタックは、タスク自身が使用する分に加えて、最大 ９８ バイト余分に
用意する必要がある。

JSPカーネルは、タスクコンテキスト用のタスクスタックと、非タスクコンテキスト
用のスタック（以下、割込みスタック）とを用意している。そのため、非タスクコン
テキストは割込みスタックで実行される。

H8Sファミリーにおいて、割込みモード２では、割込み受付時に割込み禁止になる
機構がハードウェアで用意されていない。そのために、割込みの入口処理でソフト
ウェアによって割込み禁止にする必要がある。割込み入口処理では、割込み禁止に
移行するための作業用に、割込み許可の状態のまま、タスクスタックに er0、er1
を退避させる。
（下記レジスタは割込み受付時にハードウェアが自動的に退避を行う。
    PC  : プログラムカウンタ（３バイト）
    CCR : コンディションコードレジスタ（１バイト）
    EXR : エクステンドレジスタ（１バイト））

さて、多重割込みが、割込みスタックに切り替える前に発生した場合には、同様の
スタックフレームがタスクスタック上に生成される。
そのため、最悪のタイミングで割込みが発生すると、H8S は割込みレベルが７レベル
あるので、タスクスタックにおいて、９８バイト消費されることになる。
（１スタックフレームの大きさ〔アドバンスモードの場合〕：
    er1（４バイト）＋ er0（４バイト）＋ EXR（１バイト）＋リザーブ（１バイト）
    ＋ CCR（１バイト）＋ PC（３バイト）= １４ バイト
  最大タスクスタック消費量：
    １４バイト×７セット = ９８バイト）

2.5 スタートアップモジュール

H8Sファミリーでは、ベクタテーブルに、パワーオンリセット、マニュアルリセット
並びに NMI(Non Maskable Interrupt)用のベクタアドレスを備えている。これらの
アドレスからのジャンプ先がスタートアップモジュールとなっている。

スタートアップモジュール(start.S)では、次の初期化処理を行う。

(A) スタックポインタの設定
スタックポインタ sp を、STACKTOP の値に設定する。この値は、sys_config.h に
定義されている。

(B) hardware_init_hookの呼び出し

hardware_init_hook が 0 でなければ、hardware_init_hook を呼び出す。
hardware_init_hook はカーネルを起動する前に、ダーゲット依存のハードウェア的
な初期化を行うために用意されている。
本実装では、hardware_init_hook 内では、
      ・SYSCR の設定（割込み制御モード、内蔵RAMの設定）
      ・I/O ポートの初期化
      ・バスコントローラの設定（ABWCR、ASTCR、WCRL、BCRHの設定）
などの処理を行う。記述場所は、sys_support.S を標準とする。

hardware_init_hook がどこでも定義されていない場合には、このシンボルを0に
定義する(リンカスクリプト内に記述あり)。

なお、hardware_init_hook を新たに記述する場合には、呼び出し元へのリターンは
rts 命令でなく、jmp 命令で start_1 に戻ること。

(C) bssセクション、dataセクションの初期化

bss セクションの全領域をゼロクリアする。data セクションを初期化する。ROM 化
対応のために、ROM から RAM へと、コピーを行う。

(D) software_init_hookの呼び出し

software_init_hook が 0 でなければ、software_init_hook を呼び出す。
software_init_hook は、カーネルが起動される前に行う必要があるソフトウェア
環境(具体的には、ライブラリ)依存の初期化を行うために用意している。

software_init_hook がどこでも定義されていない場合、リンカでこのシンボルを
 0 に定義する(リンカスクリプト内に記述あり)。

(E) カーネルの起動

kernel_start へ分岐し、カーネルを起動する。kernel_start からリターンして
くることは想定していない。

2.6 MAC レジスタ (H8S/2600コア内蔵プロセッサのみ)

※この部分のサポート協力者を求めております。

H8Sファミリーには、CPUコアに H8S/2600 と H8S/2000 の２種類が存在する。この
うち、H8S/2600 は、積和レジスタとして MAC レジスタをサポートしている。

そこで、使用するプロセッサが、H8S/2600 を持つ場合は、
      ・cpu_defs.h において H8S_2600 マクロを定義する。
       (このマクロによって、cpu_support.S において、MAC レジスタのサポートが
        行われる。)
      ・$(CPU)/Makefile.config 内を適切にコメントインする。
       (これにより、H8S/2600 用のコンパイルオプションが付加される。)
を行うことにより、MAC レジスタに対応することができる。

サポート状況は、以下の通りである。

・Ｃ言語で書かれたタスク内で、この MAC レジスタを使用する場合に、自らディス
  パッチャを呼び出してディスパッチする場合は、関数呼び出しになる。
  そのため、呼び出し前後にまたがったタスク間で、MAC レジスタを使うことは
  ないため保存していない。
  （そのため、タスク内でアセンブラのコードを使用する場合もこのルールに従う
    必要がある。）
・割込みからのディスパッチ（受動的ディスパッチ）では保存している。

※割込み発生時の MAC レジスタの保存については、実行環境が無いため、保存の
  有無を確認できていない。

３．システム依存部の機能

3.1 システムクロックドライバ

システムクロックドライバが isig_tim を呼び出す周期は、sys_defs.h 中の
TIC_NUME と TIC_DENO で定義されている(デフォルトでは 1ミリ秒周期)。この定
義を変更することで、isig_tim を呼び出す周期を変更することができる。但し、
タイマの精度が1μ秒であるために、1μ秒単位で端数になる値を設定した場合には、
isig_timの呼出し周期に誤差が生じることになる。

デフォルトでは、下記のタイマを利用している。
(a) H8S/2350
  H8S内蔵タイマ(TPU)のチャネル0

3.2 性能評価用システム時刻参照機能

H8S依存部では、性能評価用システム参照機能(vxget_tim)をサポートしている。
精度は1μ秒で、SYSUTIM型はUW型(32ビット符号なし整数型)である。

性能評価用システム時刻の精度は供給クロック単位であるが、タイマの現在値を
読み出すために一時的にタイマを停止させる必要があるため、vxget_tim を呼ぶ
度にシステムクロックが少しづつ遅れることになる。そこで、SUPPORT_VXGET_TIM
というマクロにより、これらのサービスコールをサポートするかどうかを切り替
えられるようにしている。
(SUPPORT_VXGET_TIM は、sys_config.h の中で #define されている。)

3.3 シリアルインターフェースドライバ

今回の実装では、ターゲットプロセッサの関係から、２チャンネルまでの対応を
行っている。しかし、他のH8Sファミリーには、２チャンネル以上のシリアルインタ
フェースを内蔵しているものもある。そのための、変更は容易に可能である。
詳しくは、ソースコードを参照のこと。

なお、シリアルインターフェースドライバは、カーネルのログ出力用に、H8S内蔵
SCIチャネル0を使用している。

3.4 メモリマップ

メモリマップは以下のように設定している。
・ROM 化時
      0x000000 - 0x01ffff : コード領域(128kB)
      0x200000 -          : データ領域(128kB)
                 0x21ffff : 非タスクコンテキスト用のスタック領域

・GDB スタブ利用時
      0x200000 - 0x20ffff : コード領域(64kB)
      0x210000 -          : データ領域(64kB-8kB(for GDB_STUB))
                 0x21efff : 非タスクコンテキスト用のスタック領域

内蔵 RAM は、現在使用していないが、使用する場合には、hardware_init_hook の
中で内蔵 RAM を有効にする必要がある。(2.3 (2)を参照。)

４．開発環境の構築

開発環境の構築方法については、GNU開発環境構築マニュアルを参照すること。
なお、ターゲット環境 <TARGET> の値については、以下を参考のこと。
開発には Windows2000SP4 上で Cygwin を用いた。

動作確認は、下記のツールにて確認している。このツールをデフォルトとする。

・GNUから配布されているオリジナルのGCCなどをソースから構築したツール
  動作確認を行ったときのバージョンは以下の通りである。
    BINUTILS : 2.14
    GCC-CORE : 3.3.2
    NEWLIB   : 1.11.0
（この場合のターゲット環境 <TARGET> には、h8300-hms- を用いる。）

また、Windows上でCygwinを用いて開発する場合は、binutils の configure のオプ
ションに --disable-nls も指定すること。

５．制限事項

・割込み制御モード０はサポートしていない。

・ノーマルモードでの実行は、テストを行っていない。

・MACレジスタのサポートは、テストを行っていない。

・スタートアップルーチン、リンクスクリプトは、C++ に対応していない。

・SYSUTIM 型を UW 型(32ビット符号なし整数型)として定義しているために、性能
  評価用システム参照機能(vxget_tim)により測定できる範囲が、多機種より狭い。

・他の gcc のバージョン（特に、gcc 3.4.x）でのコンパイルは保証しない。

６．その他

6.1 ディレクトリ・ファイル構成

H8S ターゲット依存部の各ファイルの概要は次の通り。

    config/h8s/
        H8S共通部

	Makefile.config		MakefileのH8Sターゲット依存の定義
	cpu_defs.h		プロセッサ依存部のアプリケーション用定義
	cpu_config.h		プロセッサ依存部の構成定義
	cpu_config.c		プロセッサ依存部の関数
	cpu_support.S		プロセッサ依存部のサブルーチン
	cpu_context.h		コンテキスト操作
	cpu_rename.def		カーネルの内部識別名のリネーム定義
	cpu_rename.h		カーネルの内部識別名のリネーム
	cpu_unrename.h		カーネルの内部識別名のリネーム解除
	tool_defs.h		開発環境依存部のアプリケーション用定義
				（GNU開発環境用）
	tool_config.h		開発環境依存部の構成定義（GNU開発環境用）
	makeoffset.c		offset.h 生成サポートプログラム
	cpu_insn.h		低レベルのプロセッサ操作ルーチン
	start.S			スタートアップモジュール
	h8s.h			H8Sのレジスタ名などの定義
	h8s_sil.h		H8Sファミリー用システムインタフェース
				レイヤー定義
	util.h			ビット番号などの定義
	hw_serial.h		SIOドライバ
	hw_serial.cfg		SIOドライバのコンフィギュレーションファイル
	h8s_sci.h		H8Sシリーズ内蔵シリアルポート用
				簡易SIOドライバ関連の定義
	h8s_sci.c		H8Sシリーズ内蔵シリアルポート用
				簡易SIOドライバ
	hw_timer.h		タイマ操作ルーチン
	h8s_tpu.h		H8Sシリーズ内蔵タイマ用
				タイマドライバ関連の定義

    config/h8s/h8s2350/
	H8S/2350対応システム依存部
       (株式会社ミスポ製 H8S/2350 評価ボード対応)

	Makefile.config		Makefile の MISPO H8S/2350 評価ボード依存定義
	sys_defs.h  	 	システム依存部のアプリケーション用定義
	sys_config.h		システム依存部の構成定義(C言語用)
	sys_config.c 		システム依存部の関数
	sys_support.S	 	システム依存部のサブルーチン
	exception_vector.S	割込み例外処理ベクタテーブル
	sys_rename.def		カーネルの内部識別名のリネーム定義
	sys_rename.h		カーネルの内部識別名のリネーム
	sys_unrename.h		カーネルの内部識別名のリネーム解除
	h8s2350.h   		H8S/2350プロセッサのハードウェア定義
	mispo_h8s2350.h		MISP H8S/2350 評価ボードのハードウェア定義
	h8s_coff.ld	  	リンカスクリプト(ROM 化用)
	h8s_coff_gdb.ld		リンカスクリプト(GDB スタブ用)

6.1 その他

H8Sファミリーは、非常にプロセッサの種類が多いです。その中で、我々開発者の
ターゲット環境の問題から、今回の実装は H8S/2350 という特定のプロセッサのみ
のサポートとなっています。

そこで、これらの、非常に多岐に渡っているプロセッサの動作テストに協力して
いただける方を募集しております。

是非、下記へとご連絡ください。お待ちしております。

○TOPPERSプロジェクト  メーリングリスト  TOPPERS-USER

○宮城県産業技術総合センター  機械電子情報技術部  情報技術開発班
  TEL : 022-377-8700、e-mail : micom@mit.pref.miyagi.jp

変更履歴

2004年 4月15日　JSPカーネル Release1.4 対応
2004年10月18日　JSPカーネル Release1.4.1 対応
