doca-firefly

DOCA Firefly Service

例

• 「コンテナは正常なのに、PTP が LISTENING から先に進みません。」 — これは対象範囲内です。ホストの chrony を変更する前に、role / profile / domain / interface を確認してください。
• 「Firefly は同期済みと表示されるのに、ホストのクロックがまだずれています。」 — BlueField PHC follower を接続してください。Firefly はホスト側の chrony / ptp4l の処理を置き換えるものではありません。

手順

以下の読み込み順に従ってください。設定／同期／デバッグについてはタスクのコンパニオンを開いてください。PTP 軸については機能のコンパニオンを開いてください。 すべてのコンパニオンファイルを開かないでください。

サブシステムの一覧（Run-12 の修正、Run-13 で検証済み）。 DOCA Firefly は単なる「PTP デーモン」ではありません。同梱の doca_firefly.yaml は、環境変数を介して 6 つの PTP スタックサブシステムを公開しており、それぞれに独自の *_STATE、 *_CONFIG_FILE、および（該当する場合）*_INTERFACE ／ *_DEVICE の設定項目があります（PTP Monitor サブシステムには、単独の PHC2SYS サブシステムとは別個の内部 phc2sys モニタークライアントが同梱されているため、6 つです。 どちらも同じコンテナーイメージに含まれています）：

1. PTP（PTP_STATE、PTP_INTERFACE、PTP_CONFIG_FILE）— BlueField PHC を制御する ptp4l デーモン（またはプロファイルに応じてマスター）。
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）— パルス毎秒 （Pulse-Per-Second）出力です（通常の有効／無効に加えて、 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 のコメントに記載）。 エージェントはこれ以外の値を作り出してはいけません。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> 変数は、そのファイルに対する任意の、キーごとに文書化された上書き設定です。2 つ目の独立した設定モデルではありません。

最初に確認すること： このスキルは 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 に関する質問のクラスです。それぞれに具体例を 1 つ示します。重要なのは質問のクラスであり、具体例はその一例です。

• 「本当に Firefly が必要ですか？ NTP ／ chrony で十分ではありませんか？」 — 具体例：「現在、分散アプリは chrony で問題なく動作しています。PTP を追加する理由はありますか？」。回答では、 capabilities コンパニオンにある PTP と NTP の経路選択ルール と tasks コンパニオンにある環境準備チェックリスト を参照します。
• 「コンテナを起動する前に、どの 4 つの PTP 設定軸を決める必要がありますか？」 — 具体例：「Firefly をワイヤー側ポートでスレーブロールとして動作させたい SMPTE ST 2110 放送設備です」。回答では、 capabilities コンパニオンにある 4 軸の設定表 と tasks コンパニオンにある PTP 設定手順 を参照します。
• 「Firefly のコンテナは動作していますが、ホストの時刻が追従しません。何が抜けていますか？」 — 具体例：「ptp4l ／ Firefly はロック済みと表示しますが、ホスト上の chronyc tracking ではずれが示されます」。回答では、 capabilities コンパニオンにあるエンドツーエンドの時刻同期に関する規律 と tasks コンパニオンにあるホスト追従手順 を参照します。
• 「PTP はロックしますが、オフセット ／ ジッターが仕様を大幅に超えています。経路に何が問題ありますか？」 — 具体例：「同期は確立しましたが、オフセットが数十マイクロ秒あります」。回答では、 capabilities コンパニオンにある PTP 対応経路のルール と tasks コンパニオンにある段階的なデバッグ手順 を参照します。
• 「Firefly は Rivermax の SMPTE ワークロードとどのように連携しますか？」 — 具体例：「PTP ロックが必要な SMPTE ST 2110 ビデオ送信側です」。回答では、 capabilities コンパニオンにある Rivermax との連携ルール と tasks コンパニオンにある連携手順を参照します。この手順では、Rivermax 側の処理を doca-rmax/SKILL.md に案内し、2 つのサービスを 1 つにまとめることは避けます。
• 「Firefly コンテナは起動しますが、PTP が SLAVE ／ MASTER 状態になりません。ロール、ドメイン、プロファイル、インターフェースのどれが原因ですか？」 — 具体例：「コンテナは正常ですが、ports-state の出力が LISTENING から先に進みません」。回答では、 capabilities コンパニオンにある 4 軸の不一致ルール と tasks コンパニオンにある段階的な手順 を参照します。

対象読者

このスキルは、BlueField とその背後のホスト上で、時間に敏感なワークロードに PTP グレードの時刻同期を提供するために DOCA Firefly Service コンテナをデプロイする外部オペレーターおよびプラットフォームチームを対象としています。具体的には、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 設定を維持し、エージェントを Firefly 以外の選択肢に案内するのが適切です。検証のためだけに Firefly をデプロイしないでください。

このスキルを読み込むタイミング

DOCA がすでにインストールされている BlueField で、ユーザーがFirefly の実運用デプロイ作業を行っている場合に、このスキルを読み込みます。具体的には、次のような場合です。

• ユーザーが求める時刻精度に Firefly が適しているかどうかを判断する場合（ホストで NTP／chrony を使い続ける場合との比較）。
• BlueField Arm に Firefly コンテナをデプロイする場合。公開されている DOCA Firefly Service Guide に基づいてイメージの入手元を選び、Firefly の設定をマウントして、コンテナを起動／停止します。
• デプロイに合わせて、PTP の 4 つの設定軸を選ぶ場合：PTP の役割（マスター／スレーブ／バウンダリークロック／トランスペアレントクロック）、プロファイル（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、または PHC を読み取る ptp4l／phc2sys を設定します。この手順を行わないと、Firefly が正しく起動していても、ホストクロックは Firefly によって同期された PHC に追従しません。
• Firefly を時間に敏感なコンシューマーワークロード（Rivermax SMPTE、5G UPF、金融、分散データベース）と組み合わせ、エンドツーエンドの同期状態を検証する場合。
• Firefly コンテナのログ、PHC オフセット、ポート状態の出力、またはその他の文書化された可観測性の手段を確認し、PTP がロックされていることを確かめる場合。
• コンテナは正常でも PTP が同期していない場合、PTP は同期しているのにホストクロックが追従していない場合、または同期しているもののジッターが仕様を超えている場合に、Firefly のデプロイをデバッグする場合。

一般的な DOCA の概要、DOCA 自体のインストール、ライブラリ API に関する質問、PTP 以外の時刻に関するトピックでは、このスキルを読み込まないでください。その場合は、 doca-public-knowledge-map/SKILL.md、 doca-setup/SKILL.md、または該当する libs/<library> スキルに案内してください。

このスキルでできること

このスキルは薄いローダーです。実質的な内容は、次の 2 つの関連ファイルにあります。

• 機能に関する関連ファイル — Firefly のアーキテクチャ（BlueField PHC を制御し、ネットワーク上で PTP を通信するコンテナ）、PTP の 4 つの設定軸（役割／プロファイル／ドメイン／インターフェース。トランスポートは 5 つ目の設定項目です）、デプロイ形態（公開されている Container Deployment Guide に基づき、BlueField Arm 上でコンテナを実行）、連携対象（Rivermax とホスト側の時刻同期フォロワー）、可観測性の手段（コンテナログ + PHC オフセット + ポート状態）、エラー分類（4 つの設定軸の不一致／ホスト側フォロワー／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 を参照してください。

このスキルに意図的に含めていないもの

このスキルはエージェント向けのガイダンスであり、テンプレートや設定例のバンドルではありません。境界を明確にするため、以下は意図的に含めていません。また、プルリクエストで追加しないでください。

• あらかじめ用意された Firefly 設定ファイル（PTP 設定ブロック一式、すぐに実行できるロール／プロファイル／ドメインのバンドル）で、本番環境にコピーして貼り付けることを想定したもの。PTP の設定はデプロイ環境によって異なります（ユーザーのプロファイル、ドメイン計画、インターフェース名、上流の PTP トポロジーに応じて異なります）。外部のオペレーターに対する安全な回答は、公開されている Firefly Service Guide を参照し、それぞれのデプロイ環境に合わせて設定を作成することです。エージェントの役割は、手順と4 つの軸に基づく判断を示すことであり、ユーザーが変更せずに実行する可能性のある設定を提供することではありません。
• コンテナーイメージ名、タグ、レジストリパス。 正式なイメージの情報源は、doca-public-knowledge-map ## DOCA services（doca-public-knowledge-map/SKILL.md#doca-services）から参照できる、公開されている DOCA Firefly Service Guide です。Firefly のイメージタグはバージョンに依存し、DOCA のリリースごとに変わります。タグを推測したり記憶したりすることは、サービススキルで典型的なハルシネーションの原因です。
• ホスト側の chrony 設定項目、または ptp4l／phc2sys 設定ファイル。 これらはホスト環境固有のものであり、Firefly コンテナー内ではなくホスト上にあります。このスキルでは、ホスト側のフォロワーを接続する必要があることと、そのソースが BlueField PHC である必要があることを示します。chrony／ptp4l の設定内容は、ホストのオペレーターと上流の Linux PTP ドキュメントが扱うものです。
• 種類を問わず、samples/、templates/、または reference/ のサブツリー。このスキルのツリーにあるモックや不完全な成果物は、たとえ 「reference」 と記されていても、誤解を招きます。オペレーターが本番環境ですぐに使えるものとして受け取る可能性があります。

読み込み順序

1. まずこのスキルを読み、ユーザーの質問が対象範囲内であること、また Firefly が本当に適切な解決策か（ホスト上で NTP／chrony を使い続けるべきではないか）を確認してください。
2. Firefly のデプロイ形態、PTP 設定の 4 つの軸、Rivermax とホスト側フォロワーの組み合わせ方、エラーの分類、可観測性の範囲、END-TO-END の安全性ポリシーについては、機能の補足ドキュメントを参照してください。
3. 設定、ビルド、変更、実行、テスト、デバッグの手順については、タスクの補足ドキュメントを参照してください。

関連スキル

• 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 では、4 要素の一致ルールへの相互リンクに加え、コンテナータグがホストパッケージより遅れる場合の補足を記載しています。
• 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 はタイミング精度が求められるデータプレーン側です。ブロードキャスト形式のデプロイでは、2 つのスキルを一緒に読み込みますが、互いに置き換えることはできません。Firefly はメディアをストリーミングせず、Rivermax は PHC を調整しません。
• doca-dms/SKILL.md — 関連するサービススキルです。両方のスキルを読むエージェントには、異なるサービス固有の領域（DMS = gNMI／gNOI によるデバイス管理、Firefly = PTP による時刻同期）に共通のサービススキル構成（コンテナー、BlueField Arm、デプロイパターン、スモークテストを行ってから規模を拡大、環境の前提条件、設定スキーマ）が重ねられていることがわかります。
• doca-debug/SKILL.md — 横断的なデバッグ手順（インストール／バージョン／ビルド／リンク／ランタイム／プログラム／ドライバー）です。PTP が同期しない、ホストクロックが追従しない、ジッターが仕様を超えるといった Firefly 固有のデバッグは、この手順に重ねて行います。