/hsb-ip-def

name: hsb-ip-def
author: "Holoscan Team <holoscan-team@nvidia.com>"
description: 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.
version: "0.1.0"
tags:
  - holoscan
  - hsb
  - fpga
  - systemverilog
  - configuration
permissions: [file_read, file_write, shell]
license: Apache-2.0
compatibility: 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.
metadata:
  author: "Holoscan Team <holoscan-team@nvidia.com>"
  team: holoscan
  domain: fpga
  vendor: nvidia
  tags:
    - holoscan
    - hsb
    - fpga
    - systemverilog
    - configuration
  languages:
    - systemverilog
    - python
  artifact: HOLOLINK_def.svh
  hsb_ip_version: "16'h2604"
  min_compat_rev: "16'h2603"

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`: `\`define` directives, `localparam` arrays, the `HOLOLINK_pkg` wrapper, and boot-time `init_reg[]` sequence. The surrounding top-level wrapper is owned by `hsb-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