lib: flow: update hw install API and documentation

Renaming HW install/uninstall API Updating documentation: * new APIs - installing flow into the HW * Corrections in API documentation Signed-off-by: Harman Kalra <hkalra@marvell.com> Change-Id: I3d2d59449e1575e28136a6dcd91add4e6b336cc2 Reviewed-on: https://sj1git1.cavium.com/c/IP/SW/dataplane/dpu-offload/+/134311 Tested-by: sa_ip-toolkits-Jenkins <sa_ip-toolkits-jenkins@marvell.com> Reviewed-by: Jerin Jacob <jerinj@marvell.com>
MarvellEmbeddedProcessors · Aug 28, 2024 · 71a2695 · 71a2695
1 parent f402312
commit 71a2695
Show file tree

Hide file tree

Showing 3 changed files with 81 additions and 48 deletions.
diff --git a/doc/guides/prog_guide/flow.rst b/doc/guides/prog_guide/flow.rst
@@ -112,11 +112,11 @@ TCAM.
                                   struct rte_flow_error *error);
 
 Arguments:
- ``port_id``: Port identifier of Ethernet device
- ``attr``: Flow rule attributes
- ``pattern``: Pattern specification (list terminated by the END pattern item)
- ``actions``: Associated actions (list terminated by the END action)
- ``error``: Perform verbose error reporting if not NULL
+ | ``port_id``: Port identifier of Ethernet device
+ | ``attr``: Flow rule attributes
+ | ``pattern``: Pattern specification (list terminated by the END pattern item)
+ | ``actions``: Associated actions (list terminated by the END action)
+ | ``error``: Perform verbose error reporting if not NULL
 
 Return value:
   A valid handle in case of success, NULL otherwise and errno is set
@@ -135,9 +135,9 @@ enough to decide to push the rule to HW.
  int dao_flow_lookup(uint16_t port_id, struct rte_mbuf **objs, uint16_t nb_objs);
 
 Arguments:
- ``port_id``: Port identifier of Ethernet device
- ``objs``: Array of packet buffers
- ``nb_objs``: No of packet buffers
+ | ``port_id``: Port identifier of Ethernet device
+ | ``objs``: Array of packet buffers
+ | ``nb_objs``: No of packet buffers
 
 Return value:
   0 on success, a negative errno value
@@ -153,9 +153,9 @@ Applications can call ``dao_flow_destroy()``. This function removes the rule fro
  int dao_flow_destroy(uint16_t port_id, struct dao_flow *flow, struct rte_flow_error *error);
 
 Arguments:
- ``port_id``: Port identifier of Ethernet device
- ``flow``: Flow rule handle to destroy
- ``error``: Perform verbose error reporting if not NULL
+ | ``port_id``: Port identifier of Ethernet device
+ | ``flow``: Flow rule handle to destroy
+ | ``error``: Perform verbose error reporting if not NULL
 
 Return value:
   0 on success, a negative errno value
@@ -171,11 +171,11 @@ accumulated through special actions that are integral to the flow rule definitio
   int dao_flow_query(uint16_t port_id, struct dao_flow *flow, const struct rte_flow_action *action, void *data, struct rte_flow_error *error);
 
 Arguments:
- ``port_id``: Port identifier of Ethernet device
- ``flow``: Flow rule handle to query
- ``action``: Action definition as defined in original flow rule
- ``data``: Pointer to storage for the associated query data type
- ``error``: Perform verbose error reporting if not NULL
+ | ``port_id``: Port identifier of Ethernet device
+ | ``flow``: Flow rule handle to query
+ | ``action``: Action definition as defined in original flow rule
+ | ``data``: Pointer to storage for the associated query data type
+ | ``error``: Perform verbose error reporting if not NULL
 
 Return value:
   0 on success, a negative errno value otherwise and rte_errno is set
@@ -191,8 +191,8 @@ handles associated with a port.
  int dao_flow_flush(uint16_t port_id, struct rte_flow_error *error);
 
 Arguments:
- ``port_id``: Port identifier of Ethernet device
- ``error``: Perform verbose error reporting if not NULL
+ | ``port_id``: Port identifier of Ethernet device
+ | ``error``: Perform verbose error reporting if not NULL
 
 Return value:
  0 on success, a negative value otherwise.
@@ -207,10 +207,50 @@ Dumping internal information about a flow.
  int dao_flow_dev_dump(uint16_t port_id, struct dao_flow *flow, FILE *file, struct rte_flow_error *error);
 
 Arguments:
- ``port_id``: The port identifier of the Ethernet device
- ``flow``: The pointer of flow rule to dump. Dump all rules if NULL
- ``file``: A pointer to a file for output
- ``error``: Perform verbose error reporting if not NULL
+ | ``port_id``: The port identifier of the Ethernet device
+ | ``flow``: The pointer of flow rule to dump. Dump all rules if NULL
+ | ``file``: A pointer to a file for output
+ | ``error``: Perform verbose error reporting if not NULL
+
+Return value:
+ 0 on success, a negative value otherwise.
+
+Installing flow directly into hardware
+--------------------------------------
+
+Install a flow rule on a given port which gets offloaded directly into the HW.
+
+.. code-block:: c
+
+ struct dao_flow *dao_flow_hw_install(uint16_t port_id, const struct rte_flow_attr *attr,
+                                      const struct rte_flow_item pattern[],
+                                      const struct rte_flow_action actions[],
+                                      struct rte_flow_error *error);
+
+Arguments:
+ | ``port_id``: Port identifier of Ethernet device
+ | ``attr``: Flow rule attributes
+ | ``pattern``: Pattern specification (list terminated by the END pattern item)
+ | ``actions``: Associated actions (list terminated by the END action)
+ | ``error``: Perform verbose error reporting if not NULL
+
+Return value:
+  A valid handle in case of success, NULL otherwise and errno is set
+
+Removing a flow from hardware
+-----------------------------
+
+Removing a flow rule on a given port which was directly offloaded to hardware.
+
+.. code-block:: c
+
+ int dao_flow_hw_uninstall(uint16_t port_id, struct dao_flow *flow,
+                           struct rte_flow_error *error);
+
+Arguments:
+ | ``port_id``: Port identifier of Ethernet device
+ | ``flow``: Pointer to flow which is to be removed.
+ | ``error``: Perform verbose error reporting if not NULL
 
 Return value:
  0 on success, a negative value otherwise.
diff --git a/lib/flow/dao_flow.c b/lib/flow/dao_flow.c
@@ -96,9 +96,9 @@ dao_flow_create(uint16_t port_id, const struct rte_flow_attr *attr,
 }
 
 struct dao_flow *
-dao_flow_install_hardware(uint16_t port_id, const struct rte_flow_attr *attr,
-			  const struct rte_flow_item pattern[],
-			  const struct rte_flow_action actions[], struct rte_flow_error *error)
+dao_flow_hw_install(uint16_t port_id, const struct rte_flow_attr *attr,
+		    const struct rte_flow_item pattern[], const struct rte_flow_action actions[],
+		    struct rte_flow_error *error)
 {
 	struct hw_offload_config_per_port *hw_off_cfg = NULL;
 	struct flow_config_per_port *flow_cfg_prt;
@@ -392,7 +392,7 @@ dao_flow_destroy(uint16_t port_id, struct dao_flow *flow, struct rte_flow_error
 }
 
 int
-dao_flow_uninstall_hardware(uint16_t port_id, struct dao_flow *flow, struct rte_flow_error *error)
+dao_flow_hw_uninstall(uint16_t port_id, struct dao_flow *flow, struct rte_flow_error *error)
 {
 	struct hw_offload_config_per_port *hw_off_cfg;
 	struct flow_config_per_port *flow_cfg_prt;

diff --git a/lib/flow/dao_flow.h b/lib/flow/dao_flow.h
@@ -131,10 +131,10 @@ struct dao_flow *dao_flow_create(uint16_t port_id, const struct rte_flow_attr *a
  * @return
  *   A valid handle in case of success, NULL otherwise and errno is set.
  */
-struct dao_flow *dao_flow_install_hardware(uint16_t port_id, const struct rte_flow_attr *attr,
-					   const struct rte_flow_item pattern[],
-					   const struct rte_flow_action actions[],
-					   struct rte_flow_error *error);
+struct dao_flow *dao_flow_hw_install(uint16_t port_id, const struct rte_flow_attr *attr,
+				     const struct rte_flow_item pattern[],
+				     const struct rte_flow_action actions[],
+				     struct rte_flow_error *error);
 
 /**
  * Destroy a flow rule on a given port.
@@ -165,8 +165,7 @@ int dao_flow_destroy(uint16_t port_id, struct dao_flow *flow, struct rte_flow_er
  * @return
  *   0 on success, a negative errno value.
  */
-int dao_flow_uninstall_hardware(uint16_t port_id, struct dao_flow *flow,
-				struct rte_flow_error *error);
+int dao_flow_hw_uninstall(uint16_t port_id, struct dao_flow *flow, struct rte_flow_error *error);
 
 /**
  * Lookup for a flow on a given port.
@@ -194,8 +193,6 @@ int dao_flow_lookup(uint16_t port_id, struct rte_mbuf **objs, uint16_t nb_objs);
  * Data is gathered by special actions which must be present in the flow
  * rule definition.
  *
- * \see RTE_FLOW_ACTION_TYPE_COUNT
- *
  * @param port_id
  *   Port identifier of Ethernet device.
  * @param flow
@@ -205,11 +202,10 @@ int dao_flow_lookup(uint16_t port_id, struct rte_mbuf **objs, uint16_t nb_objs);
  * @param[in, out] data
  *   Pointer to storage for the associated query data type.
  * @param[out] error
- *   Perform verbose error reporting if not NULL. PMDs initialize this
- *   structure in case of error only.
+ *   Perform verbose error reporting if not NULL.
  *
  * @return
- *   0 on success, a negative errno value otherwise and rte_errno is set.
+ *   0 on success, a negative errno value otherwise.
  */
 int dao_flow_query(uint16_t port_id, struct dao_flow *flow, const struct rte_flow_action *action,
 		   void *data, struct rte_flow_error *error);
@@ -224,8 +220,8 @@ int dao_flow_query(uint16_t port_id, struct dao_flow *flow, const struct rte_flo
  * @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.
+ *   Perform verbose error reporting if not NULL.
+ *
  * @return
  *   0 on success, a negative value otherwise.
  */
@@ -242,11 +238,10 @@ int dao_flow_dev_dump(uint16_t port_id, struct dao_flow *flow, FILE *file,
  * @param port_id
  *   Port identifier of Ethernet device.
  * @param[out] error
- *   Perform verbose error reporting if not NULL. PMDs initialize this
- *   structure in case of error only.
+ *   Perform verbose error reporting if not NULL.
  *
  * @return
- *   0 on success, a negative errno value otherwise and rte_errno is set.
+ *   0 on success, a negative errno value otherwise.
  */
 int dao_flow_flush(uint16_t port_id, struct rte_flow_error *error);
 
@@ -260,11 +255,10 @@ int dao_flow_flush(uint16_t port_id, struct rte_flow_error *error);
  * @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.
+ *   Perform verbose error reporting if not NULL.
  *
  * @return
- *   0 on success, a negative errno value otherwise and rte_errno is set.
+ *   0 on success, a negative errno value otherwise.
  */
 int dao_flow_info(uint16_t port_id, FILE *file, struct rte_flow_error *error);
 
@@ -277,11 +271,10 @@ int dao_flow_info(uint16_t port_id, FILE *file, struct rte_flow_error *error);
  * @param[out] count
  *   A pointer to a flow count structure.
  * @param[out] error
- *   Perform verbose error reporting if not NULL. PMDs initialize this
- *   structure in case of error only.
+ *   Perform verbose error reporting if not NULL.
  *
  * @return
- *   0 on success, a negative errno value otherwise and rte_errno is set.
+ *   0 on success, a negative errno value otherwise.
  */
 
 int dao_flow_count(uint16_t port_id, struct dao_flow_count *count, struct rte_flow_error *error);