Sipeed RISC-V Debuggerを使う

激安デバイスのSipeed Longan Nanoに使えるSipeed RISC-V Debuggerを購入して設定した。
設定時、いくつか迷ったところがあるので、備忘録として記録に残そうと思う。

全く知識がない状態で書いているので、知っている人には冗長だと思うが、逆に、初心者の人には役に立つ部分もあろうかと思う。
経験者の皆様の指摘は大歓迎。

※今、千石の通販のページを見たら売り切れになっていた。ということは誰かが買ったということなので部分的だが公開することにした。もし、今、ケーブルの配置で「あれ？」と思って検索した人がいたら、ぜひコメントください。あなたのために公開した、と言っても過言ではない・・・（恐ろしく低い確率だろうけど）

ケーブルの作成

Sipeed RISC-V Debuggerは、10pinのボックスヘッダがついている。　Longan-Nanoは8Pinなので変換のためのケーブルを作らなくてはならない。

購入したものは、千石通商で2022/01に購入したものだが、購入したものと商品写真でピンの配置が違っている。いろいろ調べていくと、さらにいくつかのバージョンがあるようだ。

結果としては、製品表面に印刷されているものが正しいようだ。

図中、「表」は、製品名が書かれている側、■はボックスヘッダの切り欠き

パターン１：手元にあるもの

裏	表
GND	TDI
RXD	RST
TXD	TMS■
5V	TDO
3V3	TCK

パターン２：千石通商・スイッチサイエンス、Sipeed社の商品画像

裏	表
GND	TDI
RXD	RST
TXD	TMS■
3V3	TDO
5V	TCK

パターン３：ロボショップ株式会社他の商品画像

裏	表
GND	TDI
RXD	RST
TXD	TMS■
NC	TDO
GND	TCK

Sipeed社の製品ページについては、回路図が公開されている。商品画像ではパターン２で、3.3Vと5Vが出ているはずだが、回路図は次のようになっており、パターン３になっている。

私が買った製品のシルク印刷が間違えているのか、製品のリビジョンが違うのか、さっぱりわからない。せっかく初心者なので「高い」純正品を買ったのにこれでは困る・・・

結局、電源ピンの電圧を測っておそらくパターン１だろう、とした。これから使う人は、ケーブルを作る前は念のためピンの配置を確認しておくとよいと思う。

電源ラインは3.3Vだけを接続する。（Longan Nanoのピンでは3.3Vしか出ていない）

Longan Nanoとの接続

Longan Nanoは、デバッガから電源が供給されるので別途電源は不要。（3.3Vのみ） Longan Nanoの3V3には3.3Vが出力される（当たり前だが）ので、このラインをブレッドボードの電源ラインなどに接続すればよい。

ドライバの導入

ケーブルを作成し、正しく接続してもドライバが正しく導入されていない場合、Platform IOでUploadを行うと、

http://openocd.org/doc/doxygen/bugs.html
Warn : Transport "jtag" was already selected
jtag
adapter speed: 1000 kHz
Error: libusb_open() failed with LIBUSB_ERROR_NOT_FOUND
Error: no device found
Error: unable to open ftdi device with vid 0403, pid 6010, description 'Dual RS232', serial '*' at bus location '*'
*** [upload] Error 1

基本的にドライバのダウンロードは不要。（Windowsに同梱されているもので動作する）

ただ、各種のWebページにあるように、ドライバの手動による変更が必要。多くのページでzadigを使用した方法が案内されているが、私はUSB Driver Toolを使用した。　当初、zadigをダウンロードしたところ2.4で私の環境ではうまく動作しなかったため。

また、Zadigで、変更後の画面を見てみると

となってしまい、変更したのかがわかりにくい。 usbDriverToolは、

と、変更後のデバイス名の後ろに、（）でドライバ名が書かれており、元に戻すとき一目でわかるように思う。（画面中、USB Serial Converter Bは、ドライバを変更していない）

正しくドライバが導入された場合、

 http://openocd.org/doc/doxygen/bugs.html
 Warn : Transport "jtag" was already selected
 jtag
 adapter speed: 1000 kHz
 Info : clock speed 1000 kHz
 Info : JTAG tap: auto0.tap tap/device found: 0x790007a3 (mfg: 0x3d1 (GigaDevice Semiconductor (Beijing)), part: 
 0x9000, ver: 0x7)
 Error: Trying to use configured scan chain anyway...
 Warn : AUTO auto0.tap - use "jtag newtap auto0 tap -irlen 5 -expected-id 0x790007a3"
 Warn : Bypassing JTAG setup events due to errors
 Info : datacount=4 progbufsize=2
 Info : Exposing additional CSR 3040
   :
 Info : Exposing additional CSR 3071
 Info : Examined RISC-V core; found 1 harts
   :
Warn : Bypassing JTAG setup events due to errors
** Programming Started **
auto erase enabled
wrote 47104 bytes from file .pio\build\sipeed-longan-nano\firmware.elf in 6.618960s (6.950 KiB/s)
** Programming Finished **
** Verify Started **
verified 46744 bytes in 1.884120s (24.228 KiB/s)
** Verified OK **
Info : Hart 0 unexpectedly reset!
Info : Note: Hart is halted due to the halt-on-reset bit is set,please continue your  program by appropriate debugger commands or operations!!

という感じでビルドが行われる

問題点の切り分け

Longan Nanoを接続し、電源供給がされているにもかかわらず、アップロードに失敗する場合、次のチェックを行う。

・Error: JTAG scan chain interrogation failed: all ones
この場合、TDOが常にHighになっているかを確認する。TDOと3.3Vが短絡していないかなど。問題ないなら、TDOをGNDに落としてアップロードする。エラーが　all ones　から all Zeros　に変わったらTDOのラインは正常。
・Error: JTAG scan chain interrogation failed: all zeros
All onesの逆。TDOが常にLowになっているかを確認する。TDOとGNDが短絡していないかなど。問題ないなら、TDOをHighにしてアップロードする。エラーが all zerosからAll onesに変わったらTDOのラインは正常。

TDOの接続が正しく、エラーが出る場合、ほかのラインが正しく接続されていないことでTDO出力がされていない可能性がある。ほかの線の接続を死ぬほど確認する。

ちなみに、今手元にあるうちのデバイスの一つが、ある日突然 TDOがGNDと短絡されてしまった。ICソケットから外すとき、ズボラをして長めのピンセットでエイっ、と外していたのが悪かったのか・・・
個体不良もあるので、Longan NanoのTDOとGND/3V3ピンの短絡は確認したほうが良いかもしれない。（電源を接続していない状態で短絡していない状態が正常）

プロジェクトの設定とデバッグの開始

ケーブルに問題がなく、ドライバのインストールが完了すれば、あとはplatform.iniに2行追加するだけで、デバッガが使用できるようになる。

platform.iniの末尾に、upload_protocolとdebug_toolを次のように追加する。

[env:sipeed-longan-nano]
platform = gd32v
board = sipeed-longan-nano
framework = gd32vf103-sdk
upload_protocol = sipeed-rv-debugger
debug_tool = sipeed-rv-debugger

デバッグは、VSCodeの[実行]>[デバッグの開始]から行う。

ワークスペース中に、複数のプロジェクトが存在する場合、[実行とデバッグ]タブのドロップダウンから、デバッグ対象のプロジェクトを選択する。

その他困ったこと

タイマー割込みがかからなくなることがある。

何かの拍子に、デバッグ実行するとタイマー割込みがかからなくなってしまうことがある。この時は、VSCodeを終了させ、Longan Nanoの電源を落としてから再度実行するとうまくいくことが多い。
割り込み処理の中でブレイクポイントを設定して停止させた後に発生することが多いような気がする。割り込み処理についてはデバッグ実行が不安定な印象がある。