app/testpmd: add flow template management

[dpdk.git] / doc / guides / testpmd_app_ug / testpmd_funcs.rst

diff --git a/doc/guides/testpmd_app_ug/testpmd_funcs.rst b/doc/guides/testpmd_app_ug/testpmd_funcs.rst
index 9cc2480..2e6a23b 100644 (file)
--- a/doc/guides/testpmd_app_ug/testpmd_funcs.rst
+++ b/doc/guides/testpmd_app_ug/testpmd_funcs.rst
@@ -3308,8 +3308,8 @@ Flow rules management
 ---------------------
 
 Control of the generic flow API (*rte_flow*) is fully exposed through the
 ---------------------
 
 Control of the generic flow API (*rte_flow*) is fully exposed through the

-``flow`` command (validation, creation, destruction, queries and operation
-modes).
+``flow`` command (configuration, validation, creation, destruction, queries
+and operation modes).

 
 Considering *rte_flow* overlaps with all `Filter Functions`_, using both
 features simultaneously may cause undefined side-effects and is therefore
 
 Considering *rte_flow* overlaps with all `Filter Functions`_, using both
 features simultaneously may cause undefined side-effects and is therefore


@@ -3332,6 +3332,38 @@ The first parameter stands for the operation mode. Possible operations and
 their general syntax are described below. They are covered in detail in the
 following sections.
 
 their general syntax are described below. They are covered in detail in the
 following sections.
 

+- Get info about flow engine::
+
+   flow info {port_id}
+
+- Configure flow engine::
+
+   flow configure {port_id}
+       [queues_number {number}] [queues_size {size}]
+       [counters_number {number}]
+       [aging_counters_number {number}]
+       [meters_number {number}]
+
+- Create a pattern template::
+   flow pattern_template {port_id} create [pattern_template_id {id}]
+       [relaxed {boolean}] [ingress] [egress] [transfer]
+          template {item} [/ {item} [...]] / end
+
+- Destroy a pattern template::
+
+   flow pattern_template {port_id} destroy pattern_template {id} [...]
+
+- Create an actions template::
+
+   flow actions_template {port_id} create [actions_template_id {id}]
+       [ingress] [egress] [transfer]
+       template {action} [/ {action} [...]] / end
+       mask {action} [/ {action} [...]] / end
+
+- Destroy an actions template::
+
+   flow actions_template {port_id} destroy actions_template {id} [...]
+

 - Check whether a flow rule can be created::
 
    flow validate {port_id}
 - Check whether a flow rule can be created::
 
    flow validate {port_id}


@@ -3391,6 +3423,132 @@ following sections.
 
    flow tunnel list {port_id}
 
 
    flow tunnel list {port_id}
 

+Retrieving info about flow management engine
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``flow info`` retrieves info on pre-configurable resources in the underlying
+device to give a hint of possible values for flow engine configuration.
+
+``rte_flow_info_get()``::
+
+   flow info {port_id}
+
+If successful, it will show::
+
+   Flow engine resources on port #[...]:
+   Number of queues: #[...]
+   Size of queues: #[...]
+   Number of counters: #[...]
+   Number of aging objects: #[...]
+   Number of meters: #[...]
+
+Otherwise it will show an error message of the form::
+
+   Caught error type [...] ([...]): [...]
+
+Configuring flow management engine
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``flow configure`` pre-allocates all the needed resources in the underlying
+device to be used later at the flow creation. Flow queues are allocated as well
+for asynchronous flow creation/destruction operations. It is bound to
+``rte_flow_configure()``::
+
+   flow configure {port_id}
+       [queues_number {number}] [queues_size {size}]
+       [counters_number {number}]
+       [aging_counters_number {number}]
+       [meters_number {number}]
+
+If successful, it will show::
+
+   Configure flows on port #[...]: number of queues #[...] with #[...] elements
+
+Otherwise it will show an error message of the form::
+
+   Caught error type [...] ([...]): [...]
+
+Creating pattern templates
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``flow pattern_template create`` creates the specified pattern template.
+It is bound to ``rte_flow_pattern_template_create()``::
+
+   flow pattern_template {port_id} create [pattern_template_id {id}]
+       [relaxed {boolean}] [ingress] [egress] [transfer]
+          template {item} [/ {item} [...]] / end
+
+If successful, it will show::
+
+   Pattern template #[...] created
+
+Otherwise it will show an error message of the form::
+
+   Caught error type [...] ([...]): [...]
+
+This command uses the same pattern items as ``flow create``,
+their format is described in `Creating flow rules`_.
+
+Destroying pattern templates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``flow pattern_template destroy`` destroys one or more pattern templates
+from their template ID (as returned by ``flow pattern_template create``),
+this command calls ``rte_flow_pattern_template_destroy()`` as many
+times as necessary::
+
+   flow pattern_template {port_id} destroy pattern_template {id} [...]
+
+If successful, it will show::
+
+   Pattern template #[...] destroyed
+
+It does not report anything for pattern template IDs that do not exist.
+The usual error message is shown when a pattern template cannot be destroyed::
+
+   Caught error type [...] ([...]): [...]
+
+Creating actions templates
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``flow actions_template create`` creates the specified actions template.
+It is bound to ``rte_flow_actions_template_create()``::
+
+   flow actions_template {port_id} create [actions_template_id {id}]
+       [ingress] [egress] [transfer]
+          template {action} [/ {action} [...]] / end
+       mask {action} [/ {action} [...]] / end
+
+If successful, it will show::
+
+   Actions template #[...] created
+
+Otherwise it will show an error message of the form::
+
+   Caught error type [...] ([...]): [...]
+
+This command uses the same actions as ``flow create``,
+their format is described in `Creating flow rules`_.
+
+Destroying actions templates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``flow actions_template destroy`` destroys one or more actions templates
+from their template ID (as returned by ``flow actions_template create``),
+this command calls ``rte_flow_actions_template_destroy()`` as many
+times as necessary::
+
+   flow actions_template {port_id} destroy actions_template {id} [...]
+
+If successful, it will show::
+
+   Actions template #[...] destroyed
+
+It does not report anything for actions template IDs that do not exist.
+The usual error message is shown when an actions template cannot be destroyed::
+
+   Caught error type [...] ([...]): [...]
+

 Creating a tunnel stub for offload
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Creating a tunnel stub for offload
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~