| name | asp3-core-ops |
| description | asp3_core リポジトリ固有の運用（ビルド・QEMU/実機実行・TAPテスト・構造化ログ(slog)解析・TTSP3適合性テスト・上流マージ台帳）の具体コマンドとツール。CMakeプリセットでビルドするとき、QEMU(mps2_an505/mps2_an386/mps3_an547/zcu102/polarfire 等)で動かすとき、`--tap`/`--slog` を使うとき、`scripts/parse_slog.py`/`check_events.py` でトレースを解析するとき、`test/ttsp/run_ttsp.py` で TTSP3 を回すとき、`DIVERGENCE_MAP.md`/`UPSTREAM_PRISTINE.txt`/`docs/dev/cfg-spec-map.md` を扱うとき、SAFEG(`ENABLE_SAFEG_M`)ビルドを確認するとき、ARM-M実機で性能評価（DWT CYCCNT・`USE_ARM_DWT_PMCNT` で ns 精度の histogram／`PERF_DWT.md`）を行うときに使う。実機(SWD/JTAG)でロード実行・テストするとき＝OpenOCD(rp2350.cfg/rp2350-riscv.cfg)・`--target run`/`swd-run`/`osdebug`・移植検証テスト(`test/porting` の `# 6/6 passed`)・機能テスト全件(`scripts/ci/run_board_pico2.sh` で testexec)・pico2_arm/pico2_riscv/stm32mp257f_dk 実機・`gh run watch` でのCI確認 にも使う。**規約の正本は `AGENTS.md`。TOPPERS共通の概念は別skill `toppers-kernel-dev`/`toppers-kernel-debug`/`toppers-asp`。本skillはasp3_core固有の具体手順だけを補う。** |
asp3_core 運用ツール（リポジトリ固有）
このリポジトリ（TOPPERS/ASP3 Core）で実際に使う具体コマンド・ツール・台帳ファイルの
早見。概念・規約は他で正本化されているので、ここは「このリポジトリでの叩き方」に徹する。
正本・概念へのリンク（先に読む）
- 規約・手順の正本：このリポジトリの
AGENTS.md（§4 ビルド・§8 構造化ログ・§10 上流マージ・§2 禁則）。
- TOPPERS共通の概念（実装非依存）：
- カーネル作業規約・上流追従 → skill
toppers-kernel-dev
- 不具合切り分け・観測・TTSP3概念 → skill
toppers-kernel-debug
- アプリのAPI/静的API/エラー辞書 → skill
toppers-asp
- 詳細手順：
docs/building.md（ビルド）・docs/dev/（機能ごとの経緯）・test/ttsp/README.md（TTSP3）。
1. ビルド（CMakeプリセット）
cmake --list-presets
cmake --preset linux -B build/linux && cmake --build build/linux
timeout 5 ./build/linux/asp --tap
ctest --preset linux
cmake --preset mps2_an505-qemu -B build/mps2_an505-qemu && cmake --build build/mps2_an505-qemu
timeout 30 qemu-system-arm -M mps2-an505 -cpu cortex-m33 \
-kernel build/mps2_an505-qemu/asp.elf \
-semihosting -semihosting-config enable=on,target=native -nographic
cmake --build --preset run-mps2_an505-qemu
- プリセット名＝ターゲット名から
_gcc を除いたもの。QEMU/実機両対応はQEMU側を -qemu。
- QEMUマシン名はハイフン（
mps2-an505）、ASP3ターゲット名はアンダースコア（mps2_an505_gcc）。
- 対応ターゲット・コマンドの全量は
AGENTS.md §4 と docs/building.md。
- SAFEG（ARMv8-M TrustZone Dual-OS）：
-DENABLE_SAFEG_M=ON で有効化（既定OFF＝素ASP3不変）。
対象は mps2_an505 / pico2_arm / mimxrt685evk（各 *_safeg.ld＋SAU/NS_VTOR を target に同梱）。詳細は docs/dev/safeg.md。
-DENABLE_SAFEG_IMPLIB=ON：gate(cmse_nonsecure_entry)を持つアプリで CMSE import lib secure_nsclib.o を最終ELFに生成（NS がリンク）。gate無アプリ(sample)では "no symbols" 失敗するため opt-in（既定OFF）。- Secure+NS の遷移テスト(test/) を実機で回す手順（test_safeg ビルドレシピ／NS の TST_ENABLE／2イメージ書込み／
[TST] 取得／imxrt685 の RESET自走+capture先行／RP2350 の SWD-lock→UF2／QEMU の INVEP 限界）は SafeG-M リポの skill safeg-m-ops（asp3_core はベース／ビルド基盤を提供する側）。
2. 構造化ログ（slog）でのデバッグ
timeout 5 ./build/linux/asp --slog 2>&1 | python3 scripts/parse_slog.py
timeout 5 ./build/linux/asp --slog 2>&1 | python3 scripts/parse_slog.py --json > actual.jsonl
python3 scripts/check_events.py test/porting/expected/<name>.json actual.jsonl
イベント形式 T=<tick_us>,EV=<event>,... と全イベント種別は
references/slog-events.md（asp3_core 固有の出力仕様）。
切り分けの考え方（症状→原因）は skill toppers-kernel-debug。
3. TTSP3 適合性テスト
python3 test/ttsp/run_ttsp.py --target mps2_an505 --tap api_test/ASP
python3 test/ttsp/run_ttsp.py --target mps2_an505 --tap api_test/ASP/staticAPI
ドライバ test/ttsp/run_ttsp.py のオプション・並列実行・SKIP判定は
references/ttsp3-driver.md。経緯は docs/dev/ttsp3-conformance.md。
TTSP3 の概念・PASS/FAIL/SKIP の意味は skill toppers-kernel-debug。
実機 HW で回す（--target <t>_hw）：QEMU の代わりにデバッガでロード実行する。
PolarFire SoC Discovery Kit は §7 と target/polarfire_soc_kit_gcc/TTSP3_HOWTO.md
（SoftConsole openocd+gdb・reset init なし・staticAPI 123/6/9・semaphore 73/0/44）。
4. 上流マージの台帳（このリポジトリの実ファイル）
| ファイル | 役割 |
|---|
UPSTREAM_VERSION | 現在ベースの上流ASP3バージョン |
DIVERGENCE_MAP.md | 上流乖離台帳（ファイル単位・PRISTINE/EXTENDED/DIVERGED/NEW） |
UPSTREAM_PRISTINE.txt | 上流そのまま＝上書きしてよいファイル一覧 |
kernel/kernel_api.def | 静的API構造の正本（接頭辞DSL） |
docs/dev/cfg-spec-map.md | cfg（Python）の上流追従台帳（CFG_SPEC_MAP） |
手順は AGENTS.md §10、考え方は skill toppers-kernel-dev。
5. 検証の鉄則（再掲）
- 変更したら必ず
cmake --build が通ることを確認してから報告。
- テストは TAP（
ok/not ok） で機械判定。# SKIP は想定スキップ。
- 実行結果を根拠に報告する。「動くはず」は禁止。
compile_commands.json をルートにリンク維持：
ln -sf build/<preset>/compile_commands.json compile_commands.json。
6. 性能評価（DWT CYCCNT・ns精度 histogram）
ARM-M 実機で syssvc/histogram の計測時間源を DWT CYCCNT サイクルカウンタに
差し替え、ns 精度で実行時間分布を採る。概念・対象ボード・変換式（cycles→ns）・
レジスタは arch/arm_m_gcc/common/PERF_DWT.md（このリポ）。汎用の考え方（histogram
の時間源差し替え／エミュレータは性能カウンタを実装しないことが多い）は skill
toppers-kernel-debug。
- オプトインフラグ：
USE_ARM_DWT_PMCNT（arm_gcc の USE_ARM_PMCNT と同型）。
未指定の通常ビルドは既定の fch_hrt（μs精度）＝無影響。
- 実機専用：QEMU の ARM-M は DWT CYCCNT を実装せず常に 0（
DWT_CTRL.NOCYCCNT=0
で「実装あり」に見える罠）。QEMU では指定しない（指定すると全計測 0）。
- 対象：
core_syssvc.h を取り込む ARM-M 実機。asp3_core 本体は pico2_arm /
mimxrt685evk。SDK統合リポは RA6M5/RA8M2(asp3_fsp)・RT685/MCXN947(asp3_mcuxsdk)・
pico2_arm_sdk(asp3_pico_sdk)。RISC-V(pico2_riscv 等)は DWT 非対象。
R=$(pwd)
cmake -S . -B build/perf0-pico2 --preset pico2_arm \
-DASP3_APPLDIR=$R/test -DASP3_APPLNAME=perf0 \
"-DASP3_EXTRA_APP_C_FILES=$R/syssvc/test_svc.c;$R/syssvc/histogram.c" \
"-DASP3_EXTRA_COMPILE_DEFS=USE_ARM_DWT_PMCNT"
cmake --build build/perf0-pico2
- 新ボードで有効化する手順（target_syssvc.h で
core_syssvc.h を取り込み、
HIST_CONV_TIM をクロック依存で与える）は PERF_DWT.md を参照。
- フラグ off でも
core_syssvc.h は空＝回帰しない。perf 経路の手早いコンパイル検証は
compile_commands.json の core_kernel_impl.c/histogram.c のコマンドに
-DUSE_ARM_DWT_PMCNT -fsyntax-only を足して再実行（SDK統合リポで実機が無いとき有効）。
7. 実機ブリングアップ（PolarFire SoC Discovery Kit / U54・RV64GC）
asp3 は mpfs_hal の system_startup を持たず、HSS が起動時に設定した MSS IO・クロックに
依存する。実機（JTAG 起動）では次の要点で起こす（詳細・落とし穴は
target/polarfire_soc_kit_gcc/REALBOARD_BRINGUP.md）：
-DPOLARFIRE_DISCOVERY=ON … Discovery ボード選択（コンソール=MMUART1・L2-LIM リンカ）。- L2-LIM(0x08000000) リンク（
polarfire_soc_kit_lim.ld）… DDR 学習不要のデバッグロード領域。
reset init をしない … monitor halt→load→PC=start→continue。reset init は HSS の
MSS IO 設定を壊し MMUART1 が無音になる。- 起動時 CLINT MSIP クリア（
chip_initialize で実装済み）… HSS 残存の MSIP が MSIE 許可時に
発火して未登録割込みになるのを防ぐ（FMP3 の clear_msip 相当）。
ロード手段は SoftConsole openocd + gdb。HW TTSP3 は §3 と TTSP3_HOWTO.md。
TOPPERS 共通の概念（前段ブートFW依存・デバッガ観測・MP→SP の割込み残留）は
skill toppers-kernel-debug/toppers-kernel-dev。
8. 実機ロード実行・移植検証・testexec（pico2/stm32）
新ターゲットを実機で起こす／回帰するときの叩き方は
references/onboard-run.md：
- ボード別 OpenOCD cfg と
--target run/swd-run の使い分け
- OpenOCD の作法（
pkill -x openocd・シリアルは書込み前に開く）
- 移植検証テスト
test/porting（tap.c を ASP3_EXTRA_APP_C_FILES で足す・
# 6/6 passed 判定・故障切り分け順）
- 機能テスト全件
scripts/ci/run_board_pico2.sh（testexec の実機ランナ・逐次実行・
OBJ削除のタイミング）
- osdebug（実機は
monitor resume/halt＋flush register-cache）
gh run watch でのCI確認・実機で踏んだ落とし穴（UARTドレイン・ld LMAずれ・
Hazard3優先度スタック・QEMU版依存）
references/
