ecp5-sv-yosys-verilator

name

ecp5-sv-yosys-verilator

description

Use this skill whenever writing, reviewing, or debugging SystemVerilog for Lattice ECP5 FPGAs that must be compatible with both Yosys (nextpnr synthesis) and Verilator (simulation). Covers ECP5-specific primitives (EHXPLLL, DP16KD, PDPW16KD, MULT18X18D, ALU54B, DCCA, ODDRX1F, OSCG, JTAGG, USRMCLK, GSR, etc.), correct explicit instantiation patterns, Verilator stub strategies, macro guards, resource budgeting for ECP5-25K, and common pitfalls. Trigger on any mention of ECP5, nextpnr, Yosys synthesis with Verilator cosim, FPGA primitives in SV, DSP multipliers, block RAM configurations, or questions about making vendor hard IP simulate correctly. Use when the user asks about block RAM aspect ratios, DSP pipeline registers, dual/single-port RAM configs, or wants to explicitly instantiate limited hard resources rather than relying on inference.

ECP5 SystemVerilog: Yosys + Verilator Compatibility

Core Principle: Always Instantiate Hard Resources Explicitly

For DP16KD (56 on ECP5-25K) and MULT18X18D (28 on ECP5-25K), do not rely on Yosys inference. Inference is incomplete and unreliable: ALU54B features are not inferred at all, MULT9X9D (two 9x9 mults per DSP tile) is not supported by Yosys/nextpnr, and BRAM inference fails for wider-than-18-bit or multi-port patterns. Explicit instantiation gives you exact resource consumption, correct pipeline register placement, and predictable timing closure.

---

ECP5-25K Hard IP Budget (CABGA256/CABGA381)

Resource	Count	Notes
DP16KD	56	18Kbit true dual-port EBR; also configurable as PDPW16KD
MULT18X18D	28	18x18 signed multiplier; shares tile with ALU54B
ALU54B	14	54-bit accumulator; paired 2:1 with MULT18X18D
EHXPLLL	2	Integer-N PLL (2 on -25K, 4 on larger variants)
DCCA	56	Clock distribution / CE gates
CLKDIVF	4	Integer clock dividers
TRELLIS_ECLKBUF	8	Edge-clock buffers for DDR clocking
ECLKSYNCB	10	Edge-clock synchronizer/gate
OSCG	1	Internal ring oscillator (~155 MHz / DIV)
JTAGG	1	User access to JTAG port
USRMCLK	1	User access to SPI flash MCLK
GSR	1	Global Set/Reset network driver
IOLOGIC	128	High-speed I/O registers (DDR, gearbox)
SIOLOGIC	69	Single-data-rate I/O registers

---

The Golden Pattern: Macro-Guarded Instantiation

// Build system: -D SYNTHESIS for Yosys; omit for Verilator
`ifdef SYNTHESIS
  EHXPLLL #(...) pll_inst (...);
`else
  pll_sim_model pll_inst (...);
`endif

---

Block RAM: DP16KD and PDPW16KD

Two EBR Configurations

The same physical 18Kbit EBR block is configured as one of two named primitives:

DP16KD — True Dual-Port (TDP). Both ports read/write independently, each with its own clock. Port width up to 18 bits (16 data + 2 parity). Yosys internal name $__ECP5_DP16KD.

PDPW16KD — Pseudo Dual-Port Wide (SDP mode). Port A is write-only at 36 bits (32 data + 4 parity). Port B is read-only, configurable at 9, 18, or 36 bits — asymmetric reads allowed. This is the only way to achieve 32-bit data width from a single EBR. Yosys internal name $__ECP5_PDPW16KD.

These are mutually exclusive configurations of the same hardware — you cannot mix them.

DP16KD Aspect Ratios

DATA_WIDTH	Addr bits active	Depth	Data	Parity
1	ADA13:ADA0	16384x1	1	0
2	ADA13:ADA1	8192x2	2	0
4	ADA13:ADA2	4096x4	4	0
9	ADA13:ADA3	2048x8	8	1
18	ADA13:ADA4	1024x16	16	2
36	ADA13:ADA5	512x32	32	4

Port A and Port B can have different widths (asymmetric). The lower address pins not used by the selected width must be tied to 1'b0.

DP16KD Instantiation (1K x 16-bit TDP)

`ifdef SYNTHESIS
DP16KD #(
  .DATA_WIDTH_A(18),      // 16 data + 2 parity
  .DATA_WIDTH_B(18),
  .REGMODE_A("NOREG"),    // "OUTREG" adds 1 cycle latency, improves Fmax
  .REGMODE_B("NOREG"),
  .RESETMODE("SYNC"),
  .ASYNC_RESET_RELEASE("SYNC"),
  .WRITEMODE_A("NORMAL"), // "NORMAL"=read-before-write, "WRITETHROUGH"=pass-through
  .WRITEMODE_B("NORMAL"),
  .GSR("ENABLED"),
  .INIT_DATA("STATIC"),
  .CSDECODE_A("0b000"),   // chip select decode; 0b000 = always selected
  .CSDECODE_B("0b000")
) bram_i (
  // Port A
  .CLKA(clk_a), .CEA(1'b1), .OCEA(1'b1), .RSTA(rst),
  .WEA(we_a), .CSA0(1'b0), .CSA1(1'b0), .CSA2(1'b0),
  // For DATA_WIDTH=18: active addr is ADA13:ADA4; tie ADA3:ADA0 to 0
  .ADA13(addr_a[9]),.ADA12(addr_a[8]),.ADA11(addr_a[7]),.ADA10(addr_a[6]),
  .ADA9(addr_a[5]),.ADA8(addr_a[4]),.ADA7(addr_a[3]),.ADA6(addr_a[2]),
  .ADA5(addr_a[1]),.ADA4(addr_a[0]),
  .ADA3(1'b0),.ADA2(1'b0),.ADA1(1'b0),.ADA0(1'b0),
  // DIA17:DIA16 = parity (tie to 0 if unused)
  .DIA17(1'b0),.DIA16(1'b0),
  .DIA15(din_a[15]),.DIA14(din_a[14]),.DIA13(din_a[13]),.DIA12(din_a[12]),
  .DIA11(din_a[11]),.DIA10(din_a[10]),.DIA9(din_a[9]),.DIA8(din_a[8]),
  .DIA7(din_a[7]),.DIA6(din_a[6]),.DIA5(din_a[5]),.DIA4(din_a[4]),
  .DIA3(din_a[3]),.DIA2(din_a[2]),.DIA1(din_a[1]),.DIA0(din_a[0]),
  .DOA17(),.DOA16(),
  .DOA15(dout_a[15]),.DOA14(dout_a[14]),.DOA13(dout_a[13]),.DOA12(dout_a[12]),
  .DOA11(dout_a[11]),.DOA10(dout_a[10]),.DOA9(dout_a[9]),.DOA8(dout_a[8]),
  .DOA7(dout_a[7]),.DOA6(dout_a[6]),.DOA5(dout_a[5]),.DOA4(dout_a[4]),
  .DOA3(dout_a[3]),.DOA2(dout_a[2]),.DOA1(dout_a[1]),.DOA0(dout_a[0]),
  // Port B: identical structure; see references/ecp5_bram_guide.md for full listing
  .CLKB(clk_b),.CEB(1'b1),.OCEB(1'b1),.RSTB(rst),.WEB(we_b),
  .CSB0(1'b0),.CSB1(1'b0),.CSB2(1'b0)
  // ... addr/data ports B same pattern
);
`else
// Behavioral TDP
logic [15:0] mem_r [0:1023];
always_ff @(posedge clk_a) if (we_a) mem_r[addr_a] <= din_a;
always_ff @(posedge clk_a) dout_a <= mem_r[addr_a];
always_ff @(posedge clk_b) if (we_b) mem_r[addr_b] <= din_b;
always_ff @(posedge clk_b) dout_b <= mem_r[addr_b];
`endif

PDPW16KD — 36-bit Read (512×32 Symmetric)

Write and read both use 9-bit addresses (512 entries). All 36 DO outputs are connected; parity bits (DO35:DO32) left unconnected if unused.

`ifdef SYNTHESIS
PDPW16KD #(
  .DATA_WIDTH_W(36),      // Write port: always 36 in Yosys flow
  .DATA_WIDTH_R(36),      // Read port: 36-bit (symmetric with write)
  .REGMODE("NOREG"),
  .RESETMODE("SYNC"),
  .GSR("ENABLED"),
  .INIT_DATA("STATIC"),
  .CSDECODE_W("0b000"),
  .CSDECODE_R("0b000")
) pdpw_i (
  // Write port: 9-bit address (512 entries at 36-bit width)
  // CEW gates writes (no separate WEW in Yosys); BE0-3 enable byte lanes
  .CLKW(clk_w), .CEW(we),
  .CSW0(1'b0),.CSW1(1'b0),.CSW2(1'b0),
  .BE3(1'b1),.BE2(1'b1),.BE1(1'b1),.BE0(1'b1),
  .ADW8(waddr[8]),.ADW7(waddr[7]),.ADW6(waddr[6]),.ADW5(waddr[5]),
  .ADW4(waddr[4]),.ADW3(waddr[3]),.ADW2(waddr[2]),.ADW1(waddr[1]),.ADW0(waddr[0]),
  // 36-bit write data: DI35:DI32=parity, DI31:DI0=data
  .DI35(1'b0),.DI34(1'b0),.DI33(1'b0),.DI32(1'b0),
  .DI31(din[31]),.DI30(din[30]),.DI29(din[29]),.DI28(din[28]),
  .DI27(din[27]),.DI26(din[26]),.DI25(din[25]),.DI24(din[24]),
  .DI23(din[23]),.DI22(din[22]),.DI21(din[21]),.DI20(din[20]),
  .DI19(din[19]),.DI18(din[18]),.DI17(din[17]),.DI16(din[16]),
  .DI15(din[15]),.DI14(din[14]),.DI13(din[13]),.DI12(din[12]),
  .DI11(din[11]),.DI10(din[10]),.DI9(din[9]),.DI8(din[8]),
  .DI7(din[7]),.DI6(din[6]),.DI5(din[5]),.DI4(din[4]),
  .DI3(din[3]),.DI2(din[2]),.DI1(din[1]),.DI0(din[0]),
  // Read port: 9-bit addr for DATA_WIDTH_R=36 (512 entries, symmetric)
  .CLKR(clk_r),.CER(1'b1),.OCER(1'b1),.RST(rst),
  .CSR0(1'b0),.CSR1(1'b0),.CSR2(1'b0),
  .ADR13(raddr[8]),.ADR12(raddr[7]),.ADR11(raddr[6]),.ADR10(raddr[5]),
  .ADR9(raddr[4]),.ADR8(raddr[3]),.ADR7(raddr[2]),.ADR6(raddr[1]),
  .ADR5(raddr[0]),
  .ADR4(1'b0),.ADR3(1'b0),.ADR2(1'b0),.ADR1(1'b0),.ADR0(1'b0),
  .DO35(),.DO34(),.DO33(),.DO32(),  // parity — leave unconnected
  .DO31(dout[31]),.DO30(dout[30]),.DO29(dout[29]),.DO28(dout[28]),
  .DO27(dout[27]),.DO26(dout[26]),.DO25(dout[25]),.DO24(dout[24]),
  .DO23(dout[23]),.DO22(dout[22]),.DO21(dout[21]),.DO20(dout[20]),
  .DO19(dout[19]),.DO18(dout[18]),.DO17(dout[17]),.DO16(dout[16]),
  .DO15(dout[15]),.DO14(dout[14]),.DO13(dout[13]),.DO12(dout[12]),
  .DO11(dout[11]),.DO10(dout[10]),.DO9(dout[9]),.DO8(dout[8]),
  .DO7(dout[7]),.DO6(dout[6]),.DO5(dout[5]),.DO4(dout[4]),
  .DO3(dout[3]),.DO2(dout[2]),.DO1(dout[1]),.DO0(dout[0])
);
`else
logic [31:0] mem_r [0:511];
always_ff @(posedge clk_w) if (we) mem_r[waddr] <= din;
always_ff @(posedge clk_r) dout <= mem_r[raddr];
`endif

PDPW16KD — 18-bit Read (1K×16 Asymmetric)

Write uses 9-bit address (512×36), read uses 10-bit address (1024×18). Each 36-bit write word maps to two 18-bit read words (16 data + 2 parity each). DO35:DO18 are unused in 18-bit mode.

`ifdef SYNTHESIS
PDPW16KD #(
  .DATA_WIDTH_W(36),      // Write port: always 36 in Yosys flow
  .DATA_WIDTH_R(18),      // Read port: 18-bit (asymmetric)
  .REGMODE("NOREG"),
  .RESETMODE("SYNC"),
  .GSR("ENABLED"),
  .INIT_DATA("STATIC"),
  .CSDECODE_W("0b000"),
  .CSDECODE_R("0b000")
) pdpw_i (
  // Write port: 9-bit address (512 entries at 36-bit width)
  // CEW gates writes (no separate WEW in Yosys); BE0-3 enable byte lanes
  .CLKW(clk_w), .CEW(we),
  .CSW0(1'b0),.CSW1(1'b0),.CSW2(1'b0),
  .BE3(1'b1),.BE2(1'b1),.BE1(1'b1),.BE0(1'b1),
  .ADW8(waddr[8]),.ADW7(waddr[7]),.ADW6(waddr[6]),.ADW5(waddr[5]),
  .ADW4(waddr[4]),.ADW3(waddr[3]),.ADW2(waddr[2]),.ADW1(waddr[1]),.ADW0(waddr[0]),
  // 36-bit write data: DI35:DI32=parity, DI31:DI0=data
  .DI35(1'b0),.DI34(1'b0),.DI33(1'b0),.DI32(1'b0),
  .DI31(din[31]),.DI30(din[30]),.DI29(din[29]),.DI28(din[28]),
  .DI27(din[27]),.DI26(din[26]),.DI25(din[25]),.DI24(din[24]),
  .DI23(din[23]),.DI22(din[22]),.DI21(din[21]),.DI20(din[20]),
  .DI19(din[19]),.DI18(din[18]),.DI17(din[17]),.DI16(din[16]),
  .DI15(din[15]),.DI14(din[14]),.DI13(din[13]),.DI12(din[12]),
  .DI11(din[11]),.DI10(din[10]),.DI9(din[9]),.DI8(din[8]),
  .DI7(din[7]),.DI6(din[6]),.DI5(din[5]),.DI4(din[4]),
  .DI3(din[3]),.DI2(din[2]),.DI1(din[1]),.DI0(din[0]),
  // Read port: 10-bit addr for DATA_WIDTH_R=18 (1K entries)
  .CLKR(clk_r),.CER(1'b1),.OCER(1'b1),.RST(rst),
  .CSR0(1'b0),.CSR1(1'b0),.CSR2(1'b0),
  .ADR13(raddr[9]),.ADR12(raddr[8]),.ADR11(raddr[7]),.ADR10(raddr[6]),
  .ADR9(raddr[5]),.ADR8(raddr[4]),.ADR7(raddr[3]),.ADR6(raddr[2]),
  .ADR5(raddr[1]),.ADR4(raddr[0]),
  .ADR3(1'b0),.ADR2(1'b0),.ADR1(1'b0),.ADR0(1'b0),
  .DO17(),.DO16(),  // parity — leave unconnected
  .DO15(dout[15]),.DO14(dout[14]),.DO13(dout[13]),.DO12(dout[12]),
  .DO11(dout[11]),.DO10(dout[10]),.DO9(dout[9]),.DO8(dout[8]),
  .DO7(dout[7]),.DO6(dout[6]),.DO5(dout[5]),.DO4(dout[4]),
  .DO3(dout[3]),.DO2(dout[2]),.DO1(dout[1]),.DO0(dout[0])
);
`else
logic [31:0] mem_r [0:511];
always_ff @(posedge clk_w) if (we) mem_r[waddr] <= din;
always_ff @(posedge clk_r) dout <= raddr[0] ? mem_r[raddr[9:1]][31:16]
                                             : mem_r[raddr[9:1]][15:0];
`endif

---

DSP: MULT18X18D and ALU54B

Architecture

Each physical DSP tile contains one MULT18X18D and one ALU54B. The ECP5-25K has 28 MULT18X18Ds and 14 ALU54Bs (one ALU per two multipliers).

Critical limitation: MULT9X9D (Diamond's primitive for two independent 9x9 multiplications per tile) is not supported by Yosys or nextpnr. To use a DSP tile for two 9-bit multiplications, instantiate a single MULT18X18D with the two pairs of 9-bit operands packed into the 18-bit inputs, using the MSB as a zero sign extension:

// Pack two 9x9 unsigned multiplications into one MULT18X18D
// A = {9'b0, a_hi} or use MSB as sign — treat output P[35:18] and P[17:0] separately
// This is manual packing; results overlap if inputs have MSB set

For fully independent 9x9 multiplies, use two MULT18X18D instances.

MULT18X18D — Signed 18x18 Multiplier

Four pipeline register stages, each selectable on one of four DSP column clocks (CLK0–CLK3):

`ifdef SYNTHESIS
MULT18X18D #(
  // Each REG_*_CLK: "CLK0".."CLK3" or "NONE" (combinational)
  .REG_INPUTA_CLK  ("CLK0"), .REG_INPUTA_CE("CE0"),  .REG_INPUTA_RST("RST0"),
  .REG_INPUTB_CLK  ("CLK0"), .REG_INPUTB_CE("CE0"),  .REG_INPUTB_RST("RST0"),
  .REG_INPUTC_CLK  ("NONE"), // C addend to ALU54B; "NONE" if ALU not used
  .REG_PIPELINE_CLK("CLK0"), .REG_PIPELINE_CE("CE0"),.REG_PIPELINE_RST("RST0"),
  .REG_OUTPUT_CLK  ("CLK0"), .REG_OUTPUT_CE("CE0"),  .REG_OUTPUT_RST("RST0"),
  .CLK0_DIV("ENABLED"), .CLK1_DIV("ENABLED"),
  .CLK2_DIV("ENABLED"), .CLK3_DIV("ENABLED"),
  .HIGHSPEED_CLK("NONE"),
  .GSR("ENABLED"),
  .SOURCEB_MODE("B_SHIFT"),  // "B_SHIFT"=normal; "ROUND"=rounding mode
  .MULT_BYPASS("DISABLED"),  // "ENABLED"=combinational bypass (all regs ignored)
  .RESETMODE("SYNC"),
  .CAS_MATCH_REG("FALSE")
) mult_i (
  .CLK0(clk),.CLK1(1'b0),.CLK2(1'b0),.CLK3(1'b0),
  .CE0(1'b1),.CE1(1'b0),.CE2(1'b0),.CE3(1'b0),
  .RST0(rst),.RST1(1'b0),.RST2(1'b0),.RST3(1'b0),
  // 18-bit signed inputs; bit 17 is the sign bit
  .A17(a[17]),.A16(a[16]),.A15(a[15]),.A14(a[14]),
  .A13(a[13]),.A12(a[12]),.A11(a[11]),.A10(a[10]),
  .A9(a[9]),  .A8(a[8]),  .A7(a[7]),  .A6(a[6]),
  .A5(a[5]),  .A4(a[4]),  .A3(a[3]),  .A2(a[2]),  .A1(a[1]),  .A0(a[0]),
  .B17(b[17]),.B16(b[16]),.B15(b[15]),.B14(b[14]),
  .B13(b[13]),.B12(b[12]),.B11(b[11]),.B10(b[10]),
  .B9(b[9]),  .B8(b[8]),  .B7(b[7]),  .B6(b[6]),
  .B5(b[5]),  .B4(b[4]),  .B3(b[3]),  .B2(b[2]),  .B1(b[1]),  .B0(b[0]),
  // C: addend forwarded to ALU54B; tie to 0 if ALU not used
  .C17(1'b0),.C16(1'b0),.C15(1'b0),.C14(1'b0),
  .C13(1'b0),.C12(1'b0),.C11(1'b0),.C10(1'b0),
  .C9(1'b0),.C8(1'b0),.C7(1'b0),.C6(1'b0),
  .C5(1'b0),.C4(1'b0),.C3(1'b0),.C2(1'b0),.C1(1'b0),.C0(1'b0),
  // 36-bit signed product
  .P35(p[35]),.P34(p[34]),.P33(p[33]),.P32(p[32]),
  .P31(p[31]),.P30(p[30]),.P29(p[29]),.P28(p[28]),
  .P27(p[27]),.P26(p[26]),.P25(p[25]),.P24(p[24]),
  .P23(p[23]),.P22(p[22]),.P21(p[21]),.P20(p[20]),
  .P19(p[19]),.P18(p[18]),.P17(p[17]),.P16(p[16]),
  .P15(p[15]),.P14(p[14]),.P13(p[13]),.P12(p[12]),
  .P11(p[11]),.P10(p[10]),.P9(p[9]),  .P8(p[8]),
  .P7(p[7]),  .P6(p[6]),  .P5(p[5]),  .P4(p[4]),
  .P3(p[3]),  .P2(p[2]),  .P1(p[1]),  .P0(p[0]),
  // Cascade to ALU54B — leave unconnected if not using ALU
  .SIGNEDA(),.SIGNEDB(),.SOUTSIGNED(),
  .SOUT35(),.SOUT34(),.SOUT33(),.SOUT32(),
  .SOUT31(),.SOUT30(),.SOUT29(),.SOUT28(),.SOUT27(),.SOUT26(),
  .SOUT25(),.SOUT24(),.SOUT23(),.SOUT22(),.SOUT21(),.SOUT20(),
  .SOUT19(),.SOUT18(),.SOUT17(),.SOUT16(),.SOUT15(),.SOUT14(),
  .SOUT13(),.SOUT12(),.SOUT11(),.SOUT10(),.SOUT9(),.SOUT8(),
  .SOUT7(),.SOUT6(),.SOUT5(),.SOUT4(),.SOUT3(),.SOUT2(),.SOUT1(),.SOUT0()
);
`else
// Behavioral: 4-stage pipeline matching synthesis register configuration
logic signed [17:0] a_r, b_r;
logic signed [35:0] pipe_r, p_r;
always_ff @(posedge clk or posedge rst) begin
  if (rst) begin
    a_r <= '0; b_r <= '0; pipe_r <= '0; p_r <= '0;
  end else begin
    a_r    <= $signed(a);
    b_r    <= $signed(b);
    pipe_r <= a_r * b_r;
    p_r    <= pipe_r;
  end
end
assign p = p_r;
`endif

Latency with all 4 stages: 4 clock cycles (INPUT_A + INPUT_B in parallel = 1, PIPELINE = 1, OUTPUT = 1, plus the implicit multiply = 1). Adjust the behavioral model stage count to match.

Unsigned inputs: The hardware is signed. For unsigned 16-bit inputs: {2'b0, a_unsigned[15:0]} (zero-extend to 18 bits with sign bit = 0).

ALU54B — 54-bit Accumulator

Pairs with MULT18X18D via the SOUT cascade bus. Supports accumulation, addition, and subtraction of the multiplier output. nextpnr support is limited — it must share a DSP tile with its MULT18X18D; use LPF placement constraints if P&R fails. See references/dsp_guide.md for full port listing and a MAC example.

---

Clock and Oscillator Primitives

OSCG — Internal Ring Oscillator (~155 MHz / DIV)

One instance per device. Use for non-timing-critical functions (debug counters, watchdogs):

`ifdef SYNTHESIS
OSCG #(.DIV(4)) osc_i (.OSC(osc_clk)); // ~38 MHz; actual freq ±15%
`else
reg osc_r = 0;
always #13 osc_r = ~osc_r;             // 13 ns half-period ≈ 38 MHz
assign osc_clk = osc_r;
`endif

Valid DIV: 2, 4, 8, 16, 32, 64, 128.

TRELLIS_ECLKBUF — Edge Clock Buffer

Required when routing PLL output to IOLOGIC DDR registers:

`ifdef SYNTHESIS
TRELLIS_ECLKBUF eclkbuf_i (.A(pll_clkop), .Z(eclk));
`else
assign eclk = pll_clkop;
`endif

ECLKSYNCB — Edge Clock Gate

`ifdef SYNTHESIS
ECLKSYNCB eclksync_i (.ECLKI(eclk_in), .STOP(1'b0), .ECLKO(eclk_out));
`else
assign eclk_out = eclk_in;
`endif

---

Miscellaneous Hard IP

GSR — Global Set/Reset

Normally driven by configuration engine. Instantiate only for user-controlled global reset:

`ifdef SYNTHESIS
GSR gsr_i (.GSR(user_reset_n)); // active-low
`else
// No behavioral effect — drive resets directly in testbench
`endif

JTAGG — User JTAG Access

`ifdef SYNTHESIS
JTAGG #(.ER1("ENABLED"), .ER2("DISABLED")) jtag_i (
  .JTDO1(tdo), .JTDO2(1'b0),
  .JTDI(tdi), .JTCK(tck),
  .JRTI1(rti), .JSHIFT(shift),
  .JUPDATE(update), .JRSTN(rstn), .JCE1(ce1)
);
`else
// Drive from testbench JTAG BFM
`endif

USRMCLK — SPI Flash Clock

On packages where MCLK is not a standard I/O, access it via USRMCLK:

`ifdef SYNTHESIS
USRMCLK usrmclk_i (.USRMCLKI(spi_clk), .USRMCLKTS(spi_clk_oe_n));
`else
assign spi_mclk = spi_clk_oe_n ? 1'bz : spi_clk;
`endif

---

Yosys Synthesis Script

# synth_ecp5.tcl
yosys read_verilog -sv -D SYNTHESIS \
    src/top.sv src/core.sv src/mem_ctrl.sv

# -nobram: disable BRAM inference (using explicit DP16KD/PDPW16KD)
# -nodsp:  disable DSP inference (using explicit MULT18X18D)
yosys synth_ecp5 -top top -nobram -nodsp -json build/top.json

nextpnr-ecp5 \
    --25k \
    --package CABGA256 \
    --json build/top.json \
    --lpf constraints.lpf \
    --textcfg build/top.config \
    --report build/timing.json

ecppack build/top.config build/top.bit

Use -nobram -nodsp whenever you are explicitly instantiating all hard resources to prevent Yosys from also inferring instances from any remaining arithmetic operators.

---

Verilator Build

verilator --sv --cc --exe \
    --top-module tb_top -Isrc/ \
    sim/stubs/sim_stubs.sv \
    sim/tb_top.sv src/top.sv sim/main.cpp \
    -Wall --assert --x-assign unique \
    --build -j4

---

Stub Strategy Summary

Primitive	Simulation strategy
EHXPLLL	Dedicated stub (complex ports, lock delay)
DCCA	assign out = in
CLKDIVF	Inline toggle flop
TRELLIS_ECLKBUF	assign Z = A
ECLKSYNCB	assign ECLKO = ECLKI
DP16KD	Behavioral inferred RAM (much simpler than port mapping)
PDPW16KD	Behavioral inferred RAM
TRELLIS_DPR16X4	Inline array + flop
MULT18X18D	Behavioral signed registered multiply; match stage count
ALU54B	Behavioral accumulator
ODDRX1F/IDDRX1F	Inline dual-edge flop
BB/OB/IB	Inline assign
OSCG	always #N clock generator
JTAGG	Testbench-driven stub
USRMCLK	assign mclk = clk inline
GSR	No-op; drive resets directly in testbench

---

Common Pitfalls

1. MULT9X9D is not supported by Yosys/nextpnr. Diamond's MULT9X9D (SIMD 9x9 mode) does not exist in the open toolchain. Use MULT18X18D with 9-bit inputs zero-extended to 18 bits, or use two MULT18X18D instances for independent multiplications.

2. PDPW16KD write port is always 36 bits in the Yosys flow. Despite the Lattice datasheet describing variable write width, Yosys only models DATA_WIDTH_W=36. Do not attempt a narrower write port on PDPW16KD via Yosys — use DP16KD instead.

3. Unused address pins must be tied to 0, not left floating. For DATA_WIDTH=18, ADA3:ADA0 are unused and must be 1'b0. Floating address bits cause unpredictable write targeting.

4. MULT18X18D pipeline latency must match between synthesis and simulation. If the synthesis instance has 4 pipeline stages but the behavioral model has 1, functional simulation will pass and hardware will fail. Count your register stages carefully.

5. ALU54B requires placement in the same DSP tile as its MULT18X18D. If nextpnr cannot auto-place them adjacently, add an LPF LOCATE COMP constraint.

6. Use -nobram -nodsp in synth_ecp5 when being fully explicit. Without these flags, Yosys may infer additional BRAM/DSP instances from other expressions in your design, silently blowing your resource budget.

7. DP16KD and PDPW16KD are exclusive configurations of the same EBR. You cannot set DATA_WIDTH_A=36 and use DP16KD — that is a PDPW16KD. Attempting it will fail silently in Yosys or error in nextpnr.

8. OSCG frequency is approximate (±15%). Never use it directly for anything requiring accurate timing. Route it through an EHXPLLL if you need a precise derived frequency.

---

Reference Files

• references/sim_stubs.sv — Complete behavioral stubs for all common ECP5 primitives
• references/pll_params.md — PLL parameter tables for common input/output frequency pairs
• references/ecp5_bram_guide.md — Full DP16KD and PDPW16KD port mapping guide
• references/dsp_guide.md — Full MULT18X18D and ALU54B port listing with MAC example