[dpdk-dev] [PATCH 1/4] ethdev: add rte API for single flow dump

[Haifei Luo <haifeil@nvidia.com>]

Previous implementations support dump all the flows.Add new ones
to dump one flow.
New API added: rte_flow_dump.

Signed-off-by: Haifei Luo <haifeil@nvidia.com>
---
 doc/guides/nics/mlx5.rst            | 10 +++++++--
 doc/guides/prog_guide/rte_flow.rst  | 44 +++++++++++++++++++++++++++++++++++++
 lib/librte_ethdev/rte_flow.c        | 21 ++++++++++++++++++
 lib/librte_ethdev/rte_flow.h        | 24 ++++++++++++++++++++
 lib/librte_ethdev/rte_flow_driver.h |  6 +++++
 lib/librte_ethdev/version.map       |  1 +
 6 files changed, 104 insertions(+), 2 deletions(-)

diff --git a/doc/guides/nics/mlx5.rst b/doc/guides/nics/mlx5.rst
index 7c50497..b8b6b02 100644
--- a/doc/guides/nics/mlx5.rst
+++ b/doc/guides/nics/mlx5.rst
@@ -1778,13 +1778,19 @@ all flows with assistance of external tools.
 
    .. code-block:: console
 
-       testpmd> flow dump <port> <output_file>
+       To dump all flows:
+       testpmd> flow dump <port> all <output_file>
+       and dump one flow:
+       testpmd> flow dump <port> rule <rule_id> <output_file>
 
    - call rte_flow_dev_dump api:
 
    .. code-block:: console
 
+       To dump all flows:
        rte_flow_dev_dump(port, file, NULL);
+       and dump one flow:
+       rte_flow_dump(port, flow, file, NULL);
 
 #. Dump human-readable flows from raw file:
 
@@ -1792,4 +1798,4 @@ all flows with assistance of external tools.
 
    .. code-block:: console
 
-       mlx_steering_dump.py -f <output_file>
+       mlx_steering_dump.py -f <output_file> -flowptr <flow_ptr>
diff --git a/doc/guides/prog_guide/rte_flow.rst b/doc/guides/prog_guide/rte_flow.rst
index 62a5791..17e4351 100644
--- a/doc/guides/prog_guide/rte_flow.rst
+++ b/doc/guides/prog_guide/rte_flow.rst
@@ -3023,6 +3023,50 @@ Return values:
 
 - 0 on success, a negative errno value otherwise and ``rte_errno`` is set.
 
+Dump
+~~~~~
+
+Dump information for all or one flows.
+
+This Function rte_flow_dev_dump will dump the information for all the flows.
+
+.. code-block:: c
+
+   int
+   rte_flow_dev_dump(uint16_t port_id, FILE *file,
+                     struct rte_flow_error *error);
+
+Arguments:
+
+- ``port_id``: port identifier of Ethernet device.
+- ``file``: a pointer to a file for output
+- ``error``: perform verbose error reporting if not NULL. PMDs initialize
+  this structure in case of error only.
+
+Return values:
+
+- 0 on success, a negative errno value otherwise and ``rte_errno`` is set.
+
+This Function rte_flow_dump will dump the information for one flow.
+
+.. code-block:: c
+
+   int
+   rte_flow_dump(uint16_t port_id, struct rte_flow *flow, FILE *file,
+                 struct rte_flow_error *error);
+
+Arguments:
+
+- ``port_id``: port identifier of Ethernet device.
+- ``file``: a pointer to a file for output
+- ``flow``: flow rule handle to dump.
+- ``error``: perform verbose error reporting if not NULL. PMDs initialize
+  this structure in case of error only.
+
+Return values:
+
+- 0 on success, a negative errno value otherwise and ``rte_errno`` is set.
+
 Query
 ~~~~~
 
diff --git a/lib/librte_ethdev/rte_flow.c b/lib/librte_ethdev/rte_flow.c
index 241af6c..ff051e7 100644
--- a/lib/librte_ethdev/rte_flow.c
+++ b/lib/librte_ethdev/rte_flow.c
@@ -1044,6 +1044,27 @@ enum rte_flow_conv_item_spec_type {
 }
 
 int
+rte_flow_dump(uint16_t port_id, struct rte_flow *flow,
+			FILE *file, struct rte_flow_error *error)
+{
+	struct rte_eth_dev *dev = &rte_eth_devices[port_id];
+	const struct rte_flow_ops *ops = rte_flow_ops_get(port_id, error);
+	int ret;
+
+	if (unlikely(!ops))
+		return -rte_errno;
+	if (likely(!!ops->dev_single_dump)) {
+		fts_enter(dev);
+		ret = ops->dev_single_dump(dev, flow, file, error);
+		fts_exit(dev);
+		return flow_err(port_id, ret, error);
+	}
+	return rte_flow_error_set(error, ENOSYS,
+				  RTE_FLOW_ERROR_TYPE_UNSPECIFIED,
+				  NULL, rte_strerror(ENOSYS));
+}
+
+int
 rte_flow_get_aged_flows(uint16_t port_id, void **contexts,
 		    uint32_t nb_contexts, struct rte_flow_error *error)
 {
diff --git a/lib/librte_ethdev/rte_flow.h b/lib/librte_ethdev/rte_flow.h
index 68c68cd..aac9e6c 100644
--- a/lib/librte_ethdev/rte_flow.h
+++ b/lib/librte_ethdev/rte_flow.h
@@ -3214,6 +3214,30 @@ enum rte_flow_conv_op {
 rte_flow_dev_dump(uint16_t port_id, FILE *file, struct rte_flow_error *error);
 
 /**
+ * @warning
+ * @b EXPERIMENTAL: this API may change without prior notice.
+ *
+ * Dump hardware internal representation information of
+ * one rte flow to file.
+ *
+ * @param[in] port_id
+ *   The port identifier of the Ethernet device.
+ * @param[in] flow
+ *   The pointer of rte flow.
+ * @param[in] file
+ *   A pointer to a file for output.
+ * @param[out] error
+ *   Perform verbose error reporting if not NULL. PMDs initialize this
+ *   structure in case of error only.
+ * @return
+ *   0 on success, a nagative value otherwise.
+ */
+__rte_experimental
+int
+rte_flow_dump(uint16_t port_id, struct rte_flow *flow,
+			FILE *file, struct rte_flow_error *error);
+
+/**
  * Check if mbuf dynamic field for metadata is registered.
  *
  * @return
diff --git a/lib/librte_ethdev/rte_flow_driver.h b/lib/librte_ethdev/rte_flow_driver.h
index dabd819..8aa4510 100644
--- a/lib/librte_ethdev/rte_flow_driver.h
+++ b/lib/librte_ethdev/rte_flow_driver.h
@@ -102,6 +102,12 @@ struct rte_flow_ops {
 		(struct rte_eth_dev *dev,
 		 FILE *file,
 		 struct rte_flow_error *error);
+	/** See rte_flow_dump(). */
+	int (*dev_single_dump)
+		(struct rte_eth_dev *dev,
+		 struct rte_flow *flow,
+		 FILE *file,
+		 struct rte_flow_error *error);
 	/** See rte_flow_get_aged_flows() */
 	int (*get_aged_flows)
 		(struct rte_eth_dev *dev,
diff --git a/lib/librte_ethdev/version.map b/lib/librte_ethdev/version.map
index a124e1e..234798e 100644
--- a/lib/librte_ethdev/version.map
+++ b/lib/librte_ethdev/version.map
@@ -231,6 +231,7 @@ EXPERIMENTAL {
 	rte_eth_fec_get_capability;
 	rte_eth_fec_get;
 	rte_eth_fec_set;
+	rte_flow_dump;
 	rte_flow_shared_action_create;
 	rte_flow_shared_action_destroy;
 	rte_flow_shared_action_query;
-- 
1.8.3.1