hw-debug-loop

Diagnoses FPGA silicon failures through bounded scope-capture and oracle bisection experiments.

26|8|Updated Jun 13, 2026
One-click install
npx skills add https://github.com/vibeic/vibe-ic --skill hw-debug-loop-vibeic
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: hw-debug-loop
Source: https://github.com/vibeic/vibe-ic/tree/main/vibe-ic-marketplace/plugins/vibe-ic/skills/hw-debug-loop
Command: npx skills add https://github.com/vibeic/vibe-ic --skill hw-debug-loop-vibeic

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When your RTL passes every simulation and structural gate but the burned FPGA still fails the host acceptance test, you face an open-ended trial-and-error debug loop. This Skill converts that into a bounded 7-step methodology that deterministically classifies the failure as a spec-vs-silicon discrepancy (Category B) or a pad-level synthesis artifact (Category C) and drives it to a verified PASS. ## Core Features & Use Cases - Structured evidence capture: Records baseline FAIL frames, oracle PASS verification, and oscilloscope pulse-train captures as named evidence files for reproducibility. - A/B/C decision tree: Diffs scope captures between oracle and chip SOF to route the debug effort toward either bytewise oracle dumps (spec correction with waivers) or controlled wrapper-flip experiments (pad/fan-out fixes). - Regression gating: Every fix is paired with a structural gate and a mandatory convergence audit via hw_acceptance_test_passed_check.py before Phase 2+3 closure. - Use Case: Your half-duplex protocol IC returns byte[6]=0x02 instead of 0xF2 on the connect test despite a 12/12 byte-exact BFM. The skill walks you through oracle comparison, scope capture, and wrapper bisection until the root cause is found and gated. ## Quick Start Ask the AI to run the hardware debug loop because the connect test fails with byte[6]=0x02 even though the BFM passes and the SOF is burned.

Frequently Asked Questions about hw-debug-loop

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug an FPGA that passes simulation but fails on real hardware?▼

Use a closed-loop bisection methodology: capture a baseline FAIL with frame bytes, verify a known-good oracle SOF passes on the same rig, then scope-capture both versions and diff the pulse trains. The diff result routes you to either a spec-vs-silicon byte mismatch or a pad-level synthesis issue.

What is the difference between Category B and Category C silicon failures?▼

Category B means the vendor documentation disagrees with actual silicon behavior, such as a response length of 18 bytes versus a documented 22. Category C covers sub-microsecond pad and FPGA inference artifacts that only appear when specific RTL patterns meet a specific analog front-end.

When should I not use this hardware debug loop?▼

Do not use it when any flow_compliance_check gate is still failing or the BFM is not yet byte-exact, since those issues must be fixed first. Also stop if you lack a known-PASS oracle SOF or bytewise dump, because Category B diagnosis requires that ground truth.

Why does my FPGA drive nothing on the bus where the oracle drives a response?▼

This indicates the chip never enters the expected response path, typically because the main FSM is stuck in an idle or receive state waiting for a frame_end that never fires. Inspect the FSM with a debug state LED tap to confirm.

How do I prevent a fixed hardware bug from being reintroduced?▼

Every fix must be paired with a structural gate, such as the LL-15 through LL-23 checks, before being declared complete. After the fix, re-run flow_compliance_check in strict mode and the hw_acceptance_test_passed_check convergence audit.