Doca Devemu

DOCA Device Emulation capabilities, version overlay, errors, observability, safety

Where to start: Pick the H2 anchor that matches your question (umbrella architecture / sub-library selection / per-sub-library Core context / capability discovery / 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 a Device Emulation overlay on top of, see doca-version/SKILL.md. For the host-side kernel driver layer that consumes the emulated PCIe device, route via doca-public-knowledge-map/SKILL.md to the upstream Linux kernel virtio / PCIe documentation — the host kernel driver layer is not part of DOCA and is not re-explained here.

Pattern overview

Every Device Emulation question this skill teaches resolves into one of SEVEN patterns. The patterns are CLASSES — they apply across every Device Emulation release and every BlueField generation + firmware combination, not just the worked examples shown.

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

• Sub-library selection precedes everything. "Use DOCA Device Emulation" is not actionable on its own — the API surface, the pkg-config module, the capability-query family, the sample tree under /opt/mellanox/doca/samples/doca_devemu/, and the firmware-level enablement axis ALL depend on whether the user is building a PCI Generic device, a virtio-net device, or a virtio-fs device. An agent that begins writing code (or quoting symbols) before pinning the sub-library is wrong for every Device Emulation release.

• The library is the building block; the packaged services are different artifacts. DOCA SNAP Service and DOCA Virtio-net Service are packaged daemons built on top of this library. The library is the right answer when the user is writing a custom backend; the service is the right answer when the user wants a packaged solution and is willing to let the service own the backend implementation. Conflating the two is the single most common Device Emulation first-app design error and the cleanest place to fail fast.

Capabilities and modes

DOCA Device Emulation is an umbrella library: a shared architecture across the four sub-libraries covered end-to-end here, each of which exposes its own API surface, pkg-config module, sample tree subdirectory, and capability-query family. The umbrella architecture is constant; the per-sub-library specifics differ.

Umbrella architecture — what every Device Emulation deployment looks like.

The agent's rule: when the user asks "what backend should I write", that is a domain question (storage / networking / filesystem design), NOT an API question — route via doca-public-knowledge-map/SKILL.md to the public DOCA Device Emulation umbrella guide and the per-sub-library guides linked from it, plus the user's own domain expertise. When the user asks "how do I expose an emulated PCIe device from the DPU and react to host driver calls", that is this skill's scope.

Sub-library selection — the load-bearing first move. Before any code is written, the agent must pin the sub-library the user needs. Different sub-libraries have different APIs, different pkg-config modules (per the per-sub-library guides reachable via doca-public-knowledge-map/SKILL.md), and different firmware-level enablement axes.

If the user does not yet know which sub-library they need, the agent's job is to walk the rows above with the user before writing any code. Picking a sub-library for the user when the rows do not pin one is a wrong answer regardless of how clean the rest of the setup goes.

The per-sub-library DOCA Core context — one per emulated device per sub-library.

A DPU exposing more than one emulated device — or emulated devices in more than one sub-library — needs one per-sub-library context per emulated device. There is no "global Device Emulation context" that spans sub-libraries; the sub-library contexts are independent and follow their own lifecycles.

Doorbell / DMA primitives — the bridge between host driver and DPU backend. Each sub-library exposes its own doorbell and DMA primitives that the host's kernel driver and the DPU-side backend use to coordinate without each side having to poll the other unconditionally. The agent's rule for these primitives is the same as for the Core context: per-sub-library, not global.

Per-sub-library capability discovery — the only rule. Each sub-library exposes its own doca_devemu_<sub>_cap_* family. Before assuming a feature bit, a maximum, or a device characteristic is available, call the matching family against the active doca_devinfo for the BlueField device the user is emulating from.

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/SKILL.md. The body lives there; this skill does not duplicate it.

The Device Emulation-specific overlay is:

• Version handling is per-sub-library, not per-umbrella. Each sub-library has its own pkg-config module installed by the DOCA host packages on the DPU side; the user's build manifest must reference the module for the sub-library they picked (per the sub-library selection table in ## Capabilities and modes). The exact per-sub-library module name lives in the public Device Emulation umbrella guide and the per-sub-library guides linked from it, reachable via doca-public-knowledge-map/SKILL.md; the agent should route the user there to read it off the guide and off their own pkg-config install rather than hardcoding a module name from memory.

• Cap-query is the runtime authority per sub-library. Per the cross-cutting rule in doca-version CAPABILITIES.md ## Observability (doca-version/CAPABILITIES.md#observability), the per-sub-library doca_devemu_<sub>_cap_* query against the active doca_devinfo is the runtime authority for "is the emulation type I want supported on this BlueField + this DOCA install + this firmware". The public guides are the promise; the cap query is the reality. The four-way-match check (the chosen sub-library's .pc plus doca-common.pc plus doca_caps --version) per doca-version CAPABILITIES.md ## Version compatibility (doca-version/CAPABILITIES.md#version-compatibility) catches the partial-install case where the umbrella is installed but a sub-library is not.

• The devemu public API changed in DOCA 3.5. DOCA 3.5 introduced breaking public API changes for devemu. Code using the previous devemu API surface must migrate. Removed families include VFS configuration create/destroy/add/remove/user-data-size APIs (doca_devemu_vfs_cfg_*) and the PCI device VF-count and reset getters/controls (doca_devemu_pci_dev_get_num_vfs, _get_total_vfs, _reset_db, _reset_msix), and the PCI capability-type hotplug query (doca_devemu_pci_cap_type_is_hotplug_supported; use doca_devemu_pci_cap_is_hotplug_supported). Added families include the virtio offload engine setters (doca_devemu_virtio_offload_engine_*), vnet capability queries (doca_devemu_vnet_cap_*), vnet counters (doca_devemu_vnet_counters_*), admin request user-data size get/set (doca_devemu_vnet_get_admin_req_user_data_size and doca_devemu_vnet_set_admin_req_user_data_size), and vnet offload engine export/import (doca_devemu_vnet_offload_engine_export and doca_devemu_vnet_offload_engine_create_from_export). Developers must use the devemu public header for exact prototypes and constants for these families; do not hardcode them from memory or from older DOCA releases. The header is the same public Device Emulation header referenced in the headers-win-over-docs bullet below.

• Headers in $(pkg-config --variable=includedir doca-common) win over docs. Per the headers-win-over-docs rule in doca-version/SKILL.md, if a public Device Emulation doc page mentions a doca_devemu_* symbol that is not in the installed headers, the headers describe what this install can call. The agent must quote the headers (and the cap query), not the docs URL, when the two disagree.

Error taxonomy

Device Emulation-specific overlays on the cross-library DOCA_ERROR_* taxonomy. The cross-library taxonomy itself lives in doca-programming-guide CAPABILITIES.md ## Error taxonomy (doca-programming-guide/CAPABILITIES.md#error-taxonomy); the rows below are the Device Emulation 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 DOCA_ERROR_* without first identifying which of the rows above is the cause. None of the Device Emulation errors above want a retry — every row points at investigation (env / firmware / sub-library selection / feature negotiation / host-side driver), not at retry.

Observability

Device Emulation observability surface is two-sided: there is a DPU-side observability surface (per-sub-library context state, capability-query snapshots, DOCA logger events on the DPU side) AND a host-side observability surface (the host kernel's view of the emulated PCIe device — lspci, the matching kernel driver's sysfs / debugfs entries, dmesg). The agent must reach for both, not just one — an emulated device that appears to load on the DPU side but is invisible to the host's lspci, or visible but unbound to its driver, is a half-deployment that the DPU-side surface alone cannot fully diagnose.

Three primary signals the agent should reach for:

1. DPU-side per-sub-library context state and logger. The DPU-side context's state transitions (configure → start → running → stop → destroy), the per-sub-library doorbell / DMA primitives' observability hooks, and the DOCA logger on the DPU side (set DOCA_LOG_LEVEL=trace for first runs) are the primary DPU-side signals. Absence of a doorbell reaction when the host driver is clearly active should first be checked for a missing doca_pe_progress() in the DPU-side main loop, a doorbell registration wired against the wrong sub-library context, or an operation sent to the wrong queue / register.

2. Per-sub-library capability snapshot at configure time. The output of every doca_devemu_<sub>_cap_* query against the active doca_devinfo is a snapshot of what the library + the hardware + the firmware said was possible before any emulated device was created. Save it; if a later call returns DOCA_ERROR_NOT_SUPPORTED or _INVALID_VALUE the diff against this baseline is the bug.

3. Host-side enumeration and kernel-driver state. On the host side, lspci shows whether the emulated PCIe device is enumerated at all; the matching kernel driver's sysfs / debugfs entries show whether the driver bound to it; the host's dmesg shows what the kernel saw at bind time (virtio feature negotiation issues, DMA failures, BAR mapping issues). A DPU-side context that started cleanly but produced no host-side enumeration is most often a firmware-side enable that has not taken effect yet (a BlueField reset after the firmware-side flip is typically required); a host-side enumeration without driver bind is most often a host kernel that ships no driver for the emulated class (the host kernel must have the matching driver, the DPU does not provide it).

DOCA 3.5 added five vnet counter query families for TX/VQ error observability: TX VQ header-length errors, TX VQ host-address errors, TX VQ LSO/GSO errors, TX VQ skipped descriptors, and VQ error-handler-scheduled counts. Query these through the doca_devemu_vnet_counters_* family declared in the header that declares the devemu vnet counter queries; treat them as the authoritative counter surface and do not rely on older counter guidance that omits them.

For cross-cutting observability primitives (--sdk-log-level, the DOCA_LOG_LEVEL env var, the trace build flavor) see doca-debug CAPABILITIES.md ## Observability (doca-debug/CAPABILITIES.md#observability). For the install-tree observability (logger names, package layout, sample tree) defer to doca-public-knowledge-map/SKILL.md.

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 (doca-hardware-safety/CAPABILITIES.md#safety-policy) (specifically ### Per-artifact overlay pattern (doca-hardware-safety/CAPABILITIES.md#per-artifact-overlay-pattern)). When the two layers disagree, the stricter wins; when either layer says STOP, the agent stops.

Device Emulation's safety surface is dual-axis-driven AND host-driver-driven. The three most common Device Emulation first-app failures are (1) the BlueField firmware does not have the chosen emulation type enabled; (2) the DPU-side process lacks the privilege required for PCIe-level emulation; and (3) the host's kernel does not ship the standard driver for the emulated device class the user picked, or the host's kernel ships it but it failed to bind for a feature- negotiation reason. The agent's job is to verify all three before any doca_devemu_<sub>_* create call, not after the first DOCA_ERROR_NOT_PERMITTED or first silent host-side non-enumeration.

The env-precondition matrix the agent must walk for any new Device Emulation setup:

Configuration shape. Mandatory configurations before any doca_ctx_start() on the per-sub-library context: the chosen sub-library's emulated-device context must be created against a doca_dev whose BlueField firmware has the matching emulation type enabled; the per-sub-library doorbell / DMA primitives must be wired; the per-sub-library capability queries (doca_devemu_<sub>_cap_*) must agree that the deployment is supported on this combo; the per- sub-library feature negotiation (virtio-net / virtio-fs only, where the host driver negotiates features with the emulated device) must be set up before the host kernel driver attempts to bind. Optional configurations (per-device queue tuning, per-device user-data) ride on top of the same cap-query rule.

Choosing the library does not preclude later choosing a service. A user who starts with doca-devemu and discovers they would rather adopt the packaged DOCA SNAP Service or DOCA Virtio-net Service can do so — the services are built on top of the same library and the firmware-side preconditions are the same. The agent should surface this escape hatch when the user's intent reveals a packaged solution would suit them better; conversely, the agent should surface this library path when a user trying to adopt a service discovers the service does not implement what they need and they will have to write a custom backend.

Lifecycle ordering is per-sub-library. The per-sub-library context follows the universal DOCA Core teardown order on top of the doca_dev; out-of-order teardown surfaces as DOCA_ERROR_BAD_STATE. The Device Emulation-specific addition is the host-driver-attached state: tearing down the per-sub-library context while the host kernel driver is still attached to the emulated device may leave the host side with a half-removed PCIe surface that produces noisy dmesg output on the host until the next BlueField reset. The agent must surface this ordering explicitly — instruct the user to detach the host kernel driver (or unload the host kernel module) before tearing down the DPU-side context, and to destroy emulated devices before destroying their parent per-sub-library context.

This skill does not define a backend. doca-devemu provides the framework for emulated PCIe devices; it does not implement a specific storage backend, packet processor, or filesystem. When the user asks "what backend should I write", the agent must refuse to invent backend bodies and must route the user to the public DOCA Device Emulation umbrella guide via doca-public-knowledge-map/SKILL.md and to the user's own domain expertise.

Deferred topic boundaries

This skill scopes itself to the library umbrella across the three sub-libraries covered end-to-end here. Adjacent topics the agent will get asked but should route elsewhere:

• DOCA SNAP Service — packaged NVMe / virtio-blk storage daemon built on top of this library. Out of scope; route via doca-public-knowledge-map/SKILL.md to the DOCA SNAP Services guide. The library is the building block; the service is the packaged solution and is a different artifact than what this skill covers.

• DOCA Virtio-net Service — packaged virtio-net daemon built on top of this library's virtio-net sub-library. Out of scope; route via doca-public-knowledge-map/SKILL.md to the DOCA Virtio-net Service guide. Same library-vs-service distinction as SNAP above.

• Host kernel drivers for the emulated device class (upstream virtio-net, virtio-fs, virtio-blk drivers, the host's generic PCIe driver model) — outside DOCA entirely. Route to the upstream Linux kernel documentation; this skill assumes the host kernel ships the matching driver.

• Designing the backend itself (the storage backend body, the packet-forwarding logic, the filesystem implementation) — outside this skill. Route via doca-public-knowledge-map/SKILL.md to the public DOCA Device Emulation umbrella guide and the per-sub-library guides for sub-library-specific guidance; the backend body itself is the user's domain expertise.

• Standard NIC behavior on the BlueField data path (doca-flow/SKILL.md + doca-eth/SKILL.md territory) — outside this skill. Device Emulation is for custom emulated PCIe devices; Flow + Eth are for the BlueField's existing NIC personality.

• General-purpose host ↔ DPU memory copies (doca-dma/SKILL.md) — outside this skill. The per-sub-library DMA primitives in Device Emulation are contract-correct for the emulated device class; for raw general-purpose host ↔ DPU memcpy outside the emulation contract, DMA is the right library.

• Host ↔ DPU control-plane messaging that does NOT involve the host seeing a new PCIe device class (doca-comch/SKILL.md) — outside this skill. Comch is an explicit host ↔ DPU IPC over PCIe; Device Emulation hides the DPU behind a real-looking PCIe device that uses the host's standard driver path.

• DOCA Core context and progress engine internals — owned by doca-programming-guide/SKILL.md. This skill uses the Core lifecycle; it does not redefine it.

• Cross-cutting DOCA_ERROR_* taxonomy — owned by doca-programming-guide CAPABILITIES.md ## Error taxonomy (doca-programming-guide/CAPABILITIES.md#error-taxonomy). This skill adds the Device Emulation overlay, not the taxonomy itself.

• Cross-cutting debug ladder (install / version / build / link / runtime / program / driver) — owned by doca-debug ## debug (doca-debug/TASKS.md#debug). This skill's ## debug redirects there for layer 1-4; layers 5-7 carry the Device Emulation-specific overlay (including the firmware-side emulation-type enable route, the sub-library mis-selection diagnosis, and the host-kernel- driver bind state).