doca-pcc-ztr-rttcc-algo

DOCA PCC ZTR RTTCC Algorithm

Where to start: This skill assumes DOCA is already installed, the user's BlueField has a DPA processor that the host can see through DOCA (a BlueField-3-generation device per the README), the BlueField firmware has the custom-PCC slot enabled, the DPACC compiler is installed at a matched version per the DOCA Compatibility Policy, and the user is doing hands-on deployment of the DOCA-shipped ZTR RTTCC reference algorithm on a BlueField port that already carries RoCE-v2 traffic — i.e. either deploying it as the no-config-required baseline, tuning its documented parameters, or evaluating it against a custom algorithm the user intends to write. Open TASKS.md if the user wants to do something (install / configure / build / modify / run / test / debug / use); open CAPABILITIES.md when the question is what does the algorithm express, what are its variants and parameters, what does it ship vs not ship. If the user has not installed DOCA yet, route to doca-setup first; if the user has not stood up the host-side doca-pcc framework yet, route to doca-pcc first (this algorithm is a library consumed by the PCC framework, not a standalone program); if the user only wants to inspect PCC counters at runtime without changing the running algorithm, route to doca-pcc-counters; if the user wants to write their own algorithm from scratch, that is the doca-pcc library plus the public PCC programming guide — this skill is for the shipped reference algorithm specifically.

Example questions this skill answers well

The CLASSES of ZTR RTTCC questions this skill is built to answer, each with one worked example. The agent should treat the class as the load-bearing piece — the worked example is a single instance.

• "Is the ZTR RTTCC reference algorithm the right baseline for my deployment, or should I write a custom algorithm?" — worked example: "I have a BlueField-3 carrying production RoCE-v2 traffic from a GPU cluster; is the shipped algorithm a fine default or do I need custom logic?". Answered by the decision rule in CAPABILITIES.md ## Capabilities and modes ("when to use the reference vs custom") + the env preconditions in TASKS.md ## install.
• "How do I wire the shipped algorithm into the DOCA PCC application that's already running on my host?" — worked example: "/opt/mellanox/doca/applications/pcc is already building from sample sources; what do I change so the user algo callback dispatches to doca_pcc_dev_ztr_rttcc_algo under a chosen algo slot?". Answered by the integration sequence in CAPABILITIES.md ## Capabilities and modes
  • the in-place edits in TASKS.md ## modify.
• "Which variant of the algorithm am I getting — vanilla RTT-CC, path-migration mode, RX-rate mode, multipath, multipath with credits, window-probeless?" — worked example: "the shipped library exposes one public symbol doca_pcc_dev_ztr_rttcc_algo but the device- side source ships several variants; how do I know which one I get and how do I pick another?". Answered by the variants table in CAPABILITIES.md ## Capabilities and modes.
• "How do I confirm the algorithm is actually modulating my RDMA / RoCE traffic, and not just loading?" — worked example: "I followed the integration steps; the application starts; how do I know the algorithm is shaping flows under load?". Answered by the observability surface in CAPABILITIES.md ## Observability
  • the counter-watch loop in TASKS.md ## test which routes to doca-pcc-counters.
• "Which tunables does the algorithm expose, and how do I change them from the host without rebuilding the DPA-side image?" — worked example: "my workload is more latency-sensitive than the default profile assumes — which parameter knob do I adjust?". Answered by the parameter surface in CAPABILITIES.md ## Capabilities and modes
  • the doca_pcc_dev_set_ztr_rttcc_params workflow in TASKS.md ## use.
• "What does this DOCA_PCC_DEV_STATUS_FAIL or DOCA_ERROR_* from a doca_pcc_dev_ztr_rttcc_* call mean and which layer caused it?" — worked example: "my init callback returns DOCA_PCC_DEV_STATUS_FAIL on first launch". Answered by the algorithm overlay on the host-side PCC taxonomy in CAPABILITIES.md ## Error taxonomy
  • the layered ladder in TASKS.md ## debug that escalates through doca-pcc and doca-debug.

Audience

This skill serves external developers operating a BlueField-3-class DPU who want to deploy NVIDIA's shipped reference PCC algorithm on RoCE-v2 traffic, OR who are evaluating it against a custom algorithm they intend to write. The reference algorithm is zero-touch by design — the no-config-required baseline — and the canonical use case is dropping it onto a port and confirming it shapes flows correctly under congestion. It is not for NVIDIA developers contributing to the algorithm itself, nor for users who want general PCC programming theory (route via the public DOCA PCC programming guide), nor for users who only want to inspect PCC counters (route to doca-pcc-counters).

Language scope. The algorithm ships as a DPA-side library (pkg-config module doca-pcc-ztr-rttcc-algo) plus a public header doca_pcc_dev_ztr_rttcc_algo.h that DPA-side translation units include. The shipped algorithm binary is the static library libdoca_pcc_ztr_rttcc_algo_dev.a per the README; the device-side translation unit that consumes it is C and is compiled by DPACC. The host-side that drives the PCC context comes from doca-pcc; this library does NOT add a host-side surface beyond the host-side helpers (also shipped as libdoca_pcc_ztr_rttcc_algo.{a,so} per the README) that the doca-pcc framework links. Other-language host-side wrappers around doca-pcc can drive this algorithm through the same lifecycle described in doca-pcc; the DPA-side integration always stays C-via-DPACC.

When to load this skill

Load this skill when the user is doing hands-on deployment, tuning, or evaluation of the DOCA-shipped ZTR RTTCC reference algorithm on a BlueField port carrying RoCE-v2 traffic, in any host language plus the DPA-side translation unit built by dpacc. Concretely:

• Deciding whether the shipped algorithm is the right baseline for the user's RoCE-v2 workload, or whether the user needs a custom algorithm.
• Wiring the algorithm into the DOCA PCC sample application by patching the user-algo / user-init / user-set-algo-params callbacks per the steps the shipped README documents.
• Picking which of the algorithm's documented variants (vanilla, path-migration, RX-rate, RX-rate + PM, multipath, multipath + credits, window-probeless) matches the user's intent — and surfacing that the public surface only ships one symbol (doca_pcc_dev_ztr_rttcc_algo); the variants live in the DPA-side source the user compiles against.
• Tuning the host-set parameters the algorithm exposes (per the parameter list in doca_pcc_dev_ztr_rttcc_algo.h and the shipped doca_pcc_dev_set_ztr_rttcc_params).
• Observing whether the running algorithm is actually modulating RoCE-v2 flows under load (route to doca-pcc-counters for the read-only inspection side).
• Deciding when to replace the shipped algorithm with a custom one because latency target, fairness policy, or convergence behavior requirements diverge from what the reference provides.

Do not load this skill for general DOCA orientation; for the host-side doca-pcc lifecycle (route to doca-pcc); for writing a custom algorithm from scratch (route to doca-pcc and the public PCC programming guide via doca-public-knowledge-map); for read-only PCC counter inspection (route to doca-pcc-counters); or for the default firmware-shipped PCC algorithms that predate Programmable Congestion Control entirely (no host-side code, no DPACC compile — that is a firmware-only path routed via doca-public-knowledge-map).

What this skill provides

This is a thin loader. The body keeps only the orientation needed to pick the right next file. The substantive algorithm-specific material lives in two companion files:

• CAPABILITIES.md — what the shipped ZTR RTTCC algorithm expresses on this version + this BlueField generation + this firmware: the public DPA-side API surface (doca_pcc_dev_ztr_rttcc_init, doca_pcc_dev_ztr_rttcc_algo, doca_pcc_dev_set_ztr_rttcc_params, doca_pcc_dev_ztr_rttcc_get_param_num, doca_pcc_dev_ztr_rttcc_get_counter_num, doca_pcc_dev_ztr_rttcc_get_num_of_histograms), the documented variants (vanilla / path-migration / RX-rate / multipath / window-probeless — pick one at DPA-side compile time), the relationship to the host-side doca-pcc framework (this is an algorithm body the framework loads), the relationship to the doca-pcc-counters tool (which is the canonical inspection surface), the algorithm's parameter and counter surface (RTT-based congestion signal, per-feature parameter blocks), the error taxonomy in DOCA_PCC_DEV_STATUS_OK / _FAIL, and the safety policy.
• TASKS.md — step-by-step workflows for the in-scope algorithm verbs: install, configure, build, modify, run, test, debug, use. Plus a Deferred task verbs block that points out-of-scope questions at the right next skill.

The skill assumes DOCA + the DPACC compiler + the doca-pcc host-side framework are already installed; the BlueField is a generation that exposes the DPA processor (the algorithm runs on the DPA); the BlueField firmware has the custom-PCC slot enabled (inherited from doca-pcc CAPABILITIES.md ## Safety policy); and the BlueField port the algorithm will modulate has RoCE-v2 traffic actually flowing on it (the algorithm modulates existing RDMA / RoCE traffic — without traffic, there is nothing for it to do).

What this skill deliberately does not ship

This skill is agent guidance, not a samples or templates bundle. To keep the boundary clean, it deliberately does not contain — and pull requests should not add:

• The algorithm body itself, in any language. The shipped algorithm is the static library libdoca_pcc_ztr_rttcc_algo_dev.a (plus the host-side helpers) installed by the matching DOCA host package per the README. The agent's job is to route the user to the installed library and header (doca_pcc_dev_ztr_rttcc_algo.h) and to prescribe the in-place edits documented in the README on the shipped DOCA PCC application source, not to author the algorithm.
• A standalone PCC application. The DOCA PCC application that hosts this algorithm is the shipped C sample under /opt/mellanox/doca/applications/pcc/ (per the README). The agent's job is to prescribe the minimum-diff modifications the README documents and to walk the user through the rebuild — not to author a parallel application.
• A description of every internal variant's behavior. The DPA-side source ships several variants (vanilla, path-migration, RX-rate, multipath, multipath + credits, window-probeless). The agent names the variant set, says which one is reachable via the public symbol on this install, and routes algorithm-design questions to the public PCC programming guide via doca-public-knowledge-map. It does not redefine each variant's mathematical behavior.
• A specific congestion-control algorithm tutorial. Congestion-control theory, RoCE-v2 fairness analysis, workload-specific tuning — out of scope. Route to the user's own domain expertise and to the public DOCA PCC guide.

Loading order

1. Read this SKILL.md first to confirm the user's question is in scope (deployment / tuning / evaluation of the shipped reference algorithm, not algorithm design from scratch and not read-only counter inspection).
2. For the algorithm capability matrix, the public DPA-side API surface, the variant set, the parameter and counter surface, the host-side doca-pcc framework relationship, the doca-pcc-counters inspection-side relationship, the error taxonomy, the observability surface, and the safety policy, see CAPABILITIES.md.
3. For step-by-step workflows — install, configure, build, modify, run, test, debug, use — see TASKS.md.

Both companion files cross-link to each other, doca-pcc for the host-side PCC lifecycle that loads this algorithm, doca-pcc-counters for the read-only counter-inspection side of validating that the algorithm is modulating traffic, doca-dpa for the DPA-side two-side-program model and the DPACC compiler discipline, doca-version for the canonical DOCA version-handling rules (with the DPACC overlay inherited from doca-dpa and doca-pcc), and doca-public-knowledge-map whenever the right answer is "look it up in the public DOCA PCC programming guide or the on-disk install layout".

Related skills

• doca-pcc — the host-side PCC control library. This algorithm is loaded INTO a doca_pcc context that doca-pcc stands up; the host-side lifecycle (doca_pcc create / configure / start / stop / destroy, the algorithm image doca_pcc_app, the attach-to-port semantics) is owned by doca-pcc. This skill prescribes only the DPA-side algorithm integration on top.
• doca-pcc-counters — the read-only diagnostic CLI for PCC counters at the port. The canonical "is the algorithm actually modulating traffic" check goes through the counter tool; this skill names what counters the algorithm emits (CNP / NACK / AI / HAI / decrement / RTT-band counters per the public header) and routes the inspection workflow to the tool skill.
• doca-dpa — the host-side DPA control library. The algorithm runs on the DPA, compiled by DPACC; the two-side-program rule and the DOCA-and-DPACC version-match overlay inherited from here apply.
• doca-public-knowledge-map — the routing table for every public DOCA documentation source (the DOCA PCC programming guide at https://docs.nvidia.com/doca/sdk/doca-pcc/index.html; the DOCA PCC application guide; the DOCA Compatibility Policy) and the on-disk layout of an installed DOCA package.
• doca-setup — env preparation, install verification, DPACC compiler install / verification, BlueField firmware configuration (including the custom-PCC slot enable), and the I have no install yet path with the public NGC DOCA container. This skill assumes its preconditions are satisfied AND that DPACC is installed at a version that matches DOCA AND that the firmware- level custom-PCC slot is enabled.
• doca-version — canonical DOCA version-handling rules. This skill's ## Version compatibility cross-links the four-way match rule plus the DOCA-and-DPACC overlay inherited from doca-pcc.
• doca-structured-tools-contract — the bundle's structured-tools precedence rule (detect / prefer / fall back / report). The Command appendix in TASKS.md honors this contract.
• doca-programming-guide — general DOCA programming patterns. This skill layers algorithm-specific overlays on top of the universal build, modify-a-shipped-sample, and Core lifecycle patterns.
• doca-debug — cross-cutting debug ladder. Algorithm-specific debug (the algorithm loaded but counters do not move; the algorithm fails to initialize; the algorithm modulates traffic too aggressively / too gently for the workload) overlays on top of that ladder.
• doca-hardware-safety — cross-cutting hardware-safety meta-policy. Because the algorithm modulates production RoCE-v2 flows on a BlueField port, the meta-policy's pre-flight inventory, replica-first, and rollback rules apply via this skill's ## Safety policy overlay.