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 <[email protected]> > Acked-by: Vladimir Medvedkin <[email protected]> > --- > > 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>
