| name | porting-asp3-to-nxp |
| description | TOPPERS/ASP3 を NXP i.MX RT6xx/RT5xx（MCUXpresso SDK + arm-none-eabi-gcc）の新しいボードに移植する手順と、SDK統合特有の落とし穴（SDK startup でのSecureブートとEXC_RETURN・ASP3ベクタテーブル配置・SDK既定クロックとHRT精度・west非使用のsubmodule直参照・LinkServer/J-Link 操作）をまとめたガイド。新規ボード対応、実機ブリングアップのデバッグ、ビルド・書込み・検証の作業で参照する。 |
TOPPERS/ASP3 を NXP MCUXpresso SDK ボードに移植する
このリポジトリ（asp3_mcuxsdk）は TOPPERS/ASP3 Core を NXP MCUXpresso SDK 環境で
動かすための移植層。EVK-MIMXRT685（i.MX RT685・Cortex-M33）を実例として、
新規 NXP ボード対応や実機ブリングアップに必要な作業をまとめる。
ASP3 はシングルプロセッサカーネルで、RT685 では CM33 のみ使用する（HiFi4 DSP は停止のまま）。
このスキルが扱う作業
- 新規ボード（例: EVK-MIMXRT595 / LPCXpresso55S69）を ASP3 に追加する → checklists/new-board.md
- 実機で動かない時のデバッグ → checklists/bringup-debug.md
- SDK の取得・更新（west 非使用の submodule 直参照） → reference/sdk-acquisition.md
- 書込み・デバッグ・シリアルのツール操作（LinkServer / J-Link） → reference/flash-debug-tools.md
- ブート経路と EXC_RETURN・ベクタ配置の落とし穴 → reference/boot-vector-pitfalls.md
重要な前提知識（最初に読む）
1. ディレクトリ構成
asp3_mcuxsdk/
├── asp3/
│ ├── asp3_core/ # カーネル本体（git submodule・無変更が原則）
│ ├── arch/arm_m_gcc/imxrt600_mcuxsdk/ # チップ層（SDK版・外側リポジトリ管理）
│ ├── target/evkmimxrt685_mcuxsdk/ # ターゲット依存部（SDK版）
│ └── asp3_mcuxsdk.cmake # glue（ASP3_TARGET_DIR / ASP3_CORE_DIR 解決）
├── sdk/ # MCUXpresso SDK（submodule・release タグでピン留め）
│ ├── core/ devices-rt/ cmsis/ components/
├── evkmimxrt685/sample1/ # ボードプロジェクト（asp3_fsp と同構成）
│ ├── CMakeLists.txt / CMakePresets.json / main.c
│ ├── MIMXRT685Sxxxx_cm33_flash.ld # SDK の ld に ASP3 ベクタ配置を追加
│ └── board/ # SDK examples のボード初期化（BSD-3・コピー）
└── docs/ # host-setup / verification / tech-notes / TODO
新規ボード追加では asp3/target/<新ターゲット>_mcuxsdk と <board>/<app>/ の
2 箇所をセットで用意する。SDK 固有部は外側リポジトリ管理、asp3_core は
ASP3_TARGET_DIR で受け入れる（Pico SDK / FSP / STM32 統合と同方針）。
2. SDK との付き合い方（west を使わない）
MCUXpresso SDK は本来 west マニフェスト方式だが、本リポジトリは
mcuxsdk-manifests の release タグが指す SHA を submodule で直接ピン留めする
（core / devices-rt / cmsis / components の4本）。west・Kconfig・SDK の CMake
ビルドシステムは使わない。必要な fsl_* ソースだけをボードプロジェクトの
CMakeLists で直接コンパイルする（STM32Cube の HAL と同じ扱い）。
- これにより GUI 生成ツールが不要になり、
git clone --recurse-submodules
直後にそのままビルドできる（CI でもビルド可能＝CubeMX/RASC と違う利点）。
- ボード初期化ファイル（
board.c / clock_config / pin_mux / flash_config）は
examples リポジトリ（巨大）からコピーする（CubeMX 生成コードのコミットと同じ扱い）。
- 取得・更新の詳細は reference/sdk-acquisition.md。
3. 実機ブリングアップで踏んだ地雷（必読）
詳細は reference/boot-vector-pitfalls.md。要点:
| # | 落とし穴 | 症状 | 対策（実装済みの形） |
|---|
| 1 | SDK startup は Secure ブート→ TrustZone 定義が必要 | 最初のディスパッチで INVPC（UsageFault・CFSR=0x40000）即死 | imxrt600_mcuxsdk/arch.cmake で TOPPERS_ENABLE_TRUSTZONE を定義する（mps2_an521 と同じ。Phase A の自前プレーンイメージブートとは逆） |
| 2 | ASP3 ベクタテーブルが orphan→ リンク失敗 | .vector will not fit / LMA overlap | SDK の ld をコピーし .kernel_vector（ALIGN(512)・> m_text）を追加して明示配置 |
| 3 | VTOR 整列違反 | バナーは出るがタスク切替で即死 | target_kernel.py がテーブルに整列属性を生成＋ld の ALIGN(512) |
| 4 | HRT が正確に 1MHz にならない | get_tim がわずかにドリフト（実用上問題なし） | SDK 既定 main_clk の整数分周＝1.000421MHz（+421ppm）を許容・文書化 |
| 5 | fsl ヘッダと arm_m.h のマクロ二重定義 | EXC_RETURN_PREFIX 等の警告 | fsl include を #pragma push_macro/pop_macro で挟む |
最重要の教訓：ブートイメージのタイプ（ベクタ9＝オフセット 0x24 の値とブート経路）が
EXC_RETURN 構成を決める。新ボード移植ではまずブート経路を確認すること。
4. ビルド
cd evkmimxrt685/sample1
cmake --preset Debug
cmake --build build/Debug
アプリ（既定 sample1）の差し替えは asp3_core 標準の -D 機構が使える:
CORE=$PWD/../../asp3/asp3_core
cmake --preset Debug -B build/Debug-porting \
-DASP3_APPLDIR=$CORE/test/porting -DASP3_APPLNAME=test_porting \
-DASP3_EXTRA_APP_C_FILES=$CORE/test/porting/tap.c
cmake --build build/Debug-porting
CMakePresets.json は version 7 必須（MCUXpresso for VS Code 拡張が環境ブロックを
注入する。詳細は tech-notes §8）。注入されるマシン固有パスはビルドでは未参照のため、
CI やそのパスを持たない環境でもビルドは通る。
5. 書込みと動作確認
標準はオンボード LPC-Link2 の CMSIS-DAP（出荷時ファームウェア）＋ LinkServer：
cd evkmimxrt685/sample1/build/Debug
/usr/local/LinkServer/LinkServer flash MIMXRT685S:EVK-MIMXRT685 load asp.elf
stty -F /dev/ttyACM0 115200 raw -echo
cat /dev/ttyACM0
最小チェック（sample1）:
- バナー →
Sample program starts (exinf = 0). → task1 is running (NNN)
printf 'r' > /dev/ttyACM0 で task1→task2→task3 が切り替わればディスパッチ OK- 仕上げは test_porting（TAP 6項目） を書込み、
# 6/6 passed を確認
ツールのパス・J-Link 切替・OS Awareness は
reference/flash-debug-tools.md。
参考
- 経緯・root cause 解析の正本:
asp3/asp3_core/docs/dev/nxp-integration.md
- 技術ノート（再び踏みそうな知見）:
docs/tech-notes.md
- ホストPC構築（LinkServer/LPCScrypt・ファームウェア切替・VCOM・ジャンパ）:
docs/host-setup.md
- 実機検証スナップショットと再実行手順:
docs/verification.md
- 動作確認済み: EVK-MIMXRT685、MCUXpresso SDK
mcuxsdk-manifests release/26.03.00、
arm-none-eabi-gcc 13.2.1、LinkServer（CMSIS-DAP）・J-Link 切替可
- 同型の移植スキル: asp3_stm32cube（STM32Cube HAL）、
asp3_fsp（Renesas RA / FSP）、
asp3_pico_sdk（Raspberry Pi Pico）
- ベアメタル版（SDK不使用・自前ブート）: asp3_core 本体の
target/mimxrt685evk_gcc
（Phase A。SDK版とは TrustZone/クロック/ブートが逆または別なので値を流用しないこと）
