source: asp3_tinet_ecnl_rx/trunk/asp3_dcre/tecsgen/tecs/mruby/mrubyBridge.txt@ 374

Last change on this file since 374 was 374, checked in by coas-nagasima, 5 years ago

mbed関連を更新
シリアルドライバをmbedのHALを使うよう変更
ファイルディスクリプタの処理を更新
  • Property svn:eol-style set to native
  • Property svn:mime-type set to text/plain;charset=UTF-8
File size: 16.9 KB
Line 
1MrubyBridgePlugin に関するメモ
2 2012年11月 7日　初版作成
3 2013年 5月26日　見直し
4 大山　博司
5
6【概要】
7
8MrubyBridgePlugin は、TECS CDL の signature 記述に基づき、mruby と TECS
9コンポーネントをブリッジする、mruby の C 言語実装クラスであり TECS のセ
10ルタイプとなるコンポーネントを生成する、TECS のシグニチャプラグインであ
11る。
12
13【構造】
14
15 +--------------------------+ +-------------------+
16 | (ブリッジセル) | | (目的セル) |
17 | | | |
18mruby | nMruby::tsSignatureBridge| sSignature | tTargetCelltype |
19 - - - > | BridgeCell |--------------|> TargetCell |
20 | |cTECS eTest| |
21 | mruby クラス： | | |
22 | TECS::TSignatureBridge | | |
23 +--------------------------+ +-------------------+
24
25MrubyBridgePlugin は、mruby から TECS へブリッジをするセルタイプを生成
26する。mruby=>TECS をブリッジするセルは、そのセルタイプのセルとして、プ
27ラグインの利用者が CDL 内に設置し、mruby から操作したいセル、すなわち
28目的セルに結合する。
29
30このセルタイプは、mruby のクラスの定義を行い、ブリッジセルを mruby の
31インスタンスとして取り扱えるようにし、mruby のインスタンスメソッドの呼
32び出しに応じて、目的セルの受け口関数を呼び出す働きを持つ。
33
34【簡単な使用例】
35
36簡単な使用例は、SimpleSample.cdl および SimpleSample.rb にある。
37MrubyBrigePlugin はシグニチャプラグインであり、シグニチャプラグインの
38使用方法を理解していれば、これらのソースファイルのコメントを参照するこ
39とで、MrubyBrigePlugin の大よその使い方は理解できるはずである。
40以下の方法で、ビルドおよび実行できる。
41
42 % make # mruby 本体のビルド (.a を作成)
43 % cd MrubyBridge # MrubyBridge へ移動
44 % make # ビルド
45 % ./mruby-Sample SimpleSample.rb # 実行
46
47【Makefile の構成】
48
49tecsgen により生成される gen/Makefile.templ に対し、以下の変更を加える必要があ
50る。
51
52・gen/Makefile.temp は、一つ上のディレクトリへ Makefile という名前で置
53 けば、cygwin などの POSIX 環境で試験実行する場合には、無調整で使用で
54 きるように生成される(ただし gnu make を使用する)
55・tSysLog を使う場合、リロケータブルオブジェクトを追加 (下行参照)
56 OTHER_OBJS = $(_TECS_OBJ_DIR)vasyslog.o
57
58【データ型】
59
60MrubyBridgePlugin は、以下の TECS の型を扱うことができる (制限される)。
61この制限は、MrubyBridgePlugin を適用しようとするシグニチャに対するものであり、
62それ以外へ制限がおよぶものではない。
63
64 スカラー型 bool_t, char_t, intN_t, double64_t, float32_t
65 (N=8,16,32,64)
66 int, short, long, char (TECS 非推奨の型)
67
68 ポインタ型 bool_t*, char_t*, intN_t*, double64_t*, float32_t*
69 int*, short*, long*, char*
70 構造体型へのポインタ（構造体型と同じ制限あり）
71
72 これらは、ポインタの指している先の値を扱うためのも
73 のである。ポインタ値(アドレス)を渡したい場合には、
74 これらを使用できない。代わりに intptr_t, uintptr_t
75 を使用する。
76
77 size_is, string 指定子あり/なしのいずれも扱える。
78 ただし構造体型へのポインタに size_is 指定されたも
79 のは扱えない。(仕様書に明言されていないが構造体ポ
80 インタの string は、元々サポートされない)
81
82 string の長さ指定がない場合、in 引数に対してのみ用
83 いることができる。
84
85 構造体型 メンバは、スカラー型でなくてはならない
86
87 typedef型 上記のスカラー型、構造体型、ポインタ型の typedef
88 された型を扱うことができる。元の型として扱われる。
89 このためポインタ型や構造体型の場合、元の型名により
90 これらを扱うための mruby クラスを指定する。
91
92【対応する mruby の型(クラス)】
93
94 bool_t true または false。
95 mruby で false と見なされるもの(false または nil)
96 を C の false として扱う。mruby で false と見なさ
97 れないものを C の true として扱う。整数値 0 は、
98 mruby では false とは見なされない。
99 char_t FIXNUM (値は 0..255)
100 schar_t FIXNUM (値は -128..127)
101 uchar_t FIXNUM (値は 0..255)
102 intN_t FIXNUM
103 uintN_t FIXNUM
104 double64_t FLOAT (mruby の FLOAT が double か float かは実装
105 による)
106 float32_t FLOAT
107 int FIXNUM
108 short FIXNUM
109 long FIXNUM
110 char FIXNUM (char_t と同じ)
111
112・TECS 専用のクラスを用いるもの
113
114 bool_t* TECS::BoolPointer
115 char_t* TECS::CharPointer
116 uchar_t* TECS::UCharPointer
117 schar_t* TECS::SCharPointer
118 intN_t* TECS::IntNPointer N:8,16,32,64
119 uintN_t* TECS::UIntNPointer N:8,16,32,64
120 float32_t* TECS::Float32Pointer
121 double64_t* TECS::Double64Pointer
122 int* TECS::IntPointer
123 short* TECS::ShortPointer
124 long* TECS::LongPointer
125 char* TECS::CharPointer (char_t* と同じ)
126
127 struct TAG TECS:TECSStructTAG
128 struct TAG* TECS:TECSStructTAG
129 TAG の部分は、構造体のタグ名に置き換える。関数への
130 引数として、構造体を渡すか、構造体へのポインタを渡
131 すかは、プラグインが自動で判定する。TAG 名を付けて
132 いない構造体を扱うことはできない。typedef した名前
133 で構造体を扱うことはできない。
134
135・その他
136
137 void * は扱えない
138 intptr_t は、通常 stdint.h で typedef されているが、元の型として扱う
139
140プラグイン引数として ignoreUnsigned=true を指定すると、無符号整数型へ
141のポインタ型を有符号整数型のポインタ型として扱う（値の範囲チェックを含
142む）。ポインタを扱うクラスのメモリ使用量を抑えること、有符号、無符号の
143使い分けをルーズにすることができる。
144
145ビルド時のオプション (C 言語のマクロ定義) TECS_NO_VAL_CHECK を指定する
146ことで、値の範囲チェックを行わないようにすることができる。
147
148【関数名】
149
150・関数名に関数する制限
151
152 関数名 initialize は ruby で既定のメソッド名と重複するため、initialize_cell
153 に置換される。
154
155 initialize と initialize_cell の両方が signature 内に存在する場合、エラーと
156 なる。エラーを解消するには、少なくとも一方の名前を変更する必要がある。
157
158【戻り値】
159
160戻り値で扱えるのは、以下の型に限られる。
161
162 void, bool_t, char_t, intN_t, float32_t, double64_t
163 int, short, long, char
164 元の型が、これらである typedef された型
165
166【引数】
167
168・順序の通り対応する mruby の型（クラス）の値を引数として渡す
169・指定可能な基本指定子 in, inout, out (send/receive は不可)
170・例外の発生
171 ・整数の値が、引数の型の範囲を超えている場合、例外を発生する。
172 無符号型の場合、負の値を取ることはできない。ただし、mrb_int と同じ
173 またはそれ以上のサイズの場合には、負の値が指定されても例外とはしな
174 い。さもないと最上位ビットが 1 の値を入力できないため。
175 char_t (char) は無符号と見なされる。
176 なお uintptr_t に 0x80000000 にを渡す際に RangeError 例外が発生す
177 るが、これは mruby によるものであり、TECS による制限ではない
178 ・ポインタ型や構造体型に対応する mruby の型(クラス) と一致しない
179 ・size_is, string のサイズが小さい
180
181【参考】
182
183 TECSPointer.txt
184
185 以下の mruby クラス、すなわち TECS のポインタ値を扱うためのクラスに
186 ついての説明。
187　これらのクラスは必要に応じて生成される。引数として使用されていないク
188 ラスは生成されない。
189
190 TECS::Int8Pointer, TECS::Int16Pointer, TECS::Int32Pointer
191 TECS::Int64Pointer, TECS::UInt64Pointer
192 TECS::UInt8Pointer, TECS::UInt16Pointer, TECS::UInt32Pointer
193 TECS::CharPointer, TECS::SCharPointer, TECS::UCharPointer
194 TECS::IntPointer, TECS::ShortPointer, TECS::LongPointer
195 TECS::UIntPointer, TECS::UShortPointer, TECS::ULongPointer
196 TECS::BoolPointer, TECS::Float32Pointer, TECS::Double64Pointer
197
198 TECSStruct.txt
199
200 以下の mruby クラス、すなわち TECS の構造体（ポインタ）値を扱うため
201 のクラスについての説明。
202
203 TECS::StructTAG
204
205【TECS CDLによる記述】
206
207 ブリッジプラグインにより、ブリッジセルタイプが自動生成される。
208 ブリッジセルは、CDL に記述して設置する必要がある
209
210・ブリッジプラグインの呼出し
211
212mruby=>TECS ブリッジプラグインは、シグニチャプラグインである。CDL 上の以下のよ
213うな記述により、mruby=>TECS ブリッジプラグインを呼び出す。
214
215 ex)
216 generate( MrubyBridgePlugin, sSignature, "" );
217
218 シグニチャ sSignature は、この記述よりも前に定義されていなくてはならない。
219 この generate の記述により、次のようなブリッジセルタイプが生成される。
220
221generate の第3引数は、プラグイン引数（オプション）である。
222
223 ignoreUnsigned true を指定すると無符号整数へのポインタ型に有符号のポ
224 インタクラスを使用する（メモリを節約できる）
225 デフォルトは false である。
226 include ブリッジに含める関数を指定する。exclude と同時指定不可。
227 exclude ブリッジに含める関数を指定する。include と同時指定不可。
228
229 ex)
230 generate( MrubyBridgePlugin, sSignature, "exclude=fun99" );
231
232多くの関数を指定する場合、以下のように、分割した文字列の連接として師定
233することができます。
234
235 ex)
236 generate( MrubyBridgePlugin, sSignature,
237 "ignoreUnsigned=true, "
238 "include='func1,func2', "
239 "include='func3,func4', "
240 );
241
242・ブリッジセルタイプ
243
244 ブリッジセルタイプは、ネームスペース nMruby の下に作られる。ブリッジ
245セルタイプの名前は、シグニチャ名に 't' を前置きしたものである。以下は、
246ブリッジプラグインにより自動生成されるセルタイプのコードの例である。シ
247グニチャ sSignature に対するブリッジセルタイプ名は tsSignature であり、
248呼び口cTECS を持つ。
249
250 ex) 自動生成される CDL コード（内部で生成され、解釈される）
251
252 namespace nMruby {
253 celltype SSignature{
254 call sSignature cTECS;
255 };
256 };
257
258・ブリッジセルの設置
259
260 ブリッジセルは、ブリッジセルタイプのセルとして生成する。ブリッジセル
261 の設置は CDL の記述者が行うものである。ブリッジセルの呼び口 cTECS を
262 mRuby から呼び出したいセルへ結合する。
263
264 ex) ブリッジセルを設置する CDL 記述
265
266 cell nMruby::tsSignature BridgeCell {
267 cTECS = Cell.eEnt;
268 };
269
270 ex) ブリッジセルを設置する CDL 記述(VM 名指定あり)
271
272 cell nMruby::tsSignature BridgeCell {
273 cTECS = Cell.eEnt;
274 VMname = "VM2";
275 };
276
277 VMname は mruby VM のセルの名前の指定である。VMname を指定しない場合、
278 "VM" が仮定される。VMname は、実際には、VM_TECSInitializer などのよ
279 うに、ブリッジを登録するセルの、セル名に用いられる。tecsgen 実行時に
280 以下のようなメッセージが出力される。受け口
281 VM_TECSInitializer.eInitialize へ VM の初期化用呼び口から結合する。
282
283 MrubyBridgePlugin: join your VMs cInitialize to VM_TECSInitializer.eInitialize
284
285【mruby コード】
286
287 ブリッジプラグインが適用されたシグニチャに対応する mruby クラスが生成
288 される。これをブリッジクラスと呼ぶ。
289 ブリッジクラスを通してセルの受け口関数を呼び出すことができる。
290
291・ブリッジクラス
292
293 ブリッジクラスは、モジュール TECS の下に作成される。ブリッジクラスの
294 名前は、シグニチャ名に 'T' を前置きしたものとなる。
295
296 ex) TECS::TsSignature
297
298・ブリッジのインスタンス
299
300 ブリッジクラスにて、ブリッジセル名を引数として new することで、ブリッ
301 ジクラスのインスタンスが生成される。ブリッジクラスのインスタンスのこ
302 とを、短かくブリッジのインスンタンスとも呼ぶ。ブリッジのインスタンス
303 は、ブリッジセルへのポインタ情報を保持するだけである。同一のブリッジ
304 のインスタンスは何度でも生成することができる。
305
306 ex) brdige = TECS::TsSignature.new( "CellName" )
307
308【残課題】
309
310[済] 整数型の unsigned の扱い
311 キャストをしているので、コンパイルは警告なく通る。
312 値の範囲チェックと整合していない。
313 以下を新たに設けるか。
314 UInt8Pointer, UInt16Pointer, UInt32Pointer, UInt64Pointer
315 UIntPointer, UShortPointer, ULongPointer, UCharPointer, SCharPointer,
316
317[済] 値の範囲のチェック
318 TECSPointer, TECSStruct では整数値を設定する際に、範囲チェックがある。
319 メソッドへの直接の引数はチェックされない。
320
321[済] 現状の so としての実装はおかしい
322 静的に mruby の本体が結合されている。
323
324[済] ポインタ型を扱うクラスが多すぎる
325 使用するクラスだけロードされ、初期化される仕組みが欲しい。
326
327・以下の方法でブリッジを割り付けているが、
328 bridge = TsSample.new( "SimpleBridge" )
329　以下のように、定数として扱うことができる方がスマートである。
330 bridge = TECS::SimpleBridge
331 (現状の方が、ブリッジのセルタイプがわかる点が優れている)
332 ⇒ もし定数として扱うとして、割付けを C で行うか ruby コードで行うか
333 の違いでしかない。以下にあるラッパークラスにより定数の初期化を行
334 えばよい。
335 ⇒ 定数として扱うと、オブジェクトが最初から最後まで消えないという問
336 題がある(それでも少量であるが)
337
338・上記に関連して、VM が異なる場合に、他の VM に割り付けたブリッジ名が
339 見えてしまう。アクセス制限が十分でない。
340 ブリッジ名のアクセス制限を実現するには、VM を識別する情報が必要にな
341 る。mrb_state に p_cellcb を加える方法、mrb_state自身で区別する方法
342 が考えられる。要検討。
343 なお、セルタイプ単位でのアクセス制 限はできている(てきていないのは、
344 同じセルタイプで複数のブリッジセルがある場合に、ブリッジ名のアクセス
345 制限)。
346
347・typedef された型名でアクセスできると便利である
348 TECSPointer や TECSStruct のクラスに対する alias により、別名として
349 アクセスできるとよい。
350 ⇒ とりあえず、MrubyBridgePlugin のメッセージとしてわかるようにした。
351
352・send/receive への対応
353 mruby と共通のアロケータを指定可能とする (アロケータコンバータプラグインを新規に設けては?)
354
355・構造体メンバーの型制限の緩和
356 strign or size_is 指定された char* など
357
358・ruby らしいプログラムから mruby ⇒ TECS ブリッジのクラスへの自動変換するラッパークラスの生成
359 (ruby's Array => TECS::Pointer, ruby's Struct => TECS::StructTAG)
360
361[済]ブリッジクラスの new でセルが見つからなかった場合、ruby 例外を発生させる。
362 これを free する段階で SEGV が発生するため DATA_SET を早めに行うように変更。
363 なお、各メソッドの関数で DATA_PTR が null かどうかをチェックしないが、
364 例外が発生したことにより不完全なブリッジは変数に記憶されない（はず）
365 ため、問題ない。
366
Note: See TracBrowser for help on using the repository browser.