e4981aa2f6
AGENTS.md stopped being the store of record for build steps, Python env, hardware pins, doc conventions, log cost and task ownership. Those facts already live in docs, skills and role files; the entry file now only points at them. This commit moves every reference that used to name the entry file to the authoritative landing point, so a reader who follows a link arrives at the fact instead of at a sentence that no longer exists. What changed is links and prose, not behaviour. Code, scripts and tests only have comment and docstring lines touched; the only non-comment edit in the whole changeset is one note string inside the generated pin table JSON, and its generator was changed in the same step so the two stay byte-identical. New landing points created before the references were retargeted: - The console single-writer log design doc, section 7.1, is now the single authority for log cost: about 90 B flash and 216 B stack per DBG_ line, and the rule that deep call chains must predefine DBG_LINE_BUF_MAX. It also carries the full list of the twelve translation units that have tightened it, plus the grep command that decides the truth if the list and the code ever disagree. - The document writing standard, section 2, now holds the BOM list. - keil-build skill gains an exit code table: 0 success, 1 build failure, 2 BuildEnvError, 3 usage, 4 build lock held. This corrects a belief that was never actually written down anywhere: exit 2 does not simply mean environment error, argparse also exits 2 and the wrapper script was remapped so the two no longer collide. Regenerated and checked byte for byte: - The end-to-end architecture SVG in docs/images from its generator. - tools/netlist_semantics/pinout_kb.json from gen_kb.py. Both are idempotent; running the generators again produces no diff. Deliberately not touched, because machines read them: - scripts/check_bom_drift.py joins every line containing BOM and asserts four paths are present, so the entry file BOM line must stay one line. - scripts/gen_task_table.py reads the TASK_TABLE anchors directly. - scripts/rename_maps and scripts/archive keep their historical wording; they describe what happened, not what is true now. Verified: doc links report the same six pre-existing findings as the base commit and no new ones, generated-fresh passes, bom drift is clean across 101 files, and AGENTS.md itself is unchanged in this commit.
131 lines
7.2 KiB
C
131 lines
7.2 KiB
C
/*
|
||
* 模块名称:模块级轻量断言宏(APP_ASSERT)
|
||
* 模块功能:给自研代码里"不该发生"的**内部不变量**一个统一出口——编译期整体
|
||
* 裁剪,生产构建零符号零开销;打开后与 configASSERT 共用同一个失败钩子。
|
||
* 规格出处:本头注释即规格正文(原专项文档已删除,2026-10-28;历史见 git log)。
|
||
* 早期示意稿自称"示意,非最终实现",本文件即落地实现;与示意稿的两处
|
||
* 差异见下方"落地差异"。
|
||
* 落地差异(相对早期示意稿,均为有意):
|
||
* 1. 断言点**不再额外发一条 DBG_ERROR**:钩子本身就打印 file:line(断言唯一有
|
||
* 价值的现场信息),而每条 DBG_* 调用点约 90 B Flash + 216 B 栈(见
|
||
* docs/子系统设计/控制台单写者日志设计.md §7.1);断言点又常处在"内核状态已不可信"的现场,走裸控制台
|
||
* 比走日志行缓冲更稳。
|
||
* 2. 本头落在 Drivers/BSP 根目录(与 dbg_log.h、bsp_err.h 同级),不是示意稿写的
|
||
* App/util:它是纯宏叶子能力(无状态、无数据、不依赖任何上层服务),BSP 与
|
||
* App 两侧都要用。放 App/util 会让 BSP 层新增一条"反向 include App 层头"的边,
|
||
* 而 layer-deps 门禁的存量基线只减不增,加不进去。落在 Drivers/BSP 已在 MCU
|
||
* (uvprojx IncludePath)与模拟器(simulator/CMakeLists.txt 的
|
||
* include_directories)双端 include 路径内 → **双端零工程文件改动**;主机侧
|
||
* 单测也因此直接用真头、不再造桩——假件与真头漂移正是"常量闸"要防的那类
|
||
* 自洽假绿(见 test/host/net_socket/run_unit_test.py 的注释)。
|
||
* ⚠ 本注释块内禁止出现"斜杠紧跟星号"的连写(Markdown 粗体收尾在路径末尾时最容易
|
||
* 撞上,例如目录通配那种写法):ARMCC 报 #9-D nested comment is not allowed,
|
||
* 而 /keil-build 的验收口径是 0 错误 **0 警告**(2026-10-25 首编即中招,已改)。
|
||
* 适用平台:STM32F407ZGTx(ARMCC v5,C99);PC 模拟器与主机侧单测(MSVC)同标准
|
||
* 作者:王建锋
|
||
* 创建日期:2026-10-25
|
||
* 修改记录:
|
||
* 2026-10-25 王建锋 创建(S12;试点 = Drivers/BSP/NET/net_socket.c 状态机不变量 2 处)
|
||
*/
|
||
|
||
#ifndef APP_ASSERT_H
|
||
#define APP_ASSERT_H
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
/* ============================================================================
|
||
* 一、编译期裁剪分级:两态(规格只给"生产关 / 调试开",不设中间档)
|
||
* ==========================================================================*/
|
||
|
||
/*
|
||
* 开关:**默认关闭 = 产品构建**。
|
||
* 打开方式 = 取消下一行注释。策略与 test/board/test_config.h 的
|
||
* ENABLE_DESTRUCTIVE_TESTS 同级:默认必须关闭,严禁以打开态提交。
|
||
* ⚠ 关闭态是 /keil-build 的验收口径:"0 错误 0 警告" 且 .map 无新增符号
|
||
* (规格 §2.1 完成判据)。本宏不新增任何 .c,故不涉及双端注册。
|
||
*/
|
||
//#define APP_ASSERT_ENABLE
|
||
|
||
/* ============================================================================
|
||
* 二、打开态:失败交"与 configASSERT 同一个出口"
|
||
* ==========================================================================*/
|
||
#ifdef APP_ASSERT_ENABLE
|
||
|
||
#if defined(__arm__) || defined(__CC_ARM)
|
||
/*
|
||
* MCU 端:Inc/FreeRTOSConfig.h 的 configASSERT 用的就是这个钩子——实现见
|
||
* Src/freertos.c 的 USER CODE Application 区(裸控制台打
|
||
* "[ERR] ASSERT FAILED <file>:<line>" 后 NVIC_SystemReset())。
|
||
* 应用层断言复用同一钩子 → 台架上"断言是怎么死的"只有一种形态,不必再造
|
||
* 第二条复位路径。这里**不** include FreeRTOSConfig.h:本头必须能被看不见
|
||
* RTOS 的编译单元包含(模拟器 / 主机侧单测就是这种)。声明与
|
||
* FreeRTOSConfig.h 原文同签名——重复声明合法,真漂移了由链接器兜底。
|
||
*/
|
||
extern void vApplicationAssertFailed(const char *file, long line);
|
||
#define APP_ASSERT_FAIL(p_file, line) vApplicationAssertFailed((p_file), (long)(line))
|
||
#else
|
||
/*
|
||
* 宿主端(PC 模拟器 / 主机侧单测):没有 RTOS、也没有可复位的外设看门狗,
|
||
* 正确形态是"现场写 stderr 然后 abort()"——非零退出码,任何一键回归都会
|
||
* 判失败,不会被"静默继续"把断言吞成一条日志。
|
||
*/
|
||
#include <stdio.h>
|
||
#include <stdlib.h>
|
||
#define APP_ASSERT_FAIL(p_file, line) do { \
|
||
(void)fprintf(stderr, "[ASSERT] FAILED %s:%d\r\n", (p_file), (int)(line)); \
|
||
(void)fflush(stderr); \
|
||
abort(); \
|
||
} while (0)
|
||
#endif /* __arm__ || __CC_ARM */
|
||
|
||
/*
|
||
* 断言宏(打开态):条件为假 → 交 APP_ASSERT_FAIL 处置。
|
||
* 包成 do { } while (0) 以适配"单条语句"位置;条件只求值一次。
|
||
*/
|
||
#define APP_ASSERT(cond) do { \
|
||
if (!(cond)) { \
|
||
APP_ASSERT_FAIL(__FILE__, __LINE__); \
|
||
} \
|
||
} while (0)
|
||
|
||
/* ============================================================================
|
||
* 三、关闭态(默认):代码消失,但表达式的类型检查保留
|
||
* ==========================================================================*/
|
||
#else /* !APP_ASSERT_ENABLE */
|
||
|
||
/*
|
||
* 与示意稿的 ((void)0) 同样"零代码零符号",但用 sizeof 把条件留在编译期的
|
||
* 类型检查里:sizeof 的操作数是**不求值上下文**(不生成代码、不产生副作用),
|
||
* 于是断言写错变量名 / 写错比较类型时,生产构建也会当场报错——否则"生产裁掉
|
||
* 断言"等于"这条表达式从没被编译器看过",要等到哪天有人打开开关才炸。
|
||
* 附带好处:只在断言里出现的变量不会被 ARMCC 判成"set but never used"。
|
||
*/
|
||
#define APP_ASSERT(cond) do { (void)sizeof(!!(cond)); } while (0)
|
||
|
||
#endif /* APP_ASSERT_ENABLE */
|
||
|
||
/* ============================================================================
|
||
* 四、使用纪律(规格 §2.1 的三条 + 落地补两条;错用是常态,故随头常驻)
|
||
* ==========================================================================*/
|
||
/*
|
||
* 1. **不得**在中断上下文或高频路径使用——打开态每次失败都要打印并复位;
|
||
* 本宏服务"逻辑上不可能",不是"偶尔会失败"。
|
||
* 2. **不得**替代正常错误返回:外部输入、对端数据、芯片返回值一律走错误码
|
||
* (约定见 Drivers/BSP/bsp_err.h 与 net_* 的返回契约)。断言只写内部不变量
|
||
* ——即"为假就说明我们自己写错了"的状态机 / 指针来源 / 字段配对关系。
|
||
* 3. 生产构建关闭(与 ENABLE_DESTRUCTIVE_TESTS 同级):要开就在本地或测试构建
|
||
* 里打开,**跑完必须还原成注释态**。
|
||
* 4. 断言条件**不得带副作用**:关闭态不求值、打开态才求值,带副作用等于让行为
|
||
* 随开关漂移——这是本宏唯一真正危险的误用形态。
|
||
* 5. 台架口径:MCU 钩子打印以 [ERR] 开头 → 真机上断言一旦触发,/serial-boot-test 必然判本次
|
||
* 失败,这是刻意的(Forbidden 标记含 [ERR] / 出现 Fault 即不通过)。
|
||
*/
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
|
||
#endif /* APP_ASSERT_H */
|