[PATCH v1 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>
---
 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