拓冰网站定制 
English version:en/06-pitfall-cheatsheet.md本篇对应源码main/kmcu.c·main/main.c·sdkconfig.defaults·docs/milestones.md本项目的所有坑汇总。遇到问题先来这里按「症状」检索。环境详见 01#症状原因解决1cannot read spec file E:/\x0a/...项目路径含中文构建副本放纯 ASCII 路径C:\kmcu2fatal error: bits/cconfig.h工具链路径超 MAX_PATH(260)subst X:短盘符 CONFIG_COMPILER_CXX_RTTIy3git 卡在 esp32-wifi-libHTTP 423Gitee 封锁该子模块IDF_SKIP_CHECK_SUBMODULES14标准库头文件编译错默认 picolibc 兼容问题CONFIG_LIBC_NEWLIBy5CONFIG_SPIRAM_MODE_QUAD无效P4 的 PSRAM 是八线CONFIG_SPIRAM_MODE_HEX6所有优化收益远低于理论默认-Og压制循环优化CONFIG_COMPILER_OPTIMIZATION_PERFy7idf.py 报 venv 路径不一致退出build 用 X: venv 配置把X:\python_env\...\Scripts放 PATH 最前TF 卡详见 03#症状原因解决8双重 deinit 崩溃Instruction access faultesp_vfs_fat_sdmmc_mount失败时内部已 deinit失败后不要再调sdmmc_host_deinit()9TF 卡无响应CMD1 超时默认 slot 把 GPIO45 当 D4 抢走它是卡电源开关显式slot.width 4供电GPIO45 0低有效推理 / 脚手架详见 03#症状原因解决10序列与参考对不上贪心循环把生成结果写回 prompt 覆盖先预处理整条 prompt再自回归11每步打印寄存器转储计算型任务不喂狗CONFIG_ESP_TASK_WDT_ENn12printf 输出错乱riscv32 的uint32_t是unsigned long用PRIu32或显式转unsigned性能 / 编译器详见 04#症状原因解决13unroll 只换来 4%行对齐反而变慢全程-Og切-O2坑 6 的延伸最隐蔽17decode 20.6s/token慢得离谱全流式每 token 重读全量权重SD_STREAM方案 BSD_RESIDENT权重常驻 PSRAM只流式读 embed131×数值 / fp16 转换详见 13#症状原因解决16板端 argmax 翻转如 650→1306PC 参考一致km_f16_to_f32subnormal 分支指数误写-15应为-1414.2% 的 scale 被减半改127-14-ePIE 汇编详见 05#症状原因解决14illegal operands esp.srs.s.xacc t2,t1PIE 标量操作数不能用 t0-t2x5-x7用 a0-a7 或 t3x2815随机数据对拍正确、真实权重全错scratch 的 int16 缓冲未 16 字节对齐heap_caps_aligned_alloc(16, ...)四条最重要的经验-Og是隐形杀手它会系统性压低所有性能读数且不会报错。做性能优化前先确认构建在-O2。「随机数据对拍通过」≠「实现正确」量化满量程、dot 大值才暴露对齐/溢出类 bug。对拍要覆盖满量程输入和真实权重。实测胜于推论理想化的「向量化 8×」在带宽受限的 CPU 上是误导。纯计算 21× 的 PIE接入后只有 2.11×——每一步都用板端硬数据界定。手写 fp16→fp32 转换必须单独验证 subnormal 分支normal 分支对拍测不出 subnormal 的指数 off-by-one-15vs-14而它能把 14.2% 的 scale 减半、翻转 argmax。「量化精度导致翻转」这类归因先用同量化权重的 PC 参考做逐 GEMV 模拟排除量化嫌疑。对应源码文件关键符号 / 位置支撑本文哪部分main/kmcu.ckm_f16_to_f32()坑 16 fp16→fp32 subnormal 指数 off-by-onemain/main.cheap_caps_aligned_alloc(16, ...)、PRIu32坑 15 scratch 对齐 / 坑 12 printfsdkconfig.defaultsCONFIG_COMPILER_OPTIMIZATION_PERF、CONFIG_SPIRAM_MODE_HEX、CONFIG_ESP_TASK_WDT_EN坑 5/6/11 配置类docs/milestones.mdesp_vfs_fat_sdmmc_mount、sdmmc_host_deinit()坑 8 双重 deinit 崩溃docs/agent_loop_router.mdidf.py --no-ccache坑 1/2 构建环境三坑《Kestrel-MCU 手记》· 全系列 28 篇在 ESP32-P4 上从零训练并部署 32M~64M 参数 MoE 大模型5.7~6.4 tok/s源码、权重、训练脚本与全部文章开源可复现。仓库https://gitee.com/pei-xiaoguang/kestrel-llm-mcu · 觉得有用欢迎 Star 06 · ESP32-P4 跑 LLM 踩坑速查表：环境、量化、内核、性能问题一网打尽
English version:en/06-pitfall-cheatsheet.md本篇对应源码main/kmcu.c·main/main.c·sdkconfig.defaults·docs/milestones.md本项目的所有坑汇总。遇到问题先来这里按「症状」检索。环境详见 01#症状原因解决1cannot read spec file E:/\x0a/...项目路径含中文构建副本放纯 ASCII 路径C:\kmcu2fatal error: bits/cconfig.h工具链路径超 MAX_PATH(260)subst X:短盘符 CONFIG_COMPILER_CXX_RTTIy3git 卡在 esp32-wifi-libHTTP 423Gitee 封锁该子模块IDF_SKIP_CHECK_SUBMODULES14标准库头文件编译错默认 picolibc 兼容问题CONFIG_LIBC_NEWLIBy5CONFIG_SPIRAM_MODE_QUAD无效P4 的 PSRAM 是八线CONFIG_SPIRAM_MODE_HEX6所有优化收益远低于理论默认-Og压制循环优化CONFIG_COMPILER_OPTIMIZATION_PERFy7idf.py 报 venv 路径不一致退出build 用 X: venv 配置把X:\python_env\...\Scripts放 PATH 最前TF 卡详见 03#症状原因解决8双重 deinit 崩溃Instruction access faultesp_vfs_fat_sdmmc_mount失败时内部已 deinit失败后不要再调sdmmc_host_deinit()9TF 卡无响应CMD1 超时默认 slot 把 GPIO45 当 D4 抢走它是卡电源开关显式slot.width 4供电GPIO45 0低有效推理 / 脚手架详见 03#症状原因解决10序列与参考对不上贪心循环把生成结果写回 prompt 覆盖先预处理整条 prompt再自回归11每步打印寄存器转储计算型任务不喂狗CONFIG_ESP_TASK_WDT_ENn12printf 输出错乱riscv32 的uint32_t是unsigned long用PRIu32或显式转unsigned性能 / 编译器详见 04#症状原因解决13unroll 只换来 4%行对齐反而变慢全程-Og切-O2坑 6 的延伸最隐蔽17decode 20.6s/token慢得离谱全流式每 token 重读全量权重SD_STREAM方案 BSD_RESIDENT权重常驻 PSRAM只流式读 embed131×数值 / fp16 转换详见 13#症状原因解决16板端 argmax 翻转如 650→1306PC 参考一致km_f16_to_f32subnormal 分支指数误写-15应为-1414.2% 的 scale 被减半改127-14-ePIE 汇编详见 05#症状原因解决14illegal operands esp.srs.s.xacc t2,t1PIE 标量操作数不能用 t0-t2x5-x7用 a0-a7 或 t3x2815随机数据对拍正确、真实权重全错scratch 的 int16 缓冲未 16 字节对齐heap_caps_aligned_alloc(16, ...)四条最重要的经验-Og是隐形杀手它会系统性压低所有性能读数且不会报错。做性能优化前先确认构建在-O2。「随机数据对拍通过」≠「实现正确」量化满量程、dot 大值才暴露对齐/溢出类 bug。对拍要覆盖满量程输入和真实权重。实测胜于推论理想化的「向量化 8×」在带宽受限的 CPU 上是误导。纯计算 21× 的 PIE接入后只有 2.11×——每一步都用板端硬数据界定。手写 fp16→fp32 转换必须单独验证 subnormal 分支normal 分支对拍测不出 subnormal 的指数 off-by-one-15vs-14而它能把 14.2% 的 scale 减半、翻转 argmax。「量化精度导致翻转」这类归因先用同量化权重的 PC 参考做逐 GEMV 模拟排除量化嫌疑。对应源码文件关键符号 / 位置支撑本文哪部分main/kmcu.ckm_f16_to_f32()坑 16 fp16→fp32 subnormal 指数 off-by-onemain/main.cheap_caps_aligned_alloc(16, ...)、PRIu32坑 15 scratch 对齐 / 坑 12 printfsdkconfig.defaultsCONFIG_COMPILER_OPTIMIZATION_PERF、CONFIG_SPIRAM_MODE_HEX、CONFIG_ESP_TASK_WDT_EN坑 5/6/11 配置类docs/milestones.mdesp_vfs_fat_sdmmc_mount、sdmmc_host_deinit()坑 8 双重 deinit 崩溃docs/agent_loop_router.mdidf.py --no-ccache坑 1/2 构建环境三坑《Kestrel-MCU 手记》· 全系列 28 篇在 ESP32-P4 上从零训练并部署 32M~64M 参数 MoE 大模型5.7~6.4 tok/s源码、权重、训练脚本与全部文章开源可复现。仓库https://gitee.com/pei-xiaoguang/kestrel-llm-mcu · 觉得有用欢迎 Star