Skip to content

API Guide

DAQIRI is a library that moves bursts of packets between NICs and CPU or GPU memory with zero copies, configured from a YAML file or an equivalent C++ NetworkConfig struct.

This page is the orientation for the API: it covers DAQIRI's configuration-first model and the lifecycle every application follows. For the terminology and conceptual background it relies on (kernel bypass, GPUDirect, burst, segment, flow, queue, memory region, zero-copy ownership, RX reorder), keep the Concepts page open in a second tab.

Configuration-First Model

A DAQIRI application starts from a YAML configuration file (or an equivalent NetworkConfig struct built in code). The configuration defines the active stream type, optional engine, endpoint URIs, NIC interfaces, RX and TX queues, memory regions, flow steering rules, flow isolation, hardware flow transform actions, header-data split, and optional reorder plans. After initialization, the language API operates on that topology and, where supported, can extend it explicitly at runtime.

The APIs do not discover queues, memory, or flow steering rules on their own. The startup configuration remains the source of truth for stream-type, engine, endpoint selection, and immutable static flows. Applications may then add and delete RX flow rules on raw DPDK or raw ibverbs. The raw ibverbs engine also accepts explicit runtime memory-region and RX/TX queue creation and drain-based deletion through the C++ and Python APIs. A newly added RX queue does not receive traffic until a dynamic flow targets it, and that flow must be deleted before its queue can be removed. Static startup flows and TX transform flows remain immutable. TCP/UDP socket options are also runtime state: after resolving a connection ID, applications can call socket_setsockopt() with native Linux level and option constants.

The configuration schema lives in the Configuration YAML Reference. For an annotated end-to-end example, see the configuration walkthrough tutorial.

Application Model

The typical DAQIRI application lifecycle has six steps:

  1. Write or select a YAML configuration for the target system.
  2. Initialize DAQIRI from that configuration (daqiri_init).
  3. Receive or transmit packet bursts through configured queues (get_rx_burst / get_tx_packet_burst + send_tx_burst). Raw-ibverbs applications may also add or drain queues and memory regions, and redirect dynamic RX flows, while the engine is running.
  4. Access packet data through BurstParams helper functions (get_packet_ptr, get_segment_packet_ptr, ...).
  5. Explicitly release packet and burst buffers when the application is done with them (the free_* family).
  6. Shut down DAQIRI before process exit (shutdown).

Each step maps directly to a section of the C++ API Usage and Python API Usage pages. The buffer-release step in particular is load-bearing. See Zero-Copy Ownership on the Concepts page for why missed frees cause queue drops.

See also

  • Concepts: terminology and background for everything this page references.
  • Configuration YAML Reference: every YAML key, its type, and its valid values.
  • C++ API Usage: initialization, RX/TX workflows, buffer lifecycle, file writing, utilities, and the full C++ function reference.
  • Python API Usage: the same workflow through the pybind11 bindings, including GIL behavior, tuple return shapes, and the full Python function reference.
  • Configuration walkthrough tutorial: annotated YAML walkthrough with a use-case decision tree.