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