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 and start at ## configure. If the question is what shape of service is Firefly and what PTP roles / profiles does it speak, start at CAPABILITIES.md. If DOCA is not installed on the BlueField yet, route to doca-setup 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 — 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
  • the env-prep checklist in 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
  • the PTP-config step in 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
  • the host-follower step in 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
  • the layered debug ladder in 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
  • the pairing step in TASKS.md ## configure, which routes the Rivermax side to doca-rmax 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 CAPABILITIES.md ## Error taxonomy
  • the layered ladder in TASKS.md ## debug.

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, and it is not a programming guide for building applications on top of DOCA libraries (that is doca-programming-guide plus the matching libs/<library> skill). Firefly is a service, not a library: the operator runs a container and configures PTP via the documented config surface; they do not link against a libfirefly.so to write their own program.

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 services/firefly/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, doca-setup, or the matching libs/<library> skill.