(4) dpdk rte acl (FFI only)

[daniel-noland]

Safe-ish Rust wrapper around librte_acl, plus a soundness fix to eal::init that came up while wiring things in.

The const-generic AclContext<N, State> is the load-bearing abstraction. N (number of fields per rule) is shared between AclContext<N>, Rule<N>, AclCreateParams<N>, and AclBuildConfig<N>, so any field-count mismatch is a compile-time error. The Configuring -> Built typestate transition enforces DPDK's "rules cannot be added after build" and "classification is &self (thread-safe)" invariants at the type level.

Commit layout

The wrapper is split into six commits so each lands as a digestible unit, with one prerequisite (the EAL fix). Every commit compiles on its own and passes cargo fmt --check + cargo clippy --all-targets -p dataplane-dpdk-sys -p dataplane-dpdk -- -D warnings.

#	Commit	What it adds
1	fix(dpdk): prepend program-name placeholder in eal::init	The EAL fix. rte_eal_init treats argv[0] as the program name and skips it during option parsing; the wrapper was silently swallowing the first real flag. into_raw/from_raw round-trip on the argv strings keeps pointer provenance mut-clean under Stacked/Tree Borrows.
2	chore(dpdk-sys): link rte_acl and bind its headers	Enable acl in the nix DPDK build, add rte_acl to the link list, include <rte_acl.h> in the bindgen wrapper.
3	chore(dpdk): scaffold acl module with field-layout types	New dpdk::acl module; FieldDef / FieldType / FieldSize (no DPDK runtime state).
4	feat(dpdk/acl): typed error enums	Dedicated error per operation (AclCreateError, AclAddRulesError, AclBuildError, AclClassifyError, AclSetAlgorithmError, plus InvalidAclName / InvalidRule / InvalidAclBuildConfig).
5	feat(dpdk/acl): SIMD classify algorithm enum	ClassifyAlgorithm with round-tripping From<u32> / TryFrom<u32>.
6	feat(dpdk/acl): rules, build config, and the typestate context	The wrapper itself: Rule<N>, AclField, Priority, CategoryMask, AclBuildConfig<N>, AclCreateParams<N>, AclContext<N, State>, plus ACL_CREATE_LOCK and dump_all_contexts. These three files have mutual type-level dependencies and ship together.
7	feat(dpdk/acl): public re-exports and integration tests	The user-facing re-exports and the end-to-end lifecycle tests against a live EAL.

Soundness surface

• AclContext::classify and classify_with_algorithm are unsafe fn. Each *const u8 in the input slice must reference a buffer valid for at least ctx.build_config().min_input_size() bytes. The bound is wider than max(offset + size): DPDK's classify loop does 4-byte aligned loads starting at the lowest offset within each input_index group, so the per-buffer extent is max(group_offset + 4) across groups.
• classify_with_algorithm's safety contract additionally requires CPU support for the chosen variant -- rte_acl_classify_alg does not validate against the per-CPU capability table (only rte_acl_set_ctx_classify does), so a real (non-stub) SIMD slot on an unsupported host executes unsupported instructions. Default and Scalar are always safe; everything else needs an is_x86_feature_detected! (or arch-equivalent) gate at the call site.
• Rule::validate reads each field through the union member matching the declared FieldSize, so the validator is endian-safe on big-endian hosts. It catches: mask-prefix-length out of range (would be UB in DPDK's RTE_ACL_MASKLEN_TO_BITMASK C shift), reversed range bounds, and category_mask bits beyond num_categories (DPDK would silently mask those off).
• AclField::value_u* / mask_range_u* are safe -- every member of the underlying union is a plain integer, so no bit pattern is invalid. Constructors guarantee the wider union members are zero-initialised.
• AclContext::as_raw_ptr / as_raw_mut_ptr are safe -- returning a raw pointer is sound; only its later use is unsafe. The &mut self receiver on as_raw_mut_ptr carries the typestate's mutability discipline into raw FFI code.
• Process-wide ACL_CREATE_LOCK: OnceLock<Mutex<()>> (via the concurrency facade) serialises every operation that touches DPDK's global ACL TAILQ: AclContext::new, Drop, and dump_all_contexts. This closes the duplicate-name TOCTOU (rte_acl_create returns the existing context pointer for a duplicate name, which would otherwise produce two owners of the same DPDK handle).
• Send is blanket over AclState; Sync is per-state with separate unsafe impls for Configuring<N> and Built<N>, so adding a new typestate later forces a fresh reentrancy audit rather than silently inheriting Sync.
• Rule<0> and AclBuildConfig<0> are rejected at compile time; N > MAX_FIELDS is rejected in AclCreateParams::new to prevent Rule::<N>::RULE_SIZE's u32 cast from truncating.
• #[repr(C)] types carry compile-time size_of / align_of asserts against the matching bindgen structs.

Test coverage

Unit tests live next to the code they test. bolero property tests cover ClassifyAlgorithm round-trip, AclBuildConfig::new field-defs validation against an independent oracle, the num_categories and context-name validators, and AclField::from_u* upper-byte invariants.

Integration tests (acl::tests, gated on #[cfg(test)]) run against a live EAL initialised through a shared OnceLock<Eal>:

• classify_smoke, reset_round_trip
• add_rules_rejects_out_of_range_prefix_length
• add_rules_rejects_category_mask_beyond_num_categories
• classify_categories_validated_before_ffi
• set_default_algorithm_then_classify, classify_with_algorithm_scalar
• duplicate_name_rejected
• add_rules_after_overflow_failure, build_failure_returns_usable_context
• classify_concurrent_arc_shared -- four threads classify concurrently through Arc<AclContext> to confirm the per-state Sync claim isn't vacuous.

[Copilot]

Pull request overview

This PR introduces a new dpdk::acl module providing a (safe-ish) Rust abstraction over DPDK’s librte_acl, and fixes dpdk::eal::init so rte_eal_init receives a proper argv[0] program name. It also enables and links the DPDK ACL library in the Nix + dpdk-sys build plumbing.

Changes:

• Add dpdk::acl (typestate AclContext<N, State>, validated config types, rule/field wrappers, and algorithm selection) plus tests.
• Fix eal::init to prepend a dummy argv[0] so the first real EAL flag isn’t skipped by rte_eal_init.
• Enable/build-link ACL support end-to-end (Nix DPDK build, wrapper header include, and dpdk-sys link list).

Reviewed changes

Copilot reviewed 13 out of 14 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
nix/pkgs/dpdk/default.nix	Enable DPDK acl library in the Nix build.
nix/pkgs/dpdk-wrapper/src/dpdk_wrapper.h	Include rte_acl.h for bindgen exposure.
dpdk-sys/build.rs	Link rte_acl alongside other DPDK libs.
dpdk/src/lib.rs	Export new dpdk::acl module.
dpdk/src/eal.rs	Prepend dummy argv[0] when calling rte_eal_init.
dpdk/src/acl/mod.rs	New ACL module entry, docs, and re-exports (plus smoke test).
dpdk/src/acl/classify.rs	New ClassifyAlgorithm enum + conversions/tests.
dpdk/src/acl/config.rs	New validated AclCreateParams / AclBuildConfig<N> + tests.
dpdk/src/acl/context.rs	New typestate AclContext<N, State> wrapper + lifecycle methods.
dpdk/src/acl/error.rs	New typed error enums for ACL operations.
dpdk/src/acl/field.rs	New FieldDef / FieldType / FieldSize wrappers + tests.
dpdk/src/acl/rule.rs	New Rule<N> / RuleData / AclField types + layout checks + tests.
dpdk/Cargo.toml	Add bolero dev-dependency for property tests.
Cargo.lock	Lockfile update for new dev dependency.

Comments suppressed due to low confidence (2)

dpdk/src/acl/rule.rs:325

confidence: 9
tags: [logic]

Same issue as `from_u8`: assigning to `rte_acl_field_types` union members (`u16_`) requires `unsafe`, so these writes will fail to compile.

Wrap the union field assignments in `unsafe { ... }` (keeping the prior zero-initialization so Debug/Hash/PartialEq remain deterministic).

pub fn from_u16(value: u16, mask_range: u16) -> Self {
    let mut field = Self::default();
    field.value.u16_ = value;
    field.mask_range.u16_ = mask_range;
    field
}

**dpdk/src/acl/rule.rs:338**
* ```yaml
confidence: 9
tags: [logic]

Same union-write compile error as from_u8/from_u16: writing to rte_acl_field_types.u32_ requires unsafe, so these assignments will not compile.

Please wrap the writes in an unsafe block (keeping the zero-initialization so later u64_ reads are not reading uninitialized bytes).

    pub fn from_u32(value: u32, mask_range: u32) -> Self {
        let mut field = Self::default();
        field.value.u32_ = value;
        field.mask_range.u32_ = mask_range;
        field
    }

[Copilot]

Pull request overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (2)

dpdk/src/acl/rule.rs:453

confidence: 9
tags: [logic]

`dpdk_sys::rte_acl_field_types` is a bindgen union; writing `field.value.u16_` / `field.mask_range.u16_` requires `unsafe`. This constructor currently performs union-field access in safe code and should be adjusted (e.g., write through the `u64_` member, or add an `unsafe` block around the union writes).

pub fn from_u16(value: u16, mask_range: u16) -> Self {
    let mut field = Self::default();
    field.value.u16_ = value;
    field.mask_range.u16_ = mask_range;
    field

**dpdk/src/acl/rule.rs:466**
* ```yaml
confidence: 9
tags: [logic]

Same issue as the other from_u* constructors: assigning to field.value.u32_ / field.mask_range.u32_ is union-field access and requires unsafe. Rework this constructor to avoid union-field writes in safe code (e.g., initialise via u64_ or use an unsafe { ... } block).

    pub fn from_u32(value: u32, mask_range: u32) -> Self {
        let mut field = Self::default();
        field.value.u32_ = value;
        field.mask_range.u32_ = mask_range;
        field

[Copilot]

Pull request overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated 2 comments.

[mvachhar]

Please read my comments first, no changes required because of them unless you want to make the changes.

[mvachhar]

I'm not going to reject the commit over this but the argument for unsafe here is specious. It says it avoids a panic, but it does so in favor of possible undefined behavior if the safety analysis is wrong or ever becomes wrong. The unreachable! is preferable here IMHO.

[daniel-noland]

yeah, I can see the spooky-action-at-a-distance arg. That being said, it is a compile time assert, and if that assert is wrong DPDK will malfunction anyway. It can't deal with zero sized rules

[mvachhar]

Again, I am not going to block the PR on this basis but a bunch of these presumably AI generated comments have some clutter. ctx is non-null because it's type is NonNull, there is no need to repeat it in every safety analysis, it is a red herring. This happens repeatedly in this file.

[daniel-noland]

this is a stronger example of where we really could stand to have an unreachable!()