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

[Suanming Mou]

Hi,

> -----Original Message-----
> From: Ferruh Yigit <ferruh.yigit at amd.com>
> Sent: Wednesday, January 31, 2024 1:34 AM
> To: Suanming Mou <suanmingm at nvidia.com>; Ori Kam <orika at nvidia.com>;
> Aman Singh <aman.deep.singh at intel.com>; Yuying Zhang
> <yuying.zhang at intel.com>; NBU-Contact-Thomas Monjalon (EXTERNAL)
> <thomas at monjalon.net>; Andrew Rybchenko
> <andrew.rybchenko at oktetlabs.ru>
> Cc: dev at dpdk.org
> Subject: Re: [PATCH v3 2/3] ethdev: add compare item
> 
> 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?

Yes, I think we have something to do in "testpmd_funcs.rst", will update.

> 
> > 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.

Agree, will adjust.

> 
> <...>
> 
> > 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.

Will rebase and update.

> 
> <...>
> 
> > +/**
> > + * 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.

The previous patch is just for renaming, I assume moving the struct is too much in previous patch, what do you think?

> 
> > +/**
> > + * @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.

Agree the struct maybe a bit nested. But not sure how it was discussed before during the last new member was added... @Ori, Do you have any idea about this?

And if it is really expected, I believe another new thread is worth for that change,  better not be in that series.
Need to discuss the new struct name and other stuff. What do you think? 

> 
> <...>
> 
> > +/**
> > + *
> > + * 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.

Yes, thanks for the suggestion, in fact we also discussed about the name a lot, finally we choose the widely used 'a' and 'b'

Thanks