cortex-cycle-budget 0.2.0__py3-none-any.whl

cortex_cycle_budget/__init__.py

@@ -0,0 +1,87 @@
+"""
+cortex_cycle_budget — Static cycle-count estimation for ARM Cortex-M binaries.
+
+Supports Cortex-M0, M4, M7, and M33 instruction timing models.  Estimates
+cycle consumption for user-defined critical paths through an ELF binary by
+parsing ``arm-none-eabi-objdump`` output.
+
+Public API:
+    parse_disassembly        — disassembly → Function list
+    analyze_stages           — Function list + config → PathStage list
+    walk_call_graph          — recursive cycle attribution
+    generate_report          — full markdown report
+    generate_pr_comment      — concise PR comment markdown
+    generate_cpu_budget_table — budget table only (markdown)
+    generate_annotated_disasm — annotated disassembly markdown
+    generate_json_metrics    — machine-readable metrics dict
+    validate_config          — raise ConfigError on invalid configs
+    EXCEPTION_OVERHEAD       — per-variant ISR entry/exit cycles
+    TIMING                   — resolved timing table for the default variant
+    BASE_TIMING              — variant-agnostic timing table
+    VARIANT_OVERRIDES        — per-variant overrides applied on top of BASE_TIMING
+    SUPPORTED_VARIANTS       — frozenset of supported Cortex-M variants
+"""
+
+from __future__ import annotations
+
+from cortex_cycle_budget.analysis import analyze_stages, walk_call_graph
+from cortex_cycle_budget.config import validate_config
+from cortex_cycle_budget.models import (
+    ConfigError,
+    Function,
+    Instruction,
+    PathStage,
+    StageMatchError,
+)
+from cortex_cycle_budget.parser import parse_disassembly
+from cortex_cycle_budget.reports import (
+    generate_annotated_disasm,
+    generate_cpu_budget_table,
+    generate_json_metrics,
+    generate_pr_comment,
+    generate_report,
+)
+from cortex_cycle_budget.timing_model import (
+    BASE_TIMING,
+    EXCEPTION_OVERHEAD,
+    SUPPORTED_VARIANTS,
+    TIMING,
+    VARIANT_OVERRIDES,
+    classify_instruction,
+    get_timing,
+    normalize_mnemonic,
+    resolve_timing_table,
+)
+from cortex_cycle_budget.tooling import log, run_objdump, run_size
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "BASE_TIMING",
+    "EXCEPTION_OVERHEAD",
+    "SUPPORTED_VARIANTS",
+    "TIMING",
+    "VARIANT_OVERRIDES",
+    "ConfigError",
+    "Function",
+    "Instruction",
+    "PathStage",
+    "StageMatchError",
+    "__version__",
+    "analyze_stages",
+    "classify_instruction",
+    "generate_annotated_disasm",
+    "generate_cpu_budget_table",
+    "generate_json_metrics",
+    "generate_pr_comment",
+    "generate_report",
+    "get_timing",
+    "log",
+    "normalize_mnemonic",
+    "parse_disassembly",
+    "resolve_timing_table",
+    "run_objdump",
+    "run_size",
+    "validate_config",
+    "walk_call_graph",
+]

cortex_cycle_budget/__main__.py

@@ -0,0 +1,10 @@
+"""``python -m cortex_cycle_budget`` → single-mode CLI."""
+
+from __future__ import annotations
+
+import sys
+
+from cortex_cycle_budget.cli_single import main
+
+if __name__ == "__main__":
+    sys.exit(main())

cortex_cycle_budget/analysis.py

@@ -0,0 +1,203 @@
+"""Call-graph walker and stage analysis (config → :class:`PathStage` list)."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from cortex_cycle_budget.models import (
+    Function,
+    PathStage,
+    StageMatchError,
+)
+from cortex_cycle_budget.timing_model import EXCEPTION_OVERHEAD
+from cortex_cycle_budget.tooling import log
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Call-graph walker
+# ──────────────────────────────────────────────────────────────────────────────
+
+def _resolve_fn(name: str, lookup: dict[str, Function]) -> Function | None:
+    fn = lookup.get(name)
+    if fn is not None:
+        return fn
+    for k, f in lookup.items():
+        if name in k:
+            return f
+    return None
+
+
+def walk_call_graph(
+    entry_fn: Function,
+    lookup: dict[str, Function],
+) -> dict[str, dict[str, int]]:
+    """Walk the call graph from *entry_fn*, counting each callee per invocation.
+
+    Returns a mapping of demangled function name → aggregate metrics
+    (``min``, ``max``, ``instructions``, ``code_size``, instruction-mix
+    counters, and ``call_count``).
+    """
+    breakdown: dict[str, dict[str, int]] = {}
+
+    def _walk(fn_name: str, visited_stack: frozenset[str]) -> None:
+        fn = _resolve_fn(fn_name, lookup)
+        if fn is None:
+            return
+        canonical = fn.demangled
+        if canonical in visited_stack:
+            return
+        visited_stack = visited_stack | {canonical}
+
+        if canonical not in breakdown:
+            breakdown[canonical] = {
+                "min": 0,
+                "max": 0,
+                "instructions": fn.instruction_count,
+                "code_size": fn.code_size,
+                "fpu_ops": fn.fpu_ops,
+                "load_store": fn.load_store_ops,
+                "branch": fn.branch_ops,
+                "alu": fn.alu_ops,
+                "mul_div": fn.mul_div_ops,
+                "call_count": 0,
+            }
+
+        breakdown[canonical]["call_count"] += 1
+        breakdown[canonical]["min"] += fn.total_min_cycles
+        breakdown[canonical]["max"] += fn.total_max_cycles
+
+        for callee in fn.calls:
+            _walk(callee, visited_stack)
+
+    _walk(entry_fn.demangled, frozenset())
+    return breakdown
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Stage analysis
+# ──────────────────────────────────────────────────────────────────────────────
+
+def analyze_stages(
+    config: dict[str, Any],
+    all_fns: list[Function],
+    lookup: dict[str, Function],
+    *,
+    strict: bool = True,
+) -> list[PathStage]:
+    """Resolve the configured ``path_stages`` against the disassembled binary.
+
+    Args:
+        config: Parsed JSON configuration (must include ``path_stages``).
+        all_fns: Output of :func:`parse_disassembly`.
+        lookup: ``{fn.demangled: fn}`` mapping over *all_fns*.
+        strict: When ``True``, raise :class:`StageMatchError` if any required
+            stage matches no functions.
+
+    Raises:
+        StageMatchError: in strict mode, when at least one required stage
+            fails to match.
+    """
+    cortex = config.get("cortex", "m4")
+    overhead = EXCEPTION_OVERHEAD.get(cortex, EXCEPTION_OVERHEAD["m4"])
+    stages: list[PathStage] = []
+    errors: list[str] = []
+
+    for stage_cfg in config["path_stages"]:
+        stage_type = stage_cfg.get("type")
+        required = stage_cfg.get("required", True)
+
+        if stage_type == "exception_entry":
+            stages.append(PathStage(
+                label=stage_cfg["label"],
+                min_cycles=overhead["entry_min"],
+                max_cycles=overhead["entry_max"],
+                is_overhead=True,
+            ))
+            continue
+
+        if stage_type == "exception_exit":
+            stages.append(PathStage(
+                label=stage_cfg["label"],
+                min_cycles=overhead["exit_min"],
+                max_cycles=overhead["exit_max"],
+                is_overhead=True,
+            ))
+            continue
+
+        patterns = stage_cfg.get("patterns", [])
+        entry_pattern = stage_cfg.get("entry")
+
+        matched: dict[str, Function] = {}
+        for fn in all_fns:
+            for pat in patterns:
+                try:
+                    if re.search(pat, fn.demangled):
+                        matched[fn.demangled] = fn
+                        break
+                except re.error as exc:
+                    msg = (
+                        f"Stage '{stage_cfg['label']}': invalid regex "
+                        f"pattern '{pat}': {exc}"
+                    )
+                    errors.append(msg)
+                    log(f"  ERROR: {msg}")
+                    break
+
+        stage = PathStage(label=stage_cfg["label"])
+
+        if entry_pattern:
+            entry_fn = None
+            for name, fn in matched.items():
+                if re.search(entry_pattern, name):
+                    entry_fn = fn
+                    break
+            if entry_fn is not None:
+                breakdown = walk_call_graph(entry_fn, lookup)
+                stage.min_cycles = sum(v["min"] for v in breakdown.values())
+                stage.max_cycles = sum(v["max"] for v in breakdown.values())
+                stage.instruction_count = sum(v["instructions"] for v in breakdown.values())
+                stage.code_size = sum(v["code_size"] for v in breakdown.values())
+                stage.fpu_ops = sum(v["fpu_ops"] for v in breakdown.values())
+                stage.functions = sorted(breakdown.keys())
+            else:
+                msg = (
+                    f"Stage '{stage_cfg['label']}': entry function matching "
+                    f"'{entry_pattern}' not found in binary"
+                )
+                if required:
+                    errors.append(msg)
+                log(f"  ERROR: {msg}")
+        else:
+            if not matched and required:
+                msg = (
+                    f"Stage '{stage_cfg['label']}': no functions matched any "
+                    f"of the {len(patterns)} configured patterns"
+                )
+                errors.append(msg)
+                log(f"  ERROR: {msg}")
+            for fn in matched.values():
+                stage.min_cycles += fn.total_min_cycles
+                stage.max_cycles += fn.total_max_cycles
+                stage.instruction_count += fn.instruction_count
+                stage.code_size += fn.code_size
+                stage.fpu_ops += fn.fpu_ops
+            stage.functions = sorted(matched.keys())
+
+        stages.append(stage)
+
+    if strict and errors:
+        log("")
+        log("Stage matching failed — the configuration does not align with the binary.")
+        log("Unmatched stages:")
+        for e in errors:
+            log(f"  • {e}")
+        log("")
+        log("Ensure the path_stages patterns in your config JSON match the ")
+        log("demangled symbol names in the ELF. You can inspect them with:")
+        log("  arm-none-eabi-objdump -d -C <elf> | grep '^[0-9a-f].*<.*>:$'")
+        raise StageMatchError(
+            f"{len(errors)} path stage(s) matched no functions in the binary. "
+            f"See stderr for details."
+        )
+
+    return stages

cortex_cycle_budget/cli_multi.py

@@ -0,0 +1,331 @@
+"""Multi-mode CLI: ``cortex-cycle-budget-multi``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+from typing import Any
+
+from cortex_cycle_budget.analysis import analyze_stages
+from cortex_cycle_budget.config import validate_config
+from cortex_cycle_budget.models import ConfigError, StageMatchError
+from cortex_cycle_budget.parser import parse_disassembly
+from cortex_cycle_budget.reports import (
+    generate_annotated_disasm,
+    generate_cpu_budget_table,
+    generate_json_metrics,
+    generate_report,
+)
+from cortex_cycle_budget.timing_model import (
+    EXCEPTION_OVERHEAD,
+    SUPPORTED_VARIANTS,
+    resolve_timing_table,
+)
+from cortex_cycle_budget.tooling import log, run_objdump, run_size
+
+PR_COMMENT_MARKER = "<!-- cortex-cycle-budget-comment -->"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="cortex-cycle-budget-multi",
+        description="Multi-configuration ARM Cortex-M cycle analysis.",
+    )
+    parser.add_argument(
+        "analyses_config",
+        help="JSON file containing an array of analysis entries",
+    )
+    parser.add_argument("--target", required=True, help="Target board identifier")
+    parser.add_argument("--build-config", required=True, help="Build configuration")
+    parser.add_argument("--clock-mhz", required=True, type=int, help="CPU clock in MHz")
+    parser.add_argument(
+        "--cortex",
+        default="m4",
+        choices=sorted(SUPPORTED_VARIANTS),
+        help="Cortex-M variant (default: m4)",
+    )
+    parser.add_argument("--objdump", default="arm-none-eabi-objdump")
+    parser.add_argument("--size-tool", default="arm-none-eabi-size")
+    parser.add_argument("--output-dir", default="cycle-analysis-combined")
+    parser.add_argument(
+        "--no-strict",
+        action="store_true",
+        help="Do not fail when path stages match no functions",
+    )
+    parser.add_argument(
+        "--fail-over-max-cycles",
+        type=int,
+        default=None,
+        help="Exit with non-zero status if any mode's max cycles exceeds this threshold.",
+    )
+    return parser
+
+
+def _run_single_analysis(
+    entry: dict[str, Any],
+    shared_args: argparse.Namespace,
+) -> tuple[str, str, int]:
+    """Run analysis for one entry. Returns (cpu_budget_md, full_report_md, max_cycles)."""
+    label = entry["label"]
+    elf_path = entry["elf_path"]
+    config_path = entry["config_path"]
+    output_dir = entry["output_dir"]
+
+    log(f"\n--- Analyzing: {label} ---")
+
+    if not os.path.isfile(elf_path):
+        log(f"ERROR: ELF not found: {elf_path}")
+        sys.exit(1)
+
+    if not os.path.isfile(config_path):
+        log(f"ERROR: Config not found: {config_path}")
+        sys.exit(1)
+
+    try:
+        with open(config_path) as f:
+            config = json.load(f)
+    except json.JSONDecodeError as exc:
+        log(f"ERROR: Failed to parse config JSON '{config_path}': {exc}")
+        sys.exit(1)
+
+    config["target"] = shared_args.target
+    config["build_config"] = shared_args.build_config
+    config["clock_mhz"] = shared_args.clock_mhz
+    config["cortex"] = shared_args.cortex
+
+    try:
+        validate_config(config)
+    except ConfigError as exc:
+        log(f"ERROR: {exc}")
+        sys.exit(1)
+
+    os.makedirs(output_dir, exist_ok=True)
+
+    try:
+        disasm = run_objdump(elf_path, shared_args.objdump)
+    except FileNotFoundError:
+        log(f"ERROR: objdump tool not found: '{shared_args.objdump}'")
+        log("Install the ARM toolchain or pass --objdump with the correct path.")
+        sys.exit(1)
+    except subprocess.CalledProcessError as exc:
+        log(f"ERROR: objdump failed (exit {exc.returncode}): {exc.stderr}")
+        sys.exit(1)
+
+    with open(os.path.join(output_dir, "full_disassembly.txt"), "w") as f:
+        f.write(disasm)
+
+    size_out = run_size(elf_path, shared_args.size_tool)
+    if size_out:
+        with open(os.path.join(output_dir, "size_report.txt"), "w") as f:
+            f.write(size_out)
+
+    timing = resolve_timing_table(shared_args.cortex)
+    all_fns = parse_disassembly(disasm, timing=timing)
+    lookup = {fn.demangled: fn for fn in all_fns}
+    log(f"Parsed {len(all_fns)} functions")
+
+    if len(all_fns) == 0:
+        log("ERROR: No functions found in the disassembly.")
+        log("The ELF may be stripped, empty, or not an ARM binary.")
+        sys.exit(1)
+
+    try:
+        stages = analyze_stages(
+            config, all_fns, lookup, strict=not getattr(shared_args, "no_strict", False),
+        )
+    except StageMatchError as exc:
+        log(f"ERROR: {exc}")
+        sys.exit(1)
+
+    report = generate_report(config, stages, all_fns, lookup)
+    with open(os.path.join(output_dir, "cycle_estimation_report.md"), "w") as f:
+        f.write(report)
+
+    budget = generate_cpu_budget_table(config, stages)
+    with open(os.path.join(output_dir, "cpu_budget.md"), "w") as f:
+        f.write(budget)
+
+    annotated = generate_annotated_disasm(config, all_fns, stages)
+    with open(os.path.join(output_dir, "annotated_disassembly.md"), "w") as f:
+        f.write(annotated)
+
+    metrics = generate_json_metrics(config, stages)
+    with open(os.path.join(output_dir, "cycle_metrics.json"), "w") as f:
+        json.dump(metrics, f, indent=2)
+
+    total_min = sum(s.min_cycles for s in stages)
+    total_max = sum(s.max_cycles for s in stages)
+    log(f"{label}: {total_min}–{total_max} cycles, {len(stages)} stages")
+
+    return budget, report, total_max
+
+
+def _build_collapsible_sections(
+    analyses: list[dict[str, Any]],
+    budgets: list[str],
+    reports: list[str],
+    target: str,
+) -> list[str]:
+    lines: list[str] = []
+    for i, (entry, budget, report) in enumerate(zip(analyses, budgets, reports, strict=False)):
+        label = entry["label"]
+        lines.extend((
+            f"### {label} | {target}",
+            "",
+            "**CPU Utilization Budget**",
+            "",
+            budget,
+            "",
+            "<details>",
+            "<summary>Click to expand full details</summary>",
+            "",
+            report,
+            "",
+            "</details>",
+            "",
+        ))
+        if i < len(analyses) - 1:
+            lines.extend(("---", ""))
+    return lines
+
+
+def generate_combined_pr_comment(
+    analyses: list[dict[str, Any]],
+    budgets: list[str],
+    reports: list[str],
+    target: str,
+) -> str:
+    lines = [PR_COMMENT_MARKER, "## 🏎️ Cycle Analysis Results", ""]
+    lines.extend(_build_collapsible_sections(analyses, budgets, reports, target))
+    return "\n".join(lines)
+
+
+def generate_combined_step_summary(
+    analyses: list[dict[str, Any]],
+    budgets: list[str],
+    reports: list[str],
+    target: str,
+) -> str:
+    lines = ["## 🏎️ Cycle Analysis Results", ""]
+    lines.extend(_build_collapsible_sections(analyses, budgets, reports, target))
+    return "\n".join(lines)
+
+
+def generate_combined_metrics(analyses: list[dict[str, Any]]) -> dict[str, Any]:
+    modes: list[dict[str, Any]] = []
+    overall_max = 0
+
+    for entry in analyses:
+        metrics_path = os.path.join(entry["output_dir"], "cycle_metrics.json")
+        if not os.path.isfile(metrics_path):
+            continue
+        with open(metrics_path) as f:
+            m = json.load(f)
+        m["mode_label"] = entry["label"]
+        modes.append(m)
+        overall_max = max(overall_max, m["summary"]["estimated_max_cycles"])
+
+    return {"modes": modes, "overall_max_cycles": overall_max}
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    if not os.path.isfile(args.analyses_config):
+        log(f"ERROR: Analyses config not found: {args.analyses_config}")
+        return 1
+
+    if args.clock_mhz <= 0:
+        log(f"ERROR: --clock-mhz must be a positive integer, got {args.clock_mhz}")
+        return 1
+
+    if args.cortex not in EXCEPTION_OVERHEAD:
+        valid = ", ".join(sorted(EXCEPTION_OVERHEAD))
+        log(f"ERROR: --cortex '{args.cortex}' is not supported. Valid values: {valid}")
+        return 1
+
+    try:
+        with open(args.analyses_config) as f:
+            analyses = json.load(f)
+    except json.JSONDecodeError as exc:
+        log(f"ERROR: Failed to parse analyses config JSON: {exc}")
+        return 1
+
+    if not isinstance(analyses, list) or len(analyses) == 0:
+        log("ERROR: Analyses config must be a non-empty JSON array")
+        return 1
+
+    os.makedirs(args.output_dir, exist_ok=True)
+
+    budgets: list[str] = []
+    reports: list[str] = []
+    per_mode_max: list[tuple[str, int]] = []
+
+    for entry in analyses:
+        budget, report, max_cycles = _run_single_analysis(entry, args)
+        budgets.append(budget)
+        reports.append(report)
+        per_mode_max.append((entry["label"], max_cycles))
+
+    comment = generate_combined_pr_comment(analyses, budgets, reports, args.target)
+    comment_path = os.path.join(args.output_dir, "combined_pr_comment.md")
+    with open(comment_path, "w") as f:
+        f.write(comment)
+    log(f"\nCombined PR comment: {comment_path}")
+
+    summary = generate_combined_step_summary(analyses, budgets, reports, args.target)
+    summary_path = os.path.join(args.output_dir, "combined_step_summary.md")
+    with open(summary_path, "w") as f:
+        f.write(summary)
+    log(f"Combined step summary: {summary_path}")
+
+    combined_metrics = generate_combined_metrics(analyses)
+    metrics_path = os.path.join(args.output_dir, "combined_metrics.json")
+    with open(metrics_path, "w") as f:
+        json.dump(combined_metrics, f, indent=2)
+    log(f"Combined metrics: {metrics_path}")
+
+    clock = args.clock_mhz
+    avail_20k = clock * 1_000_000 // 20_000
+    print(f"\n{'=' * 65}")
+    print(f" Multi-Config Cycle Analysis ({args.target} {args.build_config}, "
+          f"Cortex-{args.cortex.upper()})")
+    print(f"{'=' * 65}")
+    for entry in analyses:
+        mp = os.path.join(entry["output_dir"], "cycle_metrics.json")
+        if not os.path.isfile(mp):
+            continue
+        with open(mp) as f:
+            m = json.load(f)
+        total_min = m["summary"]["estimated_min_cycles"]
+        total_max = m["summary"]["estimated_max_cycles"]
+        pct = total_max / avail_20k * 100 if avail_20k > 0 else 0.0
+        print(
+            f" {entry['label']:<22s}  {total_min:>4d}–{total_max:<4d} cycles  "
+            f"({pct:.1f}% max @ 20 kHz)"
+        )
+    print(f"{'=' * 65}")
+
+    if args.fail_over_max_cycles is not None:
+        violators = [
+            (label, mx)
+            for label, mx in per_mode_max
+            if mx > args.fail_over_max_cycles
+        ]
+        if violators:
+            log(
+                f"ERROR: {len(violators)} mode(s) exceed the cycle budget "
+                f"({args.fail_over_max_cycles}):"
+            )
+            for label, mx in violators:
+                log(f"  • {label}: {mx} cycles")
+            return 2
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())