From d4a2e7239dd90f049d0837e642b8f658b3ad3c36 Mon Sep 17 00:00:00 2001 From: Mark Date: Wed, 20 May 2026 18:40:54 +0200 Subject: [PATCH] Add Ethernet sensitivity tools --- .../eth_sensitivity/build_candidate_matrix.py | 42 +++++++++++++ scripts/eth_sensitivity/candidate_matrix.json | 30 +++++++++ scripts/eth_sensitivity/eth_qsf_checklist.py | 37 +++++++++++ scripts/eth_sensitivity/eth_timing_parser.py | 52 ++++++++++++++++ .../eth_sensitivity/local_validation_plan.md | 61 +++++++++++++++++++ 5 files changed, 222 insertions(+) create mode 100644 scripts/eth_sensitivity/build_candidate_matrix.py create mode 100644 scripts/eth_sensitivity/candidate_matrix.json create mode 100644 scripts/eth_sensitivity/eth_qsf_checklist.py create mode 100644 scripts/eth_sensitivity/eth_timing_parser.py create mode 100644 scripts/eth_sensitivity/local_validation_plan.md diff --git a/scripts/eth_sensitivity/build_candidate_matrix.py b/scripts/eth_sensitivity/build_candidate_matrix.py new file mode 100644 index 0000000..d44a452 --- /dev/null +++ b/scripts/eth_sensitivity/build_candidate_matrix.py @@ -0,0 +1,42 @@ +"""Generate a small Ethernet placement-sensitivity test matrix.""" + +import json +from pathlib import Path + + +MATRIX = { + "baseline_seed_2": { + "description": "Known-good forced 10/100 Ethernet baseline seed.", + "quartus_seed": 2, + "env": {}, + "expected": "ping_pass", + }, + "baseline_seed_5": { + "description": "Previously observed seed-sensitive Ethernet failure candidate.", + "quartus_seed": 5, + "env": {}, + "expected": "investigate", + }, + "buttons_csr_seed_2": { + "description": "Opt-in KEY1-KEY3 CSR image using the known-good seed.", + "quartus_seed": 2, + "env": {"DE2_ENABLE_BUTTONS_CSR": "1"}, + "expected": "investigate", + }, + "ps2_rx_seed_2": { + "description": "Opt-in PS/2 receive probe image using the known-good seed.", + "quartus_seed": 2, + "env": {"DE2_ENABLE_PS2_RX_PROBE": "1"}, + "expected": "investigate", + }, +} + + +def main() -> None: + out_path = Path(__file__).with_name("candidate_matrix.json") + out_path.write_text(json.dumps(MATRIX, indent=2) + "\n", encoding="utf-8") + print(f"Wrote {out_path}") + + +if __name__ == "__main__": + main() diff --git a/scripts/eth_sensitivity/candidate_matrix.json b/scripts/eth_sensitivity/candidate_matrix.json new file mode 100644 index 0000000..ca2e319 --- /dev/null +++ b/scripts/eth_sensitivity/candidate_matrix.json @@ -0,0 +1,30 @@ +{ + "baseline_seed_2": { + "description": "Known-good forced 10/100 Ethernet baseline seed.", + "quartus_seed": 2, + "env": {}, + "expected": "ping_pass" + }, + "baseline_seed_5": { + "description": "Previously observed seed-sensitive Ethernet failure candidate.", + "quartus_seed": 5, + "env": {}, + "expected": "investigate" + }, + "buttons_csr_seed_2": { + "description": "Opt-in KEY1-KEY3 CSR image using the known-good seed.", + "quartus_seed": 2, + "env": { + "DE2_ENABLE_BUTTONS_CSR": "1" + }, + "expected": "investigate" + }, + "ps2_rx_seed_2": { + "description": "Opt-in PS/2 receive probe image using the known-good seed.", + "quartus_seed": 2, + "env": { + "DE2_ENABLE_PS2_RX_PROBE": "1" + }, + "expected": "investigate" + } +} diff --git a/scripts/eth_sensitivity/eth_qsf_checklist.py b/scripts/eth_sensitivity/eth_qsf_checklist.py new file mode 100644 index 0000000..09166e7 --- /dev/null +++ b/scripts/eth_sensitivity/eth_qsf_checklist.py @@ -0,0 +1,37 @@ +"""Report Ethernet-related QSF assignments for quick pass/fail comparison.""" + +import argparse +from pathlib import Path + + +KEYWORDS = ("eth", "enet", "rgmii", "mdio", "mdc") + + +def ethernet_lines(qsf_path: Path) -> list[str]: + lines: list[str] = [] + for raw_line in qsf_path.read_text(encoding="utf-8", errors="ignore").splitlines(): + line = raw_line.strip() + if not line or line.startswith("#"): + continue + lower = line.lower() + if any(keyword in lower for keyword in KEYWORDS): + lines.append(line) + return lines + + +def main() -> None: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("qsf", type=Path, help="Path to de2_115_vga_platform.qsf") + args = parser.parse_args() + + if not args.qsf.exists(): + raise SystemExit(f"QSF not found: {args.qsf}") + + lines = ethernet_lines(args.qsf) + print(f"Ethernet-related QSF assignments in {args.qsf}: {len(lines)}") + for line in lines: + print(line) + + +if __name__ == "__main__": + main() diff --git a/scripts/eth_sensitivity/eth_timing_parser.py b/scripts/eth_sensitivity/eth_timing_parser.py new file mode 100644 index 0000000..f4b0001 --- /dev/null +++ b/scripts/eth_sensitivity/eth_timing_parser.py @@ -0,0 +1,52 @@ +"""Extract Ethernet-related timing lines from a Quartus STA report.""" + +import argparse +from pathlib import Path + + +KEYWORDS = ("eth", "enet", "rgmii", "mdio", "mdc") +CONTEXT_MARKERS = ( + "setup", + "hold", + "recovery", + "removal", + "unconstrained", + "slack", + "violat", + "clock", +) + + +def interesting_lines(report_path: Path) -> list[tuple[int, str]]: + matches: list[tuple[int, str]] = [] + for lineno, raw_line in enumerate( + report_path.read_text(encoding="utf-8", errors="ignore").splitlines(), + start=1, + ): + lower = raw_line.lower() + if any(keyword in lower for keyword in KEYWORDS) and any( + marker in lower for marker in CONTEXT_MARKERS + ): + matches.append((lineno, raw_line.rstrip())) + return matches + + +def main() -> None: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("sta_report", type=Path, help="Path to Quartus .sta.rpt") + parser.add_argument("--limit", type=int, default=80) + args = parser.parse_args() + + if not args.sta_report.exists(): + raise SystemExit(f"STA report not found: {args.sta_report}") + + matches = interesting_lines(args.sta_report) + print(f"Ethernet-related timing lines in {args.sta_report}: {len(matches)}") + for lineno, line in matches[: args.limit]: + print(f"{lineno}: {line}") + if len(matches) > args.limit: + print(f"... truncated {len(matches) - args.limit} additional lines") + + +if __name__ == "__main__": + main() diff --git a/scripts/eth_sensitivity/local_validation_plan.md b/scripts/eth_sensitivity/local_validation_plan.md new file mode 100644 index 0000000..889d52f --- /dev/null +++ b/scripts/eth_sensitivity/local_validation_plan.md @@ -0,0 +1,61 @@ +# Ethernet Placement Sensitivity Validation + +This is a source-only salvage of the useful idea from PR #6. It does not change +RTL, QSF, workflows, generated outputs, SOFs, VCDs, or board defaults. + +## Goal + +Identify why some otherwise successful Quartus builds lose Ethernet ping or +Etherbone reachability when the design grows, the seed changes, or opt-in debug +features are enabled. + +## Candidate Matrix + +Use `candidate_matrix.json` as the initial set of images to compare: + +- `baseline_seed_2`: known-good forced 10/100 baseline. +- `baseline_seed_5`: previously observed sensitivity candidate. +- `buttons_csr_seed_2`: opt-in KEY1-KEY3 CSR candidate. +- `ps2_rx_seed_2`: opt-in PS/2 receive-probe candidate. + +Regenerate the JSON with: + +```powershell +python scripts\eth_sensitivity\build_candidate_matrix.py +``` + +## Local Bench Sequence + +For each candidate: + +1. Build the SoC/bitstream with the candidate seed and environment variables. +2. Program the DE2-115. +3. Confirm UART boot. +4. Confirm Ethernet link/in-band status. +5. Run host ping to `192.168.178.50`. +6. Run the existing Etherbone CSR smoke path. +7. Save `.sta.rpt`, `.fit.rpt`, and `.qsf` for pass/fail comparison. + +## Report Checks + +Use the helper scripts after each build: + +```powershell +python scripts\eth_sensitivity\eth_qsf_checklist.py de2_115_vga_platform.qsf +python scripts\eth_sensitivity\eth_timing_parser.py de2_115_vga_platform.sta.rpt +``` + +Compare passing and failing reports for Ethernet clocks, RGMII/MII paths, MDIO +paths, unconstrained paths, and timing warnings. + +## Acceptance + +A candidate is useful only if it records: + +- Git commit and branch. +- Quartus seed and opt-in environment variables. +- SOF checksum or build identifier. +- UART Ethernet status line. +- Ping result. +- Etherbone CSR result. +- Timing/report artifacts retained outside the source tree.