[PATCH iwl-next v1 0/4] docs: fix minor issues with Flow Director flow types

[PATCH iwl-next v1 0/4] docs: fix minor issues with Flow Director flow types

[Aleksandr Loktionov]

The Flow Director sections of the i40e, ice and ixgbe docs are stale.
The examples use ip4 where the driver needs tcp4, and the flow type
lists do not match what the drivers accept. There seems to be no docs
for what a raw ip4 or ip6 flow actually matches, and the semantics are
confusing to newcomers. Document it.

Patches 1 and 2 update the i40e docs: the first lists the flow types
the driver accepts, the second documents what the raw ip4/ip6 flows
match and fixes the examples. Patch 3 does the same for ice. Patch 4
documents the raw ip4 match on ixgbe.

Docs only, no code changes.

Aleksandr Loktionov (4):
  i40e: list accepted Flow Director flow types
  i40e: fix raw ip4/ip6 flow match docs
  ice: fix raw ip4/ip6 flow match docs
  ixgbe: document raw ip4 flow match

 .../device_drivers/ethernet/intel/i40e.rst    | 37 +++++++++-----
 .../device_drivers/ethernet/intel/ice.rst     | 41 ++++++++++-----
 .../device_drivers/ethernet/intel/ixgbe.rst   | 54 ++++++++++++++++---
 3 files changed, 99 insertions(+), 33 deletions(-)

-- 
2.56.0

[PATCH iwl-next v1 1/4] i40e: list accepted Flow Director flow types

[Aleksandr Loktionov]

The hardware accepts all eight flow types. Keep the examples on tcp4.

Assisted-by: LLM
Signed-off-by: Aleksandr Loktionov <aleksandr.loktionov@intel.com>
---
 .../device_drivers/ethernet/intel/i40e.rst    | 25 +++++++++++--------
 1 file changed, 15 insertions(+), 10 deletions(-)

diff --git a/Documentation/networking/device_drivers/ethernet/intel/i40e.rst b/Documentation/networking/device_drivers/ethernet/intel/i40e.rst
index e01f0ad..92015b3 100644
--- a/Documentation/networking/device_drivers/ethernet/intel/i40e.rst
+++ b/Documentation/networking/device_drivers/ethernet/intel/i40e.rst
@@ -130,11 +130,12 @@ The Intel Ethernet Flow Director performs the following tasks:
 - Supports multiple parameters for flexible flow classification and load
   balancing (in SFP mode only).
 
-NOTE: The Linux i40e driver supports the following flow types: IPv4, TCPv4, and
-UDPv4. For a given flow type, it supports valid combinations of IP addresses
-(source or destination) and UDP/TCP ports (source and destination). For
-example, you can supply only a source IP address, a source IP address and a
-destination port, or any combination of one or more of these four parameters.
+NOTE: The Linux i40e driver accepts the following flow types: IPv4, TCPv4,
+UDPv4, SCTPv4, IPv6, TCPv6, UDPv6 and SCTPv6. The TCP, UDP and SCTP flow types
+accept valid combinations of IP addresses and port qualifiers: you can supply
+only a source IP address, a source address plus a destination port, or any
+combination of one or more of those four fields. The raw ip4 and ip6 flows
+reject any port qualifier.
 
 NOTE: The Linux i40e driver allows you to filter traffic based on a
 user-defined flexible two-byte pattern and offset by using the ethtool user-def
@@ -193,11 +194,15 @@ new filter use the following command::
 
 Where:
   <device> - the ethernet device to program
-  <type> - can be ip4, tcp4, udp4, or sctp4
+  <type> - can be ip4, tcp4, udp4, sctp4, ip6, tcp6, udp6 or sctp6
   <ip> - the ip address to match on
   <port> - the port number to match on
   <queue> - the queue to direct traffic towards (-1 discards matching traffic)
 
+The two port fields apply to the tcp4, udp4, sctp4, tcp6, udp6 and sctp6 flow
+types. The raw ip4 or ip6 flow rejects a port field, so use tcp4 or tcp6 when
+ports matter.
+
 Use the following command to display all of the active filters::
 
   ethtool -u <device>
@@ -218,14 +223,14 @@ directed to 192.168.0.5, port 80, and sends it to queue 7::
 For each flow-type, the programmed filters must all have the same matching
 input set. For example, issuing the following two commands is acceptable::
 
-  ethtool -U enp130s0 flow-type ip4 src-ip 192.168.0.1 src-port 5300 action 7
-  ethtool -U enp130s0 flow-type ip4 src-ip 192.168.0.5 src-port 55 action 10
+  ethtool -U enp130s0 flow-type tcp4 src-ip 192.168.0.1 src-port 5300 action 7
+  ethtool -U enp130s0 flow-type tcp4 src-ip 192.168.0.5 src-port 55 action 10
 
 Issuing the next two commands, however, is not acceptable, since the first
 specifies src-ip and the second specifies dst-ip::
 
-  ethtool -U enp130s0 flow-type ip4 src-ip 192.168.0.1 src-port 5300 action 7
-  ethtool -U enp130s0 flow-type ip4 dst-ip 192.168.0.5 src-port 55 action 10
+  ethtool -U enp130s0 flow-type tcp4 src-ip 192.168.0.1 src-port 5300 action 7
+  ethtool -U enp130s0 flow-type tcp4 dst-ip 192.168.0.5 src-port 55 action 10
 
 The second command will fail with an error. You may program multiple filters
 with the same fields, using different values, but, on one device, you may not
-- 
2.56.0

[PATCH iwl-next v1 2/4] i40e: fix raw ip4/ip6 flow match docs

[Aleksandr Loktionov]

The raw ip4/ip6 flows match only the other-IP traffic.
Fix the stale examples and rejected qualifiers.

Assisted-by: LLM
Signed-off-by: Aleksandr Loktionov <aleksandr.loktionov@intel.com>
---
 .../device_drivers/ethernet/intel/i40e.rst           | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/Documentation/networking/device_drivers/ethernet/intel/i40e.rst b/Documentation/networking/device_drivers/ethernet/intel/i40e.rst
index 92015b3..b47db47 100644
--- a/Documentation/networking/device_drivers/ethernet/intel/i40e.rst
+++ b/Documentation/networking/device_drivers/ethernet/intel/i40e.rst
@@ -137,6 +137,18 @@ only a source IP address, a source address plus a destination port, or any
 combination of one or more of those four fields. The raw ip4 and ip6 flows
 reject any port qualifier.
 
+NOTE: A flow type selects the packet type the hardware classifies. The i40e
+driver programs an ip4 filter for the "other IPv4" and "fragmented IPv4"
+packet types, and an ip6 filter for the "other IPv6" and "fragmented IPv6"
+packet types. A filter created with ethtool(8) in one of those two flow types
+matches only traffic the hardware did not classify as TCP, UDP or SCTP: ICMP
+and ICMPv6 frames, IPv4 and IPv6 fragments, and IP traffic with a next
+protocol the hardware does not classify. It matches no non-fragmented TCP, UDP
+or SCTP frame, even if you also add tcp4, udp4, sctp4, tcp6, udp6 or sctp6
+filters; use those flow types to steer TCP, UDP or SCTP traffic. The driver
+also rejects an l4proto qualifier on an ip4 or ip6 filter, and a tos qualifier
+on an ip4 filter.
+
 NOTE: The Linux i40e driver allows you to filter traffic based on a
 user-defined flexible two-byte pattern and offset by using the ethtool user-def
 and mask fields. Only L3 and L4 flow types are supported for user-defined
-- 
2.56.0

[PATCH iwl-next v1 3/4] ice: fix raw ip4/ip6 flow match docs

[Aleksandr Loktionov]

The raw ip4/ip6 flows match only the other-IP traffic.
Fix the stale examples and qualifiers.

Assisted-by: LLM
Signed-off-by: Aleksandr Loktionov <aleksandr.loktionov@intel.com>
---
 .../device_drivers/ethernet/intel/ice.rst     | 41 +++++++++++++------
 1 file changed, 29 insertions(+), 12 deletions(-)

diff --git a/Documentation/networking/device_drivers/ethernet/intel/ice.rst b/Documentation/networking/device_drivers/ethernet/intel/ice.rst
index b720763..928ebd6 100644
--- a/Documentation/networking/device_drivers/ethernet/intel/ice.rst
+++ b/Documentation/networking/device_drivers/ethernet/intel/ice.rst
@@ -237,10 +237,22 @@ NOTE: This driver supports the following flow types:
 - UDPv6
 - SCTPv6
 
-Each flow type supports valid combinations of IP addresses (source or
-destination) and UDP/TCP/SCTP ports (source and destination). You can supply
-only a source IP address, a source IP address and a destination port, or any
-combination of one or more of these four parameters.
+The TCP, UDP and SCTP flow types accept valid combinations of IP addresses
+(source or destination) and UDP/TCP/SCTP ports (source and destination). You
+can supply only a source IP address, a source IP address and a destination
+port, or any combination of one or more of these four parameters. On the raw
+IPv4 and IPv6 flow types the driver rejects a port qualifier.
+
+NOTE: A flow type selects the packet type the hardware classifies. The ice
+driver programs an ip4 filter as the "other IPv4" packet type and an ip6
+filter as the "other IPv6" packet type. A filter you create with ethtool(8) in
+one of those two flow types matches only traffic the hardware did not classify
+as TCP, UDP or SCTP: ICMP and ICMPv6 frames, IPv4 and IPv6 fragments, and IPv4
+or IPv6 traffic with a next header the hardware does not classify. It matches
+no non-fragmented TCP, UDP or SCTP frame, even if you also configure a filter
+of the tcp4, udp4, sctp4, tcp6, udp6 or sctp6 flow type; use those flow types
+to steer TCP, UDP or SCTP traffic. The driver also rejects an l4proto
+qualifier on an ip4 or ip6 filter and a tos qualifier on an ip4 filter.
 
 NOTE: This driver allows you to filter traffic based on a user-defined flexible
 two-byte pattern and offset by using the ethtool user-def and mask fields. Only
@@ -283,6 +295,10 @@ To add a new filter::
     <queue> - the queue to direct traffic toward (-1 discards the
               matched traffic)
 
+  The two port parameters apply to the tcp4, udp4, sctp4, tcp6, udp6 and sctp6
+  flow types. The raw ip4 or ip6 flow rejects a port, so use tcp4 or tcp6 when
+  ports matter.
+
 To delete a filter::
 
   # ethtool -U <ethX> delete <N>
@@ -323,21 +339,22 @@ To add a TCPv4 filter with a partial mask for a source IP subnet::
 
 NOTES:
 
-For each flow-type, the programmed filters must all have the same matching
+For each flow type, the programmed filters must all have the same matching
 input set. For example, issuing the following two commands is acceptable::
 
-  # ethtool -U enp130s0 flow-type ip4 src-ip 192.168.0.1 src-port 5300 action 7
-  # ethtool -U enp130s0 flow-type ip4 src-ip 192.168.0.5 src-port 55 action 10
+  # ethtool -U enp130s0 flow-type tcp4 src-ip 192.168.0.1 src-port 5300 action 7
+  # ethtool -U enp130s0 flow-type tcp4 src-ip 192.168.0.5 src-port 55 action 10
 
 Issuing the next two commands, however, is not acceptable, since the first
 specifies src-ip and the second specifies dst-ip::
 
-  # ethtool -U enp130s0 flow-type ip4 src-ip 192.168.0.1 src-port 5300 action 7
-  # ethtool -U enp130s0 flow-type ip4 dst-ip 192.168.0.5 src-port 55 action 10
+  # ethtool -U enp130s0 flow-type tcp4 src-ip 192.168.0.1 src-port 5300 action 7
+  # ethtool -U enp130s0 flow-type tcp4 dst-ip 192.168.0.5 src-port 55 action 10
 
-The second command will fail with an error. You may program multiple filters
-with the same fields, using different values, but, on one device, you may not
-program two tcp4 filters with different matching fields.
+The second command will fail, and the driver reports "Failed to add filter.
+Flow director filters on each port must have the same input set". You may
+program multiple filters with the same fields, using different values, but on
+one port you may not program two tcp4 filters with different matching fields.
 
 The ice driver does not support matching on a subportion of a field, thus
 partial mask fields are not supported.
-- 
2.56.0

[PATCH iwl-next v1 4/4] ixgbe: document raw ip4 flow match

[Aleksandr Loktionov]

The raw ip4 flow matches all IPv4 traffic except TCP, UDP and SCTP.
Fix the stale docs.

Assisted-by: LLM
Signed-off-by: Aleksandr Loktionov <aleksandr.loktionov@intel.com>
---
 .../device_drivers/ethernet/intel/ixgbe.rst   | 54 +++++++++++++++----
 1 file changed, 43 insertions(+), 11 deletions(-)

diff --git a/Documentation/networking/device_drivers/ethernet/intel/ixgbe.rst b/Documentation/networking/device_drivers/ethernet/intel/ixgbe.rst
index 1e5f169..1cb9935 100644
--- a/Documentation/networking/device_drivers/ethernet/intel/ixgbe.rst
+++ b/Documentation/networking/device_drivers/ethernet/intel/ixgbe.rst
@@ -329,13 +329,36 @@ The src-ip value that is written to the filter will be 0.4.1.2, not 172.0.0.0
 as might be expected. Similarly, the dst-ip value written to the filter will be
 0.21.1.1, not 172.0.0.0.
 
+NOTE: An ip4 filter matches every IPv4 packet that matches the remaining
+fields, regardless of what the packet carries above IP: TCP, UDP, SCTP, ICMP,
+an IPv4 fragment, or IPv4 with a protocol number the hardware does not
+classify. The driver leaves the L4 packet type as a don't-care, and on every
+MAC it behaves this way; the only measurement that was done was on an Ethernet
+Controller E610. The i40e and ice drivers are the opposite: there an ip4
+filter matches only traffic the hardware did not classify as TCP, UDP or SCTP,
+and matches no non-fragmented TCP, UDP or SCTP frame.
+
+An l4proto qualifier turns an ip4 filter into a protocol specific filter:
+l4proto 6, 17 and 132 program a TCP, UDP or SCTP filter, and the driver
+rejects any other protocol number. The ports of such a filter then take part
+in the match; for SCTP this depends on hardware that programs an SCTP port
+mask. Without an l4proto qualifier the driver rejects a port on an ip4 filter.
+It accepts a tos qualifier and ignores it, because it programs no tos mask: a
+filter with a tos qualifier matches its address regardless of the tos value of
+the packet. The driver implements no IPv6 flow type and rejects ip6, tcp6,
+udp6 and sctp6 filters. Filters can be programmed while ntuple offload,
+described below, or hw-tc-offload is enabled; either one keeps the Flow
+Director in perfect mode.
+
 To enable or disable the Intel Ethernet Flow Director::
 
   # ethtool -K ethX ntuple <on|off>
 
-When disabling ntuple filters, all the user programmed filters are flushed from
-the driver cache and hardware. All needed filters must be re-added when ntuple
-is re-enabled.
+Turning the ntuple offload off does not drop the programmed filters while
+hw-tc-offload is enabled, because either feature keeps the Flow Director in
+perfect mode. With both features off, the filters stay in the driver cache and
+ixgbe programs them again in hardware when either one is turned back on, so
+they do not have to be added again after such a toggle.
 
 To add a filter that directs packet to queue 2, use -U or -N switch::
 
@@ -362,6 +385,10 @@ Where:
   <port> - the port number to match on
   <queue> - the queue to direct traffic towards (-1 discards the matched traffic)
 
+The two port parameters apply to tcp4, udp4 and sctp4, and to an ip4 filter
+that carries an l4proto qualifier. The driver rejects a port on a raw ip4
+filter without one, and it accepts no IPv6 flow type.
+
 Use the following command to delete a filter::
 
   ethtool -U <device> delete <N>
@@ -375,21 +402,26 @@ directed to 192.168.0.5, port 80, and sends it to queue 7::
   ethtool -U enp130s0 flow-type tcp4 src-ip 192.168.0.1 dst-ip 192.168.0.5 \
   src-port 5300 dst-port 80 action 7
 
-For each flow-type, the programmed filters must all have the same matching
-input set. For example, issuing the following two commands is acceptable::
+All the filters programmed on one port share a single classification mask, so
+they must all match on the same fields regardless of flow type. For example,
+issuing the following two commands is acceptable::
 
-  ethtool -U enp130s0 flow-type ip4 src-ip 192.168.0.1 src-port 5300 action 7
-  ethtool -U enp130s0 flow-type ip4 src-ip 192.168.0.5 src-port 55 action 10
+  ethtool -U enp130s0 flow-type tcp4 src-ip 192.168.0.1 src-port 5300 action 7
+  ethtool -U enp130s0 flow-type tcp4 src-ip 192.168.0.5 src-port 55 action 10
 
 Issuing the next two commands, however, is not acceptable, since the first
 specifies src-ip and the second specifies dst-ip::
 
-  ethtool -U enp130s0 flow-type ip4 src-ip 192.168.0.1 src-port 5300 action 7
-  ethtool -U enp130s0 flow-type ip4 dst-ip 192.168.0.5 src-port 55 action 10
+  ethtool -U enp130s0 flow-type tcp4 src-ip 192.168.0.1 src-port 5300 action 7
+  ethtool -U enp130s0 flow-type tcp4 dst-ip 192.168.0.5 src-port 55 action 10
 
 The second command will fail with an error. You may program multiple filters
-with the same fields, using different values, but, on one device, you may not
-program two TCP4 filters with different matching fields.
+with the same fields, using different values, but on one port you may not
+program two filters that need different fields. A plain ip4 filter needs
+different fields from the protocol specific flow types, so the driver will not
+program it on a port that already holds a tcp4, udp4 or sctp4 filter, and the
+reverse is also true. An ip4 filter that carries an l4proto qualifier is one of
+the protocol-specific filters and shares their mask.
 
 Matching on a sub-portion of a field is not supported by the ixgbe driver, thus
 partial mask fields are not supported.
-- 
2.56.0

Re: [PATCH iwl-next v1 4/4] ixgbe: document raw ip4 flow match

[sashiko-bot]

Thank you for your contribution! Sashiko AI review found 2 potential issue(s) to consider:
- [Medium] ixgbe: commit message contradicts documented and actual raw ip4 filter behavior
- [Low] ixgbe: documentation embeds E610 test note and overstates MAC support
--

commit ef5298950b8a36e3b13694833b34dbd3ea4c7bf6
Author: Aleksandr Loktionov <aleksandr.loktionov@intel.com>

ixgbe: document raw ip4 flow match

This commit updates the ixgbe documentation regarding raw ip4 Flow Director
matching, l4proto and tos qualifiers, ntuple and hw-tc-offload filter
persistence, and per-port classification mask rules.

>     ixgbe: document raw ip4 flow match
>     
>     The raw ip4 flow matches all IPv4 traffic except TCP, UDP and SCTP.
>     Fix the stale docs.
>     
>     Assisted-by: LLM
>     Signed-off-by: Aleksandr Loktionov <aleksandr.loktionov@intel.com>

[Severity: Medium]
Does the commit message state the opposite of both the ixgbe driver
implementation and the documentation added by this patch?

In drivers/net/ethernet/intel/ixgbe/ixgbe_ethtool.c,
ixgbe_add_ethtool_fdir_entry() clears IXGBE_ATR_L4TYPE_MASK for raw ip4
filters:

    if (input->filter.formatted.flow_type == IXGBE_ATR_FLOW_TYPE_IPV4)
        mask.formatted.flow_type &= IXGBE_ATR_L4TYPE_IPV6_MASK;

And in drivers/net/ethernet/intel/ixgbe/ixgbe_82599.c,
ixgbe_fdir_set_input_mask_82599() masks out the L4 protocol in hardware:

    switch (input_mask->formatted.flow_type & IXGBE_ATR_L4TYPE_MASK) {
    case 0x0:
        fdirm |= IXGBE_FDIRM_L4P;

As the new note in Documentation/networking/device_drivers/ethernet/intel/ixgbe.rst
explains, an ip4 filter in ixgbe matches all IPv4 packets including TCP,
UDP, and SCTP (whereas i40e and ice exclude non-fragmented TCP, UDP, and
SCTP).

In addition, the patch updates the documentation for ntuple and
hw-tc-offload filter retention, l4proto/tos/IPv6 handling, and the shared
per-port classification mask examples. Could the commit message be updated
to accurately describe the ixgbe ip4 matching rule and summarize these
other documentation changes?

> diff --git a/Documentation/networking/device_drivers/ethernet/intel/ixgbe.rst b/Documentation/networking/device_drivers/ethernet/intel/ixgbe.rst
> index 1e5f16993f697..1cb9935fa9788 100644
> --- a/Documentation/networking/device_drivers/ethernet/intel/ixgbe.rst
> +++ b/Documentation/networking/device_drivers/ethernet/intel/ixgbe.rst
> @@ -329,13 +329,36 @@ The src-ip value that is written to the filter will be 0.4.1.2, not 172.0.0.0
>  as might be expected. Similarly, the dst-ip value written to the filter will be
>  0.21.1.1, not 172.0.0.0.
>  
> +NOTE: An ip4 filter matches every IPv4 packet that matches the remaining
> +fields, regardless of what the packet carries above IP: TCP, UDP, SCTP, ICMP,
> +an IPv4 fragment, or IPv4 with a protocol number the hardware does not
> +classify. The driver leaves the L4 packet type as a don't-care, and on every
> +MAC it behaves this way; the only measurement that was done was on an Ethernet
> +Controller E610. The i40e and ice drivers are the opposite: there an ip4

[Severity: Low]
Is the remark that the only measurement was done on an Ethernet Controller
E610 a patch-testing note that belongs in the commit message rather than
in user-facing documentation?

Also, is it accurate to say that every MAC supported by ixgbe behaves this
way? In drivers/net/ethernet/intel/ixgbe/ixgbe_main.c, ixgbe_probe() only
enables Flow Director support on 82599EB and newer MACs, excluding 82598:

    if (hw->mac.type >= ixgbe_mac_82599EB)
        netdev->hw_features |= NETIF_F_NTUPLE |
                       NETIF_F_HW_TC;

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20261102153512.1601855-1-aleksandr.loktionov@intel.com?part=4