/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:
  kind: service
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.

DOCA Firefly Service

> **Subsystem inventory (Run-12 correction, verified Run-13).** > 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; the bundle previously framed `phc2sys` as > host-only, which is wrong. > 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 [`TASKS.md`](TASKS.md) and start at [`## configure`](TASKS.md#configure). If the question is *what shape of service is Firefly and what PTP roles / profiles does it speak*, start at [`CAPABILITIES.md`](CAPABILITIES.md). If DOCA is not installed on the BlueField yet, route to [`doca-setup`](../../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`](../../libs/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 a reason to add PTP?"*. Answered by the PTP-vs-NTP path- selection rule in [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)

• the env-prep checklist in

[`TASKS.md ## configure`](TASKS.md#configure).

• **"What four PTP configuration axes do I have to decide before

starting the container?"** — worked example: *"a SMPTE ST 2110 broadcast plant that wants Firefly in slave role on the wire-side port"*. Answered by the four-axis configuration table in [`CAPABI