#!/usr/bin/env python3 # -*- coding: utf-8 -*- """BSP 错误码与超时命名约定检查（机械检查那一半）。 为什么要有这个脚本：约定写在 docs 里不会自己生效。同一层的驱动今天并存六套返回约定， 而"能不能重试"只写在个别注释里；叫 *_TIMEOUT 的东西里既有真毫秒（单位靠不统一的 _MS 后缀表达）、 也有**返回码**。没有机械检查，新代码只会继续按各自旧习惯长。 四条检查（每项一个自描述标签 = 基线键的第二字段，格式是「文件|标签|名字」）： err-type 公开 API 不得返回 HAL_StatusTypeDef / bool bool 把"为什么失败"整条丢掉；HAL 枚举把 HAL 焊进调用方的 include 链。 timeout-name *_TIMEOUT 宏不得取负值 名字叫 TIMEOUT 却是返回码，读代码的人会当成时长；超时应返回 BSP_ERR_TIMEOUT。 return-doc 非 void 的公开 API 必须在紧邻注释块里写「返回值：」 约定要能被读到，才算约定（也才谈得上审查）。匹配时忽略空格：规范 V1.0 允许列对齐写法 「返 回 值：」，门禁不去规定排版。 consume-result 返回错误码的函数，调用点必须**接住返回值**或**显式 (void) 丢弃** 名单自动取，不手写：① 返回 bsp_err_t 的公开 API（契约规定它就是错误码）； ② 返回 int/int32_t 且文档块出现"错误码 / 失败 / BSP_ERR"的函数（覆盖 GD5F 私有码族）； ③ 已知返回 HAL_StatusTypeDef 的 HAL 传输/读写族；④ 上面 ①② 同一套启发式再扫一遍 .c 里的 static 定义（只扫头文件等于只守跨编译单元的边界）。为什么单列：实测 ARMCC v5 不认 warn_unused_result、cppcheck 也不报这类丢弃（都在本仓实跑验证过）——**丢弃底层传输的 返回值，今天没有任何工具会响**。已知限度：只认单行整句的裸调用（行尾注释允许），跨行写的暂测不到。 术语迁移（2026-10-23）：这四项原先叫 R1/R2/R3/R4，已整体改名。原因是 R1~R8 在本仓是"专项 风险"的裸形编号（scripts/id_registry.json 已登记那一族，保护规划与看门狗的风险表都在用）、 带连字符的那一族又是审查报告的可靠性 / 内存优化项编号——**同一个裸形四种意思**，而编号门禁 因为 docs/编号规范.md §4.3 的同号不同义白名单不会报， 等于机器放行、人看不懂。旧名到新名对照：R1=err-type、R2=timeout-name、R3=return-doc、 R4=consume-result；已提交的文档与变更记录里出现的老名按"冻结历史不回改"处理，以本对照为准。 增量拦截（与 layer-deps / id-check 同构）：BASELINE 钉住存量，只减不增，没有 --write。 修完一条跑 --prune，它会点名"这条已消失，请从 BASELINE 删除"。 退出码：0 = 通过；1 = 有新增违规；2 = 用法或扫描错误。 """ import argparse import re import subprocess import sys from pathlib import Path ROOT = Path(__file__).resolve().parent.parent EXCLUDE = ("lftpd/",) # 存量基线（2026-10-23 清点）："文件|规则|名字"。修掉一条删一行，不要往里加。 BASELINE = frozenset( line.strip() for line in """ Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c|consume-result|HAL_SPI_Receive#1 Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c|consume-result|HAL_SPI_Receive#2 Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c|consume-result|HAL_SPI_Receive#3 Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c|consume-result|HAL_SPI_Transmit#1 Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c|consume-result|HAL_SPI_Transmit#10 Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c|consume-result|HAL_SPI_Transmit#11 Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c|consume-result|HAL_SPI_Transmit#2 Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c|consume-result|HAL_SPI_Transmit#3 Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c|consume-result|HAL_SPI_Transmit#4 Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c|consume-result|HAL_SPI_Transmit#5 Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c|consume-result|HAL_SPI_Transmit#6 Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c|consume-result|HAL_SPI_Transmit#7 Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c|consume-result|HAL_SPI_Transmit#8 Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c|consume-result|HAL_SPI_Transmit#9 Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c|consume-result|gd5f_bbt_save#1 Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c|consume-result|gd5f_block_erase#1 Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c|consume-result|gd5f_page_read#1 Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c|consume-result|gd5f_program_exec#1 Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c|consume-result|gd5f_program_load#1 Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c|consume-result|gd5f_read_from_cache#1 Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c|consume-result|gd5f_read_status#1 Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c|consume-result|gd5f_read_status#2 Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c|consume-result|gd5f_read_status#3 Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c|consume-result|gd5f_wait_busy#1 Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c|consume-result|gd5f_write_enable#1 Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c|consume-result|gd5f_write_enable#2 Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c|consume-result|gd5f_write_enable#3 Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c|consume-result|gd5f_write_enable#4 Drivers/BSP/GD5F2GQ5UE/nand_ftl.c|consume-result|gd5f_write_enable#1 Drivers/BSP/RS485/rs485.c|consume-result|rs485_receive_start#1 Drivers/BSP/RS485/rs485.c|consume-result|rs485_receive_start#2 Drivers/BSP/UI/ui_content_page.h|err-type|ui_content_page_open Drivers/BSP/UI/ui_net_sink.c|consume-result|net_close#1 Drivers/BSP/UI/ui_net_sink.c|consume-result|net_close#2 Drivers/BSP/UI/ui_net_sink.c|consume-result|net_close#3 Drivers/BSP/UI/ui_net_sink.c|consume-result|net_close#4 Drivers/BSP/UI/ui_net_sink.c|consume-result|net_close#5 Drivers/BSP/UI/ui_net_sink.c|consume-result|net_close#6 """.splitlines() if line.strip() ) DEFINE_RE = re.compile(r"^\s*#define\s+([A-Z][A-Z_0-9]*TIMEOUT[A-Z_0-9]*)\s+(-[0-9]+)", re.MULTILINE); # bool 用在"提问"上是合法的（is_editable / has_children / is_active…）；只有拿 bool 当 # **错误通道**才是问题。用名字形状区分，避免把 7 个正当谓词误判成违规、再拿基线去洗规则。 PREDICATE_RE = re.compile(r"(^|_)(is|has|can|should|need|valid|active|open|empty)_|" + r"_(is|has|can|valid)$") DECL_RE = re.compile(r"^\s*(?:extern\s+)?([A-Za-z_][A-Za-z_0-9_ ]*[ ]+\**)" r"([a-z_][a-z_0-9]*)\s*\([^;{]*\)\s*;", re.MULTILINE); def tracked_headers(): """git 跟踪的 BSP 公开头文件（排除第三方 lftpd）。""" out = subprocess.run(["git", "ls-files", "--", "Drivers/BSP"], cwd=str(ROOT), capture_output=True, text=True) if out.returncode != 0: print("git ls-files 失败:", out.stderr.strip()) raise SystemExit(2) files = [] for rel in out.stdout.split(): rel = rel.replace("\\", "/") if not rel.endswith(".h"): continue if any(part in rel for part in EXCLUDE): continue files.append(rel) return sorted(files) def doc_block_before(lines, idx): """取声明上方紧邻的注释块文本（向上直到 /* 或空行为止）。""" buf = [] j = idx - 1 while j >= 0: t = lines[j].strip() if t.endswith("*/") or t.startswith("*") or t.startswith("/*"): buf.append(t) if t.startswith("/*"): break j -= 1 continue break return "\n".join(buf) HAL_STATUS_RE = re.compile(r"^HAL_(?:SPI|I2C|UART)_(?:Transmit|Receive|TransmitReceive)" r"(?:_DMA|_IT)?$|^HAL_I2C_Mem_(?:Read|Write)$") BARE_CALL_RE = re.compile(r"^\s*([A-Za-z_][A-Za-z_0-9]*)\s*\(.*\);" r"(?:\s*/\*.*?\*/)?\s*$") # 行尾注释不影响判定 # 两类形状不算"丢弃错误码"，也不许塞进基线——同 err-type 谓词白名单的理由：**规则该按真实 # 反例收窄，而不是拿基线去洗假阳性**： # · 谓词：返回值是"提问"而不是"办成没有"（is_/has_/can_/should_/need_/valid_）； # · setter：形如 xxx_set_yyy(...) 的写入口，它返回的 int 是状态回声而不是调用成败 # （实跑误判出 net_set_errno 八处——它只是把值写进调用方自己的 errno 槽）。 ALLOW_BARE_RE = re.compile( r"(?:(?:^|_)(?:is|has|can|should|need|valid)_)|(?:^|_)set_[a-z0-9_]+$" r"|(?:^|_)mark_block_bad$") def must_use_names(): """自动取"返回错误码"的函数名（不手写名单，避免名单与代码脱节）。 两条来源用**同一套启发式**：① 头文件里的公开声明；② .c 里的 static 定义（只从头文件 取会漏掉 static——实测 gd5f_set_feature 等就是 static 且返回错误码，上面提到的 ECC 那两行丢弃 正是这类，靠人工才发现）。 """ names = {} for hdr in tracked_headers(): try: htext = (ROOT / hdr).read_text(encoding="utf-8-sig") except (OSError, UnicodeDecodeError) as exc: print("读不了", hdr, exc) raise SystemExit(2) hlines = htext.splitlines() for m in DECL_RE.finditer(htext): ret = m.group(1).replace("const", "").strip() hname = m.group(2) flat = ret.replace(" ", "") hdoc = doc_block_before(hlines, htext[:m.start()].count(chr(10))) if flat.endswith("bsp_err_t"): names.setdefault(hname, "返回 bsp_err_t") elif flat in ("int", "int32_t") and re.search("错误码|失败|BSP_ERR|_FAIL", hdoc): names.setdefault(hname, "返回 int 且文档声明会失败") for src_c in tracked_sources(): try: ctext = (ROOT / src_c).read_text(encoding="utf-8-sig") except (OSError, UnicodeDecodeError) as exc: print("读不了", src_c, exc) raise SystemExit(2) clines = ctext.splitlines() for cname, cidx in static_int_defs(ctext): cdoc = doc_block_before(clines, cidx) if re.search("错误码|失败|BSP_ERR|_FAIL", cdoc): names.setdefault(cname, ".c 内 static 且文档声明会失败") return names def tracked_sources(): """git 跟踪的 BSP 源文件（排除第三方 lftpd）。""" out = subprocess.run(["git", "ls-files", "--", "Drivers/BSP"], cwd=str(ROOT), capture_output=True, text=True) if out.returncode != 0: print("git ls-files 失败:", out.stderr.strip()) raise SystemExit(2) files = [] for rel in out.stdout.split(): rel = rel.replace(chr(92), "/") if not rel.endswith(".c"): continue if "lftpd/" in rel: continue files.append(rel) return sorted(files) def static_int_defs(text): """从 .c 里挑出"返回 int/int32_t 的 static 函数定义"（不引正则，按形状扫）。 为什么需要：只从**头文件**取 must-use 名单会漏掉 static 函数——实测 gd5f_set_feature / gd5f_private_get_feature / gd5f_private_bbt_find_best 都是 static， 它们同样返回错误码，却在名单之外，等于门禁只守跨编译单元的边界、看不见编译 单元内部的丢弃（ECC 那两行就是靠人工发现的，不是靠这条规则）。 """ hits = [] lines = text.splitlines() brace = chr(123) for idx, line in enumerate(lines): t = line.strip() if not t.endswith(brace): continue if "(" not in t or t.startswith("if") or t.startswith("for"): continue if not (t.startswith("static ") or " static " in t): continue head = t.split("(")[0] words = head.replace("static", " ").split() if len(words) < 2 or words[0] not in ("int", "int32_t"): continue hits.append((words[-1], idx)) return hits def scan_r4(must_use): """consume-result：Drivers/BSP 下的 .c 里，对 must-use 函数的"裸调用"（不接、也不显式 (void)）。""" files = tracked_sources() hits = [] for rel in files: try: text = (ROOT / rel).read_text(encoding="utf-8-sig") except (OSError, UnicodeDecodeError) as exc: print("读不了", rel, exc) raise SystemExit(2) seen = {} for line in text.splitlines(): t = line.strip() if t.startswith("*") or t.startswith("//") or t.startswith("/*"): continue m = BARE_CALL_RE.match(line) if not m: continue name = m.group(1) if name in ("if", "while", "for", "switch", "return", "sizeof", "else"): continue if name not in must_use and not HAL_STATUS_RE.match(name): continue if ALLOW_BARE_RE.search(name): continue seen[name] = seen.get(name, 0) + 1 hits.append((rel, "consume-result", "%s#%d" % (name, seen[name]))) return hits def scan(): hits = [] for rel in tracked_headers(): try: text = (ROOT / rel).read_text(encoding="utf-8") except (OSError, UnicodeDecodeError) as exc: print("读不了", rel, exc) raise SystemExit(2) lines = text.splitlines() for m in DEFINE_RE.finditer(text): hits.append((rel, "timeout-name", m.group(1))) for m in DECL_RE.finditer(text): ret = m.group(1).replace("const", "").strip() name = m.group(2) flat = ret.replace(" ", ""); if name in ("void", "return", "if", "while", "sizeof", "typedef", "static"): continue is_bool = flat.endswith("bool") or flat.endswith("_Bool") if flat.endswith("HAL_StatusTypeDef") or (is_bool and not PREDICATE_RE.search(name)): hits.append((rel, "err-type", name)) if flat == "void": continue idx = text[:m.start()].count("\n") # 忽略空格：规范 V1.0 允许列对齐写法「返 回 值：」，那只是一种排版选择， # 要求"必须写成不空格的形式"等于让门禁去规定排版，会把合规注释判成违规。 marker = doc_block_before(lines, idx).replace(" ", "").replace("\u3000", "") if "返回值" not in marker: hits.append((rel, "return-doc", name)) hits.extend(scan_r4(must_use_names())) return hits def main(): ap = argparse.ArgumentParser(description="BSP 错误码/超时命名约定（增量拦截）") ap.add_argument("--verbose", action="store_true", help="列出全部命中与归类") ap.add_argument("--prune", action="store_true", help="只报已消失、可从 BASELINE 删除的条目") ap.add_argument("--emit-baseline", action="store_true", help="打印当前全部命中的键（建基线用）") args = ap.parse_args() keys = {"%s|%s|%s" % h for h in scan()} if args.emit_baseline: for key in sorted(keys): print(key) print("# 共 %d 条" % len(keys)) return 0 gone = sorted(set(BASELINE) - keys) fresh = sorted(keys - set(BASELINE)) if args.prune: if not gone: print("[prune] 基线 %d 条全部仍在" % len(BASELINE)) for key in gone: print("[prune] 这条已消失，请从 BASELINE 删除:", key) return 0 if args.verbose: for key in sorted(keys): print(" [%s] %s" % ("基线" if key in BASELINE else "新增", key)) print("BSP 约定：命中 %d（在册 %d / 新增 %d），基线共 %d" % (len(keys), len(keys & set(BASELINE)), len(fresh), len(BASELINE))) if fresh: print("[FAIL] 新增违反 BSP 约定的条目：") for key in fresh: print(" -", key) print(' 出路：① 返回 bsp_err_t（Drivers/BSP/bsp_err.h，0=成功、负值=失败，') print(' 可重试判定用 BSP_ERR_CAN_RETRY）；② 时长宏一律 *_MS 且必须是时间，') print(' 若将来出现按循环次数计时的等待，改名 *_LOOP 并注释写明非时间量；') print(' ③ 返回码不许叫 *_TIMEOUT。') return 1 if gone: print("[提醒] 有 %d 条基线已还清，请用 --prune 列出并从 BASELINE 删除" % len(gone)) return 0 if __name__ == "__main__": raise SystemExit(main())