/*
 * 模块名称：模块级轻量断言宏（APP_ASSERT）
 * 模块功能：给自研代码里"不该发生"的**内部不变量**一个统一出口——编译期整体
 *          裁剪，生产构建零符号零开销；打开后与 configASSERT 共用同一个失败钩子。
 * 规格出处：本头注释即规格正文（原专项文档已删除，2026-10-28；历史见 git log）。
 *          早期示意稿自称"示意，非最终实现"，本文件即落地实现；与示意稿的两处
 *          差异见下方"落地差异"。
 * 落地差异（相对早期示意稿，均为有意）：
 *   1. 断言点**不再额外发一条 DBG_ERROR**：钩子本身就打印 file:line（断言唯一有
 *      价值的现场信息），而每条 DBG_* 调用点约 90 B Flash + 216 B 栈（AGENTS
 *      「日志不是免费的」）；断言点又常处在"内核状态已不可信"的现场，走裸控制台
 *      比走日志行缓冲更稳。
 *   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 必然判本次
 *    失败，这是刻意的（AGENTS「Forbidden 标记含 [ERR]」/ 出现 Fault 即不通过）。
 */

#ifdef __cplusplus
}
#endif

#endif /* APP_ASSERT_H */