GR-CITRUSでCS+のRXシリアルデバッガを使えるようにしてみた(IDE for GR編)

[IDE for GR V1.00のリリースにより更新しました。(CS+ V5.00.00との組み合わせで確認済み) 2017/02/04]
GR-CITRUSでCS+のRXシリアルデバッガが使えたら便利そうな気がしましたので、以下のことをしてみました。
なお、CS+でGNURXのELFファイルを読み込むことは動作保証外ですが、そのことは大目に見て下さい。
(IDE for GR編、CC-RX&CS+編実装編、の3本立てブログの1つです。)

予め必要な情報

RXシリアルデバッガ
製品情報

統合開発環境CS+(旧CubeSuite+)
製品情報
オンラインヘルプ

IDE for GR
製品情報

GR-CITRUS
製品情報
特設ページ:IDE for GRでArduinoスケッチ
スケッチリファレンス

やったこと (主なもの)

・USBシリアル変換モジュール(FT232RLを使用)と3.3KΩプルアップ抵抗とGR-CITRUSのSerial1を結線
・GR-CITRUSのSerial1(5Vトレラント)を使うRXシリアルデバッグモニタ(TX:オープンドレイン,RX:CMOS)の作成
・RXシリアルデバッグモニタにリセットボタンでUSBMSCファームウェア(改)へ遷移させる処理を追加
・RXシリアルデバッグモニタにROMコードを調べて通常スケッチならMSBUSBファーム(改)へ遷移させる処理を追加
・ただし上記のどちらもMSBUSBファーム(改)が消去されていたらMSBUSBファーム(改)へ遷移しないようにする
・USBMSCファームウェア(改)をRXシリアルデバッグモニタと一緒にアップデートするbinファイルの作成
・RXシリアルデバッガのセクション配置ルールに従うようにスケッチのリンカスクリプトを変更
・IDE for GRのメニューにRXシリアルデバッガ対応ELFファイルをビルドするメニューを追加
・IDE for GRでビルドしたRXシリアルデバッガ対応ELFファイルを読み込むCS+プロジェクトの作成





とりあえず試してみるのに必要なファイル一式 (なおソースコードは『実装編』に添付します)

GR-CITRUS-IDE4GR-RXSDBG-20161129.zip
GR-CITRUS-IDE4GR-RXSDBG-20161217.zip

ボード上で結線した後、CS+のRXシリアルデバッガを使う手順ですが、大きく分けて以下のようになります。

(1) CS+にRXシリアルデバッガプラグインを組み込む(ユーザーズマニュアルに従って行う)
(2) GR-CITRUSのUSBMSCファームウェアの更新(スケッチのbinファイルを書き込む手順と同じ)
(3) IDE for GRの環境設定ファイルのpreference.txtをエディタ(例えばnotepad)で編集
(4) IDE for GRのボード情報定義ファイル,スタートアップファイル,リンカスクリプトの変更
(5) IDE for GRでRXシリアルデバッガ対応ELFファイルをコンパイルしてGR-CITRUSに書き込む
(6) RXシリアルデバッガ対応ELFファイルを読み込むCS+プロジェクトでCS+を起動後デバッグ開始
(7) CS+起動後はIDE for GRの(書き込みボタンは使わずに)検証ボタンでコンパイルを行う
(8) RXシリアルデバッグ作業を終了した場合はIDE for GRに追加したメニューでモードを元に戻す

それから、補足として、以下のことがあります。

(A) RXシリアルデバッガの制限事項によりデバッガが中断してしまった時の復旧方法
(B) IDE for GRのスケッチフォルダを変えた場合のCS+プロジェクトへのファイルの登録方法
(C) RXシリアルデバッガ対応ELFファイルを読み込むCS+プロジェクトのデバッガの設定

これらの詳細は以下の通りです。

(1) CS+にRXシリアルデバッガプラグインを組み込む(ユーザーズマニュアルに従って行う)

最初に書いたRXシリアルデバッガの製品ページのダウンロードタブからダウンロードしたパッケージを解凍
するとインストーラが含まれていますので、同じくパッケージに含まれているユーザーズマニュアルに従って
インストールして下さい。なお、パッケージはCS+ V3.00.00以降向けのものとCubeSuite+ V2.02向けのものの
2種類がありますので、CS+ V3.00.00以降向けのものをダウンロードして、そちらに含まれているユーザーズ
マニュアルを参照して下さい。(ちなみに、製品ページのドキュメントタブにはCubeSuite+ V2.02向けのものの
ユーザーズマニュアルがあるだけでCS+ V3.00.00以降向けのもののユーザーズマニュアルがありません
ので注意して下さい。)



(2) GR-CITRUSのUSBMSCファームウェアの更新(スケッチのbinファイルを書き込む手順と同じ)

今回のファイル一式を固めたzipファイルには以下のbinファイルが含まれていますので、通常のスケッチの
binファイルを書き込む場合と同じ手順で書き込んで下さい。

ide4gr-rxsdbg\usbfw_updater\citrus_rxsdbg_Serial1_OpenDrain.bin



正常に更新された場合、最後にGR-CITRUSのLEDがゆっくり(約1秒間隔で)3回点灯した後、ちょっと間が空いて
から、LEDが点灯したままになります。この時、再びGR-CITRUSのドライブがマウントされ、通常のスケッチの
binファイルが書き込み出来るようになっています。もし更新に失敗した場合、GR-CITRUSのLEDが速く(約0.2秒
間隔で)点滅したままになります。この場合、以下の手順に従い初期USBMSCファームウェアを復旧させる必要が
あります。(復旧には特別なハードウェアは必要ありませんが、ジャンパワイヤが1本必要になります。また、RFP
(Renesas Flash Programmer)というソフトウェアをインストールする必要があります。RFPはWindows版のみ
しかありませんが、CS+がWindows版しかありませんので、他のOSで試される人はそもそもいないと思います。)

GR-CITRUS 初期ファームウェア (2016/7/14版)
ルネサス→Rulz→/gr_user_forum_japanese/m/mediagallery/309.aspx

(3) IDE for GRの環境設定ファイルのpreference.txtをエディタ(例えばnotepad.exe)で編集

以下のフォルダにpreference.txtというファイルがありますのでエディタで以下の2箇所を設定(追加)します。
なお、IDE for GR(というかArduino IDE)では起動時にビルドフォルダ(以下のbuild.pathで指定したフォルダ)の
下をごっそり消したりしますので、ファイルを残しておきたい場合は、リネームでは駄目で、別フォルダにバック
アップを取る必要があります。

フォルダ: C:\Users\ユーザ名\AppData\Roaming\Arduino15
ファイル: preference.txt
設定内容: 赤字の箇所(必要であればパスは変更して下さい)

browser.linux=mozilla
build.path=C:\Renesas\ide4gr-rxsdbg\build
build.warn_data_percentage=75
途中省略
serial.stopbits=1
sketchbook.path=C:\Renesas\sketchbook
software=ARDUINO




(4) IDE for GRのボード情報定義ファイル,スタートアップファイル,リンカスクリプトの変更

今回のファイル一式を固めたzipファイルに以下のファイルが含まれていますので、IDE for GRの同じ場所に
ファイルをコピー(上書き)して下さい。(なお、拡張子$のファイルはオリジナルのバックアップファイルです。)

ide4gr-1.00\hardware\arduino\rx631\boards.txt
ide4gr-1.00\hardware\arduino\rx631\platform.txt
ide4gr-1.00\hardware\arduino\rx631\cores\core\rx63n\reset_program.S
ide4gr-1.00\hardware\arduino\rx631\variants\gr_citrus\linker_scripts\linker_arduino_rxsdbg.gsi





(5) IDE for GRでRXシリアルデバッガ対応ELFファイルをコンパイルしてGR-CITRUSに書き込む

上の(4)でファイルをコピー(上書き)した後にIDE for GRを起動するとツールメニューにコンパイル形式という
メニューが追加されている筈ですので、ここで'Debugging with CS+'を選択し、あとは通常通りにコンパイル
してGR-CITRUSに書き込んで下さい。書き込むことにより、GR-CITRUSはCS+からのデバッグコマンド待ち
状態になります。




(6) RXシリアルデバッガ対応ELFファイルを読み込むCS+プロジェクトでCS+を起動後デバッグ開始

今回のファイル一式を固めたzipファイルに以下のプロジェクトファイル(.mtpjと.mtud)が含まれていますので、
mtudファイルの方の'UserName'の部分をWindowsの自分のユーザ名に変更してから、CS+でmtpjファイルを
読み込んで起動して下さい。(変更しなくてもデバッガの画面レイアウトが引き継がれない程度のようなので、
大きな問題はありません。) なお、CS+が起動したら、最初の1回だけは、RX シリアル (デバッグ・ツール)の
プロパティでUSBシリアル変換モジュールのCOMポートを選択しておいて下さい。








(7) CS+起動後はIDE for GRの(書き込みボタンは使わずに)検証ボタンでコンパイルを行う

上の(5)でRXシリアルデバッガ対応ELFファイルをコンパイルしてGR-CITRUSに書き込むと、GR-CITRUSの
ドライブがマウントされなくなり、IDE for GRからGR-CITRUSに書き込めなくなります(これは通常のスケッチの
場合と同じ振る舞いです)。ですので、以後はIDE for GRの検証ボタンでコンパイルしてCS+でダウンロードする
ようにして下さい。なお、RXシリアルデバッガ起動中にIDE for GRの検証ボタンでコンパイルを行った場合、
以下のようにCS+が状況を認識して再ダウンロードを促して来るようになります。






(8) RXシリアルデバッグ作業を終了した場合はIDE for GRに追加したメニューでモードを元に戻す

RXシリアルデバッガ終了後にGR-CITRUSのリセットボタンを押すと、通常通りGR-CITRUSのドライブがマウントされ、
マスストレージ経由のスケッチ書き込み待ちになりますので、 RXシリアルデバッグ作業を終了したらIDE for GRの
ツールメニューでコンパイル形式を'Normal Use'に戻しておいて下さい。これを'Debugging with CS+'のままにして
おくと、次にコンパイルしてGR-CITRUSに書き込んだ時に、GR-CITRUSがCS+からのデバッグコマンド待ち状態に
なってしまいます。




(A) RXシリアルデバッガの制限事項によりデバッガが中断してしまった時の復旧方法

RXシリアルデバッガではユーザプログラムの割り込み禁止時間が長いと以下のように接続が切れてデバッガが
中断してしまうことがあります。その場合は、GR-CITRUSのUSBケーブルを抜き差しすれば、GR-CITRUSは再び
CS+からのデバッグコマンド待ち状態になりますので、その後でCS+から通常通りにダウンロードしてデバッガを
再開して下さい。(ただし、デバッグしているプログラム側で割り込み禁止時間が長いことへの対処を行わないと、
いずれは再び接続が切れて同じことになります。) なお、この時、GR-CITRUSのUSBケーブルの抜き差しではなく
GR-CITRUSのリセットボタンを押してしまうと、通常通りGR-CITRUSのドライブがマウントされ、マスストレージ
経由のスケッチ書き込み待ちになってしまいますが、その場合も、GR-CITRUSのUSBケーブルを抜き差しすれば、
GR-CITRUSは再びCS+からのデバッグコマンド待ち状態になります。






(B) IDE for GRのスケッチフォルダを変えた場合のCS+プロジェクトへのファイルの登録方法

CS+のプロジェクトツリーへ以下のようにドラッグ&ドロップによってinoファイルやELFファイルを登録出来ます。






なお、そもそもCS+はソースコードの拡張子として.inoが使われることを想定していませんので、プロジェクト
ツリーでinoファイルをダブルクリックした時にWindowsで拡張子登録されたアプリケーションを起動しようとして
しまい、CS+のウィンドウ内に表示しようとしてくれません。これを回避するには、以下のようにinoファイルを
クリックして右ボタンメニューで'内部エディタで開く'を選択する必要があります。(ちょっと不便ですが、無理
矢理やっていることですので、致し方ないかと思っています。)




(C) RXシリアルデバッガ対応ELFファイルを読み込むCS+プロジェクトのデバッガの設定

上の(B)のようにプロジェクトファイルを使い回していくことで新規にプロジェクトファイルを作成することはないと
思いますが、今回のCS+プロジェクトのデバッガの設定画面を以下に載せておきます。気を付ける必要がある
のは、以下の2点です。(他は、好みだったり、デバッガがエラーになったり、とか。)

・ダウンロード前にフラッシュROMを消去する設定にしておくとUSBMSCファームウェアも消えてしまう
・IDE for GR(やWebコンパイラ)では固定ベクタの位置が変則的なのでCPUリセットフックで補正する