SWDを使えば、いちいちBootselボタンを押しながらUSBを差し直すとかいう面倒なことをしなくて済むようになります（そして、SWD以外でデバッグしたくなくなる）。PlatformIOでRaspberry Pi Picoを弄ろうと思った時にSWDを使おうと思ったのですが、公式が用意しているraspberrypi-swdを指定する方法では全くうまくいきませんでした。試行錯誤した結果、以下の方法でうまくいったので、調べた内容の整理も兼ねて共有したいと思います

環境

以下の環境で成功しています

項目	バージョン等
ホストハードウェア	Raspberry Pi 4 Model B 4GB
OS	Debian GNU/Linux 12 (64bit)
PlatformIO Core	6.1.11
OpenOCD	0.12.0
VSCode	1.83.0

前提

この記事の説明は以下を前提としています

環境にもある通り、Raspberry Pi 4BからRaspberry Pi PicoのSWDを使用したデバッグを行おうとしている
Raspberry Pi Pico をセットアップしようの6章までを完了している
- SWDによるデバッグまでできていればよいです（検索すれば、Raspberry Pi Picoのセットアップをわかりやすく説明しているサイトが出てくると思うので、そちらに従ってやってもおそらく問題ないと思います）
VSCodeにPlatformIOをインストールしている

設定方法

結論

プロジェクト設定ファイルplatformio.iniを以下のようにして、VSCodeのデバッグを行えばよいです

platformio.ini

[platformio]
default_envs = pico-raspberrypi4

[env:pico-raspberrypi4]
platform = raspberrypi
framework = arduino
board = pico
; バージョンが1.12*, 1.10*のときは、buid_type = debugがビルドエラーになる
platform_packages =
  platformio/toolchain-gccarmnoneeabi@~1.90301.0

; build configuration
build_type = debug

; upload configuration
; -fフラグの順番はこの通りに指定しないとエラーになる
upload_protocol = custom
upload_flags = 
  -s
  /usr/local/share/openocd/scripts
  -f
  interface/raspberrypi-swd.cfg
  -f
  target/rp2040.cfg
  -c
  program $BUILD_DIR/firmware.elf verify reset exit
upload_command = /usr/local/bin/openocd $UPLOAD_FLAGS

; debug configuration
debug_tool = custom
debug_server =
  /usr/local/bin/openocd
  -s
  /usr/local/share/openocd/scripts
  -f
  interface/raspberrypi-swd.cfg
  -f
  target/rp2040.cfg

ここで、debug_server、upload_command、upload_flagsで使用している以下のパスについては、openocdがインストールされているパスに適宜変更してください

/usr/local/bin/openocd
/usr/local/share/openocd/scripts

つまり、以下コマンドで該当のパスを確認できますが、

whereis openocd
# 結果例
openocd: /path/to/bin/openocd

以下のように、/usr/local部分を実際に出てきたパス（/path/to）に置き換えてください

/path/to/bin/openocd
/path/to/share/openocd/scripts

（Raspberry Pi OSを想定しているので、変更必要ないと思いますが一応、、、）

説明

コードのそれぞれについて、どんな意味か軽く説明していこうと思います。興味がなければ読み飛ばしてもらって大丈夫です

デバッグに使う環境を指定

デバッグに使われる環境は、default_envsが指定されていない場合、一番上に書かれた環境が選ばれるので、ここで明示的に指定しています（結論のファイルでは、1環境しかないのであまり意味はないですが、複数環境入る場合を想定しています）

[platformio]
default_envs = pico-raspberrypi4

使用パッケージの指定

これは別問題ですが、デフォルトで指定されているバージョン（1.90201.191206）が、linux_aarch64で取得できないので、~1.90301.0に変更しています。また、手元で確認したところ、最新のバージョン（~1.120301.0）だとデバッグ用のビルドに失敗するので、このバージョンを使うのが良いようです。

; バージョンが1.12*, 1.10*のときは、buid_type = debugがビルドエラーになる
platform_packages =
  platformio/toolchain-gccarmnoneeabi@~1.90301.0

デバッグ用にビルドする

これを行わない場合、デバッグに失敗すると思います（バイナリをアップロードしたいだけなら不要です）

; build configuration
build_type = debug

アップロードのコマンドを独自のものに変える

upload_protocolにcustomを指定することで、upload_command（独自のコマンド）を使用できるようにしています
upload_flagsにコマンドのフラグを指定して、upload_command内の$UPLOAD_FLAGSでフラグを参照しています。コメントにあるようなupload_flagsの注意事項は後述します
- upload_flagsの-cフラグに$BUILD_DIRが使われていますが、これは、環境がビルドされるディレクトリに変換されます（$SOURCEという変数はビルドオブジェクト名に変換されますが、.elfファイル名ではなく、.binファイル名に変換されるので使用できなかったです）
upload_commandにて、絶対パスでopenocdを実行しています。openocd単体で指定すると、手元では依存関係に指定されているtool-openocd-raspberrypi/bin/openocdが実行されたので、絶対パスにしています

; upload configuration
; -fフラグの順番はこの通りに指定しないとエラーになる
upload_protocol = custom
upload_flags = 
  -s
  /usr/local/share/openocd/scripts
  -f
  interface/raspberrypi-swd.cfg
  -f
  target/rp2040.cfg
  -c
  program $BUILD_DIR/firmware.elf verify reset exit
upload_command = /usr/local/bin/openocd $UPLOAD_FLAGS

upload_flagsでの注意事項は以下の2点となります

-fフラグについて、interface/raspberrypi-swd.cfgを指定してから、target/rp2040.cfgを指定する（そうしないとアップロードは失敗します）
フラグとフラグに指定した値を1行にしない
- 以下の書き方はNGとなります
```
upload_flags = 
  -s /path/to/scripts
  ...
```
- 実行されるコマンドが以下のように、"で囲われてしまって、意図したものではなくなっていしまいます
```
/usr/local/bin/openocd "-s /path/to/scripts" ...
```

upload_flagsを使わずとも、upload_commandにフラグを直接書き下すこともできますが、以下の違いがあるため見やすさのために、upload_flagsを使っています

upload_flags：改行可能（複数行にわたって書ける）
upload_command：改行不可

ちなみに実行しているコマンドは、Raspberry Pi Pico をセットアップしようの5.3節のものとほとんど同じです

デバッグ時のサーバーを独自のものに変える

アップロードのコマンドを変えた時と同様に、debug_toolをcustomにして、debug_serverを独自のコマンドに変えています

; debug configuration
debug_tool = custom
debug_server =
  /usr/local/bin/openocd
  -s
  /usr/local/share/openocd/scripts
  -f
  interface/raspberrypi-swd.cfg
  -f
  target/rp2040.cfg

こちらも使用しているコマンドは、Raspberry Pi Pico をセットアップしようの6.3節のものとほとんど同じです

なんで公式の方法ではうまくいかなかったのか

完全に予想ですが、以下のいずれかかと思っています

バージョンの相性が悪かった
- platformio/toolchain-gccarmnoneeabiのデフォルトで指定されているバージョンが取得できず、別バージョンを入れたが、他のパッケージとの相性が良くなかった可能性がある
使用しているバージョンが古くなってもう使えなくなった

特に、公式の方法で使われるOpenOCDのパッケージは3年前から更新されていないので、後者が原因ではないかと考えています

その他

プロジェクトの初期設定の罠

使用パッケージの指定で軽く触れたのですが、linux_aarch64でデフォルトパッケージが取得できないことが原因、VSCodeでプロジェクトを初期構築がうまくいかずにタイムイートされました（VSCodeでは、パッケージの取得がすべてうまくいかない限り、初期構築が失敗してプロジェクトが作成されないようであった）

プロジェクトの初期設定は、以下のCLIコマンドで行うのが良さそうです。パッケージの取得に失敗しても、プロジェクトの作成自体は成功するので、作成された骨組みのうち、platformio.iniのパッケージ指定変えればよいからです

プロジェクト初期設定のコマンド

mkdir my_project
cd my_project
pio project init -b pico

参考