⚡

HSBIP定义技能Skill hsb-ip-def

该技能用于生成、验证、比较和解释 Holoscan Sensor Bridge（HSB）IP 的 HOLOLINK_def.svh 配置文件，管理 SystemVerilog 宏定义、localparam、HOLOLINK_pkg 封装及 init_reg 启动序列。它通过捆绑 Python 脚本在本地生成经过验证的 .svh 文件，并可与 hsb-ip-create-top、hsb-ip-packetizer 协同完成 FPGA 集成。关键词：HSB IP、HOLOLINK_def.svh、SystemVerilog、FPGA、宏定义、配置生成、验证、比较、解释。

传感器桥接(HSB) 0 次安装 0 次浏览 更新于 9/7/2026
名称 hsb-ip-def
作者 Holoscan Team holoscan-team@nvidia.com
描述 生成、验证、比较或解释 HSB HOLOLINK_def.svh 宏。不要用于 FPGA_top.sv 封装或仅数据包化器派生。生成操作会在本地通过 shell 命令运行捆绑的 Python 脚本，并在用户确认路径后写入经过验证的 .svh 输出文件。
版本 0.1.0 tags: - holoscan - hsb - fpga - systemverilog - configuration permissions: [file_read, file_write, shell]
开源协议 Apache-2.0 compatibility: 目标 HSB IP 版本 16’h2604；向后兼容 16’h2603（公开发布版本）。优先使用实时 HSB IP 源代码（若可用）；对未知修订版本发出警告。生成器需要 Python 3.9+ 和 PyYAML。 metadata:
作者 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 技能（HSB IP Def Skill）

目的（Purpose）

通过四种工作流使用此技能：

  • 生成（Generate）：根据已确认的板级需求生成 HOLOLINK_def.svh。
  • 验证（Validate）：使用捆绑的验证器验证现有的 def 文件。
  • 解释/推理（Explain / Reason）：解释 HSB IP 宏、合法性及宏驱动的端口。
  • 比较（Compare）：语义上比较两个 def 文件。

范围（Scope）

此技能负责 HOLOLINK_def.svh 的内容：\define 指令、localparam 数组、HOLOLINK_pkg封装以及启动时的init_reg[]序列。外围的顶层封装由hsb-ip-create-top技能负责；仅数据包化器的剖面派生可委托给hsb-ip-packetizer`。

该文件必须使用标准保护宏和 package HOLOLINK_pkg 封装。关于完整的封装要求和每个宏的语义，请查阅 references/macro-reference.md。

先决条件（Prerequisites）

  • 捆绑脚本需要 Python 3.9+；读取 YAML 剖面时需要 PyYAML。
  • 用户必须确认文件写入和 shell 命令，除非他们已经明确要求该确切操作。
  • 在脚本支持的验证或生成之前，需要提供具体的 def 文件路径、粘贴的内容或已确认的生成剖面。
  • 实时 HSB IP 源代码是可选的，但在针对特定检出 IP 修订版本进行验证时更为推荐。

说明（Instructions）

  • 在生成、验证、比较或脚本支持的合法性检查之前，先从 references/script-usage.md 运行捆绑脚本预检。
  • 绝不在生成期间静默默认宏。展示建议值或推断的需求，并获得用户确认。
  • 在聊天驱动的生成过程中，每轮只提出一个需求问题。
  • 使用与传感器无关的语言，除非用户说明设计是特定于摄像头的。
  • 避免支持不足的“典型”、“常见”、“大多数设计”或语料库频率的说法。将选择锚定到 IP 行为、文档化约束或用户需求。
  • 始终警告 HD-W3xx 陷阱，即使用户只询问错误。
  • 不要生成 FPGA_top.sv；在生成的 def 文件通过验证后，提供移交给 hsb-ip-create-top 的技能。
  • 将不熟悉的宏视为项目特定宏，除非它们在此技能参考或实时 HSB IP 源代码中有文档记录。

安全注意事项（Security Considerations）

此技能可以通过其捆绑脚本读写本地文件并运行 shell 命令。在运行命令或写入文件之前，请说明命令或路径并获得用户确认，除非用户已明确要求该确切操作。对于粘贴的 HOLOLINK_def.svh 内容，仅写入隔离临时目录中安全生成的文件，并在验证后移除，除非用户要求保留。

版本、兼容性与实时源代码（Version, Compatibility, And Live Source）

此技能目标 HSB IP 修订版本 16'h2604，并向后兼容 16'h2603。实时 HSB IP 源代码优先于捆绑参考。

当涉及源代码敏感行为时：

  1. 找到 <hsb-ip-root>/top/HOLOLINK_top.sv。已知根目录包括 hw/nvcpu_dgx_fpga/vrtl/hololink/ 和公开版本 fpga/nv_hsb_ip/。
  2. 读取 HOLOLINK_REV 和 HOLOLINK_BACKWARD_COMPAT_REV。
  3. 当实时源代码与捆绑参考不同时，以实时源代码消耗的宏、端口门和 RTL 行为为准。
  4. 在针对已知源代码根目录验证时，向 scripts/validate_def.py 传递 --ip-source <root>。

公开文档基线：

  • 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）：当用户要求创建、搭建、起草、设计或制作 HOLOLINK_def.svh 时。
  2. 验证（Validate）：当用户要求 lint、检查、验证或审查 HOLOLINK_def.svh 时。
  3. 解释/推理（Explain / Reason）：当用户询问某个宏的作用、某个组合是否合法、验证为什么失败，或某个宏如何影响 HOLOLINK_top 时。
  4. 比较（Compare）：当用户要求比较两个 def 文件或了解配置之间的变化时。

生成（Generate）

加载 references/generate-workflow.md 和 references/script-usage.md。

按照参考文件中的详细生成工作流执行：运行预检、分类提供的需求、每轮询问一个需求问题、构建扁平的 YAML 剖面、运行 scripts/generate_def.py、展示生成字段的来源，并提供移交给 hsb-ip-create-top 技能的选项。

当需要数据包化器字段时，使用已知的 RX 数量、RX 宽度和用户的数据处理描述调用 hsb-ip-packetizer。仅使用该技能的 packetizer_profile_overlay YAML 键，将它们合并到进行中的剖面中，然后在此继续完整的文件生成和验证。

验证（Validate）

加载 references/script-usage.md。仅当解释特定规则 ID 或验证行为时，才加载 references/validation-rules.md。

步骤：

  1. 每个会话运行一次捆绑脚本预检。
  2. 定位文件。如果用户粘贴内容，在写入前告知生成的临时路径，请求确认，使用隔离的安全临时路径，并在验证后清理，除非用户要求保留。否则使用提供的路径。
  3. 运行 <PY> scripts/validate_def.py <path> --json，不要在上下文中重新实现验证。
  4. 按严重性对发现进行分组：错误、警告，然后是信息。对于每个错误，如果可用，请引用规则 ID、行号和宏。
  5. 始终警告陷阱，尤其是 HD-W3xx 静默回退警告。
  6. 如果无问题，确认推断的原型和 IP 版本，然后建议下一步可能的检查或移交。

解释 / 推理（Explain / Reason）

仅加载回答问题所需的参考资料：

问题类型 参考
宏语义或合法值 references/macro-reference.md
验证规则行为 references/validation-rules.md
宏驱动的端口影响 references/top-port-map.md
init_reg[] 和 N_INIT_REG references/init-reg-cookbook.md
高级宏 references/advanced-macros.md
示例合法配置 references/archetypes.md

对于基于事实的合法性问题，运行预检，并优先使用 scripts/validate_def.py 验证具体文件或最小合成文件，而不是手推推理。在解释规则为何存在时，引用参考中的 RTL 行号范围。

比较（Compare）

加载 references/script-usage.md，运行预检，然后使用 <PY> scripts/compare_defs.py <a.svh> <b.svh> [--json|--text]。总结语义差异，而不是空白或仅注释的更改。

限制（Limitations）

  • 不要生成 FPGA_top.sv；在 defs 文件验证后使用 hsb-ip-create-top。
  • 当数据包化器行为定义不充分时，不要在此处派生仅数据包化器的字段集；将该部分委托给 hsb-ip-packetizer。
  • 不要将捆绑的原型或语料库元数据视为规范。它们是示例和维护元数据，不是默认值。
  • 不要将未知宏静默接受为经过验证的 HSB IP 行为，除非实时源代码或参考中有文档说明。

故障排除（Troubleshooting）

  • 脚本预检失败：报告缺少的 Python 或 PyYAML 要求，并在生成或验证之前停止。
  • 验证报错：按严重性分组，引用规则 ID 和行号，并在提供顶层移交之前修复 defs 文件。
  • 验证报告 HD-W3xx 警告：即使没有错误也要提出，因为它们描述了静默 RTL 回退风险。
  • 出现未知宏：将其视为项目特定，除非实时 HSB IP 源代码或捆绑参考中有文档记录。

可用脚本（Available Scripts）

针对每条命令，请使用在预检期间从 references/script-usage.md 选择的 <PY>。

脚本 用途 参数
scripts/generate_def.py 从原型和/或 YAML/JSON 剖面生成 HOLOLINK_def.svh；在写入前验证 --profile <path>, --archetype <slug>, -o <output>, 可选 --allow-random-uuid 兼容性标志
scripts/validate_def.py 验证 HOLOLINK_def.svh 并输出 JSON 或文本结果 <path/to/HOLOLINK_def.svh>, 可选 --json 或 --text, 可选 --ip-source <root>
scripts/compare_defs.py 语义上比较两个 def 文件，忽略空白/仅注释的变化 <a.svh> <b.svh>, 可选 --json 或 --text
scripts/build_corpus_metadata.py 维护辅助程序，用于重建匿名语料库元数据；不要在正常用户工作流期间运行 <path1> [<path2> ...]

捆绑资源（Bundled Resources）

资源 用途
references/generate-workflow.md 详细的生成工作流、需求顺序、问题风格和按主题的提示指南
references/script-usage.md 捆绑脚本的预检、命令形式和 run_script() 示例
references/macro-reference.md 封装要求、宏语义、合法约束和 RTL 引用
references/validation-rules.md 验证器发现的规则目录
references/archetypes.md 说明用合法配置；切勿视为模板或频率指南
references/init-reg-cookbook.md 启动时 APB 写入序列模式和地址约定
references/top-port-map.md 宏到 HOLOLINK_top 的端口影响
references/advanced-macros.md SYNC_CLK_HIF_APB, SYNC_CLK_HIF_PTP, PERI_RAM_DEPTH, 和 DISABLE_COE
assets/metadata/corpus.json, assets/metadata/corpus-stats.json 仅维护元数据；不要将语料库计数作为用户指南引用
scripts/generate_def.py 从剖面生成 def 文件
scripts/validate_def.py 验证 def 文件并输出 JSON/文本结果
scripts/compare_defs.py 语义上比较两个 def 文件

示例（Examples）

  • “使用 hsb-ip-def 为新的 HSB 板生成一个 HOLOLINK_def.svh。” 将其视为生成，运行脚本预检，对提供的需求进行分类，每轮询问一个需求问题，并在剖面确认后才运行 scripts/generate_def.py。
  • “使用 hsb-ip-def 验证我现有的 HOLOLINK_def.svh，并告诉我哪些警告是重要的。” 将其视为验证，要求提供或定位文件，运行 scripts/validate_def.py <path> --json，按错误、警告和信息分组结果，并始终提醒 HD-W3xx 陷阱。
  • “使用 hsb-ip-def 解释 HOST_WIDTH=512 和 PTP_CLK_FREQ=90_000_000 是否合法。” 将其视为解释/推理，优先采用具体的验证器支持检查，而不是手推推理，并且只加载所需的宏或验证参考来解释结果。