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):
- PTP (
PTP_STATE, PTP_INTERFACE, PTP_CONFIG_FILE) —
the ptp4l daemon (or master, depending on profile) that
drives the BlueField PHC.
- 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.
- PHC2SYS (
PHC2SYS_STATE, PHC2SYS_ARGS,
PHC2SYS_CONFIG_FILE) — the container-internal phc2sys
instance (not host-only).
- PPS (
PPS_STATE, PPS_DEVICE) — the Pulse-Per-Second
output (with the additional enable_while_running and
do_nothing states beyond plain enable/disable).
- SyncE (
SYNCE_STATE, SYNCE_INTERFACE,
SYNCE_CONFIG_FILE) — Synchronous Ethernet frequency
distribution; orthogonal to PTP.
- 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 a reason to add PTP?”. Answered by the PTP-vs-NTP path-
selection rule in
the capabilities companion
- the env-prep checklist in
the tasks companion.
- “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
the capabilities companion
- the PTP-config step in
the tasks companion.
- “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
the capabilities companion
- the host-follower step in
the tasks companion.
- “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
the capabilities companion
- the layered debug ladder in
the tasks companion.
- “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
the capabilities companion
- the pairing step in
the tasks companion, which routes the
Rivermax side to
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, profile, or
interface?” — worked example: “container green but the
ports-state output never advances past LISTENING”. Answered by
the four-axis-mismatch rule in
the capabilities companion
- the layered ladder in
the tasks companion.
Audience
This skill serves external operators and platform teams who deploy
the DOCA Firefly Service container to provide PTP-grade time
synchronization to time-sensitive workloads on BlueField + the host
behind it. Concretely: people running the Firefly container on
BlueField Arm, choosing its PTP role / profile / domain / interface
from the public Firefly guide, wiring the host-side follower (chrony
with the PHC source, or ptp4l reading the PHC) so the host clock
tracks the BlueField PHC, and validating the end-to-end discipline
before scaling a Rivermax, 5G UPF, financial-trading, or distributed-
database workload that depends on it.
It is not for NVIDIA developers contributing to Firefly itself,
nor a programming guide for building on DOCA libraries (see
doca-programming-guide/SKILL.md). Firefly is a service: the
operator runs a container and configures PTP; there is no
libfirefly.so to link against.
Path selection up front. Use Firefly when sub-microsecond,
PTP-grade time precision is required on BlueField AND the host (SMPTE
ST 2110 broadcast workloads layered on Rivermax, 5G UPF time
requirements, distributed systems that need PTP-grade time, anything
where NTP / chrony jitter is not tight enough). Do not reach for
Firefly when NTP / chrony already meets the workload's time-precision
budget, when no PTP-aware switching / boundary-clock infrastructure
exists in the path, or when pure software-side time precision is
sufficient — in those cases the correct answer is to keep the host's
existing chrony / NTP setup and route the agent away from Firefly,
not to deploy it speculatively.
When to load this skill
Load this skill when the user is doing hands-on Firefly deployment
work on a BlueField where DOCA is already installed. Concretely:
- Deciding whether Firefly is the right answer for the user's
time-precision requirement (vs. keeping NTP / chrony on the host).
- Deploying the Firefly container on BlueField Arm — choosing image
source per the public DOCA Firefly Service Guide, mounting the
Firefly config, and starting / stopping the container.
- Choosing the four PTP configuration axes — PTP role (master /
slave / boundary clock / transparent clock), profile (the
PROFILE env var accepts EXACTLY default / media /
telco-l2 / custom per the shipped doca_firefly.yaml;
these map onto industry PTP profile names: default → IEEE 1588,
media → SMPTE 2059-2, telco-l2 → G.8275.1 only (G.8275.2
corresponds to the separate telco-l3 config, reached via
custom) — do NOT put the industry names directly into the env
var), domain number,
network interface — for the user's deployment.
- Wiring the host-side follower so the host clock tracks the
BlueField PHC (chrony with the PHC source, or
ptp4l /
phc2sys reading the PHC) — without this step the host clock
does NOT follow the Firefly-disciplined PHC, regardless of how
cleanly Firefly comes up.
- Pairing Firefly with a time-sensitive consumer workload (Rivermax
SMPTE, 5G UPF, finance, distributed databases) and validating
the end-to-end discipline.
- Reading the Firefly container's logs, the PHC offset, the
ports-state output, or any other documented observability surface
to confirm PTP is locked.
- Debugging a Firefly deployment where the container is healthy but
PTP is not syncing, or PTP is syncing but the host clock is not
following, or sync is up but jitter is past spec.
Do not load this skill for general DOCA orientation, install of
DOCA itself, library-API questions, or non-PTP time topics. For
those, route via
doca-public-knowledge-map/SKILL.md,
doca-setup/SKILL.md, or the matching
libs/<library> skill.
What this skill provides
This is a thin loader. Substantive material lives in two
companion files:
- the capabilities companion — Firefly's architecture (container that drives
the BlueField PHC and speaks PTP on the wire), the four PTP
configuration axes (role / profile / domain / interface, with
transport as a fifth knob), the deployment shape (container on
BlueField Arm per the public Container Deployment Guide), the
pairing surface (Rivermax + host-side time-sync follower), the
observability surface (container logs + PHC offset + ports state),
the error taxonomy (four-axis-mismatch / host-follower / PTP-aware-
path / container-runtime), and the safety policy (PTP-vs-NTP path
selection, END-TO-END discipline, smoke-before-scale).
- the tasks companion — step-by-step workflows for the in-scope Firefly
verbs:
configure, build, modify, run, test, debug,
plus a Deferred task verbs block routing out-of-scope questions
and a Command appendix of recurring commands.
The skill assumes a BlueField where DOCA is already installed and
the operator has the privileges the public Firefly Service Guide
expects to pull, run, and configure containers on BlueField Arm.
It does not cover installing DOCA — that path goes through
doca-setup/SKILL.md.
What this skill deliberately does not ship
This skill is agent guidance, not a templates or sample-config
bundle. To keep the boundary clean, it deliberately does not contain —
and pull requests should not add:
- Pre-baked Firefly configuration files (full PTP config blocks,
ready-to-run role / profile / domain bundles) intended to be
copy-pasted into production. PTP configuration is deployment-
specific (per the user's profile, domain plan, interface naming,
and upstream PTP topology); the safe answer for an external
operator is to derive the config from the public Firefly Service
Guide against their own deployment. The agent's job is to
prescribe the procedure and the four-axis decision, not to
ship a config the user might run unmodified.
- Container image names, tags, or registry paths. The
authoritative image source is the public DOCA Firefly Service
Guide reachable through
doca-public-knowledge-map ## DOCA services (doca-public-knowledge-map/SKILL.md#doca-services);
Firefly's image tag is version-bound and changes between DOCA
releases. Inventing or memorizing a tag is the canonical
hallucination failure mode for a service skill.
- Host-side chrony stanzas or
ptp4l / phc2sys config files.
Those are host-environment-specific and live on the host, not
inside the Firefly container. The skill names that the
host-side follower must be wired and what its source must be
(the BlueField PHC); the chrony / ptp4l config bodies belong
to the host operator and to upstream Linux PTP documentation.
- A
samples/, templates/, or reference/ subtree of any
kind. A mock or incomplete artifact in this skill's tree, even
one labeled “reference”, is misleading: operators will read it
as production-ready.
Loading order
- Read this skill first to confirm the user's question is in
scope and that Firefly is the right answer at all (vs. keeping
NTP / chrony on the host).
- For Firefly's deployment shape, the four PTP configuration
axes, the Rivermax + host-follower pairing surface, the error
taxonomy, the observability surface, and the END-TO-END safety
policy, see the capabilities companion.
- For step-by-step workflows — configure, build, modify, run,
test, debug — see the tasks companion.
Related skills
doca-public-knowledge-map/SKILL.md
— the routing table to the public DOCA Firefly Service Guide and
the rest of the public DOCA documentation set. The Firefly URL is
listed under
## DOCA services (doca-public-knowledge-map/SKILL.md#doca-services).
doca-setup/SKILL.md — env preparation and
install verification on the BlueField where the Firefly container
will run, including the I have no install yet path via the
public NGC DOCA container. This skill assumes its preconditions
are satisfied on BlueField Arm.
doca-version/SKILL.md — canonical DOCA
version-handling rules. Firefly's container tag is version-bound;
this skill's ## Version compatibility cross-links the four-way
match rule and adds the container-tag-lags-host-package overlay.
doca-structured-tools-contract/SKILL.md —
the bundle's structured-tools precedence rule (detect / prefer /
fall back / report). The Command appendix in the tasks companion
honors this contract.
doca-programming-guide/SKILL.md
— general DOCA patterns. Firefly is service-shaped not library-
shaped, so the build / modify / first-app pattern there does not
apply directly, but the cross-library debug discipline (frontend-
before-backend, env-before-program) remains useful when Firefly
reports an error that originated in the container runtime or in
a DOCA library it called.
doca-rmax/SKILL.md — the canonical
paired workload. SMPTE ST 2110 Rivermax streams depend on a
Firefly-disciplined PHC; Firefly is the time-source side and
Rivermax is the timing-precise data-plane side. The two skills
load together for any broadcast-style deployment, and they do
NOT collapse into one another — Firefly does not stream media;
Rivermax does not discipline the PHC.
doca-dms/SKILL.md — sibling service skill. The
agent reading both skills should see the same service-skill shape
(container, BlueField Arm, deployment pattern, smoke-before-scale,
env preconditions, config schema) layered on top of a different
per-service domain (DMS = device management via gNMI / gNOI;
Firefly = time synchronization via PTP).
doca-debug/SKILL.md — the cross-cutting
debug ladder (install / version / build / link / runtime /
program / driver). Firefly-specific debug (PTP not syncing,
host clock not following, jitter past spec) overlays on top of
that ladder.
1---2license: Apache-2.03name: doca-firefly4description: >5 Use this skill when the user is operating the DOCA Firefly Service6 container on BlueField — picking the four PTP configuration axes (role7 / profile / domain / interface), wiring the BlueField PHC + host8 follower + consumer workload pairing, deciding whether PTP-grade time9 is even needed (vs. chrony / NTP), or debugging a Firefly deployment10 where PTP isn't syncing or the host clock isn't following. Trigger11 even when the user does not explicitly mention "DOCA Firefly" or "PTP"12 — typical implicit phrasings include "container green but PTP never13 advances past LISTENING", "Firefly says synced but the host clock14 still drifts", "sync acquired but offset is tens of microseconds", "my15 Rivermax SMPTE workload needs PTP", or "is chrony good enough". Refuse16 and route elsewhere for installing DOCA, host-side chrony / ptp4l17 config bodies, PTP topology / boundary-clock design, building DOCA18 apps that read the disciplined PHC, or other DOCA services (DMS,19 Flow-Inspector, HBN) — those belong to other skills.20metadata:21 source: https://skillmd.com/skills/nvidia/doca-firefly22 author: NVIDIA <doca-feedback@nvidia.com>23 kind: service24 doca_version: "3.5"25 tags:26 - doca27 - firefly28 - ptp29compatibility: >30 BlueField-Arm-only DOCA service container; pulled from NVIDIA NGC and31 started under the BlueField OS container runtime. Host-side install is32 irrelevant. Requires a reachable PTP master (or runs as the master33 itself) and a PTP-aware network path; the host-side time follower34 (chrony / ptp4l / phc2sys reading the BlueField PHC) is also35 operator-owned. The validation steps require a live DOCA install.36---3738# DOCA Firefly Service3940## Examples4142- **“Container green but PTP never advances past LISTENING.”**43 — this is in scope. Check role / profile / domain /44 interface before changing host chrony.45- **“Firefly says synced but the host clock still drifts.”** —46 wire the BlueField PHC follower; Firefly does not replace47 host-side chrony / ptp4l bodies.4849## Instructions5051Follow Loading order below. Open the tasks companion for configure /52sync / debug. Open the capabilities companion for PTP axes.53Do not open every companion file.5455> **Subsystem inventory.**56> DOCA Firefly is NOT just "a PTP daemon." The shipped57> `doca_firefly.yaml` exposes **six** PTP-stack subsystems via58> environment variables, each with its own `*_STATE`,59> `*_CONFIG_FILE`, and (where relevant) `*_INTERFACE` /60> `*_DEVICE` knobs (the count is six because the PTP Monitor61> subsystem ships an internal `phc2sys` monitor client that is62> distinct from the standalone PHC2SYS subsystem — both ship in63> the same container image):64>65> 1. **PTP** (`PTP_STATE`, `PTP_INTERFACE`, `PTP_CONFIG_FILE`) —66> the `ptp4l` daemon (or master, depending on profile) that67> drives the BlueField PHC.68> 2. **PTP Monitor** (`MONITOR_STATE`, `MONITOR_CONFIG_FILE`,69> `MONITOR_CLIENT_TYPE`, `MONITOR_CLIENT_PHC2SYS_INTERFACE`,70> `MONITOR_CLIENT_CONNECTION_TIMEOUT`) — the monitor server +71> client surface; the **internal `phc2sys` monitor client**72> (`MONITOR_CLIENT_TYPE=phc2sys`) is a real subsystem inside73> Firefly, not just a host-side concern.74> 3. **PHC2SYS** (`PHC2SYS_STATE`, `PHC2SYS_ARGS`,75> `PHC2SYS_CONFIG_FILE`) — the **container-internal** `phc2sys`76> instance (not host-only).77> 4. **PPS** (`PPS_STATE`, `PPS_DEVICE`) — the Pulse-Per-Second78> output (with the additional `enable_while_running` and79> `do_nothing` states beyond plain enable/disable).80> 5. **SyncE** (`SYNCE_STATE`, `SYNCE_INTERFACE`,81> `SYNCE_CONFIG_FILE`) — Synchronous Ethernet frequency82> distribution; orthogonal to PTP.83> 6. **Firefly Servo** (`SERVO_STATE`, `SERVO_CONFIG_FILE`) —84> the proprietary Firefly servo loop (alternative to the85> upstream linuxptp servo).86>87> The valid `PROFILE` values are exactly **`default` / `media` /88> `telco-l2` / `custom`** (per `doca_firefly.yaml` comments) —89> the agent must not invent additional values. Subsystems configured90> as `defined_by_profile` are controlled by the active `PROFILE`.91>92> Configuration-override env vars follow the pattern93> `CONF_<SUBSYSTEM>_<section>_<key>` (e.g.94> `CONF_PTP_global_priority1`, `CONF_SYNCE_global_backend`,95> `CONF_MONITOR_global_telemetry_export`); these are the96> documented surface for overriding individual config keys97> without shipping a full custom config file.98>99> **Configuration hierarchy:** the mounted Firefly config file is100> mandatory and owns the primary PTP axes (role, profile, domain,101> interface, and transport). `CONF_<SUBSYSTEM>_<section>_<key>`102> variables are optional, documented per-key overrides of that file;103> they are not a second standalone configuration model.104105**Where to start:** This skill is for *operating* the DOCA Firefly106Service container, not for *linking against* a library. Firefly is107the **PTP / PHC2SYS / PPS / SyncE / Servo / Monitor** stack that108drives and observes the BlueField PTP Hardware Clock (PHC); it is109*not* the host-side time follower, *not* the consumer workload, and110*not* a programming surface. If the user wants to *deploy* the111container, open the tasks companion and start at112`## configure`. If the question is *what shape113of service is Firefly and what PTP roles / profiles does it speak*,114start at the capabilities companion. If DOCA is not installed115on the BlueField yet, route to116`doca-setup/SKILL.md` first. If the user's117real question is *“I have a Rivermax SMPTE workload and the docs say I118need PTP”*, the right pairing is this skill **plus**119`doca-rmax/SKILL.md` — Firefly disciplines120the PHC; Rivermax reads the disciplined time.121122## Example questions this skill answers well123124The CLASSES of Firefly questions this skill is built to answer, each125with one worked example. The class is the load-bearing piece; the126worked example is one instance.127128- **“Do I actually need Firefly, or is NTP / chrony good enough?”** —129 worked example: *“my distributed app is fine on chrony today; is130 there a reason to add PTP?”*. Answered by the PTP-vs-NTP path-131 selection rule in132 the capabilities companion133 + the env-prep checklist in134 the tasks companion.135- **“What four PTP configuration axes do I have to decide before136 starting the container?”** — worked example: *“a SMPTE ST 2110137 broadcast plant that wants Firefly in slave role on the wire-side138 port”*. Answered by the four-axis configuration table in139 the capabilities companion140 + the PTP-config step in141 the tasks companion.142- **“Firefly's container is running but the host's time isn't143 following — what did I miss?”** — worked example: *“`ptp4l` /144 Firefly says it's locked but `chronyc tracking` on the host shows145 drift”*. Answered by the END-TO-END time-sync discipline in146 the capabilities companion147 + the host-follower step in148 the tasks companion.149- **“PTP locks but the offset / jitter is way past spec — what's150 wrong with the path?”** — worked example: *“sync acquired but offset151 is in the tens of microseconds”*. Answered by the PTP-aware-path152 rule in153 the capabilities companion154 + the layered debug ladder in155 the tasks companion.156- **“How does Firefly pair with a Rivermax SMPTE workload?”** —157 worked example: *“SMPTE ST 2110 video sender that needs to be PTP-158 locked”*. Answered by the Rivermax-pairing rule in159 the capabilities companion160 + the pairing step in161 the tasks companion, which routes the162 Rivermax side to163 `doca-rmax/SKILL.md` and refuses to164 collapse the two services into one.165- **“My Firefly container starts but PTP never reaches166 `SLAVE` / `MASTER` state — was it role, domain, profile, or167 interface?”** — worked example: *“container green but the168 ports-state output never advances past `LISTENING`”*. Answered by169 the four-axis-mismatch rule in170 the capabilities companion171 + the layered ladder in172 the tasks companion.173174## Audience175176This skill serves **external operators and platform teams who deploy177the DOCA Firefly Service container** to provide PTP-grade time178synchronization to time-sensitive workloads on BlueField + the host179behind it. Concretely: people running the Firefly container on180BlueField Arm, choosing its PTP role / profile / domain / interface181from the public Firefly guide, wiring the host-side follower (chrony182with the PHC source, or `ptp4l` reading the PHC) so the host clock183tracks the BlueField PHC, and validating the end-to-end discipline184 before scaling a Rivermax, 5G UPF, financial-trading, or distributed-185database workload that depends on it.186187It is **not** for NVIDIA developers contributing to Firefly itself,188nor a programming guide for building on DOCA libraries (see189`doca-programming-guide/SKILL.md`). Firefly is a **service**: the190operator runs a container and configures PTP; there is no191`libfirefly.so` to link against.192193**Path selection up front.** Use Firefly when sub-microsecond,194PTP-grade time precision is required on BlueField AND the host (SMPTE195ST 2110 broadcast workloads layered on Rivermax, 5G UPF time196requirements, distributed systems that need PTP-grade time, anything197where NTP / chrony jitter is not tight enough). Do **not** reach for198Firefly when NTP / chrony already meets the workload's time-precision199budget, when no PTP-aware switching / boundary-clock infrastructure200exists in the path, or when pure software-side time precision is201sufficient — in those cases the correct answer is to keep the host's202existing chrony / NTP setup and route the agent away from Firefly,203not to deploy it speculatively.204205## When to load this skill206207Load this skill when the user is doing **hands-on Firefly deployment208work** on a BlueField where DOCA is already installed. Concretely:209210- Deciding *whether* Firefly is the right answer for the user's211 time-precision requirement (vs. keeping NTP / chrony on the host).212- Deploying the Firefly container on BlueField Arm — choosing image213 source per the public DOCA Firefly Service Guide, mounting the214 Firefly config, and starting / stopping the container.215- Choosing the four PTP configuration axes — PTP role (master /216 slave / boundary clock / transparent clock), profile (the217 `PROFILE` env var accepts EXACTLY `default` / `media` /218 `telco-l2` / `custom` per the shipped `doca_firefly.yaml`;219 these map onto industry PTP profile names: `default` → IEEE 1588,220 `media` → SMPTE 2059-2, `telco-l2` → G.8275.1 only (G.8275.2221 corresponds to the separate `telco-l3` config, reached via222 `custom`) — do NOT put the industry names directly into the env223 var), domain number,224 network interface — for the user's deployment.225- Wiring the host-side follower so the host clock tracks the226 BlueField PHC (chrony with the PHC source, or `ptp4l` /227 `phc2sys` reading the PHC) — without this step the host clock228 does NOT follow the Firefly-disciplined PHC, regardless of how229 cleanly Firefly comes up.230- Pairing Firefly with a time-sensitive consumer workload (Rivermax231 SMPTE, 5G UPF, finance, distributed databases) and validating232 the end-to-end discipline.233- Reading the Firefly container's logs, the PHC offset, the234 ports-state output, or any other documented observability surface235 to confirm PTP is locked.236- Debugging a Firefly deployment where the container is healthy but237 PTP is not syncing, or PTP is syncing but the host clock is not238 following, or sync is up but jitter is past spec.239240Do **not** load this skill for general DOCA orientation, install of241DOCA itself, library-API questions, or non-PTP time topics. For242those, route via243`doca-public-knowledge-map/SKILL.md`,244`doca-setup/SKILL.md`, or the matching245`libs/<library>` skill.246247## What this skill provides248249This is a **thin loader**. Substantive material lives in two250companion files:251252- the capabilities companion — Firefly's architecture (container that drives253 the BlueField PHC and speaks PTP on the wire), the four PTP254 configuration axes (role / profile / domain / interface, with255 transport as a fifth knob), the deployment shape (container on256 BlueField Arm per the public Container Deployment Guide), the257 pairing surface (Rivermax + host-side time-sync follower), the258 observability surface (container logs + PHC offset + ports state),259 the error taxonomy (four-axis-mismatch / host-follower / PTP-aware-260 path / container-runtime), and the safety policy (PTP-vs-NTP path261 selection, END-TO-END discipline, smoke-before-scale).262- the tasks companion — step-by-step workflows for the in-scope Firefly263 verbs: `configure`, `build`, `modify`, `run`, `test`, `debug`,264 plus a `Deferred task verbs` block routing out-of-scope questions265 and a `Command appendix` of recurring commands.266267The skill assumes a BlueField where DOCA is already installed and268the operator has the privileges the public Firefly Service Guide269expects to pull, run, and configure containers on BlueField Arm.270It does not cover installing DOCA — that path goes through271`doca-setup/SKILL.md`.272273## What this skill deliberately does not ship274275This skill is **agent guidance**, not a templates or sample-config276bundle. To keep the boundary clean, it deliberately does not contain —277and pull requests should not add:278279- **Pre-baked Firefly configuration files** (full PTP config blocks,280 ready-to-run role / profile / domain bundles) intended to be281 copy-pasted into production. PTP configuration is deployment-282 specific (per the user's profile, domain plan, interface naming,283 and upstream PTP topology); the safe answer for an external284 operator is to derive the config from the public Firefly Service285 Guide against their own deployment. The agent's job is to286 prescribe the *procedure* and the *four-axis decision*, not to287 ship a config the user might run unmodified.288- **Container image names, tags, or registry paths.** The289 authoritative image source is the public DOCA Firefly Service290 Guide reachable through291 `doca-public-knowledge-map ## DOCA services` (`doca-public-knowledge-map/SKILL.md#doca-services`);292 Firefly's image tag is version-bound and changes between DOCA293 releases. Inventing or memorizing a tag is the canonical294 hallucination failure mode for a service skill.295- **Host-side chrony stanzas or `ptp4l` / `phc2sys` config files.**296 Those are host-environment-specific and live on the host, not297 inside the Firefly container. The skill names *that* the298 host-side follower must be wired and *what its source must be*299 (the BlueField PHC); the chrony / `ptp4l` config bodies belong300 to the host operator and to upstream Linux PTP documentation.301- **A `samples/`, `templates/`, or `reference/` subtree** of any302 kind. A mock or incomplete artifact in this skill's tree, even303 one labeled *“reference”*, is misleading: operators will read it304 as production-ready.305306## Loading order3073081. Read this skill first to confirm the user's question is in309 scope **and** that Firefly is the right answer at all (vs. keeping310 NTP / chrony on the host).3112. **For Firefly's deployment shape, the four PTP configuration312 axes, the Rivermax + host-follower pairing surface, the error313 taxonomy, the observability surface, and the END-TO-END safety314 policy, see the capabilities companion.**3153. **For step-by-step workflows — configure, build, modify, run,316 test, debug — see the tasks companion.**317318## Related skills319320- `doca-public-knowledge-map/SKILL.md`321 — the routing table to the public DOCA Firefly Service Guide and322 the rest of the public DOCA documentation set. The Firefly URL is323 listed under324 `## DOCA services` (`doca-public-knowledge-map/SKILL.md#doca-services`).325- `doca-setup/SKILL.md` — env preparation and326 install verification on the BlueField where the Firefly container327 will run, including the *I have no install yet* path via the328 public NGC DOCA container. This skill assumes its preconditions329 are satisfied on BlueField Arm.330- `doca-version/SKILL.md` — canonical DOCA331 version-handling rules. Firefly's container tag is version-bound;332 this skill's `## Version compatibility` cross-links the four-way333 match rule and adds the container-tag-lags-host-package overlay.334- `doca-structured-tools-contract/SKILL.md` —335 the bundle's structured-tools precedence rule (detect / prefer /336 fall back / report). The Command appendix in the tasks companion337 honors this contract.338- `doca-programming-guide/SKILL.md`339 — general DOCA patterns. Firefly is service-shaped not library-340 shaped, so the build / modify / first-app pattern there does not341 apply directly, but the cross-library debug discipline (frontend-342 before-backend, env-before-program) remains useful when Firefly343 reports an error that originated in the container runtime or in344 a DOCA library it called.345- `doca-rmax/SKILL.md` — the canonical346 paired workload. SMPTE ST 2110 Rivermax streams depend on a347 Firefly-disciplined PHC; Firefly is the time-source side and348 Rivermax is the timing-precise data-plane side. The two skills349 load together for any broadcast-style deployment, and they do350 NOT collapse into one another — Firefly does not stream media;351 Rivermax does not discipline the PHC.352- `doca-dms/SKILL.md` — sibling service skill. The353 agent reading both skills should see the same service-skill shape354 (container, BlueField Arm, deployment pattern, smoke-before-scale,355 env preconditions, config schema) layered on top of a different356 per-service domain (DMS = device management via gNMI / gNOI;357 Firefly = time synchronization via PTP).358- `doca-debug/SKILL.md` — the cross-cutting359 debug ladder (install / version / build / link / runtime /360 program / driver). Firefly-specific debug (PTP not syncing,361 host clock not following, jitter past spec) overlays on top of362 that ladder.