フレーム無し 関数一覧(フレーム無し) フレーム付き

XTAL RT
共通仕様
システムコール/ライブラリ
説明書

Ver.0.007a
(MAY/09/2000)
(DEC/14/1995)

(株)アックス
AXE, Inc.



目次


  1. はじめに
  2. システムコール
    C インクルードファイル
    システム (system)
    プロセス (process)
    キュー (queue)
    イベント (event)
    セマフォ (semaphore)
    共有メモリ (Common Memory)
    デバッグ (debugging)
  3. ライブラリ
  4. 関数・構造体 一覧表

I. はじめに

このドキュメントはXTAL RT(DEC/14/1995)のC言語インターフェースを 説明しています。

XTALでは、すべてのオブジェクトには名前が必要です。 特に意味を持たせなくてもよい名前は name_generate() でつくり出して下さい。

時間の単位は tick (system 依存)です。
tick は基本的に1/60秒ですが、ハードウェアの都合により 必ずしも 1/60を保証できない場合があります。 tickに関してはXTALのポーティング者に照会ください。

一般に、時間に -1 を指定した場合は無限を表します。

また、未来のバージョンにおいて、 プログラム・コードを外部から読み込むプリミティブ(code_load() 等)が サポートされた場合、code_create() は、使えなくなる可能性があります。

XTAL RT では特に断らない限りプロセスがスケジューリングされることは ありません。 (SystemCallを呼び出したり、割り込みが起こってもプロセスの スケジューリングは一切起こりません。もちろん Task は、時間によって スケジュールされますが、その他は thread と同じ条件です。)

プロセスはその状態が「WAIT」か「SLEEP」となった場合、CPUを失い、 スケジューリングの対象となります。

スケジューリングの優先度において thread と Task は同等に扱われます。 I/Oなどの処理を高速に行ないたい thread は優先度を高くしておくべきです。

ただし、同じ優先度の thread と Task が READY であるときは、 同じ優先度の全ての thread が処理されるまで、Task の実行は起こりません。

queue 待ち状態のプロセスが queue の待ち行列から外され READY になる 順序は、優先度その他の要素に関係なく、queue 待ちに来た順序の通りです。

threadは近い将来、CPUをグラブするプロセスと表現されるようになります。

すべてのプロセスはCPUを動的にグラブしたり、開放したりできます。 プロセス生成時にthreadを指定した場合は、かならず CPUをグラブします。 TaskもCPUをグラブできます。


II. システムコール
  1. Cインクルードファイル
     
    #include "crystal.h"
     
     

  2. システム (system)
     
    
    BYTE4
    sys_gettime()
     
     
    システムの絶対時間の下位 3 byte を返す。最上位 byte は0
     
    
    OBJECT_NAME
    name_generate()
     
     
    今まで使われていないオブジェクト名をつくり出す

    注意:
    name_generate()で得た名前は、 なるべく早く(実時間で5分間程度のうちに)、 オブジェクトの生成に使用して下さい。
    時間が経ち過ぎると、一意性の保証ができなくなります。

  3. プロセス (process)

    プロセスには次の5つの状態がある。

    EXIST
    プロセス・オブジェクトが生成されている。実行は始まっていない
    READY
    プロセスは code を実行可能
    (「READY」状態のプロセスは「ACTIVE」になる可能性を常に持っている)
    ACTIVE
    プロセスは code を実行中(CPUを得ている)
    SLEEP
    プロセスは sleep 中
    WAIT
    プロセスはイベント、キューなどを待っている

    Task はそれぞれ固有の timeslice 値というものを持っている。

    timeslice 値とは「何 tick で timeslice されるか」というものである。

    PROC_INI 構造体
     
    struct  Proc_ini {
    	PROC_TYPE       type;		/* thread or Task */
    	PRIO            priority;	/* priority 初期値*/
    	OBJECT_NAME     code;		/* プログラム・コードの名前 */
    	BYTE4           stack_size;	/* 使用するスタックの大きさ */
    	OBJECT_NAME     data;		/* 将来バージョンで使用 */
    };
    #define PROC_INI struct Proc_ini
     
     
    PROC_INI メンバーの意味
    type
    thread/Task/SystemThreadのいずれかを設定
    priority
    優先度の初期値
    code
    Codeオブジェクトの名前を入れる
    stack_size
    プロセスが使用するスタックのサイズ(Bytesで)
    data
    将来バージョンで使用
     
    
    int
    proc_create(name, pdata)
    OBJECT_NAME name;
    PROC_INI *pdata;
     
     
    プロセスを作る
    プロセスの状態は「EXIST」

    エラーの時は -1 が返る
    エラー原因の可能性:
    メモリが不足でプロセスが作れない。
    指定した名前のオブジェクトが既に存在している。
     
    
    int
    proc_delete(name)
    OBJECT_NAME name;
     
     
    name で指定されたプロセスを delete する
    「EXIST」以外の状態にあるプロセスに作用することはできない


    エラーの時は -1 が返る
    エラー原因の可能性:
    指定した名前のプロセスが存在しない。
    指定したプロセスの状態が「EXIST」ではない。
     
    
    int
    proc_start(name)
    OBJECT_NAME name;
     
     
    「EXIST」状態のプロセスをスタートする
    プロセスの状態は「READY」になる
    「EXIST」以外の状態にあるプロセスに作用することはできない

    エラーの時は -1 が返る
    エラー原因の可能性:
    指定した名前のプロセスが存在しない。
    指定したプロセスの状態が「EXIST」ではない。
     
    
    int
    proc_stop(name)	
    OBJECT_NAME name;
     
     
    name で指定されたプロセスを「EXIST」状態にする

    エラーの時は -1 が返る
    エラー原因の可能性:
    指定した名前のプロセスが存在しない。
     
    
    int
    proc_wakeup(name)
    OBJECT_NAME name;
     
     
    「SLEEP」状態のプロセスを起こす
    プロセスの状態は「READY」になる
    「SLEEP」以外の状態にあるプロセスに作用することはできない

    エラーの時は -1 が返る
    エラー原因の可能性:
    指定した名前のプロセスが存在しない。
    指定したプロセスの状態が「SLEEP」ではない。
     
    
    int
    proc_sleep(naem,timeout)
    OBJECT_NAME name;
    BYTE4 timeout;
     
     
    name で指定したプロセスを timeout だけ sleep させる
    プロセスの状態は「SLEEP」になる
    sleep 中のプロセスは proc_wakeup() で「READY」状態にすることができる
    proc_sleep()は、timeout==0 の場合も、スケジューリングを引き起こす。

    タイム・アウトが起こった場合は -2 が返る。

    エラーの時は -1 が返る
    エラー原因の可能性:
    指定した名前のプロセスが存在しない。
     
    
    int
    proc_setslice(name,s)
    OBJECT_NAME name;
    BYTE4 s;
     
     
    name で指定されたプロセスの timeslice 値を設定する

    エラーの時は -1 が返る
    エラー原因の可能性:
    指定した名前のプロセスが存在しない。
     
    
    int
    proc_setpriority(name,s)
    OBJECT_NAME name;
    BYTE4 s;
     
     
    name で指定されたプロセスの priority 値を設定する

    エラーの時は -1 が返る
    エラー原因の可能性:
    指定した名前のプロセスが存在しない。
     
    
    int
    self_sleep(timeout)
    BYTE4 timeout;
     
     
    timeout だけ sleep する
    プロセスの状態は「SLEEP」になる
    sleep 中のプロセスは proc_wakeup() で「READY」状態にすることができる
    self_sleep()は、timeout==0 の場合も、スケジューリングを引き起こす。

    タイム・アウトが起こった場合は -2 が返る。
     
    
    void
    self_end()
     
     
    自プロセスを終了する
    プロセスの状態を「EXIST」にした後、proc_delete(自プロセス) を行なう
    絶対にリターンしない
     
    
    int
    self_getname()
     
     
    自分自身のプロセス名を得る
     
    
    int
    self_setslice(s)
    BYTE4 s;
     
     
    自分の timeslice 値を s に設定する
     
    
    int
    self_setpriority(s)
    BYTE4 s;
     
     
    自分の priority 値を設定する
     
    
    int
    self_grab_cpu()
     
     
    CPUをグラブする
    プロセスがthreadとなったのと同じ効果を持つ
    プロセスが「WAIT」状態になるまでCPUを独占し続ける
    self_ungrab_cpu()によりプリエンプションされるプロセスに戻る
     
    
    int
    self_ungrab_cpu()
     
     
    CPUを開放可能にする
    プロセスはプリエンプションされるプロセスに戻る
    プロセスは次のプリエンプション・ポイントでプリエンプションされる

  4. キュー (queue)

    キューはプロセス間で、ある程度の大きさを持つデータを通信するための FIFOである。

    プロセスがキューを queue_write() に来た時に、キューが一杯ならば、 そのプロセスはデータを書き込めるか、タイムアウトになるまで「WAIT」状態に される。

    プロセスがキューを queue_read() に来た時に、キューが空ならば、 そのプロセスはデータが得られるか、 タイムアウトになるまで「WAIT」状態にされる。

    タイムアウトの場合を除き、queue 待ち状態のプロセスが queue の 待ち行列から外され READY になる順序は、優先度その他の要素に関係なく、 queue 待ちに来た順序のままである。

    タイムアウトが0と指定された時は、どんな場合もスケジュールされない。

    注意:
    データの大きさ0のキューは create できない。

    QUEUE_PBOX構造体
     
    struct Queue_pbox {
    	BYTE *data;
    	BYTE4 size;
    	BYTE4 timeout;
    	OBJECT_NAME sender;
    	BYTE4 when;
    };
    #define QUEUE_PBOX struct Queue_pbox
     
     
    QUEUE_PBOX メンバーの意味
    data
    データへのポインタ
    size
    データの大きさ(in Byte)
    timeout
    timeout の時間
    sender
    queue_read() において、データの送り主の名前
    queue_write() では意味無し
    when
    queue_read() において、送り主がデータをキューイングしたときの システム時刻
    queue_write() では意味無し
     
    
    int
    queue_create(name, len, data_max_size)
    OBJECT_NAME name;
    BYTE4 len;
    BYTE4 data_max_size;
     
     
    キューを作る
    len はキューの長さ(バッファの個数)
    data_max_size はバッファ(一度に通信するデータ)の大きさ

    エラーの時は -1 が返る
    エラー原因の可能性:
    メモリが不足でオブジェクトが作れない。
    指定した名前のオブジェクトが既に存在している。
     
    
    int
    queue_delete(name)
    OBJECT_NAME name;
     
     
    キューを削除する
    queue に読み出されていないデータが存在する場合は、 削除に失敗しエラーとなる。何も変化しない
    queue 操作に来て「WAIT」状態のプロセスが存在する場合は、 削除に失敗しエラーとなる。何も変化しない

    エラーの時は -1 が返る
    エラー原因の可能性:
    指定した名前のオブジェクトが存在しない。
    queue に読み出されていないデータが存在する。
    queue 操作に来て「WAIT」状態のプロセスが存在する。
     
    
    int
    queue_read(name, pbox)
    OBJECT_NAME name;
    QUEUE_PBOX *pbox;
     
     
    キューから読み出す
    引数は QUEUE_PBOX 参照
    読み出した Byte 長が戻り値となる
    読むべきデータがなく、timeout が0でなければ、 プロセスの状態は「WAIT」になる

    タイム・アウトが起こった場合は -2 が返る。

    エラーの時は -1 が返る
    エラー原因の可能性:
    指定した名前のオブジェクトが存在しない。
     
    
    int
    queue_write(name, pbox)
    OBJECT_NAME name;
    QUEUE_PBOX *pbox;
     
     
    キューへ書き込む
    引数は QUEUE_PBOX 参照
    書き込んだ Byte 長が戻り値となる
    queueが一杯で書き込めむことができなく、 かつ timeout が0でなければ、プロセスの状態は「WAIT」になる

    タイム・アウトが起こった場合は -2 が返る

    エラーの時は -1 が返る
    エラー原因の可能性:
    指定した名前のオブジェクトが存在しない。
     
    
    int
    queue_peek(name)
    OBJECT_NAME name;
     
     
    キューの先頭にあるデータのサイズを返す

    キューにデータが全くない場合には -2 が返る

    エラーの時は -1 が返る
    エラー原因の可能性:
    指定した名前のオブジェクトが存在しない。
     
    
    int
    queue_npeek(name)
    OBJECT_NAME name;
     
     
    キューにあるデータの個数を返す
    キューにデータが全くない場合には 0 が返る

    エラーの時は -1 が返る
    エラー原因の可能性:
    指定した名前のオブジェクトが存在しない。

  5. イベント(event)

    イベントを event_wait() に来たプロセスは、待ち条件が満たされるか、 タイムアウトになるまで、「WAIT」状態にされる。

    タイムアウトが0と指定された時は、どんな場合もスケジュールされない。

    EVENT_PBOX構造体
     
    struct Event_pbox {
    	BYTE4	value;
    	BYTE4	mask;
    	BYTE4	op;
    	BYTE4	timeout;
    	BYTE4	result;
    	OBJECT_NAME sender;
    	BYTE4	when	;
    };
    #define EVENT_PBOX struct Event_pbox
     
     
    Event-PBOX構造体メンバーの意味
    1. set 時
      value
      op のオペランド
      mask
      ソースとオペランドのマスク
      op
      セットの演算
      timeout
      無意味
      result
      演算後セットした値
      sender
      無意味
      when
      無意味
      許される op
      EVOP_REPLACE
      result = (old_value & ~mask) | (value & mask)
      EVOP_AND
      result = (old_value & ~mask) | ((old_value & value) & mask)
      EVOP_OR
      result = old_value | (value & mask)
      EVOP_XOR
      result = (old_value & ~mask) | ((old_value ^ value) & mask)
      EVOP_NAND
      result = (old_value & ~mask) | (~(old_value & value) & mask)
      EVOP_NOR
      result = (old_value & ~mask) | (~(old_value | value) & mask)
      EVOP_NXOR
      result = (old_value & ~mask) | (~(old_value ^ value) & mask)
      EVOP_ANDN
      result = (old_value & ~mask) | ((~old_value & value) & mask)
    2. wait 時
      value
      wait からもどる時にイベントにセットする値
      mask
      waitのマスク・パターン
      op
      wait の演算(or/and のみ)
      timeout
      timeout の時間
      result
      戻り時の event の値
      sender
      最新のイベントの送り主の名前
      when
      最新のイベントがポストされたときのシステム時刻
      許される op
      EVCOND_AND
      mask パターンに指定した全ての bit が 1 になるまで待つ
      EVCOND_OR
      mask パターンの中のいずれかの bit が 1 になるまで待つ
    
     
    int
    event_create(name)
    OBJECT_NAME name;
     
     
    イベントを作る

    エラーの時は -1 が返る
    エラー原因の可能性:
    メモリが不足でオブジェクトが作れない。
    指定した名前のオブジェクトが既に存在している。
     
    
    int
    event_delete(name)
    OBJECT_NAME name;
     
     
    イベントを削除する
    対象のイベントに対してすでに「WAIT」状態の プロセスが存在する場合は、削除に失敗して、何も変化しない。

    エラーの時は -1 が返る
    エラー原因の可能性:
    指定した名前のオブジェクトが存在しない。
    対象のイベントに対して待ち状態のプロセスが存在する。
     
    
    int
    event_set(name, pbox)
    OBJECT_NAME name;
    EVENT_PBOX *pbox;
     
     
    イベントをセットする

    エラーの時は -1 が返る
    エラー原因の可能性:
    指定した名前のオブジェクトが存在しない。
     
    
    int
    event_wait(name, pbox)
    OBJECT_NAME name;
    EVENT_PBOX *pbox;
     
     
    イベントを待つ
    待ち条件については EVENT_PBOX 参照
    待ち条件を満たすイベントが無く、かつ timeout が0でなければ、 プロセスの状態は「WAIT」になる
    すでに、そのイベントに対して待ちに入っているプロセスがある場合には、 エラーとなる

    タイム・アウトが起こった場合は -2 が返る。

    エラーの時は -1 が返る
    エラー原因の可能性:
    指定した名前のオブジェクトが存在しない。
    既に、イベントを待っているプロセスがある。
     
    
    BYTE4
    event_get(name)
    OBJECT_NAME name;
     
     
    イベントを読み出す(影響を与えない)

    エラーの時は -1 が返る
    エラー原因の可能性:
    指定した名前のオブジェクトが存在しない。
     
    
    int
    object_join_event(obj_name, mode,  event_name, evpbox)
    OBJECT_NAME obj_name;
    int mode;
    OBJECT_NAME event_name;
    EVENT_PBOX *evpbox;
     
     
    obj_nameで示されたオブジェクトにeventで示すイベントを結び付ける。

    obj_nameで示されたオブジェクトにmodeで示された変化が生じたとき、 結び付けられたeventにevpboxの情報を使って、event_set()を行なう。

    evpboxの、op,value,maskのみが有効。

    mode :
    1. obj_nameで指定されたオブジェクトがqueue の時
      JOEV_QWRITE queueに書き込みがあった時event_set()する
      JOEV_QREAD queueから読みだしがあった時event_set()する
    2. obj_nameで指定されたオブジェクトがsemaphore の時
      JOEV_SEM_SIGNAL semaphoreにsemaphore_signal()された時event_set()する
      JOEV_SEM_WAIT semaphoreに対し誰かがsemaphore_wait()に成功時event_set()する

      エラーの時は -1 が返る
      エラー原因の可能性:
      指定した名前のオブジェクトが存在しない。

  6. セマフォ(semaphore)

    セマフォを semaphore_wait() に来たプロセスは、セマフォが得られるか、 タイムアウトになるまで、「WAIT」状態にされる。

    タイムアウトが0と指定された時は、どんな場合もスケジュールされない。

     
    
    int
    semaphore_create(name)
    OBJECT_NAME name;
     
     
    セマフォを作る

    エラーの時は -1 が返る
    エラー原因の可能性:
    メモリが不足でオブジェクトが作れない。
    指定した名前のオブジェクトが既に存在している。
     
    
    int
    semaphore_delete(name)
    OBJECT_NAME name;
     
     
    セマフォを削除する
    対象のセマフォに対してすでに「WAIT」状態の プロセスが存在する場合は、削除に失敗して、何も変化しない。

    エラーの時は -1 が返る
    エラー原因の可能性:
    指定した名前のオブジェクトが存在しない。
    対象のセマフォに対して待ち状態のプロセスが存在する。
     
    
    int
    semaphore_signal(name)
    OBJECT_NAME name;
     
     
    セマフォを解放する(clear)

    エラーの時は -1 が返る
    エラー原因の可能性:
    指定した名前のオブジェクトが存在しない。
    指定したセマフォは自プロセスが現在得ているセマフォではない。
     
    
    int
    semaphore_wait(name, timeout,pbox)
    OBJECT_NAME name;
    BYTE4 timeout; 
    SEMAPHORE_PBOX *pbox;
     
     
    セマフォを得る(test & set)
    セマフォを得ることができず、かつ timeout が0でなければ、 プロセスの状態は「WAIT」になる

    タイム・アウトが起こった場合は -2 が返る。
    タイム・アウトの時には、以下のように、PBOXの中に興味深い情報が得られる
    なお、pbox==NULLの時は、pboxに対する操作は行われない

    エラーの時は -1 が返る
    エラー原因の可能性:
    指定した名前のオブジェクトが存在しない。

    SEMAPHORE_PBOX構造体
     
    struct Semaphore_pbox {
    	OBJECT_NAME owner;
    	BYTE4	when	;
    };
    #define SEMAPHORE_PBOX struct Semaphore_pbox
     
     
    SEMAPHORE_PBOX構造体メンバーの意味
    owner
    現在セマフォを得ているプロセスの名前
    when
    現在のownerがセマフォを得たときのシステム時刻

  7. 共有メモリ(Common Memory)

    通常のプロセスはメモリ空間が分離されているため、 共有メモリ・プリミティブを使用しなければ、共有メモリを実現できない。

     
    
    unsigned int
    memory_page_size()
     
     
    システムのメモリ管理のページ・サイズを問い合わせる。
    返り値の単位はByte。
    *SH3版では使用できません。同等な機能としてmemory_page_size1()を使用します*
     
    
    int
    memory_common_create(name, n)
    OBJECT_NAME name;
    unsigned int n;
     
     
    n Bytesの共有メモリを、オブジェクト名nameで生成する。
    サイズnはページサイズに合わせて切り上げられる。

    エラーの時は -1 が返る
    エラー原因の可能性:
    メモリが不足でオブジェクトが作れない。
    指定した名前のオブジェクトが既に存在している。
     
    
    int
    memory_common_delete(name)
    OBJECT_NAME name;
     
     
    共有メモリを削除する

    エラーの時は -1 が返る
    エラー原因の可能性:
    指定した名前のオブジェクトが存在しない。
     
    
    unsigned int
    memory_common_size(name)
    OBJECT_NAME name;
     
     
    共有メモリのサイズを問い合わせる。
    返り値の単位はByte。
    サイズnはページサイズに合わせて切り上げられているであろう。

    エラーの時は -1 が返る
    エラー原因の可能性:
    指定した名前のオブジェクトが存在しない。
     
    
    void *
    memory_window_create(name, n)
    OBJECT_NAME name;
    unsigned int n;
     
     
    プロセスのメモリ空間中に、n Bytesのメモリ・ウインドウを、 オブジェクト名nameで生成する。
    サイズnはページサイズに合わせて切り上げられる。
    返り値はウインドウの先頭番地。

    エラーの時は -1 が返る
    エラー原因の可能性:
    メモリが不足でオブジェクトが作れない。
    指定した名前のオブジェクトが既に存在している。
    プロセスのページ・テーブルが不足している。
     
    
    int
    memory_window_delete(name)
    OBJECT_NAME name;
     
     
    メモリ・ウインドウを削除する

    エラーの時は -1 が返る
    エラー原因の可能性:
    指定した名前のオブジェクトが存在しない。
     
    
    unsigned int
    memory_window_size(name)
    OBJECT_NAME name;
     
     
    メモリ・ウインドウのサイズを問い合わせる。
    返り値の単位はByte。
    サイズnはページサイズに合わせて切り上げられているであろう。

    エラーの時は -1 が返る
    エラー原因の可能性:
    指定した名前のオブジェクトが存在しない。
     
    
    int
    memory_common_map_window(cm_name, win_name)
    OBJECT_NAME cm_name, win_name;
     
     
    cm_nameで指定される共有メモリを、win_nameのメモリ・ウインドウに マップする。
    共有メモリのサイズ >= ウインドウのサイズ でなければエラーとなる。

    エラーの時は -1 が返る
    エラー原因の可能性:
    指定した名前のオブジェクトが存在しない。
    共有メモリのサイズ >= ウインドウのサイズではない。

  8. デバッグ(debugging)
     
    
    void
    dbg_putstr(s)
    char *s;
     
     
    デバッグポートへ puts する
     
    
    void
    dbg_write(c)
    BYTE4 c;
     
     
    デバッグポートへ putc する
     
    
    void
    object_dbgdump(name)
    OBJECT_NAME name;
     
     
    name で示されたオブジェクトをデバッグポートへダンプする

III. ライブラリ
  1. 名前(name)

    オブジェクトの名前に使用できる文字セットは、XTALの実装に依存する。 また、オブジェクト名の表現は、XTALの実装に依存する。

    オブジェクト名<->文字列の変換には、必ず、str_to_name(),name_to_str()を 使用しなければ、アプリケーションのソース・コード互換性が保証されない。

    XTALのいかなるバージョンでも、少なくとも、 以下の文字がオブジェクト名に使用できる。

     
    {
            '_' , 'A' , 'B' , 'C' ,
            'D' , 'E' , 'F' , 'G' ,
            'H' , 'I' , 'J' , 'K' ,
            'L' , 'M' , 'N' , 'O' ,
            'P' , 'Q' , 'R' , 'S' ,
            'T' , 'U' , 'V' , 'W' ,
            'X' , 'Y' , 'Z' , '!' ,
            '+' , '-' , '$' , '%'
    };
     
     
     
    
    OBJECT_NAME
    str_to_name(s)
    char *s;
     
     
    sで与えられた文字列を名前に変換
     
    
    void
    name_to_str(s,name)
    char *s;
    OBJECT_NAME name;
     
     
    nameで与えられた名前を文字列に変換してsに置く