[squash] match-action vocabulary + ACL backends + lookup/fixed-size facades

Pre-review squash of the acl-pat-design branch (51 commits' worth of
accumulated work + iteration above PR 7's threading-rewrite tip
`d69246dbf`). To be re-split into a reviewable stack before pushing.

Contents:

- Two new facade crates: `dataplane-fixed-size` (FixedSize trait +
  primitive impls) and `dataplane-lookup` (Lookup + Projection +
  classify/classify_opt + Option<K> identity + std map impls). Both
  dependency-free.

- `match-action` crate: backend-agnostic key vocabulary -- the
  `MatchKey` trait (+ derive supporting generics, default #[exact]),
  `FieldSpec`/`FieldKind`, `Backend`/`IntoBackendField`, four
  `*Spec<T>` rule wrappers, type-erased `FieldPredicate` enum with
  per-kind structs (Exact/Prefix/Mask/Range) and always-on
  assertions. `match-action-derive` proc-macro.

- `net`: implements `FixedSize` for `TcpPort`, `UdpPort`,
  `UnicastIpv4Addr`, `Vni`. Wires its wire-newtypes into the
  match-action key vocabulary with no orphan-rule dance.

- `cascade`: re-exports `Lookup` / `Projection` from the lookup
  crate (no behavior change for consumers).

- `dpdk`: `#[with_eal]` proc macro for EAL-bound integration tests.

- `acl` crate: the match-action ACL stack.
  * Software reference backend (linear scan, RIB-shaped, non-lossy
    invariant) + a differential bolero harness vs DPDK with
    rule-derived boundary probes.
  * DPDK `rte_acl` backend: layout planner, rule splice, install
    pipeline, single-shot + SIMD batch classify, `dpdk_table_alias!`
    macro, IPv6 via 4x u32 wide-field splitting, blanket `AclWord
    for all FixedSize` (so net wire newtypes work in DPDK keys with
    zero acl-side code).
  * `Lookup::classify_opt` for fallible projection (`Option<K>`
    identity for one-off call sites; the `PacketSource` + Projection
    impl pattern for reusable sources). Metadata projection demo:
    header fields + VRF + VNI through both backends.
  * Criterion benches: reference + DPDK lookup (single + batch) and
    table-build, IPv4 and IPv6, 1..16384 log2 rule-count sweep.

- `nix`: `benches` target precompiling criterion binaries against
  the optimized release DPDK sysroot.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: daniel-noland

Cargo.lock

@@ -1,7 +1,9 @@
 [workspace]
 
 members = [
+    "acl",
     "args",
+    "cascade",
     "cli",
     "common",
     "concurrency",
@@ -11,7 +13,9 @@ members = [
     "dpdk",
     "dpdk-sys",
     "dpdk-sysroot-helper",
+    "dpdk-test-macros",
     "errno",
+    "fixed-size",
     "flow-entry",
     "flow-filter",
     "hardware",
@@ -22,7 +26,10 @@ members = [
     "k8s-less",
     "left-right-tlcache",
     "lifecycle",
+    "lookup",
     "lpm",
+    "match-action",
+    "match-action-derive",
     "mgmt",
     "nat",
     "net",
@@ -59,7 +66,9 @@ repository = "https://github.com/githedgehog/dataplane/"
 # justifying why it is workspace-wide.
 
 # Internal
+acl = { path = "./acl", package = "dataplane-acl", features = [] }
 args = { path = "./args", package = "dataplane-args", features = [] }
+cascade = { path = "./cascade", package = "dataplane-cascade", features = [] }
 cli = { path = "./cli", package = "dataplane-cli", features = [] }
 common = { path = "./common", package = "dataplane-common", features = [] }
 concurrency = { path = "./concurrency", package = "dataplane-concurrency", features = [] }
@@ -68,8 +77,10 @@ config = { path = "./config", package = "dataplane-config", features = [] }
 dpdk = { path = "./dpdk", package = "dataplane-dpdk", features = [] }
 dpdk-sys = { path = "./dpdk-sys", package = "dataplane-dpdk-sys", features = [] }
 dpdk-sysroot-helper = { path = "./dpdk-sysroot-helper", package = "dataplane-dpdk-sysroot-helper", features = [] }
+dpdk-test-macros = { path = "./dpdk-test-macros", package = "dataplane-dpdk-test-macros", features = [] }
 dplane-rpc = { git = "https://github.com/githedgehog/dplane-rpc.git", rev = "e8fc33db10e1d00785f2a2b90cbadcad7900f200", features = [] }
 errno = { path = "./errno", package = "dataplane-errno", features = [] }
+fixed-size = { path = "./fixed-size", package = "dataplane-fixed-size", features = [] }
 flow-entry = { path = "./flow-entry", package = "dataplane-flow-entry", features = [] }
 flow-filter = { path = "./flow-filter", package = "dataplane-flow-filter", features = [] }
 hardware = { path = "./hardware", package = "dataplane-hardware", features = [] }
@@ -80,7 +91,10 @@ k8s-intf = { path = "./k8s-intf", package = "dataplane-k8s-intf", default-featur
 k8s-less = { path = "./k8s-less", package = "dataplane-k8s-less", features = [] }
 left-right-tlcache = { path = "./left-right-tlcache", package = "dataplane-left-right-tlcache", features = [] }
 lifecycle = { path = "./lifecycle", package = "dataplane-lifecycle", features = [] }
+lookup = { path = "./lookup", package = "dataplane-lookup", features = [] }
 lpm = { path = "./lpm", package = "dataplane-lpm", features = [] }
+match-action = { path = "./match-action", package = "dataplane-match-action", features = [] }
+match-action-derive = { path = "./match-action-derive", package = "dataplane-match-action-derive", features = [] }
 mgmt = { path = "./mgmt", package = "dataplane-mgmt", features = [] }
 nat = { path = "./nat", package = "dataplane-nat", features = [] }
 net = { path = "./net", package = "dataplane-net", features = [] }
@@ -113,6 +127,7 @@ bytes = { version = "1.11.1", default-features = false, features = [] }
 caps = { version = "0.5.6", default-features = false, features = [] }
 chrono = { version = "0.4.44", default-features = false, features = [] }
 clap = { version = "4.6.1", default-features = true, features = [] }
+criterion = { version = "0.5.1", default-features = false, features = ["cargo_bench_support"] }
 color-eyre = { version = "0.6.5", default-features = false, features = [] }
 colored = { version = "3.1.1", default-features = false, features = [] }
 crossbeam-utils = { version = "0.8.21", default-features = false, features = [] }

Cargo.toml

@@ -0,0 +1,47 @@
+[package]
+name = "dataplane-acl"
+edition.workspace = true
+license.workspace = true
+publish.workspace = true
+version.workspace = true
+
+[features]
+default = ["dpdk"]
+# Enables the DPDK `rte_acl` backend for `cascade::Lookup`.  Pulls in
+# the `dpdk` crate (and transitively `dpdk-sys`), so off by default;
+# only the production binary / DPDK-bound consumers turn it on.
+dpdk = ["dep:dpdk", "dep:thiserror"]
+
+[dependencies]
+arrayvec = { workspace = true, default-features = true }
+concurrency = { workspace = true, features = [] }
+dpdk = { workspace = true, optional = true }
+lookup = { workspace = true, features = [] }
+match-action = { workspace = true, features = ["derive"] }
+net = { workspace = true, features = [] }
+thiserror = { workspace = true, optional = true }
+
+[dev-dependencies]
+# Differential oracle harness: random rulesets + packets compared
+# between the reference and DPDK backends.
+bolero = { workspace = true, features = ["std"] }
+criterion = { workspace = true }
+# Override the regular `dpdk` dep to enable its `test` feature
+# (exposes `dpdk::test_support::start_eal` and `dpdk::with_eal`).
+dpdk = { workspace = true, features = ["test"] }
+# Override match-action to also enable `bolero` for property-test
+# generators (`FieldHit` / `FieldMiss`).
+match-action = { workspace = true, features = ["derive", "bolero"] }
+net = { workspace = true, features = ["test_buffer", "builder"] }
+
+[[bench]]
+name = "reference_five_tuple"
+harness = false
+
+[[bench]]
+name = "dpdk_five_tuple"
+harness = false
+
+[[bench]]
+name = "table_build"
+harness = false

acl/Cargo.toml

@@ -0,0 +1,240 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright Open Network Fabric Authors
+
+//! Criterion benchmark for DPDK `rte_acl` 5-tuple lookup at IPv4 and
+//! IPv6 widths.  Companion to `reference_five_tuple`; same rule-count
+//! sweep, miss vs hit, single-shot vs SIMD batch.  `rte_acl` compiles
+//! rules into a trie walked by the input bytes, so lookup cost is
+//! roughly flat in rule count -- contrast with the reference's `O(n)`
+//! linear scan.  The v6 path exercises the wide-field split (one
+//! 16-byte address -> four 4-byte sub-fields).  Requires a live EAL:
+//! `cargo bench -p dataplane-acl --bench dpdk_five_tuple`.
+
+#![allow(clippy::unwrap_used, clippy::expect_used)]
+
+#[cfg(feature = "dpdk")]
+mod bench {
+    use core::net::{Ipv4Addr, Ipv6Addr};
+    use core::num::NonZero;
+
+    use criterion::measurement::WallTime;
+    use criterion::{BenchmarkGroup, BenchmarkId, Criterion, Throughput, black_box};
+
+    use dataplane_acl::dpdk::install::install_table;
+    use dataplane_acl::dpdk::lookup::DpdkAclLookup;
+    use dataplane_acl::dpdk::rule::{Dpdk, RuleSpec};
+    use dataplane_acl::dpdk_table_alias;
+    use dpdk::acl::{CategoryMask, Priority};
+    use lookup::Lookup;
+    use match_action::{ExactSpec, MatchKey, PrefixSpec, RangeSpec};
+
+    #[derive(MatchKey)]
+    struct FiveTuple {
+        #[exact]
+        proto: u8,
+        #[prefix]
+        src: Ipv4Addr,
+        #[prefix]
+        dst: Ipv4Addr,
+        #[range]
+        sport: u16,
+        #[range]
+        dport: u16,
+    }
+
+    #[derive(MatchKey)]
+    struct FiveTuple6 {
+        #[exact]
+        proto: u8,
+        #[prefix]
+        src: Ipv6Addr,
+        #[prefix]
+        dst: Ipv6Addr,
+        #[range]
+        sport: u16,
+        #[range]
+        dport: u16,
+    }
+
+    dpdk_table_alias!(type FiveTupleTable<A> = FiveTuple);
+    dpdk_table_alias!(type FiveTuple6Table<A> = FiveTuple6);
+
+    /// Rule-count sweep: powers of two from 1 to 16384.
+    const RULE_COUNTS: [usize; 15] = [
+        1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192, 16384,
+    ];
+
+    /// Batch size for the SIMD path; matches `MAX_BATCH` in the backend.
+    const BATCH: usize = 32;
+
+    /// `n` IPv4 rules sharing every field except a distinct `dport`,
+    /// mirroring the reference bench for direct comparison.  Action is
+    /// the rule index.
+    fn build_table_v4(n: usize) -> FiveTupleTable<u32> {
+        let specs: Vec<RuleSpec<FiveTuple, u32>> = (0..n)
+            .map(|i| {
+                let prio = i32::try_from(i + 1).unwrap_or(i32::MAX);
+                let dport = u16::try_from(i).unwrap_or(u16::MAX);
+                let action = u32::try_from(i).unwrap_or(u32::MAX);
+                RuleSpec::new(
+                    Priority::new(prio).expect("nonzero priority"),
+                    CategoryMask::new(1).expect("nonzero mask"),
+                    FiveTupleRule {
+                        proto: ExactSpec::new(6),
+                        src: PrefixSpec::new(Ipv4Addr::new(10, 0, 0, 0), 8),
+                        dst: PrefixSpec::new(Ipv4Addr::UNSPECIFIED, 0),
+                        sport: RangeSpec::new(0, u16::MAX),
+                        dport: RangeSpec::exact(dport),
+                    }
+                    .into_backend_fields::<Dpdk>(),
+                    action,
+                )
+                .expect("valid RuleSpec")
+            })
+            .collect();
+        let max_rules = NonZero::new(u32::try_from(n).unwrap_or(u32::MAX)).expect("n >= 1");
+        install_table(&format!("bench_dpdk_v4_{n}"), max_rules, 1, specs).expect("install_table")
+    }
+
+    /// IPv6 analog of [`build_table_v4`]; the 16-byte source prefix
+    /// exercises the wide-field split.
+    fn build_table_v6(n: usize) -> FiveTuple6Table<u32> {
+        let src: Ipv6Addr = "2001:db8::".parse().expect("v6 literal");
+        let specs: Vec<RuleSpec<FiveTuple6, u32>> = (0..n)
+            .map(|i| {
+                let prio = i32::try_from(i + 1).unwrap_or(i32::MAX);
+                let dport = u16::try_from(i).unwrap_or(u16::MAX);
+                let action = u32::try_from(i).unwrap_or(u32::MAX);
+                RuleSpec::new(
+                    Priority::new(prio).expect("nonzero priority"),
+                    CategoryMask::new(1).expect("nonzero mask"),
+                    FiveTuple6Rule {
+                        proto: ExactSpec::new(6),
+                        src: PrefixSpec::new(src, 32),
+                        dst: PrefixSpec::new(Ipv6Addr::UNSPECIFIED, 0),
+                        sport: RangeSpec::new(0, u16::MAX),
+                        dport: RangeSpec::exact(dport),
+                    }
+                    .into_backend_fields::<Dpdk>(),
+                    action,
+                )
+                .expect("valid RuleSpec")
+            })
+            .collect();
+        let max_rules = NonZero::new(u32::try_from(n).unwrap_or(u32::MAX)).expect("n >= 1");
+        install_table(&format!("bench_dpdk_v6_{n}"), max_rules, 1, specs).expect("install_table")
+    }
+
+    /// Single-shot (miss + hit) and SIMD-batch lookup benches for one
+    /// width.  Generic over field/stride extents and key type so v4
+    /// and v6 share one body.
+    fn run_lookups<K, const N: usize, const STRIDE: usize>(
+        group: &mut BenchmarkGroup<'_, WallTime>,
+        n: usize,
+        table: &DpdkAclLookup<N, STRIDE, u32>,
+        miss: &K,
+        hit: &K,
+        batch: &[K],
+    ) where
+        K: MatchKey,
+    {
+        // Single-shot: one rte_acl_classify per packet, forfeits SIMD.
+        group.throughput(Throughput::Elements(1));
+        group.bench_function(BenchmarkId::new("single_miss", n), |b| {
+            b.iter(|| black_box(table.lookup(black_box(miss))));
+        });
+        group.bench_function(BenchmarkId::new("single_hit", n), |b| {
+            b.iter(|| black_box(table.lookup(black_box(hit))));
+        });
+
+        // Batch: one rte_acl_classify across BATCH packets; per-element
+        // throughput reports the amortized per-packet cost.
+        group.throughput(Throughput::Elements(
+            u64::try_from(batch.len()).unwrap_or(0),
+        ));
+        group.bench_function(BenchmarkId::new("batch", n), |b| {
+            let mut out: [Option<&u32>; BATCH] = [None; BATCH];
+            b.iter(|| {
+                table
+                    .lookup_batch(black_box(batch), &mut out)
+                    .expect("batch");
+                black_box(&out);
+            });
+        });
+    }
+
+    fn bench_v4(c: &mut Criterion) {
+        let batch: Vec<FiveTuple> = (0..BATCH)
+            .map(|j| FiveTuple {
+                proto: 6,
+                src: Ipv4Addr::new(10, 0, 0, 1),
+                dst: Ipv4Addr::new(192, 0, 2, 1),
+                sport: 1234,
+                dport: u16::try_from(j).unwrap_or(0),
+            })
+            .collect();
+
+        let mut group = c.benchmark_group("dpdk_five_tuple_v4");
+        for n in RULE_COUNTS {
+            let table = build_table_v4(n);
+            // `dport = u16::MAX` is carried by no rule -> miss; `0` hits
+            // the first rule.
+            let miss = FiveTuple {
+                proto: 6,
+                src: Ipv4Addr::new(10, 0, 0, 1),
+                dst: Ipv4Addr::new(192, 0, 2, 1),
+                sport: 1234,
+                dport: u16::MAX,
+            };
+            let hit = FiveTuple { dport: 0, ..miss };
+            run_lookups(&mut group, n, &table, &miss, &hit, &batch);
+        }
+        group.finish();
+    }
+
+    fn bench_v6(c: &mut Criterion) {
+        let in_prefix: Ipv6Addr = "2001:db8::1".parse().expect("v6 literal");
+        let dst: Ipv6Addr = "::1".parse().expect("v6 literal");
+        let batch: Vec<FiveTuple6> = (0..BATCH)
+            .map(|j| FiveTuple6 {
+                proto: 6,
+                src: in_prefix,
+                dst,
+                sport: 1234,
+                dport: u16::try_from(j).unwrap_or(0),
+            })
+            .collect();
+
+        let mut group = c.benchmark_group("dpdk_five_tuple_v6");
+        for n in RULE_COUNTS {
+            let table = build_table_v6(n);
+            let miss = FiveTuple6 {
+                proto: 6,
+                src: in_prefix,
+                dst,
+                sport: 1234,
+                dport: u16::MAX,
+            };
+            let hit = FiveTuple6 { dport: 0, ..miss };
+            run_lookups(&mut group, n, &table, &miss, &hit, &batch);
+        }
+        group.finish();
+    }
+
+    pub fn benches(c: &mut Criterion) {
+        // OnceLock-backed: one EAL per process.
+        let _eal = dpdk::test_support::start_eal();
+        bench_v4(c);
+        bench_v6(c);
+    }
+}
+
+#[cfg(feature = "dpdk")]
+criterion::criterion_group!(benchmarks, bench::benches);
+#[cfg(feature = "dpdk")]
+criterion::criterion_main!(benchmarks);
+
+// No EAL backend without the `dpdk` feature; a no-op `main` keeps the
+// `harness = false` target linkable.
+#[cfg(not(feature = "dpdk"))]
+fn main() {}