/doca-pcc-ztr-rttcc-algo

license: Apache-2.0
name: doca-pcc-ztr-rttcc-algo
description: >
  Use this skill when the user is doing hands-on deployment, tuning,
  or evaluation of the DOCA-shipped Zero-Touch RoCE RTT-based
  Congestion Control (ZTR RTTCC) reference algorithm on a BlueField-3
  DPA — wiring `doca_pcc_dev_ztr_rttcc_algo` into the shipped DOCA
  PCC sample, picking a variant (vanilla / PM / RX-rate / multipath /
  window-probeless) at DPACC build time, tuning host-set parameters,
  or diagnosing `DOCA_PCC_DEV_STATUS_FAIL` from the algorithm.
  Trigger even when the user does not say 'DOCA PCC' or 'ZTR RTTCC' —
  typical implicit phrasings: 'my RoCE-v2 flows aren't being
  throttled', 'PCC sample isn't dispatching to my algo', 'how do I
  pick the multipath PCC variant', 'set-params returns fail',
  'algorithm loaded but counters are flat', or 'do I need a custom
  CC algorithm on BF3'. Refuse and route elsewhere for writing a
  custom PCC algorithm from scratch, read-only PCC counter
  inspection, the host-side `doca-pcc` lifecycle, or firmware-only
  pre-Programmable PCC — those belong to other skills.
metadata:
  kind: library
compatibility: >
  Requires DOCA SDK installed at /opt/mellanox/doca on Linux (Ubuntu
  22.04/24.04 or RHEL/SLES) with a BlueField-3 DPU exposing the DPA
  processor, the firmware custom-PCC slot enabled, a matched-version
  DPACC compiler, and live RoCE-v2 traffic on the attached port.
  Reads `pkg-config doca-pcc-ztr-rttcc-algo` and inspects
  /opt/mellanox/doca/{lib,include,applications/pcc}.

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`](TASKS.md) if the user wants to *do* something (install / configure / build / modify / run / test / debug / use); open [`CAPABILITIES.md`](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`](../../doca-setup/SKILL.md) first; if the user has not stood up the host-side `doca-pcc` framework yet, route to [`doca-pcc`](../doca-pcc/SKILL.md) 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`](../../tools/doca-pcc-counters/SKILL.md); 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`](CAPABILITIES.md#capabilities-and-modes) ("when to use the reference vs custom") + the env preconditions in [`TASKS.md ## install`](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`](CAPABILITIES.md#capabilities-and-modes)

• the in-place edits in

[`TASKS.md ## modify`](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`](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`](CAPABILITIES.md#observability)

• the counter-watch loop in

[`TASKS.md ## test`](TASKS.md#test) which routes to [`doca-pcc-counters`](../../tools/doca-pcc-counters/SKILL.md).

• **"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`](CAPABILITIES.md#capabilities-and-modes)

• the `doca_pcc_dev_set_ztr_rttcc_params` workflow in

[`TASKS.m