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

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/nvidia/hsb-ip-def/download

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:

Locate <hsb-ip-root>/top/HOLOLINK_top.sv. Known roots include hw/nvcpu_dgx_fpga/vrtl/hololink/ and public-release fpga/nv_hsb_ip/.
Read HOLOLINK_REV and HOLOLINK_BACKWARD_COMPAT_REV.
Trust live source for consumed macros, port gates, and RTL behavior when it differs from bundled references.
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

Generate when the user asks to create, scaffold, draft, design, or produce a HOLOLINK_def.svh.
Validate when the user asks to lint, check, validate, or review a HOLOLINK_def.svh.
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.
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:

Run bundled script preflight once per session.
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.
Run <PY> scripts/validate_def.py <path> --json and do not reimplement validation in context.
Group findings by severity: errors, warnings, then info. For each error, cite rule ID, line number, and macro when available.
Always surface footgun warnings, especially HD-W3xx silent-fallback warnings.
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 type	Reference
Macro semantics or legal values	`references/macro-reference.md`
Validation rule behavior	`references/validation-rules.md`
Macro-driven port effects	`references/top-port-map.md`
`init_reg[]` and `N_INIT_REG`	`references/init-reg-cookbook.md`
Advanced macros	`references/advanced-macros.md`
Example legal configurations	`references/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.

Script	Purpose	Arguments
`scripts/generate_def.py`	Generate `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.py`	Validate 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.py`	Compare two def files semantically, ignoring whitespace/comment-only changes	`<a.svh> <b.svh>`, optional `--json` or `--text`
`scripts/build_corpus_metadata.py`	Maintenance helper to rebuild anonymized corpus metadata; do not run during normal user workflows	`<path1> [<path2> ...]`

Bundled Resources

Resource	Use
`references/generate-workflow.md`	Detailed Generate workflow, requirement order, question style, and per-topic prompt guidance
`references/script-usage.md`	Preflight, command forms, and `run_script()` examples for bundled scripts
`references/macro-reference.md`	Wrapper requirement, macro semantics, legal constraints, and RTL citations
`references/validation-rules.md`	Rule catalog for validator findings
`references/archetypes.md`	Illustrative legal configurations; never treat as templates or frequency guidance
`references/init-reg-cookbook.md`	Boot-time APB write sequence patterns and address conventions
`references/top-port-map.md`	Macro-to-`HOLOLINK_top` port effects
`references/advanced-macros.md`	`SYNC_CLK_HIF_APB`, `SYNC_CLK_HIF_PTP`, `PERI_RAM_DEPTH`, and `DISABLE_COE`
`assets/metadata/corpus.json`, `assets/metadata/corpus-stats.json`	Maintenance metadata only; do not cite corpus counts as user guidance
`scripts/generate_def.py`	Generate a def file from a profile
`scripts/validate_def.py`	Validate a def file and emit JSON/text findings
`scripts/compare_defs.py`	Compare 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

ATTRIBUTION.mdAdded by AutoGineer895 B
BENCHMARK.md3.4 KiB
LICENSELicence file added by AutoGineer11.2 KiB
README.md5.0 KiB
SKILL.md11.3 KiB
assets/metadata/corpus-stats.json5.3 KiB
assets/metadata/corpus.json16.9 KiB
evals/evals.json4.4 KiB
references/advanced-macros.md4.7 KiB
references/archetypes.md22.3 KiB
references/generate-workflow.md25.1 KiB
references/init-reg-cookbook.md5.7 KiB
references/macro-reference.md29.8 KiB
references/script-usage.md3.1 KiB
references/top-port-map.md10.2 KiB
references/validation-rules.md14.8 KiB
scripts/build_corpus_metadata.pyScript7.5 KiB
scripts/compare_defs.pyScript6.0 KiB
scripts/generate_def.pyScript8.6 KiB
scripts/lib/__init__.pyScript0 B
scripts/lib/emitter.pyScript25.7 KiB
scripts/lib/parser.pyScript22.3 KiB
scripts/lib/rules.pyScript29.1 KiB
scripts/validate_def.pyScript5.6 KiB
skill-card.md4.5 KiB
skill.oms.sig8.9 KiB

references/validation-rules.md

Validation Rules

Each rule has a stable ID (HD-E… for errors, HD-W… for warnings, HD-I… for info). The same IDs appear in scripts/lib/rules.py and in the JSON output of validate_def.py. Drift between this file and rules.py is a defect.

Rule severity & exit behavior

Severity	Exit code impact	Examples
Error (`HD-E…`)	Non-zero exit (1)	Missing wrapper, byte-alignment violation, derived-equality failure, init_reg cardinality mismatch
Warning (`HD-W…`)	Zero exit (info only)	Non-power-of-2 widths, resource-threshold warnings, documented frequency-band warnings, peripheral-macro footguns
Info (`HD-I…`)	Zero exit (info only)	Don't-care fields present, IP-rev backward-compat targets, archetype-classification notes

The validator ALWAYS reports all rule findings even when the user requests "errors only" — warnings about silent peripheral fallback in particular are too important to suppress.

E001–E099 · File structure (wrapper required)

ID	Severity	Triggers when	Message template
HD-E001	Error	First non-comment, non-blank line is not `\`ifndef HOLOLINK_def`	"File must begin with `\`ifndef HOLOLINK_def` guard. See macro-reference.md § File wrapper requirement."
HD-E002	Error	`\`ifndef HOLOLINK_def`is present but``define HOLOLINK_def` is missing on the following line	"After `\`ifndef HOLOLINK_def`, the next directive must be` `define HOLOLINK_def`."
HD-E003	Error	`package HOLOLINK_pkg;` declaration is missing	"Missing `package HOLOLINK_pkg;` declaration. The file must be wrapped in this package."
HD-E004	Error	`endpackage` is missing or does not name `HOLOLINK_pkg`	"Missing or malformed `endpackage: HOLOLINK_pkg`. Close the package before the final `\`endif`."
HD-E005	Error	Closing `\`endif` is missing	"Missing closing `\`endif`for the``ifndef HOLOLINK_def` guard."

E101–E199 · Per-macro range / format

Clocks

ID	Severity	Triggers when	Message template
HD-E101	Error	`HIF_CLK_FREQ` ≤ 0 or non-numeric	"HIF_CLK_FREQ must be a positive integer (Hz)."
HD-E102	Error	`APB_CLK_FREQ` ≤ 0 or non-numeric	"APB_CLK_FREQ must be a positive integer (Hz)."
HD-E103	Error	`PTP_CLK_FREQ` ≤ 0 or non-numeric	"PTP_CLK_FREQ must be a positive integer (Hz)."

Board identity

ID	Severity	Triggers when	Message template
HD-E104	Error	`UUID` is undefined	"UUID is required. Define a 128-bit hex literal — never derive at runtime."
HD-E105	Error	`UUID` literal width != 128	"UUID must be exactly 128 bits (e.g. `128'h…`). Got <width>-bit literal."
HD-E106	Error	`UUID` literal is malformed (parse failure)	"UUID literal is malformed; expected `128'h<32 hex chars, optionally` _`-separated>`."

Enumeration

ID	Severity	Triggers when	Message template
HD-E107	Error	`ENUM_EEPROM` defined and `EEPROM_REG_ADDR_BITS` ∉ {8, 16}	"EEPROM_REG_ADDR_BITS must be 8 or 16 when ENUM_EEPROM is defined."

Sensor datapath

ID	Severity	Triggers when	Message template
HD-E108	Error	`DATAPATH_WIDTH` ≤ 0	"DATAPATH_WIDTH must be a positive integer."
HD-E109	Error	`DATAPATH_WIDTH` not divisible by 8	"DATAPATH_WIDTH must be byte-aligned (divisible by 8). Got <value>."
HD-E110	Error	`DATAUSER_WIDTH` ∉ {1, 2}	"DATAUSER_WIDTH must be 1 or 2 (per HSB documentation)."
HD-E111	Error	`HOSTUSER_WIDTH` != 1	"HOSTUSER_WIDTH is fixed at 1 in the current IP."

Host

ID	Severity	Triggers when	Message template
HD-E112	Error	`HOST_WIDTH` ≤ 0	"HOST_WIDTH must be a positive integer."
HD-E113	Error	`HOST_WIDTH` not divisible by 8	"HOST_WIDTH must be byte-aligned (divisible by 8). Got <value>."
HD-E114	Error	`HOST_IF_INST` ∉ {1..32}	"HOST_IF_INST must be in the range 1..32. Got <value>."
HD-E115	Error	`HOST_MTU` ≤ 0	"HOST_MTU must be a positive integer (bytes)."

Sensor RX / TX gating

ID	Severity	Triggers when	Message template
HD-E116	Error	`SENSOR_RX_IF_INST` defined but ∉ {1..32}	"SENSOR_RX_IF_INST must be in the range 1..32 when defined. Got <value>. (Leave it undefined to disable RX.)"
HD-E117	Error	`SENSOR_TX_IF_INST` defined but ∉ {1..32}	"SENSOR_TX_IF_INST must be in the range 1..32 when defined. Got <value>."

Peripherals

ID	Severity	Triggers when	Message template
HD-E118	Error	`SPI_INST` defined but ∉ {1..8}	"SPI_INST must be in the range 1..8 when defined. Got <value>."
HD-E119	Error	`I2C_INST` defined but ∉ {1..8}	"I2C_INST must be in the range 1..8 when defined. Got <value>."
HD-E120	Error	`UART_INST` defined but != 1	"UART_INST must be 1 when defined (only one UART instance is currently supported)."
HD-E121	Error	`GPIO_INST` ∉ {1..255}	"GPIO_INST must be in the range 1..255. Got <value>."
HD-E122	Error	`REG_INST` ∉ {1..8}	"REG_INST must be in the range 1..8. Got <value>."

Per-port arrays

ID	Severity	Triggers when	Message template
HD-E123	Error	`SIF_RX_WIDTH[i]` ≤ 0 or not byte-aligned	"SIF_RX_WIDTH[<i>] must be a positive byte-aligned integer. Got <value>."
HD-E124	Error	`SIF_TX_WIDTH[i]` ≤ 0 or not byte-aligned	"SIF_TX_WIDTH[<i>] must be a positive byte-aligned integer. Got <value>."
HD-E125	Error	`SIF_TX_BUF_SIZE[i]` ≤ 0	"SIF_TX_BUF_SIZE[<i>] must be a positive integer FIFO depth in SIF_TX_WIDTH elements."
HD-E126	Error	`SIF_RX_PACKETIZER_EN[i]` ∉ {0, 1}	"SIF_RX_PACKETIZER_EN[<i>] must be 0 or 1."
HD-E127	Error	`GPIO_RESET_VALUE` width != `GPIO_INST`	"GPIO_RESET_VALUE must be sized exactly [GPIO_INST-1:0]. Declared width <wD>, expected <wE>."

E201–E299 · Cross-macro / derived equalities

ID	Severity	Triggers when	Message template
HD-E201	Error	`DATAKEEP_WIDTH` != `DATAPATH_WIDTH/8`	"DATAKEEP_WIDTH must equal DATAPATH_WIDTH/8. Got DATAKEEP_WIDTH=<a>, DATAPATH_WIDTH=<b>, expected <b/8>."
HD-E202	Error	`HOSTKEEP_WIDTH` != `HOST_WIDTH/8`	"HOSTKEEP_WIDTH must equal HOST_WIDTH/8. Got HOSTKEEP_WIDTH=<a>, HOST_WIDTH=<b>, expected <b/8>."
HD-E203	Error	Any `SIF_RX_WIDTH[i]` > `DATAPATH_WIDTH`	"SIF_RX_WIDTH[<i>] = <v> exceeds DATAPATH_WIDTH = <D>. Per-port widths must be ≤ the system-wide datapath."
HD-E204	Error	Any `SIF_TX_WIDTH[i]` > `DATAPATH_WIDTH`	"SIF_TX_WIDTH[<i>] = <v> exceeds DATAPATH_WIDTH = <D>."

E301–E399 · Conditional dependencies / array length

ID	Severity	Triggers when	Message template
HD-E301	Error	`SIF_RX_WIDTH[]` length != `SENSOR_RX_IF_INST`	"SIF_RX_WIDTH array length (<L>) must equal SENSOR_RX_IF_INST (<N>)."
HD-E302	Error	`SIF_RX_PACKETIZER_EN[]` length != `SENSOR_RX_IF_INST`	"SIF_RX_PACKETIZER_EN array length (<L>) must equal SENSOR_RX_IF_INST (<N>)."
HD-E303	Error	`SIF_RX_VP_COUNT[]` length != `SENSOR_RX_IF_INST` (and any packetizer is enabled)	"SIF_RX_VP_COUNT array length (<L>) must equal SENSOR_RX_IF_INST (<N>) when any SIF_RX_PACKETIZER_EN element is 1."
HD-E304	Error	`SIF_RX_SORT_RESOLUTION[]` length mismatch (and any packetizer enabled)	"SIF_RX_SORT_RESOLUTION array length (<L>) must equal SENSOR_RX_IF_INST (<N>)."
HD-E305	Error	`SIF_RX_VP_SIZE[]` length mismatch (and any packetizer enabled)	"SIF_RX_VP_SIZE array length (<L>) must equal SENSOR_RX_IF_INST (<N>)."
HD-E306	Error	`SIF_RX_NUM_CYCLES[]` length mismatch (and any packetizer enabled)	"SIF_RX_NUM_CYCLES array length (<L>) must equal SENSOR_RX_IF_INST (<N>)."
HD-E307	Error	`SIF_TX_WIDTH[]` length != `SENSOR_TX_IF_INST`	"SIF_TX_WIDTH array length (<L>) must equal SENSOR_TX_IF_INST (<N>)."
HD-E308	Error	`SIF_TX_BUF_SIZE[]` length != `SENSOR_TX_IF_INST`	"SIF_TX_BUF_SIZE array length (<L>) must equal SENSOR_TX_IF_INST (<N>)."
HD-E309	Error	`GPIO_INST` defined but `GPIO_RESET_VALUE` missing	"GPIO_RESET_VALUE must be declared whenever GPIO_INST is defined."

E401–E499 · `init_reg` cardinality

ID	Severity	Triggers when	Message template
HD-E401	Error	`N_INIT_REG` != literal length of `init_reg[]` array	"N_INIT_REG (<N>) must equal the literal length of the init_reg[] array (<L>)."
HD-E402	Error	Any `init_reg[k]` entry has width != 64 bits	"init_reg[<k>] entry must be exactly 64 bits — `{32'h<addr>, 32'h<data>}`."
HD-E403	Error	`init_reg` array present but `N_INIT_REG` undefined	"init_reg[] is declared but N_INIT_REG is undefined. Define N_INIT_REG to match the array length."
HD-E404	Error	`N_INIT_REG` is defined and > 0 but `init_reg[]` is missing	"N_INIT_REG is defined but init_reg[] is missing. Declare init_reg[] with exactly N_INIT_REG entries."
HD-E405	Error	`N_INIT_REG` is defined as `0`	"N_INIT_REG = 0 is invalid: the IP's `\`ifdef N_INIT_REG`gate evaluates true and instantiates`sys_init`with a zero-element array, which fails elaboration. To skip the system-init sequence, leave`N_INIT_REG`undefined entirely (remove the``define) — the IP then omits `sys_init` cleanly."

W001–W099 · FPGA-resource warnings

ID	Severity	Triggers when	Message template
HD-W001	Warning	`DATAPATH_WIDTH` > 1024	"DATAPATH_WIDTH = <v> is wider than the resource-warning threshold (1024). Confirm the target has sufficient logic and routing resources for the wider datapath."
HD-W002	Warning	`HOST_WIDTH` > 1024	"HOST_WIDTH = <v> is wider than the resource-warning threshold (1024). Confirm the target has sufficient logic and routing resources."
HD-W003	Warning	Any `SIF_RX_WIDTH[i]` > 1024	"SIF_RX_WIDTH[<i>] = <v> is wider than the resource-warning threshold (1024). Confirm logic and routing capacity."
HD-W004	Warning	Any `SIF_TX_WIDTH[i]` > 1024	"SIF_TX_WIDTH[<i>] = <v> is wider than the resource-warning threshold (1024). Confirm logic and routing capacity."
HD-W005	Warning	Any `SIF_TX_BUF_SIZE[i]` > 8192	"SIF_TX_BUF_SIZE[<i>] = <v> exceeds the resource-warning threshold (8192 TX-width elements). Confirm the target has sufficient embedded RAM resources for the deeper FIFO."

W101–W199 · Style (power-of-2 convention)

ID	Severity	Triggers when	Message template
HD-W101	Warning	`DATAPATH_WIDTH` is byte-aligned but not a power of 2	"DATAPATH_WIDTH = <v> is byte-aligned but not a power of 2. AXI conventions favor powers of 2; some downstream IP may not handle non-power-of-2 widths cleanly."
HD-W102	Warning	`HOST_WIDTH` is byte-aligned but not a power of 2	"HOST_WIDTH = <v> is byte-aligned but not a power of 2 (AXI bus convention favors powers of 2)."
HD-W103	Warning	Any `SIF_RX_WIDTH[i]` byte-aligned but not power of 2	"SIF_RX_WIDTH[<i>] = <v> is not a power of 2 (AXI bus convention)."
HD-W104	Warning	Any `SIF_TX_WIDTH[i]` byte-aligned but not power of 2	"SIF_TX_WIDTH[<i>] = <v> is not a power of 2."
HD-W105	Warning	Any `SIF_TX_BUF_SIZE[i]` not a power of 2	"SIF_TX_BUF_SIZE[<i>] = <v> is not a power of 2. Power-of-2 FIFO depths are easier for downstream memory implementations."

W201–W299 · Frequency-band warnings

ID	Severity	Triggers when	Message template
HD-W207	Warning	`PTP_CLK_FREQ` outside the 95–105 MHz band	"PTP_CLK_FREQ = <v> Hz is outside the HSB-documented range of 95–105 MHz. PTP timing accuracy may be degraded."

W301–W399 · Footguns

ID	Severity	Triggers when	Message template
HD-W301	Warning	Any `SIF_RX_*[]` array is declared but `SENSOR_RX_IF_INST` is undefined	"SIF_RX_<name>[] array is declared but SENSOR_RX_IF_INST is undefined. The RTL silently falls back to a 1-bit dummy interface — there is no compile error. Did you mean to define SENSOR_RX_IF_INST?"
HD-W302	Warning	Any `SIF_TX_*[]` array is declared but `SENSOR_TX_IF_INST` is undefined	"SIF_TX_<name>[] array is declared but SENSOR_TX_IF_INST is undefined. RTL falls back silently — define SENSOR_TX_IF_INST or remove the array."
HD-W303	Warning	`EEPROM_REG_ADDR_BITS` is defined but `ENUM_EEPROM` is not	"EEPROM_REG_ADDR_BITS is defined but ENUM_EEPROM is undefined — the macro is dead. Either define ENUM_EEPROM or remove EEPROM_REG_ADDR_BITS."
HD-W304	Warning	A `\`define BUILD_REV …` directive appears	"BUILD_REV is a Verilog parameter on HOLOLINK_top, not a `\`define`macro. The``define`here will be ignored. Pass BUILD_REV via parameter override at module instantiation:`HOLOLINK_top #(.BUILD_REV(48'h…)) u_…`."
HD-W305	Warning	`SENSOR_RX_IF_INST` defined and at least one packetizer enabled but `SIF_RX_VP_COUNT[]` (or peers) is missing	"SIF_RX_<name>[] is required when any SIF_RX_PACKETIZER_EN element is 1. Provide the array (use `'{default:<value>}` for uniform configurations)."
HD-W306	Warning	`GPIO_RESET_VALUE` is declared with a literal width that does not match `GPIO_INST` exactly (but happens to fit)	"GPIO_RESET_VALUE is declared as <wD> bits but GPIO_INST = <wE>. The mismatch is silently sign-extended or truncated by Verilog elaboration; declare it explicitly as [GPIO_INST-1:0] for clarity."

I001–I099 · Informational

ID	Severity	Triggers when	Message template
HD-I001	Info	An element of any `SIF_RX_VP_*[]`/`SORT_RESOLUTION[]`/`VP_SIZE[]`/`NUM_CYCLES[]` is provided where the corresponding `SIF_RX_PACKETIZER_EN[i] = 0`	"SIF_RX_<name>[<i>] is a don't-care because SIF_RX_PACKETIZER_EN[<i>] = 0; the value is ignored by the IP."
HD-I003	Info	Configuration does not match any of the 6 archetypes	"Configuration does not cleanly match any archetype in archetypes.md. The validator confirms it is structurally valid; archetype-specific guidance is not available."
HD-I004	Info	Configuration matches archetype `<name>`	"Configuration matches the `<name>` archetype. See `archetypes.md` for guidance on common adjustments."

Validator output contract

The validator emits a JSON object of the form:

{
  "errors":   [{"rule": "HD-E…", "line": <int|null>, "macro": "<NAME|null>", "msg": "<rendered message>"}],
  "warnings": [{"rule": "HD-W…", "line": <int|null>, "macro": "<NAME|null>", "msg": "<rendered message>"}],
  "info":     [{"rule": "HD-I…", "line": <int|null>, "macro": "<NAME|null>", "msg": "<rendered message>"}],
  "inferred_archetype": "<name|null>",
  "ip_version_target": "16'h2604"
}

The validator's output must never name out-of-scope macros in any msg field. Out-of-scope macros pass silently with no annotation. This is a hard ship-blocker — see PLAN.md Phase 7.

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

2026-11-08

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