/hsb-ip-def

HOLOLINK_def.svh Macro Reference

Known-revision reference. Where this file conflicts with the public documentation, follow this file. Conflicts are noted inline.

If live HSB IP source is available, use it as the authority for the checked-out design. This file documents known rev 16'h2604 and backward-compatible rev 16'h2603; live HOLOLINK_top.sv wins for newer or locally modified IP.

Public-doc baseline

The closest public reference is the HSB user guide:

• Macros: docs/user_guide/ip_integration.md
• Ports: docs/user_guide/port_description.md

Repo: https://github.com/nvidia-holoscan/holoscan-sensor-bridge/tree/release-2.6.0-EA

The HSB documentation includes example macro values. They are not closed allow-sets. The skill enforces hard RTL/legal constraints such as byte-alignment, derived-width equality, and documented frequency bands; it does not warn merely because a legal value differs from bundled examples.

IP-root layout

The HSB IP RTL ships under at least two known directory roots:

Both roots contain identical subdirectories (top/, lib_axis/, packetizer/, sys_init/, ptp/, bootp/, etc.). All RTL citations in this file use the form <hsb-ip-root>/<subdir>/<file>.sv:<line> — substitute your root.

IP version compatibility

This file is written against 16'h2604. It is backward-compatible with 16'h2603 (the public release rev).

For an unknown or newer live revision, read top/HOLOLINK_top.sv before making source-sensitive claims. If the live source changes consumed macros, conditional port gates, or macro-to-RTL behavior, trust the live source and flag that this reference may need an update.

File wrapper requirement

HOLOLINK_def.svh must be wrapped in a guard + package:

`ifndef HOLOLINK_def
`define HOLOLINK_def

package HOLOLINK_pkg;

  // ... `define directives and localparam arrays ...

endpackage: HOLOLINK_pkg
`endif

The wrapper is required: top/HOLOLINK_top.sv:17 does `include "HOLOLINK_def.svh" and import HOLOLINK_pkg::*;. A file missing the wrapper will fail elaboration.

Macro index

Clocking

HIF_CLK_FREQ

Host Interface clock frequency, in Hz.

APB_CLK_FREQ

APB Interface clock frequency, in Hz. Used to compute I²C clock divider when ENUM_EEPROM is defined.

PTP_CLK_FREQ

PTP Interface clock frequency, in Hz.

Board identity

UUID

Universally unique identifier used in BOOTP enumeration to identify the board for bitfile flashing.

Enumeration

ENUM_EEPROM

Toggle. When defined, the IP reads MAC address and serial number from an external EEPROM over I²C bus 0 (7-bit address 0x50). When undefined, the user must drive i_mac_addr[], i_board_sn, and i_enum_vld ports.

EEPROM_REG_ADDR_BITS

EEPROM register address width.

Sensor datapath

DATAPATH_WIDTH

Width of the Sensor AXI-Stream tdata bus, in bits. The system-wide maximum sensor datapath width.

DATAKEEP_WIDTH

Width of the Sensor AXI-Stream tkeep bus, in bits.

DATAUSER_WIDTH

Width of the Sensor AXI-Stream tuser sideband signal, in bits. The HSB dataplane.md doc describes the per-bit semantics only for MIPI CSI-2 camera datapaths feeding an internal ISP:

• i_sif_axis_tuser[0] — asserted during cycles containing embedded data (MIPI Data Type 0x12).
• i_sif_axis_tuser[1] — asserted on the final clock cycle of a long packet (Line End signal).

The doc explicitly notes these signals are "used only for high-bandwidth camera with need for internal Image Signal Processing (ISP). For further details, please contact the NVIDIA Holoscan team." It does not define tuser semantics for non-MIPI sensor sources, and does not state a "default" or "typical" choice.

Sensor RX

SENSOR_RX_IF_INST

Number of Sensor RX (sensor → host) interfaces. Defining or undefining this macro gates an entire group of ports on the top module.

SIF_RX_WIDTH[]

Per-RX-interface AXI-Stream tdata width, in bits.

SIF_RX_DATA_GEN

Compile-time toggle for the per-port test-pattern injection capability. When defined, the IP instantiates a data_gen module per Sensor RX interface, each with its own APB register interface. The data_gen has an internal data_gen_ena register (defaults to 0 at reset) that the host software writes via APB at runtime to enable test injection per port. When enabled on a port, that port's input mux selects the generator output instead of i_sif_axis_*, and the IP asserts back-pressure to the external sensor (o_sif_axis_tready[i] = 0). When the register is 0 (the reset state), external sensor data flows. When the macro is undefined, the data_gen modules are not instantiated, the mux select is tied to 0, and only external sensor data ever flows.

SIF_RX_PACKETIZER_EN[]

Per-RX-interface packetizer enable flag.

SIF_RX_VP_COUNT[], SIF_RX_SORT_RESOLUTION[], SIF_RX_VP_SIZE[], SIF_RX_NUM_CYCLES[]

Packetizer internal parameters. Do not change per HSB documentation. Required when any element of SIF_RX_PACKETIZER_EN[] is 1; the corresponding element is a don't-care when its EN[i] is 0.

The validator does not enforce specific values for these; it only enforces presence (when packetizers are enabled) and array length consistency.

Sensor TX

SENSOR_TX_IF_INST

Number of Sensor TX (host → sensor) interfaces. Defining or undefining gates the TX port group.

SIF_TX_WIDTH[]

Per-TX-interface AXI-Stream tdata width.

SIF_TX_BUF_SIZE[]

Per-TX-interface FIFO depth, measured as a count of SIF_TX_WIDTH[i]-wide elements, not bytes. Backed by FPGA embedded RAM. The buffer primarily lets the IP absorb host-to-sensor data and apply backpressure toward the host when the sensor side cannot accept data immediately; larger values allow more TX-width elements to be stored at the cost of embedded RAM.

Host

HOST_WIDTH

Width of the Host AXI-Stream tdata bus, in bits. This is one scalar width shared by every host interface selected by HOST_IF_INST; the IP does not support per-host HOST_WIDTH[] values. The value is determined by the host-side Ethernet datapath connected to HSB and the line-rate/clock pairing implemented by the user's MAC, transceiver, and FPGA clocking chain.

Documented Ethernet line-rate / HOST_WIDTH / HIF_CLK_FREQ pairings:

Set HOST_WIDTH to the single AXI-Stream width shared by all HSB host interfaces. Set HIF_CLK_FREQ to the frequency of the clock actually driving that HSB host interface; it may be driven directly by the MAC or derived through a PLL/divider from another MAC/transceiver clock. Other byte-aligned widths are legal for the shared width; validation focuses on hard constraints and resource-risk thresholds.

HOSTKEEP_WIDTH

HOSTUSER_WIDTH

Width of the Host AXI-Stream tuser signal.

HOST_IF_INST

Number of Host (Ethernet) interfaces.

HOST_MTU

Maximum Ethernet packet payload, in bytes. Applies to both directions (ingress and egress).

Peripherals

SPI_INST

Number of SPI controller instances. Defining or undefining gates the SPI port group.

I2C_INST

Number of I²C controller instances.

UART_INST

Number of UART instances.

GPIO_INST

Number of bidirectional GPIO bits.

GPIO_RESET_VALUE

Reset value of GPIO output bits.

PTP

EXT_PTP

Toggle. When defined, the user provides PTP timestamps externally via i_ptp_sec[47:0] and i_ptp_nanosec[31:0]. When undefined, the IP generates timestamps internally and exposes o_ptp_sec[47:0], o_ptp_nanosec[31:0], and o_pps.

Clock synchronization (not in HSB public docs)

SYNC_CLK_HIF_APB and SYNC_CLK_HIF_PTP are advanced CDC-tightening toggles. See advanced-macros.md for canonical behavior, safety caveats, and RTL citations.

User registers and system init

REG_INST

Number of user-accessible APB register interfaces exposed by the IP.

N_INIT_REG

Number of entries in the init_reg[] boot-time write sequence.

init_reg[]

The boot-time register write sequence. The IP loops over the entries on rising edge of i_init, issuing APB writes; asserts o_init_done when complete.

Other

Advanced peripheral and dataplane macros

PERI_RAM_DEPTH and DISABLE_COE are advanced macros. See advanced-macros.md for canonical behavior, safety guidance, and RTL citations.

Module parameter (not a \define`)

BUILD_REV

48-bit Verilog parameter on the HOLOLINK_top module identifying the FPGA build revision. Not a \definemacro; cannot be set inHOLOLINK_def.svh`. Pass it via parameter override at instantiation:

HOLOLINK_top #(
  .BUILD_REV(48'h2604_DEAD_BEEF)
) u_hololink (
  ...
);

Cross-cutting rules summary

The following rules span multiple macros. Per-rule details and the canonical rule IDs (HD-Exxx, HD-Wxxx, HD-Ixxx) are in validation-rules.md.

1. Wrapper required. File must be wrapped in \ifndef HOLOLINK_def/`define HOLOLINK_def/package HOLOLINK_pkg;...endpackage; `endif`.
2. Byte-alignment of widths. All width macros must be divisible by 8.
3. Derived equalities. DATAKEEP_WIDTH = DATAPATH_WIDTH/8; HOSTKEEP_WIDTH = HOST_WIDTH/8. Mismatch is a hard error.
4. Per-port width caps. SIF_RX_WIDTH[i] ≤ DATAPATH_WIDTH; SIF_TX_WIDTH[i] ≤ DATAPATH_WIDTH.
5. init_reg[] cardinality. N_INIT_REG must equal the literal array length of init_reg[].
6. Conditional dependencies. EEPROM_REG_ADDR_BITS is only meaningful when ENUM_EEPROM is defined; SIF_RX_*[] arrays are only meaningful when SENSOR_RX_IF_INST is defined; SIF_TX_*[] arrays are only meaningful when SENSOR_TX_IF_INST is defined; the four packetizer "do not change" arrays are don't-cares for any element where SIF_RX_PACKETIZER_EN[i] = 0.
7. PTP / HIF clock ratio. PTP_CLK_FREQ < HIF_CLK_FREQ produces shorter CDC buffers (ptp/ptp_timer.sv:106-119); >= produces deeper CDC. Both work; the latter has more latency.
8. Silent peripheral fallback. Forgetting to define SENSOR_RX_IF_INST, SENSOR_TX_IF_INST, SPI_INST, I2C_INST, or UART_INST does not produce a compile error — the RTL falls back to dummy 1-bit logic. Validator emits a warning when a corresponding array (e.g. SIF_RX_WIDTH[]) is present but the gate macro is undefined.
9. BUILD_REV is not a \define`. Set it via Verilog parameter override at module instantiation.
10. Out-of-scope macros. A small set of macros that the IP and some workspace projects use are out of scope for this skill. The validator silently accepts them — never errors, warns, or names them. Consult your project's design owner if you encounter unfamiliar macros.