doca-firefly

# 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
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + the PTP-config step in
  [`TASKS.md ## configure`](TASKS.md#configure).
- **"Firefly's container is running but the host's time isn't
  following — what did I miss?"** — worked example: *"`ptp4l` /
  Firefly says it's locked but `chronyc tracking` on the host shows
  drift"*. Answered by the END-TO-END time-sync discipline in
  [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)
  + the host-follower step in
  [`TASKS.md ## configure`](TASKS.md#configure).
- **"PTP locks but the offset / jitter is way past spec — what's
  wrong with the path?"** — worked example: *"sync acquired but offset
  is in the tens of microseconds"*. Answered by the PTP-aware-path
  rule in
  [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)
  + the layered debug ladder in
  [`TASKS.md ## debug`](TASKS.md#debug).
- **"How does Firefly pair with a Rivermax SMPTE workload?"** —
  worked example: *"SMPTE ST 2110 video sender that needs to be PTP-
  locked"*. Answered by the Rivermax-pairing rule in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + the pairing step in
  [`TASKS.md ## configure`](TASKS.md#configure), which routes the
  Rivermax side to
  [`doca-rmax`](../../libs/doca-rmax/SKILL.md) and refuses to
  collapse the two services into one.
- **"My Firefly container starts but PTP never reaches
  `SLAVE` / `MASTER` state — was it role, domain, prof