[PATCH v3 2/3] ethdev: add compare item

[Ferruh Yigit]

On 1/15/2024 9:13 AM, Suanming Mou wrote:
> The new item type is added for the case user wants to match traffic
> based on packet field compare result with other fields or immediate
> value.
> 
> e.g. take advantage the compare item user will be able to accumulate
> a IPv4/TCP packet's TCP data_offset and IPv4 IHL field to a tag
> register, then compare the tag register with IPv4 header total length
> to understand the packet has payload or not.
> 

ack, above sample makes it easier to understand.

This patch is adding testpmd commands, can you please provide some
sample commands in commit log?
The more samples are better, as far as I remember there was a testpmd
documentation that documents the sample usages, can you please check for it?

> The supported operations can be as below:
>  - RTE_FLOW_ITEM_COMPARE_EQ (equal)
>  - RTE_FLOW_ITEM_COMPARE_NE (not equal)
>  - RTE_FLOW_ITEM_COMPARE_LT (less than)
>  - RTE_FLOW_ITEM_COMPARE_LE (less than or equal)
>  - RTE_FLOW_ITEM_COMPARE_GT (great than)
>  - RTE_FLOW_ITEM_COMPARE_GE (great than or equal)
> 
> Signed-off-by: Suanming Mou <suanmingm at nvidia.com>
> Acked-by: Ori Kam <orika at nvidia.com>
> Acked-by: Andrew Rybchenko <andrew.rybchenko at oktetlabs.ru>

<...>

>  
> -static const char *const modify_field_ids[] = {
> +static const char *const flow_field_ids[] = {
>

I wonder if this rename should be in previous patch, as it does the
logical change of the modify action specific fields to more generic fields.

<...>

> diff --git a/doc/guides/rel_notes/release_24_03.rst b/doc/guides/rel_notes/release_24_03.rst
> index a691e794f4..8c8c661218 100644
> --- a/doc/guides/rel_notes/release_24_03.rst
> +++ b/doc/guides/rel_notes/release_24_03.rst
> @@ -55,6 +55,11 @@ New Features
>       Also, make sure to start the actual text at the margin.
>       =======================================================
>  
> +* **Added compare flow matching criteria.**
> +
> +  Added ``RTE_FLOW_ITEM_TYPE_COMPARE`` to allow matching on compare
> +  result between the packet fields or value.
> +
>  * **Updated NVIDIA mlx5 driver.**
>  
>    * Added support for accumulating from src field to dst field.
>

I guess you are rebasing on some internal repo, because above NVIDIA
note doesn't exist in upstream repo. Can you please rebase on latest
next-net, this also helps to resolve conflict with random action in
upstream repo.

<...>

> +/**
> + * Field IDs for packet field.
> + */
> +enum rte_flow_field_id {
> +	RTE_FLOW_FIELD_START = 0,	/**< Start of a packet. */
> +	RTE_FLOW_FIELD_MAC_DST,		/**< Destination MAC Address. */
> +	RTE_FLOW_FIELD_MAC_SRC,		/**< Source MAC Address. */
> +	RTE_FLOW_FIELD_VLAN_TYPE,	/**< VLAN Tag Identifier. */
> +	RTE_FLOW_FIELD_VLAN_ID,		/**< VLAN Identifier. */
> +	RTE_FLOW_FIELD_MAC_TYPE,	/**< EtherType. */
> +	RTE_FLOW_FIELD_IPV4_DSCP,	/**< IPv4 DSCP. */
> +	RTE_FLOW_FIELD_IPV4_TTL,	/**< IPv4 Time To Live. */
> +	RTE_FLOW_FIELD_IPV4_SRC,	/**< IPv4 Source Address. */
> +	RTE_FLOW_FIELD_IPV4_DST,	/**< IPv4 Destination Address. */
> +	RTE_FLOW_FIELD_IPV6_DSCP,	/**< IPv6 DSCP. */
> +	RTE_FLOW_FIELD_IPV6_HOPLIMIT,	/**< IPv6 Hop Limit. */
> +	RTE_FLOW_FIELD_IPV6_SRC,	/**< IPv6 Source Address. */
> +	RTE_FLOW_FIELD_IPV6_DST,	/**< IPv6 Destination Address. */
> +	RTE_FLOW_FIELD_TCP_PORT_SRC,	/**< TCP Source Port Number. */
> +	RTE_FLOW_FIELD_TCP_PORT_DST,	/**< TCP Destination Port Number. */
> +	RTE_FLOW_FIELD_TCP_SEQ_NUM,	/**< TCP Sequence Number. */
> +	RTE_FLOW_FIELD_TCP_ACK_NUM,	/**< TCP Acknowledgment Number. */
> +	RTE_FLOW_FIELD_TCP_FLAGS,	/**< TCP Flags. */
> +	RTE_FLOW_FIELD_UDP_PORT_SRC,	/**< UDP Source Port Number. */
> +	RTE_FLOW_FIELD_UDP_PORT_DST,	/**< UDP Destination Port Number. */
> +	RTE_FLOW_FIELD_VXLAN_VNI,	/**< VXLAN Network Identifier. */
> +	RTE_FLOW_FIELD_GENEVE_VNI,	/**< GENEVE Network Identifier. */
> +	RTE_FLOW_FIELD_GTP_TEID,	/**< GTP Tunnel Endpoint Identifier. */
> +	RTE_FLOW_FIELD_TAG,		/**< Tag value. */
> +	RTE_FLOW_FIELD_MARK,		/**< Mark value. */
> +	RTE_FLOW_FIELD_META,		/**< Metadata value. */
> +	RTE_FLOW_FIELD_POINTER,		/**< Memory pointer. */
> +	RTE_FLOW_FIELD_VALUE,		/**< Immediate value. */
> +	RTE_FLOW_FIELD_IPV4_ECN,	/**< IPv4 ECN. */
> +	RTE_FLOW_FIELD_IPV6_ECN,	/**< IPv6 ECN. */
> +	RTE_FLOW_FIELD_GTP_PSC_QFI,	/**< GTP QFI. */
> +	RTE_FLOW_FIELD_METER_COLOR,	/**< Meter color marker. */
> +	RTE_FLOW_FIELD_IPV6_PROTO,	/**< IPv6 next header. */
> +	RTE_FLOW_FIELD_FLEX_ITEM,	/**< Flex item. */
> +	RTE_FLOW_FIELD_HASH_RESULT,	/**< Hash result. */
> +	RTE_FLOW_FIELD_GENEVE_OPT_TYPE,	/**< GENEVE option type. */
> +	RTE_FLOW_FIELD_GENEVE_OPT_CLASS,/**< GENEVE option class. */
> +	RTE_FLOW_FIELD_GENEVE_OPT_DATA,	/**< GENEVE option data. */
> +	RTE_FLOW_FIELD_MPLS,		/**< MPLS header. */
> +	RTE_FLOW_FIELD_TCP_DATA_OFFSET,	/**< TCP data offset. */
> +	RTE_FLOW_FIELD_IPV4_IHL,	/**< IPv4 IHL. */
> +	RTE_FLOW_FIELD_IPV4_TOTAL_LEN,	/**< IPv4 total length. */
> +	RTE_FLOW_FIELD_IPV6_PAYLOAD_LEN	/**< IPv6 payload length. */
> +};
> +

+1 to move the structs to keep the proper order, but not sure if it is
better to do this in previous patch or this one.

> +/**
> + * @warning
> + * @b EXPERIMENTAL: this structure may change without prior notice
> + *
> + * Field description for packet field.
> + */
> +struct rte_flow_field_data {
> +	enum rte_flow_field_id field; /**< Field or memory type ID. */
> +	union {
> +		struct {
> +			/** Encapsulation level and tag index or flex item handle. */
> +			union {
> +				struct {
> +					/**
> +					 * Packet encapsulation level containing
> +					 * the field to modify.
> +					 *
> +					 * - @p 0 requests the default behavior.
> +					 *   Depending on the packet type, it
> +					 *   can mean outermost, innermost or
> +					 *   anything in between.
> +					 *
> +					 *   It basically stands for the
> +					 *   innermost encapsulation level.
> +					 *   Modification can be performed
> +					 *   according to PMD and device
> +					 *   capabilities.
> +					 *
> +					 * - @p 1 requests modification to be
> +					 *   performed on the outermost packet
> +					 *   encapsulation level.
> +					 *
> +					 * - @p 2 and subsequent values request
> +					 *   modification to be performed on
> +					 *   the specified inner packet
> +					 *   encapsulation level, from
> +					 *   outermost to innermost (lower to
> +					 *   higher values).
> +					 *
> +					 * Values other than @p 0 are not
> +					 * necessarily supported.
> +					 *
> +					 * @note that for MPLS field,
> +					 * encapsulation level also include
> +					 * tunnel since MPLS may appear in
> +					 * outer, inner or tunnel.
> +					 */
> +					uint8_t level;
> +					union {
> +						/**
> +						 * Tag index array inside
> +						 * encapsulation level.
> +						 * Used for VLAN, MPLS or TAG types.
> +						 */
> +						uint8_t tag_index;
> +						/**
> +						 * Geneve option identifier.
> +						 * Relevant only for
> +						 * RTE_FLOW_FIELD_GENEVE_OPT_XXXX
> +						 * modification type.
> +						 */
> +						struct {
> +							/**
> +							 * Geneve option type.
> +							 */
> +							uint8_t type;
> +							/**
> +							 * Geneve option class.
> +							 */
> +							rte_be16_t class_id;
> +						};
> +					};
> +				};
> +				struct rte_flow_item_flex_handle *flex_handle;
> +			};
> +			/** Number of bits to skip from a field. */
> +			uint32_t offset;
> +		};
> +		/**
> +		 * Immediate value for RTE_FLOW_FIELD_VALUE, presented in the
> +		 * same byte order and length as in relevant rte_flow_item_xxx.
> +		 * The immediate source bitfield offset is inherited from
> +		 * the destination's one.
> +		 */
> +		uint8_t value[16];
> +		/**
> +		 * Memory address for RTE_FLOW_FIELD_POINTER, memory layout
> +		 * should be the same as for relevant field in the
> +		 * rte_flow_item_xxx structure.
> +		 */
> +		void *pvalue;
> +	};
> +};
> +
>

I am aware that you are just moving the above struct, but it is nested
too much which is making it hard to read.

As you are touching it, can we extract some structs and make this struct
less nested, what do you think?
Of course it needs to be done in separate patch, as a
preperation/clean-up patch before moving it around.

<...>

> +/**
> + *
> + * RTE_FLOW_ITEM_TYPE_COMPARE
> + *
> + * Matches the packet with compare result.
> + *
> + * The operation means a compare with b result.
> + */
> +struct rte_flow_item_compare {
> +	enum rte_flow_item_compare_op operation; /* The compare operation. */
> +	struct rte_flow_field_data a;		 /* Field be compared.  */
> +	struct rte_flow_field_data b;		 /* Field as comparator. */
>

Variable names 'a' and 'b' are not descriptive although it may be OK
since there is no significance to the values, but other option can be
'first' and 'second', but overall not strong opinion.