-------------------------------------------------------------------------------
 HOS-80 Ver 0.01 Hyper Oparating System for Z80                                
 リファレンスマニュアル                                                        
                                                    Copyright (C) 1998 by Ryuz 
-------------------------------------------------------------------------------


  このマニュアルでは HOS-80 の利用しかたを説明します。



＜目次＞
  第１章  HOS-80 の概要
  第２章  ライブラリのメイク方法
  第３章  コンフィギュレーターの使い方
  第４章  プログラムのメイク方法
  付録Ａ  著作権・再配布について
  付録Ｂ  謝辞
  付録Ｃ  参考文献




-------------------------------------------------------------------------------
                                第１章
                            HOS-80 の概要
-------------------------------------------------------------------------------

  HOS-80 はμITRON3.0仕様に準拠した Z80 用のリアルタイムＯＳです。主に個人
レベルでのホビーを目的とした物でＲＯＭ化するシステムにリンクするだけで簡単
に組み込むことが出来ます。


1.1 ＜システムコール＞

  接続機能を除くレベルＳまでと一部のレベルＥ、Ｃのシステムコールをサポート
しています。
  サポートしているシステムコールは以下の通り。

タスク管理
  sta_tsk  ext_tsk  ter_tsk  dis_dsp  ena_dsp  chg_pri  rot_rdq  rel_wai
  get_tid  ref_tsk

タスク付属同期機能
  sus_tsk  rsm_tsk  frsm_tsk slp_tsk  wup_tsk  can_wup

同期・通信機能
  sig_sem  wai_sem  preq_sem ref_sem  set_flg  clr_flg  wai_flg  pol_flg
  ref_flg  snd_msg  rcv_msg  prcv_msg ref_mbx

割り込み管理機能
  ret_int  loc_cpu  unl_cpu

時間管理機能
  set_tim  get_tim  dly_tsk

メモリプール
  get_blf  pget_blf rel_blf  ref_mpf

システム管理
  get_ver  ref_sys


  各オブジェクトは全て静的に生成します。コンフィギュレーターを用意しており
ますので簡単に生成することが可能です。


1.2 ＜スペック＞
  最大タスク数           255
  SUSPEND最大ネスト数    255
  起床要求最大ネスト数   255
  最大セマフォ数         255
  最大セマフォカウンタ   255
  最大イベントフラグ数   255
  イベントフラグの種類   8 bit
  最大メイルボックス数   255




-------------------------------------------------------------------------------
                                第２章
                        ライブラリのメイク方法
-------------------------------------------------------------------------------

  HOS-80 はソースで配布されますので利用するためにはまずソースをメイクして
ライブラリファイルを生成する必要があります。この章ではライブラリのメイク方法
を説明します。


2.1 ＜必要なコンパイラ＞
  HOS-80 をコンパイルするためには「エル・エス・アイ ジャパン株式会社」製の
LSI C-80 が必要です。HOS-80の開発には Ver3.5 を利用しましたが特に複雑な機
能は利用していませんので多少の変更で他のバージョンでもコンパイル可能かと
思います。
  以後の説明はコンパイラのディレクトリにパスが通り、利用可能な状態になって
いることを前提に進めます。

2.2 ＜ヘッダファイルのコピー＞
  まずは配布ファイルを解凍した時に作られる INCLUDE というディレクトリの
下にあるファイルをコンパイル時に利用するディレクトリにコピーします。この
ヘッダファイルはライブラリのリンク時にも使用しますし、後からHOS-80を利用
したアプリケーションを作製する際にもインクルードする必要があります。
  例として LSIC-80 が c:\lsij\lsic80 にインストールされているなら
c:\lsij\lsic80\include\hos といったディレクトリを作製してコピーしておけ
ばいいでしょう。

2.3 ＜コンパイルオプションの設定＞
  LSIC-80 にはデフォルトのコンパイルオプションとして _lcc80 というファイル
があります。解凍時にできる libsrc というディレクトリにはライブラリのメイク
時に使用する _lcc80 があります。まずはこれを自分の環境に合わせて書き直して
ください。具体的にはインクルードファイルやライブラリファイルのあるパスを
変更して、先にコピーしたヘッダファイルのパスを追加します。
  例えば先の例の場合は以下のような設定になるはずです。

-Xc:\lsij\lsic80\bin			# コマンドのディレクトリ
-Lc:\lsij\lsic80\lib			# ライブラリのディレクトリ
-Ic:\lsij\lsic80\include		# ヘッダのディレクトリ
-Ic:\lsij\lsic80\include\hos	# HOS-80のヘッダファイル

  また、_lcc80 が無かった場合は LSIC-80 のディレクトリの _lcc80 が参照され
ますので、こちらにも HOS-80 用のヘッダファイルのパスを指定しておくと後々
便利でしょう。
  また sample ディレクトリにもサンプルメイク用の _lcc80 がありますので
サンプルをメイクする場合にはこちらも書き直してください。

2.4 ＜ライブラリのメイク＞
  全ての設定が終ったらいよいよメイクです。解凍時の libsrc に makefail があり
ますので、このディレクトリに移動し LSIC-80 付属の kmmake を実行してください。
エラーが無ければ hos80.sof というライブラリファイルと hos80_st.sof という
スタートアップ用のオブジェクトファイルが生成されるはずです。
  この hos80.sof と hos80_st.sof をライブラリ用のディレクトリ(先の例では
c:\lsij\lsic80\lib) にコピーしてください。

  hos80_st.sof は lcc80 の -a オプションで組み込みます。HOS80 しか利用しない
のであればデフォルトの _lcc80 に -ahos80_st.sof と書き加えておいても良いかも
しれません。

2.3 ＜コンフィギュレーターのコピー＞
  config というディレクトリに hcfg80.c というコンフィギュレーターのソースと
hcfg80.exe という hcfg80.c を Borland-C++ 5.02J Development Suite で
コンパイルした物を用意しています。アプリケーション作成時に hcfg80.exe を
利用しますので、これをパスの通ったディレクトリにコピーしておいてください。

  これで HOS-80 を利用したアプリケーションを作製する準備が整いました。




-------------------------------------------------------------------------------
                                第３章
                      コンフィギュレーターの使い方
-------------------------------------------------------------------------------

  この章では HOS-80 のコンフィギュレーターの使い方を説明します。


3.1 ＜コンフィギュレーターとは＞
  HOS-80 ではタスクをはじめ、セマフォ、イベントフラグなどは静的に生成されま
す。そのためこれらを記述したプログラム書きコンパイル、リンクを行なう必要が
あります。しかしこれらのプログラムを毎回記述するのは面倒であるため、必要な
項目のみを書いたファイルを用意し、コンフィギュレーターを使いこのファイルから
必要なソースを生成させます。

3.2 ＜コンフィギュレーターの機能＞
  コンフィギュレーターは次の機能を持ちます。

  ・最大優先度の指定
  ・割り込みハンドラの登録
  ・タスクの登録
  ・セマフォの登録
  ・イベントフラグの登録
  ・メイルボックスの登録


3.3 ＜コンフィギュレーターの動作＞
  コンフィギュレーターはユーザーが用意した "hos.cfg" というファイルを読み込
んで解析し、"cfg_c.c"、"cfg_asm.asz"、"defid.h"という３つのファイルを出力し
ます。ユーザーは各プログラムの中で "defid.h" をインクルードして使い、メイク
時には "cfg_c.c"、"cfg_asm.asz" をそれぞれコンパイルしてリンクする必要があり
ます。

（注：現バージョンではファイル名が固定です。）


3.4 ＜コンフィギュレーションファイルの書き方＞
  コンフィギュレーションファイル("hos.cfg")の書き方を説明します。

ファイル中には１行に１命令のみおくことが出来ます。また命令は一行に全て書いて
しまう必要があります。
  利用できる命令を以下に記します。

  INCLUDE_C     "cfg_c.c" で読み込むファイルの指定
  USE_TIMER     時間管理機能を利用することを宣言
  NOUSE_TIMER   時間管理機能を利用しないことを宣言
  MAX_TSKPRI    最大タスク優先度を指定
  SYSTEM_STACK  システム用のスタックポインタの指定
  CRE_TSK       タスクの登録
  CRE_SEM       セマフォの登録
  CRE_FLG       イベントフラグの登録
  CRE_MBX       メイルボックスの登録
  CRE_MPF       固定長メモリプールの登録
  DEF_INT       割り込みハンドラの登録


  具体的な例は解凍時に出来た sample というディレクトリにありますので参照して
ください。ここでは個々の命令を簡単に説明します。


INCLUDE_C  Ｃ言語ファイル用インクルードファイル指定
  文法： INCLUDE_C("filename.h")

  "cfg_c.c" でインクルードするファイルを指定します。"cfg_c.c" ではタスク
開始時の関数などが利用されますので、それらを宣言したヘッダファイルのイン
クルードが必要です。この命令にて指定してください。
  なお、<ITRON.h> は自動的に読み込まれます。


USE_TIMER  タイマ利用
  文法： USE_TIMER (デフォルト)

  時間管理機能を使うことを宣言します。ただし実際に機能を使うには定期的に
__time_handler を呼び出すようにする必要があります。
  時間管理用のシステムコールを呼び出さなければ USE_TIMER を指定しても問題は
無いのでデフォルトとなっています。


NOUSE_TIMER  タイマ未使用
  文法： NOUSE_TIMER

  時間管理機能を使わないことを宣言します。時間管理用のメモリを確保しなく
なります。


MAX_TSKPRI  最大タスク優先度指定
  文法： MAX_TSKPRI(maxtskpri)

  maxtskpri : 最大優先度

  最大優先度を指定します。範囲のエラーチェックは行なっていないので指定する
際は実際に使っている優先度を良く確認してください。


SYSTEM_STACK  システム用スタックアドレス指定
  文法： SYSTEM_STACK(stackadr)

  stackadr  : スタックポインタのアドレス

  スタートアップ時や非タスク部でシステムが利用するスタックポインタの初期値
を指定します。デフォルトは 0x0000 です。通常はRAMの最後を指定しますが、
0xffff までメモリを積んでいない場合はここで変更してください。


CRE_TSK  タスク生成
  文法： CRE_TASK(ID_TASK, exinf, func, itskpri, stacksize)

  ID_TASK   : タスクＩＤ定義名
  exinf     : 拡張情報
  func      : タスク開始関数名  void func(int stcd)
  itskpri   : タスク優先度初期値 1〜8
  stacksize : スタックサイズ

  タスクＩＤは自動的に振られ "defid.h" に

  #define ID_TASK 1

  といった形で出力されます。この項目に数値を指定すると直接ID番号を
指定することが出来ます。


CRE_SEM  セマフォ生成
  文法： CRE_SEM(ID_SEM, exinf, isemcnt, maxsem)

  ID_SEM    : セマフォＩＤ定義名
  exinf     : 拡張情報
  isemcnt   : セマフォの初期値
  maxsem    : セマフォの最大値


CRE_FLG  イベントフラグ生成
  文法： CRE_SEM(ID_FLG, exinf, iflgptn)

  ID_FLG    : イベントフラグＩＤ定義名
  exinf     : 拡張情報
  iflgptn   : イベントフラグ初期値


CRE_MBX  メイルボックス生成
  文法： CRE_MBX(ID_MBX, exinf, bufsize)

  ID_MBX    : メイルボックスＩＤ定義名
  exinf     : 拡張情報
  bufcnt    : バッファのサイズ


CRE_MPF  固定長メモリプール生成
  文法： CRE_MPF(ID_MPF, exinf, mpfsz, mpfcnt)

  ID_MBX    : メイルボックスＩＤ定義名
  exinf     : 拡張情報
  mpfsz     : １ブロックのサイズ(Byte) ２以上であること
  mpfcnt    : ブロック数


DEF_INT  割り込みハンドラ定義
  文法： DEF_INT(intnum, func)

  intnum    : 割り込み番号 0〜254 (２の倍数であること)
  func      : 割り込みハンドラ（Ｃ言語の関数）

  レジスタの待避、スタックの切り替え後 void func(void) が呼ばれる。
  なお割り込み中も割り込みは許可されている。必要であれば di()、ei() で
処理すること。


  なお、"cfg_c.c" に展開されるパラメーターのほとんどは数値としてではなく
文字列としてそのまま展開します。そのためエラーチェック能力はほとんどあり
ませんが、数式を入力したり、INCLUDE_C 命令で読み込むヘッダファイル中のマクロ
を利用することが出来ます。




-------------------------------------------------------------------------------
                                 第４章
                            プログラムの作成方法
-------------------------------------------------------------------------------

  この章では実際に HOS-80 を使ったプログラムを作成する方法を説明します。


4.1 ＜スタートアップルーチン＞

  普通のＣ言語のプログラムは main 関数から始まりますが、HOS-80 では
  start_up という関数から始まります。

  void start_up(void)

  という関数を必ず用意してください。

  このスタートアップルーチンは非タスク部として扱われ、割り込みは許可されてい
ます。普通はここで変数の初期化やデバイス初期設定を行いタスクをスタートさせた
りします。タスクを一切使わず割り込みだけで処理するなどという場合は普通の mian
関数として使えますが OS としての意味がほとんどありません。
  なお、非タスク部ですが割り込みルーチンではありませんので ret_int は使えませ
ん、絶対に呼び出さないでください（普通に return してください）。リターン後に
ディスパッチが開始されます。


4.2 ＜時間管理機能＞
  時間管理機能を使うためには __time_handler というハンドラを定期的に呼び出す
必要があります。非タスク部から定期的に呼ぶか、インターバルタイマを設定して
割り込みアドレスに __time_handler を指定してください。
  なお、一回呼び出すごとに進む時間を設定する vset_tmi(timint) というマクロを
用意しています。デフォルトで１が設定されていますが vset_tim(5) と宣言しておけ
ば 5msec 間隔で呼び出しても時間は 1msec 単位となります。
  荒業ですが、2.5msec単位で呼び出して vset_tim(2)とvset_tim(3) を交互に呼ぶ
などということも出来ます。特に msec 単位である必要がある場合は利用してくださ
い(Z80で 1msec での割り込みはさすがに重いですので）。


4.3 ＜メイク＞
  メイクの際には作製したソースのほかにコンフィギュレーターが出力した cfg_c.c
と cfg_asm.asz の２種類をそれぞれコンパイルする必要があります。また HOS-80 の
スタートアップルーチンとして startup.sof を用意していますのでこれを必ず先頭に
してリンクを行なってください。





-------------------------------------------------------------------------------
                                 付録Ａ
                             著作権・再配布
-------------------------------------------------------------------------------

A.1 ＜著作権＞
  配布用アーカイブに含まれる全てのプログラム、ソースファイル、ドキュメントの
著作権は Ryuz こと渕上竜司が保持します。


A.2 ＜免責＞
  これらのプログラムの使用によって生じたいかなる損害も作者が補償するものでは
ありません。プログラムの利用は利用者の責任において行なってください。


A.3 ＜利用条件＞
  このプログラムは非営利目的であれば自由に利用することが出来ます。個人レベル
での改造も自由に行なうことが出来ますが、著作権の表示は変更しないようお願いい
たします。
  営利目的で利用される方はおられないとは思いますが、ご希望がありましたら作者
までご連絡ください。


A.4 ＜再配布＞
  プログラムを改変した物も含めて再配布は自由といたします。作者に無断でどん
どんやってください。ただし、改変した物を再配布する場合は著作権の表示と変更
履歴をきちんと残していただけますようにお願いします。変更履歴さえ残していた
だければＯＳ名を変更、もしくは加工していただいてかまいません。作者に無断で
どんどん派生してください（連絡を頂ければ嬉しいですが）。


A.5 ＜寄付＞
  寄付は大歓迎です（いないでしょうけど(^^; ）。作者までご連絡ください。寄付
していただいたからといって特別になにか出来るわけではありませんが、開発費に
当てさせていただきます。実践的な物資も歓迎です。私のシェアウェアを買っていた
だいてもいいです（爆）。


A.6 ＜作者の連絡先＞
  １９９８年３月現在の作者の連絡先は以下の通りです。バグレポや感想など
頂けると嬉しいです。


  e-mail  : QZF06013@niftyserve.or.jp  (テキストメールのみ)
            ryuz@try-net.or.jp
 HomePage : http://member.nifty.ne.jp/Ryuz/
            http://www.try-net.or.jp/~ryuz/

  将来的にはメール、ホームページとも Nifty-Serve に移行する予定ですが、
今のところ Try-Netをメインにしております。




-------------------------------------------------------------------------------
                                 付録Ｂ
                                  謝辞
-------------------------------------------------------------------------------

  最後になりましたが TRONプロジェクトというすばらしいものを生み出してくだ
さいました坂村先生を始めとする多くの方々、素人の私にこころよく助言くだ
さった ITRON-Club メイリングリストの方々に厚く御礼申し上げます。
  またこのプログラムの開発にあたって九州工業大学の高野先生に開発環境を提供
していただきました。有り難うございます。




-------------------------------------------------------------------------------
                                 付録Ｃ
                                参考文献
-------------------------------------------------------------------------------

  このプログラムの作成にあたり参考とした文書を以下に記します。
「μITRON3.0標準ハンドブック」は手元に置かれることをお勧めいたします。
 http://tron.um.u-tokyo.ac.jp/TRON/ITRON/home-j.html から英語版の
 ダウンロードが出来るようです。


  μITRON3.0標準ハンドブック  改訂新版
     監修 坂村 健   パーソナルメディア
     ISBN4-89362-154-8  \4,000+税

  ITRON・μITRON標準ハンドブック
     監修 坂村 健   パーソナルメディア
     ISBN4-89362-079-7  \4,800+税

  TRON標準ガイドブック2
     監修 坂村 健   パーソナルメディア
     ISBN4-89362-133-5  \3,500+税

  TRONWARE Vol.3 リアルタイムＯＳ ITRON入門
     パーソナルメディア
     ISBN4-89362-071-1  \1,204+税

  TRONWARE Vol.5 シングルチップCPU向けリアルタイムＯＳ μITRON入門
     パーソナルメディア
     ISBN4-89362-076-2  \1,204+税
