#194 - Add hardware tunnel flow offloads (#194)

Signed-off-by: Cliff Burdick <cburdick@nvidia.com>

Author: cliffburdick

AGENTS.md

@@ -33,8 +33,8 @@ There is no unit test suite. Verification is done via the benchmark executables
 
 | Executable | Source | Typical config |
 |---|---|---|
-| `daqiri_bench_raw_gpudirect` | `raw_gpudirect_bench.cpp` | `daqiri_bench_raw_tx_rx.yaml`, `daqiri_bench_raw_tx_rx_4q.yaml`, `daqiri_bench_raw_tx_rx_spark.yaml`, `daqiri_bench_raw_{tx,rx}_spark_xhost.yaml`, `daqiri_bench_raw_sw_loopback.yaml`, `daqiri_bench_raw_rx_multi_q.yaml`, `daqiri_bench_raw_tx_rx_spark_mq.yaml` (mq base; `run_spark_mq_bench.sh` derives the 4 cells via `scripts/gen_spark_mq_config.py`), `daqiri_bench_raw_tx_rx_pacing.yaml` (per-queue `pacing_mbps`; DPDK engine only) |
-| `daqiri_example_dynamic_rx_flow` | `dynamic_rx_flow_example.cpp` | `daqiri_example_dynamic_rx_flow.yaml` — queues-only `flow_isolation: true` startup followed by runtime RX flow add/delete |
+| `daqiri_bench_raw_gpudirect` | `raw_gpudirect_bench.cpp` | `daqiri_bench_raw_tx_rx.yaml`, `daqiri_bench_raw_tx_rx_4q.yaml`, `daqiri_bench_raw_tx_rx_spark.yaml`, `daqiri_bench_raw_{tx,rx}_spark_xhost.yaml`, `daqiri_bench_raw_sw_loopback.yaml`, `daqiri_bench_raw_rx_multi_q.yaml`, `daqiri_bench_raw_tx_rx_vxlan.yaml`, `daqiri_bench_raw_tx_rx_vlan.yaml`, `daqiri_bench_raw_tx_rx_gre.yaml`, `daqiri_bench_raw_tx_rx_nvgre.yaml`, `daqiri_bench_raw_tx_rx_spark_mq.yaml` (mq base; `run_spark_mq_bench.sh` derives the 4 cells via `scripts/gen_spark_mq_config.py`), `daqiri_bench_raw_tx_rx_pacing.yaml` (per-queue `pacing_mbps`; DPDK engine only) |
+| `daqiri_example_dynamic_rx_flow` | `dynamic_rx_flow_example.cpp` | `daqiri_example_dynamic_rx_flow.yaml` — `flow_isolation: true` startup followed by runtime RX queue-steering and raw-engine decap/pop flow add/delete |
 | `daqiri_bench_raw_hds` | `raw_hds_bench.cpp` | `daqiri_bench_raw_tx_rx_hds.yaml` |
 | `daqiri_bench_raw_reorder_seq` | `raw_reorder_seq_bench.cpp` | `daqiri_bench_raw_tx_rx_reorder_seq_1024*.yaml`, `daqiri_bench_raw_rx_reorder_seq_*.yaml` |
 | `daqiri_bench_raw_reorder_quantize` | `raw_reorder_quantize_bench.cpp` | `daqiri_bench_raw_tx_rx_reorder_quantize_seq_batch.yaml` |
@@ -94,9 +94,10 @@ Vendored under `third_party/` as submodules (`.gitmodules`): `yaml-cpp` (config
 
 ### Current limitations
 - TX header fill currently supports UDP only (see README).
-- Raw Ethernet RX flow `action.id` must match an `rx.queues` ID and flex-item flows must reference a valid `flex_item_id` on the same interface; `daqiri_init()` aborts if RX flow rules, send-to-kernel fallbacks (`flow_isolation: true`), or `tx_eth_src` offload rules cannot be programmed on the NIC.
+- Raw Ethernet RX flow legacy `action.id` or final `actions:` queue action must match an `rx.queues` ID, and flex-item flows must reference a valid `flex_item_id` on the same interface; `daqiri_init()` aborts if RX flow rules, send-to-kernel fallbacks (`flow_isolation: true`), transform flow actions, or `tx_eth_src` offload rules cannot be programmed on the NIC.
+- Raw Ethernet tunnel/VLAN transform flows are hardware-only on the DPDK and ibverbs raw engines. TX flows may contain only push/encap transform actions and RX transform flows must use pop/decap actions ending in a queue; socket/RDMA engines reject these actions instead of adding a software fallback.
 - Raw Ethernet RX flow steering: a single interface cannot mix standard (UDP/IP) and
-  flex-item flows; `DpdkEngine::validate_config()` rejects mixed configs at init.
+  flex-item flows, and flex-item flows cannot combine with tunnel/VLAN transform actions; `DpdkEngine::validate_config()` rejects mixed configs at init.
 - No CI yet — contributors and reviewers verify manually (CONTRIBUTING.md).
 
 ## Documentation

README.md

@@ -39,7 +39,9 @@ DAQIRI provides direct NIC hardware access in userspace, bypassing the Linux ker
 - **Flow Steering** — Configure the NIC's hardware flow engine to route packets by UDP
   source/destination port or flex-item payload fields. Raw RX flows can be configured
   statically in YAML or added/deleted dynamically after `daqiri_init()`. Per RX
-  interface, use standard UDP/IP flows or flex-item flows, not both.
+  interface, use standard UDP/IP flows or flex-item flows, not both. Raw DPDK and
+  raw ibverbs flows can also use hardware-only VLAN push/pop and VXLAN, GRE, or
+  NVGRE encap/decap actions; socket/RDMA streams reject those tunnel actions.
 - **RDMA** — RDMA verbs (READ, WRITE, SEND) over RoCE on Ethernet NICs or InfiniBand.
 - **Optional OpenTelemetry metrics** — Expose per-interface or per-queue packet,
   byte, and drop counters when built with `DAQIRI_ENABLE_OTEL_METRICS=ON`.

docs/api-reference/configuration.md

@@ -194,19 +194,28 @@ engine.
 
 `rx.flows:` — Static startup flow rules that steer packets to specific queues based on
 match criteria. This sequence may be omitted; a queues-only RX config can add DPDK RX
-flows later with the dynamic flow API.
+flows later with the dynamic flow API. For Raw Ethernet on the DPDK and ibverbs engines,
+RX flows can also perform hardware VLAN pop or tunnel decapsulation before queue delivery.
 
 - **`name`**: Flow name.
   - type: `string`
 - **`id`**: Flow ID. Retrievable at runtime via `get_packet_flow_id()`.
   - type: `integer`
-- **`action`**: What to do with matched packets.
-  - **`type`**: Action type. Only `queue` is currently supported.
-    - type: `string`
-  - **`id`**: Queue ID to steer matched packets to. Must match the `id` of an entry under
-    `rx.queues` on the same interface. `daqiri_init()` rejects unknown queue IDs during
-    config validation.
-    - type: `integer`
+- **`action`**: Legacy single action map. Existing configs may keep using
+  `action: {type: queue, id: ...}`.
+- **`actions`**: Ordered action list. Use this for tunnel/VLAN transforms.
+  RX transform flows must end with `type: queue`.
+  - **`type: queue`**: Steer matched packets to an RX queue.
+    - **`id`**: Queue ID under `rx.queues` on the same interface.
+  - **`type: vlan_pop`**: Pop one VLAN tag in hardware.
+  - **`type: tunnel_decap`**: Decapsulate a hardware tunnel before queue delivery.
+    - **`tunnel.type`**: `vxlan`, `gre`, or `nvgre`.
+    - **`outer_eth_src` / `outer_eth_dst`**: Outer Ethernet addresses.
+    - **`outer_ipv4_src` / `outer_ipv4_dst`**: Outer IPv4 addresses. IPv6 outer
+      headers are not supported in v1.
+    - **VXLAN fields**: `vni`, optional `outer_udp_src`, `outer_udp_dst` default `4789`.
+    - **GRE fields**: optional `gre_protocol` default `0x0800`.
+    - **NVGRE fields**: `tni`, optional `flow_id`.
 - **`match`**: Criteria for matching packets.
   - **`udp_src`**: UDP source port or port range (e.g., `1000-1010`).
     - type: `integer` or `string`
@@ -230,6 +239,7 @@ created when `flow_isolation: true`, initialization fails with a critical log an
 A single RX interface must use either standard UDP/IP flows or flex-item flows, not both.
 Both classes install conflicting DPDK group-0 jump rules, so only one is reachable when mixed.
 `daqiri_init` rejects such configs with a clear error.
+Flex-item flows cannot be combined with VLAN/tunnel transform actions in v1.
 
 ### Flow Isolation
 
@@ -375,6 +385,34 @@ daqiri::set_reorder_cuda_stream("rx_port", "rx_reorder_0", stream);
   - type: `integer`
   - default: `0`
 
+### Transmit Flows
+
+`tx.flows:` — Raw Ethernet hardware transform rules for outgoing packets. Supported on
+the DPDK and ibverbs raw engines only. TX flows match the packet as supplied by the
+application, then push or encapsulate headers in hardware; the application buffer remains
+the pre-encap packet.
+
+- **`name`** / **`id`**: Flow label and ID.
+- **`actions`**: Ordered transform action list. TX flows cannot contain `queue`.
+  - **`type: vlan_push`**: Push one VLAN tag.
+    - **`vlan_id`**: VLAN ID, `0..4095`.
+    - **`pcp`**: Priority, `0..7`, default `0`.
+    - **`dei`**: Drop eligible indicator, `0..1`, default `0`.
+    - **`ethertype`**: VLAN TPID, default `0x8100`.
+  - **`type: tunnel_encap`**: Encapsulate in `vxlan`, `gre`, or `nvgre`.
+    - **`tunnel.type`**: `vxlan`, `gre`, or `nvgre`.
+    - **`outer_eth_src` / `outer_eth_dst`** and **`outer_ipv4_src` /
+      `outer_ipv4_dst`** are required.
+    - **VXLAN fields**: `vni`, optional `outer_udp_src`, `outer_udp_dst` default `4789`.
+    - **GRE fields**: optional `gre_protocol` default `0x0800`.
+    - **NVGRE fields**: `tni`, optional `flow_id`.
+- **`match`**: Same standard UDP/IP match keys as RX flows. Omit `match` for a
+  catch-all TX transform.
+
+DAQIRI validates tunnel overhead against the configured packet buffer size and
+the supported jumbo-frame bound. For RX decap/pop, MTU sizing accounts for the
+outer wire frame while packet buffers contain the post-decap frame.
+
 ### Accurate Send
 
 `tx.accurate_send:` — Enable hardware-timed packet transmission using PTP timestamps. When

docs/api-reference/cpp.md

@@ -136,6 +136,11 @@ Raw Ethernet RX flows can be added and deleted after `daqiri_init()` on the
 `dpdk` and raw `ibverbs` engines. This supports queues-only startup configs,
 including `rx.flow_isolation: true` with no initial `rx.flows`. Static YAML
 flows still use explicit configured IDs and are not deletable through this API.
+The legacy `FlowRuleConfig::action_` field remains the shorthand for a single
+queue action; `FlowRuleConfig::actions_` is the ordered form used when a dynamic
+RX rule needs hardware VLAN pop or tunnel decapsulation before queue delivery.
+Dynamic TX transform flows are not part of v1; configure TX encapsulation/push
+rules statically under `tx.flows`.
 
 ```cpp
 daqiri::FlowRuleConfig flow;
@@ -173,6 +178,33 @@ while (flow_id == 0) {
 }
 ```
 
+For a dynamic VXLAN decap rule, use ordered actions and make the final action
+the target queue:
+
+```cpp
+daqiri::FlowRuleConfig decap;
+decap.name_ = "vxlan_decap_5000";
+
+daqiri::FlowAction tunnel;
+tunnel.type_ = daqiri::FlowType::TUNNEL_DECAP;
+tunnel.tunnel_.type_ = daqiri::TunnelType::VXLAN;
+tunnel.tunnel_.outer_eth_src_ = "02:00:00:00:00:01";
+tunnel.tunnel_.outer_eth_dst_ = "02:00:00:00:00:02";
+tunnel.tunnel_.outer_ipv4_src_ = "192.0.2.1";
+tunnel.tunnel_.outer_ipv4_dst_ = "192.0.2.2";
+tunnel.tunnel_.outer_udp_dst_ = 4789;
+tunnel.tunnel_.vni_ = 100;
+decap.actions_.push_back(tunnel);
+
+daqiri::FlowAction queue;
+queue.type_ = daqiri::FlowType::QUEUE;
+queue.id_ = 0;
+decap.actions_.push_back(queue);
+
+decap.match_.type_ = daqiri::FlowMatchType::IPV4_UDP;
+decap.match_.udp_dst_ = 5000;
+```
+
 Packets matching a dynamic rule are marked with the same `FlowId` returned by
 the add completion, so `get_packet_flow_id()` gives the handle to pass to
 `delete_flow_async()`. `poll_flow_op()` returns `Status::NOT_READY` when no flow
@@ -219,7 +251,8 @@ auto delete_status = daqiri::delete_flow_async(flow_id, &delete_op);
 ```
 
 Dynamic flow support is RX-only in v1. Socket, RDMA/RoCE, and software loopback
-engines return `NOT_SUPPORTED`.
+engines return `NOT_SUPPORTED`; tunnel/VLAN transform actions are accepted only
+by raw DPDK and raw ibverbs.
 
 ## Reordered RX Bursts
 

docs/api-reference/index.md

@@ -22,15 +22,18 @@ 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,
-header-data split, and optional reorder plans. After initialization,
+hardware flow transform actions, header-data split, and optional reorder plans. After initialization,
 the language API operates on those configured ports, queues, buffers,
 and flows.
 
 The language APIs do **not** discover queues, memory, or flow steering
 rules on their own. They are runtime handles over the topology declared
 in the configuration (YAML file or `NetworkConfig` struct). The
 configuration is the source of truth for queue IDs, memory placement,
-stream-type / engine / endpoint selection, and flow routing.
+stream-type / engine / endpoint selection, flow routing, and static TX
+tunnel/VLAN transforms. Dynamic RX flow APIs can add and delete runtime
+queue-steering rules and, on raw DPDK or raw ibverbs, runtime RX decap/pop
+rules using the same ordered action model.
 
 The configuration schema lives in the
 [Configuration YAML Reference](configuration.md). For an annotated

docs/api-reference/python.md

@@ -591,6 +591,11 @@ The workflow sections above show the common call order and ownership rules.
 | `rdma_get_port_queue(conn_id)` | Return `(Status, port, queue)`. |
 | `rdma_get_server_conn_id(server_addr, server_port)` | Return `(Status, conn_id)`. |
 
+Dynamic RX flows are RX-only in v1. The `action` attribute remains the single queue-action
+shorthand; use ordered `actions` when a raw DPDK or raw ibverbs dynamic rule needs hardware
+VLAN pop or VXLAN/GRE/NVGRE decapsulation before the final queue action. Static TX
+encapsulation/push rules are configured in YAML under `tx.flows`.
+
 ## Constants
 
 | Name | Description |
@@ -622,7 +627,8 @@ The workflow sections above show the common call order and ownership rules.
 | `RDMAMode` | `CLIENT`, `SERVER`, `INVALID` |
 | `RDMATransportMode` | `RC`, `UC`, `UD`, `INVALID` |
 | `SocketMode` | `CLIENT`, `SERVER`, `INVALID` |
-| `FlowType` | `QUEUE` |
+| `FlowType` | `QUEUE`, `VLAN_PUSH`, `VLAN_POP`, `TUNNEL_ENCAP`, `TUNNEL_DECAP` |
+| `TunnelType` | `NONE`, `VXLAN`, `GRE`, `NVGRE` |
 | `FlowMatchType` | `IPV4_UDP`, `FLEX_ITEM` |
 | `FlowOpType` | `ADD_RX`, `ADD_RX_BATCH`, `DELETE` |
 | `ReorderMethod` | `INVALID`, `SEQ_BATCH_NUMBER`, `SEQ_PACKETS_PER_BATCH` |
@@ -654,10 +660,12 @@ names that mostly omit the trailing underscore from the C++ member name (e.g.
 | `RxQueueConfig` | RX queue wrapper with common queue fields and timeout. |
 | `TxQueueConfig` | TX queue wrapper with common queue fields. |
 | `MemoryRegionConfig` | Memory region kind, affinity, access flags, sizes, counts, and ownership. |
-| `FlowAction` | Flow action type and target ID. |
+| `VlanActionConfig` | VLAN push parameters: VLAN ID, priority, DEI, and ethertype. |
+| `TunnelConfig` | VXLAN, GRE, or NVGRE tunnel template fields for hardware encap/decap actions. |
+| `FlowAction` | Flow action type, queue target ID, optional VLAN config, and optional tunnel config. |
 | `FlowMatch` | Flow match fields for UDP, IPv4, and flex item matching. |
-| `FlowConfig` | Named flow rule combining action and match. |
-| `FlowRuleConfig` | Dynamic flow rule match and action. |
+| `FlowConfig` | Static named flow rule combining legacy `action`, ordered `actions`, and match fields. |
+| `FlowRuleConfig` | Dynamic RX flow rule combining legacy `action`, ordered `actions`, and match fields. |
 | `FlowOpResult` | Dynamic flow operation completion. Batch adds return `flow_ids` in input order. |
 | `FlexItemConfig` | Flexible parser item configuration. |
 | `FlexItemMatch` | Flexible parser match value and mask. |

docs/benchmarks/raw_benchmarking.md

@@ -110,6 +110,20 @@ The benchmark executables and example YAML configurations are located at:
 
 The fields in the YAML configs will be explained in more detail in [Understanding the Configuration File](../tutorials/configuration-walkthrough.md). For now, we'll stick to modifying the strict minimum required fields to run the application as-is on your system.
 
+### Hardware tunnel transform examples
+
+Raw DPDK and raw ibverbs builds can program hardware flow actions that push or
+encapsulate on TX and pop or decapsulate on RX. The application packet buffers
+remain pre-encap on TX and post-decap on RX; DAQIRI accounts for outer-header
+overhead when sizing MTU/wire frames.
+
+| Transform | YAML config | Binary |
+|---|---|---|
+| VXLAN encap + decap | [`daqiri_bench_raw_tx_rx_vxlan.yaml`](https://github.com/nvidia/daqiri/blob/main/examples/daqiri_bench_raw_tx_rx_vxlan.yaml) | `daqiri_bench_raw_gpudirect` |
+| VLAN push + pop | [`daqiri_bench_raw_tx_rx_vlan.yaml`](https://github.com/nvidia/daqiri/blob/main/examples/daqiri_bench_raw_tx_rx_vlan.yaml) | `daqiri_bench_raw_gpudirect` |
+| GRE encap + decap | [`daqiri_bench_raw_tx_rx_gre.yaml`](https://github.com/nvidia/daqiri/blob/main/examples/daqiri_bench_raw_tx_rx_gre.yaml) | `daqiri_bench_raw_gpudirect` |
+| NVGRE encap + decap | [`daqiri_bench_raw_tx_rx_nvgre.yaml`](https://github.com/nvidia/daqiri/blob/main/examples/daqiri_bench_raw_tx_rx_nvgre.yaml) | `daqiri_bench_raw_gpudirect` |
+
 ##### Identify your NIC's PCIe addresses
 
 Retrieve the PCIe addresses of both ports of your NIC. We'll arbitrarily use the first for Tx and the second for Rx here:

docs/concepts.md

@@ -242,18 +242,17 @@ buffers (CPU hugepages, GPU device memory, or pinned host memory).
 
 ### Flow
 
-A **flow** is a match pattern paired with an action. The common action
-is to steer matching packets into a specific queue. For example, all
-UDP-destination-port-4096 packets can be routed into a queue backed by
-GPU memory. Matching and the resulting action both run entirely in NIC
-hardware.
+A **flow** is a match pattern paired with one or more actions. The
+common RX action is to steer matching packets into a specific queue. For
+example, all UDP-destination-port-4096 packets can be routed into a
+queue backed by GPU memory. Matching and the resulting actions both run
+entirely in NIC hardware.
 
 Flow rules are only available in Raw Ethernet (`stream_type: "raw"`).
 
 A flow's match can combine fields such as `udp_src`, `udp_dst`, and
 `ipv4_len`; multiple flows can target the same queue, and the matching
-flow's ID is available at runtime so the application can distinguish
-them.
+flow's ID is available at runtime so the application can distinguish them.
 
 Flows can be static or dynamic. Static flows are configured under
 `rx.flows` in the YAML and keep their configured IDs for the process lifetime.
@@ -264,16 +263,24 @@ returned in the add completion, and used as the packet marks returned by
 flow IDs are in input order. Only dynamic flows can be deleted dynamically. TX
 dynamic flows are not part of v1.
 
+Raw DPDK and raw ibverbs flows can also use ordered `actions:` for hardware VLAN
+pop/push and VXLAN, GRE, or NVGRE decap/encap. RX decap/pop actions deliver
+post-decap packets to application buffers; TX encap/push actions leave
+application buffers as pre-encap packets and change only the wire frame.
+Dynamic RX flows use the same ordered action model for runtime decap/pop rules,
+while TX transform flows remain static startup configuration.
+
 ### Flow Steering
 
 **Flow steering** is the NIC-level mechanism that classifies an
 incoming packet against the configured flows and writes it into the
 matching queue's buffer, entirely in hardware. Multi-queue RX works by
 routing each flow to a separate queue for parallel processing.
 
-For Raw Ethernet, flow steering is implemented on top of RTE Flow. Flow
-rules are programmed during `daqiri_init()`; initialization fails if the
-NIC rejects a rule. The YAML options are documented in
+For Raw Ethernet, flow steering is implemented on top of RTE Flow in the
+DPDK engine and mlx5 Direct Rules in the ibverbs engine. Flow rules are
+programmed during `daqiri_init()`; initialization fails if the NIC
+rejects a rule. The YAML options are documented in
 [Configuration YAML Reference → Flows](api-reference/configuration.md#flows).
 
 ## Memory Regions