デバッガの環境設定

ここでは、Sipeed Risk-V Debuggerの導入と、動作の確認を行う。

全体の目次

注意

このページは、quiita.com で公開されています。URLがqiita.com以外のサイト、例えばjpdebug.comなどのページでご覧になっている場合、悪質な無許可転載サイトで記事を見ています。正しいURLは、https://qiita.com/BUBUBB/items/7ce85ada67a3f6d1944d です。
無許可転載サイトでの権利表記（CC BY SA 2.5、CC BY SA 3.0とCC BY SA 4.0など）は、不当な表示です。
正確な内容は、qiitaのページで参照してください。

Sipeed Risk-V Debugger

この記事では、DFUではなくSipeed Risk V Debuggerを使用して開発を行う。

おおむね1200円～1500円前後で購入できる。

スイッチサイエンス
 千石通商
 マルツ

Sipeed Risk-V デバッガはFT2232Dそのまま、というもので、回路図はSipeedのページからダウンロードできる。回路自体は秋月電子で売られている FD2232D USB シリアル2ch変換モジュールとほぼ同じなので、代用可能かもしれない。

ただ、Sipeed Risk-V Debuggerは金属のケースに入ったドングルなので別途ケーブルを用意しなくてもよいが、秋月のソレは Mini-USBだったり、基盤がむき出しだったり。値段はSipeed製のほうが安めないので、用途がLongan Nanoの開発だけであれば、RiskV Debuggerのほうが良いのではないかと思う。逆に、秋月版のほうは、バスパワー/外部電源の切り替えができたり、ロジックレベルを5/3.3Vで切り替えができたりする。（Sipeed製品はバスパワー、3.3V固定）ほかにも用途がある場合は秋月製品を選ぶほうがよさそう。

用意するもの

これまでの作業で必要だったもの

Windows PC (Windows10/11)
Longan Nano 本体
microSD (16GBytes程度あれば十分すぎる)
USB Type-Cケーブル（PCとLongan Nanoを接続する）

このページで新しく用意が必要なもの

Sipeed Risk V Debugger(前述）
接続ケーブル。Debugger付属、もしくは自作（後述）

Risk-V Debuggerの仕組み

Risk-Vデバッガは、基本的にはUSB-シリアル(RS-232C)変換器。使われているのは、FT2232Dという有名なICで接続すると、自動的にドライバが組み込まれて、WindowsからはCOMポートとして認識される。COMポート、と言っても若い人はわからないかもしれないが、大昔のコンピュータ同士やコンピュータと外部装置を結ぶための接続端子。今のUSBポートのご先祖様、と言ってもよい。

このドライバのままだとデバッガとしては動作しないので、標準に添付されたドライバの代わりに、WinUSBと呼ばれるこれもまた標準の汎用ドライバを使用するように変更する。WinUSBは、汎用的な用途のドライバで、シリアルポートのプロトコルに縛られない通信ができる。

WinUSBを使って、JTAGプロトコルで通信を行ってデバッグが行われる。

つまり、デバッガを使うために必要なステップは次のようになる。

本体、ケーブルなど物理的に必要なものを用意する。
デバッガをWindowsにつなぎ、FT232Dとして認識できるようにする。
デバッガのポート（FT232Dは、標準で２つのCOMポートが用意されるので、そのうちの1つ目）のドライバをWinUSBに変更する。
Platform IOから書き込みにデバッガを使うように変更する。

開封とケーブルの接続

Sipeed RiskV Debuggerは、10pinのボックスヘッダがついており、一方、Longan Nanoは無理やり感のある８ピンが出ている。同じメーカなのだから、ピン配置に配慮があったり、つなぐだけというケーブルが同梱されていてもよいと思ったのだが、そんなことはなく、１ピンのバラケーブルがついてきた。

このケーブルが妙にコシが強く、非常につなぎにくいが、次のように配線する。(GNDと3V3は省略した。NCは接続しない） Longan Nano側のR0、T0、R0や、Debugger側のRST、RXD、TXD、5Vは接続する必要はないが、printfデバッグをする際に使用するので、Longan-NanoのR0とDebuggerのTxD、Longan NanoのT0とDebuggerのRXDを結線しておく。

実際につないだところがこうなる(TXD/RXDは省略した）が、見ての通り非常にわかりにくく、また、少しストレスがかかるとはずれしてしまい、非常に不便。ずっとドングルを刺しっぱなしならそれでも我慢できるが、そこまでLonganに全精力をつぎ込むわけにはいかない。

専用ケーブルの作り方

もし、手持ちに道具があるなら、専用のケーブルを作ってしまったほうが便利だと感じる。下の写真は適当に作ったケーブル。

秋月電子であれば、次のような部品で簡単にコネクタを作ることもできる。

なお、コネクタを作る際の工具はコレ。

精密圧着ペンチ　ＰＡ－２０￥3800

もちろん、工具を買うのが惜しい、などの場合、Longan Nano側のソケットは、圧着ではなくピンソケットと半田ごてを使って作ってもよい。それでも、製品付属のバラよりは使いやすいと思われる。（個人的な感想では、手間と出来栄え、頑丈さを考えると圧着工具を買う価値は十分あると思う）

ケーブル作成時の注意事項

Sipeed Risk-V Debuggerには、いくつかのリビジョンがあるようだ。ケーブル作成時に注意が必要。

Sipeed RISC-V Debuggerを参照すること。

PCへの接続とドライバの確認

DebuggerをPCに接続すると、COMポートとして標準ドライバで認識される。

ドライバは、FTDIとなる。（Windows10/11では標準で添付されている）

ドライバの変更

次に、標準のFTDIドライバから、Microsoft製のWinUSB ドライバにドライバを変更する。ツールを使わず、自力で導入もできるが、元に戻すことを考えるとツールを使ておいたほうが楽。

UsbDriverTool
Zadig

などが使用できる。

この記事では、USB Driver Toolを使用する。https://visualgdb.com/UsbDriverTool/　から、USB Driver Tool.exeをダウンロードし、実行する。解凍先を指定すると、UsbDriverToolというフォルダが作成される。

フォルダ内の、USBDriverTool.exeを、管理者権限で実行する。

起動するとUSBデバイスの一覧が表示されるので、USB Serial Converter を選択する。この画面では、　USB Serial Converter Aを選択しているが、複数のFT2232Dデバイスが接続されている場合には、CとDなど、2つづつずれてくる可能性もある。その場合、デバイスを抜き差しして、Sipeed Risk V Debuggerが作成したエントリを探す必要がある。

デバイスを選択したら、Change driver typeをクリックする。

選択したデバイスに現在登録されているドライバ（デフォルトでは、FTDIになっている）と、置き換え可能なドライバが一覧されているので、WinUSBに変更してInstallボタンをクリックする。

前の画面に戻ると、（WinUSB)が追加され、ドライバが変更されていることが確認できる。

何らかの理由で、ドライバをもとに戻したい場合（同じFT2232Dを使うデバイスが動作しなくなった、など）には、逆の操作を行い、FTDIドライバを選択する必要がある。

動作確認

最後に、Visual Studio Codeからプロジェクトをビルドし、Longan Nanoに転送、デバッガが動作していることを確認する。

サンプルプロジェクトのインポート

Visual Studio Codeを起動し、画面左下の家のアイコンをクリックする。

Visual Studio codeのホームページが起動するので、Project Examplesをクリック。

Import Project Exampleのダイアログでは、Longan-nano-blinkを選択、Immportボタンをクリック。

インポートが終了すると、プロジェクトを信用するかの問い合わせがあるので、信頼するのチェックボックスをチェック、[はい]をクリック。

プロジェクトがインポートされる。

設定ファイルの変更

左側ペイン（エクスプローラー）でplatformio.iniをダブルクリック。右側には、このプロジェクトの設定が表示される。

platformIOに、デバッグやビルドの時にRV Debuggerを使用することを示すため、次の2行を追加する。
upload_protocol = sipeed-rv-debugger
debug_tool = sipeed-rv-debugger

変更前

[env:sipeed-longan-nano]
platform = gd32v
framework = gd32vf103-sdk
board = sipeed-longan-nano
monitor_speed = 115200

変更後

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

ビルドと転送

ステータスバーにある、右矢印ボタンをクリックする。このボタンを押すと、現在のプロジェクトがビルドされ、platformIO.iniに指定された方法（今回の場合、sipeed-rv-debuggerを指定した）で転送が行われる。

コンソールには、ビルドの進捗が表示される。

 :
 :
Verbose mode can be enabled via `-v, --verbose` option
CONFIGURATION: https://docs.platformio.org/page/boards/gd32v/sipeed-longan-nano.html
PLATFORM: GigaDevice GD32V (1.2.1) > Sipeed Longan Nano
Info : flash size = 128kbytes
cleared protection for sectors 0 through 127 on flash bank 0
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 : Bypassing JTAG setup events due to errors
** Programming Started **
auto erase enabled
wrote 7168 bytes from file .pio\build\sipeed-longan-nano\firmware.elf in 1.937121s (3.614 KiB/s)
** Programming Finished **
** Verify Started **
verified 6584 bytes in 0.337878s (19.030 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!!
================================== [SUCCESS] Took 25.85 seconds ==================================

成功したら、Longan Nano上のLEDが赤く点滅する。

問題点の切り分け

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ピンの短絡は確認したほうが良いかもしれない。（電源を接続していない状態で短絡していない状態が正常）

ここまででできたこと

Sipeed Risk-V DebuggerをPCとLongan Nanoの間に接続し、Longan Nanoでプログラムを実行できるようになった

次の記事に進む

Longan Nanoを使ってみる 3 ～デバッガの使用方法～

Sipeed RISC-V Debugger

Longan Nanoを使ってみる 2 ～デバッガの環境設定～

前の記事