source: ssp_qb_r5f100le_cs/trunk/arch/rl78_ca78k0r/prc_user.txt@ 95

=====================================================================
                         RL78プロセッサ依存部
                                  Last Modified: '15/6/2
=====================================================================


(1) 対応しているターゲットシステムの種類・構成

RL78プロセッサ依存部(以下，RL78依存部)は，ルネサスエレクトロニクス製 RL78ファミリ
のプロセッサを主なターゲットとする．RL78ファミリは，いくつかのグループ，
そしてまたそのグループの中に，様々な型番で表現されるプロセッサのバリエーションが
存在している．

ただし，本プロセッサ依存部において，現状では，サポートするターゲットボードとの関係から，
RL78/G13 に関する定義のみを用意している．


(2) プロセッサ依存部のファイル構成

リアルタイムOSカーネルのプロセッサ依存部として実装する部分のみを考えた場合，
RL78依存部の定義は，大抵の場合，全てのプロセッサに共通する部分と，
プロセッサの型番で異なる部分(※1)とにコードを整理することが可能である．
異なる部分についてはプロセッサ型番に基づくファイルを用意している．

※1 割込み番号，割込みハンドラ番号，及び，割込み制御レジスタの配置など

以上より，プロセッサ依存部のコードは，以下の命名規則に従って用意された
ファイルへ，共通部分と可変部分とに分類して配置されている．

prc_*  ： 全てのプロセッサに共通する定義
rl78g13_* など：プロセッサ型番毎に異なる定義

定義の配置はサポートするプロセッサを増やす毎に見直しが必要となるかもしれない．
もし現状のコード配置で不都合が生じる場合にはサポートメーリングリストまで
ご連絡頂けると幸いである．


(3) 使用する開発環境と動作検証した条件

コンパイル，及びビルド管理にはルネサスエレクトロニクス製ツールを用いる．
動作確認したバージョンはターゲット依存部のドキュメントに記載する．


(4) ターゲット定義事項の規定

(4-1) データ型に関する規定

TOPPERS共通データ型のうち，TOPPERS新世代カーネル統合仕様書(以下，統合仕様書)で
オプション扱いとされているデータ型を対象に，ターゲット依存部でのサポート状況について
記述する．これらの定義は arch/ca78k0r/tool_stddef.h で定義されている

【整数型】

・サポート
        int8_t          符号付き8ビット整数（オプション，C99準拠）
        uint8_t         符号無し8ビット整数（オプション，C99準拠）
        float32_t       IEEE754準拠の32ビット単精度浮動小数点数（オプション）

        このうち，float32_t は，IEEE754準拠の単精度浮動小数点数である．

・未サポート
        int64_t         符号付き64ビット整数（オプション，C99準拠）
        uint64_t        符号無し64ビット整数（オプション，C99準拠）
        double64_t      IEEE754準拠の64ビット倍精度浮動小数点数（オプション）
        int128_t        符号付き128ビット整数（オプション，C99準拠）
        uint128_t       符号無し128ビット整数（オプション，C99準拠）

【最大値，最小値の定数】

・サポート
        INT8_MAX                        int8_tに格納できる最大値（オプション，C99準拠）
        INT8_MIN                        int8_tに格納できる最小値（オプション，C99準拠）
        UINT8_MAX                       uint8_tに格納できる最大値（オプション，C99準拠）
        FLOAT32_MIN                     float32_tに格納できる最小の正規化された正の浮動小数点数（オプション）
        FLOAT32_MAX                     float32_tに格納できる表現可能な最大の有限浮動小数点数（オプション）

・未サポート
        INT64_MAX                       int64_tに格納できる最大値（オプション，C99準拠）
        INT64_MIN                       int64_tに格納できる最小値（オプション，C99準拠）
        UINT64_MAX                      uint64_tに格納できる最大値（オプション，C99準拠）
        DOUBLE64_MIN            double64_tに格納できる最小の正規化された正の浮動小数点数（オプション）
        DOUBLE64_MAX            double64_tに格納できる表現可能な最大の有限浮動小数点数（オプション）
        INT128_MAX                      int128_tに格納できる最大値（オプション，C99準拠）
        INT128_MIN                      int128_tに格納できる最小値（オプション，C99準拠）
        UINT128_MAX                     uint128_tに格納できる最大値（オプション，C99準拠）

(4-2) 割込み処理に関する規定

(4-2-1) 割込みハンドラ番号と割込み番号の割当て，両者の対応

割込みハンドラ番号(inhno)と割込み番号(intno)は，共にデフォルトプライオリティの値を用いる．
両者は基本的に同じ番号が1対1に対応する．従って使用可能な全ての割込み番号に対して
割込みサービスルーチン(ISR)を登録可能である．
割込み番号，割込みハンドラ番号は <プロセッサ名>.h ファイルで定義している．
(例えば rl78g13.h など)

(4-2-2) 割込み優先度の段階数（TMIN_INTPRIの値），その設定方法

カーネル管理外の割込みに対する，DEF_INH,CFG_INTはサポートする．
そのため，RL78依存部で CFG_INT のパラメータとして指定可能な割込み優先度の値は，
RL78 が持つ割込み優先度レベルの値の範囲に対応して -1(=TMAX_INTPRI) から -4 までの
値を設定可能である(※2)(※3)．ただし，後述するように，TMIN_INTPRI で定義される値に応じて，
カーネル管理及びカーネル管理外の割込みハンドラに指定可能な値の範囲が変化する．

CFG_INT で設定された割込み要求ラインにカーネル管理の割込みハンドラを
登録する場合は，TMAX_INTPRI 以下，TMIN_INTPRI 以上の値を指定しなければならない．
他方，カーネル管理外の割込みハンドラを登録する割込み要求ラインを設定する場合は，
TMIN_INTPRI より小さく，-4 以上の値を指定しなければならない．

(※2) カーネルの割込み処理モデルの上では割込み優先度を -1 から始まる負数で
 　  表現することになっているため，負号がついている．

(※3) TMIN_INTPRI を -4 にした場合，CFG_INT で優先度 -4 に設定した割込み要因は，
CPUロック状態にしない限り何重にも多重割込みが可能となるため，注意が必要である．

(4-2-3) カーネル管理外の割込み

RL78依存部では，カーネル管理外の割込みをサポートしている．

TMIN_INTPRI より高い(数値としてはより小さい)割込み優先度に設定された
割込み要求ラインの割込みは，カーネル管理外の割込みとして用いることが
可能である．カーネル管理外の割込みはOS実行中も禁止になることはなく
（厳密には割込みの出口でごく短い区間禁止される），割込み発生時は，
カーネルのコードを経由せずに呼び出される．

TMIN_INTPRI はカーネル管理の割込みに設定することのできる割込み優先度の最高値
(値としては最小値)を定義したマクロで，arch/m16c_ncxx/prc_kernel.h で
定義されている．既定では，-3となっている．この値はターゲット依存部で上書きが可能である．

(4-2-4) カーネル管理外の割込みの設定方法

CFG_INT, DEF_INH を用いてカーネル管理外の割込みハンドラを登録する場合の制約は，
(1) DEF_INH で登録する割込みハンドラの属性として TA_NONKERNEL を指定すること，
及び，(2) ハンドラ登録先の割込み要求ラインがもつ割込み優先度は，
CFG_INT により TMIN_INTPRI より高く (値としては小さい値)に設定すること，
である．

(4-2-5) カーネル管理外の割込みハンドラの記述方法

カーネル管理外の割込みハンドラは，以下のように引数，戻り値が共に void の関数
として実装すること．

void
interrupt_handler (void)
{
        /* ハンドラの内容 */
}

(4-2-6) CFG_INT でターゲット独自に使用できる割込み属性

INT割込みに関してのみ，割込み要求ラインのトリガモードの設定をサポートする．
設定できるのは，以下のいずれかである．
        ・ポジティブエッジ(トリガ割込み)：TA_POSEDGE
        ・ネガティブエッジ(トリガ割込み)：TA_NEGEDGE
        ・両エッジ(トリガ割込み)：TA_BOTHEDGE

(4-2-7) dis_intとena_intのサポートの有無，その制限事項

RL78依存部では dis_int 及び ena_int をサポートする．制限事項は特にない．

TOPPERS割込み処理モデルにおける割込み要求禁止フラグは
RL78プロセッサの割込みマスク・フラグ・レジスタが対応する．

(4-2-8) 多重割込みのサポート

多重割込みを許可する．ただし，カーネル管理外の割込みの場合，割込みハンドラの中で
PSWレジスタのIEビットを明示的にセットし，割込み許可にしなければ多重割込みが
有効とならないため，注意が必要である．

また TMIN_INTPRI==-4 の場合，CFG_INT で -4 に設定した割込みは，
CPUロック解除状態において同じ優先度 -4 の割込み処理が実行中でも
多重に割込みが受け付けられる．これはRL78のプロセッサの仕様によるもので，
PSWのIEビットが1である限り，(プロセッサ内部表現における)レベル0の割込み
(割込み処理モデルでは優先度-4の割込み)は，PSWのISPを使用した
レベルによる割込みのマスクを行うことができない．

割込み優先度-4 のカーネル管理の割込みハンドラはCPUロック解除状態で
起動されるため，注意が必要である．

(4-2-9) 割込みサービスルーチンも割込みハンドラも登録していない割込み要求

ある割込み要求ラインで割込み要求を受け付けたが，そのラインに割込みサービスルーチン及び
割込みハンドラのどちらも登録していない場合，_unused_interrupt (prc_support.asm) へ
ジャンプするようにコンフィギュレータが割込みベクタを生成する．そして，
そこから即座にリターンするようになっている．


(4-3) CPU例外処理に関する規定

(4-3-1) CPU例外ハンドラ番号

RL78 依存部ではBRK命令によるソフトウェア割込みをCPU例外として扱う．
CPU例外ハンドラ番号として0 を割り振ることにする．

各CPU例外に対する CPU例外ハンドラ番号は以下の通り．
これらは <プロセッサ名>.h で定義されている．

                例外        例外番号
#define EXCNO_BRK       0       /* ソフトウェアベクタ割込み命令 */


(4-3-2) ハンドラを登録していないCPU例外が発生したとき

発生したCPU例外に対して，CPU例外ハンドラが登録されていない場合，
_unused_interrupt (prc_support.asm) へジャンプするようにコンフィギュレータが
割込みベクタを生成する．そして，そこから即座にリターンする．

(4-3-3) ソフトウェア割込みの扱い

ソフトウェア割込みに対するハンドラは DEF_EXC で呼び出すことはできない．
一方，DEF_INH を用いて呼出し可能であるが，ソフトウェア割込みは厳密には
CPU例外に属するものであり，しかもノンマスカブルであるため，
システムコールを呼び出すなどの通常の割込みハンドラと同様の使用は避けた
方が無難である．


(4-4) CPUロック・割込みロック

割込みロック状態は，PSWレジスタのIEビットにより実現している．
IEビットが0のとき割込みロック状態，1のとき割込みロック解除状態とする．

カーネルのCPUロック状態は，TMIN_INTPRI で定義する値により異なる．

(4-4-1) TMIN_INTPRI が -4 の場合

CPUロック状態は，PSWレジスタのIEビットにより実現する．
IEビットが0のときCPUロック状態，1のときCPUロック解除状態とする．
この場合，CPUロックと割込みロックは同じである．

(4-4-2) TMIN_INTPRI が -1 以上 -3 以下の場合

PSWのインサービス・プライオリティフラグ(ISP{1,0})の値を
(-TMIN_INTPRI+3) に設定することで実現する．
例えば -3 の場合，PSW レジスタの ISP{1,0} が (0,0) に設定される．

RL78 では，ISP{1,0} に設定した値「以上(値としては小)」の優先順位を持つ割込みが
「許可」される，という仕様になっている．したがって，マスクしたいレベルより
一段高い値をセットする必要がある．


(4-5) 性能評価用システム時刻の参照に関する規定

get_utmをサポートする予定であるがまだ実装していない．


(4-6) システム初期化手順の内容

スタートアップルーチンは，システムリセット直後に呼び出され，実行を開始する．
その際のプロセッサ状態は以下を前提としている．
        ・SP, MAA は未初期化
        ・レジスタバンクは RB0
        ・PSWレジスタのIEフラグが0 (割込みロック状態と同等の状態)
        ・PSWレジスタのISP=(1,1)
        ・システムクロックは未初期化(内部オシレータ動作 1MHz)
        ・メモリ未初期化(もしソフトウェアリセットを独自に実装していれば保持されている)

まず，スタートアップルーチンの start (start.asm) が以下の処理を行う．
        ISP, MAA の初期化
        メモリ初期化
        sta_ker (startup.c) コール
そして，target_initialize (target_config.c) にてクロック設定が行われる．

その後，dispatcher (task.c) を実行する前に CPUロック状態かつ割込みロック解除状態に
しておく必要があるため，start_dispatch (prc_support.asm)において
PSW レジスタの ISP 及び IEビットを，以下の値にセットする．

(a) TMIN_INTPRI が -1 以下かつ -3 以上の場合
        IPL=-(TMIN_INTPRI)+3 かつ，IEビット=1

(b) TMIN_INTPRI==-4の場合
        IPL=3 かつ，IEビット=0

さらに，dispatcher は無限ループでリターンしないため，ジャンプ前に
start_dispatch でスタックの初期化を行っている．


(4-7) システム終了手順

システム終了時は call_exit_kernel (prc_support.asm) でスタックを初期化し，
exit_kernel (startup.c) を呼び出す．

その後，target_exit (target_config.c) でターゲット依存の終了を行う．
規定では無限ループさせるのみで特に何もしていない．
もし，ターゲット固有の終了処理を行う必要がある場合，target_exit もしくは
そこから呼び出される関数で処理を実施する．


(5) タイマドライバ関連の情報

最小セットカーネルの拡張機能として周期ハンドラ及びアラームハンドラが
用意されている．これらを使用するためにはタイムティックを供給する
タイマドライバをターゲットで用意する必要がある．


(6) 制限事項

・カーネルのコンフィギュレーション
        コンフィギュレーションのパス3（ビルド後の構成チェック）は行っていない。
        そのため，タスク，割込みハンドラ，割込みサービスルーチン，CPU例外ハンドラ，
        初期化処理ルーチン，終了処理ルーチン，周期ハンドラ，アラームハンドラが
        不正である場合を E_PAR エラーとして検出することができない．
        従ってアプリケーション開発時にテストすることでこれらの異常を検出する必要がある．

・文字コード，改行コードについて
        RL78プロセッサ依存部は Windows上で動作する開発環境 CubeSuite+ を用いて
        開発することを前提としている．TOPPERSプロジェクトから公開されるソースパッケージは
        文字コードはSJIS, 改行コードは CR+LF として公開している．


(7) サポートプロセッサの追加

(7-1) プロセッサ毎の定義事項

プロセッサ毎に異なる事項としては以下の事項がある．
        ・有効な割込み番号，割込みハンドラ番号，CPU例外ハンドラ番号の範囲
        ・割込み番号，割込みハンドラ番号，CPU例外ハンドラ番号の割り当て

従って，サポートするプロセッサを追加する場合には，まずプロセッサ名に基づく
次のファイルを用意する．例えば RL78/G13 の場合，
        rl78g13.h
                割込み番号，割込みハンドラ番号，CPU例外ハンドラ番号の定義
        rl78g13_config.h
                割込み番号の最大値(INTNO_MAX), 有効な割込み番号
        rl78g13.tf
                ・CFG_INT, DEF_INH, ATT_ISR, DEF_EXC などで指定可能なパラメータ値の定義
                        ・有効な割込み番号，割込みハンドラ番号，CPU例外ハンドラ番号の範囲の定義
                                $INTNO_VALID
                                $INHNO_VALID
                                $EXCNO_VALID
                        ・割込み番号，割込みハンドラ番号，CPU例外ハンドラ番号の範囲(無効値も含む)
                                $INTNO_RANGE 
                                $INHNO_RANGE 
                                $EXCNO_RANGE 

そしてこれらが，ビルド過程で使用されるように，ターゲット依存部のファイルから
これらをインクルードする．
        rl78g13_config.h の場合，target_config.h から
        rl78g13.h の場合，<ターゲット名称>.h から
        rl78g13.tf の場合，ターゲット依存部のCFG用テンプレートファイル(target.tf) から
                ・target.tf では，prc.tf をインクルードする前に，使用するターゲットプロセッサの
                　CFG用テンプレートファイル(この場合，rl78g13.tf)をインクルードすること．

また，これらのファイルから，それぞれのファイルに対応する共通部分の
ファイルをインクルードする
        rl78g13_config.h の場合，prc_config.h を
        rl78g13.tf の場合，prc.tf (M16Cファミリの全プロセッサに共通のtf)を

上記以外に，prc_ で定義されている事項の中に，これまでとは異なる定義の仕方を
しなければならないものが出てくるかもしれない．その場合は，定義の配置を
変更する必要があるため，サポートメーリングリストへ報告頂ければ幸いである．
報告頂いた場合，以降のバージョンアップにて対応する予定である．


○変更履歴
2014/8/21  ・新規作成
2014/9/05  ・TMIN_INTPRI が -4 の場合にも対応したため，関連箇所を追記．
2014/10/14 ・TMIN_INTPRI が -4 の場合の多重割込みについて注意事項を追記(4-2-2,4-2-8)．
           ・TMIN_INTPRI を -4 にした場合にアセンブラのオプションを変更する
           　必要がなくなったため，一部記載を削除．(4-4-1)
           ・システム初期化手順での処理内容について TMIN_INTPRI が -4 の場合を追加(4-6)．
2014/10/15 ・多重割込みの注意事項について一部修正(4-2-8)．
2015/6/2   ・SSP-1.3.0対応
以上