source: TECS-SimpleSample/trunk/README.txt@ 38

TECS の Simple な Sample

                                                   2012年 7月6日
                                                   大山 博司

【ライセンス】

本ソフトウェアは、簡単なサンプルであり、個々のファイルにはライセンス条
件を記載していませんが、TOPPERS ライセンスに準じます。License.txt を参
照してください。

【概要】

TECS のもっとも簡単なアプリケーションサンプルです。 exerb 版の TECS ジェ
ネレータとcygwin だけで動作させることができますので、手軽に TECS を学ぶ
ことができます。cygwin 上では exerb 版で動作しますので、Ruby や racc の
インストールする必要がありません。
Linux などの POSIX 環境でも動作するはずです。この場合は、Ruby インタプ
リタが必要となります。動作環境の項を参照してください。

【サンプルプログラムの概要】

4 つのプログラムの例が同梱されています。

これらには、共通した tSimple, tSample というセルタイプが用いられていま
す。これらのセルタイプは、すべての例で同じです。
この例では Makefile の簡単さ優先して、tSimple.c, tSample.c には 4 つの
コピーがありますが、diff を取ってみれば、同じであることがわかります。こ
れはソフトウェア部品にまったく手を加えることなく、種々のバリエーション
が可能になることを示しています。

・SimpleSample … 直接結合版

    最もシンプルで、最も入門的な例です。
    tSimple と tSample の 2 つのセルタイプを定義しています。
    それぞれのセルタイプに属するセル Simple から Sample へ、シグニチャ
    sSample として定義された関数群を介して呼び出すことができます。コン
    ポーネント図やもう少し詳しい説明が SimpleSample.cdl に記述されてい
    ますので参照してください。

    なお、タスクセルタイプ tTask は、cygwin (POSIX) 環境用に予め用意さ
    れたものを用いています(後述の「cygwin_kernel について」を参照してく
    ださい）。

・SimpleSampleTrace … 直接結合の TracePlugin あり版

    上記 SimpleSample に TracePlugin を適用した例です。
        実行に伴って、関数の呼び出しに関するトレースが出力されます。
    Simple と Sample の間に TracePlugin によって自動生成されたセルが挿
    入されます。このセルにより、トレースの出力がなされます。

    このディレクトリ下の SimpleSample.cdl を参照すると、TracePlugin の
    使い方がわかります。

    挿入されたセルのセルタイプは tTracePlugin_sSample という名前になり
    ます。gen ディレクトリの下の tTracePlugin_sSample.c というファイル
    を見ると TracePlugin により生成された sSample の関数の呼び出しのト
    レースを出力するコードがあります。

    以下の 2 つの例は、SimpleSample と言っても、だいぶ複雑になります。
    初めて TECS に触れてみる方は、【動作環境】まで読み飛ばしていただい
    た方がよいでしょう。

・SimpleSampleTransparentRPC … Transparent RPC 版

    上記 SimpleSample に RPCPlugin を適用して、Transparent RPC を実現す
    る例です。

    RPC とは、遠隔手続き呼び出し (Remote Procedure Call) のことで、呼び
    元のセルと呼び先のセルが、異なるタスク上で動作します。TECS には
    Transparent RPC と Opaque RPC の2種類がありますが、Transparent RPC
    は、同じ RTOS 上の別のタスクで、それぞれのセルを動作させるのに向い
    ています。

    この例では Simple と Sample は異なるタスクで動作します。Sample が動
    作するタスクのセルは cdl 上に現れていません。RPCPlugin により自動で
    生成されます。RPCPlugin は、その他にも tDataqueue を使用する通信チャ
    ンネルや、マーシャラ、アンマーシャラも自動生成してくれます。

    マーシャラ、アンマーシャラは、タスク間の通信用のパケットの生成と分
    解を行うもので、RPCPlugin は、それらのセルタイプとセルの両方を生成
    します。マーシャラ、アンマーシャラのセルタイプは、対象となるシグニ
    チャごとに相違するため、いわばオーダーメードの通信プログラムになり
    ます。RPCPlugin は C 言語のプログラムも含めて生成します。

    Transparent RPC は、メモリ対称なマルチプロセッサ間での通信に応用で
    きます (しかし、現時点で TOPPERS/FMP に適用するサンプルは、ありませ
    ん。近い将来実現されるでしょう)。

    なお Transparet (透明) と Opaque (不透明) の違いは、メモリ透過性が
    あるかどうかです。Transparent RPC ではメモリ透過性があり、ポインタ
    を渡せば、渡された側はポインタを通して本来の引数にアクセスすること
    ができます。一方、Opaque RPC ではメモリ透過性がなく、ポインタを渡さ
    れても、本来の引数にアクセスすることができません。Opaque RPC では、
    ポインタの指している先の本来の引数を渡す必要があります。その分
    Opaque RPC のマーシャラ、アンマーシャラは複雑になります。

・SimpleSampleOpaqueRPC … Opaque RPC 版

    上記 SimpleSample に OpaqueRPCPlugin を適用して、Opaque RPC を実現
    します。

    SimpleSampleOpaqueRPC の cdl を見ると、上記の 3 つの例に比べて、少
    し雰囲気が異なっていることが分かります。

    まず、コンポーネント図上で TaskMain が加えられているのが相違します。
    これは、呼び元の側で通信チャンネルをオープンするために追加されてい
    ます。

    cdl の内容としては、Simple と Sample が異なるリージョン (region) に
    属している点が、これまでと大きく異なります。region はセルの配置を制
    御するのに用いられます。と同時に、セルの名前衝突の回避にも用いられ
    ます。

    region rSimple と rSample は、独立したリンク単位 (linkunit) である
    と指定されています。実際にこのサンプルをビルドすると、2 つの exe が
    生成されます。2 つのセル Simple と Sample は、それぞれの exe に分か
    れて動作します。

    この例では、tSocket を使って 2 つのセル間 (つまりは exe 間) をつな
    ぎます。OpaqueRPCPlugin は、コンポーネント図上に現れていない要素を、
    すべて生成します。基本的には Transparent RPC の場合と同じですが、ポ
    インタをそのまま渡すことができないため、マーシャラやアンマーシャラ
    も異なるものになります。

    この事例では、TECS RPC のエラー回復モデルを組み込んでいません。エラー
    回復モデルは、実行の途中で通信エラーが発生した場合などに、適切な振
    る舞いをさせるためのものです。tecsgen の test/opaqueRPC のサンプル
    コードは、エラー回復モデルを含んでいます。
    Opaque RPC に用いられる通信チャンネルは ethernet など、CPU やメモリ
    などの信頼性に比べ、信頼性が劣ります。このため、実用的なアプリケー
    ションとしては、通信途中でエラーが発生した場合、どのように対処する
    か作りこんでおく必要があります。

    この Simple Sample で利用する tecs_package にも Opaque RPC に関する
    情報があります。これは TINET を用い skyeye 上で動作するように組み込
    まれています。

【動作環境】

cygwin 上でビルドし動作します。2012.6.2 に発行された tecs_package
(TECS ジェネレータ V1.1.0.4 を同梱) を用いてください。exerb 版を用いる
ようになっているため、Ruby インタープリターは不要です。

   exerb 版とは Ruby インタプリタと TECS ジェネレータが一体の exe 化さ
   れたもので、Ruby インタプリタのインストールを必要としません。ただし
   exerb 版は Windows 上でしか動作しません。

以下の環境で動作確認しています。
  ・cygwin 1.7.15 
  ・gcc  4.5.3
  ・Ruby  1.8.7p358

Linux などの POSIX 環境でも動作させることができます。その場合 Makefile 
の TECSGEN_EXE を tecsgen.exe から tecsgen に変更してください。Ruby
1.8 がインストールされている必要があります。Ruby 1.9 には対応しません。

【準備】

1) ファイルの展開

 tecs_package ディレクトリの直下 asp+tecs, tecsgen の並びに 
 SimpleSample を置いてください。exerb 版を用いる都合上、tecsgen コマン
 ド引数に与えるパスは、すべて相対パスで指定しています。

  tecs_package-+- asp+tecs
               |
               +- tecsgen
               |
               +- SimpleSample -+- SimpleSample
                     (※)       |
                                +- SimpleSampleTrace
                                |
                                +- SimpleSampleTransparentRPC
                                |
                                +- SimpleSampleOpaqueRPC

※ svn の trunk のディレクトリの位置に対応します。名前は変更しても構いません。

2) パスの設定

 cygwin コンソールを開き、以下のような方法で set_env.sh 内の PATH 等を
 取り込みます。

  % cd tecs_package/tecsgen
  % source set_env.sh

  exerb 版を使用するため、TECS ジェネレータのビルドは不要です。

【ビルドと実行】

3) 直接結合版のビルドと実行

・ビルド

  % cd tecs_package/SimpleSample/SimpleSample
  % make tecs
  % make all

・実行

  % ./SimpleSample.exe

4) 直接結合の TracePlugin あり版のビルドと実行

  % cd tecs_package/SimpleSample/SimpleSampleTrace
  % make tecs
  % make all

・実行

  % ./SimpleSample.exe

5) transparent RPC 版のビルドと実行

・ビルド

  % cd tecs_package/SimpleSample/SimpleSampleTransparentRPC
  % make tecs
  % make all

・実行

  % ./SimpleSample.exe

  実行後、サーバー側のタスクが終了しないため、プロセスが終了しません。
  ctrl-C で終了させてください。
  わかりにくいですが、Simple と Sample は異なるタスクで実行されています。

6) opaque RPC 版のビルドと実行

・ビルド

  % cd tecs_package/SimpleSample/SimpleSampleOpaqueRPC
  % make tecs
  % make all

・実行

 2つの cygwin コンソールを使います。
 1 つ目のコンソールでサーバー側を起動します。

  % ./rSample/SimpleSample-rSample.exe

 次に 2 つ目のコンソールでクライアント側を起動します。

  % cd tecs_package/SimpleSample/SimpleSampleOpaqueRPC
  % ./rSimple/SimpleSample-rSimple.exe

 終了後、サーバー側のプロセスは transparent RPC と同様終了しないため、
 ctrl-C で終了させてください。
 Sample(サーバー) のメッセージが Simple(クライアント) 側で出力されます
 が、これは out 引数で返されたものを表示しているためです。

【あさらい】

ポイントは、各 CDL 内の tSimple, tSample の定義、セルタイプコード 
tSimple.c, tSample.c は、まったく無変更で 4 つのパターンに対応している
ことです。再利用が図られることがわかります。

【次のステップ】

うまく動いたら、次のステップとしてやってみることを記します。

 ・シグニチャ sSample に関数を追加する

    まずは、この手順を理解しましょう。.c にも関数を加える必要があります。
    以下のコマンドで追加された関数のテンプレートをマージすることができ
    ます。

       % tecsmerge gen/tSample_template.c src

    tSimple.c には、追加された関数を呼び出すプログラムを追加する必要が
    あります。以下を実行しても関数を呼び出すプログラムは追加されません
    が、冒頭のコメント部に呼び口関数が追加されます。

       % tecsmerge gen/tSimple_template.c src

・シグニチャと、それを受け口に持つセルタイプを定義して Sample から結合
  してみる
    セルタイプコード (.c) も作成する必要があります。テンプレートコード
    (gen の下の  _templete.c) をベースにすることができます。

【cygwin_kernel について】

cygwin 上で pthread を用いた tTask 等のセルタイプを用意していますが、
テストドライバーまたはスタブであり、ほとんど機能は備わっていません。