flow_parser: add shared parser library

This series extracts the testpmd flow CLI parser into a reusable library, enabling external applications to parse rte_flow rules using testpmd syntax.

Motivation
----------
External applications like Suricata IDS [1] need to express hardware filtering rules in a consistent, human-readable format. Rather than inventing custom syntax, reusing testpmd's well-tested flow grammar provides immediate compatibility with existing documentation and user knowledge.

Note: This library provides only one way to create rte_flow structures. Applications can also construct rte_flow_attr, rte_flow_item[], and rte_flow_action[] directly in C code.

Design
------
The library (librte_flow_parser) exposes the following APIs:
- rte_flow_parser_parse_attr_str(): Parse attributes only
- rte_flow_parser_parse_pattern_str(): Parse patterns only
- rte_flow_parser_parse_actions_str(): Parse actions only

Testpmd is updated to use the library, ensuring a single maintained parser implementation.

Testing and Demo
-------
- Functional tests in dpdk-test
- Example application: examples/flow_parsing

Changes
-------
v11:
- targetting 26.07 now
- MAJOR overhaul of the patch set to make every part of the library API public and reusable, while only parsing flow testpmd commands.
- library splitted into a "simple" part and "cmdline" part
- testpmd changed to use the "cmdline" part of the library, and also to handle most of the "set" commands itself, while still using the library to parse the parameters of the "set" commands. Previous "operation callbacks" are now replaced by command-codes (enum) and the caller is expected to handle the command execution itself. Likewise, the ownership of helper structures, e.g. for vxlan/raw/sample etc. is in the hands of the caller, and the library only uses/fills them in with the parsed parameters.

v10:
- rebased to avoid Github Actions CI build failure
- merge conflict solved in rel_notes/release_26_03.rst
- release notes shortened

v9:
- removed extra new line from the flow parser docs file

v8:
- rte_port/queue_id_t typedefs removal to be included in a separate patch series
- move of accidental changes of rte_flow parser library from the testpmd commit
- DynaNIC copyright name update

v7:
- Fixed implicit integer comparison (while (left) -> while (left != 0))
- NULL checks fixed
- arpa header removed for Windows compatibility
- minor comments from the last review addressed

v6:
- Inconsistent Experimental API Version adjusted
- Fixes Tag added to MSVC build commit
- Non-Standard Header Guards updated
- Implicit Pointer Comparison and Return Type issues addressed in many places
- commit message in patch 6 updated

v5:
- removed/replaced (f)printf code from the library
- reverted back to exporting the internal/private API as it is needed by testpmd and cannot be easily split further.
- adjusted length of certain lines
- marking port/queue id typedef as experimental
- updated release rel_notes
- copyeright adjustments

v4:
- ethdev changes in separate commit
- library's public API only exposes attribute, pattern and action parsing, while the full command parsing is kept internal for testpmd usage only.
- Addressed Stephen's comments from V3
- dpdk-test now have tests focused on public and internal library functions

v3:
- Add more functional tests
- More concise MAINTAINERS updates
- Updated license headers
- A thing to note: When playing with flow commands, I figured, some may use non-flow commands, such as raw decap/encap, policy meter and others. Flow parser library itself now supports set command to set e.g. the decap/ encap parameters, as the flow syntax only supports defining the index of the encap/decap configs. The library, however, does not support e.g. create command to create policy meters, as that is just an ID and it can be created separately using rte_meter APIs.

[1] https://github.com/OISF/suricata/pull/13950

Lukas Sismis (6):
cmdline: include stddef.h for MSVC compatibility
ethdev: add RSS type helper APIs
ethdev: add flow parser library app/testpmd: use flow parser from ethdev examples/flow_parsing: add flow parser demo
test: add flow parser functional tests

 MAINTAINERS                                   |     6 +-
 app/test-pmd/cmd_flex_item.c                  |    47 +-
 app/test-pmd/cmdline.c                        |   249 +-
 app/test-pmd/config.c                         |   115 +-
 app/test-pmd/flow_parser.c                    |   288 +
 app/test-pmd/flow_parser_cli.c                |   479 +
 app/test-pmd/meson.build                      |     3 +-
 app/test-pmd/testpmd.h                        |   135 +-
 app/test/meson.build                          |     2 +
 app/test/test_ethdev_api.c                    |    56 +
 app/test/test_flow_parser.c                   |   791 +
 app/test/test_flow_parser_simple.c            |   445 +
 doc/api/doxy-api-index.md                     |     2 +
 doc/guides/prog_guide/flow_parser_lib.rst     |    99 +
 doc/guides/prog_guide/index.rst               |     1 +
 doc/guides/rel_notes/release_26_07.rst        |    11 +
 doc/guides/sample_app_ug/flow_parsing.rst     |    60 +
 doc/guides/sample_app_ug/index.rst            |     1 +
 examples/flow_parsing/main.c                  |   409 +
 examples/flow_parsing/meson.build             |     8 +
 examples/meson.build                          |     1 +
 lib/cmdline/cmdline_parse.h                   |     2 +
 lib/ethdev/meson.build                        |     5 +-
 lib/ethdev/rte_ethdev.c                       |   109 +
 lib/ethdev/rte_ethdev.h                       |    60 +
 .../ethdev/rte_flow_parser.c                  | 12250 ++++++++--------
 lib/ethdev/rte_flow_parser.h                  |   130 +
 lib/ethdev/rte_flow_parser_cmdline.h          |   739 +
 lib/meson.build                               |     2 +-
 29 files changed, 9936 insertions(+), 6569 deletions(-)
 create mode 100644 app/test-pmd/flow_parser.c
 create mode 100644 app/test-pmd/flow_parser_cli.c
 create mode 100644 app/test/test_flow_parser.c
 create mode 100644 app/test/test_flow_parser_simple.c
 create mode 100644 doc/guides/prog_guide/flow_parser_lib.rst
 create mode 100644 doc/guides/sample_app_ug/flow_parsing.rst
 create mode 100644 examples/flow_parsing/main.c
 create mode 100644 examples/flow_parsing/meson.build
 rename app/test-pmd/cmdline_flow.c => lib/ethdev/rte_flow_parser.c (59%)
 create mode 100644 lib/ethdev/rte_flow_parser.h
 create mode 100644 lib/ethdev/rte_flow_parser_cmdline.h

2.43.7

Include <stddef.h> at the top of cmdline_parse.h before the fallback offsetof macro definition. This improves MSVC build compatibility by ensuring the standard offsetof is available before the fallback definition, avoiding macro redefinition warnings when building with /WX (warnings as errors).

The standard header provides offsetof on all platforms, and including it first ensures the fallback is only used when truly needed.

---
 lib/cmdline/cmdline_parse.h | 2 ++
 1 file changed, 2 insertions(+)

index d9a7d86256..c4131e4af5 100644
@@ -7,6 +7,8 @@
 #ifndef _CMDLINE_PARSE_H_
 #define _CMDLINE_PARSE_H_
 
+#include <stddef.h>
+
 #ifdef __cplusplus
 extern "C" {
 #endif

2.43.7

Add a global RSS type string table and helper functions to convert between RSS type names and values.
Add unit tests for RSS type helper.

---
 app/test/test_ethdev_api.c             |  56 +++++++++++++
 doc/guides/rel_notes/release_26_07.rst |   5 ++
 lib/ethdev/rte_ethdev.c                | 109 +++++++++++++++++++++++++
 lib/ethdev/rte_ethdev.h                |  60 ++++++++++++++
 4 files changed, 230 insertions(+)

index 76afd0345c..ab0e018c60 100644
@@ -2,6 +2,9 @@
  * Copyright (C) 2023, Advanced Micro Devices, Inc.
  */
 
+#include <stdbool.h>
+#include <string.h>
+
 #include <rte_log.h>
 #include <rte_ethdev.h>
 

@@ -162,12 +165,65 @@ ethdev_api_queue_status(void)
 	return TEST_SUCCESS;
 }
 
+static int
+ethdev_api_rss_type_helpers(void)
+{
+	const struct rte_eth_rss_type_info *tbl;
+	const char *zero_name = NULL;
+	unsigned int i;
+	bool has_zero = false;
+	const char *name;
+	uint64_t type;
+
+	tbl = rte_eth_rss_type_info_get();
+	TEST_ASSERT_NOT_NULL(tbl, "rss type table missing");
+
+	for (i = 0; tbl[i].str != NULL; i++) {
+		TEST_ASSERT_SUCCESS(rte_eth_rss_type_from_str(tbl[i].str,
+			&type), "rss type lookup failed for %s", tbl[i].str);
+		TEST_ASSERT_EQUAL(type, tbl[i].rss_type,
+			"rss type mismatch for %s", tbl[i].str);
+
+		if (tbl[i].rss_type == 0 && !has_zero) {
+			has_zero = true;
+			zero_name = tbl[i].str;
+		}
+
+		name = rte_eth_rss_type_to_str(tbl[i].rss_type);
+		TEST_ASSERT_NOT_NULL(name, "rss type name missing for %s",
+			tbl[i].str);
+		TEST_ASSERT_SUCCESS(rte_eth_rss_type_from_str(name, &type),
+			"rss type round-trip lookup failed for %s", name);
+		TEST_ASSERT_EQUAL(type, tbl[i].rss_type,
+			"rss type round-trip mismatch for %s", name);
+	}
+
+	TEST_ASSERT(tbl[i].str == NULL, "rss type table not NULL terminated");
+	TEST_ASSERT(rte_eth_rss_type_from_str(NULL, &type) != 0,
+		"rss type from NULL str should fail");
+	TEST_ASSERT(rte_eth_rss_type_from_str("ipv4", NULL) != 0,
+		"rss type from NULL rss_type should fail");
+	TEST_ASSERT(rte_eth_rss_type_from_str("not-a-type", &type) != 0,
+		"rss type unknown should fail");
+	name = rte_eth_rss_type_to_str(0);
+	if (has_zero) {
+		TEST_ASSERT_NOT_NULL(name, "rss type 0 should be defined");
+		TEST_ASSERT(strcmp(name, zero_name) == 0,
+			"rss type 0 name mismatch");
+	} else {
+		TEST_ASSERT(name == NULL, "rss type 0 should be NULL");
+	}
+
+	return TEST_SUCCESS;
+}
+
 static struct unit_test_suite ethdev_api_testsuite = {
 	.suite_name = "ethdev API tests",
 	.setup = NULL,
 	.teardown = NULL,
 	.unit_test_cases = {
 		TEST_CASE(ethdev_api_queue_status),
+		TEST_CASE(ethdev_api_rss_type_helpers),
 		/* TODO: Add deferred_start queue status test */
 		TEST_CASES_END() /**< NULL terminate unit test array */
 	}

index 060b26ff61..e58c3365b6 100644
@@ -55,6 +55,11 @@ New Features
      Also, make sure to start the actual text at the margin.
      =======================================================
 
+* **Added experimental RSS type helper APIs in ethdev.**
+
+  * Added new APIs to convert between RSS type names and values.
+  * Added new API call to obtain the global RSS string table.
+
 
 Removed Items
 -------------

2.43.7

Add flow rule string parsing to librte_ethdev. The parser converts flow command strings into rte_flow C structures.

Two public headers:

- rte_flow_parser.h: standalone string-to-struct helpers for attributes, patterns, and actions. Thread-safe per-lcore.
- rte_flow_parser_cmdline.h: full command parsing with cmdline dynamic token integration and tab completion. Applications register configuration storage via rte_flow_parser_config and receive parsed commands through a dispatch callback.

Configuration is application-owned: the library stores no mutable config state. Applications allocate encap/decap, raw, ipv6_ext, and sample slot storage and register pointers at init time.

Setter APIs serialize pattern/action items into raw encap/decap and ipv6 extension configurations.

---
 MAINTAINERS                               |     2 +-
 doc/api/doxy-api-index.md                 |     2 +
 doc/guides/prog_guide/flow_parser_lib.rst |    99 +
 doc/guides/prog_guide/index.rst           |     1 +
 doc/guides/rel_notes/release_26_07.rst    |     6 +
 lib/ethdev/meson.build                    |     5 +-
 lib/ethdev/rte_flow_parser.c              | 14270 ++++++++++++++++++++
 lib/ethdev/rte_flow_parser.h              |   130 +
 lib/ethdev/rte_flow_parser_cmdline.h      |   739 +
 lib/meson.build                           |     2 +-
 10 files changed, 15253 insertions(+), 3 deletions(-)
 create mode 100644 doc/guides/prog_guide/flow_parser_lib.rst
 create mode 100644 lib/ethdev/rte_flow_parser.c
 create mode 100644 lib/ethdev/rte_flow_parser.h
 create mode 100644 lib/ethdev/rte_flow_parser_cmdline.h

index 0f5539f851..c4bc6632cc 100644
@@ -444,8 +444,8 @@ F: doc/guides/prog_guide/ethdev/switch_representation.rst
 Flow API
 M: Ori Kam <[email protected]>
 T: git://dpdk.org/next/dpdk-next-net
-F: app/test-pmd/cmdline_flow.c
 F: doc/guides/prog_guide/ethdev/flow_offload.rst
+F: doc/guides/prog_guide/flow_parser_lib.rst
 F: lib/ethdev/rte_flow*
 
 Traffic Management API

index 9296042119..c4e3fac841 100644
@@ -13,6 +13,8 @@ The public API headers are grouped by topics:
   [ethdev](@ref rte_ethdev.h),
   [ethctrl](@ref rte_eth_ctrl.h),
   [rte_flow](@ref rte_flow.h),
+  [flow_parser](@ref rte_flow_parser.h),
+  [flow_parser_cmdline](@ref rte_flow_parser_cmdline.h),
   [rte_tm](@ref rte_tm.h),
   [rte_mtr](@ref rte_mtr.h),
   [bbdev](@ref rte_bbdev.h),

index e6f24945b0..3530cf8128 100644
@@ -121,6 +121,7 @@ Utility Libraries
 
     argparse_lib
     cmdline
+    flow_parser_lib
     ptr_compress_lib
     timer_lib
     rcu_lib

index e58c3365b6..1ba21b096f 100644
@@ -60,6 +60,12 @@ New Features
   * Added new APIs to convert between RSS type names and values.
   * Added new API call to obtain the global RSS string table.
 
+* **Added experimental flow parser to ethdev.**
+
+  * Introduced ``rte_flow_parser`` helpers in ethdev to convert the
+    testpmd's ``flow`` CLI commands into ``rte_flow`` structures.
+    See ``rte_flow_parser.h`` and ``rte_flow_parser_cmdline.h``.
+
 
 Removed Items
 -------------

index 8ba6c708a2..05190a63b9 100644
@@ -11,6 +11,7 @@ sources = files(
         'rte_ethdev_cman.c',
         'rte_ethdev_telemetry.c',
         'rte_flow.c',
+        'rte_flow_parser.c',
         'rte_mtr.c',
         'rte_tm.c',
         'sff_telemetry.c',

@@ -26,6 +27,8 @@ headers = files(
         'rte_ethdev_trace_fp.h',
         'rte_dev_info.h',
         'rte_flow.h',
+        'rte_flow_parser.h',
+        'rte_flow_parser_cmdline.h',
         'rte_mtr.h',
         'rte_tm.h',
 )

@@ -53,7 +56,7 @@ if is_linux
     )
 endif
 
-deps += ['net', 'kvargs', 'meter', 'telemetry']
+deps += ['net', 'kvargs', 'meter', 'telemetry', 'cmdline']
 
 if is_freebsd
     annotate_locks = false

index 8f5cfd28a5..d534e803a7 100644

2.43.7

Part of the diff is not shown here. View the raw message.

Replace the embedded flow command parser with the shared parser from librte_ethdev.

Testpmd owns all configuration storage (encap/decap, raw, ipv6_ext, sample slots) and registers it via rte_flow_parser_config_register. Parsed flow commands are dispatched to port_flow_* functions.

SET commands (raw_encap, raw_decap, sample_actions, ipv6_ext_push, ipv6_ext_remove) are handled by testpmd's own cmdline callback, which delegates pattern/action item tokenization to the library for tab completion.

---
 MAINTAINERS                    |     1 +
 app/test-pmd/cmd_flex_item.c   |    47 +-
 app/test-pmd/cmdline.c         |   249 +-
 app/test-pmd/cmdline_flow.c    | 14434 -------------------------------
 app/test-pmd/config.c          |   115 +-
 app/test-pmd/flow_parser.c     |   288 +
 app/test-pmd/flow_parser_cli.c |   479 +
 app/test-pmd/meson.build       |     3 +-
 app/test-pmd/testpmd.h         |   135 +-
 9 files changed, 958 insertions(+), 14793 deletions(-)
 delete mode 100644 app/test-pmd/cmdline_flow.c
 create mode 100644 app/test-pmd/flow_parser.c
 create mode 100644 app/test-pmd/flow_parser_cli.c

index c4bc6632cc..fdd0555bb4 100644
@@ -446,6 +446,7 @@ M: Ori Kam <[email protected]>
 T: git://dpdk.org/next/dpdk-next-net
 F: doc/guides/prog_guide/ethdev/flow_offload.rst
 F: doc/guides/prog_guide/flow_parser_lib.rst
+F: app/test-pmd/flow_parser*
 F: lib/ethdev/rte_flow*
 
 Traffic Management API

index 83163a5406..459082ac00 100644

2.43.7

Part of the diff is not shown here. View the raw message.

Add a standalone example demonstrating the flow parser API. Parses attribute, pattern, and action strings into rte_flow structures and prints the results.

---
 MAINTAINERS                               |   2 +
 doc/guides/sample_app_ug/flow_parsing.rst |  60 ++++
 doc/guides/sample_app_ug/index.rst        |   1 +
 examples/flow_parsing/main.c              | 409 ++++++++++++++++++++++
 examples/flow_parsing/meson.build         |   8 +
 examples/meson.build                      |   1 +
 6 files changed, 481 insertions(+)
 create mode 100644 doc/guides/sample_app_ug/flow_parsing.rst
 create mode 100644 examples/flow_parsing/main.c
 create mode 100644 examples/flow_parsing/meson.build

index fdd0555bb4..fdd841c835 100644
@@ -448,6 +448,8 @@ F: doc/guides/prog_guide/ethdev/flow_offload.rst
 F: doc/guides/prog_guide/flow_parser_lib.rst
 F: app/test-pmd/flow_parser*
 F: lib/ethdev/rte_flow*
+F: doc/guides/sample_app_ug/flow_parsing.rst
+F: examples/flow_parsing/
 
 Traffic Management API
 M: Cristian Dumitrescu <[email protected]>

index e895f692f9..eadea67569 100644
@@ -16,6 +16,7 @@ Sample Applications User Guides
     skeleton
     rxtx_callbacks
     flow_filtering
+    flow_parsing
     ip_frag
     ipv4_multicast
     ip_reassembly

new file mode 100644
index 0000000000..83554409d1
@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2026 DynaNIC Semiconductors, Ltd.
+
+# meson file, for building this example as part of a main DPDK build.
+
+allow_experimental_apis = true
+deps += 'ethdev'
+sources = files('main.c')

index 25d9c88457..22f45e8c81 100644
@@ -17,6 +17,7 @@ all_examples = [
         'eventdev_pipeline',
         'fips_validation',
         'flow_filtering',
+        'flow_parsing',
         'helloworld',
         'ip_fragmentation',
         'ip_pipeline',

2.43.7

Unit tests covering:

- Simple API: parse_attr_str, parse_pattern_str, parse_actions_str, parse_flow_rule
- Cmdline API: rte_flow_parser_parse with flow create, validate, indirect_action, meter, modify_field, queue, and port_id commands
- Setter APIs: raw_encap/decap set + get round-trip, boundary checks for out-of-range indices
- Config registration: pointer identity verification
- Cmdline integration: dynamic token population

Simple API tests work without config registration.

---
 MAINTAINERS                        |   1 +
 app/test/meson.build               |   2 +
 app/test/test_flow_parser.c        | 791 +++++++++++++++++++++++++++++
 app/test/test_flow_parser_simple.c | 445 ++++++++++++++++
 4 files changed, 1239 insertions(+)
 create mode 100644 app/test/test_flow_parser.c
 create mode 100644 app/test/test_flow_parser_simple.c

index fdd841c835..42e3f7674b 100644
@@ -450,6 +450,7 @@ F: app/test-pmd/flow_parser*
 F: lib/ethdev/rte_flow*
 F: doc/guides/sample_app_ug/flow_parsing.rst
 F: examples/flow_parsing/
+F: app/test/test_flow_parser*
 
 Traffic Management API
 M: Cristian Dumitrescu <[email protected]>

index 7d458f9c07..242527516d 100644
@@ -88,6 +88,8 @@ source_file_deps = {
     'test_fib6_perf.c': ['fib'],
     'test_fib_perf.c': ['net', 'fib'],
     'test_flow_classify.c': ['net', 'acl', 'table', 'ethdev', 'flow_classify'],
+    'test_flow_parser.c': ['ethdev', 'cmdline'],
+    'test_flow_parser_simple.c': ['ethdev'],
     'test_func_reentrancy.c': ['hash', 'lpm'],
     'test_graph.c': ['graph'],
     'test_graph_feature_arc.c': ['graph'],

2.43.7

Better, no callbacks but still has a big problem. Making every application suck in cmdline is bad idea. Maybe flow parser needs to be part of cmdline not ethdev? In current form, this patch is not something I would accept.

Long winded AI review attached:
=== Patch Review: flow_parser v11 (via Claude) ===

Patch 2/6: ethdev: add RSS type helper APIs

No issues found — patch omitted from review.

Patch 3/6: ethdev: add flow parser library

Warning: Adding cmdline as a mandatory dependency of libethdev (deps += [..., 'cmdline']) means every application linking ethdev now pulls in the cmdline library even if it never uses the flow parser. The flow parser should be a separate library (librte_flow_parser) that depends on both ethdev and cmdline, rather than embedding it inside ethdev and inflicting the cmdline dependency on all ethdev consumers. The cover letter says "The library (librte_flow_parser)" but the implementation puts everything into lib/ethdev/.

Warning: rte_flow_parser_parse_flow_rule() returns pointers into static internal storage (flow_parser_simple_parse_buf) but its Doxygen does not say so. The individual helpers (parse_pattern_str, parse_actions_str) document "Points to internal storage valid until the next parse call" — the same caveat must appear on parse_flow_rule's pattern and actions output parameters. Without it, callers will assume the returned pointers are stable.

Warning: parser_str_strip_trailing_end() has inconsistent return values. When the input does not end with "/ end", the function returns strlen(src) (preserving trailing whitespace). But when the input is shorter than 3 characters, it returns length with trailing whitespace stripped. If the intent is "strip / end or return full length unchanged," the short-string path should also return strlen(src).

Warning: The RTE_EXPORT_EXPERIMENTAL_SYMBOL() macros are placed in a block at the bottom of rte_flow_parser.c, detached from the function definitions they refer to. In the rest of the DPDK codebase (and in patch 2/6 of this series) the export macro is placed immediately before each function definition. This style inconsistency makes it easy for the export list to drift out of sync with the actual functions.

Info: rte_flow_parser_parse() casts result_size to unsigned int when passing to cmd_flow_parse. The check "result_size > UINT32_MAX" guards against truncation, which is correct, but the function signature accepts size_t while all internal consumers use unsigned int — consider documenting the practical upper bound.

Patch 4/6: app/testpmd: use flow parser from ethdev

No issues found — the dispatch switch correctly covers all command enum values and the tunnel_ops conversion is straightforward. Patch omitted from review.

Patch 5/6: examples/flow_parsing: add flow parser demo

No issues found — patch omitted from review.

Patch 6/6: test: add flow parser functional tests

No issues found — patch omitted from review.

Patch 1/6: cmdline: include stddef.h for MSVC compatibility

No issues found — patch omitted from review.