/hsb-ip-create-top

Fixed FPGA_top.sv Format

Use this reference when generating the top-level scaffold.

Output Intent

The generated file is an HSB integration scaffold, not a complete project top. It instantiates HOLOLINK_top and declares HSB-facing signals according to the active HOLOLINK_def.svh macros. This file is a reference/template for hooking up top-level signals and companion IP to the HSB IP.

Required Order

Emit sections in this order:

1. SPDX/Apache license header.
2. `include "HOLOLINK_def.svh".
3. module FPGA_top declaration, normally with no top-level ports.
4. HSB-facing declarations in fixed section order.
5. HOLOLINK_top instantiation.
6. endmodule.

Module Shell

Use this shape unless the user explicitly asks for board ports:

`include "HOLOLINK_def.svh"

module FPGA_top
  import HOLOLINK_pkg::*;
  import apb_pkg::*;
#(
  // Build identifier reported by HSB status/version registers:
  // BUILD_REV[47:16] = build date, BUILD_REV[15:0] = build revision.
  parameter BUILD_REV = 48'h0
)();

Comment Banner

Use this baked banner style:

//------------------------------------------------------------------------------
// Section Name
//------------------------------------------------------------------------------

Inside the HOLOLINK_top port map, use the same banner style for major groups and concise single-line comments for subgroups.

Signal Shape Rules

Preserve the HOLOLINK_top.sv declaration shape. Keep packed vector widths before the signal name and keep unpacked interface-array dimensions after the signal name. Do not collapse these ports into packed two-dimensional vectors.

Use this shape for multi-interface data buses:

logic [`DATAPATH_WIDTH-1:0]   sif_rx_axis_tdata [`SENSOR_RX_IF_INST-1:0];
logic [`DATAKEEP_WIDTH-1:0]   sif_rx_axis_tkeep [`SENSOR_RX_IF_INST-1:0];
logic [`DATAUSER_WIDTH-1:0]   sif_rx_axis_tuser [`SENSOR_RX_IF_INST-1:0];

logic [`DATAPATH_WIDTH-1:0]   sif_tx_axis_tdata [`SENSOR_TX_IF_INST-1:0];
logic [`DATAKEEP_WIDTH-1:0]   sif_tx_axis_tkeep [`SENSOR_TX_IF_INST-1:0];
logic [`DATAUSER_WIDTH-1:0]   sif_tx_axis_tuser [`SENSOR_TX_IF_INST-1:0];

logic [`HOST_WIDTH-1:0]       hif_rx_axis_tdata [`HOST_IF_INST-1:0];
logic [`HOSTKEEP_WIDTH-1:0]   hif_rx_axis_tkeep [`HOST_IF_INST-1:0];
logic [`HOSTUSER_WIDTH-1:0]   hif_rx_axis_tuser [`HOST_IF_INST-1:0];
logic [`HOST_WIDTH-1:0]       hif_tx_axis_tdata [`HOST_IF_INST-1:0];
logic [`HOSTKEEP_WIDTH-1:0]   hif_tx_axis_tkeep [`HOST_IF_INST-1:0];
logic [`HOSTUSER_WIDTH-1:0]   hif_tx_axis_tuser [`HOST_IF_INST-1:0];

Do not emit this packed 2-D form for those buses:

logic [`SENSOR_RX_IF_INST-1:0][`DATAPATH_WIDTH-1:0] sif_rx_axis_tdata;
logic [`HOST_IF_INST-1:0][`HOST_WIDTH-1:0] hif_rx_axis_tdata;

Use packed vectors for one-bit-per-interface signals:

logic [`SENSOR_RX_IF_INST-1:0] sif_rx_clk;
logic [`SENSOR_RX_IF_INST-1:0] sif_rx_rst;
logic [`SENSOR_RX_IF_INST-1:0] sif_rx_axis_tvalid;
logic [`SENSOR_RX_IF_INST-1:0] sif_rx_axis_tlast;
logic [`SENSOR_RX_IF_INST-1:0] sif_rx_axis_tready;

logic [`HOST_IF_INST-1:0] hif_rx_axis_tvalid;
logic [`HOST_IF_INST-1:0] hif_rx_axis_tlast;
logic [`HOST_IF_INST-1:0] hif_rx_axis_tready;

Use the APB register interface shape from HOLOLINK_top.sv; only psel, pready, and pserr are per-REG_INST vectors, and only prdata is a 32-bit unpacked array:

logic [`REG_INST-1:0] apb_psel;
logic                 apb_penable;
logic [31:0]          apb_paddr;
logic [31:0]          apb_pwdata;
logic                 apb_pwrite;
logic [`REG_INST-1:0] apb_pready;
logic [31:0]          apb_prdata [`REG_INST-1:0];
logic [`REG_INST-1:0] apb_pserr;

When ENUM_EEPROM is undefined, declare the host-indexed MAC array as:

logic [47:0] mac_addr [`HOST_IF_INST-1:0];

Declaration Sections

Emit these sections in order, omitting groups that are absent under the active defs macro set:

1. Clock and Reset

   • sys_rst
   • apb_clk, apb_rst
   • hif_clk, hif_rst
   • ptp_clk, ptp_rst
   • sif_rx_clk, sif_rx_rst only when SENSOR_RX_IF_INST is defined
   • sif_tx_clk, sif_tx_rst only when SENSOR_TX_IF_INST is defined

   Comment sif_rx_rst and sif_tx_rst at the declaration site. They are HSB outputs generated by HOLOLINK_top / reset_gen in the corresponding sensor interface clock domain.

2. User APB Interface

   • apb_psel
   • apb_penable
   • apb_paddr
   • apb_pwdata
   • apb_pwrite
   • apb_pready
   • apb_prdata
   • apb_pserr

3. Board Enumeration

   • Only when ENUM_EEPROM is undefined:
     • mac_addr [HOST_IF_INST-1:0]
     • board_sn
     • enum_vld

4. Initialization

   • init_done

5. Sensor RX Interface

   • Only when SENSOR_RX_IF_INST is defined:
     • sif_rx_axis_tvalid
     • sif_rx_axis_tlast
     • sif_rx_axis_tdata
     • sif_rx_axis_tkeep
     • sif_rx_axis_tuser
     • sif_rx_axis_tready

6. Sensor TX Interface

   • Only when SENSOR_TX_IF_INST is defined:
     • sif_tx_axis_tvalid
     • sif_tx_axis_tlast
     • sif_tx_axis_tdata
     • sif_tx_axis_tkeep
     • sif_tx_axis_tuser
     • sif_tx_axis_tready

7. Sensor Event

   • sif_event

8. Host Interface

   • hif_rx_axis_* for data entering HSB from the host side
   • hif_tx_axis_* for data leaving HSB toward the host side

9. Peripheral Interfaces

   • SPI only when SPI_INST is defined
   • I2C only when I2C_INST is defined
   • UART only when UART_INST is defined

10. GPIO

    • gpio_in
    • gpio_out
    • gpio_dir

11. Sensor Reset

    • sw_sys_rst
    • sw_sen_rst

12. PTP

    • Always declare ptp_clk and ptp_rst in Clock and Reset.
    • When EXT_PTP is undefined, declare ptp_sec, ptp_nanosec, and pps as outputs from HSB.
    • When EXT_PTP is defined, declare board-provided ptp_sec and ptp_nanosec signals and connect them to the live-source i_ptp_sec and i_ptp_nanosec ports.

Instantiation Rules

• Instantiate HOLOLINK_top as u_hololink_top.
• Pass .BUILD_REV ( BUILD_REV ).
• Preserve the HOLOLINK_top port order from live source when available.
• Include only ports present under the active macro set.
• Avoid trailing comma on the final active port connection.
• Use the same section order as the declarations.
• Do not connect absent optional ports.

Placeholder Policy

Do not invent project-specific drivers. Prefer declarations plus TODO comments:

// TODO: Drive sys_rst from board reset and clock/reset logic.
logic sys_rst;

Use tie-offs only for clearly inert placeholders when the scaffold would otherwise be misleading, and call them out as placeholders. Do not tie off active sensor, host, APB, or clock paths as if that were complete integration.

Packetizer Comment Language

When packetizer fields are enabled, summarize them in terms of data manipulation behavior:

// TODO: Connect sif_rx_axis_* to the sensor-side source. Packetizer enabled
// (SIF_RX_PACKETIZER_EN[0]=1) with VP_COUNT=4, VP_SIZE=128,
// SORT_RESOLUTION=16, NUM_CYCLES=1 -- runtime APB programming routes
// virtual ports and controls the data manipulation behavior.

Generated comments should keep packetizer wording generic and describe the configured data manipulation behavior.