fpga-patterns · diff
git:20260225.a4aeb64 to git:20260226.186740f
169 added, 69 removed. Audit C to C.
- # Fpga Patterns
-
- A comprehensive pattern library and knowledge base for fpga-integration.
+ # fpga-patterns
## Knowledge Base
- ### Core Concepts
- - **Fundamentals**: The foundational principles that govern fpga-integration
- - **Terminology**: Standard vocabulary and definitions used in the domain
- - **Standards**: Industry standards and specifications that apply
- - **Tools**: Common tools and frameworks used for fpga-integration
+ Synthesizable Verilog patterns for FPGA-MCU integration. Targeting Xilinx Artix-7 and Intel Cyclone V.
- ### Architecture Principles
- - Separation of concerns within fpga-integration implementations
- - Modularity and reusability of components
- - Scalability considerations for growing systems
- - Integration patterns with adjacent domains
+ ---
- ### Quality Attributes
- - **Correctness**: Implementations must meet functional requirements
- - **Maintainability**: Code and artifacts should be easy to understand and modify
- - **Performance**: Implementations should meet non-functional requirements
- - **Security**: Sensitive data and operations must be properly protected
+ ## Pattern 1: Register Bank with Read/Write Strobe
- ## Patterns
+ Simpler than AXI-Lite for SPI-connected FPGAs:
- ### Pattern 1: Structured Approach
- - Start with requirements analysis
- - Design before implementing
- - Validate against acceptance criteria
- - Document decisions and rationale
+ ```verilog
+ /* 8 x 32-bit register file with address/data/write-enable interface */
+ module reg_bank (
+ input wire clk,
+ input wire rst_n,
+ input wire [2:0] addr,
+ input wire [31:0] wdata,
+ input wire wen,
+ output reg [31:0] rdata,
+ /* Application outputs */
+ output wire [31:0] reg0_out,
+ output wire [31:0] reg1_out,
+ input wire [31:0] reg4_in, /* Read-back from hardware */
+ input wire [31:0] reg5_in
+ );
+ reg [31:0] regs [0:7];
- ### Pattern 2: Iterative Refinement
- - Begin with a minimal viable implementation
- - Gather feedback early and often
- - Refine based on real-world usage
- - Continuously improve based on metrics
+ always @(posedge clk or negedge rst_n) begin
+ if (!rst_n) begin
+ regs[0] <= 32'h0; regs[1] <= 32'h0;
+ regs[2] <= 32'h0; regs[3] <= 32'h0;
+ end else if (wen) begin
+ regs[addr] <= wdata;
+ end
+ end
- ### Pattern 3: Convention Over Configuration
- - Follow established conventions where they exist
- - Configure only what needs to deviate from defaults
- - Document any non-standard choices
- - Prefer explicit over implicit behavior
+ /* Read: hardware status registers override software writes */
+ always @(*) begin
+ case (addr)
+ 3'd4: rdata = reg4_in;
+ 3'd5: rdata = reg5_in;
+ default: rdata = regs[addr];
+ endcase
+ end
- ### Pattern 4: Defense in Depth
- - Validate at multiple levels
- - Handle errors gracefully at each layer
- - Provide meaningful feedback for failures
- - Log important events for debugging
+ assign reg0_out = regs[0];
+ assign reg1_out = regs[1];
+ endmodule
+ ```
- ## Anti-Patterns
+ ---
- ### Anti-Pattern 1: Premature Optimization
- - Optimizing before understanding the actual bottleneck
- - Adding complexity without measured need
- - Sacrificing readability for marginal performance gains
+ ## Pattern 2: Clock Domain Crossing — 2FF Synchronizer
- ### Anti-Pattern 2: Copy-Paste Without Understanding
- - Duplicating code without understanding its purpose
- - Propagating bugs through mechanical copying
- - Missing opportunities for abstraction
+ Signals crossing from one clock domain to another must be synchronized to avoid metastability.
- ### Anti-Pattern 3: Ignoring Standards
- - Deviating from conventions without clear justification
- - Creating inconsistency across the codebase
- - Making onboarding harder for new contributors
+ ```verilog
+ /* 2-flipflop synchronizer for a single control bit */
+ module sync_2ff (
+ input wire dst_clk,
+ input wire rst_n,
+ input wire sig_in, /* Asynchronous input */
+ output reg sig_out /* Synchronized output */
+ );
+ reg ff1;
- ### Anti-Pattern 4: Over-Engineering
- - Building for hypothetical future requirements
- - Adding abstraction layers without clear benefit
- - Creating complex solutions for simple problems
+ (* ASYNC_REG = "TRUE" *) reg sync_ff1; /* Vivado: keep close in placement */
+ (* ASYNC_REG = "TRUE" *) reg sync_ff2;
- ## References
+ always @(posedge dst_clk or negedge rst_n) begin
+ if (!rst_n) begin
+ sync_ff1 <= 0; sync_ff2 <= 0;
+ end else begin
+ sync_ff1 <= sig_in;
+ sync_ff2 <= sync_ff1;
+ end
+ end
+ assign sig_out = sync_ff2;
+ endmodule
+ ```
- ### Documentation
- - Official documentation for related tools and frameworks
- - Industry standards and specifications
- - Community best practices and guides
+ For multi-bit data: use a dual-clock FIFO or handshaking with acknowledgment.
- ### Learning Resources
- - Tutorials and walkthroughs for beginners
- - Advanced guides for experienced practitioners
- - Case studies and real-world examples
+ ---
- ### Tools
- - Development tools for fpga-integration
- - Testing and validation tools
- - Monitoring and observability tools
+ ## Pattern 3: Pulse Width Modulation (PWM) Generator
+
+ ```verilog
+ module pwm_gen #(
+ parameter integer CNT_WIDTH = 16 /* 100MHz / 65536 ≈ 1.5kHz */
+ )(
+ input wire clk,
+ input wire rst_n,
+ input wire [CNT_WIDTH-1:0] duty, /* 0=0%, 65535=100% */
+ output reg pwm_out
+ );
+ reg [CNT_WIDTH-1:0] cnt;
+
+ always @(posedge clk or negedge rst_n) begin
+ if (!rst_n) begin
+ cnt <= 0;
+ pwm_out <= 0;
+ end else begin
+ cnt <= cnt + 1;
+ pwm_out <= (cnt < duty) ? 1'b1 : 1'b0;
+ end
+ end
+ endmodule
+ ```
+
+ MCU sets `duty` register via SPI/AXI. Frequency = clk / (2^CNT_WIDTH).
+
+ ---
+
+ ## Pattern 4: Xilinx Block Design Tcl Automation
+
+ ```tcl
+ # Create Vivado project from Tcl (for version control of block design)
+ create_project myproject ./myproject -part xc7a100tcsg324-1
+
+ # Add HDL sources
+ add_files -norecurse {src/spi_slave.v src/reg_bank.v}
+
+ # Create block design with Zynq PS
+ create_bd_design "system"
+ create_bd_cell -type ip -vlnv xilinx.com:ip:processing_system7:5.5 ps7
+
+ # Apply Zynq preset (board-specific)
+ set_property CONFIG.preset {ZedBoard} [get_bd_cells ps7]
+
+ # Connect AXI-Lite custom IP
+ create_bd_cell -type module -reference axi_lite_regs axi_regs_0
+ apply_bd_automation -rule xilinx.com:bd_rule:axi4 \
+ -config {Master "/ps7/M_AXI_GP0" Clk "Auto"} [get_bd_intf_pins axi_regs_0/S_AXI]
+
+ # Save and generate
+ save_bd_design
+ generate_target all [get_files system.bd]
+ ```
+
+ ---
+
+ ## Pattern 5: SignalTap / ILA In-Logic Analyzer
+
+ Add debug capture to synthesized netlist (no external pins needed):
+
+ ```tcl
+ # Vivado: create ILA debug core via Tcl
+ create_debug_core u_ila ila
+ set_property C_DATA_DEPTH 1024 [get_debug_cores u_ila]
+ set_property C_TRIGIN_EN false [get_debug_cores u_ila]
+
+ # Connect signals to probe
+ set_property port_width 8 [get_debug_ports u_ila/probe0]
+ connect_debug_port u_ila/probe0 [get_nets spi_rx_byte]
+
+ set_property port_width 1 [get_debug_ports u_ila/probe1]
+ connect_debug_port u_ila/probe1 [get_nets spi_rx_valid]
+
+ implement_debug_core
+ ```
+
+ Or instantiate directly in Verilog:
+ ```verilog
+ ila_0 u_ila (
+ .clk (clk),
+ .probe0 (spi_rx_byte), /* 8 bits */
+ .probe1 (spi_rx_valid) /* 1 bit */
+ );
+ ```
+
+ ---
+
+ ## Anti-Patterns
+
+ - **Combinational loops**: any feedback path without a register causes simulation mismatch and synthesis failure. Add a register.
+ - **Missing `(* ASYNC_REG = "TRUE" *)` on CDC synchronizers**: Vivado placement optimizer separates the two FFs, increasing metastability risk.
+ - **Inferring RAM with `initial` blocks**: synthesis ignores `initial`; use reset logic or external initialization.
+ - **Blocking assignments in sequential blocks**: use non-blocking (`<=`) for clocked logic. Mixing causes simulation/synthesis mismatch.
+
+ ## References
+
+ - Xilinx UG901: Vivado Design Suite User Guide - Synthesis
+ - Xilinx PG209: AXI4-Lite Interface
+ - Intel AN 433: Constraining and Analyzing Source Synchronous Interfaces (Quartus)
+ - Cummings, "Simulation and Synthesis Techniques for Asynchronous FIFO Design" (SNUG 2002)