[PATCH v2 1/1] doc/ice: document protocol agnostic filtering

[Bruce Richardson]

On Wed, Nov 12, 2025 at 11:34:12AM +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 <anatoly.burakov at intel.com>
> Acked-by: Vladimir Medvedkin <vladimir.medvedkin at intel.com>
> ---
> 
> Notes:
>     v2:
>     - Reformat lines to have complete sentences per line
>     - Added C implementation for testpmd examples
>     - Added link to packetforge script
> 
>  doc/guides/nics/ice.rst | 222 ++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 211 insertions(+), 11 deletions(-)
> 
> diff --git a/doc/guides/nics/ice.rst b/doc/guides/nics/ice.rst
> index 6cc27cefa7..ffa11cf066 100644
> --- a/doc/guides/nics/ice.rst
> +++ b/doc/guides/nics/ice.rst
> @@ -624,20 +624,220 @@ 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.
>  
> -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
> +Protocol Agnostic Filtering
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +One notable feature is the ice PMD's ability to leverage the Raw pattern, 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.
> +
> +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 control field extraction without affecting the packet type identification.
> +
> +.. note::
> +   Raw pattern must be the only flow item in the flow item list.
> +
> +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.
> +This script can be found under ``extras/packetforge`` in `VPP project <https://github.com/FDio/vpp/blob/master/extras/packetforge/flow_parse.py>`_.
> +
> +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'}}}}
> +

This looks like it should have a code-block tag on it too. Was that a
deliberate omission? If it should be there, I'll add it on apply.

> +.. 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
> +

The format of the output in the HTML here is not as above. Again, should
this have a code-block tag on it?

> +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)
> +
<snip>