On Wed, Oct 29, 2025 at 03:17:14PM +0000, Anatoly Burakov wrote:
> Current documentation for protocol agnostic filtering for ICE driver is a
> bit terse and relies on a lot of assumed knowledge. Document the feature
> better and make all of the assumptions explicit.
>
> Signed-off-by: Anatoly Burakov <[email protected]>
> ---
Thanks Anatoly,
review comments inline below.
/Bruce
> doc/guides/nics/ice.rst | 143 +++++++++++++++++++++++++++++++++++++---
> 1 file changed, 133 insertions(+), 10 deletions(-)
>
> diff --git a/doc/guides/nics/ice.rst b/doc/guides/nics/ice.rst
> index 7e9ba23102..cb06abcdbc 100644
> --- a/doc/guides/nics/ice.rst
> +++ b/doc/guides/nics/ice.rst
> @@ -506,20 +506,143 @@ For each engine, a list of supported patterns is
> maintained in a global array
> named ``ice_<engine>_supported_pattern``. The Ice PMD will reject any rule
> with
> a pattern that is not included in the supported list.
>
> +Protocol Agnostic Filtering
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> One notable feature is the ice PMD's ability to leverage the Raw pattern,
> -enabling protocol-agnostic flow offloading. Here is an example of creating
> -a rule that matches an IPv4 destination address of 1.2.3.4 and redirects it
> to
> -queue 3 using a raw pattern::
> -
> - flow create 0 ingress group 2 pattern raw \
> - pattern spec \
> - 00000000000000000000000008004500001400004000401000000000000001020304 \
> - pattern mask \
> - 000000000000000000000000000000000000000000000000000000000000ffffffff \
> - end actions queue index 3 / mark id 3 / end
> +enabling protocol-agnostic flow offloading. This feature allows users to
> create
> +flow rules for any protocol recognized by the hardware parser, by manually
> +specifying the raw packet structure. Therefore, flow offloading can be used
> even
> +in cases where desired protocol isn't explicitly supported by RTE_FLOW
> interface.
> +
A general comment, relevant to all docs. For the rst document files, don't
wrap the lines at/after a column boundary. Instead, it's recommended to
break the lines at a suitable punctuation boundary. This means that editing
the middle of a line is not going to cause rewrapping of all subsequent
lines.
> +Raw Pattern Components
> +++++++++++++++++++++++
> +
> +Raw patterns consist of two key components:
> +
> +**Pattern Spec**
> + An ASCII hexadecimal string representing the complete packet structure
> that defines
> + the packet type and protocol layout. The hardware parser analyzes this
> structure
> + to determine the packet type (PTYPE) and identify protocol headers and
> their offsets.
> + This specification must represent a valid packet structure that the
> hardware
> + can parse and classify. If the hardware parser does not support a
> particular protocol
> + stack, it may not correctly identify the packet type.
> +
> +**Pattern Mask**
> + An ASCII hexadecimal string of the same length as the spec that determines
> which specific
> + fields within the packet will be extracted and used for matching. The mask
> controls
> + field extraction without affecting the packet type identification.
> +
> +It is important to note that raw pattern must be the only flow item in the
> flow item list.
> +
I think this should be called out in a dedicated NOTE block, or some other
way highlighted.
> +Generating Raw Pattern Values
> ++++++++++++++++++++++++++++++
> +
> +To create raw patterns, follow these steps:
> +
> +1. **Verify parser support**: Confirm that the hardware parser supports the
> protocol
> + combination needed for the intended flow rule. This can be checked against
> + the documentation for the DDP package currently in use.
> +
> +2. **Build the packet template**: Create a complete, valid packet header
> with all
> + necessary sections (Ethernet, IP, UDP/TCP, etc.) using the exact field
> values
> + that need to be matched.
> +
> +3. **Convert to hexadecimal**: Transform the entire header into a continuous
> + ASCII hexadecimal string, with each byte represented as two hex
> characters.
> +
> +4. **Create the extraction mask**: Generate a mask of the same length as the
> spec, where set bits
> + would indicate the fields used for extraction/matching.
> +
> +VPP project's `flow_parse.py` script can be used to generate packet
> templates and masks for raw patterns.
> +This tool takes a human-readable flow description and outputs the
> corresponding ASCII hexadecimal spec and mask.
> +
Can you include a link directly to the script?
> +Example usage:
> +
> +.. code-block:: console
> +
> + python3 flow_parse.py --show -p
> "mac()/ipv4(src=1.1.1.1,dst=2.2.2.2)/udp()"
> +
> +Output:
> +
> + {'flow': {'generic': {'pattern': {'spec':
> b'00000000000100000000000208004500001c000000000011000001010101020202020000000000080000',
> + 'mask':
> b'0000000000000000000000000000000000000000000000000000ffffffffffffffff0000000000000000'}}}}
> +
> +.. note::
> + Ensure the spec represents complete protocol headers, as the hardware
> parser processes
> + fields at 16-bit boundaries. Incomplete or truncated headers may result
> in unpredictable
> + field extraction behavior.
> +
> +Action Support and Usage
> +^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +After constructing the raw pattern spec and mask, they can be used in the
> flow API with pattern type "raw".
> +
> +The following is an example of a minimal Ethernet + IPv4 header template.
> Source and destination IPv4 addresses are
> +part of the match key; all other fields are ignored.
> +
> +Spec (packet template):
> + 000000000001 Destination MAC (6 bytes)
> + 000000000002 Source MAC (6 bytes)
> + 0800 EtherType = IPv4
> + 4500001c0000000000110000 IPv4 header, protocol = UDP
> + 01010101 Source IP = 1.1.1.1
> + 02020202 Destination IP = 2.2.2.2
> + 0000000000080000 UDP header
> +
> +Mask:
> + 000000000000 Destination MAC (ignored)
> + 000000000000 Source MAC (ignored)
> + 0000 EtherType (ignored)
> + 000000000000000000000000 IPv4/UDP header (ignored)
> + ffffffff Source IP (match all 32 bits)
> + ffffffff Destination IP (match all 32 bits)
> + 0000000000000000 UDP header (ignored)
> +
> +This spec will match any non-fragmented IPv4/UDP packet whose source IP is
> 1.1.1.1 and destination IP is 2.2.2.2.
> +
> +Currently, the following actions are supported:
> +
> +- **mark**: Attaches a user-defined integer value to matching packets. Can
> be specified together with another action.
> +
> +- **queue**: Directs matching packets to a specific receive queue.
> +
> +- **drop**: Discards matching packets at the hardware level.
> +
> +- **rss**: Enables Receive Side Scaling (RSS) for matching packets.
> +
> +Constraints:
> + * For RSS, only the global configuration is used; per-rule queue lists or
> RSS keys are not supported.
> +
> +To direct matching packets to a specific queue, and set mbuf FDIR metadata:
> +
> +.. code-block:: console
> +
> + flow create 0 ingress pattern raw \
> + pattern spec
> 00000000000100000000000208004500001c000000000011000001010101020202020000000000080000
> \
> + pattern mask
> 0000000000000000000000000000000000000000000000000000ffffffffffffffff0000000000000000
> / end \
> + actions queue index 3 mark id 3 / end
> +
This is testpmd commands, not C code, right? Can you call that out?
Should some C API calls be included, as end apps are not likely to
configure things using testpmd commands.
> +To use masked bits (IPv4 source/destination addresses) to distribute such
> packets via RSS:
> +
> +.. code-block:: console
> +
> + flow create 0 ingress pattern raw \
> + pattern spec
> 00000000000100000000000208004500001c000000000011000001010101020202020000000000080000
> \
> + pattern mask
> 0000000000000000000000000000000000000000000000000000ffffffffffffffff0000000000000000
> / end \
> + actions rss / end
> +
> +**Limitations**
>
> Currently, raw pattern support is limited to the FDIR and Hash engines.
>
> +.. note::
> +
> + **DDP Package Dependency**: Raw pattern functionality relies on the loaded
> + DDP package to define available packet types and protocol parsing rules.
> + Different DDP packages (OS Default, COMMS, Wireless) may support different
> + protocol combinations and PTYPE mappings.
> +
> Traffic Management Support
> ~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> --
> 2.47.3
>
