feat(chip): 移植到 WCH CH57x（CH583 主目标 / CH572 极窄资源）——核对点与验收标准

[gqf2008]

目标：把内核移植到 WCH CH57x 系列（重点 CH583，兼顾极窄资源的 CH572），对齐 README「移植的芯片」清单里 RISC-V 一节。

两台机器同为 QingKe + PFIC + WCH 自有 SysTick 架构，且 PFIC(0xE000E000)/SysTick(0xE000F000) 基址与系统块寄存器（0x40001000 起）逐字节基本同址，
因此计划做成一份 ch57x 芯片层 + 一组差异常量，而不是两份独立移植。

已有资料（本地已核对，未入仓）：openwch/ch583 的 EVT/EXAM/{SRC,FreeRTOS,RT-Thread,HarmonyOS} 实装（startup_CH583.S / Link.ld / CH583SFR.h / core_riscv.h）与 openwch/ch570 的 CH572SFR.h / startup_CH572.S。

---

1. 与现有口的关系（选型结论）

基线取 src/chip/ch32v103，不是 ch32v307：V3A 与 V4A 的 PFIC+SysTick 模型同源（都靠 STK_CTLR.SWIE 触发软中断当 PendSV，都是 SR.CNTIF 写 0 清），
且都是「纯软件全保存」而非 WCH 硬件压栈路线（0x804 = 0，36 字帧，Direct mtvec）。
CH583 官方 FreeRTOS 口走的是硬件压栈+HPE 路线（("WCH-Interrupt-fast") 属性），Rust 侧表达不了，不采用。

2. 必须解决的增量（4 条）

1. 代码基址是 0x00000000，不是现有各 RISC-V 口的 0x08000000；且 EVT Link.ld 只给 448K（尾部留给 BootLoader/ISP/配置）。
   • 向量表第 5 个字（index 4）必须是私有 boot 标记 0xF3F9BDA9，不可改（BootLoader 靠它识别有效用户向量表）。
   • BootLoader 默认开启 → 量产配置须关掉，否则不直接跑用户程序。
2. .highcode 段（CH57x 特有）：WCH 约定 __attribute__((section(".highcode")))，VMA 在 RAM、LMA 在 FLASH，由 startup_*.S 逐字搬运；官方把所有 ISR + 高频函数塞进去（FLASH 取指有等待周期；且擦写 FLASH 期间代码不能跑在 FLASH 上）。
   riscv-rt 的 link.x 不会做 LMA→VMA 搬运 → 需要决策：(a) 先不用 .highcode（代码全留 FLASH，最省事，代价是 ISR 慢 + 不能在 RAM 里跑 ISR 以避 flash 操作冲突）；(b) 额外 linker script 段 >RAM AT>FLASH + 启动拷贝循环 + Rust 侧 #[link_section=".highcode"]。
3. 私有 CSR：0xbc0（流水线控制 + 动态分支预测控制位）CH583 写 0x1f、CH572 写 0x25 且另有 0xbc1=1；0x804（INTSYSCR）官方各自写 0x01/0x03。
   现有 ch32v103/ch32v307 口只写 0x804=0（关 HPE），没写 0xbc0 → 需确认 CH57x 上是否必须补。
4. delay_us() 当前实现用 mcycle。CH57x 若不实现 Zicntr/mcycle（读出来恒 0），现有实现会死循环。CH57x 无 DWT，备选是 SysTick/TMR 计时。

3. 双机差异（决定能否共用一份芯片层）

项	CH572	CH583
CIU 内核	QingKe（无 A 扩展 → 原子操作只能关中断/自旋锁）	QingKe V4A
CODE	240K（+BOOT 8K + INFO 8K）	512K
DATA	12KB（xISRStack 与任务栈全要挤）	32KB
SysTick 计数器	32 位（CNTL/CMPL）	64 位
软中断触发位	SR.SWIE(bit31)（CTLR 里没有）	CTLR.SWIE(bit31)
PFIC 复位寄存器	无 CFGR → 只能用 PFIC->SCTLR = 0x80000000	CFGR = PFIC_KEY3|(1<<7)
PFIC FastINT 寄存器名	VTFIDR/VTFADDR[4]	IDCFGR/FIADDRR[4]（同址同义改名）
IPRIOR 语义	priority ? 0x80 : 0（1 位抢占，无子优先级）	整字节：bit7 抢占 / bit6-4 子优先级
外设	1×UART / 1×SPI / 1×TMR / 无 ADC / 1×USB，另有 LCD·按键扫描·正交编码器·4 比较器	4×UART / 2×SPI / 4×TMR / ADC+温度 / 2×USB，另有触摸按键
中断号	Reset=0；外部尾部 …KEYSCAN=33, ENCODE=34, WDOG_BAT=35	Reset=1；尾部 TMR3=32, UART2=33, UART3=34, WDOG_BAT=35

（Core 槽完全一致：NMI=2、EXC=3、SysTick=12、SWI=14 可当 PendSV。）

4. 上板前必须核对（构建级已静态确认，板上行为待验）

• 0x00000000 是否可写 / 是否存在 0x08000000 别名
• mcycle 是否存在（决定 delay_us 走 mcycle 还是 SysTick/TMR）
• INTSYSCR(0x804) 写 0 后，中断入口是否确实不再硬件压栈（决定 36 字帧是否成立）
• csrw 0xbc0, 0x1f 是否必须 已按官方 SDK 确认（2026-09-19，PR feat(chip): 新增 WCH CH583(QingKe V4A) 移植骨架(构建级) #15）：EVT/EXAM/SRC/Startup/startup_CH583.S 的 reset 序列逐字写 li t0,0x1f; csrw 0xbc0,t0，本口保留；上板只需确认不触发 Illegal Instruction
• CTLR.SWIE 置 1 后是否真进 SysTick 入口、且 SR.CNTIF 仍为 0（CH572 需换到 SR 位置）。本项已升级（2026-09-19 独立审查）：官方 CH583 三套 RTOS 移植（FreeRTOS/RT-Thread/HarmonyOS）都不走 CTLR.SWIE（SDK 里只定义、零使用），一律用青稞专用 SWI_IRQn=14 + SW_Handler（FreeRTOS portYIELD() = PFIC_SetPendingIRQ(SWI_IRQn)）；本口沿用 ch32v103 模板的 SWIE，故上板要验的是"SWIE 可用 / 否则改走 IRQ 14"两条路
• BootLoader 是否拦截 启动头已复刻（2026-09-19，PR feat(chip): 新增 WCH CH583(QingKe V4A) 移植骨架(构建级) #15）：flash 0x00..0x17 = 入口跳转 + 向量表前 5 字，boot option 0xF3F9BDA9 落在 0x14（官方 Ld/Link.ld 把 .vector 的 flash LMA 摆在 .init 的 j handle_reset 之后，故不是 0x10 —— 本 issue 正文原写的 0x10 有误）；链接期 ASSERT 钉地址 + ci/check_ch583_boot.py 钉产物字节。实板仍需确认"是否确实进用户程序"
• WCH「SAM（Safe Access Mode）」寄存器：官方启动先写 R8_SAFE_ACCESS_SIG@0x40001040 = 0x57 → 0xA8 解锁，之后凡写 R8_RST_WDOG_CTRL/R8_PLL_CONFIG/R32_OSC32M_CTRL/R32_MISC_CTRL 等必须先解锁，否则写入被丢弃；R32_MISC_CTRL 还要按官方写法 &= ~7; |= 0x60000005

5. 验收标准

• 构建级：cargo build --example multitask_ch583 --features ch583,timer --target riscv32imac-unknown-none-elf --release 通过（✅ 2026-09-19，PR feat(chip): 新增 WCH CH583(QingKe V4A) 移植骨架(构建级) #15：已进门禁，并附启动头产物级校验），且 --features ch572 同构通过（✅ 2026-09-19，PR feat(chip): 新增 CH572(青稞无 A 扩展/RV32IMC)移植口 + 12K SRAM 栈账实测 #17：ch572 口落地，门禁含 riscv32imc 构建 + 启动头产物校验）；无 a 扩展时 riscv32imc-unknown-none-elf 也过。
  ✅ "riscv32imc 也过"已打通（2026-09-19，PR feat(arch): RISC-V 无 A 扩展目标的原子垫片(critical-section 收归一处) #16）：内核的原子读改写本就封装在 atomic-polyfill 里（arc/semaphore/notify），缺的只是 critical-section 的 RISC-V 实现——已收归 src/arch/riscv/critical.rs（存 mstatus.MIE → 关中断 → 按旧值恢复，单核语义）。同一 ch583 示例在 riscv32imc 下编译+链接通过，产物反汇编 0 条 AMO/LR/SC（有 A 的 imac 产物 12 条作阳性对照），门禁已含该目标构建。剩下的只是 CH572 口自身的差异常量（32 位 SysTick、软中断位在 SR、PFIC 无 CFGR、12K SRAM 的栈账）。
• 执行级（有板）：blink + UART printf + SysTick tick + 一个外设中断 → 再换 xtask：跑通现有 multitask_* 例程语义（优先级抢占 + 同优先级时间片 + IPC）。
• 若两者均通过，README 的「移植的芯片」清单加 CH32V? 风格两行（注明「构建级验证 / 真机待验」）。 ✅（2026-09-19，PR feat(chip): 新增 WCH CH583(QingKe V4A) 移植骨架(构建级) #15/feat(chip): 新增 CH572(青稞无 A 扩展/RV32IMC)移植口 + 12K SRAM 栈账实测 #17：已加 CH58x: ch583 与 CH57x: ch572 两行，均标注构建级验证/真机待验）

6. 参考

• openwch/ch583（Apache-2.0）：官方 SDK，EVT 自带 FreeRTOS / RT-Thread / HarmonyOS 三份移植（libcpu/WCH/Qingke_V4A/* 是最直接的内核对照）
• biemster/ch32fun_freertos（CC0）：ch5xx 的 FreeRTOS RISC-V port（port.c/portASM.S/portmacro.h）
• cnlohr/ch32fun（MIT）：examples_ch5xx/ 有 ch570_encoder_timer、ble_beacon、lowpower
• biemster/ch570_ble：BLE broadcaster + 闭源 libCH572BLE_PERI.a/libCH57xRF.a（BLE 先不带；这些库的 ISR 跑在中断上下文、栈需求大，12K SRAM 上尤其危险）

---

备注：本轮已完成的静态比对见工作区 pdfwork/ch583-xtask-port-guide.md（CH583 移植速查表）与 pdfwork/ch572-vs-ch583-diff.md（双机对照表），素材副本在 pdfwork/ch583src/、pdfwork/ch572src/。

补记（2026-09-19）：上述 pdfwork/* 素材不在仓库也不在工作区，审查者与后来读者无法复算（已按 startup_CH583.S/CH572SFR.h 等文件名全盘搜过，零命中）。寄存器常量与启动头布局现改按官方 openwch/ch583 EVT 源码逐条核对，出处写进 src/chip/ch583/port.{S,rs} 注释与 docs/README.md 的芯片手册表；本仓 ci/check_ch583_boot.py 把启动头布局钉成机器可检。

[gqf2008]

落地记录（2026-09-19）

PR #15（CH583 移植骨架 + 三轮审查整改）已合并进 main 并删除分支。合并后在我机复验：ch583 示例构建通过、启动头产物校验 PASS、bash ci/gate.sh 全绿（host 159 / 乒乓 200 轮 / kernel_tests 24×3 / smp 9/9）。

issue 里剩下的都是上板项：0x0 可写性/别名、mcycle、SWIE（官方三套移植走 SWI_IRQn=14，本口沿用模板的 SWIE，需实板确认或改走 IRQ 14）、0x804=0 是否真关硬件压栈、BootLoader 是否放行、复位默认主频。CH572 口与无 A 扩展的原子垫片仍未开工（后者是前置：riscv32imc 无 target_has_atomic，内核 RMW 编不过）。

[gqf2008]

落地记录（2026-09-19，PR #16）

无 A 扩展目标已打通：riscv32imc-unknown-none-elf 下同一 ch583 示例编译+链接通过，产物反汇编 0 条 AMO/LR/SC（imac 12 条作阳性对照）。做法：critical-section 的 RISC-V 实现收归 src/arch/riscv/critical.rs（mstatus.MIE 存取恢复，单核语义），门控放宽到全部 riscv32（因为 atomic-polyfill 对 riscv32imac 是 (Native, Polyfill) —— u64/i64 原子在有 A 的口上也要它）；门禁新增 imc 构建步骤并补齐预检/CI target。

于是本 issue 的"无 a 扩展时 riscv32imc 也过"这条已成立（已在上方验收标准处更新）。剩下的 CH572 工作是芯片差异常量：并行做 32 位 SysTick（CNTL/CMPL）、软中断位在 SR 而非 CTLR、PFIC 无 CFGR（只用 SCTLR）、12K SRAM 下的任务栈账（本机实测:默认任务 256 字 ≈1.19K 一个,idle 512 字,软件定时器任务 1024 字）。

[gqf2008]

CH572 口落地记录（PR #17，已合并进 master ed36956）

本 issue 的「构建级」验收已完成：CH57x 双机（ch583 主目标 / ch572 极窄资源）的移植口都在 master 上，门禁含 riscv32imac 与 riscv32imc 两条构建 + 三个产物的启动头字节校验。剩下的只有 §4 的真机项与 §5 的执行级（有板）验收。

PR #17 做了什么

• 新增 src/chip/ch572/（QingKe 无 A 扩展，RV32IMC）：32 位 SysTick（CNTL@+8 / CMPL@+16）、软中断触发位在 SR.bit31（SysTick_SR_SWIE）而非 CTLR、CTLR=0x0F（无 INIT 位）、私有 CSR 0xbc0=0x25 且 0xbc1=1、启动头与 ch583 同布局（魔数落 flash 0x14）。
• 12K SRAM 的栈账：src/chip/env.rs 把 idle/软件定时器任务栈做成按芯片取值（ch572 用 256 字），示例 examples/multitask_ch572.rs 按实测账配 5.5K 堆；ci/check_ch583_boot.py → ci/check_wch_boot.py（三产物共用）。
• 独立审查整改轮：示例去掉抄来的未用导入、脚本 docstring/FAIL 文案去芯片化、CSR 顺序注。

验证（可在本机复算）

• 官方 SDK 逐条对账（openwch/ch570 的 RVMSIS/core_riscv.h、StdPeriphDriver/inc/{CH572SFR.h,CH57x_common.h}、Startup/startup_CH572.S、Ld/Link.ld）：SysTick 结构体字段偏移、SysTick_SR_SWIE/CNTIF、SysTick_Config 的 CTLR=0x0F、0xbc0/0xbc1、FREQ_SYS=100MHz、240K/12K、SysTick_IRQn=12 与 PFIC_EnableIRQ（IENR[IRQn>>5]=1<<(IRQn&31)，IENR@PFIC+0x100）全部命中；CH572 的 SysTick_CTLR_* 没有 INIT 宏，故本口 0x0F 与 ch583 的 0x2F 之差有依据。
• 「魔数落 flash 0x14」不是转述：用官方 startup_CH572.S + Link.ld 现场链接复现 —— .init@0x00、.highcode LMA=0x04 / VMA=0x20000000、.vector 第 5 字 0xF3F9BDA9 → flash 0x14；. = ALIGN(1024) 确因 RAM 基址已 1024 对齐而无效果。
• 产物级：riscv32imc 产物 0 条 AMO/LR/SC（imac 12 条作阳性对照）；内存账 _sheap=0x20001180 + 堆 5.5K → 中断栈（_stack_start）余 2176B，示例注释里的 1.6K 余量成立。
• bash ci/gate.sh（合并前 + 合并后各一次）exit 0：host 159 passed、ISR 向量绑定 PASS、启动头校验 PASS×3、qemu_kernel_tests 24-24（含 -smp 2 与 tlsf 后端）、qemu_smp -smp 2 9-9、全部通过。

仍未完成（保持 open 的原因）

• §4 六条真机项一条未验：0x00000000 可写性/别名、复位默认主频（env 现按官方 FREQ_SYS=100MHz 配，但本口不做时钟初始化/SAM 解锁/PLL）、SR.SWIE 是否即刻进 SysTick 入口与 CNTIF 清法（官方 CH572 SDK 的 SysTick 只定义不用，备选改走 SWI_IRQn=14）、0x804=0 是否真关硬件压栈、mcycle 是否实现（未实现则 delay_us 死循环）、BootLoader 是否放行。
• §5 的执行级（blink + UART printf + tick + 外设中断 → multitask_* 语义）需要板子。

清单已同步：src/chip/ch572/mod.rs 头注与 examples/multitask_ch572.rs 顶部都列了这六条，README/CLAUDE.md/docs 的芯片清单与材料表也已登记（构建级验证 / 真机待验）。

[gqf2008]

ISA 事实核对（2026-09-19，官方 MRS 工程设置 + 产物指令数）

回应本 issue 里"无 A 扩展档位"的存疑，用官方工程设置（.cproject 的 RISC-V ISA 选项）钉死三家的 ISA：

芯片	option.target.isa.atomic	结论
CH583	true	有 A 扩展 → riscv32imac 正确（ch583 口无误）
CH572	false	无 A 扩展 → riscv32imc 正确（ch572 口正确）
ESP32-C3（顺带发现）	——	真身 RV32IMC；仓库此前按 riscv32imac 构建，产物实测含 12 条 A 扩展指令，真芯片执行到即非法指令 → 已改按真 ISA 构建并进门禁（PR #18，产物 0 条）

即:本 issue 的 CH572/CH583 目标选择都经官方工程设置背书;esp32c3 的错配是这一轮顺带修掉的。