/hsb-ip-def

init_reg[] Cookbook

The init_reg[] array drives a boot-time write sequence: on rising edge of i_init, the IP loops through entries and issues APB writes, then asserts o_init_done when complete. Each entry is a 64-bit tuple {32'h<addr>, 32'h<data>}. The array length must equal N_INIT_REG.

This file documents the address-space conventions seen across in-scope archetypes and gives ready-to-copy templates per archetype.

Address-space map

The 32-bit APB address space the IP exposes is partitioned by high-order nibbles. Most projects only touch a handful of these ranges.

The HSB IP itself does not require any init_reg[] entries to function. The minimum useful sequence is the per-host destination-UDP-port writes (0x0200_0024, 0x0201_0024, …); even those can be omitted if the user's bitstream targets a DHCP-assigned port. Larger init sequences are project-side configuration of the surrounding Ethernet MAC IP, which lives outside the HSB IP boundary. In a generator profile, use init_reg: [] to explicitly suppress system init when using any defaults or archetype samples that might otherwise carry example writes.

Per-archetype templates

High-bandwidth single-sensor (2 entries)

Two host interfaces, default UDP destination port on each:

`define N_INIT_REG 2
localparam logic [63:0] init_reg [`N_INIT_REG] = '{
  {32'h0200_0024, 32'h0000_12B7},
  {32'h0201_0024, 32'h0000_12B7}
};

Mid-bandwidth baseline (2 entries)

Same shape as high-bandwidth — two host interfaces, two writes. In production, expand with vendor-specific MAC/PCS register init as required by your surrounding IP. Replace the placeholder addresses with the values supplied by your MAC IP datasheet:

`define N_INIT_REG 2
localparam logic [63:0] init_reg [`N_INIT_REG] = '{
  {32'h0200_0024, 32'h0000_12B7},
  {32'h0201_0024, 32'h0000_12B7}
  // Append vendor MAC/PCS init entries here. Each entry must be 64 bits.
};

Minimal gateway (2 entries)

Single host interface, single write — but you need both placeholder writes to keep the array a non-trivial example. In a real minimal-gateway design with one host you'd only need one entry:

`define N_INIT_REG 1
localparam logic [63:0] init_reg [`N_INIT_REG] = '{
  {32'h0200_0024, 32'h0000_12B7}
};

Ultra-minimal (1–2 entries)

The default UDP port write, plus optional MAC config:

`define N_INIT_REG 1
localparam logic [63:0] init_reg [`N_INIT_REG] = '{
  {32'h0200_0024, 32'h0000_12B7}
};

Very-high-speed (1 entry)

The high-speed archetype's corpus example uses a vendor MAC IP that handles its own initialization — the HSB IP only writes a single high-speed-archetype boot register:

`define N_INIT_REG 1
localparam logic [63:0] init_reg [`N_INIT_REG] = '{
  {32'h0120_0000, 32'h0000_0001}
};

Common mistakes

1. N_INIT_REG mismatched with array length. This is the #1 cause of silent breakage. The validator hard-errors on this (rule HD-E401). When you add or remove an entry, update both.
2. Missing \define N_INIT_REG`. Declaring init_reg[] without N_INIT_REG causes the sys_init module to be omitted entirely (the gating \ifdef N_INIT_REGat<hsb-ip-root>/top/HOLOLINK_top.sv:479` is false). The validator hard-errors (HD-E403).
3. Non-32-bit address or data fields. Each entry must be exactly {32'h<addr>, 32'h<data>} — 64 bits total. Mistakes like {32'h0200_0024, 16'h12B7} produce a 48-bit entry which Verilog elaboration may extend silently. The validator hard-errors (HD-E402).
4. Writing to an address that doesn't exist on the user's MAC. The HSB IP forwards the write blindly; if the address doesn't decode to anything in your MAC IP, the APB transaction may stall, producing a hung o_init_done. The validator can't catch this — it's project-specific.
5. Order matters. The IP writes entries strictly top-to-bottom, with a fixed inter-write delay (32 cycles per <hsb-ip-root>/sys_init/m_apb_reg.sv). If your MAC IP has dependencies (e.g., "set X before Y"), reflect them in the array order.

Where the IP consumes init_reg[]

For the curious: