codejunkie99/gf-ip-detect

GF-IP-Detect — IP Block Auto-Detection and Auto-Fill

Scans hardware codebases to find IP blocks, identify gaps, and dispatch agents to implement missing pieces.

What This Detects

1. Missing Module Implementations

Modules instantiated but never defined in the project:

# Find all module instantiations
grep -rn "^\s*\w\+\s\+\w\+\s*(" rtl/ tb/ --include="*.sv" --include="*.v" --include="*.vhd"

# Find all module definitions
grep -rn "^\s*module\s\+\w\+" rtl/ --include="*.sv" --include="*.v"

# Diff = missing implementations

2. Stub Modules (Empty or TODO)

Modules defined but with no real implementation:

# Find modules with TODO/FIXME/stub markers
grep -rn "TODO\|FIXME\|STUB\|NOT IMPLEMENTED" rtl/ --include="*.sv"

# Find modules with empty bodies (just endmodule after ports)

3. Standard IP Pattern Matching

Detect common hardware patterns that could use verified IP blocks:

| Pattern Detected | Matching IP Block | Confidence | |-----------------|-------------------|------------| | FIFO-like read/write with full/empty | fifo_sync or fifo_async | High | | 2+ flip-flop chain (synchronizer) | cdc_2ff | High | | Req/ack handshake across clocks | cdc_handshake | High | | UART-like shift register with baud | uart | Medium | | SPI-like SCLK/MOSI/MISO/CS_N | spi_master | High | | AXI-like valid/ready with addr/data | axi4lite_slave | Medium | | Counter with debounce logic | debouncer | Medium |

4. Interface Gaps

Ports declared in a top module but not connected to any implementation:

# Find top module ports
# Check which ports connect to instantiated submodules
# Unconnected ports = potential missing IP

5. Vendor IP Placeholders

Detect instantiations of vendor-specific IP that could have open-source alternatives:

# Xilinx primitives
grep -rn "IBUF\|OBUF\|BUFG\|MMCME2\|PLLE2\|BRAM" rtl/ --include="*.sv"

# Lattice primitives
grep -rn "SB_IO\|SB_GB\|SB_PLL\|SB_RAM" rtl/ --include="*.sv"

---

Detection Workflow

Step 1: Scan Codebase

Read all .sv/.v/.vhd files in project
        |
Extract: module definitions (name, ports, parameters)
        |
Extract: module instantiations (what's used)
        |
Extract: signal patterns (FIFO, CDC, protocol)
        |
Build dependency graph

Step 2: Identify Gaps

For each instantiated module:

1. Is it defined in the project? → if no, MISSING
2. Is it a known IP block from GateFlow library? → suggest /gf-ip add
3. Is it a vendor primitive? → flag for review
4. Is it defined but empty/stub? → NEEDS IMPLEMENTATION

For each signal pattern:

1. Does it match a standard IP pattern? → suggest replacement
2. Is the implementation ad-hoc? → suggest verified IP block
3. Is there a CDC crossing without synchronizer? → CRITICAL: suggest cdc_2ff

Step 3: Report

---GATEFLOW-RESULT---
STATUS: PASS | NEEDS_ACTION
SCAN_RESULTS:
  total_modules: 15
  defined: 12
  missing: 2
  stubs: 1
  
MISSING_MODULES:
  - name: fifo_controller
    instantiated_in: rtl/top.sv:42
    ports: [clk, rst_n, wr_en, wr_data, rd_en, rd_data, full, empty]
    suggested_ip: fifo_sync (92% match)
    
  - name: spi_peripheral
    instantiated_in: rtl/top.sv:67
    ports: [clk, rst_n, sclk, mosi, miso, cs_n, tx_data, rx_data]
    suggested_ip: spi_master (88% match)

STUBS:
  - name: uart_wrapper
    file: rtl/uart_wrapper.sv:1
    status: "Module defined but body is empty (TODO marker at line 15)"
    suggested_action: "Implement using uart IP block as base"

PATTERN_MATCHES:
  - pattern: "Ad-hoc 2FF synchronizer at rtl/sync.sv:10"
    suggestion: "Replace with verified cdc_2ff IP block"
    
  - pattern: "CDC crossing without synchronizer at rtl/top.sv:55"
    severity: CRITICAL
    suggestion: "Add cdc_2ff between clk_a and clk_b domains"

IP_OPPORTUNITIES:
  - "3 modules could use GateFlow IP blocks (fifo_sync, spi_master, cdc_2ff)"
  - "1 stub module needs implementation (uart_wrapper)"
  - "1 critical CDC issue detected"
---END-GATEFLOW-RESULT---

Step 4: Auto-Fill (with user approval)

Present findings and ask:

Found 2 missing modules and 1 stub:

1. fifo_controller → 92% match with fifo_sync IP block
   Action: /gf-ip add fifo_sync and rename to fifo_controller? [Y/n]

2. spi_peripheral → 88% match with spi_master IP block
   Action: /gf-ip add spi_master and adapt ports? [Y/n]

3. uart_wrapper → Empty stub, matches uart IP pattern
   Action: Generate implementation using uart IP as base? [Y/n]

4. CRITICAL: CDC crossing at top.sv:55 without synchronizer
   Action: Insert cdc_2ff synchronizer? [Y/n]

---

Auto-Fill Dispatch

When user approves auto-fill, dispatch appropriate agents:

For IP Block Matches

Use Task tool:
  subagent_type: "gateflow:sv-codegen"
  prompt: |
    Implement module <name> based on the <ip_block> IP block.
    Adapt ports to match the instantiation in <file>:<line>.
    Original ports: <detected_ports>
    IP block ports: <ip_ports>
    Generate the module, then create a testbench.

For Stubs

Use Task tool:
  subagent_type: "gateflow:sv-codegen"
  prompt: |
    Implement the stub module at <file>.
    The module signature is already defined:
    <module_signature>
    
    Based on the port names and context, this appears to be a <type>.
    Implement full functionality, following the existing codebase patterns.

For CDC Issues

Use Task tool:
  subagent_type: "gateflow:sv-refactor"
  prompt: |
    Add CDC synchronization at <file>:<line>.
    Signal <signal> crosses from <src_clk> to <dst_clk> domain
    without synchronization.
    
    Insert a cdc_2ff synchronizer (from GateFlow IP library).
    Ensure the synchronizer is properly reset.

---

Pattern Detection Rules

FIFO Detection

Confidence: HIGH if module has:
- wr_en/write + rd_en/read signals
- full + empty signals  
- data_in/wr_data + data_out/rd_data signals
- Single clock → fifo_sync
- Dual clock → fifo_async

CDC Detection

Confidence: HIGH if:
- Signal assigned in always_ff @(posedge clk_a)
- Signal read in always_ff @(posedge clk_b) where clk_a != clk_b
- No synchronizer between domains

Confidence: MEDIUM if:
- 2+ flip-flop chain detected but not using standard sync pattern

Protocol Detection

SPI: sclk + mosi + miso + cs_n (any naming variant)
UART: tx/rx + baud-related parameter
I2C: scl + sda (bidirectional)
AXI: *valid + *ready + *addr + *data patterns

Vendor IP Detection

Xilinx: IBUF, OBUF, BUFG, MMCME2, PLLE2, BRAM_TDP, DSP48E1
Lattice: SB_IO, SB_GB, SB_PLL40, SB_SPRAM, SB_RAM
Gowin: IBUF, OBUF, rPLL, SDPB, pROM
Intel: altpll, altsyncram, altddio

---

Integration with /gf Orchestrator

The /gf orchestrator can invoke IP detection:

• Before any new feature implementation (check what exists)
• After codebase mapping (enrich with IP analysis)
• When user says "what's missing" or "scan for gaps"

Integration with /gf-architect

Combine with codebase mapping:

1. /gf-architect maps the module hierarchy
2. /gf-ip-detect overlays IP analysis on the map
3. Result: hierarchy + IP opportunities + CDC issues

---

Commands

• "Scan for missing IP blocks" → full detection + report
• "Auto-fill missing modules" → detect + dispatch agents
• "What IP blocks does my project need?" → detection + suggestions
• "Find CDC issues" → focused CDC crossing analysis
• "Replace ad-hoc code with verified IP" → pattern match + swap

---

Extended Vendor IP Detection

Additional primitives to detect beyond existing list:

• Xilinx UltraScale+: URAM288, DSP48E2, BUFGCE, MMCME4_ADV, GTHE4_CHANNEL, STARTUPE3
• Intel Agilex: IOPLL, RAM20K, M20K, MLAB, tennm_ph2_iopll
• Lattice ECP5: EHXPLLL, DP16KD, TRELLIS_FF, DCUA, EXTREFB
• Gowin (extended): rPLL, PLLVR, SDPB, DPB, pROM, EMCU, DHCEN
• Microchip PolarFire: LSRAM, uSRAM, MACC, CCC, SERDES_IF
• Efinix: EFX_PLL, EFX_RAM_5K, EFX_DPRAM_5K, EFX_GBUFCE

False Positive Reduction

| Pattern | False Positive When | Action | |---|---|---| | 2FF chain | Inside shift register (3+ stages) | Skip | | 2FF chain | Both FFs same clock | Skip | | FIFO signals | Inside module named *fifo* | Skip | | valid/ready | AXI bus already using IP block | Skip | | SPI signals | Inside testbench files (tb_*, *_tb.sv) | Skip | | Vendor primitive | In comments or string literals | Skip |

Severity Scoring

| Severity | Criteria | Examples | |---|---|---| | CRITICAL | Data corruption, metastability | CDC without synchronizer | | HIGH | Missing module, empty stubs | Instantiated but undefined | | MEDIUM | Ad-hoc reimplementation | Hand-rolled FIFO, manual 2FF | | LOW | Style, minor optimization | Vendor primitive with OSS equivalent | | INFO | Already correct | Verified IP properly used |

Auto-Suggestion Integration

| Detected Pattern | Suggested Command | Parameters | |---|---|---| | Sync FIFO signals | /gf-ip add fifo_sync | WIDTH=detected, DEPTH=next_pow2 | | Async FIFO signals | /gf-ip add fifo_async | WIDTH=detected, DEPTH=8 | | 2FF CDC crossing | /gf-ip add cdc_2ff | default | | Multi-bit CDC handshake | /gf-ip add cdc_handshake | WIDTH=detected | | UART pattern | /gf-ip add uart | CLK_FREQ=detected, BAUD=115200 | | SPI pattern | /gf-ip add spi_master | CLK_DIV=computed | | AXI register pattern | /gf-ip add axi4lite_slave | ADDR_WIDTH=detected | | Button debounce | /gf-ip add debouncer | DEBOUNCE_MS=20 |