Files
STM32F4-Base/scripts/stack_report.py
T
wandering1 10323c4c22 feat(ioboard): board test suite for DI/DO, fix default_task conditional compile
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%).
2026-11-16 19:35:15 +08:00

316 lines
13 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
#!/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('&rArr;', '->').replace('&gt;', '>').replace('&lt;', '<')
text = text.replace('&nbsp;', ' ').replace('&amp;', '&')
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())