[PATCH v1 0/2] ethdev: add random item support

[PATCH v1 0/2] ethdev: add random item support

[Michael Baum]

Add support for matching random value using new "rte_flow_item_random"
structure.
This random value is not based on the packet data/headers.
Application shouldn't assume that this value is kept during the life
time of the packet.

Michael Baum (2):
  ethdev: add random item support
  app/testpmd: add random item support

 app/test-pmd/cmdline_flow.c                 | 30 ++++++++++++++++++-
 doc/guides/nics/features/default.ini        |  1 +
 doc/guides/prog_guide/rte_flow.rst          | 11 +++++++
 doc/guides/rel_notes/release_23_11.rst      |  4 +++
 doc/guides/testpmd_app_ug/testpmd_funcs.rst |  4 +++
 lib/ethdev/rte_flow.c                       |  1 +
 lib/ethdev/rte_flow.h                       | 33 +++++++++++++++++++++
 7 files changed, 83 insertions(+), 1 deletion(-)

-- 
2.25.1

[PATCH v1 1/2] ethdev: add random item support

[Michael Baum]

Add support for a new item type "RTE_FLOW_ITEM_TYPE_RANDOM".
This item enables to match on some random value as a part of flow rule.

Signed-off-by: Michael Baum <michaelba@nvidia.com>
---
 doc/guides/nics/features/default.ini   |  1 +
 doc/guides/prog_guide/rte_flow.rst     | 11 +++++++++
 doc/guides/rel_notes/release_23_11.rst |  4 ++++
 lib/ethdev/rte_flow.c                  |  1 +
 lib/ethdev/rte_flow.h                  | 33 ++++++++++++++++++++++++++
 5 files changed, 50 insertions(+)

diff --git a/doc/guides/nics/features/default.ini b/doc/guides/nics/features/default.ini
index 2011e97127..0a790dafe8 100644
--- a/doc/guides/nics/features/default.ini
+++ b/doc/guides/nics/features/default.ini
@@ -139,6 +139,7 @@ pppoes               =
 pppoe_proto_id       =
 quota                =
 raw                  =
+random               =
 represented_port     =
 sctp                 =
 tag                  =
diff --git a/doc/guides/prog_guide/rte_flow.rst b/doc/guides/prog_guide/rte_flow.rst
index 5bc998a433..5ad699dff7 100644
--- a/doc/guides/prog_guide/rte_flow.rst
+++ b/doc/guides/prog_guide/rte_flow.rst
@@ -1566,6 +1566,17 @@ Matches an InfiniBand base transport header in RoCE packet.
 
 - ``hdr``: InfiniBand base transport header definition (``rte_ib.h``).
 
+Item: ``RANDOM``
+^^^^^^^^^^^^^^^^
+
+Matches a random value.
+
+This value is not based on the packet data/headers.
+Application shouldn't assume that this value is kept during the life time of
+the packet.
+
+- ``value``: Random value.
+
 Actions
 ~~~~~~~
 
diff --git a/doc/guides/rel_notes/release_23_11.rst b/doc/guides/rel_notes/release_23_11.rst
index 4411bb32c1..1e90bf83e7 100644
--- a/doc/guides/rel_notes/release_23_11.rst
+++ b/doc/guides/rel_notes/release_23_11.rst
@@ -72,6 +72,10 @@ New Features
      Also, make sure to start the actual text at the margin.
      =======================================================
 
+* **Added flow matching of Infiniband BTH.**
+
+  Added ``RTE_FLOW_ITEM_RANDOM`` to match random value.
+
 
 Removed Items
 -------------
diff --git a/lib/ethdev/rte_flow.c b/lib/ethdev/rte_flow.c
index 271d854f78..51db3e5aec 100644
--- a/lib/ethdev/rte_flow.c
+++ b/lib/ethdev/rte_flow.c
@@ -136,6 +136,7 @@ static const struct rte_flow_desc_data rte_flow_desc_item[] = {
 		     sizeof(struct rte_flow_item_icmp6_nd_opt_tla_eth)),
 	MK_FLOW_ITEM(MARK, sizeof(struct rte_flow_item_mark)),
 	MK_FLOW_ITEM(META, sizeof(struct rte_flow_item_meta)),
+	MK_FLOW_ITEM(RANDOM, sizeof(struct rte_flow_item_random)),
 	MK_FLOW_ITEM(TAG, sizeof(struct rte_flow_item_tag)),
 	MK_FLOW_ITEM(GRE_KEY, sizeof(rte_be32_t)),
 	MK_FLOW_ITEM(GRE_OPTION, sizeof(struct rte_flow_item_gre_opt)),
diff --git a/lib/ethdev/rte_flow.h b/lib/ethdev/rte_flow.h
index 2ebb76dbc0..b5228b293c 100644
--- a/lib/ethdev/rte_flow.h
+++ b/lib/ethdev/rte_flow.h
@@ -688,6 +688,19 @@ enum rte_flow_item_type {
 	 * @see struct rte_flow_item_ib_bth.
 	 */
 	RTE_FLOW_ITEM_TYPE_IB_BTH,
+
+	/**
+	 * [META]
+	 *
+	 * Matches a random value.
+	 *
+	 * This value is not based on the packet data/headers.
+	 * Application shouldn't assume that this value is kept during the life
+	 * time of the packet.
+	 *
+	 * @see struct rte_flow_item_random.
+	 */
+	RTE_FLOW_ITEM_TYPE_RANDOM,
 };
 
 /**
@@ -2031,6 +2044,25 @@ static const struct rte_flow_item_ib_bth rte_flow_item_ib_bth_mask = {
 };
 #endif
 
+/**
+ * @warning
+ * @b EXPERIMENTAL: this structure may change without prior notice
+ *
+ * RTE_FLOW_ITEM_TYPE_RANDOM
+ *
+ * Matches a random value.
+ */
+struct rte_flow_item_random {
+	uint32_t value;
+};
+
+/** Default mask for RTE_FLOW_ITEM_TYPE_RANDOM. */
+#ifndef __cplusplus
+static const struct rte_flow_item_random rte_flow_item_random_mask = {
+	.value = UINT32_MAX,
+};
+#endif
+
 /**
  * Matching pattern item definition.
  *
@@ -3875,6 +3907,7 @@ enum rte_flow_field_id {
 	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_RANDOM		/**< Random value. */
 };
 
 /**
-- 
2.25.1

[PATCH v1 2/2] app/testpmd: add random item support

[Michael Baum]

Add support for random item, usage example:

	pattern random spec value 0x1 mask value 0x3 / eth / end

Flow rule with above pattern matching 25% of the traffic, it hits only
when random value suffix is "01" and miss the others ("00", "10", "11").

Signed-off-by: Michael Baum <michaelba@nvidia.com>
---
 app/test-pmd/cmdline_flow.c                 | 30 ++++++++++++++++++++-
 doc/guides/testpmd_app_ug/testpmd_funcs.rst |  4 +++
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/app/test-pmd/cmdline_flow.c b/app/test-pmd/cmdline_flow.c
index 94827bcc4a..55fb07ec91 100644
--- a/app/test-pmd/cmdline_flow.c
+++ b/app/test-pmd/cmdline_flow.c
@@ -417,6 +417,8 @@ enum index {
 	ITEM_ICMP6_ND_OPT_TLA_ETH_TLA,
 	ITEM_META,
 	ITEM_META_DATA,
+	ITEM_RANDOM,
+	ITEM_RANDOM_VALUE,
 	ITEM_GRE_KEY,
 	ITEM_GRE_KEY_VALUE,
 	ITEM_GRE_OPTION,
@@ -936,7 +938,8 @@ static const char *const modify_field_ids[] = {
 	"ipv6_proto",
 	"flex_item",
 	"hash_result",
-	"geneve_opt_type", "geneve_opt_class", "geneve_opt_data", "mpls",
+	"geneve_opt_type", "geneve_opt_class", "geneve_opt_data",
+	"mpls", "random",
 	NULL
 };
 
@@ -1535,6 +1538,7 @@ static const enum index next_item[] = {
 	ITEM_ICMP6_ND_OPT_SLA_ETH,
 	ITEM_ICMP6_ND_OPT_TLA_ETH,
 	ITEM_META,
+	ITEM_RANDOM,
 	ITEM_GRE_KEY,
 	ITEM_GRE_OPTION,
 	ITEM_GTP_PSC,
@@ -1842,6 +1846,12 @@ static const enum index item_meta[] = {
 	ZERO,
 };
 
+static const enum index item_random[] = {
+	ITEM_RANDOM_VALUE,
+	ITEM_NEXT,
+	ZERO,
+};
+
 static const enum index item_gtp_psc[] = {
 	ITEM_GTP_PSC_QFI,
 	ITEM_GTP_PSC_PDU_T,
@@ -5063,6 +5073,21 @@ static const struct token token_list[] = {
 		.args = ARGS(ARGS_ENTRY_MASK(struct rte_flow_item_meta,
 					     data, "\xff\xff\xff\xff")),
 	},
+	[ITEM_RANDOM] = {
+		.name = "random",
+		.help = "match random value",
+		.priv = PRIV_ITEM(RANDOM, sizeof(struct rte_flow_item_random)),
+		.next = NEXT(item_random),
+		.call = parse_vc,
+	},
+	[ITEM_RANDOM_VALUE] = {
+		.name = "value",
+		.help = "random value",
+		.next = NEXT(item_random, NEXT_ENTRY(COMMON_UNSIGNED),
+			     item_param),
+		.args = ARGS(ARGS_ENTRY_MASK(struct rte_flow_item_random,
+					     value, "\xff\xff")),
+	},
 	[ITEM_GRE_KEY] = {
 		.name = "gre_key",
 		.help = "match GRE key",
@@ -12634,6 +12659,9 @@ flow_item_default_mask(const struct rte_flow_item *item)
 	case RTE_FLOW_ITEM_TYPE_META:
 		mask = &rte_flow_item_meta_mask;
 		break;
+	case RTE_FLOW_ITEM_TYPE_RANDOM:
+		mask = &rte_flow_item_random_mask;
+		break;
 	case RTE_FLOW_ITEM_TYPE_FUZZY:
 		mask = &rte_flow_item_fuzzy_mask;
 		break;
diff --git a/doc/guides/testpmd_app_ug/testpmd_funcs.rst b/doc/guides/testpmd_app_ug/testpmd_funcs.rst
index a182479ab2..0b27a6fd97 100644
--- a/doc/guides/testpmd_app_ug/testpmd_funcs.rst
+++ b/doc/guides/testpmd_app_ug/testpmd_funcs.rst
@@ -3724,6 +3724,10 @@ This section lists supported pattern items and their attributes, if any.
 
   - ``data {unsigned}``: metadata value.
 
+- ``random``: match application specific random value.
+
+  - ``value {unsigned}``: random value.
+
 - ``gtp_psc``: match GTP PDU extension header with type 0x85.
 
   - ``pdu_type {unsigned}``: PDU type.
-- 
2.25.1

Re: [PATCH v1 0/2] ethdev: add random item support

[Ivan Malov]

Hi Michael,

Very interesting proposal. However, could you please
provide a use case example for this feature and also
provide an example of where such value could come
from, theoretically.

Thank you.

On Tue, 22 Aug 2023, Michael Baum wrote:

> Add support for matching random value using new "rte_flow_item_random"
> structure.
> This random value is not based on the packet data/headers.
> Application shouldn't assume that this value is kept during the life
> time of the packet.
>
> Michael Baum (2):
>  ethdev: add random item support
>  app/testpmd: add random item support
>
> app/test-pmd/cmdline_flow.c                 | 30 ++++++++++++++++++-
> doc/guides/nics/features/default.ini        |  1 +
> doc/guides/prog_guide/rte_flow.rst          | 11 +++++++
> doc/guides/rel_notes/release_23_11.rst      |  4 +++
> doc/guides/testpmd_app_ug/testpmd_funcs.rst |  4 +++
> lib/ethdev/rte_flow.c                       |  1 +
> lib/ethdev/rte_flow.h                       | 33 +++++++++++++++++++++
> 7 files changed, 83 insertions(+), 1 deletion(-)
>
> -- 
> 2.25.1
>
>

RE: [PATCH v1 0/2] ethdev: add random item support

[Michael Baum]

Hi Ivan, 

On Tue, 22 Aug 2023, Ivan Malov wrote: 
> 
> Hi Michael,
> 
> Very interesting proposal. However, could you please provide a use case example for this feature

I can think about 2 different use cases:
1. Sampling - when application wants to sample certain percentage of the flow, it can match random value for getting it.
2. Distribution - when application wants to distribute the traffic between ports/queues, it can match all random value range with send to port/queue actions.

> and also provide an example of where such value could come from, theoretically.

The random value can come from everywhere, it can come from hardware, software or even from the system clock.

> 
> Thank you.
> 
> On Tue, 22 Aug 2023, Michael Baum wrote:
> 
> > Add support for matching random value using new "rte_flow_item_random"
> > structure.
> > This random value is not based on the packet data/headers.
> > Application shouldn't assume that this value is kept during the life
> > time of the packet.
> >
> > Michael Baum (2):
> >  ethdev: add random item support
> >  app/testpmd: add random item support
> >
> > app/test-pmd/cmdline_flow.c                 | 30 ++++++++++++++++++-
> > doc/guides/nics/features/default.ini        |  1 +
> > doc/guides/prog_guide/rte_flow.rst          | 11 +++++++
> > doc/guides/rel_notes/release_23_11.rst      |  4 +++
> > doc/guides/testpmd_app_ug/testpmd_funcs.rst |  4 +++
> > lib/ethdev/rte_flow.c                       |  1 +
> > lib/ethdev/rte_flow.h                       | 33 +++++++++++++++++++++
> > 7 files changed, 83 insertions(+), 1 deletion(-)
> >
> > --
> > 2.25.1

Re: [PATCH v1 0/2] ethdev: add random item support

[Stephen Hemminger]

On Tue, 22 Aug 2023 16:41:09 +0400 (+04)
Ivan Malov <ivan.malov@arknetworks.am> wrote:

> Hi Michael,
> 
> Very interesting proposal. However, could you please
> provide a use case example for this feature and also
> provide an example of where such value could come
> from, theoretically.

A possible use case is netflow or ipfix traffic sampling

[PATCH v2 0/2] ethdev: add random item support

[Michael Baum]

Add support for matching random value using new "rte_flow_item_random"
structure.
This random value is not based on the packet data/headers.
Application shouldn't assume that this value is kept during the life
time of the packet.

v2:
 - Rabase.
 - Fix copy-paste mistake in release notes.

Michael Baum (2):
  ethdev: add random item support
  app/testpmd: add random item support

 app/test-pmd/cmdline_flow.c                 | 30 ++++++++++++++++++-
 doc/guides/nics/features/default.ini        |  1 +
 doc/guides/prog_guide/rte_flow.rst          | 11 +++++++
 doc/guides/rel_notes/release_23_11.rst      |  4 +++
 doc/guides/testpmd_app_ug/testpmd_funcs.rst |  4 +++
 lib/ethdev/rte_flow.c                       |  1 +
 lib/ethdev/rte_flow.h                       | 33 +++++++++++++++++++++
 7 files changed, 83 insertions(+), 1 deletion(-)

-- 
2.25.1

[PATCH v2 1/2] ethdev: add random item support

[Michael Baum]

Add support for a new item type "RTE_FLOW_ITEM_TYPE_RANDOM".
This item enables to match on some random value as a part of flow rule.

Signed-off-by: Michael Baum <michaelba@nvidia.com>
---
 doc/guides/nics/features/default.ini   |  1 +
 doc/guides/prog_guide/rte_flow.rst     | 11 +++++++++
 doc/guides/rel_notes/release_23_11.rst |  4 ++++
 lib/ethdev/rte_flow.c                  |  1 +
 lib/ethdev/rte_flow.h                  | 33 ++++++++++++++++++++++++++
 5 files changed, 50 insertions(+)

diff --git a/doc/guides/nics/features/default.ini b/doc/guides/nics/features/default.ini
index 2011e97127..0a790dafe8 100644
--- a/doc/guides/nics/features/default.ini
+++ b/doc/guides/nics/features/default.ini
@@ -139,6 +139,7 @@ pppoes               =
 pppoe_proto_id       =
 quota                =
 raw                  =
+random               =
 represented_port     =
 sctp                 =
 tag                  =
diff --git a/doc/guides/prog_guide/rte_flow.rst b/doc/guides/prog_guide/rte_flow.rst
index 5bc998a433..5ad699dff7 100644
--- a/doc/guides/prog_guide/rte_flow.rst
+++ b/doc/guides/prog_guide/rte_flow.rst
@@ -1566,6 +1566,17 @@ Matches an InfiniBand base transport header in RoCE packet.
 
 - ``hdr``: InfiniBand base transport header definition (``rte_ib.h``).
 
+Item: ``RANDOM``
+^^^^^^^^^^^^^^^^
+
+Matches a random value.
+
+This value is not based on the packet data/headers.
+Application shouldn't assume that this value is kept during the life time of
+the packet.
+
+- ``value``: Random value.
+
 Actions
 ~~~~~~~
 
diff --git a/doc/guides/rel_notes/release_23_11.rst b/doc/guides/rel_notes/release_23_11.rst
index 333e1d95a2..bcd71138cb 100644
--- a/doc/guides/rel_notes/release_23_11.rst
+++ b/doc/guides/rel_notes/release_23_11.rst
@@ -78,6 +78,10 @@ New Features
 * build: Optional libraries can now be selected with the new ``enable_libs``
   build option similarly to the existing ``enable_drivers`` build option.
 
+* **Added flow matching of random value.**
+
+  Added ``RTE_FLOW_ITEM_RANDOM`` to match random value.
+
 
 Removed Items
 -------------
diff --git a/lib/ethdev/rte_flow.c b/lib/ethdev/rte_flow.c
index 271d854f78..51db3e5aec 100644
--- a/lib/ethdev/rte_flow.c
+++ b/lib/ethdev/rte_flow.c
@@ -136,6 +136,7 @@ static const struct rte_flow_desc_data rte_flow_desc_item[] = {
 		     sizeof(struct rte_flow_item_icmp6_nd_opt_tla_eth)),
 	MK_FLOW_ITEM(MARK, sizeof(struct rte_flow_item_mark)),
 	MK_FLOW_ITEM(META, sizeof(struct rte_flow_item_meta)),
+	MK_FLOW_ITEM(RANDOM, sizeof(struct rte_flow_item_random)),
 	MK_FLOW_ITEM(TAG, sizeof(struct rte_flow_item_tag)),
 	MK_FLOW_ITEM(GRE_KEY, sizeof(rte_be32_t)),
 	MK_FLOW_ITEM(GRE_OPTION, sizeof(struct rte_flow_item_gre_opt)),
diff --git a/lib/ethdev/rte_flow.h b/lib/ethdev/rte_flow.h
index 2ebb76dbc0..b5228b293c 100644
--- a/lib/ethdev/rte_flow.h
+++ b/lib/ethdev/rte_flow.h
@@ -688,6 +688,19 @@ enum rte_flow_item_type {
 	 * @see struct rte_flow_item_ib_bth.
 	 */
 	RTE_FLOW_ITEM_TYPE_IB_BTH,
+
+	/**
+	 * [META]
+	 *
+	 * Matches a random value.
+	 *
+	 * This value is not based on the packet data/headers.
+	 * Application shouldn't assume that this value is kept during the life
+	 * time of the packet.
+	 *
+	 * @see struct rte_flow_item_random.
+	 */
+	RTE_FLOW_ITEM_TYPE_RANDOM,
 };
 
 /**
@@ -2031,6 +2044,25 @@ static const struct rte_flow_item_ib_bth rte_flow_item_ib_bth_mask = {
 };
 #endif
 
+/**
+ * @warning
+ * @b EXPERIMENTAL: this structure may change without prior notice
+ *
+ * RTE_FLOW_ITEM_TYPE_RANDOM
+ *
+ * Matches a random value.
+ */
+struct rte_flow_item_random {
+	uint32_t value;
+};
+
+/** Default mask for RTE_FLOW_ITEM_TYPE_RANDOM. */
+#ifndef __cplusplus
+static const struct rte_flow_item_random rte_flow_item_random_mask = {
+	.value = UINT32_MAX,
+};
+#endif
+
 /**
  * Matching pattern item definition.
  *
@@ -3875,6 +3907,7 @@ enum rte_flow_field_id {
 	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_RANDOM		/**< Random value. */
 };
 
 /**
-- 
2.25.1

Re: [PATCH v2 1/2] ethdev: add random item support

[Thomas Monjalon]

11/09/2023 09:41, Michael Baum:
> Add support for a new item type "RTE_FLOW_ITEM_TYPE_RANDOM".
> This item enables to match on some random value as a part of flow rule.
> 
> Signed-off-by: Michael Baum <michaelba@nvidia.com>
> ---
> +Item: ``RANDOM``
> +^^^^^^^^^^^^^^^^
> +
> +Matches a random value.
> +
> +This value is not based on the packet data/headers.
> +Application shouldn't assume that this value is kept during the life time of
> +the packet.
> +
> +- ``value``: Random value.

I think it is the opposite:
the value is defined by the application, right?
Then it matches randomly based on a number generator?

Please describe where the random is generated and what is the range.

We could also wonder why it is not integrated in the existing sampling item.

RE: [PATCH v2 1/2] ethdev: add random item support

[Michael Baum]

11/09/2023 19:00, Thomas Monjalon:
> 
> 11/09/2023 09:41, Michael Baum:
> > Add support for a new item type "RTE_FLOW_ITEM_TYPE_RANDOM".
> > This item enables to match on some random value as a part of flow rule.
> >
> > Signed-off-by: Michael Baum <michaelba@nvidia.com>
> > ---
> > +Item: ``RANDOM``
> > +^^^^^^^^^^^^^^^^
> > +
> > +Matches a random value.
> > +
> > +This value is not based on the packet data/headers.
> > +Application shouldn't assume that this value is kept during the life
> > +time of the packet.
> > +
> > +- ``value``: Random value.
> 
> I think it is the opposite:
> the value is defined by the application, right?
> Then it matches randomly based on a number generator?
Generating the random number is the PMD responsibility, it may be performed by either HW or SW.
The application provides the random value/range to match on.

> 
> Please describe where the random is generated and what is the range.
Ack

> 
> We could also wonder why it is not integrated in the existing sampling item.
We don't have sample item, we have existing sample action.

[PATCH v2 2/2] app/testpmd: add random item support

[Michael Baum]

Add support for random item, usage example:

	pattern random spec value 0x1 mask value 0x3 / eth / end

Flow rule with above pattern matching 25% of the traffic, it hits only
when random value suffix is "01" and miss the others ("00", "10", "11").

Signed-off-by: Michael Baum <michaelba@nvidia.com>
---
 app/test-pmd/cmdline_flow.c                 | 30 ++++++++++++++++++++-
 doc/guides/testpmd_app_ug/testpmd_funcs.rst |  4 +++
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/app/test-pmd/cmdline_flow.c b/app/test-pmd/cmdline_flow.c
index 94827bcc4a..55fb07ec91 100644
--- a/app/test-pmd/cmdline_flow.c
+++ b/app/test-pmd/cmdline_flow.c
@@ -417,6 +417,8 @@ enum index {
 	ITEM_ICMP6_ND_OPT_TLA_ETH_TLA,
 	ITEM_META,
 	ITEM_META_DATA,
+	ITEM_RANDOM,
+	ITEM_RANDOM_VALUE,
 	ITEM_GRE_KEY,
 	ITEM_GRE_KEY_VALUE,
 	ITEM_GRE_OPTION,
@@ -936,7 +938,8 @@ static const char *const modify_field_ids[] = {
 	"ipv6_proto",
 	"flex_item",
 	"hash_result",
-	"geneve_opt_type", "geneve_opt_class", "geneve_opt_data", "mpls",
+	"geneve_opt_type", "geneve_opt_class", "geneve_opt_data",
+	"mpls", "random",
 	NULL
 };
 
@@ -1535,6 +1538,7 @@ static const enum index next_item[] = {
 	ITEM_ICMP6_ND_OPT_SLA_ETH,
 	ITEM_ICMP6_ND_OPT_TLA_ETH,
 	ITEM_META,
+	ITEM_RANDOM,
 	ITEM_GRE_KEY,
 	ITEM_GRE_OPTION,
 	ITEM_GTP_PSC,
@@ -1842,6 +1846,12 @@ static const enum index item_meta[] = {
 	ZERO,
 };
 
+static const enum index item_random[] = {
+	ITEM_RANDOM_VALUE,
+	ITEM_NEXT,
+	ZERO,
+};
+
 static const enum index item_gtp_psc[] = {
 	ITEM_GTP_PSC_QFI,
 	ITEM_GTP_PSC_PDU_T,
@@ -5063,6 +5073,21 @@ static const struct token token_list[] = {
 		.args = ARGS(ARGS_ENTRY_MASK(struct rte_flow_item_meta,
 					     data, "\xff\xff\xff\xff")),
 	},
+	[ITEM_RANDOM] = {
+		.name = "random",
+		.help = "match random value",
+		.priv = PRIV_ITEM(RANDOM, sizeof(struct rte_flow_item_random)),
+		.next = NEXT(item_random),
+		.call = parse_vc,
+	},
+	[ITEM_RANDOM_VALUE] = {
+		.name = "value",
+		.help = "random value",
+		.next = NEXT(item_random, NEXT_ENTRY(COMMON_UNSIGNED),
+			     item_param),
+		.args = ARGS(ARGS_ENTRY_MASK(struct rte_flow_item_random,
+					     value, "\xff\xff")),
+	},
 	[ITEM_GRE_KEY] = {
 		.name = "gre_key",
 		.help = "match GRE key",
@@ -12634,6 +12659,9 @@ flow_item_default_mask(const struct rte_flow_item *item)
 	case RTE_FLOW_ITEM_TYPE_META:
 		mask = &rte_flow_item_meta_mask;
 		break;
+	case RTE_FLOW_ITEM_TYPE_RANDOM:
+		mask = &rte_flow_item_random_mask;
+		break;
 	case RTE_FLOW_ITEM_TYPE_FUZZY:
 		mask = &rte_flow_item_fuzzy_mask;
 		break;
diff --git a/doc/guides/testpmd_app_ug/testpmd_funcs.rst b/doc/guides/testpmd_app_ug/testpmd_funcs.rst
index a182479ab2..0b27a6fd97 100644
--- a/doc/guides/testpmd_app_ug/testpmd_funcs.rst
+++ b/doc/guides/testpmd_app_ug/testpmd_funcs.rst
@@ -3724,6 +3724,10 @@ This section lists supported pattern items and their attributes, if any.
 
   - ``data {unsigned}``: metadata value.
 
+- ``random``: match application specific random value.
+
+  - ``value {unsigned}``: random value.
+
 - ``gtp_psc``: match GTP PDU extension header with type 0x85.
 
   - ``pdu_type {unsigned}``: PDU type.
-- 
2.25.1

RE: [PATCH v2 2/2] app/testpmd: add random item support

[Ori Kam]

Hi Michael,

> -----Original Message-----
> From: Michael Baum <michaelba@nvidia.com>
> Sent: Monday, September 11, 2023 10:42 AM
> 
> Add support for random item, usage example:
> 
> 	pattern random spec value 0x1 mask value 0x3 / eth / end
> 
> Flow rule with above pattern matching 25% of the traffic, it hits only
> when random value suffix is "01" and miss the others ("00", "10", "11").
> 
> Signed-off-by: Michael Baum <michaelba@nvidia.com>
> ---

Acked-by: Ori Kam <orika@nvidia.com>
Best,
Ori

RE: [PATCH v2 0/2] ethdev: add random item support

[Morten Brørup]

> From: Michael Baum [mailto:michaelba@nvidia.com]
> Sent: Monday, 11 September 2023 08.42
> 
> Add support for matching random value using new "rte_flow_item_random"
> structure.

I get it. It can be used for things like stochastic sampling.

However, it doesn't provide support for e.g. 1/100 or 1/500.

So here's a suggestion:

Instead of "value" (which is irrelevant) & "mask" (which is what really controls the probability), wouldn't it be better if "value" was an inverse probability (and "mask" was irrelevant)? E.g. value=500 means that there is a 1 of 500 probability of a match.

Would this kind of random item better serve the purpose?

Or is the random item, in its current form, also required for other purposes?

Re: [PATCH v2 0/2] ethdev: add random item support

[Stephen Hemminger]

On Mon, 11 Sep 2023 18:55:45 +0200
Morten Brørup <mb@smartsharesystems.com> wrote:

> > From: Michael Baum [mailto:michaelba@nvidia.com]
> > Sent: Monday, 11 September 2023 08.42
> > 
> > Add support for matching random value using new
> > "rte_flow_item_random" structure.  
> 
> I get it. It can be used for things like stochastic sampling.
> 
> However, it doesn't provide support for e.g. 1/100 or 1/500.
> 
> So here's a suggestion:
> 
> Instead of "value" (which is irrelevant) & "mask" (which is what
> really controls the probability), wouldn't it be better if "value"
> was an inverse probability (and "mask" was irrelevant)? E.g.
> value=500 means that there is a 1 of 500 probability of a match.
> 
> Would this kind of random item better serve the purpose?
> 
> Or is the random item, in its current form, also required for other
> purposes?
> 

For netem (Linux kernel) needed to support expressing a percent in fixed
point number. The solution was to express it as:
    Percent = X / UINT32_MAX

RE: [PATCH v2 0/2] ethdev: add random item support

[Michael Baum]

On  Monday, 11 September 2023 20:53 Stephen Hemminger wrote: 
> 
> On Mon, 11 Sep 2023 18:55:45 +0200
> Morten Brørup <mb@smartsharesystems.com> wrote:
> 
> > > From: Michael Baum [mailto:michaelba@nvidia.com]
> > > Sent: Monday, 11 September 2023 08.42
> > >
> > > Add support for matching random value using new
> > > "rte_flow_item_random" structure.
> >
> > I get it. It can be used for things like stochastic sampling.
> >
> > However, it doesn't provide support for e.g. 1/100 or 1/500.
> >
> > So here's a suggestion:
> >
> > Instead of "value" (which is irrelevant) & "mask" (which is what
> > really controls the probability), wouldn't it be better if "value"
> > was an inverse probability (and "mask" was irrelevant)? E.g.
> > value=500 means that there is a 1 of 500 probability of a match.
> >
> > Would this kind of random item better serve the purpose?
> >
> > Or is the random item, in its current form, also required for other
> > purposes?
> >
> 
> For netem (Linux kernel) needed to support expressing a percent in fixed point
> number. The solution was to express it as:
>     Percent = X / UINT32_MAX

I concur with the notion that numbers can be utilized for probability calculations. However, it's important to acknowledge that when employing numbers, we are essentially working with a superset of possibilities due to their inherent versatility.

To illustrate this, consider the scenario where we transmit a numerical value to an application and use that same value across different stages of the pipeline. Take, for instance, the following use case:

In the initial stage, there is a 20% probability of selecting a packet for sampling before proceeding with the pipeline.

Towards the end of the pipeline, if the packet was initially sampled, we sample it once more.

The challenge arises when attempting to replicate this process solely using a numerical value, as there is no guarantee that the same packet will be chosen both in the initial and final stages. Conversely, by duplicating the random number and using it as a reference for matching, we can effectively implement the aforementioned usage scenario.

I hope this clarifies the distinction and benefits of utilizing random numbers in our probability calculations.

RE: [PATCH v2 0/2] ethdev: add random item support

[Michael Baum]

On Mon, 11 Sep 2023 18:55:45 +0200
Morten Brørup <mb@smartsharesystems.com> wrote: 
> 
> > From: Michael Baum [mailto:michaelba@nvidia.com]
> > Sent: Monday, 11 September 2023 08.42
> >
> > Add support for matching random value using new "rte_flow_item_random"
> > structure.
> 
> I get it. It can be used for things like stochastic sampling.
> 
> However, it doesn't provide support for e.g. 1/100 or 1/500.

It supports those values using "last" field in addition to "spec" and "mask".
It matches a range of random values for any requested percentage.

> 
> So here's a suggestion:
> 
> Instead of "value" (which is irrelevant) & "mask" (which is what really controls the
> probability), wouldn't it be better if "value" was an inverse probability (and
> "mask" was irrelevant)? E.g. value=500 means that there is a 1 of 500 probability
> of a match.
> 
> Would this kind of random item better serve the purpose?
> 
> Or is the random item, in its current form, also required for other purposes?

The random item is more generic than stochastic sampling, it can implement distribution. 
When application wants to distribute the traffic between ports/queues, it can match all random value range with send to port/queue actions.

[PATCH v3 0/2] ethdev: add random item support

[Michael Baum]

Add support for matching random value using new "rte_flow_item_random"
structure.
This random value is not based on the packet data/headers.
Application shouldn't assume that this value is kept during the life
time of the packet.

v2:
 - Rabase.
 - Fix copy-paste mistake in release notes.

v3:
 - Rabase.
 - Move release notes to the new release file.
 - Improve documentation.


Michael Baum (2):
  ethdev: add random item support
  app/testpmd: add random item support

 app/test-pmd/cmdline_flow.c                 | 28 +++++++++++++++++
 doc/guides/nics/features/default.ini        |  1 +
 doc/guides/prog_guide/rte_flow.rst          | 13 ++++++++
 doc/guides/rel_notes/release_24_03.rst      |  4 +++
 doc/guides/testpmd_app_ug/testpmd_funcs.rst |  4 +++
 lib/ethdev/rte_flow.c                       |  1 +
 lib/ethdev/rte_flow.h                       | 35 ++++++++++++++++++++-
 7 files changed, 85 insertions(+), 1 deletion(-)

-- 
2.25.1

[PATCH v3 1/2] ethdev: add random item support

[Michael Baum]

Add support for a new item type "RTE_FLOW_ITEM_TYPE_RANDOM".
This item enables to match on some random value as a part of flow rule.

Signed-off-by: Michael Baum <michaelba@nvidia.com>
---
 doc/guides/nics/features/default.ini   |  1 +
 doc/guides/prog_guide/rte_flow.rst     | 13 ++++++++++
 doc/guides/rel_notes/release_24_03.rst |  4 +++
 lib/ethdev/rte_flow.c                  |  1 +
 lib/ethdev/rte_flow.h                  | 35 +++++++++++++++++++++++++-
 5 files changed, 53 insertions(+), 1 deletion(-)

diff --git a/doc/guides/nics/features/default.ini b/doc/guides/nics/features/default.ini
index 806cb033ff..6d50236292 100644
--- a/doc/guides/nics/features/default.ini
+++ b/doc/guides/nics/features/default.ini
@@ -140,6 +140,7 @@ pppoe_proto_id       =
 ptype                =
 quota                =
 raw                  =
+random               =
 represented_port     =
 sctp                 =
 tag                  =
diff --git a/doc/guides/prog_guide/rte_flow.rst b/doc/guides/prog_guide/rte_flow.rst
index 627b845bfb..fd7fddb6cd 100644
--- a/doc/guides/prog_guide/rte_flow.rst
+++ b/doc/guides/prog_guide/rte_flow.rst
@@ -1573,6 +1573,19 @@ Matches the packet type as defined in rte_mbuf_ptype.
 
 - ``packet_type``: L2/L3/L4 and tunnel information.
 
+Item: ``RANDOM``
+^^^^^^^^^^^^^^^^
+
+Matches a random value.
+
+The rundom number is generated by PMD,
+application can match on either exact value or range of values.
+This value is not based on the packet data/headers.
+Application shouldn't assume that this value is kept during the life time of
+the packet.
+
+- ``value``: Specific value to match.
+
 Actions
 ~~~~~~~
 
diff --git a/doc/guides/rel_notes/release_24_03.rst b/doc/guides/rel_notes/release_24_03.rst
index e9c9717706..ab91ce2b21 100644
--- a/doc/guides/rel_notes/release_24_03.rst
+++ b/doc/guides/rel_notes/release_24_03.rst
@@ -55,6 +55,10 @@ New Features
      Also, make sure to start the actual text at the margin.
      =======================================================
 
+* **Added flow matching of random value.**
+
+  Added ``RTE_FLOW_ITEM_RANDOM`` to match random value.
+
 
 Removed Items
 -------------
diff --git a/lib/ethdev/rte_flow.c b/lib/ethdev/rte_flow.c
index 549e329558..090b936ca9 100644
--- a/lib/ethdev/rte_flow.c
+++ b/lib/ethdev/rte_flow.c
@@ -136,6 +136,7 @@ static const struct rte_flow_desc_data rte_flow_desc_item[] = {
 		     sizeof(struct rte_flow_item_icmp6_nd_opt_tla_eth)),
 	MK_FLOW_ITEM(MARK, sizeof(struct rte_flow_item_mark)),
 	MK_FLOW_ITEM(META, sizeof(struct rte_flow_item_meta)),
+	MK_FLOW_ITEM(RANDOM, sizeof(struct rte_flow_item_random)),
 	MK_FLOW_ITEM(TAG, sizeof(struct rte_flow_item_tag)),
 	MK_FLOW_ITEM(GRE_KEY, sizeof(rte_be32_t)),
 	MK_FLOW_ITEM(GRE_OPTION, sizeof(struct rte_flow_item_gre_opt)),
diff --git a/lib/ethdev/rte_flow.h b/lib/ethdev/rte_flow.h
index affdc8121b..887401bb86 100644
--- a/lib/ethdev/rte_flow.h
+++ b/lib/ethdev/rte_flow.h
@@ -704,6 +704,19 @@ enum rte_flow_item_type {
 	 *
 	 */
 	RTE_FLOW_ITEM_TYPE_PTYPE,
+
+	/**
+	 * [META]
+	 *
+	 * Matches a random value.
+	 *
+	 * This value is not based on the packet data/headers.
+	 * Application shouldn't assume that this value is kept during the life
+	 * time of the packet.
+	 *
+	 * @see struct rte_flow_item_random.
+	 */
+	RTE_FLOW_ITEM_TYPE_RANDOM,
 };
 
 /**
@@ -2047,6 +2060,25 @@ static const struct rte_flow_item_ib_bth rte_flow_item_ib_bth_mask = {
 };
 #endif
 
+/**
+ * @warning
+ * @b EXPERIMENTAL: this structure may change without prior notice
+ *
+ * RTE_FLOW_ITEM_TYPE_RANDOM
+ *
+ * Matches a random value.
+ */
+struct rte_flow_item_random {
+	uint32_t value;
+};
+
+/** Default mask for RTE_FLOW_ITEM_TYPE_RANDOM. */
+#ifndef __cplusplus
+static const struct rte_flow_item_random rte_flow_item_random_mask = {
+	.value = UINT32_MAX,
+};
+#endif
+
 /**
  * Matching pattern item definition.
  *
@@ -3903,7 +3935,8 @@ enum rte_flow_field_id {
 	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. */
+	RTE_FLOW_FIELD_IPV6_PAYLOAD_LEN,/**< IPv6 payload length. */
+	RTE_FLOW_FIELD_RANDOM		/**< Random value. */
 };
 
 /**
-- 
2.25.1

RE: [PATCH v3 1/2] ethdev: add random item support

[Dariusz Sosnowski]

Hi Michael,

> +Item: ``RANDOM``
> +^^^^^^^^^^^^^^^^
> +
> +Matches a random value.
> +
> +The rundom number is generated by PMD,
s/rundom/random

I'm not sure that mentioning PMD here is fully correct, because in my opinion it implies that SW generates it.
HW, SW and system clock were mentioned as examples of sources of randomness in previous discussions on this API.

Also, I think it's worth adding that "number == unsigned integer with at most 32 bits."
It gives some leeway for any driver implementing this API - value is uint32_t but not all bits must be used.
For example, some HW may support only 16-bit random number generation.
Such HW might implement validation on mask, where mask with more than 16 bits would be rejected.

What do you think about the following proposal based on those comments?
 
"A random unsigned integer (at most 32-bit) is generated for each packet
during flow rule processing, by either HW, SW or some external source.
Application can match on either exact value or range of values."

> +Application shouldn't assume that this value is kept during the life
> +time of the packet.
s/life time/lifetime

Best regards,
Dariusz Sosnowski

RE: [PATCH v3 1/2] ethdev: add random item support

[Michael Baum]

On 12/8/2023 8:54 PM, 0 Dariusz Sosnowski wrote:
> 
> Hi Michael,
> 
> > +Item: ``RANDOM``
> > +^^^^^^^^^^^^^^^^
> > +
> > +Matches a random value.
> > +
> > +The rundom number is generated by PMD,
> s/rundom/random
Ack, thank you.

> 
> I'm not sure that mentioning PMD here is fully correct, because in my opinion it
> implies that SW generates it.
> HW, SW and system clock were mentioned as examples of sources of randomness
> in previous discussions on this API.
> 
> Also, I think it's worth adding that "number == unsigned integer with at most 32
> bits."
> It gives some leeway for any driver implementing this API - value is uint32_t but
> not all bits must be used.
> For example, some HW may support only 16-bit random number generation.
> Such HW might implement validation on mask, where mask with more than 16
> bits would be rejected.
> 
> What do you think about the following proposal based on those comments?
> 
> "A random unsigned integer (at most 32-bit) is generated for each packet during
> flow rule processing, by either HW, SW or some external source.
> Application can match on either exact value or range of values."
I think your suggestion is good, but the words "for each packet" imply that the generated random value is oriented to the packet.
So I'm taking it and keeping the next lines: 
" This value is not based on the packet data/headers.
Application shouldn't assume that this value is kept during the lifetime of the packet."
> 
> > +Application shouldn't assume that this value is kept during the life
> > +time of the packet.
> s/life time/lifetime
Ack, thank you.

> 
> Best regards,
> Dariusz Sosnowski

RE: [PATCH v3 1/2] ethdev: add random item support

[Dariusz Sosnowski]

> >
> > I'm not sure that mentioning PMD here is fully correct, because in my
> > opinion it implies that SW generates it.
> > HW, SW and system clock were mentioned as examples of sources of
> > randomness in previous discussions on this API.
> >
> > Also, I think it's worth adding that "number == unsigned integer with
> > at most 32 bits."
> > It gives some leeway for any driver implementing this API - value is
> > uint32_t but not all bits must be used.
> > For example, some HW may support only 16-bit random number generation.
> > Such HW might implement validation on mask, where mask with more than
> > 16 bits would be rejected.
> >
> > What do you think about the following proposal based on those comments?
> >
> > "A random unsigned integer (at most 32-bit) is generated for each
> > packet during flow rule processing, by either HW, SW or some external source.
> > Application can match on either exact value or range of values."
> I think your suggestion is good, but the words "for each packet" imply that the
> generated random value is oriented to the packet.
> So I'm taking it and keeping the next lines:
> " This value is not based on the packet data/headers.
> Application shouldn't assume that this value is kept during the lifetime of the
> packet."
Sounds good to me.

Best regards,
Dariusz Sosnowski

RE: [PATCH v3 1/2] ethdev: add random item support

[Dariusz Sosnowski]

> +       RTE_FLOW_FIELD_RANDOM           /**< Random value. */
I think that this new modify field type should be mentioned in release notes as well.

Best regards,
Dariusz Sosnowski

[PATCH v3 2/2] app/testpmd: add random item support

[Michael Baum]

Add support for random item, usage example:

	pattern random spec value 0x1 mask value 0x3 / eth / end

Flow rule with above pattern matching 25% of the traffic, it hits only
when random value suffix is "01" and miss the others ("00", "10", "11").

Signed-off-by: Michael Baum <michaelba@nvidia.com>
---
 app/test-pmd/cmdline_flow.c                 | 28 +++++++++++++++++++++
 doc/guides/testpmd_app_ug/testpmd_funcs.rst |  4 +++
 2 files changed, 32 insertions(+)

diff --git a/app/test-pmd/cmdline_flow.c b/app/test-pmd/cmdline_flow.c
index ce71818705..359c187b3c 100644
--- a/app/test-pmd/cmdline_flow.c
+++ b/app/test-pmd/cmdline_flow.c
@@ -433,6 +433,8 @@ enum index {
 	ITEM_ICMP6_ND_OPT_TLA_ETH_TLA,
 	ITEM_META,
 	ITEM_META_DATA,
+	ITEM_RANDOM,
+	ITEM_RANDOM_VALUE,
 	ITEM_GRE_KEY,
 	ITEM_GRE_KEY_VALUE,
 	ITEM_GRE_OPTION,
@@ -956,6 +958,7 @@ static const char *const modify_field_ids[] = {
 	"hash_result",
 	"geneve_opt_type", "geneve_opt_class", "geneve_opt_data", "mpls",
 	"tcp_data_off", "ipv4_ihl", "ipv4_total_len", "ipv6_payload_len",
+	"random",
 	NULL
 };
 
@@ -1562,6 +1565,7 @@ static const enum index next_item[] = {
 	ITEM_ICMP6_ND_OPT_SLA_ETH,
 	ITEM_ICMP6_ND_OPT_TLA_ETH,
 	ITEM_META,
+	ITEM_RANDOM,
 	ITEM_GRE_KEY,
 	ITEM_GRE_OPTION,
 	ITEM_GTP_PSC,
@@ -1873,6 +1877,12 @@ static const enum index item_meta[] = {
 	ZERO,
 };
 
+static const enum index item_random[] = {
+	ITEM_RANDOM_VALUE,
+	ITEM_NEXT,
+	ZERO,
+};
+
 static const enum index item_gtp_psc[] = {
 	ITEM_GTP_PSC_QFI,
 	ITEM_GTP_PSC_PDU_T,
@@ -5195,6 +5205,21 @@ static const struct token token_list[] = {
 		.args = ARGS(ARGS_ENTRY_MASK(struct rte_flow_item_meta,
 					     data, "\xff\xff\xff\xff")),
 	},
+	[ITEM_RANDOM] = {
+		.name = "random",
+		.help = "match random value",
+		.priv = PRIV_ITEM(RANDOM, sizeof(struct rte_flow_item_random)),
+		.next = NEXT(item_random),
+		.call = parse_vc,
+	},
+	[ITEM_RANDOM_VALUE] = {
+		.name = "value",
+		.help = "random value",
+		.next = NEXT(item_random, NEXT_ENTRY(COMMON_UNSIGNED),
+			     item_param),
+		.args = ARGS(ARGS_ENTRY_MASK(struct rte_flow_item_random,
+					     value, "\xff\xff")),
+	},
 	[ITEM_GRE_KEY] = {
 		.name = "gre_key",
 		.help = "match GRE key",
@@ -12883,6 +12908,9 @@ flow_item_default_mask(const struct rte_flow_item *item)
 	case RTE_FLOW_ITEM_TYPE_META:
 		mask = &rte_flow_item_meta_mask;
 		break;
+	case RTE_FLOW_ITEM_TYPE_RANDOM:
+		mask = &rte_flow_item_random_mask;
+		break;
 	case RTE_FLOW_ITEM_TYPE_FUZZY:
 		mask = &rte_flow_item_fuzzy_mask;
 		break;
diff --git a/doc/guides/testpmd_app_ug/testpmd_funcs.rst b/doc/guides/testpmd_app_ug/testpmd_funcs.rst
index 447e28e694..0cd1615d9e 100644
--- a/doc/guides/testpmd_app_ug/testpmd_funcs.rst
+++ b/doc/guides/testpmd_app_ug/testpmd_funcs.rst
@@ -3756,6 +3756,10 @@ This section lists supported pattern items and their attributes, if any.
 
   - ``data {unsigned}``: metadata value.
 
+- ``random``: match application specific random value.
+
+  - ``value {unsigned}``: random value.
+
 - ``gtp_psc``: match GTP PDU extension header with type 0x85.
 
   - ``pdu_type {unsigned}``: PDU type.
-- 
2.25.1

RE: [PATCH v3 2/2] app/testpmd: add random item support

[Dariusz Sosnowski]

Hi Michael,

> Subject: [PATCH v3 2/2] app/testpmd: add random item support
> 
> Add support for random item, usage example:
> 
>         pattern random spec value 0x1 mask value 0x3 / eth / end
> 
> Flow rule with above pattern matching 25% of the traffic, it hits only when
> random value suffix is "01" and miss the others ("00", "10", "11").
> 
> Signed-off-by: Michael Baum <michaelba@nvidia.com>
Reviewed-by: Dariusz Sosnowski <dsosnowski@nvidia.com>

Best regards,
Dariusz Sosnowski

[PATCH v4 0/2] ethdev: add random item support

[Michael Baum]

Add support for matching random value using new "rte_flow_item_random"
structure.
This random value is not based on the packet data/headers.
Application shouldn't assume that this value is kept during the lifetime
of the packet.

v2:
 - Rabase.
 - Fix copy-paste mistake in release notes.

v3:
 - Rabase.
 - Move release notes to the new release file.
 - Improve documentation.

v4:
 - Mention random field ID in release file.
 - Improve documentation.
 - Fix typos in documentation.
 - Add "Reviewed-by" and "Acked-by" from previous versions.


Michael Baum (2):
  ethdev: add random item support
  app/testpmd: add random item support

 app/test-pmd/cmdline_flow.c                 | 28 +++++++++++++++++
 doc/guides/nics/features/default.ini        |  1 +
 doc/guides/prog_guide/rte_flow.rst          | 14 +++++++++
 doc/guides/rel_notes/release_24_03.rst      |  5 +++
 doc/guides/testpmd_app_ug/testpmd_funcs.rst |  4 +++
 lib/ethdev/rte_flow.c                       |  1 +
 lib/ethdev/rte_flow.h                       | 35 ++++++++++++++++++++-
 7 files changed, 87 insertions(+), 1 deletion(-)

-- 
2.25.1

[PATCH v4 1/2] ethdev: add random item support

[Michael Baum]

Add support for a new item type "RTE_FLOW_ITEM_TYPE_RANDOM".
This item enables to match on some random value as a part of flow rule.

Signed-off-by: Michael Baum <michaelba@nvidia.com>
---
 doc/guides/nics/features/default.ini   |  1 +
 doc/guides/prog_guide/rte_flow.rst     | 14 +++++++++++
 doc/guides/rel_notes/release_24_03.rst |  5 ++++
 lib/ethdev/rte_flow.c                  |  1 +
 lib/ethdev/rte_flow.h                  | 35 +++++++++++++++++++++++++-
 5 files changed, 55 insertions(+), 1 deletion(-)

diff --git a/doc/guides/nics/features/default.ini b/doc/guides/nics/features/default.ini
index 806cb033ff..6d50236292 100644
--- a/doc/guides/nics/features/default.ini
+++ b/doc/guides/nics/features/default.ini
@@ -140,6 +140,7 @@ pppoe_proto_id       =
 ptype                =
 quota                =
 raw                  =
+random               =
 represented_port     =
 sctp                 =
 tag                  =
diff --git a/doc/guides/prog_guide/rte_flow.rst b/doc/guides/prog_guide/rte_flow.rst
index 627b845bfb..900fdaefb6 100644
--- a/doc/guides/prog_guide/rte_flow.rst
+++ b/doc/guides/prog_guide/rte_flow.rst
@@ -1573,6 +1573,20 @@ Matches the packet type as defined in rte_mbuf_ptype.
 
 - ``packet_type``: L2/L3/L4 and tunnel information.
 
+Item: ``RANDOM``
+^^^^^^^^^^^^^^^^
+
+Matches a random value.
+
+A random unsigned integer (at most 32-bit) is generated for each packet during
+flow rule processing, by either HW, SW or some external source.
+Application can match on either exact value or range of values.
+This value is not based on the packet data/headers.
+Application shouldn't assume that this value is kept during the lifetime of
+the packet.
+
+- ``value``: Specific value to match.
+
 Actions
 ~~~~~~~
 
diff --git a/doc/guides/rel_notes/release_24_03.rst b/doc/guides/rel_notes/release_24_03.rst
index 6f8ad27808..819cef7f20 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 flow matching of random value.**
+
+  * Added ``RTE_FLOW_ITEM_TYPE_RANDOM`` to match random value.
+  * Added ``RTE_FLOW_FIELD_RANDOM`` to represent it in field API.
+
 
 Removed Items
 -------------
diff --git a/lib/ethdev/rte_flow.c b/lib/ethdev/rte_flow.c
index 549e329558..090b936ca9 100644
--- a/lib/ethdev/rte_flow.c
+++ b/lib/ethdev/rte_flow.c
@@ -136,6 +136,7 @@ static const struct rte_flow_desc_data rte_flow_desc_item[] = {
 		     sizeof(struct rte_flow_item_icmp6_nd_opt_tla_eth)),
 	MK_FLOW_ITEM(MARK, sizeof(struct rte_flow_item_mark)),
 	MK_FLOW_ITEM(META, sizeof(struct rte_flow_item_meta)),
+	MK_FLOW_ITEM(RANDOM, sizeof(struct rte_flow_item_random)),
 	MK_FLOW_ITEM(TAG, sizeof(struct rte_flow_item_tag)),
 	MK_FLOW_ITEM(GRE_KEY, sizeof(rte_be32_t)),
 	MK_FLOW_ITEM(GRE_OPTION, sizeof(struct rte_flow_item_gre_opt)),
diff --git a/lib/ethdev/rte_flow.h b/lib/ethdev/rte_flow.h
index affdc8121b..860b100e45 100644
--- a/lib/ethdev/rte_flow.h
+++ b/lib/ethdev/rte_flow.h
@@ -704,6 +704,19 @@ enum rte_flow_item_type {
 	 *
 	 */
 	RTE_FLOW_ITEM_TYPE_PTYPE,
+
+	/**
+	 * [META]
+	 *
+	 * Matches a random value.
+	 *
+	 * This value is not based on the packet data/headers.
+	 * Application shouldn't assume that this value is kept during the
+	 * lifetime of the packet.
+	 *
+	 * @see struct rte_flow_item_random.
+	 */
+	RTE_FLOW_ITEM_TYPE_RANDOM,
 };
 
 /**
@@ -2047,6 +2060,25 @@ static const struct rte_flow_item_ib_bth rte_flow_item_ib_bth_mask = {
 };
 #endif
 
+/**
+ * @warning
+ * @b EXPERIMENTAL: this structure may change without prior notice
+ *
+ * RTE_FLOW_ITEM_TYPE_RANDOM
+ *
+ * Matches a random value.
+ */
+struct rte_flow_item_random {
+	uint32_t value;
+};
+
+/** Default mask for RTE_FLOW_ITEM_TYPE_RANDOM. */
+#ifndef __cplusplus
+static const struct rte_flow_item_random rte_flow_item_random_mask = {
+	.value = UINT32_MAX,
+};
+#endif
+
 /**
  * Matching pattern item definition.
  *
@@ -3903,7 +3935,8 @@ enum rte_flow_field_id {
 	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. */
+	RTE_FLOW_FIELD_IPV6_PAYLOAD_LEN,/**< IPv6 payload length. */
+	RTE_FLOW_FIELD_RANDOM		/**< Random value. */
 };
 
 /**
-- 
2.25.1

RE: [PATCH v4 1/2] ethdev: add random item support

[Dariusz Sosnowski]

> Subject: [PATCH v4 1/2] ethdev: add random item support
> 
> Add support for a new item type "RTE_FLOW_ITEM_TYPE_RANDOM".
> This item enables to match on some random value as a part of flow rule.
> 
> Signed-off-by: Michael Baum <michaelba@nvidia.com>
Acked-by: Dariusz Sosnowski <dsosnowski@nvidia.com>

Best regards,
Dariusz Sosnowski

RE: [PATCH v4 1/2] ethdev: add random item support

[Ori Kam]

Hi Michael,

> -----Original Message-----
> From: Michael Baum <michaelba@nvidia.com>
> Sent: Thursday, December 14, 2023 12:59 PM
> Add support for a new item type "RTE_FLOW_ITEM_TYPE_RANDOM".
> This item enables to match on some random value as a part of flow rule.
> 
> Signed-off-by: Michael Baum <michaelba@nvidia.com>
> ---

Acked-by: Ori Kam <orika@nvidia.com>
Best,
Ori

Re: [PATCH v4 1/2] ethdev: add random item support

[Ferruh Yigit]

On 12/14/2023 10:58 AM, Michael Baum wrote:
> Add support for a new item type "RTE_FLOW_ITEM_TYPE_RANDOM".
> This item enables to match on some random value as a part of flow rule.
> 
> Signed-off-by: Michael Baum <michaelba@nvidia.com>
> ---
>  doc/guides/nics/features/default.ini   |  1 +
>  doc/guides/prog_guide/rte_flow.rst     | 14 +++++++++++
>  doc/guides/rel_notes/release_24_03.rst |  5 ++++
>  lib/ethdev/rte_flow.c                  |  1 +
>  lib/ethdev/rte_flow.h                  | 35 +++++++++++++++++++++++++-
>  5 files changed, 55 insertions(+), 1 deletion(-)
> 
> diff --git a/doc/guides/nics/features/default.ini b/doc/guides/nics/features/default.ini
> index 806cb033ff..6d50236292 100644
> --- a/doc/guides/nics/features/default.ini
> +++ b/doc/guides/nics/features/default.ini
> @@ -140,6 +140,7 @@ pppoe_proto_id       =
>  ptype                =
>  quota                =
>  raw                  =
> +random               =
>  represented_port     =
>  sctp                 =
>  tag                  =
> diff --git a/doc/guides/prog_guide/rte_flow.rst b/doc/guides/prog_guide/rte_flow.rst
> index 627b845bfb..900fdaefb6 100644
> --- a/doc/guides/prog_guide/rte_flow.rst
> +++ b/doc/guides/prog_guide/rte_flow.rst
> @@ -1573,6 +1573,20 @@ Matches the packet type as defined in rte_mbuf_ptype.
>  
>  - ``packet_type``: L2/L3/L4 and tunnel information.
>  
> +Item: ``RANDOM``
> +^^^^^^^^^^^^^^^^
> +
> +Matches a random value.
> +
> +A random unsigned integer (at most 32-bit) is generated for each packet during
> +flow rule processing, by either HW, SW or some external source.
> +Application can match on either exact value or range of values.
> +This value is not based on the packet data/headers.
> +Application shouldn't assume that this value is kept during the lifetime of
> +the packet.
> +
> +- ``value``: Specific value to match.
> +


Hi Michael,

What is the usecase for the 'random' flow item?

Is it to match some kind of metadata generated by HW?
Or is it a way to sampling traffic?

And how random 'random' item is, is it configured/set in HW or random
per packet?

RE: [PATCH v4 1/2] ethdev: add random item support

[Michael Baum]

On 12/14/2023 2:18 PM, Ferruh Yigit wrote: 
> 
> On 12/14/2023 10:58 AM, Michael Baum wrote:
> > Add support for a new item type "RTE_FLOW_ITEM_TYPE_RANDOM".
> > This item enables to match on some random value as a part of flow rule.
> >

...

> >
> > +Item: ``RANDOM``
> > +^^^^^^^^^^^^^^^^
> > +
> > +Matches a random value.
> > +
> > +A random unsigned integer (at most 32-bit) is generated for each
> > +packet during flow rule processing, by either HW, SW or some external source.
> > +Application can match on either exact value or range of values.
> > +This value is not based on the packet data/headers.
> > +Application shouldn't assume that this value is kept during the
> > +lifetime of the packet.
> > +
> > +- ``value``: Specific value to match.
> > +
> 
> 
> Hi Michael,
> 
> What is the usecase for the 'random' flow item?
I can think about 2 different use cases:
1. Sampling - when application wants to sample certain percentage of the flow, it can match random value for getting it.
2. Distribution - when application wants to distribute the traffic between ports/queues, it can match all random value range with send to port/queue actions.

> 
> Is it to match some kind of metadata generated by HW?
It can be generated by either HW, SW or some external source.
Each PMD supporting random item responds to have a generator for that.

> Or is it a way to sampling traffic?
It can be both. The PMD can use random value generated by HW while user match on it for sampling traffic.

> 
> And how random 'random' item is, is it configured/set in HW or random per packet?
From API perspective, it is pure random not packet oriented. Same packet can get different values during the pipeline.
I mentioned it in documentation:
"This value is not based on the packet data/headers.
Application shouldn't assume that this value is kept during the lifetime of the packet."

Re: [PATCH v4 1/2] ethdev: add random item support

[Ferruh Yigit]

On 12/14/2023 1:43 PM, Michael Baum wrote:
> 
> On 12/14/2023 2:18 PM, Ferruh Yigit wrote: 
>>
>> On 12/14/2023 10:58 AM, Michael Baum wrote:
>>> Add support for a new item type "RTE_FLOW_ITEM_TYPE_RANDOM".
>>> This item enables to match on some random value as a part of flow rule.
>>>
> 
> ...
> 
>>>
>>> +Item: ``RANDOM``
>>> +^^^^^^^^^^^^^^^^
>>> +
>>> +Matches a random value.
>>> +
>>> +A random unsigned integer (at most 32-bit) is generated for each
>>> +packet during flow rule processing, by either HW, SW or some external source.
>>> +Application can match on either exact value or range of values.
>>> +This value is not based on the packet data/headers.
>>> +Application shouldn't assume that this value is kept during the
>>> +lifetime of the packet.
>>> +
>>> +- ``value``: Specific value to match.
>>> +
>>
>>
>> Hi Michael,
>>
>> What is the usecase for the 'random' flow item?
> I can think about 2 different use cases:
> 1. Sampling - when application wants to sample certain percentage of the flow, it can match random value for getting it.
> 2. Distribution - when application wants to distribute the traffic between ports/queues, it can match all random value range with send to port/queue actions.
> 
>>
>> Is it to match some kind of metadata generated by HW?
> It can be generated by either HW, SW or some external source.
> Each PMD supporting random item responds to have a generator for that.
> 
>> Or is it a way to sampling traffic?
> It can be both. The PMD can use random value generated by HW while user match on it for sampling traffic.
> 
>>
>> And how random 'random' item is, is it configured/set in HW or random per packet?
> From API perspective, it is pure random not packet oriented. Same packet can get different values during the pipeline.
> I mentioned it in documentation:
> "This value is not based on the packet data/headers.
> Application shouldn't assume that this value is kept during the lifetime of the packet."
>

Thanks Michael, for clarification.

I was thinking if this can be used together with external (to DPDK) flow
steering configuration.
Like external tool can set values to match for specific pattern,
tcp --> 100
udp --> 200
Later these values can be used by DPDK application and this filtering item.

Can you please confirm this is not the "use case"/intention, if so we
may need to rename the rte flow item.


Also there will be driver implementation in this release, right?

RE: [PATCH v4 1/2] ethdev: add random item support

[Michael Baum]

On 12/14/2023 5:56 PM, Ferruh Yigit wrote:
> 
> On 12/14/2023 1:43 PM, Michael Baum wrote:
> >
> > On 12/14/2023 2:18 PM, Ferruh Yigit wrote:
> >>
> >> On 12/14/2023 10:58 AM, Michael Baum wrote:
> >>> Add support for a new item type "RTE_FLOW_ITEM_TYPE_RANDOM".
> >>> This item enables to match on some random value as a part of flow rule.
> >>>
> >
> > ...
> >
> >>>
> >>> +Item: ``RANDOM``
> >>> +^^^^^^^^^^^^^^^^
> >>> +
> >>> +Matches a random value.
> >>> +
> >>> +A random unsigned integer (at most 32-bit) is generated for each
> >>> +packet during flow rule processing, by either HW, SW or some external
> source.
> >>> +Application can match on either exact value or range of values.
> >>> +This value is not based on the packet data/headers.
> >>> +Application shouldn't assume that this value is kept during the
> >>> +lifetime of the packet.
> >>> +
> >>> +- ``value``: Specific value to match.
> >>> +
> >>
> >>
> >> Hi Michael,
> >>
> >> What is the usecase for the 'random' flow item?
> > I can think about 2 different use cases:
> > 1. Sampling - when application wants to sample certain percentage of the flow,
> it can match random value for getting it.
> > 2. Distribution - when application wants to distribute the traffic between
> ports/queues, it can match all random value range with send to port/queue
> actions.
> >
> >>
> >> Is it to match some kind of metadata generated by HW?
> > It can be generated by either HW, SW or some external source.
> > Each PMD supporting random item responds to have a generator for that.
> >
> >> Or is it a way to sampling traffic?
> > It can be both. The PMD can use random value generated by HW while user
> match on it for sampling traffic.
> >
> >>
> >> And how random 'random' item is, is it configured/set in HW or random per
> packet?
> > From API perspective, it is pure random not packet oriented. Same packet can
> get different values during the pipeline.
> > I mentioned it in documentation:
> > "This value is not based on the packet data/headers.
> > Application shouldn't assume that this value is kept during the lifetime of the
> packet."
> >
> 
> Thanks Michael, for clarification.
> 
> I was thinking if this can be used together with external (to DPDK) flow steering
> configuration.
> Like external tool can set values to match for specific pattern, tcp --> 100 udp -->
> 200 Later these values can be used by DPDK application and this filtering item.
> 
> Can you please confirm this is not the "use case"/intention, if so we may need to
> rename the rte flow item.

Hi,  this is not the use-case.
> 
> Also there will be driver implementation in this release, right?

Yes, series-30558 ("net/mlx5: add random item support")
https://patchwork.dpdk.org/project/dpdk/cover/20231214151248.1654878-1-michaelba@nvidia.com/

[PATCH v4 2/2] app/testpmd: add random item support

[Michael Baum]

Add support for random item, usage example:

	pattern random spec value 0x1 mask value 0x3 / eth / end

Flow rule with above pattern matching 25% of the traffic, it hits only
when random value suffix is "01" and miss the others ("00", "10", "11").

Signed-off-by: Michael Baum <michaelba@nvidia.com>
Reviewed-by: Dariusz Sosnowski <dsosnowski@nvidia.com>
Acked-by: Ori Kam <orika@nvidia.com>
---
 app/test-pmd/cmdline_flow.c                 | 28 +++++++++++++++++++++
 doc/guides/testpmd_app_ug/testpmd_funcs.rst |  4 +++
 2 files changed, 32 insertions(+)

diff --git a/app/test-pmd/cmdline_flow.c b/app/test-pmd/cmdline_flow.c
index ce71818705..359c187b3c 100644
--- a/app/test-pmd/cmdline_flow.c
+++ b/app/test-pmd/cmdline_flow.c
@@ -433,6 +433,8 @@ enum index {
 	ITEM_ICMP6_ND_OPT_TLA_ETH_TLA,
 	ITEM_META,
 	ITEM_META_DATA,
+	ITEM_RANDOM,
+	ITEM_RANDOM_VALUE,
 	ITEM_GRE_KEY,
 	ITEM_GRE_KEY_VALUE,
 	ITEM_GRE_OPTION,
@@ -956,6 +958,7 @@ static const char *const modify_field_ids[] = {
 	"hash_result",
 	"geneve_opt_type", "geneve_opt_class", "geneve_opt_data", "mpls",
 	"tcp_data_off", "ipv4_ihl", "ipv4_total_len", "ipv6_payload_len",
+	"random",
 	NULL
 };
 
@@ -1562,6 +1565,7 @@ static const enum index next_item[] = {
 	ITEM_ICMP6_ND_OPT_SLA_ETH,
 	ITEM_ICMP6_ND_OPT_TLA_ETH,
 	ITEM_META,
+	ITEM_RANDOM,
 	ITEM_GRE_KEY,
 	ITEM_GRE_OPTION,
 	ITEM_GTP_PSC,
@@ -1873,6 +1877,12 @@ static const enum index item_meta[] = {
 	ZERO,
 };
 
+static const enum index item_random[] = {
+	ITEM_RANDOM_VALUE,
+	ITEM_NEXT,
+	ZERO,
+};
+
 static const enum index item_gtp_psc[] = {
 	ITEM_GTP_PSC_QFI,
 	ITEM_GTP_PSC_PDU_T,
@@ -5195,6 +5205,21 @@ static const struct token token_list[] = {
 		.args = ARGS(ARGS_ENTRY_MASK(struct rte_flow_item_meta,
 					     data, "\xff\xff\xff\xff")),
 	},
+	[ITEM_RANDOM] = {
+		.name = "random",
+		.help = "match random value",
+		.priv = PRIV_ITEM(RANDOM, sizeof(struct rte_flow_item_random)),
+		.next = NEXT(item_random),
+		.call = parse_vc,
+	},
+	[ITEM_RANDOM_VALUE] = {
+		.name = "value",
+		.help = "random value",
+		.next = NEXT(item_random, NEXT_ENTRY(COMMON_UNSIGNED),
+			     item_param),
+		.args = ARGS(ARGS_ENTRY_MASK(struct rte_flow_item_random,
+					     value, "\xff\xff")),
+	},
 	[ITEM_GRE_KEY] = {
 		.name = "gre_key",
 		.help = "match GRE key",
@@ -12883,6 +12908,9 @@ flow_item_default_mask(const struct rte_flow_item *item)
 	case RTE_FLOW_ITEM_TYPE_META:
 		mask = &rte_flow_item_meta_mask;
 		break;
+	case RTE_FLOW_ITEM_TYPE_RANDOM:
+		mask = &rte_flow_item_random_mask;
+		break;
 	case RTE_FLOW_ITEM_TYPE_FUZZY:
 		mask = &rte_flow_item_fuzzy_mask;
 		break;
diff --git a/doc/guides/testpmd_app_ug/testpmd_funcs.rst b/doc/guides/testpmd_app_ug/testpmd_funcs.rst
index 447e28e694..0cd1615d9e 100644
--- a/doc/guides/testpmd_app_ug/testpmd_funcs.rst
+++ b/doc/guides/testpmd_app_ug/testpmd_funcs.rst
@@ -3756,6 +3756,10 @@ This section lists supported pattern items and their attributes, if any.
 
   - ``data {unsigned}``: metadata value.
 
+- ``random``: match application specific random value.
+
+  - ``value {unsigned}``: random value.
+
 - ``gtp_psc``: match GTP PDU extension header with type 0x85.
 
   - ``pdu_type {unsigned}``: PDU type.
-- 
2.25.1

Re: [PATCH v4 0/2] ethdev: add random item support

[Ferruh Yigit]

On 12/14/2023 10:58 AM, Michael Baum wrote:
> Add support for matching random value using new "rte_flow_item_random"
> structure.
> This random value is not based on the packet data/headers.
> Application shouldn't assume that this value is kept during the lifetime
> of the packet.
> 
> v2:
>  - Rabase.
>  - Fix copy-paste mistake in release notes.
> 
> v3:
>  - Rabase.
>  - Move release notes to the new release file.
>  - Improve documentation.
> 
> v4:
>  - Mention random field ID in release file.
>  - Improve documentation.
>  - Fix typos in documentation.
>  - Add "Reviewed-by" and "Acked-by" from previous versions.
> 
> 
> Michael Baum (2):
>   ethdev: add random item support
>   app/testpmd: add random item support
> >
> Acked-by: Dariusz Sosnowski <dsosnowski@nvidia.com>
>
> Acked-by: Ori Kam <orika@nvidia.com>
>

Series applied to dpdk-next-net/main, thanks.