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

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

[Anatoly Burakov]

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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- 
2.47.3

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

[Medvedkin, Vladimir]

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

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

[Bruce Richardson]

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 <anatoly.burakov@intel.com>
> ---

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
>