10323c4c22
Bench verification of the IO board needs an observation window: production build has no consumer of ioboard_di_snap_read(), so the DI values were invisible. Add TEST_SUITE_IOBOARD as a semi-automatic bench sequence and fix two real bugs found while wiring it in. New files: - test/board/ioboard_test.h, test/board/ioboard_test_task.c Test suite: - Owns its own thread (iobTest, 4096 words) instead of running in testTask: testTask is osPriorityBelowNormal, below defaultTask whose 1ms console drain loop can starve a blocking wait in a lower priority context. - Phases: bit-order self-check, DI eight-point bijection, DO point-by-point toggle with operator confirmation, release-all on every exit path. - Only exit is ioboard_release_all(); it is called from the entry guard, every phase failure, the write-failure branch and the thread tail. - Sample window is 20 reads x 2ms = 40ms and does overlap the 50ms production poll. That is stated as harmless in the header: the driver wraps the whole read in taskENTER_CRITICAL (26us, not the whole 40ms), both sides only read, and a torn cross-reader sample is caught by the debounce layer rather than acted upon. default_task.c fix: - DEFAULT_TASK_DI_PUBLISH_EN was defined twice: once at file scope and once inside default_task_func(). #define has no scope, so the second was a redefinition of the first. Collapsed to a single authoritative site. - Add TEST_SUITE_STORAGE to the disable list: the STORAGE suite owns the file system via testTask, and default_task_di_poll() referenced four statics that live inside an !TEST_SUITE_STORAGE block, which broke the STORAGE build with 11 errors. - Shrink the !TEST_SUITE_STORAGE block to cover only default_task_net_cfg_save_notify() and move the three declarations out; move edges/fails into the #else branch so the empty branch references none of the four statics. Registration and gates: - MDK-ARM/STM32F407-Demo.uvprojx and simulator/CMakeLists.txt entries. - scripts/check_test_suite.py: whitelist TEST_SUITE_IOBOARD. - scripts/stack_report.py: let a self-started thread that is not declared in Src/freertos.c osThreadAttr_t still be budget checked. - test/run_all_suites.py: bring the suite into the orchestrator view. Verified: six-build matrix all 0 errors 0 warnings. CH395F/STORAGE/GD5F/RTC and the product build are bit-identical at Code=257936; the IOBOARD build is Code=264640 (+6704), which is the evidence that the suite really enters the image. Host unit tests 100/100, stack report 1760/4096 words (57%).
316 lines
13 KiB
Python
316 lines
13 KiB
Python
#!/usr/bin/env python3
|
||
"""Parse the Keil static call graph (*.htm) and report per-task stack budgets.
|
||
|
||
UV4 / armlink writes "MDK-ARM/STM32F407-Demo/STM32F407-Demo.htm" on every build
|
||
("Static Call Graph"). Every function entry carries:
|
||
|
||
<STRONG><a name="[7a]"></a>StartDefaultTask</STRONG> (Thumb, 508 bytes, Stack size 560 bytes, ...)
|
||
[Stack]<UL><LI>Max Depth = 2776<LI>Call Chain = StartDefaultTask => ... => SPI_WaitFlagStateUntilTimeout</UL>
|
||
|
||
i.e. the function's own frame ("Stack size N bytes") plus the worst-case
|
||
cumulative depth of its whole subtree ("Max Depth = N") and the chain that
|
||
reaches it. That is a build-time stack observability source: no target needed.
|
||
|
||
This tool turns it into:
|
||
1. a per-task budget table (static worst-case depth vs configured stack),
|
||
2. the worst call chain of every task,
|
||
3. a frame-size ranking (which functions are the width hogs),
|
||
4. optionally, runtime high-water-mark data overlaid from a serial log.
|
||
|
||
Runtime lines are produced by stack_probe_poll() in Src/freertos.c:
|
||
[STACK] <task> peak_used=<B>/<cfg> free_min=<B> (<pct>%)
|
||
[STACK] heap free=<B> min_ever=<B>
|
||
|
||
Usage:
|
||
python scripts/stack_report.py [-i HTML] [-s SERIAL_LOG] [-o OUTPUT]
|
||
[--isr-margin 1024] [--min-free-pct 30]
|
||
|
||
Exit code: 0 = all tasks pass, 1 = at least one task fails, 2 = parse error.
|
||
"""
|
||
import argparse
|
||
import os
|
||
import pathlib
|
||
import re
|
||
import sys
|
||
|
||
REPO_ROOT = pathlib.Path(__file__).resolve().parent.parent
|
||
HTM_DEFAULT = REPO_ROOT / "MDK-ARM" / "STM32F407-Demo" / "STM32F407-Demo.htm"
|
||
FREERTOS_C = REPO_ROOT / "Src" / "freertos.c"
|
||
|
||
# Entry function of each task -> FreeRTOS task name (attribute prefix in freertos.c).
|
||
ROOTS = {
|
||
"StartDefaultTask": "defaultTask",
|
||
"StartNetTask": "netTask",
|
||
"StartFtpTask": "ftpTask",
|
||
"StartUiTask": "uiTask",
|
||
"start_test_task": "testTask",
|
||
"time_sync_task": "timeSyncTask",
|
||
"adc_task_func": "adcTask",
|
||
"iec104_serv_task": "iec104Task",
|
||
"protect_task": "protectTask",
|
||
# 套件自起线程(xTaskCreateStatic,TCB 与栈都在 .bss,不在 freertos.c 的
|
||
# osThreadAttr_t 表里)。配置值由下面 STATIC_TASK_STACKS 直接读源码常量。
|
||
"ioboard_thread_entry": "iobTest",
|
||
}
|
||
|
||
# 自起线程的栈**不由 freertos.c 声明**,配置值只能从定义处读:任务名 -> (文件, 常量名)。
|
||
# 常量本身是**字节数**(`(1024U * 4U)` 这种写法也认);读不到即视为 0 → 报告里显示
|
||
# N/A,而不是拿一个猜的数去算余量。
|
||
STATIC_TASK_STACKS = {
|
||
"iobTest": ("test/board/ioboard_test_task.c", "IOBOARD_TEST_THREAD_STACK"),
|
||
}
|
||
|
||
# Runtime lines use the short labels emitted by stack_probe_poll() in freertos.c.
|
||
RUNTIME_ALIAS = {
|
||
"defaultTask": "default",
|
||
"netTask": "net",
|
||
"ftpTask": "ftp",
|
||
"uiTask": "ui",
|
||
"testTask": "test",
|
||
"timeSyncTask": "timesync",
|
||
"adcTask": "adc",
|
||
"iec104Task": "iec104",
|
||
"protectTask": "protect",
|
||
}
|
||
|
||
FUNC_RE = re.compile(
|
||
r'<STRONG><a name="\[[0-9a-f]+\]"></a>([^<]+)</STRONG>\s*\(([^)]*)\)', re.I)
|
||
FRAME_RE = re.compile(r'Stack size\s+(\d+)\s+bytes', re.I)
|
||
DEPTH_RE = re.compile(r'Max Depth\s*=\s*(\d+)', re.I)
|
||
CHAIN_RE = re.compile(r'Call Chain\s*=\s*(.*?)</UL>', re.I | re.S)
|
||
UPDATED_RE = re.compile(r'Last Updated:\s*(.*?)$', re.M)
|
||
MAXSTACK_RE = re.compile(r'Maximum Stack Usage\s*=\s*(\d+)\s*bytes', re.I)
|
||
ATTR_RE = re.compile(r'osThreadAttr_t\s+(\w+?)_attributes\s*=\s*\{(.*?)\};', re.S)
|
||
STACKSIZE_RE = re.compile(r'\.stack_size\s*=\s*(\d+)\s*(?:\*\s*(\d+))?')
|
||
RUNTIME_RE = re.compile(
|
||
r'\[STACK\]\s+(\w+)\s+peak_used=(\d+)/(\d+)\s+free_min=(\d+)\s+\((\d+)%\)')
|
||
HEAP_RE = re.compile(r'\[STACK\]\s+heap\s+free=(\d+)\s+min_ever=(\d+)')
|
||
TAG_RE = re.compile(r'<[^>]+>')
|
||
|
||
|
||
def _clean(text):
|
||
"""Strip HTML markup/entities from a chain fragment."""
|
||
text = TAG_RE.sub('', text)
|
||
text = text.replace('⇒', '->').replace('>', '>').replace('<', '<')
|
||
text = text.replace(' ', ' ').replace('&', '&')
|
||
return ' '.join(text.split())
|
||
|
||
|
||
def parse_callgraph(path):
|
||
"""Return (meta, functions); functions maps name -> frame/depth/chain bytes."""
|
||
text = pathlib.Path(path).read_text(encoding='utf-8', errors='replace')
|
||
meta = {"max_stack": 0, "updated": ""}
|
||
m = MAXSTACK_RE.search(text)
|
||
if m:
|
||
meta["max_stack"] = int(m.group(1))
|
||
m = UPDATED_RE.search(text)
|
||
if m:
|
||
meta["updated"] = m.group(1).strip()
|
||
|
||
functions = {}
|
||
matches = list(FUNC_RE.finditer(text))
|
||
for i, hit in enumerate(matches):
|
||
name = hit.group(1).strip()
|
||
head = hit.group(2)
|
||
end = matches[i + 1].start() if i + 1 < len(matches) else len(text)
|
||
body = text[hit.end():end]
|
||
fm = FRAME_RE.search(head)
|
||
dm = DEPTH_RE.search(body)
|
||
cm = CHAIN_RE.search(body)
|
||
frame = int(fm.group(1)) if fm else 0
|
||
depth = int(dm.group(1)) if dm else frame
|
||
chain = _clean(cm.group(1)) if cm else name
|
||
# Same name may appear once per object; keep the deepest entry.
|
||
old = functions.get(name)
|
||
if old is None or depth > old["depth"]:
|
||
functions[name] = {"frame": frame, "depth": depth, "chain": chain}
|
||
return meta, functions
|
||
|
||
|
||
def parse_task_stacks(path):
|
||
"""Parse configured stack sizes (bytes) from Src/freertos.c attributes."""
|
||
text = pathlib.Path(path).read_text(encoding='utf-8', errors='replace')
|
||
stacks = {}
|
||
for attr_name, body in ATTR_RE.findall(text):
|
||
m = STACKSIZE_RE.search(body)
|
||
if not m:
|
||
continue
|
||
size = int(m.group(1)) * (int(m.group(2)) if m.group(2) else 1)
|
||
stacks[attr_name] = size
|
||
return stacks
|
||
|
||
|
||
def parse_static_task_stacks():
|
||
"""Configured stack size (bytes) of self-spawned tasks.
|
||
|
||
These tasks never appear as osThreadAttr_t in freertos.c, so without this the
|
||
table would show them as "N/A (not in image)" and the very thread that was added
|
||
to hold a big buffer would escape the budget check entirely.
|
||
|
||
Accepted forms at the definition site (C integer literals, 0-2 multiplications):
|
||
#define X (1024U * 4U) -> 4096
|
||
#define X 2048U -> 2048
|
||
"""
|
||
sizes = {}
|
||
for task, (rel, macro) in STATIC_TASK_STACKS.items():
|
||
p = REPO_ROOT / rel
|
||
try:
|
||
text = p.read_text(encoding='utf-8', errors='replace')
|
||
except OSError:
|
||
continue
|
||
m = re.search(r'^\s*#define\s+' + re.escape(macro) + r'\s+([^\r\n/]+)', text, re.M)
|
||
if not m:
|
||
continue
|
||
expr = m.group(1)
|
||
factors = re.findall(r'(\d+)\s*[uU]?', expr)
|
||
if factors and not re.search(r'(?i)[a-wyz]', expr.replace('u', '').replace('U', '')):
|
||
total = 1
|
||
for f in factors:
|
||
total *= int(f)
|
||
sizes[task] = total
|
||
return sizes
|
||
|
||
|
||
def parse_runtime(path):
|
||
"""Extract the last [STACK] block from a serial log: task -> peak/free."""
|
||
text = pathlib.Path(path).read_text(encoding='utf-8', errors='replace')
|
||
tasks = {}
|
||
for m in RUNTIME_RE.finditer(text):
|
||
tasks[m.group(1)] = {
|
||
"peak": int(m.group(2)), "cfg": int(m.group(3)),
|
||
"free": int(m.group(4)), "pct": int(m.group(5)),
|
||
}
|
||
heap = None
|
||
hits = list(HEAP_RE.finditer(text))
|
||
if hits:
|
||
heap = {"free": int(hits[-1].group(1)), "min_ever": int(hits[-1].group(2))}
|
||
return tasks, heap
|
||
|
||
|
||
def main():
|
||
ap = argparse.ArgumentParser(description=__doc__,
|
||
formatter_class=argparse.RawDescriptionHelpFormatter)
|
||
ap.add_argument('-i', '--html', default=str(HTM_DEFAULT),
|
||
help='static call graph HTML (default: MDK-ARM output)')
|
||
ap.add_argument('-s', '--serial', default=None,
|
||
help='serial log with [STACK] lines (optional, runtime overlay)')
|
||
ap.add_argument('-o', '--output', default=None, help='write markdown report here')
|
||
ap.add_argument('--isr-margin', type=int, default=1024,
|
||
help='bytes reserved for ISR nesting (default 1024)')
|
||
ap.add_argument('--min-free-pct', type=int, default=30,
|
||
help='required free margin in %% of the stack (default 30)')
|
||
args = ap.parse_args()
|
||
|
||
html_path = pathlib.Path(args.html)
|
||
if not html_path.is_file():
|
||
print(f'ERROR: call graph HTML not found: {html_path}', file=sys.stderr)
|
||
print(' build first: .venv\\Scripts\\python.exe .dsh\\skills\\keil-build\\scripts\\keil_build.py', file=sys.stderr)
|
||
return 2
|
||
|
||
meta, functions = parse_callgraph(html_path)
|
||
stacks = parse_task_stacks(FREERTOS_C)
|
||
stacks.update(parse_static_task_stacks()) # 自起线程(不在 freertos.c 里)
|
||
runtime, heap = ({}, None)
|
||
if args.serial:
|
||
runtime, heap = parse_runtime(args.serial)
|
||
|
||
out = []
|
||
add = out.append
|
||
add('# Stack budget report')
|
||
add('')
|
||
# 显示用相对路径:传相对 -i 时 relative_to 会抛 ValueError(2026-10-22 实测踩到),
|
||
# 且绝不把本机绝对路径写进入库的 data/ 快照。
|
||
def _disp(pth):
|
||
try:
|
||
return pathlib.Path(pth).resolve().relative_to(REPO_ROOT)
|
||
except (ValueError, OSError):
|
||
return pathlib.Path(pth).name
|
||
|
||
add(f'- Source: `{_disp(html_path)}` (Keil static call graph)')
|
||
if meta["updated"]:
|
||
add(f'- Linker run: {meta["updated"]}')
|
||
add(f'- Global maximum stack usage: **{meta["max_stack"]} B** (any call tree)')
|
||
if runtime:
|
||
add(f'- Runtime watermark: {len(runtime)} task(s) from 串口采集日志 `{_disp(args.serial)}`')
|
||
add('')
|
||
add('Rule: `margin = cfg - max(static_max_depth, runtime_peak)` must be '
|
||
f'>= max({args.isr_margin} B ISR, {args.min_free_pct}% of cfg).')
|
||
add('')
|
||
add('| Task | Entry | Cfg (B) | Static max (B) | Runtime peak (B) | Worst (B) | Margin (B) | Margin % | Verdict |')
|
||
add('|---|---|---|---|---|---|---|---|---|')
|
||
|
||
failures = 0
|
||
rows = []
|
||
for entry, task in ROOTS.items():
|
||
fn = functions.get(entry)
|
||
cfg = stacks.get(task, 0)
|
||
if fn is None or cfg == 0:
|
||
rows.append((task, entry, cfg, None, None, None, None, None,
|
||
'N/A (not in image)'))
|
||
continue
|
||
depth = fn["depth"]
|
||
rt = runtime.get(task) or runtime.get(RUNTIME_ALIAS.get(task, ""))
|
||
rt_peak = rt["peak"] if rt else 0
|
||
# The verdict must use the worse of the two sources: the static graph is an
|
||
# upper bound for straight-line code but a LOWER bound once indirect calls /
|
||
# recursion are involved, and only the runtime watermark covers paths that
|
||
# actually ran (e.g. ftpTask's file-transfer loop).
|
||
worst = max(depth, rt_peak)
|
||
margin = cfg - worst
|
||
pct = (margin * 100) // cfg if cfg else 0
|
||
need = max(args.isr_margin, (cfg * args.min_free_pct) // 100)
|
||
ok = margin >= need
|
||
if not ok:
|
||
failures += 1
|
||
rows.append((task, entry, cfg, depth, rt_peak if rt else None, worst,
|
||
margin, pct, 'PASS' if ok else 'FAIL'))
|
||
for (task, entry, cfg, depth, rt_peak, worst, margin, pct, verdict) in rows:
|
||
if depth is None:
|
||
add(f'| {task} | `{entry}` | {cfg or "-"} | - | {rt_peak if rt_peak else "-"} '
|
||
f'| - | - | - | {verdict} |')
|
||
else:
|
||
add(f'| {task} | `{entry}` | {cfg} | {depth} | {rt_peak if rt_peak else "-"} '
|
||
f'| {worst} | {margin} | {pct}% | {verdict} |')
|
||
add('')
|
||
add('`Static max` = armlink worst-case call-tree depth; `Runtime peak` = measured '
|
||
'high-water mark (boot + whatever workload ran before the sample); '
|
||
'`Worst` = max of the two, which is what the verdict is computed from.')
|
||
add('')
|
||
|
||
if heap:
|
||
add(f'Runtime heap: free={heap["free"]} B, min_ever={heap["min_ever"]} B')
|
||
add('')
|
||
|
||
add('## Worst call chain per task')
|
||
add('')
|
||
for entry, task in ROOTS.items():
|
||
fn = functions.get(entry)
|
||
if fn is None:
|
||
continue
|
||
add(f'### {task}: {fn["depth"]} B (own frame {fn["frame"]} B)')
|
||
add('')
|
||
add(f'```\n{fn["chain"]}\n```')
|
||
add('')
|
||
|
||
add('## Frame-size ranking (own frame, top 15)')
|
||
add('')
|
||
add('| Bytes | Function |')
|
||
add('|---|---|')
|
||
for name, info in sorted(functions.items(), key=lambda kv: -kv[1]["frame"])[:15]:
|
||
add(f'| {info["frame"]} | `{name}` |')
|
||
add('')
|
||
|
||
report = '\n'.join(out)
|
||
if args.output:
|
||
# newline="\n":避免 Windows 换行翻译污染 data/ 快照的 LF 行尾(与 .gitattributes 一致)。
|
||
pathlib.Path(args.output).write_text(report, encoding='utf-8', newline='\n')
|
||
print(f'written: {args.output}')
|
||
else:
|
||
print(report)
|
||
|
||
return 1 if failures else 0
|
||
|
||
|
||
if __name__ == '__main__':
|
||
sys.exit(main())
|