/doca-argp

DOCA Arg Parser capabilities, version overlay, errors, observability, safety

Where to start: Pick the H2 anchor that matches your question (param model / parameter types / standard CLI surface / JSON config / version / errors / safety) and read that section end-to-end. The tables in each section are the load-bearing content; the prose around them is interpretation.

Read this file when the loader sent you here from SKILL.md. For the how of executing each pattern (the verbs configure / build / modify / run / test / debug), jump to TASKS.md. For the canonical DOCA version-handling rules that this skill layers an Arg-Parser overlay on top of, see doca-version.

Pattern overview

Every Arg Parser question this skill teaches resolves into one of FIVE patterns. The patterns are CLASSES — they apply across every DOCA release and every sample, not just the worked examples shown.

Two cross-cutting rules that apply to every pattern above:

• The shipped sample's *_main.c is the canonical reference, every time. doca-argp does not ship its own dedicated sample tree; instead, every DOCA sample's *_main.c (under /opt/mellanox/doca/samples/<library>/<sample>/) is a working, version-matched Arg Parser usage. Quote the installed file, not a remembered API shape.
• The standard CLI surface is the user's mental model, not a stylistic preference. When a user invokes any DOCA sample, they expect --device, --representor (or --rep-list), --json (-j), and --sdk-log-level to behave the same way as in the sibling samples. Adding a flag on top of that surface is fine; replacing the surface breaks the cross-sample mental model and is a regression.

Capabilities and modes

DOCA Arg Parser is a small, foundational CPU-side library. It has no hardware accelerator behind it, no DOCA Core context, and no progress engine — it owns parsing, not execution. On top of that small surface, it layers a param-registration lifecycle, a small parameter-type set, the shared DOCA standard flag surface, and the JSON-config file integration.

The Arg Parser lifecycle. Every consumer follows the same register-before-start order. The agent must not invent steps; the public surface is closed.

Parameter types. The full public enum doca_argp_type the Arg Parser exposes. Picking the right one is what makes argv validation and JSON-config validation Just Work. The enum has six real values (DOCA_ARGP_TYPE_STRING, DOCA_ARGP_TYPE_INT, DOCA_ARGP_TYPE_BOOLEAN, DOCA_ARGP_TYPE_DEVICE, DOCA_ARGP_TYPE_DEVICE_REP, DOCA_ARGP_TYPE_DOUBLE) — do not silently omit the latter three.

The standard DOCA CLI surface. Every shipped sample already registers these (via doca_argp_init and a small set of default params) so the user learns ONE CLI for all of DOCA. Modifications must preserve this surface.

JSON-config integration. The --json <path> flag (also short-form -j <path>; the long name is --json, NOT --json-config) is not optional cosmetic detail — shipped samples with non-trivial configurations expect operators to drive them from a file (the command line becomes unreadable past ~5 flags). The JSON keys match the registered long names; the JSON value types match the registered parameter types; an unknown JSON key fails with DOCA_ERROR_NOT_SUPPORTED (pedantic parsing) per ## Error taxonomy.

Path selection — when doca-argp is the right answer. This is a small library, but its scope is sharp. Walk this rule before recommending the Arg Parser path.

Version compatibility

For the canonical DOCA version-detection chain, the four-way match rule, NGC container semantics, and the headers-win-over-docs rule, see doca-version. The body lives there; this skill does not duplicate it.

The Arg-Parser-specific overlay is:

• Presence is the first check; version is the second. doca-argp is a small, foundational library — agents tend to assume it is always present. It is not always installed in every package profile. Use pkg-config --exists doca-argp for the presence check FIRST, then pkg-config --modversion doca-argp for the version. Per the cross-cutting rule in doca-version CAPABILITIES.md ## Observability, the build-time pkg-config value is the authority for "is this library available for me to link against?".
• doca-argp.pc and doca-common.pc must both match doca_caps --version at the four-way-match check (per doca-version CAPABILITIES.md ## Version compatibility). A common partial-install pattern after a DOCA upgrade is that doca-argp.pc lingers from the previous release; route to doca-version TASKS.md ## debug layer 2 before any Arg-Parser-layer diagnosis.
• Headers in $(pkg-config --variable=includedir doca-common) win over public docs. Per the headers-win-over-docs rule in doca-version, if a public Arg Parser doc page mentions a doca_argp_* symbol that is not in the installed doca_argp.h, the headers describe what this install can call; the docs describe what some release shipped. The agent must quote the headers, not the docs URL, when the two disagree.

Error taxonomy

Arg-Parser-specific overlays on the cross-library DOCA_ERROR_* taxonomy. The cross-library taxonomy itself lives in doca-programming-guide CAPABILITIES.md ## Error taxonomy; the rows below are the Arg Parser surface meaning that the agent must disambiguate before falling back to the cross-library response.

The agent's rule: never recommend a retry loop on a doca_argp_* DOCA_ERROR_*. Every row above is an authoring or operator mistake, not a transient state — the fix is to correct the call site, the registration, the JSON key, or the file path, not to retry.

Observability

The Arg Parser's observability surface is small but load-bearing: the program's own --help output (synthesized from the registered param descriptions) is what the operator reads, and DOCA Log is what the program emits at parse time.

Three primary signals the agent should reach for:

1. The --help output. Every Arg Parser instance auto-generates a --help listing from doca_argp_init's default standard flags plus every registered param's description. The agent should ask the user to run ./<binary> --help before any other debug step — if the new flag is not listed, registration never happened; if the standard flags are not listed, doca_argp_init was skipped.
2. The parsed-value callback fires. Each registered doca_argp_param's value-callback runs once per matched flag (argv or JSON-config). A param that registers cleanly but whose callback never fires means the operator never passed the flag — not that the library dropped it. Add a one-line log inside the callback before assuming a parser bug.
3. DOCA Log lines from the Arg Parser layer. Per the cross-cutting observability primitives (DOCA_LOG_LEVEL=trace, --sdk-log-level, the trace build flavor) in doca-debug CAPABILITIES.md ## Observability, the Arg Parser routes its own messages through DOCA Log; a trace-level run shows the per-param parse calls and the JSON-config file read.

For the install-tree observability (logger names, package layout) defer to doca-public-knowledge-map.

Safety policy

Overlay on the bundle-wide hardware-safety meta-policy. The rules below are this skill's per-artifact overlay on the cross-cutting rules in doca-hardware-safety CAPABILITIES.md ## Safety policy (specifically ### Per-artifact overlay pattern). When the two layers disagree, the stricter wins; when either layer says STOP, the agent stops.

The Arg Parser's safety surface is lower-stakes than most DOCA libraries for string, integer, boolean, and double parameters: that parsing runs in the user's process and holds no kernel-side resources. DOCA_ARGP_TYPE_DEVICE and DOCA_ARGP_TYPE_DEVICE_REP are different: the parser opens the selected doca_dev or doca_dev_rep handle and can fail on device visibility or permissions. Opening a handle is not itself a hardware-state mutation, but the agent must identify the target and surface those access failures. If the callback or downstream workflow uses that handle for a state change, load doca-hardware-safety and apply its stricter gate before that change.

The load-bearing safety rule is structural, not access-control shaped: when modifying a shipped DOCA sample's CLI, reuse the Arg Parser; do not replace it with getopt / argparse / hand-rolled parsing. The reasons this is a safety rule, not a stylistic preference:

• Cross-sample CLI consistency is a user contract. Operators of DOCA samples carry mental models across libraries (--device, --representor, --json / -j, --sdk-log-level behave the same in every sample). A modified sample that silently breaks that contract becomes a trap for operators and a debugging time-sink that looks like a library bug.
• --json <path> (-j <path>) is shared infrastructure (the long name is --json, NOT --json-config). Sample CI, sample documentation, and operator runbooks all assume the JSON-config path works. A hand-rolled parser drops the JSON path silently; --help still looks right; the failure surface is "my JSON file is ignored", which the operator has no obvious place to file against.
• Lifecycle violations are caught only when doca-argp owns parsing. The BAD_STATE / INVALID_VALUE / NOT_SUPPORTED / IO_FAILED ladder in ## Error taxonomy only fires when the program goes through doca_argp_* — a hand-rolled parser re-creates this ladder by accident, badly.

The narrow exception (path-selection rule in ## Capabilities and modes): when the program never calls a doca_* symbol at all, doca-argp is not the right tool — a language-native parser is — and pulling in libdoca-argp adds a build-time dependency for no agent or user benefit. The agent must distinguish "DOCA-using app modifying its CLI" (reuse mandatory) from "non-DOCA CLI tool" (language-native parser is correct).

Deferred topic boundaries

This skill scopes itself to the DOCA Arg Parser library. Adjacent topics the agent will get asked but should route elsewhere:

• Generic CLI-parser feature requests (variadic flags, subcommand routing, shell-completion generation) — outside this skill. The Arg Parser exposes a deliberately small public surface; route the user to a language-native parser layered on top if a feature is genuinely required.
• DOCA Core context, progress engine, and doca_mmap internals — owned by doca-programming-guide. Arg Parser is upstream of the Core context (it parses the CLI that selects which device the Core context will open); it does not redefine the Core context.
• DOCA Log internals (registry names, per-source level filters) — owned by the public DOCA Log guide reachable through doca-public-knowledge-map. Arg Parser registers --sdk-log-level as a default flag but does not own the log layer it configures.
• Cross-cutting DOCA_ERROR_* taxonomy — owned by doca-programming-guide CAPABILITIES.md ## Error taxonomy. This skill adds the Arg Parser overlay, not the taxonomy itself.
• Cross-cutting debug ladder (install / version / build / link / runtime / program / driver) — owned by doca-debug ## debug. This skill's ## debug overlays the program layer.