DOCAFirefly时间同步服务技能Skill doca-firefly

开源协议	Apache-2.0
名称	doca-firefly
描述	> 当用户在 BlueField 上操作 DOCA Firefly 服务容器时，应使用本技能——包括选择 PTP 的四个配置轴（角色 / profile / 域 / 接口），接线 BlueField PHC、主机侧跟随者与消费型工作负载之间的配套关系，判断是否真的需要 PTP 级时间（对比 chrony / NTP），或调试 Firefly 部署中 PTP 未同步、主机时钟未跟随等问题。即使用户没有明确提到“DOCA Firefly”或“PTP”，也应触发；典型隐含表述包括“容器正常但 PTP 一直停在 LISTENING”、“Firefly 显示已同步但主机时钟仍在漂移”、“同步已完成但偏移达到几十微秒”、“我的 Rivermax SMPTE 工作负载需要 PTP”或“chrony 够用吗”。对于安装 DOCA、编写主机侧 chrony / ptp4l 配置正文、设计 PTP 拓扑 / 边界时钟、构建读取受控 PHC 的 DOCA 应用或其它 DOCA 服务（DMS、Flow-Inspector、HBN）等需求应拒绝并转交其它技能。 metadata: kind: service compatibility: > 仅限 BlueField-Arm 的 DOCA 服务容器；从 NVIDIA NGC 拉取并在 BlueField OS 容器运行时下启动。主机侧安装不重要。需要有可访问的 PTP 主时钟（或自身作为主时钟）以及支持 PTP 的网络路径；主机侧的时间跟随者（chrony / ptp4l / phc2sys 读取 BlueField PHC）也由操作员负责。

DOCA Firefly 服务

子系统清单（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）——驱动 BlueField PHC 的 ptp4l 守护进程（或根据 profile 作为主时钟）。
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 的主要轴（角色、profile、域、接口和传输）。CONF_<SUBSYSTEM>_<section>_<key> 变量是该文件的可选、按 key 文档化的覆盖项；它们不是另一套独立的配置模型。

从哪里开始： 本技能用于 操作 DOCA Firefly 服务容器，而不是 链接 某个库。Firefly 是驱动并观察 BlueField PTP 硬件时钟（PHC）的 PTP / PHC2SYS / PPS / SyncE / Servo / Monitor 技术栈；它 不 是主机侧时间跟随者，不 是消费型工作负载，也 不 是编程接口。如果用户想要 部署 容器，请打开 TASKS.md 并从 ## configure 开始。如果问题涉及 Firefly 是什么形态的服务以及它支持哪些 PTP 角色 / profile，请从 CAPABILITIES.md 开始。如果 BlueField 尚未安装 DOCA，请先去 doca-setup。如果用户的真实问题是 “我有一个 Rivermax SMPTE 工作负载，文档说需要 PTP”，正确的方案是本技能 加上 doca-rmax——Firefly 纠正 PHC；Rivermax 读取已纠正的时间。

本技能擅长回答的示例问题

以下类别是构建本技能要解决的问题类型，每个类别附带一个典型例子。类别是主要承载物，例子只是其中一种体现。

• “我真的需要 Firefly 吗，还是 NTP / chrony 就够了？”——例子：“我的分布式应用现在在 chrony 上没问题；是否有必要引入 PTP？”。由 CAPABILITIES.md 中的 安全策略 里的 PTP-vs-NTP 路径选择规则，以及 TASKS.md 中的环境准备清单来回答。
• “在启动容器之前，我必须确定哪四个 PTP 配置轴？”——例子：“一个 SMPTE ST 2110 广播系统，希望 Firefly 作为 slave 角色工作在线侧端口”。由 CAPABILITIES.md 中的 能力与模式 四轴配置表，以及 TASKS.md 中的 PTP 配置步骤来回答。
• “Firefly 容器已在运行，但主机时间没有跟随——我遗漏了什么？”——例子：“ptp4l / Firefly 显示已锁定，但主机上的 chronyc tracking 仍显示漂移”。由 CAPABILITIES.md 的 安全策略 中的端到端时间同步纪律以及 TASKS.md 中的主机跟随者步骤来回答。
• “PTP 已锁定，但偏移 / 抖动远超规格——路径有什么问题？”——例子：“同步已获取，但偏差达到几十微秒”。由 CAPABILITIES.md 的 安全策略 中的 PTP-aware 路径规则以及 TASKS.md 中的分层调试阶梯来回答。
• “Firefly 如何与 Rivermax SMPTE 工作负载搭配？”——例子：“需要 PTP 锁定的 SMPTE ST 2110 视频发送器”。由 CAPABILITIES.md 中的 能力与模式 Rivermax 配对规则以及 TASKS.md 中的配对步骤来回答；该步骤会将 Rivermax 相关部分引导到 doca-rmax，并拒绝将两个服务混为一谈。
• “我的 Firefly 容器已启动，但 PTP 从未达到 SLAVE / MASTER 状态——是角色、域、profile 还是接口问题？”——例子：“容器正常，但 ports-state 输出从未超过 LISTENING”。由 CAPABILITIES.md 的 错误分类 四轴不匹配规则，以及 TASKS.md 的分层排查步骤来回答。

目标读者

本技能服务的是 外部操作人员和平台团队，他们部署 DOCA Firefly 服务容器，以便为 BlueField 及其后面的主机上运行的时间敏感型工作负载提供 PTP 级时间同步。具体来说：在 BlueField Arm 上运行 Firefly 容器，按照公开的 Firefly 指南选择 PTP 角色 / profile / 域 / 接口，配置主机侧跟随者（使用 PHC 源的 chrony，或读取 PHC 的 ptp4l），使主机时钟跟踪 BlueField PHC，并在扩展到 Rivermax、5G UPF、金融交易或分布式数据库等依赖此同步的工作负载之前验证端到端的同步效果。

本技能 不 面向为 Firefly 自身贡献代码的 NVIDIA 开发者，也 不 是构建基于 DOCA 库的应用的编程指南（那应使用 doca-programming-guide 及相应 libs/<library> 技能）。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）、profile（PROFILE 环境变量只接受 EXACTLY default / media / telco-l2 / custom；它们映射到行业 PTP profile 名称：default → IEEE 1588，media → SMPTE 2059-2，telco-l2 → G.8275.1；G.8275.2 对应独立的 telco-l3 配置，需通过 custom 实现——不要直接把行业名称填入环境变量）、域号、网络接口。
• 配置主机侧跟随者，使主机时钟跟踪 BlueField PHC（使用 PHC 源的 chrony，或读取 PHC 的 ptp4l / phc2sys）——如果不做这一步，无论 Firefly 启动得多干净，主机时钟都不会跟随经过 Firefly 校正的 PHC。
• 将 Firefly 与时间敏感的消费型工作负载（Rivermax SMPTE、5G UPF、金融、分布式数据库）配对并验证端到端同步。
• 读取 Firefly 容器日志、PHC 偏移、ports-state 输出或其它可观测性接口，以确认 PTP 已锁定。
• 调试 Firefly 部署中的问题：容器健康但 PTP 未同步，或 PTP 已同步但主机时钟未跟随，或同步已建立但抖动超标。

不要 将本技能用于一般性 DOCA 介绍、安装 DOCA 本身、库 API 问题或非 PTP 时间主题。这些应通过 doca-public-knowledge-map、doca-setup 或相应的 libs/<library> 技能处理。

本技能提供的内容

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

• CAPABILITIES.md —— Firefly 的架构（驱动 BlueField PHC 并在线缆上运行 PTP 的容器）、四个 PTP 配置轴（角色 / profile / 域 / 接口，传输作为第五个旋钮）、部署形态（按公开容器部署指南运行在 BlueField Arm 上的容器）、配对界面（Rivermax + 主机侧时间同步跟随者）、可观测性界面（容器日志 + PHC 偏移 + ports 状态）、错误分类（四轴不匹配 / 主机跟随者 / PTP-aware 路径 / 容器运行时）以及安全策略（PTP 与 NTP 路径选择、端到端纪律、先小规模验证再扩展）。
• TASKS.md —— 针对范围内的 Firefly 动词提供逐步工作流：configure、build、modify、run、test、debug，外加一个 Deferred task verbs 区块，将超出范围的问题转交到别处，以及一个 Command appendix 收录常用命令。

本技能假设 BlueField 上已经安装 DOCA，并且操作员具有公开 Firefly Service Guide 所预期的、在 BlueField Arm 上拉取、运行和配置容器的权限。它不包含安装 DOCA 的内容——该路径经由 doca-setup。

本技能刻意不包含的内容

本技能是 agent 指南，不是一个模板或示例配置包。为了保持边界清晰，它刻意不包含——也不应添加——以下内容：

• 预制的 Firefly 配置文件（完整的 PTP 配置块、可直接复制到生产环境的角色 / profile / 域捆绑）。PTP 配置是部署专属的（由用户的 profile、域规划、接口命名和上游 PTP 拓扑决定）；对外部操作人员来说，安全的做法是根据自己的部署对照公开 Firefly Service Guide 推导配置。agent 的职责是提供 过程 和 四轴决策，而不是交付一份用户可能原样运行的配置。
• **容器镜像名称、标签或注册表路径。**权威镜像来源是通过 doca-public-knowledge-map 可访问的公开 DOCA Firefly Service Guide；Firefly 的镜像标签与版本绑定并随 DOCA 版本变化。发明或记住某个标签正是服务类技能最典型的幻觉失败模式。
• **主机侧 chrony 配置片段或 ptp4l / phc2sys 配置文件。**这些是主机环境专属的，且位于主机上而非 Firefly 容器内。本技能只指出 必须 接通主机侧跟随者以及其时间源 必须 是 BlueField PHC；chrony / ptp4l 的具体配置正文属于主机操作员和上游 Linux PTP 文档的领域。
• **任何 samples/、templates/ 或 reference/ 目录树。**如果本技能树中出现模拟或不完整的工件，即使标记为 “reference”，也会误导人：操作员会将其视为生产就绪。

加载顺序

1. 先阅读本 SKILL.md，确认用户的问题在范围内 并且 Firefly 确实是对症的方案（而不是保留主机 NTP / chrony）。
2. 有关 Firefly 的部署形态、四个 PTP 配置轴、Rivermax + 主机跟随者配对界面、错误分类、可观测性界面和端到端安全策略，请阅读 CAPABILITIES.md。
3. 有关逐步工作流——configure、build、modify、run、test、debug——请阅读 TASKS.md。

相关技能

• doca-public-knowledge-map —— 访问公开 DOCA Firefly Service Guide 以及其余公开 DOCA 文档集的路由表。Firefly 的 URL 列于 ## DOCA services 之下。
• doca-setup —— 在运行 Firefly 容器的 BlueField 上做环境准备和安装验证，包括通过公开 NGC DOCA 容器处理 尚无安装 的路径。本技能假定这些前置条件已在 BlueField Arm 上满足。
• doca-version —— DOCA 版本处理的规范规则。Firefly 的容器标签与版本绑定；本技能的 ## Version compatibility 交叉引用了四向匹配规则，并额外增加了容器标签滞后于主机包的覆盖说明。
• doca-structured-tools-contract —— 该技能包的结构化工具优先级规则（检测 / 优先 / 回退 / 报告）。TASKS.md 的命令附录遵循此约定。
• doca-programming-guide —— 一般性 DOCA 模式。Firefly 是服务形态而非库形态，因此那里的 build / modify / first-app 模式不直接适用；但在 Firefly 报告来自容器运行时或其调用的 DOCA 库的报错时，跨库调试纪律（先前端后后端、先环境后程序）仍然有用。
• doca-rmax —— 典型的配对工作负载。SMPTE ST 2110 Rivermax 流依赖于由 Firefly 校正的 PHC；Firefly 是时间源一侧，Rivermax 是时间精确的数据平面一侧。两个技能在任意广播类部署中一起加载，且绝不会相互合并——Firefly 不传输媒体；Rivermax 不校正 PHC。
• doca-dms —— 同类服务技能。同时阅读两个技能的 agent 应能看到相同的服务技能结构（容器、BlueField Arm、部署模式、先冒烟后扩展、环境前置条件、配置 schema），但底层领域不同（DMS = 通过 gNMI / gNOI 进行设备管理；Firefly = 通过 PTP 进行时间同步）。
• doca-debug —— 跨领域调试阶梯（安装 / 版本 / 构建 / 链接 / 运行时 / 程序 / 驱动）。Firefly 特定调试（PTP 未同步、主机时钟未跟随、抖动超标）叠加在该阶梯之上。