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

[Anatoly Burakov <anatoly.burakov@intel.com>]

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>
Acked-by: Vladimir Medvedkin <vladimir.medvedkin@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'}}}}
+
+.. 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 in:
+
+.. code-block:: console
+
+   flow create 0 ingress pattern raw \
+     pattern spec 00000000000100000000000208004500001c000000000011000001010101020202020000000000080000 \
+     pattern mask 0000000000000000000000000000000000000000000000000000ffffffffffffffff0000000000000000 / end \
+     actions queue index 3 mark id 3 / end
+
+Equivalent C code using the ``rte_flow`` API:
+
+.. code-block:: c
+
+   /* Hex string for the packet spec (Ethernet + IPv4 + UDP header) */
+   static const uint8_t raw_pattern_spec[] = {
+       0x00, 0x00, 0x00, 0x00, 0x00, 0x01,  /* Destination MAC */
+       0x00, 0x00, 0x00, 0x00, 0x00, 0x02,  /* Source MAC */
+       0x08, 0x00,                          /* EtherType: IPv4 */
+       0x45, 0x00, 0x00, 0x1c, 0x00, 0x00, 0x00, 0x00,
+       0x00, 0x11, 0x00, 0x00,              /* IPv4 header, protocol UDP */
+       0x01, 0x01, 0x01, 0x01,              /* Source IP: 1.1.1.1 */
+       0x02, 0x02, 0x02, 0x02,              /* Destination IP: 2.2.2.2 */
+       0x00, 0x00, 0x00, 0x00, 0x00, 0x08, 0x00, 0x00  /* UDP header */
+   };
+
+   /* Mask indicating which fields to match (source and destination IPs) */
+   static const uint8_t raw_pattern_mask[] = {
+       0x00, 0x00, 0x00, 0x00, 0x00, 0x00,  /* MAC addresses - ignored */
+       0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+       0x00, 0x00,                          /* EtherType - ignored */
+       0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+       0x00, 0x00, 0x00, 0x00,              /* IPv4/UDP headers - ignored */
+       0xff, 0xff, 0xff, 0xff,              /* Source IP - match all bits */
+       0xff, 0xff, 0xff, 0xff,              /* Destination IP - match all bits */
+       0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00  /* UDP - ignored */
+   };
+
+   struct rte_flow_item_raw raw_spec = {
+       .length = sizeof(raw_pattern_spec),
+       .pattern = raw_pattern_spec,
+   };
+
+   struct rte_flow_item_raw raw_mask = {
+       .length = sizeof(raw_pattern_mask),
+       .pattern = raw_pattern_mask,
+   };
+
+   struct rte_flow_attr attr = {
+       .ingress = 1,
+   };
+
+   struct rte_flow_item pattern[] = {
+       {
+           .type = RTE_FLOW_ITEM_TYPE_RAW,
+           .spec = &raw_spec,
+           .mask = &raw_mask,
+       },
+       {
+           .type = RTE_FLOW_ITEM_TYPE_END,
+       },
+   };
+
+   struct rte_flow_action actions[] = {
+       /* direct flow to queue index 3 */
+       {
+           .type = RTE_FLOW_ACTION_TYPE_QUEUE,
+           .conf = &(struct rte_flow_action_queue){ .index = 3 },
+       },
+       /* write id into mbuf FDIR metadata */
+       {
+           .type = RTE_FLOW_ACTION_TYPE_MARK,
+           .conf = &(struct rte_flow_action_mark){ .id = 3 },
+       },
+       {
+           .type = RTE_FLOW_ACTION_TYPE_END,
+       },
+   };
+
+   struct rte_flow_error error;
+   struct rte_flow *flow = flow = rte_flow_create(port_id, &attr, pattern, actions, &error);
+
+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
+
+Equivalent C code using the rte_flow API:
+
+.. code-block:: c
+
+   /* Use the same structures and code as above, only actions change */
+
+   struct rte_flow_action actions[] = {
+       {
+           .type = RTE_FLOW_ACTION_TYPE_RSS,
+           /* Use NULL conf for default RSS configuration */
+       },
+       {
+           .type = RTE_FLOW_ACTION_TYPE_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