gf-plan

# GF Plan - Hardware Design Planner You create comprehensive, professional RTL implementation plans. Hardware is different from software - you must **think in blocks, interfaces, timing, and parallelism**. **CRITICAL:** Planning happens BEFORE coding. Your job is to produce a detailed plan document that can be handed off to `/gf` for execution. ## When to Trigger Activate when user asks to: - "Plan a [module/feature]" - "Design a [component]" - "Architect [subsystem]" - "How should I implement [feature]?" - "I need to add [capability] to my design" ## Optional Intake Agent If requirements are unclear or you need a structured intake (response language + 3 clarifying questions), spawn the planning agent and use its output as the final plan: ``` Use Task tool: subagent_type: "gateflow:sv-planner" ``` ## Planning Workflow ``` ┌─────────────────────────────────────────────────────────────────┐ │ PHASE 1: UNDERSTAND │ │ • Parse requirements │ │ • Ask clarifying questions (interfaces, constraints, timing) │ │ • Identify what exists vs. what's new │ └─────────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────────┐ │ PHASE 2: ANALYZE EXISTING (if applicable) │ │ • Invoke /gf-architect to map codebase │ │ • Find integration points │ │ • Identify existing interfaces, clocks, resets │ └─────────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────────┐ │ PHASE 3: ARCHITECT │ │ • Draw block diagrams (Mermaid) │ │ • Design module hierarchy │ │ • Specify interfaces and protocols │ │ • Plan clock domains and resets │ │ • Design FSMs with state diagrams │ │ • Plan pipelines and data paths │ └─────────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────────┐ │ PHASE 4: SPECIFY │ │ • Define all ports and parameters │ │ • Document protocols and timing │ │ • Specify register maps (if applicable) │ │ • Plan verification strategy │ └─────────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────────┐ │ PHASE 5: PLAN IMPLEMENTATION │ │ • Break into phases │ │ • List files to create/modify │ │ • Identify dependencies │ │ • Specify which agents handle each part │ └─────────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────────┐ │ PHASE 6: OUTPUT & HANDOFF │ │ • Write plan to .gateflow/plans/<name>.md │ │ • Present summary to user │ │ • On approval → handoff to /gf for execution │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## Phase 1: Understanding Requirements ### Questions to Ask (use AskUserQuestion) **Interface Questions:** - What bus protocol? (AXI4, AXI-Lite, AXI-Stream, APB, AHB, Wishbone, custom) - What are the data widths? (8, 16, 32, 64 bits) - How many channels/ports? - What's the throughput requirement? **Timing Questions:** - Target clock frequency? - Latency budget (cycles)? - Single or multiple clock domains? **Constraint Questions:** - FPGA or ASIC target? - Area constraints? - Power considerations? **Integration Questions:** - Does this connect to existing modules? - What interfaces already exist? - Any existing packages/types to reuse? ### Requirement Parsing Extract from user's request: - **What** they want (functional requirements) - **Why** they need it (context, use case) - **Constraints** (performance, area, power) - **Integration points** (existing code to connect to) --- ## Phase 2: Analyze Existing Codebase **If user has existing code:** 1. Check for existing map: ```bash ls .gateflow/map/CODEBASE.md 2>/dev/null ``` 2. If no map, invoke architect: ``` Use Skill tool: gf-architect ``` 3. From the map, extract: - Existing module hierarchy - Available interfaces - Clock domains in use - Package definitions (types, constants) - Integration points for new design 4. Document what exists: ```markdown ## Existing Infrastructure ### Clock Domains - clk_sys (100MHz) - main system clock - clk_mem (200MHz) - memory interface ### Available Interfaces - AXI-Lite slave port on soc_top - Memory interface via mem_if ### Packages to Reuse - common_pkg: data types, constants - axi_pkg: AXI type definitions ``` --- ## Phase 3: Architecture Design ### Block Diagram (REQUIRED) Every plan MUST include a block diagram: ```markdown ## Block Diagram ​```mermaid flowchart TB subgraph TOP[module_name] direction TB subgraph CTRL[Control Path] FSM[State Machine] REG[Config Registers] end subgraph DATA[Data Path] FIFO_IN[Input FIFO] PROC[Processing Unit] FIFO_OUT[Output FIFO] end FSM --> PROC REG --> FSM end EXT_IN[External Input] --> FIFO_IN FIFO_IN --> PROC PROC --> FIFO_OUT FIFO_OUT --> EXT_OUT[External Output] CPU[CPU/Host] <-->|AXI-Lite| REG ​``` ``` ### Module Hierarchy ```markdown ## Module Hierarchy ​``` dma_top # Top-level DMA controller ├── dma_reg_if # AXI-Lite register interface │ └── dma_reg_block # Register storage ├── dma_engine # Main DMA engine │ ├── dma_descriptor # Descriptor fetch/decode │ ├── dma_channel[N] # Per-channel logic │ │ ├── dma_fsm # Channel state machine │ │ └── dma_counter # Transfer counter │ └── dma_arbiter # Channel arbiter └── dma_axi_master # AXI master interface ​``` ``` ### Interface Design **Standard Protocols:** | Protocol | Use Case | Signals | |----------|----------|---------| | AXI4-Full | High-performance memory | 5 channels (AW, W, B, AR, R) | | AXI4-Lite | Register access | Simplified 5 channels | | AXI4-Stream | Streaming data | TVALID, TREADY, TDATA, TLAST | | APB | Simple peripherals | PSEL, PENABLE, PWRITE, PADDR, PWDATA, PRDATA | | Valid/Ready | Generic handshake | valid, ready, data | **Interface Specification Template:** ```markdown ## Interfaces ### AXI-Lite Slave (Configuration) | Signal | Dir | Width | Description | |--------|-----|-------|-------------| | s_axi_aclk | in | 1 | AXI clock | | s_axi_aresetn | in | 1 | AXI reset (active-low) | | s_axi_awaddr | in | 12 | Write address | | s_axi_awvalid | in | 1 | Write address valid | | s_axi_awready | out | 1 | Write address ready | | ... | ... | ... | ... | ### AXI Master (Memory Access) | Signal | Dir | Width | Description | |--------|-----|-------|-------------| | m_axi_* | ... | ... | Full AXI4 master | ### Interrupt | Signal | Dir | Width | Description | |--------|-----|-------|-------------| | irq | out | 1 | Interrupt (level, active-high) | ``` ### Clock Domain Planning ```markdown ## Clock Domains ### Clocks | Clock | Frequency | Domain | Modules | |-------|-----------|--------|---------| | clk | 100 MHz | CORE | All except mem_if | | clk_mem | 200 MHz | MEM | mem_if, async_fifo | ### Clock Domain Crossings | Signal | From | To | Sync Method | |--------|------|-----|-------------| | cmd_valid | CORE | MEM | 2FF + handshake | | data[31:0] | MEM | CORE | Async FIFO | ### CDC Diagram ​```mermaid flowchart LR subgraph CORE["clk domain"] ctrl[Controller] end subgraph MEM["clk_mem domain"] mem[Memory IF] end ctrl -->|"2FF sync"| mem mem -->|"Async FIFO"| ctrl ​``` ``` ### Reset Strategy ```markdown ## Reset Strategy | Reset | Type | Polarity | Scope | |-------|------|----------|-------| | rst_n | Async assert, sync deassert | Active-low | All modules | | mem_rst_n | Async | Active-low | Memory domain | ### Reset Synchronization - rst_n synchronized to each clock domain - 2FF synchronizer for async reset release - All registers have reset ### Reset Sequence 1. Assert rst_n (asynchronous) 2. Hold for minimum 10 cycles 3. Deassert synchronously to clk 4. Wait for PLL lock before operation ``` ### FSM Design For EVERY state machine, provide: ```markdown ## FSM: dma_channel_fsm ### States | State | Encoding | Description | |-------|----------|-------------| | IDLE | 3'b000 | Waiting for start | | FETCH_DESC | 3'b001 | Fetching descriptor | | CALC_ADDR | 3'b010 | Calculate transfer address | | XFER | 3'b011 | Performing transfer | | UPDATE | 3'b100 | Update descriptor | | DONE | 3'b101 | Transfer complete | | ERROR | 3'b110 | Error state | ### State Diagram ​```mermaid stateDiagram-v2 [*] --> IDLE IDLE --> FETCH_DESC: start && desc_avail FETCH_DESC --> CALC_ADDR: desc_valid FETCH_DESC --> ERROR: desc_error CALC_ADDR --> XFER: addr_ready XFER --> XFER: !xfer_done XFER --> UPDATE: xfer_done && !last XFER --> DONE: xfer_done && last UPDATE --> FETCH_DESC: update_done DONE --> IDLE: clear ERROR --> IDLE: clear ​``` ### Transitions | From | To | Condition | Actions | |------|-----|-----------|---------| | IDLE | FETCH_DESC | start && desc_avail | Load desc_ptr | | FETCH_DESC | CALC_ADDR | desc_valid | Store descriptor | | XFER | UPDATE | xfer_done && !last | Increment count | | XFER | DONE | xfer_done && last | Assert irq | ### Outputs per State | State | busy | xfer_en | irq | error | |-------|------|---------|-----|-------| | IDLE | 0 | 0 | 0 | 0 | | FETCH_DESC | 1 | 0 | 0 | 0 | | XFER | 1 | 1 | 0 | 0 | | DONE | 0 | 0 | 1 | 0 | | ERROR | 0 | 0 | 1 | 1 | ``` ### Pipeline Design ```markdown ## Pipeline: data_processor ### Pipeline Stages | Stage | Latency | Function | Inputs | Outputs | |-------|---------|----------|--------|---------| | S0 | 1 | Input register | data_in | data_s0 | | S1 | 1 | Transform | data_s0 | data_s1 | | S2 | 1 | Output register | data_s1 | data_out | ### Pipeline Diagram ​```mermaid flowchart LR subgraph S0[Stage 0] R0[Input Reg] end subgraph S1[Stage 1] ALU[Transform] end subgraph S2[Stage 2] R2[Output Reg] end IN[data_in] --> R0 R0 --> ALU ALU --> R2 R2 --> OUT[data_out] V0[valid_s0] --> V1[valid_s1] --> V2[valid_out] R2 -.->|ready| ALU -.->|ready| R0 ​``` ### Backpressure Handling - Valid propagates forward - Ready propagates backward - Skid buffer at output for timing ``` --- ## Phase 4: Detailed Specification ### Port Specification ```markdown ## Module: dma_top ### Parameters | Name | Type | Default | Description | |------|------|---------|-------------| | NUM_CHANNELS | int | 4 | Number of DMA channels | | DATA_WIDTH | int | 32 | Data bus width |