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

["Medvedkin, Vladimir" <vladimir.medvedkin@intel.com>]

Acked-by: Vladimir Medvedkin <vladimir.medvedkin@intel.com>

On 10/29/2025 3:17 PM, 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@intel.com>
> ---
>   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.
> +
> +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.
> +
> +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.
> +
> +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
> +
> +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
>   ~~~~~~~~~~~~~~~~~~~~~~~~~~
>   

-- 
Regards,
Vladimir