porting mruby on TOPPERS BASE PLATFORM using TECS
TECS を使って mruby を TOPPERS BASE PLATFORM に移植します。
TECS を使うと、驚くほど簡単に移植できます。 コンフィグレーションも簡単です。
以下のターゲットデバイスを使用します。
SMT32F746 Discovery Kit
TOPPERS BASE PLATFORM は、各種の ST 社のボードに対応しており、これ以外のデバイスでも、同様にできるはずです。
ROM 256KB, RAM 256KB 以上が必要です。RAM 実行する場合は、RAM 512KB 以上が必要です。
mruby VM の実装、tSampleMruby の実装までは、TOPPERS BASE PLATFORM 以外の TOPPERS カーネルにも同様に実装できます。
以下は、mruby+TECS on TOPPERS BASE PLATFORM を構成するモジュールです。 このリポジトリに置かれています。
- TOPPERS/ASP ターゲット非依存部 (asp-1.9.3.tar.gz)
- TOPPERS/ASP ターゲット依存部 (asp_arch_arm_m7_gcc-1.9.5.tar.gz)
- TOPPERS BASE PLAFORM(ST) (asp_baseplatformv1.3.0_052018.tar.gz)
- mruby 3.0.0 (mruby-3.0.0.tar.gz)
- TLSFメモリアロケータ (TLSF-2.4.6)
- TECS ジェネレータ (tecsgen-1.7.0.tgz)
Windows 10 でビルドする場合に必要となるツール類です。
Linux や MacOS でビルドする場合には、それらようの環境に合わせて、適切なものをご準備ください。
- cygwin
- arm 用 gcc コンパイラ (gcc-arm-none-eabi-9-2020-q2-update-win32.exe)
- ST-LINK Utility
- Tera Term (teraterm-4.106)
- TOPPERS新世代カーネル用コンフィグレータ (cfg-1.9.6)
cygwin には、gcc (レジデント用)、Ruby (V3.x 未対応) が必要ですので、setup からインストールしてください。
使用モジュールは、本リポジトリにすべて展開済みですので、チェックアウトして、そのままビルドできます。
asp-1.9.3.tar.gz, asp_arch_arm_m7_gcc-1.9.5.tar.gz, asp_baseplatformv1.3.0_052018.tar.gz, mruby-3.0.0.tar.gz は、開発用ルートディレクトリで、そのまま解凍します。
TLSF-2.4.6.tbz2 は、asp ディレクトリ下で解凍してください。
tecsgen-1.7.0.tgz は、解凍後 tecsgen-1.7.0/tecsgen ディレクトリを asp ディレクトリ下へ移動してください。移動後、残ったものは削除してください。
使用モジュールに含めていませんでしたが、後述のとおりTECS 簡易パッケージから tecs_kernel ディレクトリを持ってきています。さらに syssvc ディレクトリから必要なファイルを抜き出して持ってきています。
TOPPERS BASE PLATFORM で使用している TOPPERS/ASP カーネルは、公式リリースとしては TECS に対応していません。
TECS WG から TECS 簡易パッケージ として公開されていますが、メンテナンスされていません (TOPPERS/ASP3, HRP3 用であれば、標準に組み込まれていて、メンテナンスされています)。
このため、TOPPERS/ASP を TECS 化する必要があります。
以下の方針で TECS 化します。
-
kernel.cdl および、そこに定義されているセルタイプのセルタイプコードは、TECS 簡易パッケージに含まれているものを使用する
-
tSerial, tSysLog は、標準の TOPPERS/ASP のラッパーとして実装する (TECS簡易パッケージに含まれているものは TOPPERS/ASP3 と同様に、フルに TECS 化されている)
余談ですが TOPPERS/ASP簡易パッケージ、 TOPPERS/ASP3 で tSysLog がフルに TECS 化されているのは、ターゲットによりカスタマイズされることが多いため、可変点として、その部分を切り出してコンポーネント化がなされました。
以下の4つについて Step by step で進めていきます。
- 非 TECS 版 sample1 のビルド (a_sample1)
- 非 TECS 版 sample1 を ROM 化してビルド (b_sample1_rom)
- mruby VM のビルド (_build_mruby)
- mruby VM を実装 (c_mruby)
- TECS 版 tSample1 のビルド (d_tSample1)
- mruby で tSample1 の実現 (e_tSample1Mruby)
括弧内は、ビルドディレクトリです。 リポジトリには、ビルドディレクトリ名でタグを設定しています。 それぞれのタグでは、ビルドディレクトリ以外、最小の変更にとどめています。 変更差分を確認したい場合、タグ間の diff を参照してください。
なお、Ruby 3.0 を使用される場合、最新をチェックアウトしてください。 これらのタグがつけられたものは、Ruby 3.0 に対応していません。
非 TECS 版の sample1 は、TOPPERS/ASP の標準的なサンプルです。本題では、ありませんが、まずは基本形ができていることが重要ですので、ここからスタートです。
% cd asp/
% mkdir -p OBJ_MRUBY_TECS/STM32F7DISCOVERY_GCC/a_sample1
% ../../../configure -T stm32f7discovery_gcc
% make
これで asp.srec ができましたら ROM モニタ上で実行できます。 ROM モニタの書き込み方法は、TOPPERS BASE PLATFORM(asp_baseplatformv1.3.0_052018.tar.gz) に同梱の「ＴＯＰＰＥＲＳ基礎実装セミナー （STM32F4-Discovery版：基本） 開発環境」(BaseTrainingSeminar_environment-020010002.pdf) の ROM モニタの書き込みを参照してください。
実行には Tera Term を起動して出力を確認します。これも上記の資料に詳しく説明されています。
SMT32F746 Discovery Kit の CPU ローカルな RAM は 320KB しかありません。このため mruby VM を実装すると RAM にロードしてデバッガ実行することができません。
このため、ROM に焼いて実行するようにします。まずは、Makefile を修正してビルドしなおす必要があります。
RAM 動作版とは、別の環境でビルドすることにします。RAM 動作版と同じディレクトリから始めることとします。まずは、コンフィグレータまで、実行します。
% cd asp/OBJ_MRUBY_TECS/STM32F7DISCOVERY_GCC
% mkdir b_sample1_rom
% ../../../configure -T stm32f7discovery_gcc
Makefile の以下の行を変更する必要があります。
修正前
DBGENV :=
修正後
DBGENV := ROM
Makefile の修正が終わりましたら、ビルドします。
% make
念のため期待したようにビルドされているか確認しましょう。確認するには asp.syms を参照します。以下のように text領域 (機械語命令が置かれる領域) が 0x08000000 番地から始まっていれば成功です。
08000000 T __text
これは ROM の開始アドレスですが、使用する CPU やボードに依存します。RAM 実行版では RAM の開始アドレスである 0x20000000 になっていましたので、併せて確認してみてください。
先に mruby をビルドしておきます。 ホスト環境用と、ARM 用をビルドします。
初めにホスト用の mruby をビルドします。 これは、mruby コンパイラ mrbc を使用するため必要となります。
% cd mruby-3.0.0
% make
arm 用 mruby をビルドする前に、ビルドスクリプトを少し変更します。
mruby のビルドスクリプトを実行すると、コンパイラを呼び出すときに、絶対パスでファイル名を指定するように組まれています。
今回使用する ARM コンパイラは、非 cygwin のものであるため、このことが問題になります。 相対パスであれば、問題ありません。
本格的な修正案は、ykominami さんが、こちら で相対パスを指定する拡張を公開してくだっていますが、ここでは安直に相対パスを指定するように変更します。
mruby-3.0.0/lib/mruby/build.rb の filename メソッドを変更します。
変更前) # name.gsub('/', file_separator)
変更後) name.relative_path.gsub('/', file_separator)
TOPPERS BASE PLATFORM に合わせたクロスビルド用のスクリプト mruby-3.0.0/build_config/toppers_arm_m7.rb を用意します。
コンパイラのオプションは、Makefile.target, Makefile.chip で指定されているものと合わせる必要があります。 合っていなくても、リンク時にエラーにならないので、ビルド後に動作しない場合、チェックすべき一つになります。
ビルドコマンドは、以下の通りです。rake コマンドにクロスビルド用のスクリプトを指定します。
% rake MRUBY_CONFIG=toppers_arm_m7
いよいよ本題へ入っていきます。TOPERS BASE PLATFORM に mruby VM を組込みます。 これをするために、既存の ROM 化した sample1 をベースに開発を進めます。 ROM 化した sample1 を、そのままコピーしてから始めます。
% cd asp/OBJ_MRUBY_TECS/STM32F7DISCOVERY_GCC
% cd b_sample1_rom
% make clean
% cd ..
% mkdir c_mruby
% cd c_mruby
% cp * ../c_mruby
修正が必要なものは、以下のファイルです。
- Makefile
- sample1.cfg
- nMruby_tMrubyVM.c
- tMruby.cdl
- target_stddef.h
以下、簡単に修正内容について説明します。
Makefile の修正箇所は、たくさんありますが、変更の主旨は、以下の3点です。
- TECS ジェネレータ実行および TECS 関係のオブジェクトのリンク
- mruby へのパスと libmrby.a のリンク
- TLSF へのパスとオブジェクトのリンク
TECS ジェネレータにより生成される cfg ファイルを取り込みます。
- tecsgen.cfg の INCLUDE
TECS ジェネレータ V1.7.0 に同梱されている nMruby_tMrubyVM.c は mruby 3.0.0 に対応しません。 この点を修正します。
また、nMruby_tMrubyVM.c に mruby が参照する API で、必要のないもののダミー定義が このファイルに記載されていました。 これは実装により変わるものですので、ここへダミー定義を入れておくのは 汎用性の観点でよろしくありませんので、ここから外しました。
依存関係を tecs.timestamp から $(GEN_DIR)/tecsgen.timestamp に変更しています。 この変更は TECS ジェネレータ(tecsgen) V1.3.1.0 であれば影響しません。この変更は、次の TECS ジェネレータリリースに含まれます。
target/stm32f7discovery_gcc/target_stddef.h で stdint.h をインクルードするようにします。 さもないとビルド時にエラーが発生します。mruby.h と TOPPERS/ASP のヘッダを同時に取り込むことで、このエラーは発生しています。
修正前
#define TOPPERS_STDINT_TYPE1
修正後
// #define TOPPERS_STDINT_TYPE1
#ifndef TOPPERS_MACRO_ONLY
#include <stdint.h>
#endif // TOPPERS_MACRO_ONLY
以下のファイルを追加します。
- my_mruby.cdl
- my_mruby.rb
- tMrubyStarter.c
- dummy.c
以下、簡単に内容を説明します。
TECS コンポーネント記述言語 （TECS CDL）による記述です。
mruby VM が動作するタスク (MrubyTas)、mruby VM (Mruby) が定義されています。 タスクのスタックサイズや優先度、ヒープサイズなど調整すべき要素が、この CDL ファイルに集約されています。また、セルが定義されているセルタイプのみ、コンパイル、およびリンクされるように Makefile が調整されますので、cfg ファイル、Makefile を触る必要がなくなります。
MrubyStarter は、開始終了メッセージを syslog に出力するものですが、必須ではありません。 MrubyTask の結合先を変更して、MrubyStarter セルの定義をコメントアウトして ビルドしなおすと、完全に取り除くことができます。 tMrubyVMStarter セルタイプの定義は、残しておいてもリンクされることはありません。 リンクするオブジェクト (.o) は自動的に調整されます。
これは mruby のスクリプトです。 この例では、mruby が無事に動作したことを確認するために メッセージを表示するものとなっています。
少しスリープした後、メッセージを出力したのち、mruby VM を呼び出します。
mruby VM は、組込み用と言っても組込み Linux のような POSIX 環境が前提のようです。 dummy.c では、不足する API のダミー関数を定義しています。 これらの API は、環境によっては提供される可能性がありますので、 nMruby_tMrubyVM.c から外してあります。
ビルドは、以下のコマンドで実行できます。
% make
my_mruby.rb は、mrbc コマンドによりコンパイルされて バイトコード (mruby 仮想マシンの機械語) に変換されたものが リンクされます。
ビルドに成功したら SMT32F746 Discovery Kit の ROM に書き込んで 実行してみましょう。 Tera Term に "Welcome to mruby & TECS" と表示されたら成功です。 起動後 5秒で表示されるようになっています。 出力されるメッセージを眺めていて、見逃さないようにしてください。
次は TECS 版 tSample1 のビルドです。 これは mruby 版 tSample1 を作るための中間ステップとして実行します。 TECS 化すると、MrubyBridgePlugin により、mruby から TECS コンポーネントを呼び出すコードを自動生成できるため、まずは TECS 化します。
今回は d_tSample1 をビルドディレクトリとします。
Makefile は、b_sample1_rom のものをベースに c_mruby で行った内、 以下の部分だけ変更を加えます。
- TECS ジェネレータ実行および TECS 関係のオブジェクトのリンク
TOPPERS/ASP には、標準で TECS 化されたシリアルやログが含まれていません(ASP3 には標準え含まれています)。 真面目にやろうとすると、シリアルの TECS コンポーネント化もすべきですが、 今回は、既存のシリアルやログに対するラッパーとして、これらを実現します。
TECS簡易パッケージから持ってきた tSerial.cdl, tSysLog.cdl のシグニチャはそのままに、 セルタイプを変更して tSerialWrapper.cdl, tSysLogWrapper.cdl を作成しました。 結合の変更が CDL の中だけで行えるため、セルタイプを変更しても呼出し元の C 言語のプログラムを触らずにすみます。
これらは syssvc ディレクトリ下に置かれています。
これらは、TECS簡易パッケージから持ってきたものです。
tSample1.cdl は TECS簡易パッケージから持ってきたものを、上述の tSerialWrapper, tSysLogWrapper に合わせる変更をしています。
準備は完了しました。ビルドしましょう。
% make
成功したら、TECS 版 tSample1 を動かしてみてください。 非 TECS 版と、動作は何も変わりませんから、何も感動は、ないかもしれませんね。
それでは、いよいよ tSample1 の mruby 版にとりかかります。 これは、mruby のスクリプトから TOPPERS/ASP のカーネルオブジェクトを操作するサンプルになります。
e_tSample1Mruby をビルドディレクトリとします。
これは、tSample1.cdl をベースに改造を加えます。
MainTask は、mruby VM を動作させるタスクに変えられます。
すべてのセルに MrubyBridgePluin を適用します。
[generate(MrubyBridgePlugin,"")]
cell tTask MainTask ...
これでセルの受け口関数を mruby から呼び出すことが可能になります。
ただし MrubyBridgePlugin の扱うことのできない引数 (の型) を持つ関数は、自動的に外されます (auto_exclude される) ので、 気を付けてください。 このような関数を呼び出したい場合、MrubyBridgePlugin で扱える引数に変更した シグニチャを準備し、ラッピングするセルタイプを作ってください。
tSample1.c の内、MainTask により処理される関数を mruby スクリプトに置き換えました。 C 言語の関数をコメントとして残していますので、対比してみてください。
tSample1 を mruby 化しましたけれど、サブタスクから呼び出される部分は mruby 化されていません。 そのため tSample1Mruby.c には、サブタスクから呼び出される部分が残りました。
MrubyBridgePlugin は、タグ名のない構造体をうまく扱えません。このため serial.h 内の T_SERIAL_RPOR 型の構造体にタグ名 TAG_T_SERIAL_RPOR を付与しています。
この制約は、C言語のコンパイル時に、わかりにくいエラーとなって現れます。 本来であれば、TECS ジェネレータや MrubyBridgePlugin で、エラーにならないようなコードを生成すべきですが、現状では解決できていません。 C言語プログラムのコンパイル時に struct TAG_2_TECS_internal__ (internal__ が目安) のような構造体のエラーが出てきたら、このことを思い出してください。
準備は完了しました。ビルドしましょう。
% make
成功したら、mruby+TECS 版 tSample1Murby を動かしてみてください。 カーネルオブジェクトは、すべて mruby スクリプトにより制御されています。mruby から RTOS を操作できるなんて、素敵ですよね！
基本編完了
- 初期チェックイン asp_baseplatformv1.3.0, mruby-3.0.0
- 追加チェックイン asp-1.9.3, asp_arch_arm_m7_gcc, TLSF-2.4.6
- 追加チェックイン tecsgen-1.7.0
- 方針、進め方まで記載
- 非 TECS 版 sample1 のビルド
- 非 TECS 版 sample1 を ROM 化してビルド
- mruby VM のビルド
- TECS BASE PLATFORM へ mruby VM を組み込む
- TECS 版 tSample1 のビルド
- mruby で tSample1 の実現