arcs-dev-tools

ARCS SDK ツールチェーン

Claude Code に ARCS ハードウェアと連携するツールチェーン機能を提供します。リポジトリの取得、開発環境のインストール、コンパイル、書き込み、実行、ログの読み取りを行います。

この skill はツールチェーンの操作のみを担当し、コードの作成や理解は担当しません。 コード開発、要件の理解、バグ分析は Claude Code 自身が行います。

現在の状況

この skill は現在も開発段階です。ご利用の際に、ぜひフィードバックをお寄せください。

• 安定して再現するバグ（できればコマンド出力やログの抜粋を添付してください）
• 環境の互換性に関する問題（ディストリビューション、Python のバージョン、シリアルデバイスの種類など）
• より良い「トリガーとなる文言／使用例」（skill パッケージ内ではなく、リポジトリの docs/ ドキュメントに追加してください）

検証済みの機能（動作確認済み）

• 特定の sample を実行：モデルが自分でサンプルを特定 → コンパイル → 書き込み → ログを読み取り → 成功／失敗を判定
• UI に表示して反復：モデルがまず UI に 1 行のテキストを表示するサンプルを作成 → 書き込み・実行 → テキストを変更 → 再度書き込み、反映されたことを確認

使用例

例とトリガーとなる文言は <skill_dir>/references/usage.md を参照してください（必要に応じて読み込み、メインファイルが長くなりすぎないようにします）。

バッチモード

• コンパイル→書き込み→検証を順番に実行します（シリアルデバイスは同時に 1 つの操作でしか使用できません）
• 各サンプルの検証結果を個別に出力し、最後にまとめます
• 失敗したサンプルがあっても、後続の処理は続行します

デフォルト設定

パラメーター	デフォルト値	説明
BOARD	arcs_evb	対象の開発ボード
シリアルデバイス	動的スキャン	各操作の前に /dev/ttyACM* /dev/ttyUSB* をスキャンします
書き込みボーレート	3000000	cskburn のボーレート
シリアルボーレート	921600	ログ読み取りのボーレート
書き込み開始アドレス	0x0	Flash の書き込みオフセット
リポジトリアドレス	https://gitlab.example.com/listenai/arcs-sdk.git	git clone のアドレス（実際のアドレスをユーザーに確認してください）

基本原則：偶発的な事象ではないことを確認してから対処する

異常な現象が発生した場合は、必ず 2～3 回再検証し、安定して再現するかを確認してから対処を決めてください。

• 毎回再現する → 実際の問題です。Claude Code に返して対処してもらいます
• たまにしか発生しない → 環境要因として扱い、コードの問題とは見なしません

ツールチェーンの操作

操作 1：リポジトリの取得

ユーザーの環境に arcs-sdk リポジトリがない場合に実行します。

# 克隆仓库（用户需提供实际的仓库地址）
git clone <仓库地址> arcs-sdk
cd arcs-sdk
git submodule update --init --recursive

• ユーザーからリポジトリアドレスが提供されていない場合は、ユーザーに確認します
• リポジトリがすでに存在する場合は、この手順をスキップして既存のリポジトリを使用します
• ブランチの切り替えに対応しています：git checkout <branch>

操作 2：開発環境のインストール

初回使用時、またはツールチェーンが不足している場合に実行します。ただし、必ず最初に環境変数を確認してください。ユーザーがすでにツールチェーンのパスを設定している場合があります。

環境変数を優先して確認します：

# 检查用户是否已指定工具链路径
echo "NUCLEI_TOOLCHAIN_PATH=$NUCLEI_TOOLCHAIN_PATH"
echo "LISTENAI_TOOLS_PATH=$LISTENAI_TOOLS_PATH"

環境変数	意味	設定されている場合にスキップ
NUCLEI_TOOLCHAIN_PATH	ユーザー指定の RISC-V GCC ツールチェーンのパス	prepare_toolchain.sh をスキップ
LISTENAI_TOOLS_PATH	ユーザー指定の listenai-tools のパス（cmake、ninja など）	prepare_listenai_tools.sh をスキップ

環境変数が設定されている場合、対応するインストールスクリプトを実行しないでください。ユーザー指定のパスをそのまま使用します。

環境変数が設定されていない場合に限り、インストールスクリプトを実行します。

# 1. 安装构建工具（仅当 LISTENAI_TOOLS_PATH 未设置时）
bash prepare_listenai_tools.sh

# 2. 安装 GCC 交叉编译工具链（仅当 NUCLEI_TOOLCHAIN_PATH 未设置时）
bash prepare_toolchain.sh

# 3. 确保 cskburn 有执行权限
chmod +x ./tools/burn/cskburn

確認項目（優先順位順）：

1. NUCLEI_TOOLCHAIN_PATH が設定されている場合 → $NUCLEI_TOOLCHAIN_PATH/bin/riscv64-unknown-elf-gcc が実行可能か確認します
2. LISTENAI_TOOLS_PATH が設定されている場合 → $LISTENAI_TOOLS_PATH/cmake/bin/cmake が実行可能か確認します
3. 環境変数が設定されていない場合 → リポジトリ内の listenai-dev-tools/ 以下に対応するパスがあるか確認します
4. ./tools/burn/cskburn が実行可能か確認します

確認に問題がなければ、インストールをスキップします。

操作 3：コンパイル

入力：プロジェクトのパス（サンプルディレクトリ、またはユーザーが作成したプロジェクトのディレクトリ） 出力：build/arcs.bin ファームウェアファイル、またはコンパイルエラー情報

cd <项目目录>
bash ./build.sh -C -DBOARD=arcs_evb && bash ./build.sh -r -w -DBOARD=arcs_evb

build.sh の検索方法：

• プロジェクトディレクトリに build.sh がある場合 → そのファイルを直接使用します
• ない場合 → リポジトリのルートディレクトリにある build.sh -S <プロジェクトの相対パス> を使用します

コンパイルに失敗した場合：

• エラー出力全体を Claude Code に返し、Claude Code に分析とコードの修正を依頼します
• <skill_dir>/references/knowledge.md の該当する topic を確認し、既知の解決策があるか調べます
• Claude Code がコードを修正した後、この操作を再度呼び出してコンパイルします

コンパイル成果物の確認：

• build/ 以下で .bin ファイルを探します
• ファームウェアファイルの完全なパスとサイズを返します

ARCS のコンパイル成果物の命名規則：

• build/<name>.bin — ファームウェアファイル（書き込みに使用）
• build/<name> — ELF ファイル（拡張子なし）。GDB デバッグ用で、デバッグシンボルを含みます
• 例：build/helloworld.bin に対応する ELF は build/helloworld です
• ELF ファイルには .elf 拡張子がありません。*.elf を探さず、.bin を取り除いた同名の拡張子なしファイルを使用してください

ARCS の起動順序と build ディレクトリ構成：

チップの起動順序：ROM_BOOT → AP ファームウェア（boot）→ CP ファームウェア（アプリケーション）

build/ 以下に boot/ サブディレクトリがある場合：

• build/boot/boot.bin — AP コアの boot ファームウェア
• build/boot/boot — AP boot の ELF（拡張子なし）。AP のデバッグ時にこのファイルを使用します
• build/<name>.bin — boot を結合済みの完全なファームウェア（= boot.bin + アプリケーション bin）。そのまま書き込めます
• build/<name>.bin.without.boot — boot を含まないアプリケーション単体のファームウェア
• build/<name> — CP アプリケーションの ELF（拡張子なし）。CP のデバッグ時にこのファイルを使用します

GDB デバッグ時に正しい ELF を選択する：

• AP（boot）をデバッグ → build/boot/boot を使用します
• CP（アプリケーション）をデバッグ → build/<name> を使用します

操作 4：書き込み

入力：ファームウェアファイルのパス 出力：書き込みの成功／失敗

書き込み前：

# 动态扫描串口设备
ls /dev/ttyACM* /dev/ttyUSB* 2>/dev/null
# 确认无进程占用
fuser <串口设备> 2>/dev/null

実行：

# 必须使用仓库自带的 cskburn，必须带 -C arcs 参数
./tools/burn/cskburn -C arcs -s <串口设备> -b 3000000 0x0 <固件文件路径>

重要：リポジトリのルートディレクトリにある ./tools/burn/cskburn を必ず使用してください。listenai-dev-tools/listenai-tools/cskburn/cskburn は使用しないでください。 後者は汎用バージョンであり、-C arcs パラメーターに対応していません。書き込み前の自動消去手順もないため、書き込みに失敗する可能性があります。

書き込みが正常に完了した場合の出力例：

Waiting for device...
Entering update mode...
Detected flash size: 16 MB
Erasing region 0x00000000-0x00021000...
Burning partition 1/1... (0x00000000, 130.88 KB)
130.88 KB / 130.88 KB (100.00%)
Resetting...
Finished

失敗時の対処：

• Failed opening device → ボードが書き込みモードになっていません。ユーザーに BOOT+RESET を押して書き込みモードにするよう案内します
• EBUSY → fuser で占有中のプロセスを特定し、解放するようユーザーに案内します
• ETIMEDOUT → 3 秒待ち、デバイス番号を再スキャンして再試行します
• デバイスが消えた場合 → 待機後、/dev/ttyACM* を再スキャンします
• Failed burning partition: 01 → listenai-dev-tools 内の cskburn を誤って使っていないか確認し、./tools/burn/cskburn に切り替えます

操作 5：运行（日志读取）

输入：无（烧录完成后自动执行）或独立调用 输出：串口日志文本

使用 serial_read.py（技能自带脚本，纯 Python stdlib，零外部依赖）：

python3 <skill_dir>/serial_read.py read <串口设备> -b 921600 -t <读取秒数>

兼容旧用法：不加 read 子命令也可以（自动识别为 read 模式）。

<skill_dir> 即本技能安装目录，与 SKILL.md 同级。

参数说明：

参数	默认值	说明
-b, --baudrate	921600	波特率
-t, --timeout	5	读取超时（秒）
--dtr	不传（拉低）	传入则拉高 DTR
--rts	不传（拉低）	传入则拉高 RTS

特性：

• 非 TTY 环境兼容（O_NOCTTY + select() 非阻塞读取）
• 默认拉低 DTR 和 RTS（通过 ioctl TIOCMBIC）
• 打开后自动 flush 缓冲区，避免读到残留数据
• 实时输出到 stdout

串口问题处理：

• 乱码 → 确保波特率设置正确（921600），或等板子完全启动后再读
• 设备断连 → 关闭连接 → 等 2-3 秒 → 重新扫描设备 → 重连
• 无输出 → 先尝试操作 7 复位芯片，仍无输出则提醒用户检查连接或重新烧录
• 权限问题 → 确保用户在 uucp/dialout 组中
• 设备占用 → 读取前检查是否有其他进程占用（fuser <串口设备>）

日志返回给 Claude Code，由 Claude Code 判断程序是否正常运行。

操作 6：检查硬件连接（串口）

独立操作，可在任意时刻调用。

ls /dev/ttyACM* /dev/ttyUSB* 2>/dev/null

• 找到唯一设备 → 返回设备路径
• 找到多个 → udevadm info 识别后询问用户
• 找不到 → lsusb + dmesg | tail -20 后告知用户

操作 7：复位芯片

通过烧录串口的 DTR 信号复位芯片，无需手动按 Reset 键。

python3 <skill_dir>/serial_read.py reset <串口设备>

原理：拉高 DTR → 等待 0.5 秒 → 拉低 DTR，触发芯片硬件复位。

使用场景：

• 烧录后需要复位芯片重新启动
• 芯片卡死需要重启
• 调试过程中需要重新运行程序

复位后读日志的典型组合：

# 先复位，再立即读取启动日志
python3 <skill_dir>/serial_read.py reset <串口设备> && \
python3 <skill_dir>/serial_read.py read <串口设备> -b 921600 -t 5

操作 8：JLink 环境检测与部署

当用户需要通过 JLink 调试 ARCS 芯片时执行。详细步骤见 <skill_dir>/references/jlink-setup.md。

检测与部署流程：

1. 检测 JLink 软件是否已安装（JLinkExe、JLinkGDBServerCLExe）
2. 检测并部署 JLinkDevices 配置（~/.config/SEGGER/JLinkDevices/Listenai.xml + Flashloader.elf）
3. 检测目标核心（AP/CP）并选择对应 JLink Script，告知用户当前调试的核心
4. 动态检测 JLink 硬件序列号
5. 执行连接测试（JLinkExe 纯 CLI 读取 flash 验证通畅，不要使用 JFlashExe 避免弹出 GUI）

核心选择：ARCS 双核（AP+CP），通过 build 目录 .config 中的 CONFIG_ARCS_AP_CORE/CONFIG_ARCS_CP_CORE 自动判断。Debug AP 用 jtagscan0，debug CP 用 jtagscan1，烧录/读 Flash 始终用 jtagscan0。

ARCS JLink 接线：PA01-SWDIO, PA00-SWCLK, GND, VTref(3.3V)。接口模式为 cJTAG (2-pin)。

资源文件：<skill_dir>/assets/jlink/ 下包含 Flashloader.elf、arcs.jflash 模板、JLinkScript 文件。

严禁违反以下三条，否则必定连接失败：

1. 接口必须用 -if cJTAG，不能用 -if JTAG 或 -if SWD
2. 必须加载 JLinkScript：-JLinkScriptFile <skill_dir>/assets/jlink/jtagscan0.JLinkScript（或 jtagscan1），不带 JLinkScript 会报 Could not connect to target
3. 设备名必须用 ARCS，不能用 ListenAI ARCS

调试策略：JLink GDB 优先

当用户提到"debug"、"调试"、"断点"、"单步"、"崩溃"、"卡死"、"排查问题"等关键词时，优先使用 JLink GDB 调试，而非串口日志。

调试方法优先级

1. JLink GDB 调试（首选）— 可设断点、单步执行、查看变量和寄存器、精确定位问题
2. 串口日志读取（备选）— 仅当 JLink 环境不可用时使用

选择逻辑

用户提到 debug/调试/排查问题
  → 检查 JLink 环境是否就绪（操作 8）
    → 就绪 → 使用 JLink GDB 调试（流水线 C）
    → 未就绪 → 尝试部署 JLink 环境（操作 8）
      → 部署成功 → 使用 JLink GDB 调试
      → 无法部署（无 JLink 硬件等）→ 降级为串口日志（流水线 A/B）
        → 告知用户："当前使用串口日志排查，建议连接 JLink 以获得更精确的调试能力"

常用流水线

流水线 A：运行现有示例

Claude Code 调用顺序：

1. 检查硬件连接
2. 定位示例目录，阅读 README 和源码（Claude Code 自己做）
3. 编译（操作 3）
4. 烧录（操作 4）
5. 日志读取（操作 5）
6. Claude Code 对比日志和预期输出，判断结果

流水线 B：编写新代码并验证

Claude Code 调用顺序：

1. 检查硬件连接
2. Claude Code 参考仓库中的示例和 API，编写代码
3. 编译（操作 3）→ 失败则 Claude Code 改代码 → 重新编译（循环）
4. 烧录（操作 4）
5. 日志读取（操作 5）
6. Claude Code 判断是否符合预期 → 不符合则改代码 → 回到步骤 3（循环）

流水线 C：JLink GDB 调试

当用户需要 debug/调试时，优先使用此流水线：

Claude Code 调用顺序：

1. JLink 环境检测（操作 8）→ 未就绪则自动部署
2. 编译（操作 3）→ 定位 ELF 文件：build/<name>（无后缀，不是 .elf），确认带调试信息（with debug_info, not stripped）
3. 检测目标核心（AP/CP）→ 选择对应 JLink Script
4. 启动 JLinkGDBServer：

   ⚠️ -JLinkScriptFile 是必填参数，缺少会导致 CPU-TAP not found in JTAG chain

   JLinkGDBServerCLExe -device ARCS -if cJTAG -speed 4000 -port 2331 \
       -USB <serial_number> -nogui -noir -nologtofile \
       -JLinkScriptFile <jtagscan_script> &
   

   设备名必须用 ARCS，不能用 ListenAI ARCS（会卡死）

5. GDB 连接并调试：

   <riscv-gdb> -batch -x <gdb_commands_file> <elf_file>
   

   GDB 命令文件示例：

   set pagination off
   set confirm off
   target remote localhost:2331
   monitor reset
   monitor halt
   load
   break main
   continue
   

6. 根据调试目标设置断点、单步执行、查看变量
7. 调试完成后关闭 GDBServer 进程

经验知识库

文件：<skill_dir>/references/knowledge.md

按 6 个 topic 组织：仓库管理 / 环境安装 / 编译 / 烧录 / 串口 / JLink。遇到问题时只读对应 topic。

本文件由维护者手动维护，模型不要修改。

自优化 SKILL.md

发现应沉淀到 skill 的通用性问题时，不要直接修改 SKILL.md，告知用户，用户同意后再更新。

注意事项

1. 本 skill 只做工具链操作：代码编写、需求理解、bug 分析由 Claude Code 本身完成
2. 串口独占：烧录和日志读取不能同时使用同一串口
3. 设备号动态扫描：每次操作前都扫描，不硬编码
4. 异常先确认再处理：重复验证 2-3 次，确认非偶发后再处理
5. 安全优先：不执行 rm -rf 等危险操作
6. 避免使用的方法：
   • picocom/minicom: 在非交互式环境中无法正常工作（需要 TTY）
   • pyserial: 需要额外安装 Python 包，在受限环境中可能不可用
   • stty + cat: 在非 TTY 环境下会回显波特率，且无法控制 DTR/RTS 信号线