source: TECS-SimpleSample/tags/SimpleSample-20120707/README.txt@ 164

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 インタープリターは不要です。
tecs_package は、こちらからダウンロードできます。
  http://www.toppers.jp/download.cgi/tecs_package-20120608.tar.gz

   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 等のセルタイプを用意していますが、
テストドライバーまたはスタブであり、ほとんど機能は備わっていません。