mbed SDKの開発に貢献してみよう

これは mbed Advent Calendar 2014 - Adventar の17日目の記事です。

mbed は簡単で使いやすいプラットホームですが、使い込んでいると自分で拡張したくなったり、不具合を見つけることもあります。

問題を発見したら、mbed.org の forum や GitHub の mbed SDK 公式のリポジトリに issue として報告してみましょう。

https://developer.mbed.org/forum/bugs-suggestions/
https://github.com/mbedmicro/mbed/issues

ソースコードが公開されているので、自分で修正することもできます。オンライン環境では、mbed-src ライブラリを使って自分のアカウント環境のみでソースを改変することも出来ます。 不具合の修正が他のユーザにとっても有効だと思ったら、mbed マスターリポジトリにプルリクエストを出して、コードをマージする事も出来ます。

ここでは、私が最近出したプルリクエストを例に挙げて、その手順を説明します。

準備

GitHub のアカウントが無い場合は作成しましょう。mbedmicro/mbed をフォークして、自分の環境にクローンを作成します(これは、commit や pull request を出すために必要です)。
https://github.com/mbedmicro/mbed

なお、mbed SDK 開発環境の構築手順は、@ytsuboi さんのノートブックが大変参考になります。 http://developer.mbed.org/users/ytsuboi/notebook/getting-started-mbed-porting-ja/

オフライン環境で使用するコンパイラは別途準備する必要があります。

作業内容

今回の起点は、mbed.org の questions に動作不具合のレポートが上がっていた事でした。 https://developer.mbed.org/questions/4872/SPISlave-Class-dosnt-work-on-LPC1114/

LPC1114でSPI slave 機能が動作しないとの報告だったので、実機で確認してみたらまさにその通り。(汗) 因みに、このターゲットデバイスへのポーティングは我々(坪井さんやイギリス人のエンジニア)が行ったものです。

LPC1114 のポーティングでは、既に実績のあった LPC11U24 のペリフェラル部分のコードを多く流用しているのですが、レジスタの仕様が拡張されていたり同じ設定では動作しない部分があったようです。

この報告にはテストコードなどは含まれていなかったので、mbed SDK に含まれているテストコードを流用しました。SPI slave 機能のテストは当然 SPI master が無いと動きません。対向機としてLPC11U24を使用しました。

地道にデバッグしてチップのユーザーズマニュアル読んで、不具合を修正しました(この手順は省略します)。

で、ここからは以下のような手順になります。

  • 修正したコードのテスト
  • クローンした自分のリポジトリに修正をコミット
  • mbedmicro/mbed に対してプルリクエストを発行

修正したコードのテスト

ビルドとかデバッグ環境の構築は、先ほどの @ytsuboi さんのノートブックを参照してください。LPC1114NF28 ライブラリのビルドは、こんな感じです。

workspace_tools\build.py -m LPC1114 -t uARM

現在の mbed SDKは多数のターゲットに対応しており、ソースコードも複数のデバイスで共有している場合が多くなっています。ソースツリーは、ターゲット依存部 - ベンダー依存部 - デバイスファミリ依存部毎にディレクトリが分かれているため、初めてソースを見ても構造はそれほど難しくは無いと思います。

ソースファイルやヘッダファイルを新しく追加した場合は、念のため他のターゲットもビルドして影響がないことを確認した方が安心です。ターゲットが複数のツールチェインに対応する場合は、個別にコンパイルできるかを確認した方がいいでしょう。

mbed SDK には、automated test suite も用意されています。既存の SDK の不具合修正などでは必須ではありませんが、念のため通しておいたほうが安心です。

https://developer.mbed.org/teams/SDK-Development/wiki/Mbed-SDK-automated-test-suite

クローンした自分のリポジトリに修正をコミット

GitHub アプリなどから修正をコミットします。Summary と Description に修正内容を記述し、Commit を行います(念のため、Commit の前に Sync を実行した方が良いでしょう)。

mbedmicro/mbed に対してプルリクエストを発行

大事なのは、mbedmicro/mbed のプルリクエストをマージする担当者(ARM の mbed チームメンバー)に分かりやすく内容を説明する事です。そのため、commit log の書き方がとても重要になります。

適当に commit log を書いてプルリクエストを出すと、「もっと修正内容を詳しく書け」と怒られたことも数回ありました。orz あと、複数の内容の異なった修正をひとつのプルリクエストで纏めるのも止めた方が良いです(これも怒られました...後から、revert する場合に面倒なので当然なのですが)。

単一のコミットの場合デフォルトでは、『クローンした自分のリポジトリに修正をコミット』で作成した内容がそのまま使われます(もちろん修正することも可能です)。

Information

commit log のお作法(みたいなもの)

mbed SDK の場合、プルリクエストのタイトルは:

"[プラットフォームやコンポーネント名称] 修正の説明"

の様な感じで登録するケースが多いようです。例えば、今回の場合は:

[LPC11XX_11CXX] Fix SPI slave issue

としました。LPC1114としなかったのは、LPC11C24などの他のLPC11系のプラットホームにも影響がある変更だったからです。

https://github.com/mbedmicro/mbed/pull/756

詳細コメントの部分は、箇条書きで簡潔にすると読みやすくなります。今回は、こんな感じにしました。

  • Fix a bug reported here: https://developer.mbed.org/questions/4872/SPISlave-Class-dosnt-work-on-LPC1114/
  • Add IOCON settings to enable proper pin functions
  • Remove non-busy check in slave_receive() function, since the SSP/SPI is always in busy state when received a valid data according to the device user manual
  • Add bit mask in spi_slave_read() function
  • Add TARGET_LPC1114 pin config in SPI_SLAVE test
  • Tested with LPC11U24 SPI master and LPC1114 SPI slave

プルリクエストを出すと、mbed チームの担当者から「以下のリンク先の contributor agreement に同意して、mbed.org のニックネーム(ユーザー名)をおしえて下さい。」というコメントがきます(初回のみ)ので、素直に言う通りにします。

http://developer.mbed.org/contributor_agreement/

mbedmicro/mbed にプルリクエストを出すと、Travis CI を使った自動ビルドが走ります。他のターゲットをビルドした時のコンパイルエラーなども自動でチェックしてくれるので便利です。

担当者によるコードレビューで問題が見つかったり確認事項がある場合にはコメントが付くことがあります。質問に対して返信しないと、いつまで経ってもコードがマージされませんのでご注意ください。

Travis CI のビルド結果やコードレビューに問題なければ、プルリクエストは無事にマージされます。お疲れ様でした。

その他の情報

Handbook - 日本語ドキュメント
[lang:ja] mbedのポーティング環境構築
ARM Cortex-M, mbed SDK and HDK deep dive 資料(20140704)
英語に自信の無い方は日本語フォーラムで相談してください。

以上です。

18日目は mia_0032 さんです。よろしくお願いします。


Please log in to post comments.