已知边界与非目标

本文解释用 ws63-qemu 时必须知道的语义边界——它们大多不是缺陷，而是仿真器目标与物理/数据现实的边界。 不理解会误判结果。哪些外设建模到什么程度的事实表见 验证覆盖范围 与 外设建模矩阵。

语义边界（用之前必读）

1. 默认非周期精确，虚拟时间自由运行

TCG 不模拟流水线/cache/逐指令周期。需要可复现计时就用 ICOUNT=1，但那是 IPC=1 近似（≈250 MHz）， 不是真实微架构周期。真周期级请用 gem5 等，非本仿真器目标。这条取舍的背景见 设计取舍。

2. 掩膜 ROM 是桩的

WS63 应用核有一块片上掩膜 ROM（0x109000..0x14C000，厂商不发布二进制）。仿真器在 ws63_rom_call 里 仿真用到的 ROM 函数，**未识别的 ROM 地址返回 0（成功）**让固件不崩。代价：依赖 ROM 数据（非代码）的 功能无法重建——见下「ROM 数据墙」。清单见 ROM 桩目录。

3. -kernel 启动跳过 bootloader

直接把 app 装入 RAM，不经 flashboot，所以 flash XIP 窗口默认是空的，C SDK 的分区表 / NV 读取会失败 （[UPG] ...flash_start_addr fail、nv read sw fail）。解法：NV=1 回填分区表 + NV（见 运行固件）。但逐芯片出厂标定键（如 xo_trim 晶振温补）在生产时烧录，任何 构建产物的 NV 都没有，故 xo_trim ... nv read sw fail 一行固有残留，非缺陷。

4. 配置类外设是「影子」

寄存器可读回但无副作用——典型是 RF / PHY / 晶体等本质模拟量或物理硬件（RF_WB_CTL、SHARE_MEM、 SPACC/PKE/KM 等）。行为可内部计算的外设是真实的。为什么配置类只能是影子，见 外设建模矩阵 §配置类为何是影子。

5. 目标核 = 单核 RV32IMFC

单浮点（F）、压缩（C）、无原子（A 关）、无 D；WS63 是单核（无第二 hart）。 WS63 单核已经 fbb_ws63 C SDK 核实（ch2_system.md 明确「系统提供一个自研 RISC-V 处理器作为主控 CPU」； Wi-Fi/BT 是链接进同一应用镜像的库，HMAC/DMAC 是 Wi-Fi 软件分层而非两颗物理核）。

6. 时钟树按标称建模，频率相关的「错时钟/错波特」症状无法复现

QEMU 把时钟树建模在标称（post-clock_init）值（CPU 240 MHz、UART 160 MHz PLL、定时器 24 MHz TCXO、PLL 报告已锁）。这是 QEMU 的固有边界，不是可建模能解的缺陷，原因有三：

1. PLL 由掩膜 boot ROM 锁定——HAL clock_init 注释明确「CPU PLL（240 MHz）由 boot ROM 在 bootloader 之前配置」。-kernel 启动跳过 boot ROM，直接从 app 入口执行，此时已是「boot ROM 之后」状态，PLL 本就 应报已锁（恒报已锁是正确的；改成启动未锁反而错——probe_clocks() 会读到错值）。
2. TCG 不建模 CPU 频率——指令以宿主速度执行（-icount 仅 IPC=1 近似）。所以依赖 CPU 真实频率的忙等延时 （如 delay_ms 在低频启动时钟下变慢）在 QEMU 里不会变慢——这正是「非周期精确」（见 §1）的同一根因。
3. chardev 不限速——UART 字节无论分频器配成什么都照样发出，所以「错分频器→波特率乱码」在 QEMU 里也复现不了， 只能在写分频器时标注有效波特率（-d guest_errors，见 运行选项）。

能做与不能做：时钟源选择 / 门控已建模为状态并影响定时器/外设的模型频率（清定时器门会冻结定时器，已实测）； 但「跳过 clock_init 就在 QEMU 里也算错时序」这一行为复现不了——固件在 QEMU 里跑得「时序正确」不代表在硅片上正确。 真周期级请用 gem5 等。对应 issue #3（已说明并 close as not planned）；写分频器/CLK_SEL 时的诊断标注是现实上限。

ROM 数据墙——仍然受限的东西

ROM 里不仅有代码（可在宿主 C 里仿真），还有数据（vtable 数据、子系统常量、出厂标定），数据没有 dump 就无法重建。以下因「ROM 数据墙」仍受限（均非建模能解）：

• BT / WiFi / SLE 的射频（PHY/RF） —— 物理边界，不仿；C SDK 含 BT/WiFi 的 app 会在子系统深层初始化崩于 ROM 数据墙（vtable/NV/efuse/RF 标定无 dump），需在 config.py 注释 BGLE/BTH/WIFI_TASK_EXIST 裁剪这些任务。
• 逐芯片出厂标定 NV 键（如 xo_trim 晶振温补）——生产时烧录，任何构建产物的 NV 都不含，固有残留一行 xo_trim_temp_comp::nv read sw fail（非缺陷）。
• 看门狗中断模式回调（“kick timeout!”）：WDT 超时→复位已建模，但超时→中断回调→再复位未建模 （从虚拟时钟定时器回调改写 env->pc 注入固件回调不安全，定时器回调与 vCPU 取指边界不同步）。
• 真实密码学（AES/SHA/RSA 的 SPACC v2 描述符协议）——未在启动路径，按需扩展。

详见 ROM 桩目录 §C/§D。

冻结 / 非目标

均非建模能解或非本仿真器目标：

• RF / PHY 无线电仿真——不做；连接性若推进只到 MAC / SLIRP 边界（同 esp-qemu）。BS21/BS2X 的 BLE/SLE 连接性 为何也是死胡同，见 BS21 连接性可行性。
• 双核 / 第二 hart——WS63 单核（已核实），不做。
• 周期精确时序——TCG 非微架构；-icount 仅 IPC=1 近似。真周期级请用 gem5 等。
• snapshot / migration——按需，默认不投入。

FAQ

相关

• 哪些外设建模到什么程度 → 验证覆盖范围、外设建模矩阵
• ROM 桩清单 → ROM 桩目录
• 设计取舍的背景 → 设计取舍