[PATCH V2 2/2] app/testpmd: assign custom ID to flow rules

[Gregory Etelson <getelson@nvidia.com>]

From: Eli Britstein <elibr@nvidia.com>

Upon creation of a flow, testpmd assigns it a flow ID. Later, the
flow ID is used for flow operations (query, destroy, dump).

The testpmd application allows to manage flow rules with its IDs.
The flow ID is known only when the flow is created.
In order to prepare a complete sequence of testpmd commands to
copy/paste, the flow IDs must be predictable.

Allow the user to provide an assigned ID.

Example:
testpmd> flow create 0 ingress user_id 0x1234 pattern eth / end actions
count / drop / end
Flow rule #0 created, user-id 0x1234

testpmd> flow query 0 0x1234 count user_id

testpmd> flow dump 0 user_id rule 0x1234

testpmd> flow destroy 0 rule 0x1234 user_id
Flow rule #0 destroyed, user-id 0x1234

Here, "user_id" is a flag that signifies the "rule" ID is the user-id.

The motivation is from OVS. OVS dumps its "rte_flow_create" calls to the
log in testpmd commands syntax. As the flow ID testpmd would assign is
unkwon, it cannot log valid "flow destroy" commands.

With this enhancement, valid testpmd commands can be created in a
log to copy/paste to testpmd.
The application's flows sequence can then be played back in
testpmd, to enable enhanced dpdk debug capabilities of the
applications's flows in a controlled environment of testpmd
rather than a dynamic, more difficult to debug environment of the
application.

Signed-off-by: Eli Britstein <elibr@nvidia.com>
---
 app/test-pmd/cmdline_flow.c                 | 72 +++++++++++++++++++--
 app/test-pmd/config.c                       | 34 +++++++---
 app/test-pmd/testpmd.h                      | 12 ++--
 doc/guides/testpmd_app_ug/testpmd_funcs.rst | 33 +++++++---
 4 files changed, 121 insertions(+), 30 deletions(-)

diff --git a/app/test-pmd/cmdline_flow.c b/app/test-pmd/cmdline_flow.c
index aab0df91c2..669da31e5d 100644
--- a/app/test-pmd/cmdline_flow.c
+++ b/app/test-pmd/cmdline_flow.c
@@ -206,9 +206,11 @@ enum index {
 
 	/* Destroy arguments. */
 	DESTROY_RULE,
+	DESTROY_IS_USER_ID,
 
 	/* Query arguments. */
 	QUERY_ACTION,
+	QUERY_IS_USER_ID,
 
 	/* List arguments. */
 	LIST_GROUP,
@@ -224,10 +226,12 @@ enum index {
 	VC_TRANSFER,
 	VC_TUNNEL_SET,
 	VC_TUNNEL_MATCH,
+	VC_USER_ID,
 
 	/* Dump arguments */
 	DUMP_ALL,
 	DUMP_ONE,
+	DUMP_IS_USER_ID,
 
 	/* Configure arguments */
 	CONFIG_QUEUES_NUMBER,
@@ -1077,6 +1081,7 @@ struct buffer {
 			uint32_t act_templ_id;
 			struct rte_flow_attr attr;
 			struct tunnel_ops tunnel_ops;
+			uintptr_t user_id;
 			struct rte_flow_item *pattern;
 			struct rte_flow_action *actions;
 			struct rte_flow_action *masks;
@@ -1087,15 +1092,18 @@ struct buffer {
 		struct {
 			uint64_t *rule;
 			uint64_t rule_n;
+			bool is_user_id;
 		} destroy; /**< Destroy arguments. */
 		struct {
 			char file[128];
 			bool mode;
 			uint64_t rule;
+			bool is_user_id;
 		} dump; /**< Dump arguments. */
 		struct {
 			uint64_t rule;
 			struct rte_flow_action action;
+			bool is_user_id;
 		} query; /**< Query arguments. */
 		struct {
 			uint32_t *group;
@@ -1319,6 +1327,7 @@ static const enum index next_ia_qu_attr[] = {
 static const enum index next_dump_subcmd[] = {
 	DUMP_ALL,
 	DUMP_ONE,
+	DUMP_IS_USER_ID,
 	ZERO,
 };
 
@@ -1339,12 +1348,14 @@ static const enum index next_vc_attr[] = {
 	VC_TRANSFER,
 	VC_TUNNEL_SET,
 	VC_TUNNEL_MATCH,
+	VC_USER_ID,
 	ITEM_PATTERN,
 	ZERO,
 };
 
 static const enum index next_destroy_attr[] = {
 	DESTROY_RULE,
+	DESTROY_IS_USER_ID,
 	END,
 	ZERO,
 };
@@ -1355,6 +1366,12 @@ static const enum index next_dump_attr[] = {
 	ZERO,
 };
 
+static const enum index next_query_attr[] = {
+	QUERY_IS_USER_ID,
+	END,
+	ZERO,
+};
+
 static const enum index next_list_attr[] = {
 	LIST_GROUP,
 	END,
@@ -3533,7 +3550,7 @@ static const struct token token_list[] = {
 	[DESTROY] = {
 		.name = "destroy",
 		.help = "destroy specific flow rules",
-		.next = NEXT(NEXT_ENTRY(DESTROY_RULE),
+		.next = NEXT(next_destroy_attr,
 			     NEXT_ENTRY(COMMON_PORT_ID)),
 		.args = ARGS(ARGS_ENTRY(struct buffer, port)),
 		.call = parse_destroy,
@@ -3555,7 +3572,7 @@ static const struct token token_list[] = {
 	[QUERY] = {
 		.name = "query",
 		.help = "query an existing flow rule",
-		.next = NEXT(NEXT_ENTRY(QUERY_ACTION),
+		.next = NEXT(next_query_attr, NEXT_ENTRY(QUERY_ACTION),
 			     NEXT_ENTRY(COMMON_RULE_ID),
 			     NEXT_ENTRY(COMMON_PORT_ID)),
 		.args = ARGS(ARGS_ENTRY(struct buffer, args.query.action.type),
@@ -3674,6 +3691,12 @@ static const struct token token_list[] = {
 		.args = ARGS(ARGS_ENTRY_PTR(struct buffer, args.destroy.rule)),
 		.call = parse_destroy,
 	},
+	[DESTROY_IS_USER_ID] = {
+		.name = "user_id",
+		.help = "rule identifier is user-id",
+		.next = NEXT(next_destroy_attr),
+		.call = parse_destroy,
+	},
 	/* Dump arguments. */
 	[DUMP_ALL] = {
 		.name = "all",
@@ -3690,6 +3713,12 @@ static const struct token token_list[] = {
 				ARGS_ENTRY(struct buffer, args.dump.rule)),
 		.call = parse_dump,
 	},
+	[DUMP_IS_USER_ID] = {
+		.name = "user_id",
+		.help = "rule identifier is user-id",
+		.next = NEXT(next_dump_subcmd),
+		.call = parse_dump,
+	},
 	/* Query arguments. */
 	[QUERY_ACTION] = {
 		.name = "{action}",
@@ -3698,6 +3727,12 @@ static const struct token token_list[] = {
 		.call = parse_action,
 		.comp = comp_action,
 	},
+	[QUERY_IS_USER_ID] = {
+		.name = "user_id",
+		.help = "rule identifier is user-id",
+		.next = NEXT(next_query_attr),
+		.call = parse_query,
+	},
 	/* List arguments. */
 	[LIST_GROUP] = {
 		.name = "group",
@@ -3759,6 +3794,13 @@ static const struct token token_list[] = {
 		.args = ARGS(ARGS_ENTRY(struct tunnel_ops, id)),
 		.call = parse_vc,
 	},
+	[VC_USER_ID] = {
+		.name = "user_id",
+		.help = "specify a user id to create",
+		.next = NEXT(next_vc_attr, NEXT_ENTRY(COMMON_UNSIGNED)),
+		.args = ARGS(ARGS_ENTRY(struct buffer, args.vc.user_id)),
+		.call = parse_vc,
+	},
 	/* Validate/create pattern. */
 	[ITEM_PATTERN] = {
 		.name = "pattern",
@@ -7415,11 +7457,15 @@ parse_vc(struct context *ctx, const struct token *token,
 	case VC_TUNNEL_MATCH:
 		ctx->object = &out->args.vc.tunnel_ops;
 		break;
+	case VC_USER_ID:
+		ctx->object = out;
+		break;
 	}
 	ctx->objmask = NULL;
 	switch (ctx->curr) {
 	case VC_GROUP:
 	case VC_PRIORITY:
+	case VC_USER_ID:
 		return len;
 	case VC_TUNNEL_SET:
 		out->args.vc.tunnel_ops.enabled = 1;
@@ -9109,6 +9155,10 @@ parse_destroy(struct context *ctx, const struct token *token,
 					       sizeof(double));
 		return len;
 	}
+	if (ctx->curr == DESTROY_IS_USER_ID) {
+		out->args.destroy.is_user_id = true;
+		return len;
+	}
 	if (((uint8_t *)(out->args.destroy.rule + out->args.destroy.rule_n) +
 	     sizeof(*out->args.destroy.rule)) > (uint8_t *)out + size)
 		return -1;
@@ -9179,6 +9229,9 @@ parse_dump(struct context *ctx, const struct token *token,
 		ctx->object = out;
 		ctx->objmask = NULL;
 		return len;
+	case DUMP_IS_USER_ID:
+		out->args.dump.is_user_id = true;
+		return len;
 	default:
 		return -1;
 	}
@@ -9208,6 +9261,10 @@ parse_query(struct context *ctx, const struct token *token,
 		ctx->object = out;
 		ctx->objmask = NULL;
 	}
+	if (ctx->curr == QUERY_IS_USER_ID) {
+		out->args.query.is_user_id = true;
+		return len;
+	}
 	return len;
 }
 
@@ -11602,11 +11659,12 @@ cmd_flow_parsed(const struct buffer *in)
 	case CREATE:
 		port_flow_create(in->port, &in->args.vc.attr,
 				 in->args.vc.pattern, in->args.vc.actions,
-				 &in->args.vc.tunnel_ops);
+				 &in->args.vc.tunnel_ops, in->args.vc.user_id);
 		break;
 	case DESTROY:
 		port_flow_destroy(in->port, in->args.destroy.rule_n,
-				  in->args.destroy.rule);
+				  in->args.destroy.rule,
+				  in->args.destroy.is_user_id);
 		break;
 	case FLUSH:
 		port_flow_flush(in->port);
@@ -11614,11 +11672,13 @@ cmd_flow_parsed(const struct buffer *in)
 	case DUMP_ONE:
 	case DUMP_ALL:
 		port_flow_dump(in->port, in->args.dump.mode,
-				in->args.dump.rule, in->args.dump.file);
+				in->args.dump.rule, in->args.dump.file,
+				in->args.dump.is_user_id);
 		break;
 	case QUERY:
 		port_flow_query(in->port, in->args.query.rule,
-				&in->args.query.action);
+				&in->args.query.action,
+				in->args.query.is_user_id);
 		break;
 	case LIST:
 		port_flow_list(in->port, in->args.list.group_n,
diff --git a/app/test-pmd/config.c b/app/test-pmd/config.c
index 804af98c0e..c3aaeaed6b 100644
--- a/app/test-pmd/config.c
+++ b/app/test-pmd/config.c
@@ -3305,7 +3305,8 @@ port_flow_create(portid_t port_id,
 		 const struct rte_flow_attr *attr,
 		 const struct rte_flow_item *pattern,
 		 const struct rte_flow_action *actions,
-		 const struct tunnel_ops *tunnel_ops)
+		 const struct tunnel_ops *tunnel_ops,
+		 uintptr_t user_id)
 {
 	struct rte_flow *flow;
 	struct rte_port *port;
@@ -3353,17 +3354,23 @@ port_flow_create(portid_t port_id,
 	}
 	pf->next = port->flow_list;
 	pf->id = id;
+	pf->user_id = user_id;
 	pf->flow = flow;
 	port->flow_list = pf;
 	if (tunnel_ops->enabled)
 		port_flow_tunnel_offload_cmd_release(port_id, tunnel_ops, pft);
-	printf("Flow rule #%"PRIu64" created\n", pf->id);
+	if (user_id)
+		printf("Flow rule #%"PRIu64" created, user-id 0x%"PRIx64"\n",
+		       pf->id, pf->user_id);
+	else
+		printf("Flow rule #%"PRIu64" created\n", pf->id);
 	return 0;
 }
 
 /** Destroy a number of flow rules. */
 int
-port_flow_destroy(portid_t port_id, uint32_t n, const uint64_t *rule)
+port_flow_destroy(portid_t port_id, uint32_t n, const uint64_t *rule,
+		  bool is_user_id)
 {
 	struct rte_port *port;
 	struct port_flow **tmp;
@@ -3381,7 +3388,7 @@ port_flow_destroy(portid_t port_id, uint32_t n, const uint64_t *rule)
 			struct rte_flow_error error;
 			struct port_flow *pf = *tmp;
 
-			if (rule[i] != pf->id)
+			if (rule[i] != (is_user_id ? pf->user_id : pf->id))
 				continue;
 			/*
 			 * Poisoning to make sure PMDs update it in case
@@ -3392,7 +3399,13 @@ port_flow_destroy(portid_t port_id, uint32_t n, const uint64_t *rule)
 				ret = port_flow_complain(&error);
 				continue;
 			}
-			printf("Flow rule #%"PRIu64" destroyed\n", pf->id);
+			if (is_user_id)
+				printf("Flow rule #%"PRIu64" destroyed, "
+				       "user-id 0x%"PRIx64"\n",
+				       pf->id, pf->user_id);
+			else
+				printf("Flow rule #%"PRIu64" destroyed\n",
+				       pf->id);
 			*tmp = pf->next;
 			free(pf);
 			break;
@@ -3438,7 +3451,7 @@ port_flow_flush(portid_t port_id)
 /** Dump flow rules. */
 int
 port_flow_dump(portid_t port_id, bool dump_all, uint64_t rule_id,
-		const char *file_name)
+		const char *file_name, bool is_user_id)
 {
 	int ret = 0;
 	FILE *file = stdout;
@@ -3456,7 +3469,8 @@ port_flow_dump(portid_t port_id, bool dump_all, uint64_t rule_id,
 		port = &ports[port_id];
 		pflow = port->flow_list;
 		while (pflow) {
-			if (rule_id != pflow->id) {
+			if (rule_id !=
+			    (is_user_id ? pflow->user_id : pflow->id)) {
 				pflow = pflow->next;
 			} else {
 				tmpFlow = pflow->flow;
@@ -3498,7 +3512,7 @@ port_flow_dump(portid_t port_id, bool dump_all, uint64_t rule_id,
 /** Query a flow rule. */
 int
 port_flow_query(portid_t port_id, uint64_t rule,
-		const struct rte_flow_action *action)
+		const struct rte_flow_action *action, bool is_user_id)
 {
 	struct rte_flow_error error;
 	struct rte_port *port;
@@ -3516,7 +3530,7 @@ port_flow_query(portid_t port_id, uint64_t rule,
 		return -EINVAL;
 	port = &ports[port_id];
 	for (pf = port->flow_list; pf; pf = pf->next)
-		if (pf->id == rule)
+		if ((is_user_id ? pf->user_id : pf->id) == rule)
 			break;
 	if (!pf) {
 		fprintf(stderr, "Flow rule #%"PRIu64" not found\n", rule);
@@ -3636,7 +3650,7 @@ port_flow_aged(portid_t port_id, uint8_t destroy)
 			       ctx.pf->rule.attr->egress ? 'e' : '-',
 			       ctx.pf->rule.attr->transfer ? 't' : '-');
 			if (destroy && !port_flow_destroy(port_id, 1,
-							  &ctx.pf->id))
+							  &ctx.pf->id, false))
 				total++;
 			break;
 		case ACTION_AGE_CONTEXT_TYPE_INDIRECT_ACTION:
diff --git a/app/test-pmd/testpmd.h b/app/test-pmd/testpmd.h
index c2b0a0a48b..454f2b0c50 100644
--- a/app/test-pmd/testpmd.h
+++ b/app/test-pmd/testpmd.h
@@ -217,6 +217,7 @@ struct port_flow {
 	struct port_flow *next; /**< Next flow in list. */
 	struct port_flow *tmp; /**< Temporary linking. */
 	uint64_t id; /**< Flow rule ID. */
+	uint64_t user_id; /**< User rule ID. */
 	struct rte_flow *flow; /**< Opaque flow object returned by PMD. */
 	struct rte_flow_conv_rule rule; /**< Saved flow rule description. */
 	enum age_action_context_type age_type; /**< Age action context type. */
@@ -997,17 +998,20 @@ int port_flow_create(portid_t port_id,
 		     const struct rte_flow_attr *attr,
 		     const struct rte_flow_item *pattern,
 		     const struct rte_flow_action *actions,
-		     const struct tunnel_ops *tunnel_ops);
+		     const struct tunnel_ops *tunnel_ops,
+		     uintptr_t user_id);
 int port_action_handle_query(portid_t port_id, uint32_t id);
 void update_age_action_context(const struct rte_flow_action *actions,
 		     struct port_flow *pf);
 int mcast_addr_pool_destroy(portid_t port_id);
-int port_flow_destroy(portid_t port_id, uint32_t n, const uint64_t *rule);
+int port_flow_destroy(portid_t port_id, uint32_t n, const uint64_t *rule,
+		      bool is_user_id);
 int port_flow_flush(portid_t port_id);
 int port_flow_dump(portid_t port_id, bool dump_all,
-			uint64_t rule, const char *file_name);
+			uint64_t rule, const char *file_name,
+			bool is_user_id);
 int port_flow_query(portid_t port_id, uint64_t rule,
-		    const struct rte_flow_action *action);
+		    const struct rte_flow_action *action, bool is_user_id);
 void port_flow_list(portid_t port_id, uint32_t n, const uint32_t *group);
 void port_flow_aged(portid_t port_id, uint8_t destroy);
 const char *port_flow_tunnel_type(struct rte_flow_tunnel *tunnel);
diff --git a/doc/guides/testpmd_app_ug/testpmd_funcs.rst b/doc/guides/testpmd_app_ug/testpmd_funcs.rst
index 8f23847859..1b2991d94a 100644
--- a/doc/guides/testpmd_app_ug/testpmd_funcs.rst
+++ b/doc/guides/testpmd_app_ug/testpmd_funcs.rst
@@ -3009,13 +3009,14 @@ following sections.
 - Create a flow rule::
 
    flow create {port_id}
-       [group {group_id}] [priority {level}] [ingress] [egress] [transfer]
-       pattern {item} [/ {item} [...]] / end
+       [group {group_id}] [priority {level}] [ingress] [egress]
+       [transfer] [tunnel_set {tunnel_id}] [tunnel_match {tunnel_id}]
+       [user_id {user_id}] pattern {item} [/ {item} [...]] / end
        actions {action} [/ {action} [...]] / end
 
 - Destroy specific flow rules::
 
-   flow destroy {port_id} rule {rule_id} [...]
+   flow destroy {port_id} rule {rule_id} [...] [user_id]
 
 - Destroy all flow rules::
 
@@ -3023,7 +3024,7 @@ following sections.
 
 - Query an existing flow rule::
 
-   flow query {port_id} {rule_id} {action}
+   flow query {port_id} {rule_id} {action} [user_id]
 
 - List existing flow rules sorted by priority, filtered by group
   identifiers::
@@ -3036,11 +3037,11 @@ following sections.
 
 - Dump internal representation information of all flows in hardware::
 
-   flow dump {port_id} all {output_file}
+   flow dump {port_id} all {output_file} [user_id]
 
   for one flow::
 
-   flow dump {port_id} rule {rule_id} {output_file}
+   flow dump {port_id} rule {rule_id} {output_file} [user_id]
 
 - List and destroy aged flow rules::
 
@@ -3339,12 +3340,14 @@ to ``rte_flow_create()``::
    flow create {port_id}
       [group {group_id}] [priority {level}] [ingress] [egress] [transfer]
       [tunnel_set {tunnel_id}] [tunnel_match {tunnel_id}]
-      pattern {item} [/ {item} [...]] / end
+      [user_id {user_id}] pattern {item} [/ {item} [...]] / end
       actions {action} [/ {action} [...]] / end
 
 If successful, it will return a flow rule ID usable with other commands::
 
    Flow rule #[...] created
+   Or if user_id is provided:
+   Flow rule #[...] created, user-id [...]
 
 Otherwise it will show an error message of the form::
 
@@ -3354,6 +3357,7 @@ Parameters describe in the following order:
 
 - Attributes (*group*, *priority*, *ingress*, *egress*, *transfer* tokens).
 - Tunnel offload specification (tunnel_set, tunnel_match)
+- User identifier for the flow.
 - A matching pattern, starting with the *pattern* token and terminated by an
   *end* pattern item.
 - Actions, starting with the *actions* token and terminated by an *end*
@@ -4077,12 +4081,16 @@ Destroying flow rules
 by ``flow create``), this command calls ``rte_flow_destroy()`` as many
 times as necessary::
 
-   flow destroy {port_id} rule {rule_id} [...]
+   flow destroy {port_id} rule {rule_id} [...] [user_id]
 
 If successful, it will show::
 
    Flow rule #[...] destroyed
+   Or if user_id flag is provided:
+   Flow rule #[...] destroyed, user-id [...]
 
+Optional [user_id] is a flag that signifies the "rule" ID is the one
+provided by the user at creation.
 It does not report anything for rule IDs that do not exist. The usual error
 message is shown when a rule cannot be destroyed::
 
@@ -4161,8 +4169,10 @@ Querying flow rules
 ability. Such actions collect information that can be reported using this
 command. It is bound to ``rte_flow_query()``::
 
-   flow query {port_id} {rule_id} {action}
+   flow query {port_id} {rule_id} {action} [user_id]
 
+Optional [user_id] is a flag that signifies the "rule" ID is the one
+provided by the user at creation.
 If successful, it will display either the retrieved data for known actions
 or the following message::
 
@@ -4313,7 +4323,7 @@ Dumping HW internal information
 ``flow dump`` dumps the hardware's internal representation information of
 all flows. It is bound to ``rte_flow_dev_dump()``::
 
-   flow dump {port_id} {output_file}
+   flow dump {port_id} {output_file} [user_id]
 
 If successful, it will show::
 
@@ -4323,6 +4333,9 @@ Otherwise, it will complain error occurred::
 
    Caught error type [...] ([...]): [...]
 
+Optional [user_id] is a flag that signifies the "rule" ID is the one
+provided by the user at creation.
+
 Listing and destroying aged flow rules
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- 
2.25.1