doca-firefly

DOCA Firefly 服务

示例

• “容器状态为绿色，但 PTP 始终停留在 LISTENING。” — 这属于支持范围。修改主机上的 chrony 之前，先检查角色 / 配置文件 / 域 / 接口。
• “Firefly 显示已同步，但主机时钟仍在漂移。” — 连接 BlueField PHC 跟随器；Firefly 不会取代主机端的 chrony / ptp4l 主体。

说明

遵循下方的加载顺序。打开任务配套文档以进行配置 / 同步 / 调试。打开能力配套文档了解 PTP 轴。 不要打开所有配套文件。

子系统清单（Run-12 修正，已在 Run-13 验证）。 DOCA Firefly 不只是“一个 PTP 守护进程”。随附的 doca_firefly.yaml 通过环境变量公开了 六个 PTP 堆栈子系统，每个子系统都有自己的 *_STATE、 *_CONFIG_FILE，以及（在相关情况下）*_INTERFACE / *_DEVICE 参数（之所以计为六个，是因为 PTP Monitor 子系统附带一个内部 phc2sys 监控客户端，它不同于独立的 PHC2SYS 子系统——两者都包含在同一个容器映像中）：

1. PTP（PTP_STATE、PTP_INTERFACE、PTP_CONFIG_FILE）— ptp4l 守护进程（或主时钟，取决于配置文件），用于驱动 BlueField PHC。
2. PTP Monitor（MONITOR_STATE、MONITOR_CONFIG_FILE、 MONITOR_CLIENT_TYPE、MONITOR_CLIENT_PHC2SYS_INTERFACE、 MONITOR_CLIENT_CONNECTION_TIMEOUT）— 监控服务端与客户端接口；内部 phc2sys 监控客户端 （MONITOR_CLIENT_TYPE=phc2sys）是 Firefly 内部的真实子系统， 而不只是主机端需要考虑的内容。
3. PHC2SYS（PHC2SYS_STATE、PHC2SYS_ARGS、 PHC2SYS_CONFIG_FILE）— 容器内部的 phc2sys 实例；该套件之前将 phc2sys 说成仅在主机端运行，这是错误的。
4. PPS（PPS_STATE、PPS_DEVICE）— 每秒脉冲输出（除普通的启用 / 禁用外，还支持 enable_while_running 和 do_nothing 状态）。
5. SyncE（SYNCE_STATE、SYNCE_INTERFACE、 SYNCE_CONFIG_FILE）— 同步以太网频率分发，与 PTP 正交。
6. Firefly Servo（SERVO_STATE、SERVO_CONFIG_FILE）— 专有的 Firefly 伺服控制环（可替代上游 linuxptp 伺服控制器）。

有效的 PROFILE 值严格限定为 default / media / telco-l2 / custom（依据 doca_firefly.yaml 注释）— Agent 不得自行编造其他值。配置为 defined_by_profile 的子系统由当前激活的 PROFILE 控制。

配置覆盖环境变量遵循 CONF_<SUBSYSTEM>_<section>_<key> 模式（例如 CONF_PTP_global_priority1、CONF_SYNCE_global_backend、 CONF_MONITOR_global_telemetry_export）；这些是官方文档说明的配置入口，可用于覆盖单个配置项，而无需提供完整的自定义配置文件。

**配置层级：**挂载的 Firefly 配置文件是必需的，并负责主要 PTP 轴（角色、配置文件、域、接口和传输方式）。CONF_<SUBSYSTEM>_<section>_<key> 变量是该文件中可选的、按配置项说明的覆盖项； 它们不是第二套独立的配置模型。

从这里开始：此技能用于运行 DOCA Firefly Service 容器，而非链接到某个库。Firefly 是驱动并监控 BlueField PTP Hardware Clock（PHC）的 PTP / PHC2SYS / PPS / SyncE / Servo / Monitor 堆栈；它不是主机端的时间跟随器，不是使用者工作负载，也不是编程接口。如果用户想要部署该容器，请打开任务配套文档，并从 ## configure 开始。如果问题是Firefly 属于什么类型的服务，以及它支持哪些 PTP 角色 / 配置文件， 请从能力配套文档开始。如果 BlueField 上尚未安装 DOCA，请先转到 doca-setup/SKILL.md。如果用户真正想问的是“我有一个 Rivermax SMPTE 工作负载，文档说我需要 PTP”，正确的组合是本技能加上** doca-rmax/SKILL.md——Firefly 校准 PHC；Rivermax 读取校准后的时间。

这个技能擅长回答的示例问题

这个技能旨在回答的 Firefly 问题类别，每类 附带一个具体示例。类别是关键部分；具体示例 只是其中一种情况。

• “我真的需要 Firefly 吗？NTP / chrony 是否已经够用？” — 示例：“我的分布式应用目前用 chrony 运行良好；有 理由再加入 PTP 吗？”。答案来自 capabilities companion 中的 PTP 与 NTP 路径选择规则
  • tasks companion 中的环境准备 检查清单。
• “启动容器前，我必须确定哪四个 PTP 配置维度？” — 示例：“一个希望让 Firefly 在线路侧端口上以从属角色 运行的 SMPTE ST 2110 广播设施”。答案来自 capabilities companion 中的四维配置表
  • tasks companion 中的 PTP 配置步骤。
• “Firefly 的容器正在运行，但主机时间没有跟随——我漏了什么？” — 示例：“ptp4l / Firefly 显示已锁定，但主机上的 chronyc tracking 显示 存在偏差”。答案来自 capabilities companion 中的端到端时间同步规范
  • tasks companion 中的主机跟随步骤。
• “PTP 已锁定，但偏移 / 抖动远超规格——路径出了什么问题？” — 示例：“已获取同步，但偏移 达到几十微秒”。答案来自 capabilities companion 中的 PTP 感知路径规则
  • tasks companion 中的分层调试步骤。
• “Firefly 如何与 Rivermax SMPTE 工作负载配合？” — 示例：“需要通过 PTP 锁定的 SMPTE ST 2110 视频发送端”。答案来自 capabilities companion 中的 Rivermax 配对规则
  • tasks companion 中的配对步骤；该步骤会将 Rivermax 部分导向 doca-rmax/SKILL.md，并拒绝 将两个服务合并为一个。
• “我的 Firefly 容器已启动，但 PTP 始终无法进入 SLAVE / MASTER 状态——问题在角色、域、配置文件还是接口？” — 示例：“容器状态正常，但端口状态输出始终停留在 LISTENING”。答案来自 capabilities companion 中的四维不匹配规则
  • tasks companion 中的分层排查步骤。

目标读者

此技能面向外部运维人员和平台团队，他们部署 DOCA Firefly Service 容器，为 BlueField 及其后方主机上的 时间敏感型工作负载提供 PTP 级时间同步。具体来说：在 BlueField Arm 上运行 Firefly 容器，根据公开的 Firefly 指南选择 其 PTP 角色 / 配置文件 / 域 / 接口，配置主机侧跟随者（通过 PHC 源同步的 chrony，或读取 PHC 的 ptp4l），使主机时钟 跟随 BlueField PHC，并在扩展依赖该功能的 Rivermax、5G UPF、 金融交易或分布式数据库工作负载之前，验证端到端同步规范。

此技能不适用于为 Firefly 本身做贡献的 NVIDIA 开发人员， 也不是使用 DOCA 库进行开发的编程指南（请参阅 doca-programming-guide/SKILL.md）。Firefly 是一项服务： 运维人员运行容器并配置 PTP；没有可供链接的 libfirefly.so。

先选择路径。 当 BlueField 和主机都需要亚微秒级、 PTP 级时间精度时，使用 Firefly（例如基于 Rivermax 的 SMPTE ST 2110 广播工作负载、5G UPF 时间要求、需要 PTP 级时间的 分布式系统，以及任何 NTP / chrony 抖动不够小的场景）。如果 NTP / chrony 已满足工作负载的时间精度预算、路径中不存在 支持 PTP 的交换机 / 边界时钟基础设施，或者纯软件侧时间精度 已足够，则不要选择 Firefly。在这些情况下，正确做法是保留主机现有的 chrony / NTP 配置，并引导 Agent 避开 Firefly， 而不是贸然部署。

何时加载此技能

当用户在已安装 DOCA 的 BlueField 上进行 实际 Firefly 部署工作 时，加载此技能。具体包括：

• 判断 Firefly 是否适合满足用户的时间精度要求（而不是继续在主机上使用 NTP / chrony）。
• 在 BlueField Arm 上部署 Firefly 容器——根据公开的 DOCA Firefly Service Guide 选择镜像来源、挂载 Firefly 配置，以及启动 / 停止容器。
• 为用户的部署选择四个 PTP 配置维度——PTP 角色（master / slave / boundary clock / transparent clock）、配置文件（根据 services/firefly/doca_firefly.yaml，PROFILE 环境变量只能接受 default / media / telco-l2 / custom；这些值对应行业 PTP 配置文件名称：default → IEEE 1588、media → SMPTE 2059-2、telco-l2 → 仅 G.8275.1（G.8275.2 对应单独的 telco-l3 配置，通过 custom 使用）——不要将行业名称直接填入环境变量）、域编号和网络接口。
• 配置主机侧跟随进程，使主机时钟跟随 BlueField PHC（通过 PHC 源使用 chrony，或使用 ptp4l / phc2sys 读取 PHC）——如果未执行此步骤，无论 Firefly 启动得多么顺利，主机时钟都不会跟随由 Firefly 校准的 PHC。
• 将 Firefly 与对时间敏感的使用方工作负载（Rivermax SMPTE、5G UPF、金融、分布式数据库）配合使用，并验证端到端校准效果。
• 查看 Firefly 容器日志、PHC 偏移、端口状态输出或其他文档记录的可观测性信息，以确认 PTP 已锁定。
• 排查 Firefly 部署问题：容器运行正常但 PTP 未同步；PTP 已同步但主机时钟未跟随；或同步已建立但抖动超出规格。

不要为常规 DOCA 入门、安装 DOCA 本身、库 API 问题或非 PTP 时间相关主题加载此技能。对于这些问题，请转到 doca-public-knowledge-map/SKILL.md、doca-setup/SKILL.md 或相应的 libs/<library> 技能。

此技能提供的内容

这是一个轻量加载器。实质性内容位于两个配套文件中：

• 能力配套文件——Firefly 的架构（驱动 BlueField PHC 并通过网络传输 PTP 的容器）、四个 PTP 配置维度（角色 / 配置文件 / 域 / 接口，传输方式是第五个可调参数）、部署形态（根据公开的 Container Deployment Guide 在 BlueField Arm 上运行容器）、配套方案（Rivermax + 主机侧时间同步跟随进程）、可观测性信息（容器日志 + PHC 偏移 + 端口状态）、错误分类（四维配置不匹配 / 主机跟随进程 / PTP 感知路径 / 容器运行时）以及安全策略（PTP 与 NTP 路径选择、端到端校准、先冒烟测试再扩展）。
• 任务配套文件——适用范围内 Firefly 操作的分步工作流：configure、build、modify、run、test、debug；另含用于引导用户处理范围外问题的 Deferred task verbs 区块，以及汇总常用命令的 Command appendix。

此技能适用于已安装 DOCA 的 BlueField，并假定操作员拥有公开的 Firefly Service Guide 所要求的权限，能够在 BlueField Arm 上拉取、运行和配置容器。此技能不涵盖安装 DOCA——相关流程请参阅 doca-setup/SKILL.md。

此技能有意不提供的内容

此技能是Agent 指南，不是模板或示例配置合集。为明确划定边界，此技能有意不包含以下内容，合并请求也不应添加：

• 预先编写好的 Firefly 配置文件（完整的 PTP 配置块、可直接运行的角色／配置文件／域组合），供复制粘贴到生产环境中。PTP 配置因部署而异（取决于用户的配置文件、域规划、接口命名和上游 PTP 拓扑）；对于外部操作员，稳妥的做法是根据其自身部署，参照公开的 Firefly Service Guide 推导配置。Agent 的职责是规定流程和四轴决策，而不是提供用户可能未经修改就直接运行的配置。
• 容器镜像名称、标签或注册表路径。 权威镜像来源是公开的 DOCA Firefly Service Guide，可通过 doca-public-knowledge-map ## DOCA services（doca-public-knowledge-map/SKILL.md#doca-services）访问；Firefly 的镜像标签与版本绑定，并会随 DOCA 版本发布而变化。编造或记忆某个标签，是服务技能中最典型的幻觉失误。
• 主机端的 chrony 配置段或 ptp4l／phc2sys 配置文件。 这些内容因主机环境而异，存在于主机上，而非 Firefly 容器内。此技能会说明主机端从时钟必须接入，以及它必须以什么为时钟源（BlueField PHC）；chrony／ptp4l 配置正文应由主机操作员负责，并参照上游 Linux PTP 文档。
• 任何类型的 samples/、templates/ 或 reference/ 子目录。 即使标注为*"参考"*，技能目录中的模拟或不完整产物也会造成误导：操作员会将其视为可用于生产环境的内容。

加载顺序

1. 首先阅读此技能，确认用户的问题属于其范围，并且 Firefly 确实是合适的解决方案（而不是在主机上继续使用 NTP／chrony）。
2. 有关 Firefly 的部署形态、四个 PTP 配置轴、Rivermax 与主机端从时钟的配对方式、错误分类体系、可观测性范围以及端到端安全策略，请参阅配套的 capabilities 文档。
3. 有关配置、构建、修改、运行、测试和调试的分步工作流，请参阅配套的 tasks 文档。

相关技能

• doca-public-knowledge-map/SKILL.md — 指向公开 DOCA Firefly Service Guide 和 其余公开 DOCA 文档集的路由表。Firefly URL 列在 ## DOCA services 下（doca-public-knowledge-map/SKILL.md#doca-services）。
• doca-setup/SKILL.md — 在运行 Firefly 容器的 BlueField 上进行环境准备和 安装验证，包括通过公开的 NGC DOCA 容器走 我尚未安装 的路径。此技能假定 BlueField Arm 上的 前置条件均已满足。
• doca-version/SKILL.md — DOCA 版本处理的 权威规则。Firefly 的容器标签与版本绑定； 此技能的 ## Version compatibility 交叉链接四方匹配规则， 并补充容器标签滞后于主机软件包的说明。
• doca-structured-tools-contract/SKILL.md — 此技能包的结构化工具优先级规则（检测 / 优先使用 / 回退 / 报告）。任务配套文档中的 Command 附录 遵循此契约。
• doca-programming-guide/SKILL.md — 通用 DOCA 模式。Firefly 以服务为形态，而非以库为形态， 因此其中的构建 / 修改 / 首个应用模式不直接适用； 但跨库调试规范（先前端、后后端；先环境、后程序）仍然有用， 尤其是 Firefly 报告的错误源自容器运行时或其调用的 DOCA 库时。
• doca-rmax/SKILL.md — 权威的 配套工作负载。SMPTE ST 2110 Rivermax 流依赖由 Firefly 规范校准的 PHC； Firefly 负责时间源一侧，Rivermax 负责时序精准的数据平面一侧。这两种技能 会在任何广播式部署中同时加载，且不会相互合并——Firefly 不传输媒体； Rivermax 不校准 PHC。
• doca-dms/SKILL.md — 同类服务技能。阅读这两种技能的 Agent 应能看到相同的服务技能结构 （容器、BlueField Arm、部署模式、先冒烟测试再扩展、 环境前置条件、配置架构），但其上叠加的是不同的 服务专属领域（DMS = 通过 gNMI / gNOI 进行设备管理； Firefly = 通过 PTP 进行时间同步）。
• doca-debug/SKILL.md — 跨领域的 调试阶梯（安装 / 版本 / 构建 / 链接 / 运行时 / 程序 / 驱动程序）。Firefly 专属调试（PTP 未同步、 主机时钟未跟随、抖动超出规格）会叠加在此阶梯之上。