Lesson 2 — DOCA Core Objects & the API Model

You have the layers. Now the shape of the code. DOCA Core is small on purpose — a handful of objects that every library reuses. This lesson is the "APIs" answer from your mission: not every function, but the mental model that makes the functions obvious.^core

1 · The five Core objects

① Device — the hardware you'll use doca_dev discover + query capabilities of an accel unit

② Memory (zero-copy) doca_mmap doca_buf doca_buf_inventory

③ Context — a configured library instance doca_ctx

▼ submit work as…

④ Task → Event (async) task submitted → completion event

⑤ Progress Engine doca_pe — you poll it

Device + memory + context set the stage; then it's a loop: submit tasks, poll the progress engine, handle completion events.

Object	Role
`doca_dev`	Discover a hardware acceleration unit and query what it can do
`doca_mmap` / `doca_buf` / `_inventory`	Register memory once, then hand the HW zero-copy buffers over it
`doca_ctx`	A configured, started instance of a library — you submit tasks to it
task → event	One async unit of work; its completion comes back as an event
`doca_pe` (Progress Engine)	The thing you poll to advance tasks and receive completions

2 · The universal DOCA loop

Nearly every DOCA program — any library — follows this skeleton. Read the shape, not the exact function names:

// 1. set the stage (once) open a doca_dev // pick + query the hardware create a doca_mmap + buffers // register memory for zero-copy create + start a doca_ctx // e.g. a DMA / Flow / RDMA context connect a doca_pe // the progress engine drives it // 2. the data path (repeat, asynchronously) submit a task // "DMA these bytes" / "send this packet" while (!done) doca_pe_progress() // poll → hardware works → completion event fires handle the completion event // success or error

The one idea behind the whole API

DOCA offloads the data path to hardware and tells you when it's done. You don't call-and-block — you submit work and poll the progress engine. That async, zero-copy pattern is what keeps it at line rate.^core

3 · The libraries you'll reach for

Each library is a kind of ctx with its own task types, on top of the same Core:

Library	Accelerates
`DOCA Flow`	Hardware packet steering as "pipes" — match & act at line rate
`DOCA RDMA`	Remote direct memory access transfers
`DOCA GPUNetIO`	A CUDA kernel driving the NIC directly (GPU-initiated networking)
`DOCA Comch`	Control channel between host and DPU
`DOCA DMA` / `Compress`	Copy / (de)compress via hardware engines
`DOCA App Shield`	Agentless host process introspection (the "Argus" of the BlueField track) — DPU-only

Because they share Core, learning one library teaches you the others: swap the ctx and the task types; the device/memory/PE scaffolding is identical.

Check yourself

In DOCA, what do you poll to get task completions?

What is the purpose of doca_mmap and doca_buf?

DOCA's data-path model is best described as…

Primary source — read this next

NVIDIA's DOCA Core page (objects + progress engine) and the DOCA Programming Guide. Open one sample (e.g. DMA) and find the five objects in it.