#233 - Add automatic RSS for multi-queue flows

[cliffburdick]

Summary

• allow RX queue actions to use ids: [queue, ...] in YAML, C++, and Python
• keep scalar and single-entry targets as direct queue steering
• automatically use flow-affine IPv4/UDP Toeplitz RSS for two or more queue IDs
• implement DPDK MARK + RSS actions and ibverbs DevX RQT/indirect-TIR destinations
• validate duplicate, unknown, eCPRI, and reorder-incompatible RSS targets
• document RSS behavior, balance expectations, and current striping limitations
• increment DAQIRI_ABI_VERSION to 1 for the public FlowAction layout change

Why

A flow previously targeted only one RX queue, preventing applications from distributing varied IPv4/UDP traffic across multiple queues while preserving per-flow affinity. Multi-queue targets now select hardware RSS automatically without changing existing scalar configurations.

User impact

Existing action.id configurations remain unchanged. Users can specify:

action:
  type: queue
  ids: [0, 1]

A fixed five-tuple remains on one queue. Roughly even packet counts require enough varied tuples with reasonably balanced traffic. Exact per-packet striping is not part of this change.

Validation

• DPDK-only, ibverbs-only, combined-engine, and Python-binding builds
• parsed all 33 existing YAML configurations
• YAML/Python validation for scalar, list, empty, duplicate, unknown, and conflicting targets
• documentation reference checker and git diff --check
• DPDK software loopback regression
• ConnectX-7 physical loopback hardware tests on both engines:
  • dynamic RSS: 440,320/440,320 packets on DPDK and 441,344/441,344 on ibverbs
  • static RSS over 1,024 tuples: 882,176/882,176 packets on both engines
  • one fixed tuple: all packets remained on one queue
  • scalar steering, flow isolation, dynamic deletion, and flow marks passed

Closes #233

[greptile-apps]

Greptile Summary

This PR adds automatic hardware RSS for RX flows that target two or more queues, letting action.ids: [0, 1] in YAML, C++, or Python steer varied IPv4/UDP traffic across queues while preserving per-five-tuple affinity. Single-queue action.id configs are untouched.

• FlowAction.ids_ (types.h): new std::vector<uint16_t> placed after the legacy scalar fields to preserve positional aggregate init; ABI bumped to 1.
• DPDK: DpdkRxDestination emits RTE_FLOW_ACTION_TYPE_RSS (Toeplitz, IPv4/UDP) for multi-queue actions and RTE_FLOW_ACTION_TYPE_QUEUE for single; RSS flows routed to the legacy path rather than the template async path; force_ipv4_udp pins the match pattern so the hash function has the required headers.
• ibverbs: resolve_rx_destination creates a DevX RQT + indirect TIR per unique queue-set, cached as a weak_ptr; shutdown clears rule_specs before queue teardown to release TIR/RQT in the correct order. Validation in engine.cpp enforces duplicate-free IDs, known queue IDs, and blocks eCPRI+RSS and reorder+RSS combinations.

Confidence Score: 5/5

Safe to merge; no functional regressions found across the YAML parser, validation, DPDK, ibverbs, and Python binding paths.

Both engine implementations handle resource lifetime correctly: DpdkRxDestination keeps its vector alive within the rte_flow_create call scope, and the ibverbs RssDestination shared_ptr chain ensures TIR/RQT objects outlive all referencing dr_rules. Validation covers the newly introduced error cases (duplicate IDs, unknown IDs, eCPRI+RSS, reorder+RSS). The BurstParams free contract is preserved in the updated example. DCO trailers are present on both non-merge commits.

No files require special attention.

Important Files Changed

Filename	Overview
include/daqiri/types.h	Adds ids_ (std::vector<uint16_t>) to FlowAction after legacy fields, plus flow_config_actions, flow_queue_ids, and flow_queue_action_uses_rss helpers; ABI bump to 1 is correct given the layout change.
src/rss.h	New header with the fixed 40-byte Microsoft Toeplitz RSS key and a rss_table_size helper that rounds up to the next power-of-two; straightforward and correct.
src/engine.cpp	Validation updated to use flow_config_actions, adds duplicate-ID, unknown-ID, eCPRI+RSS, and reorder+RSS checks; removes the now-unnecessary empty-actions early-out safely because flow_config_actions always returns at least one element.
src/engines/dpdk/daqiri_dpdk_engine.cpp	Adds DpdkRxDestination that emits either RTE_FLOW_ACTION_TYPE_QUEUE or RTE_FLOW_ACTION_TYPE_RSS based on ids_ count; RSS flows routed to legacy path (not template); force_ipv4_udp pins the match pattern for Toeplitz hashing; pointer lifetimes are safe (stack-local struct within single create call).
src/engines/ibverbs/daqiri_ibverbs_engine.cpp	resolve_rx_destination creates DevX RQT + indirect TIR for multi-queue flows with correct byte-order and field masking; weak_ptr cache avoids redundant object creation; shutdown explicitly clears rule_specs before queues to release RSS TIR/RQT in the right order.
src/engines/ibverbs/mlx5_prm_min.h	Adds CREATE_RQT opcode, INDIRECT TIR disp_type, Toeplitz hash fn, L3/L4 prot types, hash field selectors, and RQT/create-rqt-in/out PRM structs needed by the new ibverbs RSS path.
src/engines/ibverbs/daqiri_ibverbs_engine.h	Adds RssDestination struct with custom shared_ptr deleter, rss_destination field on DynamicFlowEntry and RuleSpec, weak_ptr cache on PortSteering, and resolve_rx_destination declaration.
src/common.cpp	YAML parser correctly handles mutually-exclusive id/ids keys, validates non-empty sequence, and range-checks each entry to 16 bits before pushing into ids_.
examples/dynamic_rx_flow_example.cpp	Adds RSS phase to the dynamic-flow test: varied UDP source ports, add_dynamic_udp_rss_flow helper, per-packet flow-ID verification, and per-phase packet count checks; all RX bursts still free properly.
python/daqiri_common_pybind.cpp	Exposes ids_ on FlowAction via def_readwrite; one-line, correct.
CMakeLists.txt	DAQIRI_ABI_VERSION bumped from 0 to 1 to reflect the FlowAction layout change; AGENTS.md updated in sync.

_{Reviews (2): Last reviewed commit: "#233 - Document multi-queue RSS in READM..." | Re-trigger Greptile}