------------------------------------------------------------------------------
  Hyper Operating System V4 Advance  --μITRON4.0仕様OS                       
    コンフィギュレータ ドキュメント                                           
                                                                              
                                       Copyright (C) 1998-2008 by Project HOS 
                                       http://sourceforge.jp/projects/hos/    
------------------------------------------------------------------------------



1. 概要

  本ドキュメントは Hyper Operating System V4 Advance (以下 HOS-V4a)の
コンフィギュレータ(h4acfg)についての説明を記載します。



2. コンフィギュレータのメイク

  cfgrtr ディレクトリ以下にコンフィギュレータのビルド用ファイル一式が
あります。
  コンフィギュレータはターゲットプロセッサ毎に生成され、カーネル
ビルド時に連動してビルドされます。
  なお、コンフィギュレータはクロスコンパイルする際のホストマシン側
で動作するプログラムですので、ホストマシン用のコンパイラが必要に
なります。
  GNU make を利用する場合は gcc が、nmake を利用する場合は
cl (MS-C, Visual-C++)が呼び出されます。
  環境に合わせてこれらのコンパイラが実行できるように設定して
おいてください。


2. コンフィギュレータの使い方

  コンフィギュレータの仕様自体も、μITRON4.0 仕様によって定められて
おります。
  本ドキュメントはμITRON4.0仕様をご理解頂いていることを前提と
しております。μITRON4.0仕様書はITRON協会よりインターネットで
無償公開されておりますので、別途入手の上、ご確認ください。

  基本的な処理の流れとしては、静的APIを記載した、system.cfg を
Cプリプロセッサで処理した後に、h4acfg で処理することにより、
kernel_id.h(IDなどを宣言したヘッダファイル)と、kernel_cfg.c(カーネル
オブジェクトの静的生成など）を得ます。
  その後に後は、kernel_cfg.c をコンパイルしてリンクすることで、HOS-V4aが
利用可能となります。


3. HOS-V4a 独自の静的API

  h4acfgでは μITRON4.0仕様 で定める静的APIの他に下記のAPIを
備えております。

    KERNEL_HEP_MEM, KERNEL_SYS_STK,
    KERNEL_INT_STK, KERNEL_INT_SP,
    KERNEL_TIM_TIC,
    KERNEL_MIN_INTNO, KERNEL_MAX_INTNO,
    KERNEL_MAX_TSKID, KERNEL_RSV_TSKID,
    KERNEL_MAX_SEMID, KERNEL_RSV_SEMID,
    KERNEL_MAX_FLGID, KERNEL_RSV_FLGID,
    KERNEL_MAX_DTQID, KERNEL_RSV_DTQID,
    KERNEL_MAX_MBFID, KERNEL_RSV_MBFID,
    KERNEL_MAX_MBXID, KERNEL_RSV_MBXID,
    KERNEL_MAX_MPFID, KERNEL_RSV_MPFID,
    KERNEL_MAX_CYCID, KERNEL_RSV_CYCID,
    KERNEL_MAX_ISRID, KERNEL_RSV_ISRID



4. 静的APIの説明

  μITRON4.0 標準 API については μITRON4.0 仕様 をご参照ください。
   ここでは HOS 独自 API についてのみ説明いたします。



4.1 カーネルのヒープメモリの指定

  【API】
      KERNEL_HEP_MEM(SIZE hepsz, VP hep);

  【パラメータ】
      SIZE   hepsz        カーネルのヒープメモリのサイズ
      VP     sysstk       カーネルのヒープメモリ

  【機能】
      カーネルは各種動的オブジェクト生成(cre_xxxやacre_xxx)にて、
    オブジェクトを生成する場合、カーネルのヒープからメモリを
    割り当てます。
      本APIではカーネルのヒープメモリを指定します。
      hep に指定されたアドレスから、hepsz で指定されたサイズ分の
    メモリ領域をアイドル時のスタックに割り当てます。
      hep に NULL を指定した場合、hepsz で指定されたサイズを
    コンフィギュレータが自動的に確保します。


4.2 システムタスクのスタックの指定

  【API】
      KERNEL_SYS_STK(SIZE sysstksz, VP sysstk);

  【パラメータ】
      SIZE   sysstksz     システムタスクのスタックのサイズ
      VP     sysstk       システムタスクのスタック

  【機能】
      カーネルは実行するタスクがない場合のアイドルループ実行や、必要に応じて
    一部の処理をカーネル内部のシステムタスクにて実行します。
    本APIではシステムタスクのスタックを指定します。
      sysstk に指定されたアドレスから、sysstksz で指定されたサイズ分の
    メモリ領域をアイドル時のスタックに割り当てます。
      sysstk に NULL を指定した場合、sysstksz で指定されたサイズをコンフィ
    ギュレーターが自動的に確保します。
      未指定の場合、デフォルトでプロセッサ毎に最低限必要なサイズが割り当て
    られますが、アイドル時の例外処理等でスタックを大量に消費する場合は
    本APIにて調整することが可能です。


4.3 割込み時のスタックの指定

  【API】
      KERNEL_INT_STK(SIZE intstksz, VP intstk);
      KERNEL_INT_SP(VP intsp);

  【パラメータ】
      SIZE   intstksz     割込み時のスタックのサイズ
      VP     intstk       割込み時のスタック
      VP     intsp        割込み時の初期スタックポインタ値

  【機能】
      割り込みが発生した場合、スタックは割込み用スタックに切り替わります。
      本APIでは割込み時に切り替えるスタックを指定します。
      KERNEL_INT_STK と KERNEL_INT_SP は同時には利用できず、どちらか片方を
    利用して指定を行います。
      KERNEL_INT_STK では、intstk に指定されたアドレスから、intstksz で指定
    されたサイズ分のメモリ領域を割込み時のスタックに割り当てます。
      intstk に NULL を指定した場合、intstksz で指定されたサイズをコンフィ
    ギュレーターが自動的に確保します。
      KERNEL_INT_SP では、intsp に割込み発生時のスタックポインタ値を直接指定
    できます。

  【補足】
      割込み用のスタックポインタ初期値は _kernel_int_isp の名称で生成されます。
    通常、起動時のスタートアップルーチン実行時のスタックと割込み用のスタックは
    共有できる為、スタートアップルーチンにて、_kernel_int_sp を参照して利用する
    ことが可能です。


4.4 タイムティックの周期の指定

  【API】
      KERNEL_TIM_TIC(UW nume, UW deno);

  【パラメータ】
      UW      nume        タイムティックの周期の分子
      UW      deno        タイムティックの周期の分母

  【機能】
      isig_tim にてカーネルに供給するタイムティックの周期を指定します。
      例えば、周期に 10/1 を指定した場合、isig_tim を１回呼び出すごとに
    カーネルのシステム時刻は10進みます。
      逆に 1/3 などを指定した場合には、isig_tim を 3回呼び出して初めて
    システム時刻は1進みます。
      指定しない場合デフォルトで 1/1 となります。

  【補足】
      例えば 周期が 3.333... ms のインターバルタイマにて、isig_tim を
    呼び出し、システムの単位時間を ms に統一したい場合などは 10/3 を
    指定すれば、isig_tim を 呼び出すごとに、3, 3, 4, 3, 3, 3, 4...
    といった順序で3回の isig_tim の呼び出しで、システム時刻が 10 進む
    ようになります。


4.5 割り込み番号の範囲の指定

  【API】
      KERNEL_MIN_INTNO(INTNO minintno);
      KERNEL_MAX_INTNO(INTNO maxintno);

  【パラメータ】
      INTNO   minintno    割り込み番号の最小値
      INTNO   maxintno    割り込み番号の最大値

  【機能】
      割り込み番号の最大値と最小値を指定します。
      プロセッサのリビジョンにより利用できる割り込み範囲が異なったり、
    用途として使う範囲が狭い場合、本APIで範囲を限定し、割込み管理テーブルの
    メモリ量を抑制することが可能となります。

  【補足】
     プロセッサによっては、前半がプロセッサ例外やリセットなどに
    割り当てられており、割り込み番号が後半の番号から始まることが
    あるものもある為、最小値も指定できるようになっております。
      指定した範囲の分しか、割り込み管理テーブルを生成しませんの
    で、プロセッサでは定義されていても利用しない範囲を外すなどで
    メモリの削減を行うことも可能です。


4.6 オブジェクトの最大IDの指定

  【API】
      KERNEL_MAX_TSKID(ID maxtskid);
      KERNEL_MAX_SEMID(ID maxsemid);
      KERNEL_MAX_FLGID(ID maxflgid);
      KERNEL_MAX_DTQID(ID maxdtqid);
      KERNEL_MAX_MBXID(ID maxmbxid);
      KERNEL_MAX_MBFID(ID maxmbfid);
      KERNEL_MAX_MPFID(ID maxmpfid);
      KERNEL_MAX_CYCID(ID maxcycid);
      KERNEL_MAX_ISRID(ID maxisrid);

  【パラメータ】
      ID      maxtskid    タスクIDの最大値
      ID      maxsemid    セマフォIDの最大値
      ID      maxflgid    フラグIDの最大値
      ID      maxdtqid    データキューIDの最大値
      ID      maxmbxid    メールボックスIDの最大値
      ID      maxmbfid    メッセージバッファIDの最大値
      ID      maxmpfid    固定長メモリプールIDの最大値
      ID      maxcycid    周期ハンドラIDの最大値
      ID      maxisrid    割込みサービスルーチンIDの最大値

  【機能】
      各オブジェクトのIDの最大値を指定します。
      指定しない場合デフォルトでコンフィギュレータで生成した
    オブジェクトが利用している最大のID番号になります。

  【補足】
      cre_tsk や cre_sem といった、動的にオブジェクトを生成する
    場合、ここで指定した範囲を超えるIDは利用出来ません。
      利用するID範囲を適切な範囲に設定することで、ID管理部の
    メモリを有効に利用することが可能です。
      なお、本機能はID空間を予約するだけですので、実行時にメモリが
    不足していた場合は acre_xxx や cre_xxx の実行時に E_NOMEM が
    返される場合があります。


4.8 オブジェクトのID空間の予約

  【API】
      KERNEL_RSV_TSKID(ID tskidno);
      KERNEL_RSV_SEMID(ID semidno);
      KERNEL_RSV_FLGID(ID flgidno);
      KERNEL_RSV_DTQID(ID dtqidno);
      KERNEL_RSV_MBXID(ID mbxidno);
      KERNEL_RSV_MBFID(ID mbfidno);
      KERNEL_RSV_MPFID(ID mpfidno);
      KERNEL_RSV_CYCID(ID cycidno);

  【パラメータ】
      ID      tskidno    予約するタスクID数
      ID      semidno    予約するセマフォID数
      ID      flgidno    予約するイベントフラグID数
      ID      dtqidno    予約するデータキューID数
      ID      mbxidno    予約するメールボックスID数
      ID      mbfidno    予約するメッセージバッファID数
      ID      mpfidno    予約するメモリプールID数
      ID      cycidno    予約する周期ハンドラID数

  【機能】
      実行時に acre_xxx や cre_xxx でオブジェクトを生成する為にID空間を
    予約します。この指定があると、静的生成分に加えて xxxidno 個の
    ID空間が確保されます。

  【補足】
  
      基本的には KERNEL_MAX_XXXIDと同じ用途のAPIですが、IDの最大値では
    なく予約数(=静的生成分を除く利用可能なID数)を指定する点が異なり
    ます。また、本APIは複数指定が許され、実際に予約されるオブジェクト
    数は指定された予約数の総和となります。
      KERNEL_MAX_XXXIDとは排他的な関係にあります。両方を同時に使用するこ
    とは出来ません。
      なお、本機能も KERNEL_MAX_XXXID と同様にID空間を予約するだけ
    ですので、実行時にメモリが不足していた場合は acre_xxx や cre_xxx の
    実行時に E_NOMEM が返される場合があります。



------------------------------------------------------------------------------
 end of file
------------------------------------------------------------------------------
