Generated banner for Hsb Ip Def
Generated logo for Hsb Ip Def

Hsb Ip Def

NVIDIAOfficialCreated by Holoscan TeamDistributed by NVIDIA

  • Skill
  • Tool integration
  • Software development
  • Apache-2.0
  • Medium risk
  • Has scripts

From the author

Generate, validate, compare, or explain HSB HOLOLINK_def.svh macros. Do not use for FPGA_top.sv wrappers or packetizer-only derivation. Generation runs bundled Python scripts locally through shell commands and writes validated .svh output files after user-confirmed paths.
— the description by Holoscan Team

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The hsb-ip-def skill provides a structured approach to managing SystemVerilog configuration macros for the Holoscan Sensor Bridge (HSB) IP. It enables users to generate, validate, explain, and compare HOLOLINK_def.svh files, ensuring that macro definitions align with board-level requirements and IP constraints. The skill leverages bundled Python scripts to perform these operations, providing a reliable interface for configuring HSB IP revisions 16'h2603 and 16'h2604.

What it does

  • Generates HOLOLINK_def.svh files based on user-confirmed board requirements.
  • Validates existing configuration files using a dedicated linting script.
  • Explains macro semantics, legal values, and their impact on top-level ports.
  • Compares two configuration files to identify semantic differences.
  • Provides warnings for potential configuration footguns, such as HD-W3xx issues.
  • Integrates with other HSB skills for top-level wrapper creation and packetizer derivation.

When to use it

  • When you need to create a new HOLOLINK_def.svh file for a custom HSB board design.
  • When you need to verify that an existing configuration file is valid and follows IP constraints.
  • When you need to understand the effect of specific macros on the HSB IP dataplane or clocking.
  • When you need to diff two configurations to understand changes between board revisions.

Advantages

  • Ensures configuration consistency through automated validation.
  • Prevents common configuration errors with built-in rule checking.
  • Provides clear, grounded explanations for complex macro interactions.
  • Maintains compatibility with specific HSB IP revisions.

Usage examples

“Generate a new HOLOLINK_def.svh for a high-bandwidth single-sensor board.”
The agent will initiate the generation workflow, asking for board requirements one by one, building a profile, and running the generation script upon confirmation.
“Validate my current HOLOLINK_def.svh and check for any warnings.”
The agent will run the validation script, report any errors or warnings, and specifically highlight any HD-W3xx footgun warnings.
“Is it legal to set HOST_WIDTH=512 and PTP_CLK_FREQ=90_000_000?”
The agent will use the validation script or macro references to determine if the combination is legal and explain the reasoning.
“Compare my local def file with the baseline configuration.”
The agent will run the comparison script and provide a summary of the semantic differences between the two files.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/nvidia/hsb-ip-def/download
  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip hsb-ip-def.zip -d .agents/skills

Documentation by Holoscan Team

HSB IP Def Skill

Purpose

Use this skill through four workflows:

  • Generate a HOLOLINK_def.svh from confirmed board requirements.

  • Validate an existing def file with the bundled validator.

  • Explain / Reason about HSB IP macros, legality, and macro-driven ports.

  • Compare two def files semantically.

Scope

This skill owns the contents of HOLOLINK_def.svh: \definedirectives,localparamarrays, theHOLOLINK_pkgwrapper, and boot-timeinit_reg[]sequence. The surrounding top-level wrapper is owned byhsb-ip-create-top; packetizer-only profile derivation can be delegated to hsb-ip-packetizer`.

The file must use the standard guard plus package HOLOLINK_pkg wrapper. Load references/macro-reference.md for the full wrapper requirement and per-macro semantics.

Prerequisites

  • Python 3.9+ is required for the bundled scripts; PyYAML is required when reading YAML profiles.

  • The user must confirm file writes and shell commands unless they already asked for that exact operation.

  • A concrete def file path, pasted content, or confirmed generation profile is required before script-backed validation or generation.

  • Live HSB IP source is optional but preferred when validating against a specific checked-out IP revision.

Instructions

  • Run bundled script preflight from references/script-usage.md before Generate, Validate, Compare, or script-backed legality checks.

  • Never silently default a macro during Generate. Show the proposed value or inferred requirement and get user confirmation.

  • Ask one requirements question per turn during chat-driven Generate.

  • Use sensor-agnostic language unless the user says the design is camera-specific.

  • Avoid unsupported "typical", "common", "most designs", or corpus-frequency claims. Anchor choices to IP behavior, documented constraints, or user requirements.

  • Always surface HD-W3xx footgun warnings, even when the user asks only about errors.

  • Do not generate FPGA_top.sv; offer handoff to hsb-ip-create-top after a generated def file is validated.

  • Treat unfamiliar macros as project-specific unless they are documented in this skill's references or live HSB IP source.

Security Considerations

This skill can read and write local files and run shell commands through its bundled scripts. Before running a command or writing a file, state the command or path and get user confirmation unless the user already explicitly requested that exact operation. For pasted HOLOLINK_def.svh content, write only to a safely generated file in an isolated temporary directory and remove it after validation unless the user asks to keep it.

Version, Compatibility, And Live Source

This skill targets HSB IP rev 16'h2604 and is backward-compatible with 16'h2603. Live HSB IP source supersedes bundled references.

When source-sensitive behavior matters:

  1. Locate <hsb-ip-root>/top/HOLOLINK_top.sv. Known roots include hw/nvcpu_dgx_fpga/vrtl/hololink/ and public-release fpga/nv_hsb_ip/.

  2. Read HOLOLINK_REV and HOLOLINK_BACKWARD_COMPAT_REV.

  3. Trust live source for consumed macros, port gates, and RTL behavior when it differs from bundled references.

  4. Pass --ip-source <root> to scripts/validate_def.py when validating against a known source root.

Public-doc baseline:

  • https://github.com/nvidia-holoscan/holoscan-sensor-bridge/blob/release-2.6.0-EA/docs/user_guide/ip_integration.md

  • https://github.com/nvidia-holoscan/holoscan-sensor-bridge/blob/release-2.6.0-EA/docs/user_guide/port_description.md

Workflow Decision

  1. Generate when the user asks to create, scaffold, draft, design, or produce a HOLOLINK_def.svh.

  2. Validate when the user asks to lint, check, validate, or review a HOLOLINK_def.svh.

  3. Explain / Reason when the user asks what a macro does, whether a combination is legal, why validation fails, or how a macro affects HOLOLINK_top.

  4. Compare when the user asks to diff two def files or understand what changed between configurations.

Generate

Load references/generate-workflow.md and references/script-usage.md.

Follow the detailed Generate workflow in the reference: run preflight, classify supplied requirements, ask one requirements question per turn, build a flat YAML profile, run scripts/generate_def.py, show provenance for generated fields, and offer handoff to hsb-ip-create-top.

When packetizer fields are needed, invoke hsb-ip-packetizer with the known RX count, RX widths, and the user's data-manipulation description. Consume only that skill's packetizer_profile_overlay YAML keys, merge them into the in-progress profile, and continue full-file generation and validation here.

Validate

Load references/script-usage.md. Load references/validation-rules.md only when explaining specific rule IDs or validation behavior.

Steps:

  1. Run bundled script preflight once per session.

  2. Locate the file. If the user pastes content, tell them the generated temporary path before writing, ask for confirmation, use an isolated safe temp path, and clean it up after validation unless they ask to keep it. Otherwise use the provided path.

  3. Run <PY> scripts/validate_def.py <path> --json and do not reimplement validation in context.

  4. Group findings by severity: errors, warnings, then info. For each error, cite rule ID, line number, and macro when available.

  5. Always surface footgun warnings, especially HD-W3xx silent-fallback warnings.

  6. If clean, confirm the inferred archetype and IP version, then suggest the likely next check or handoff.

Explain / Reason

Load only the reference needed for the question:

Question typeReference
Macro semantics or legal valuesreferences/macro-reference.md
Validation rule behaviorreferences/validation-rules.md
Macro-driven port effectsreferences/top-port-map.md
init_reg[] and N_INIT_REGreferences/init-reg-cookbook.md
Advanced macrosreferences/advanced-macros.md
Example legal configurationsreferences/archetypes.md

For grounded legality questions, run preflight and prefer validating a concrete file or minimal synthetic file with scripts/validate_def.py over hand reasoning. Cite RTL line ranges from references when explaining why a rule exists.

Compare

Load references/script-usage.md, run preflight, then use <PY> scripts/compare_defs.py <a.svh> <b.svh> [--json|--text]. Summarize semantic differences, not whitespace or comment-only changes.

Limitations

  • Do not generate FPGA_top.sv; use hsb-ip-create-top after the defs file validates.

  • Do not derive packetizer-only field sets here when the packetizer behavior is underspecified; delegate that slice to hsb-ip-packetizer.

  • Do not treat bundled archetypes or corpus metadata as norms. They are examples and maintenance metadata, not defaults.

  • Do not silently accept unknown macros as validated HSB IP behavior unless live source or references document them.

Troubleshooting

  • Script preflight fails: report the missing Python or PyYAML requirement and stop before generation or validation.

  • Validation reports errors: group by severity, cite rule ID and line, and fix the defs file before offering top-level handoff.

  • Validation reports HD-W3xx warnings: surface them even when there are no errors because they describe silent RTL fallback risks.

  • Unknown macro appears: treat it as project-specific unless live HSB IP source or bundled references document it.

Available Scripts

Use <PY> selected during preflight from references/script-usage.md for every command.

ScriptPurposeArguments
scripts/generate_def.pyGenerate HOLOLINK_def.svh from an archetype and/or YAML/JSON profile; validates before writing--profile <path>, --archetype <slug>, -o <output>, optional --allow-random-uuid compatibility flag
scripts/validate_def.pyValidate a HOLOLINK_def.svh and emit JSON or text findings<path/to/HOLOLINK_def.svh>, optional --json or --text, optional --ip-source <root>
scripts/compare_defs.pyCompare two def files semantically, ignoring whitespace/comment-only changes<a.svh> <b.svh>, optional --json or --text
scripts/build_corpus_metadata.pyMaintenance helper to rebuild anonymized corpus metadata; do not run during normal user workflows<path1> [<path2> ...]

Bundled Resources

ResourceUse
references/generate-workflow.mdDetailed Generate workflow, requirement order, question style, and per-topic prompt guidance
references/script-usage.mdPreflight, command forms, and run_script() examples for bundled scripts
references/macro-reference.mdWrapper requirement, macro semantics, legal constraints, and RTL citations
references/validation-rules.mdRule catalog for validator findings
references/archetypes.mdIllustrative legal configurations; never treat as templates or frequency guidance
references/init-reg-cookbook.mdBoot-time APB write sequence patterns and address conventions
references/top-port-map.mdMacro-to-HOLOLINK_top port effects
references/advanced-macros.mdSYNC_CLK_HIF_APB, SYNC_CLK_HIF_PTP, PERI_RAM_DEPTH, and DISABLE_COE
assets/metadata/corpus.json, assets/metadata/corpus-stats.jsonMaintenance metadata only; do not cite corpus counts as user guidance
scripts/generate_def.pyGenerate a def file from a profile
scripts/validate_def.pyValidate a def file and emit JSON/text findings
scripts/compare_defs.pyCompare two def files semantically

Examples

  • Use hsb-ip-def to generate a HOLOLINK_def.svh for a new HSB board. Treat as Generate, run script preflight, classify supplied requirements, ask one requirement question per turn, and run scripts/generate_def.py only after the profile is confirmed.

  • Use hsb-ip-def to validate my existing HOLOLINK_def.svh and tell me whether any warnings are important. Treat as Validate, ask for or locate the file, run scripts/validate_def.py <path> --json, group findings by errors, warnings, and info, and always surface HD-W3xx footgun warnings.

  • Use hsb-ip-def to explain whether HOST_WIDTH=512 and PTP_CLK_FREQ=90_000_000 is legal. Treat as Explain / Reason, prefer a concrete validator-backed check over hand reasoning, and load only the macro or validation reference needed to explain the result.

Files

references/archetypes.md

Example configurations

Six example configurations distilled from real designs. These are illustrative — not templates you must pick from. Real designs vary continuously; use them to see legal macro combinations and as anchors for the questions in the Generate workflow. The sample defs are synthetic: edited copies of corpus material with all UUIDs replaced by placeholders, all comments stripped or rewritten as neutral guidance, and all out-of-scope macros removed.

The UUID is board-specific. The generator creates a random one by default; supply your own via the profile when you have one.

Common Boilerplate

UUID placeholder

Each sample refers back to this synthetic UUID placeholder instead of repeating it. Replace it with the board UUID through the profile, or omit uuid: and let the generator create one.

  // Board identity placeholder.
  `define UUID 128'h0000_0000_0000_0000_0000_0000_0000_0000
Init patterns

Use these notes to interpret the shortened init_reg[] callouts inside samples:

  • Standard two-register MAC pause init: N_INIT_REG = 2, with writes to 32'h0200_0024 and 32'h0201_0024, both using data 32'h0000_12B7.

  • Single-register IP-rev init: N_INIT_REG = 1, with write {32'h0120_0000, 32'h0000_0001}.

  • Single-register MAC pause init: N_INIT_REG = 1, with write {32'h0200_0024, 32'h0000_12B7}.

For real projects, replace these with the register sequence required by the surrounding Ethernet MAC, PCS, or board-control IP. See init-reg-cookbook.md for address-space conventions.

Example index

#ExampleUse caseDATAPATH_WIDTHHIF_CLK_FREQSensor RXSensor TXHost IFMTU
1High-bandwidth single-sensorOne very-fast sensor, redundant host links512~201 MHz1124096
2Mid-bandwidth baselineMultiple moderate-speed sensors, dual host64156.25 MHz2124096
3Minimal gatewayEdge device, single sensor, minimal peripherals64156.25 MHz1—11500
4Ultra-minimalSmall embedded target, TX-only825 MHz—111500
5Very-high-speedSingle ultra-fast sensor, single host512~322 MHz1114096
6Gigabit baseline1 GbE host, single sensor, common embedded camera/sensor designs8125 MHz1111500

Most real designs don't fall cleanly onto one of these. Use them to recognize patterns, not to box your design in. The validator returns inferred_archetype: null for non-matching designs; the file still passes.


1. High-bandwidth single-sensor

When to use. One very-fast sensor (e.g. high-resolution image, JESD204B aggregate, RF-conversion stream) feeding two redundant host interfaces. Datapath is wide (512 bits) to keep the per-cycle byte rate low; HIF clock is ~201 MHz to match a typical 100 GbE PHY clock.

Distinctive macros.

  • HIF_CLK_FREQ = 201_416_016

  • APB_CLK_FREQ = 100_000_000

  • DATAPATH_WIDTH = 512, DATAUSER_WIDTH = 1

  • SENSOR_RX_IF_INST = 1, SENSOR_TX_IF_INST = 1

  • HOST_WIDTH = 512, HOST_IF_INST = 2, HOST_MTU = 4096

  • ENUM_EEPROM defined

Sample.

`ifndef HOLOLINK_def
`define HOLOLINK_def

package HOLOLINK_pkg;

  // Clocking
  `define HIF_CLK_FREQ  201416016    // Host interface clock, Hz
  `define APB_CLK_FREQ  100000000    // APB clock, Hz
  `define PTP_CLK_FREQ  100707500    // PTP clock, Hz (95–105 MHz band)

  // Insert UUID block from Common Boilerplate.

  // Enumeration — read MAC/SN from external EEPROM on I2C bus 0, addr 0x50
  `define ENUM_EEPROM
  `ifdef ENUM_EEPROM
    `define EEPROM_REG_ADDR_BITS 8
  `endif

  // Sensor datapath
  `define DATAPATH_WIDTH  512
  `define DATAKEEP_WIDTH  `DATAPATH_WIDTH/8
  `define DATAUSER_WIDTH  1

  // Sensor RX
  `define SENSOR_RX_IF_INST  1
  `ifdef SENSOR_RX_IF_INST
    localparam integer SIF_RX_WIDTH         [`SENSOR_RX_IF_INST-1:0] = '{default:`DATAPATH_WIDTH};
    localparam integer SIF_RX_PACKETIZER_EN [`SENSOR_RX_IF_INST-1:0] = '{default:1};
    localparam integer SIF_RX_VP_COUNT      [`SENSOR_RX_IF_INST-1:0] = {4};
    localparam integer SIF_RX_SORT_RESOLUTION [`SENSOR_RX_IF_INST-1:0] = {16};
    localparam integer SIF_RX_VP_SIZE       [`SENSOR_RX_IF_INST-1:0] = {128};
    localparam integer SIF_RX_NUM_CYCLES    [`SENSOR_RX_IF_INST-1:0] = {1};
  `endif

  // Sensor TX
  `define SENSOR_TX_IF_INST  1
  `ifdef SENSOR_TX_IF_INST
    localparam integer SIF_TX_WIDTH    [`SENSOR_TX_IF_INST-1:0] = '{default:`DATAPATH_WIDTH};
    localparam integer SIF_TX_BUF_SIZE [`SENSOR_TX_IF_INST-1:0] = '{default:2048};
  `endif

  // Host interface
  `define HOST_WIDTH      512
  `define HOSTKEEP_WIDTH  `HOST_WIDTH/8
  `define HOSTUSER_WIDTH  1
  `define HOST_IF_INST    2
  `define HOST_MTU        4096

  // Peripherals
  `define SPI_INST  2
  `define I2C_INST  2
  `define GPIO_INST 16
  localparam [`GPIO_INST-1:0] GPIO_RESET_VALUE = 16'b0000000000001111;

  // User registers
  `define REG_INST 8

  // System initialization: standard two-register MAC pause init.
  // See Common Boilerplate for the exact `N_INIT_REG` and `init_reg[]` block.

endpackage: HOLOLINK_pkg
`endif

Things you'll likely change.

  1. UUID — supply your board's UUID via uuid: in the profile, or omit it and let the generator create one.

  2. PTP_CLK_FREQ — fine-tune for your PTP clock source (must be in 95–105 MHz).

  3. init_reg[] — extend with vendor-specific MAC/PCS register writes for your Ethernet MAC IP.

  4. GPIO_RESET_VALUE — set the boot state of board-specific control GPIOs.

  5. SIF_TX_BUF_SIZE — increase if your TX path needs more buffering than 2048 TX-width elements.


2. Mid-bandwidth baseline

When to use. Two moderate-speed sensors feeding two host interfaces. Datapath is 64 bits at 156.25 MHz — the standard configuration for boards using 10 GbE PHYs. This is the most common archetype in the corpus and a good starting point for any new design that doesn't have unusual bandwidth constraints.

Distinctive macros.

  • HIF_CLK_FREQ = 156_250_000

  • APB_CLK_FREQ = 19_531_250

  • DATAPATH_WIDTH = 64, DATAUSER_WIDTH = 2

  • SENSOR_RX_IF_INST = 2, SENSOR_TX_IF_INST = 1

  • HOST_WIDTH = 64, HOST_IF_INST = 2, HOST_MTU = 4096

  • ENUM_EEPROM defined; UART_INST = 1

Sample.

`ifndef HOLOLINK_def
`define HOLOLINK_def

package HOLOLINK_pkg;

  // Clocking
  `define HIF_CLK_FREQ  156250000
  `define APB_CLK_FREQ  19531250
  `define PTP_CLK_FREQ  100446545

  // Insert UUID block from Common Boilerplate.

  // Enumeration
  `define ENUM_EEPROM
  `ifdef ENUM_EEPROM
    `define EEPROM_REG_ADDR_BITS 8
  `endif

  // Sensor datapath
  `define DATAPATH_WIDTH  64
  `define DATAKEEP_WIDTH  `DATAPATH_WIDTH/8
  `define DATAUSER_WIDTH  2

  // Sensor RX (2 interfaces)
  `define SENSOR_RX_IF_INST  2
  `ifdef SENSOR_RX_IF_INST
    localparam integer SIF_RX_WIDTH         [`SENSOR_RX_IF_INST-1:0] = '{default:`DATAPATH_WIDTH};
    localparam integer SIF_RX_PACKETIZER_EN [`SENSOR_RX_IF_INST-1:0] = '{default:1};
    localparam integer SIF_RX_VP_COUNT      [`SENSOR_RX_IF_INST-1:0] = {2, 2};
    localparam integer SIF_RX_SORT_RESOLUTION [`SENSOR_RX_IF_INST-1:0] = {2, 2};
    localparam integer SIF_RX_VP_SIZE       [`SENSOR_RX_IF_INST-1:0] = {64, 64};
    localparam integer SIF_RX_NUM_CYCLES    [`SENSOR_RX_IF_INST-1:0] = {3, 3};
  `endif

  // Sensor TX
  `define SENSOR_TX_IF_INST  1
  `ifdef SENSOR_TX_IF_INST
    localparam integer SIF_TX_WIDTH    [`SENSOR_TX_IF_INST-1:0] = '{default:`DATAPATH_WIDTH};
    localparam integer SIF_TX_BUF_SIZE [`SENSOR_TX_IF_INST-1:0] = '{default:4096};
  `endif

  // Host
  `define HOST_WIDTH      64
  `define HOSTKEEP_WIDTH  `HOST_WIDTH/8
  `define HOSTUSER_WIDTH  1
  `define HOST_IF_INST    2
  `define HOST_MTU        4096

  // Peripherals
  `define SPI_INST  2
  `define I2C_INST  4
  `define UART_INST 1
  `define GPIO_INST 31
  localparam [`GPIO_INST-1:0] GPIO_RESET_VALUE = '0;

  // User registers
  `define REG_INST 8

  // System initialization: standard two-register MAC pause init.
  // See Common Boilerplate for the exact `N_INIT_REG` and `init_reg[]` block.

endpackage: HOLOLINK_pkg
`endif

Things you'll likely change.

  1. UUID — supply your board's UUID via uuid: in the profile, or omit it and let the generator create one.

  2. init_reg[] — extend with vendor-specific MAC/PCS register initialization when required by your surrounding IP. See init-reg-cookbook.md.

  3. SIF_RX_VP_COUNT[] and peers — the values shown are common but should match your packetizer requirements.

  4. SIF_TX_WIDTH — narrow per-port if your TX sensor only needs less than the full 64-bit datapath.

  5. GPIO_INST and GPIO_RESET_VALUE — size to your board's actual GPIO count and boot state.

  6. UART_INST — remove if no UART is needed.


3. Minimal gateway

When to use. Edge device with one sensor and one host. No TX path. Smaller MTU (1500 bytes) for compatibility with vanilla Ethernet networks. Soft enumeration (no EEPROM) — the user's top wrapper drives MAC and serial number directly.

Distinctive macros.

  • HIF_CLK_FREQ = 156_250_000

  • DATAPATH_WIDTH = 64, DATAUSER_WIDTH = 2

  • SENSOR_RX_IF_INST = 1, SENSOR_TX_IF_INST undefined

  • HOST_WIDTH = 64, HOST_IF_INST = 1, HOST_MTU = 1500

  • ENUM_EEPROM undefined (soft enumeration via input ports)

  • Minimal peripherals: SPI_INST = 1, I2C_INST = 1, GPIO_INST = 3

Sample.

`ifndef HOLOLINK_def
`define HOLOLINK_def

package HOLOLINK_pkg;

  // Clocking
  `define HIF_CLK_FREQ  156250000
  `define APB_CLK_FREQ  19531250
  `define PTP_CLK_FREQ  100446545

  // Insert UUID block from Common Boilerplate.

  // Enumeration — soft (no EEPROM); top wrapper must drive i_mac_addr,
  // i_board_sn, and i_enum_vld input ports.
  // `define ENUM_EEPROM         <-- left undefined intentionally

  // Sensor datapath
  `define DATAPATH_WIDTH  64
  `define DATAKEEP_WIDTH  `DATAPATH_WIDTH/8
  `define DATAUSER_WIDTH  2

  // Sensor RX (single interface)
  `define SENSOR_RX_IF_INST  1
  `ifdef SENSOR_RX_IF_INST
    localparam integer SIF_RX_WIDTH         [`SENSOR_RX_IF_INST-1:0] = '{default:`DATAPATH_WIDTH};
    localparam integer SIF_RX_PACKETIZER_EN [`SENSOR_RX_IF_INST-1:0] = '{default:1};
    localparam integer SIF_RX_VP_COUNT      [`SENSOR_RX_IF_INST-1:0] = {2};
    localparam integer SIF_RX_SORT_RESOLUTION [`SENSOR_RX_IF_INST-1:0] = {2};
    localparam integer SIF_RX_VP_SIZE       [`SENSOR_RX_IF_INST-1:0] = {64};
    localparam integer SIF_RX_NUM_CYCLES    [`SENSOR_RX_IF_INST-1:0] = {3};
  `endif

  // No Sensor TX

  // Host (single interface, standard MTU)
  `define HOST_WIDTH      64
  `define HOSTKEEP_WIDTH  `HOST_WIDTH/8
  `define HOSTUSER_WIDTH  1
  `define HOST_IF_INST    1
  `define HOST_MTU        1500

  // Minimal peripherals
  `define SPI_INST  1
  `define I2C_INST  1
  `define GPIO_INST 3
  localparam [`GPIO_INST-1:0] GPIO_RESET_VALUE = '0;

  // User registers
  `define REG_INST 8

  // System initialization: standard two-register MAC pause init.
  // See Common Boilerplate for the exact `N_INIT_REG` and `init_reg[]` block.

endpackage: HOLOLINK_pkg
`endif

Things you'll likely change.

  1. UUID — supply your board's UUID via uuid: in the profile, or omit it and let the generator create one.

  2. Decide between ENUM_EEPROM (read MAC/SN from EEPROM) and soft enumeration (drive i_mac_addr/i_board_sn/i_enum_vld ports). The sample shows soft.

  3. HOST_MTU = 1500 is conservative; bump to 4096 if your network supports jumbo frames.

  4. SPI_INST / I2C_INST / GPIO_INST — adjust to actual peripheral count, or undefine entirely if a peripheral isn't used.


4. Ultra-minimal

When to use. Very small embedded target where logic resources are at a premium. TX-only configuration — the IP forwards host commands to a sensor but does not receive sensor data. Datapath is 8 bits; clocks are slow (25 MHz). Peripheral RAM depth is overridden to keep memory tiny.

Distinctive macros.

  • HIF_CLK_FREQ = 25_000_000, APB_CLK_FREQ = 25_000_000

  • DATAPATH_WIDTH = 8

  • SENSOR_RX_IF_INST undefined (no RX path)

  • SENSOR_TX_IF_INST = 1, SIF_TX_WIDTH = {8}

  • HOST_WIDTH = 8, HOST_IF_INST = 1, HOST_MTU = 1500

  • PERI_RAM_DEPTH = 32

Sample.

`ifndef HOLOLINK_def
`define HOLOLINK_def

package HOLOLINK_pkg;

  // Clocking — slow, single-clock-domain design
  `define HIF_CLK_FREQ  25000000
  `define APB_CLK_FREQ  25000000
  `define PTP_CLK_FREQ  100000000

  // Insert UUID block from Common Boilerplate.

  // Enumeration
  `define ENUM_EEPROM
  `ifdef ENUM_EEPROM
    `define EEPROM_REG_ADDR_BITS 8
  `endif

  // Sensor datapath — minimal
  `define DATAPATH_WIDTH  8
  `define DATAKEEP_WIDTH  `DATAPATH_WIDTH/8
  `define DATAUSER_WIDTH  1

  // No Sensor RX
  // `define SENSOR_RX_IF_INST  1   <-- left undefined intentionally

  // Sensor TX only
  `define SENSOR_TX_IF_INST  1
  `ifdef SENSOR_TX_IF_INST
    localparam integer SIF_TX_WIDTH    [`SENSOR_TX_IF_INST-1:0] = '{default:`DATAPATH_WIDTH};
    localparam integer SIF_TX_BUF_SIZE [`SENSOR_TX_IF_INST-1:0] = '{default:2048};
  `endif

  // Host — narrow, single interface
  `define HOST_WIDTH      8
  `define HOSTKEEP_WIDTH  `HOST_WIDTH/8
  `define HOSTUSER_WIDTH  1
  `define HOST_IF_INST    1
  `define HOST_MTU        1500

  // Peripherals — minimal, with smaller peripheral RAM
  `define SPI_INST  1
  `define I2C_INST  1
  `define GPIO_INST 54
  localparam [`GPIO_INST-1:0] GPIO_RESET_VALUE = '0;
  `define PERI_RAM_DEPTH 32

  // User registers
  `define REG_INST 8

  // System initialization: standard two-register MAC pause init.
  // See Common Boilerplate for the exact `N_INIT_REG` and `init_reg[]` block.

endpackage: HOLOLINK_pkg
`endif

Things you'll likely change.

  1. UUID — supply your board's UUID via uuid: in the profile, or omit it and let the generator create one.

  2. GPIO_INST — size to your actual GPIO count; the value shown supports a wide pinout.

  3. PERI_RAM_DEPTH = 32 is the smallest reasonable depth; raise to 64 or 128 if your I²C transactions are longer.

  4. init_reg[] — extend for vendor-specific MAC initialization (the IP version of the MAC may need a few hundred bytes of register writes).

  5. The lack of Sensor RX ports means your top wrapper does not connect any i_sif_axis_* signals — make sure your top instantiation reflects that.


5. Very-high-speed

When to use. A single ultra-fast sensor (322 MHz HIF clock, 512-bit datapath) with a single host link. Often paired with SIF_RX_DATA_GEN to provide a per-port test-injection capability that the host can drive at runtime — useful for in-system diagnostics or simulation-driven bringup. Defining the macro doesn't bypass real sensor data; it just adds the capability. Soft enumeration is common.

Distinctive macros.

  • HIF_CLK_FREQ = 322_265_625

  • APB_CLK_FREQ = 50_000_000

  • DATAPATH_WIDTH = 512

  • SENSOR_RX_IF_INST = 1 with SIF_RX_DATA_GEN defined for bringup

  • HOST_WIDTH = 512, HOST_IF_INST = 1, HOST_MTU = 4096

  • ENUM_EEPROM undefined

Sample.

`ifndef HOLOLINK_def
`define HOLOLINK_def

package HOLOLINK_pkg;

  // Clocking — high-speed transceivers
  `define HIF_CLK_FREQ  322265625
  `define APB_CLK_FREQ  50000000
  `define PTP_CLK_FREQ  100000000

  // Insert UUID block from Common Boilerplate.

  // Enumeration — soft (no EEPROM)
  // `define ENUM_EEPROM         <-- left undefined intentionally

  // Sensor datapath
  `define DATAPATH_WIDTH  512
  `define DATAKEEP_WIDTH  `DATAPATH_WIDTH/8
  `define DATAUSER_WIDTH  1

  // Sensor RX with built-in data generator (for bringup; disable in production)
  `define SENSOR_RX_IF_INST  1
  `ifdef SENSOR_RX_IF_INST
    `define SIF_RX_DATA_GEN
    localparam integer SIF_RX_WIDTH         [`SENSOR_RX_IF_INST-1:0] = '{default:`DATAPATH_WIDTH};
    localparam integer SIF_RX_PACKETIZER_EN [`SENSOR_RX_IF_INST-1:0] = '{default:1};
    localparam integer SIF_RX_VP_COUNT      [`SENSOR_RX_IF_INST-1:0] = {4};
    localparam integer SIF_RX_SORT_RESOLUTION [`SENSOR_RX_IF_INST-1:0] = {16};
    localparam integer SIF_RX_VP_SIZE       [`SENSOR_RX_IF_INST-1:0] = {128};
    localparam integer SIF_RX_NUM_CYCLES    [`SENSOR_RX_IF_INST-1:0] = {1};
  `endif

  // Sensor TX
  `define SENSOR_TX_IF_INST  1
  `ifdef SENSOR_TX_IF_INST
    localparam integer SIF_TX_WIDTH    [`SENSOR_TX_IF_INST-1:0] = '{default:`DATAPATH_WIDTH};
    localparam integer SIF_TX_BUF_SIZE [`SENSOR_TX_IF_INST-1:0] = '{default:2048};
  `endif

  // Host
  `define HOST_WIDTH      512
  `define HOSTKEEP_WIDTH  `HOST_WIDTH/8
  `define HOSTUSER_WIDTH  1
  `define HOST_IF_INST    1
  `define HOST_MTU        4096

  // Peripherals
  `define SPI_INST  1
  `define I2C_INST  1
  `define GPIO_INST 31
  localparam [`GPIO_INST-1:0] GPIO_RESET_VALUE = '0;

  // User registers
  `define REG_INST 8

  // System initialization: single-register IP-rev init.
  // See Common Boilerplate for the exact `N_INIT_REG` and `init_reg[]` block.

endpackage: HOLOLINK_pkg
`endif

Things you'll likely change.

  1. UUID — supply your board's UUID via uuid: in the profile, or omit it and let the generator create one.

  2. Decide whether to keep SIF_RX_DATA_GEN for production. Defining it adds per-port runtime-controlled test injection (host-driven via APB) — useful for in-system diagnostics. Removing the \define` removes the data_gen modules entirely, saving logic and embedded RAM. Keep it on if you want diagnostic injection capability; remove if you're tight on resources.

  3. init_reg[] — minimal as shown; some boards need additional MAC/PCS configuration entries.

  4. SIF_TX_BUF_SIZE — increase if your TX path needs deeper FIFO storage in TX-width elements.

  5. Decide between ENUM_EEPROM and soft enumeration based on your board.


6. Gigabit baseline

When to use. A 1 GbE host link with a single sensor in each direction. Typical for embedded camera/sensor boards on standard 1 GbE infrastructure: 8-bit GMII-style host interface clocked at 125 MHz (8 b × 125 MHz = 1 Gbps). Compatible with vanilla Ethernet (1500-byte MTU). Distinguished from ultra-minimal (which is also 8-bit but TX-only at 25 MHz) by the 1 GbE clocking and the presence of Sensor RX.

Distinctive macros.

  • HIF_CLK_FREQ = 125_000_000 (8 b × 125 MHz = 1 Gbps)

  • APB_CLK_FREQ = 19_531_250

  • DATAPATH_WIDTH = 8, DATAUSER_WIDTH = 1

  • SENSOR_RX_IF_INST = 1, SENSOR_TX_IF_INST = 1

  • HOST_WIDTH = 8, HOST_IF_INST = 1, HOST_MTU = 1500

  • ENUM_EEPROM defined; minimal peripherals (SPI_INST = 1, I2C_INST = 1, GPIO_INST = 16)

Sample.

`ifndef HOLOLINK_def
`define HOLOLINK_def

package HOLOLINK_pkg;

  // Clocking — 1 GbE: 8 bits × 125 MHz
  `define HIF_CLK_FREQ  125000000
  `define APB_CLK_FREQ  19531250
  `define PTP_CLK_FREQ  100446545

  // Insert UUID block from Common Boilerplate.

  // Enumeration
  `define ENUM_EEPROM
  `ifdef ENUM_EEPROM
    `define EEPROM_REG_ADDR_BITS 8
  `endif

  // Sensor datapath
  `define DATAPATH_WIDTH  8
  `define DATAKEEP_WIDTH  `DATAPATH_WIDTH/8
  `define DATAUSER_WIDTH  1

  // Sensor RX
  `define SENSOR_RX_IF_INST  1
  `ifdef SENSOR_RX_IF_INST
    localparam integer SIF_RX_WIDTH         [`SENSOR_RX_IF_INST-1:0] = '{default:`DATAPATH_WIDTH};
    localparam integer SIF_RX_PACKETIZER_EN [`SENSOR_RX_IF_INST-1:0] = '{default:1};
    localparam integer SIF_RX_VP_COUNT      [`SENSOR_RX_IF_INST-1:0] = {1};
    localparam integer SIF_RX_SORT_RESOLUTION [`SENSOR_RX_IF_INST-1:0] = {8};
    localparam integer SIF_RX_VP_SIZE       [`SENSOR_RX_IF_INST-1:0] = {64};
    localparam integer SIF_RX_NUM_CYCLES    [`SENSOR_RX_IF_INST-1:0] = {1};
  `endif

  // Sensor TX
  `define SENSOR_TX_IF_INST  1
  `ifdef SENSOR_TX_IF_INST
    localparam integer SIF_TX_WIDTH    [`SENSOR_TX_IF_INST-1:0] = '{default:`DATAPATH_WIDTH};
    localparam integer SIF_TX_BUF_SIZE [`SENSOR_TX_IF_INST-1:0] = '{default:2048};
  `endif

  // Host — 1 GbE
  `define HOST_WIDTH      8
  `define HOSTKEEP_WIDTH  `HOST_WIDTH/8
  `define HOSTUSER_WIDTH  1
  `define HOST_IF_INST    1
  `define HOST_MTU        1500

  // Peripherals
  `define SPI_INST  1
  `define I2C_INST  1
  `define GPIO_INST 16
  localparam [`GPIO_INST-1:0] GPIO_RESET_VALUE = '0;

  // User registers — at least 1 required by the IP
  `define REG_INST 1

  // System initialization: single-register MAC pause init.
  // See Common Boilerplate for the exact `N_INIT_REG` and `init_reg[]` block.

endpackage: HOLOLINK_pkg
`endif

Things you'll likely change.

  1. UUID — supply your board's UUID via uuid: in the profile, or omit it and let the generator create one.

  2. init_reg[] — extend with your 1 GbE MAC IP's register configuration (entries needed depend on your specific MAC IP — check its datasheet).

  3. Decide between ENUM_EEPROM (production) and soft enumeration (eval/sim).

  4. HOST_MTU = 1500 is the standard for 1 GbE; bump to a non-standard value only if your network supports jumbo and you've sized buffers accordingly.

  5. GPIO_INST — adjust to your board's actual GPIO pin count.


Common adjustments across all archetypes

These edits apply to any archetype.

AdjustmentWhat to change
Board UUIDReplace 128'h0000… with your unique 128-bit identifier. The skill never auto-generates this for you.
Add a SPI interfaceIncrement SPI_INST and connect the additional SPI port group in your top wrapper. Range 1..8.
Add an I²C interfaceIncrement I2C_INST. Range 1..8.
Change MTUSet HOST_MTU = 4096 for jumbo frames or 1500 for standard Ethernet. The IP buffer scales automatically (HOST_BUF_DEPTH = HOST_MTU * 2 / (HOST_WIDTH/8)).
Wider Sensor RXIncrease DATAPATH_WIDTH to a power-of-2 byte-aligned value; widen SIF_RX_WIDTH[i] to match. Values above 1024 trigger a resource-impact warning.
Add user registersSet REG_INST higher (max 8); each instance gives the user 4 KB of APB-addressable register space.
Disable a peripheralComment out the corresponding \define (SPI_INST, I2C_INST, UART_INST`). The RTL will silently fall back to dummy logic; the validator warns if any per-port arrays remain.
External PTP timestampsDefine EXT_PTP and drive i_ptp_sec[47:0] / i_ptp_nanosec[31:0] in your top wrapper instead of consuming the IP's internal PTP outputs.

For deeper per-macro guidance see macro-reference.md. For init_reg[] address-space conventions see init-reg-cookbook.md.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Python

The author says: Targets HSB IP rev 16'h2604; backward-compatible with 16'h2603 (the public release rev). Prefer live HSB IP source when available; warn on unknown revisions. Requires Python 3.9+ with PyYAML for the generator.

Security

What our scanner noticed· Medium risk

  • Large base64-encoded blobs
  • Instructions that use the network
  • Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
Holoscan Team
Publisher
NVIDIA (Official)
Distributed by
NVIDIA
Source
NVIDIA/skills · skills/hsb-ip-def · commit fce3cca
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE-APACHE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Holoscan Team or NVIDIA.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download hsb-ip-def.zip