/doca-firefly

license: Apache-2.0
name: doca-firefly
description: >
  Use this skill when the user is operating the DOCA Firefly Service
  container on BlueField — picking the four PTP configuration axes (role
  / profile / domain / interface), wiring the BlueField PHC + host
  follower + consumer workload pairing, deciding whether PTP-grade time
  is even needed (vs. chrony / NTP), or debugging a Firefly deployment
  where PTP isn't syncing or the host clock isn't following. Trigger
  even when the user does not explicitly mention "DOCA Firefly" or "PTP"
  — typical implicit phrasings include "container green but PTP never
  advances past LISTENING", "Firefly says synced but the host clock
  still drifts", "sync acquired but offset is tens of microseconds", "my
  Rivermax SMPTE workload needs PTP", or "is chrony good enough". Refuse
  and route elsewhere for installing DOCA, host-side chrony / ptp4l
  config bodies, PTP topology / boundary-clock design, building DOCA
  apps that read the disciplined PHC, or other DOCA services (DMS,
  Flow-Inspector, HBN) — those belong to other skills.
metadata:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: service
  doca_version: "3.5"
  tags:
    - doca
    - firefly
    - ptp
compatibility: >
  BlueField-Arm-only DOCA service container; pulled from NVIDIA NGC and
  started under the BlueField OS container runtime. Host-side install is
  irrelevant. Requires a reachable PTP master (or runs as the master
  itself) and a PTP-aware network path; the host-side time follower
  (chrony / ptp4l / phc2sys reading the BlueField PHC) is also
  operator-owned. The validation steps require a live DOCA install.

DOCA Firefly Service

Examples

• **“Container green but PTP never advances past LISTENING.”**

— this is in scope. Check role / profile / domain / interface before changing host chrony.

• **“Firefly says synced but the host clock still drifts.”** —

wire the BlueField PHC follower; Firefly does not replace host-side chrony / ptp4l bodies.

Instructions

Follow Loading order below. Open the tasks companion for configure / sync / debug. Open the capabilities companion for PTP axes. Do not open every companion file.

> **Subsystem inventory.** > DOCA Firefly is NOT just "a PTP daemon." The shipped > `doca_firefly.yaml` exposes **six** PTP-stack subsystems via > environment variables, each with its own `*_STATE`, > `*_CONFIG_FILE`, and (where relevant) `*_INTERFACE` / > `*_DEVICE` knobs (the count is six because the PTP Monitor > subsystem ships an internal `phc2sys` monitor client that is > distinct from the standalone PHC2SYS subsystem — both ship in > the same container image): > > 1. **PTP** (`PTP_STATE`, `PTP_INTERFACE`, `PTP_CONFIG_FILE`) — > the `ptp4l` daemon (or master, depending on profile) that > drives the BlueField PHC. > 2. **PTP Monitor** (`MONITOR_STATE`, `MONITOR_CONFIG_FILE`, > `MONITOR_CLIENT_TYPE`, `MONITOR_CLIENT_PHC2SYS_INTERFACE`, > `MONITOR_CLIENT_CONNECTION_TIMEOUT`) — the monitor server + > client surface; the **internal `phc2sys` monitor client** > (`MONITOR_CLIENT_TYPE=phc2sys`) is a real subsystem inside > Firefly, not just a host-side concern. > 3. **PHC2SYS** (`PHC2SYS_STATE`, `PHC2SYS_ARGS`, > `PHC2SYS_CONFIG_FILE`) — the **container-internal** `phc2sys` > instance (not host-only). > 4. **PPS** (`PPS_STATE`, `PPS_DEVICE`) — the Pulse-Per-Second > output (with the additional `enable_while_running` and > `do_nothing` states beyond plain enable/disable). > 5. **SyncE** (`SYNCE_STATE`, `SYNCE_INTERFACE`, > `SYNCE_CONFIG_FILE`) — Synchronous Ethernet frequency > distribution; orthogonal to PTP. > 6. **Firefly Servo** (`SERVO_STATE`, `SERVO_CONFIG_FILE`) — > the proprietary Firefly servo loop (alternative to the > upstream linuxptp servo). > > The valid `PROFILE` values are exactly **`default` / `media` / > `telco-l2` / `custom`** (per `doca_firefly.yaml` comments) — > the agent must not invent additional values. Subsystems configured > as `defined_by_profile` are controlled by the active `PROFILE`. > > Configuration-override env vars follow the pattern > `CONF_<SUBSYSTEM>_<section>_<key>` (e.g. > `CONF_PTP_global_priority1`, `CONF_SYNCE_global_backend`, > `CONF_MONITOR_global_telemetry_export`); these are the > documented surface for overriding individual config keys > without shipping a full custom config file. > > **Configuration hierarchy:** the mounted Firefly config file is > mandatory and owns the primary PTP axes (role, profile, domain, > interface, and transport). `CONF_<SUBSYSTEM>_<section>_<key>` > variables are optional, documented per-key overrides of that file; > they are not a second standalone configuration model.

**Where to start:** This skill is for *operating* the DOCA Firefly Service container, not for *linking against* a library. Firefly is the **PTP / PHC2SYS / PPS / SyncE / Servo / Monitor** stack that drives and observes the BlueField PTP Hardware Clock (PHC); it is *not* the host-side time follower, *not* the consumer workload, and *not* a programming surface. If the user wants to *deploy* the container, open the tasks companion and start at `## configure`. If the question is *what shape of service is Firefly and what PTP roles / profiles does it speak*, start at the capabilities companion. If DOCA is not installed on the BlueField yet, route to `doca-setup/SKILL.md` first. If the user's real question is *“I have a Rivermax SMPTE workload and the docs say I need PTP”*, the right pairing is this skill **plus** `doca-rmax/SKILL.md` — Firefly disciplines the PHC; Rivermax reads the disciplined time.

Example questions this skill answers well

The CLASSES of Firefly questions this skill is built to answer, each with one worked example. The class is the load-bearing piece; the worked example is one instance.

• **“Do I actually need Firefly, or is NTP / chrony good enough?”** —

worked example: *“my distributed app is fine on chrony today; is there