codejunkie99/gf-protocols

GF-Protocols — Protocol Scaffolding Library

Not production IP cores. Correct, readable scaffolds that engineers customize. Plus the testbenches and integration code — that's where the real time goes.

Available Protocols

| Protocol | Priority | Scaffold Includes | |----------|----------|-------------------| | AXI4-Lite | 1 | Slave register interface + master BFM + TB | | SPI | 2 | Master + slave + loopback TB | | UART | 3 | TX + RX + loopback TB | | I2C | 4 | Master + slave model + TB | | AXI4-Full | 5 | Slave + burst master BFM + TB | | AXI-Stream | 6 | Source + sink + passthrough + TB | | Wishbone | 7 | Slave + master + TB |

Usage

When user requests a protocol interface:

1. Check if the IP library has a complete block (/gf-ip list)
2. If available as IP: suggest /gf-ip add <block> instead
3. If not available or user wants custom: generate scaffold

Scaffold Generation

Each scaffold includes:

• RTL skeleton with correct port names and widths
• Signal timing comments (when to assert/deassert)
• Testbench template with BFM (Bus Functional Model)
• Integration example showing how to wire into a design

Protocol References

Detailed protocol specifications are in references/:

• references/axi4-lite.md — AXI4-Lite signal list, timing, rules
• references/spi.md — SPI modes, timing, signal descriptions
• references/i2c.md — I2C protocol, addressing, clock stretching

When generating scaffolds, ALWAYS read the reference first for correct signal names, widths, and timing requirements.

---

AXI4-Lite Slave Scaffold

module axi4lite_slave_regs #(parameter int ADDR_WIDTH=4, DATA_WIDTH=32) (
    input  logic clk, rst_n,
    input  logic [ADDR_WIDTH-1:0] s_axi_awaddr, input logic s_axi_awvalid, output logic s_axi_awready,
    input  logic [DATA_WIDTH-1:0] s_axi_wdata, input logic [DATA_WIDTH/8-1:0] s_axi_wstrb,
    input  logic s_axi_wvalid, output logic s_axi_wready,
    output logic [1:0] s_axi_bresp, output logic s_axi_bvalid, input logic s_axi_bready,
    input  logic [ADDR_WIDTH-1:0] s_axi_araddr, input logic s_axi_arvalid, output logic s_axi_arready,
    output logic [DATA_WIDTH-1:0] s_axi_rdata, output logic [1:0] s_axi_rresp,
    output logic s_axi_rvalid, input logic s_axi_rready,
    output logic [DATA_WIDTH-1:0] reg0_out, reg1_out,
    input  logic [DATA_WIDTH-1:0] reg2_in, reg3_in
);
    // Write: accept AW+W, write register via wstrb, respond B
    // Read: accept AR, return register data on R
    // Customize: add registers, change address decode width
endmodule

SPI Master Scaffold

module spi_master_scaffold #(parameter int CLK_DIV=4) (
    input  logic clk, rst_n, cpol, cpha,
    input  logic [7:0] tx_data, input logic tx_valid, output logic tx_ready,
    output logic [7:0] rx_data, output logic rx_valid,
    output logic sclk, mosi, input logic miso, output logic cs_n
);
    // FSM: IDLE -> LEAD -> ACTIVE (8 bits MSB first) -> TRAIL -> DONE
    // Clock divider generates sclk from clk/(2*CLK_DIV)
    // CPOL/CPHA configure polarity and sample/shift edges
    // Customize: add multi-byte, variable width, DMA interface
endmodule

UART TX Scaffold

module uart_tx_scaffold #(parameter int CLK_FREQ=100_000_000, BAUD_RATE=115_200) (
    input  logic clk, rst_n,
    input  logic [7:0] tx_data, input logic tx_valid, output logic tx_ready,
    output logic tx
);
    // Baud generator: counter to CLK_FREQ/BAUD_RATE
    // FSM: IDLE -> START (1 low bit) -> DATA (8 bits LSB first) -> STOP (1 high bit)
    // tx_ready when IDLE
    // Customize: add parity, configurable data bits, RX companion
endmodule

I2C Master Scaffold

module i2c_master_scaffold #(parameter int CLK_FREQ=100_000_000, I2C_FREQ=100_000) (
    input  logic clk, rst_n,
    input  logic [6:0] slave_addr, input logic rw, input logic [7:0] wr_data,
    input  logic start, output logic [7:0] rd_data, output logic done, ack_err, busy,
    output logic scl_oen, sda_oen, input logic scl_i, sda_i
);
    // Quarter-period counter for I2C timing
    // FSM: IDLE -> START -> ADDR_BIT(8) -> ADDR_ACK -> WR/RD_BIT(8) -> WR/RD_ACK -> STOP
    // Open-drain: oen=0 drives low, oen=1 releases high via external pull-up
    // Customize: multi-byte transfers, clock stretching, repeated start
endmodule

GATEFLOW-RESULT Integration

---GATEFLOW-RESULT---
STATUS: PASS | FAIL | ERROR
PROTOCOL: axi4lite | spi | uart | i2c | wishbone | axi_stream
FILES: [generated files]
DETAILS: [summary]
---END-GATEFLOW-RESULT---