⚡

HSBIP创建顶层Skill hsb-ip-create-top

本技能用于创建或解释固定格式的HSB FPGA_top.sv顶层包装。它从经过验证的HOLOLINK_def.svh提取信号并实例化HOLOLINK_top，不生成或验证defs，也不涉及项目特定集成。关键词：HSB, FPGA_top.sv, HOLOLINK_def.svh, SystemVerilog, 传感器桥接, 顶层集成。

传感器桥接(HSB) 0 次安装 0 次浏览 更新于 9/7/2026
名称 hsb-ip-create-top
作者 ‘Holoscan Team holoscan-team@nvidia.com’
描述 从经过验证的 HOLOLINK_def.svh 文件创建或解释固定格式的 HSB FPGA_top.sv 包装。不要用于 def 生成或验证。
版本 ‘0.1.0’ tags: - holoscan - hsb - fpga - systemverilog - 顶层
开源协议 Apache-2.0 compatibility: 针对 HSB IP rev 16’h2604; 向后兼容 16’h2603。在可用时优先使用实时 HSB IP 源码；对未知版本发出警告。设计为独立使用或作为 hsb-ip-def 的伴随工具。 metadata:
作者 ‘Holoscan Team holoscan-team@nvidia.com’ team: holoscan domain: fpga vendor: nvidia tags: - holoscan - hsb - fpga - 顶层 - systemverilog languages: - systemverilog artifact: FPGA_top.sv source_artifact: HOLOLINK_def.svh hsb_ip_version: ‘16’h2604’

HSB IP 创建顶层技能

目的

创建固定格式的 SystemVerilog 顶层脚手架，实例化 HOLOLINK_top，并声明经过验证的 HOLOLINK_def.svh 所需的 HSB 面向信号。

本技能只负责 HSB IP 周围的顶层脚手架：

  • SPDX/Apache 许可证头
  • HOLOLINK_def.svh include
  • FPGA_top 模块壳
  • HSB 面向信号声明
  • HOLOLINK_top 实例化
  • 用于顶层集成的注释/TODO

使用 hsb-ip-def 进行 HOLOLINK_def.svh 的生成和验证。不要在这里创建或验证 defs 文件。

先决条件

  • 在生成 FPGA_top.sv 之前，需要经过验证的 HOLOLINK_def.svh 路径或粘贴的文件内容。
  • 当需要路径敏感的端口提取时，优先使用实时的 HOLOLINK_top.sv 源码；捆绑的引用涵盖已知 rev 16'h2604 和兼容 rev 16'h2603。
  • 写入脚手架文件时，用户必须提供或接受输出路径。

指令

  • 在创建 FPGA_top.sv 之前，需要经过验证的 HOLOLINK_def.svh。如果用户没有，请首先调用或引导他们使用 hsb-ip-def。
  • 当可用时，将实时的 HOLOLINK_top.sv 视为端口、方向、宏门和 IP 版本的真相来源。
  • 首先将请求分类为独立创建顶层、Def-技能交接或解释。仅加载该工作流所需的引用，不要仅仅为了确认格式而重新读取同一引用。
  • 使用 references/fixed-format.md 作为固定的格式和命名样式。在正常生成期间，不要仅仅为了确认格式而检查示例顶层文件。
  • 生成固定格式的脚手架，而不是完整的项目顶层。因为周围设计未知，生成的 FPGA_top 模块通常没有顶层端口。
  • 从经过验证的 defs 文件派生活跃信号组。不要连接在活跃宏集下 HOLOLINK_top 中不存在的端口。
  • 精确保留 HOLOLINK_top 端口形状：保持打包向量宽度在信号名称之前，非打包接口数组维度在信号名称之后。
  • 使用捆绑的已知版本引用时，仍保留 references/fixed-format.md 中的信号形状，包括多接口 *_tdata、*_tkeep 和 *_tuser 总线的非打包数组以及文档中的 APB 形状。
  • 使用与传感器无关的语言。说“传感器数据”、“传感器接口”和“流”；仅在用户说明设计是相机特定后才使用相机特定语言。
  • 每回合在信息缺失时提出一个清晰的问题。将源选择问题保留为清晰的语言提示，而不是单选按钮、结构化选择或多问题提示。
  • 不要虚构项目特定的集成细节。在周围设计必须连接到 HSB 的地方留下简洁的 TODO 注释。
  • 对于 FPGA_top.sv 中的打包器注释，使用通用措辞，如“数据处理行为”。
  • 在最终总结中，包括 defs 验证/源状态、所使用的端口映射源以及所发射的 HSB 信号组。不要列举脚手架范围之外的内容。仅使用这个通用注释：“此文件是用于将顶层信号和配套 IP 连接到 HSB IP 的参考/模板。”

实时 HSB IP 源码策略

只要用户的工作区提供实时 HSB IP 源码，则优先于捆绑的引用。捆绑的引用描述已知 rev 16'h2604 和向后兼容 rev 16'h2603；实时源码是已检出 IP 的权威。

当源码可用时：

  1. 定位 <hsb-ip-root>/top/HOLOLINK_top.sv。已知根包括 hw/nvcpu_dgx_fpga/vrtl/hololink/ 和公共发行版 fpga/nv_hsb_ip/。
  2. 从 HOLOLINK_top.sv 中读取 HOLOLINK_REV 和 HOLOLINK_BACKWARD_COMPAT_REV。
  3. 读取 HOLOLINK_top 模块声明，确认端口名称、方向、宽度、顺序以及 ifdef/ifndef 门。
  4. 如果版本较新、未知或实时源码与本技能的引用不一致，则说明不一致。信任实时源码进行 IO 提取，并警告捆绑的引用可能需要更新。

当没有源码时，使用捆绑的引用作为已知版本指南，并说明脚手架基于本技能支持的 HSB IP 版本。如果当没有明显的检出时，用户已授权使用捆绑的已知版本端口引用，则简要搜索明显的根，然后继续使用捆绑的引用，而不是询问实时源码问题。

如果源码根不明显，则在一个回合内对话式地询问：

您是否有当前的 HSB IP `HOLOLINK_top.sv` 源码检出想要用于端口提取，还是应该使用本技能捆绑的已知版本端口引用？

接受路径或“使用捆绑引用”答案。

引用加载

仅加载用户任务所需的引用：

文件 何时加载
references/source-policy.md 查找实时 HSB IP 源码、处理未知版本或决定源码/引用优先级时
references/fixed-format.md 生成或解释固定 FPGA_top.sv 脚手架格式时
references/handoff-contract.md 独立前提处理或 def-技能交接行为时

工作流决策

  1. 如果由 hsb-ip-def 在成功的 defs 生成/验证后调用，使用 Def-技能交接。
  2. 如果用户直接要求创建 FPGA_top.sv、实例化 HOLOLINK_top 或制作顶层包装，使用 独立创建顶层。
  3. 如果用户询问版本处理、端口组或为什么信号出现，使用 解释。

独立创建顶层

当用户直接调用本技能时使用。

步骤：

  1. 询问经过验证的 HOLOLINK_def.svh 的路径，或接受粘贴的内容。如果用户没有 defs 文件，停止并指导他们先使用 hsb-ip-def 创建并验证。
  2. 如果验证状态未知，则调用或引导用户进行 hsb-ip-def 验证。不要从未经验证的 defs 文件继续。
  3. 如果 HSB IP 源码根不明显且需要源码敏感的输出来，询问“实时 HSB IP 源码策略”中的实时源码问题，除非用户已授权捆绑的已知版本回退。不要将路径选项显示为单选按钮。已知根是供代理搜索的提示，不是强制用户的选择。
  4. 加载 references/source-policy.md 和 references/fixed-format.md。
  5. 从经过验证的 defs 文件派生活跃宏集。
  6. 当可用时，从实时源码派生或验证 HOLOLINK_top 端口组。
  7. 以固定格式生成 FPGA_top.sv。如果写入文件，默认文件名为 FPGA_top.sv，除非用户提供路径。
  8. 解释结果是 HSB 集成脚手架。使用 ## 指令 中的通用参考/模板注释；不要列举脚手架范围之外的内容。

Def-技能交接

当 hsb-ip-def 刚刚完成经过验证的 HOLOLINK_def.svh，并且用户选择创建匹配的顶层脚手架时使用。

步骤：

  1. 接受来自 hsb-ip-def 的经过验证的 defs 文件路径/内容以及任何已知的配置文件/源码根上下文。
  2. 不要重新询问已由 def 技能完成的 defs 文件决策。
  3. 仅询问缺失的顶层生成事实，如输出路径或需要时的 HSB IP 源码根。如果缺少源码根，询问“实时 HSB IP 源码策略”中的实时源码问题，除非用户已授权捆绑的已知版本回退；不要使用单选按钮或结构化选择。
  4. 加载 references/handoff-contract.md 和 references/fixed-format.md。
  5. 从活跃的 defs 宏和可用的实时 HOLOLINK_top.sv 生成固定格式的 FPGA_top.sv 脚手架。
  6. 返回一个简洁的摘要，说明发射了哪些 HSB 信号组，然后使用 ## 指令 中的通用参考/模板注释。不要列举脚手架范围之外的内容。

解释

当用户询问为什么端口或信号组出现、宏设置如何影响顶层脚手架或本技能如何处理 IP 版本时使用。

步骤：

  1. 对于端口问题，当可用时优先使用实时 HOLOLINK_top.sv。否则加载 references/fixed-format.md。
  2. 对于版本/源码问题，加载 references/source-policy.md。
  3. 对于 defs 文件宏含义，交由 hsb-ip-def 处理。

故障排除

  • 缺少或未经验证的 defs 文件：在生成之前停止，并将用户发送到 hsb-ip-def 验证。
  • 未知或较新的 HSB IP 版本：如果可用则优先实时源码，说明不一致，并警告捆绑的引用可能需要更新。
  • 活跃宏集下缺少端口：省略该连接，并解释哪个经过验证的 def 宏禁用了信号组。

示例

  • 使用 hsb-ip-create-top 从我的经过验证的 HOLOLINK_def.svh 创建 FPGA_top.sv 脚手架。如果无明显 HSB IP 源码检出，则使用捆绑的已知版本端口引用。 视为独立创建顶层，需要经过验证的 defs 文件，加载 references/source-policy.md 和 references/fixed-format.md，在简要搜索源码后使用捆绑的已知版本端口，并报告 defs 状态、端口映射源和发射的信号组。
  • 为 HSB 创建顶层 FPGA_top.sv 包装，但我还没有 HOLOLINK_def.svh。 在生成前停止，指导用户转到 hsb-ip-def，并在继续之前要求提供经过验证的 defs 文件路径或内容。
  • 为什么生成的 FPGA_top.sv 根据我的 HOLOLINK_def.svh 宏包含不同的 HSB 信号组？ 视为解释，说明经过验证的 defs 宏门控 HSB 面向信号组，并且当可用时实时的 HOLOLINK_top.sv 端口映射获胜；将详细的宏语义交由 hsb-ip-def。

限制

  • 不要生成 HOLOLINK_def.svh。
  • 不要验证完整的 HOLOLINK_def.svh 文件。
  • 不要生成 HSB 面向脚手架之外的项目特定集成。
  • 不要推断 HSB 端口映射之外的信号含义、极性、来源或行为。
  • 不要将示例项目逻辑复制到脚手架中，除非用户明确请求项目特定的适配。