diff mbox series

[v9,17/17] doc: update multicore dispatch model in graph guides

Message ID 20230607035144.1214492-18-zhirun.yan@intel.com (mailing list archive)
State Changes Requested, archived
Delegated to: Thomas Monjalon
Headers
Series graph enhancement for multi-core dispatch |

Checks

Context Check Description
ci/checkpatch success coding style OK
ci/loongarch-compilation success Compilation OK
ci/loongarch-unit-testing success Unit Testing PASS
ci/github-robot: build success github build: passed
ci/Intel-compilation success Compilation OK
ci/intel-Testing success Testing PASS
ci/intel-Functional success Functional PASS
ci/iol-aarch64-compile-testing success Testing PASS
ci/iol-x86_64-compile-testing success Testing PASS
ci/iol-unit-testing success Testing PASS
ci/iol-x86_64-unit-testing success Testing PASS
ci/iol-testing success Testing PASS
ci/iol-aarch-unit-testing success Testing PASS
ci/iol-abi-testing success Testing PASS
ci/iol-broadcom-Performance success Performance Testing PASS
ci/iol-mellanox-Performance success Performance Testing PASS
ci/iol-broadcom-Functional success Functional Testing PASS
ci/iol-intel-Performance success Performance Testing PASS
ci/iol-intel-Functional success Functional Testing PASS

Commit Message

Yan, Zhirun June 7, 2023, 3:51 a.m. UTC 
  Update graph documentation to introduce new multicore dispatch model.

Signed-off-by: Haiyue Wang <haiyue.wang@intel.com>
Signed-off-by: Cunming Liang <cunming.liang@intel.com>
Signed-off-by: Zhirun Yan <zhirun.yan@intel.com>
---
 doc/guides/prog_guide/graph_lib.rst | 68 +++++++++++++++++++++++++++--
 1 file changed, 64 insertions(+), 4 deletions(-)

Comments

Jerin Jacob June 7, 2023, 12:45 p.m. UTC | #1 
On Wed, Jun 7, 2023 at 9:30 AM Zhirun Yan <zhirun.yan@intel.com> wrote:
>
> Update graph documentation to introduce new multicore dispatch model.

Please squash this to relevant implementation patches, No need for
separate patch. This is the contribution guideline followed.

>
> Signed-off-by: Haiyue Wang <haiyue.wang@intel.com>
> Signed-off-by: Cunming Liang <cunming.liang@intel.com>
> Signed-off-by: Zhirun Yan <zhirun.yan@intel.com>
> ---
>  doc/guides/prog_guide/graph_lib.rst | 68 +++++++++++++++++++++++++++--
>  1 file changed, 64 insertions(+), 4 deletions(-)
>
> diff --git a/doc/guides/prog_guide/graph_lib.rst b/doc/guides/prog_guide/graph_lib.rst
> index 1cfdc86433..8c2c2816ed 100644
> --- a/doc/guides/prog_guide/graph_lib.rst
> +++ b/doc/guides/prog_guide/graph_lib.rst
> @@ -189,14 +189,74 @@ In the above example, A graph object will be created with ethdev Rx
>  node of port 0 and queue 0, all ipv4* nodes in the system,
>  and ethdev tx node of all ports.
>
> -Multicore graph processing
> -~~~~~~~~~~~~~~~~~~~~~~~~~~
> -In the current graph library implementation, specifically,
> -``rte_graph_walk()`` and ``rte_node_enqueue*`` fast path API functions
> +Graph models chossing

Graph models

> +~~~~~~~~~~~~~~~~~~~~~
> +Currently, there are 2 different walking models. Use macro
> +RTE_GRAPH_MODEL_SELECT to set the model in compile time. Also offers the
> +ability to choose models in runtime

by not defining RTE_GRAPH_MODEL_SELECT.

> +For application, must #define RTE_GRAPH_MODEL_SELECT before including
> +rte_graph_worker.h

Some rewording as suggestion.

Graph models
~~~~~~~~~~~~
There are two different kinds of graph walking models. User can select
the model using
``rte_graph_worker_model_set()`` API. If the application decides to
use only one model,
 the fast path check can be avoided by defining the model with
RTE_GRAPH_MODEL_SELECT. For example:

.. code-block:: console

#define RTE_GRAPH_MODEL_SELECT RTE_GRAPH_MODEL_RTC
#include "rte_graph_worker.h"



> +
> +In l3fwd-graph, set RTE_GRAPH_MODEL_SELECT as the model explicitly for
> +performance-sensitive use case.
> +Or set the macro as GRAPH_MODEL_MCORE_RUNTIME_SELECT. And parse
> +``"--model=NAME"`` in cmdline and use ``rte_graph_worker_model_set()``
> +to set the walking model in runtime.

Please move to doc/guides/sample_app_ug/l3_forward_graph.rst

> +
> +RTC (Run-To-Completion)
> +^^^^^^^^^^^^^^^^^^^^^^^
> +This is the default graph walking model. Specifically,
> +``rte_graph_walk_rtc()`` and ``rte_node_enqueue*`` fast path API functions
>  are designed to work on single-core to have better performance.
>  The fast path API works on graph object, So the multi-core graph
>  processing strategy would be to create graph object PER WORKER.
>
> +Example:
> +
> +Graph: node-0 -> node-1 -> node-2 @Core0.
> +
> +.. code-block:: diff
> +
> +    + - - - - - - - - - - - - - - - - - - - - - +
> +    '                  Core #0                  '
> +    '                                           '
> +    ' +--------+     +---------+     +--------+ '
> +    ' | Node-0 | --> | Node-1  | --> | Node-2 | '
> +    ' +--------+     +---------+     +--------+ '
> +    '                                           '
> +    + - - - - - - - - - - - - - - - - - - - - - +
> +
> +Dispatch model
> +^^^^^^^^^^^^^^
> +The dispatch model enables a cross-core dispatching mechanism which employs
> +a scheduling work-queue to dispatch streams to other worker cores which
> +being associated with the destination node.
> +
> +Use ``rte_graph_model_mcore_dispatch_lcore_affinity_set()`` to set lcore affinity
> +with the node.
> +Each worker core will have a graph repetition. Use ``rte_graph_clone()`` to clone
> +graph for each worker and use``rte_graph_model_mcore_dispatch_core_bind()`` to
> +bind graph with the worker core.
> +
> +Example:
> +
> +Graph topo: node-0 -> Core1; node-1 -> node-2; node-2 -> node-3.
> +Config graph: node-0 @Core0; node-1/3 @Core1; node-2 @Core2.
> +
> +.. code-block:: diff
> +
> +    + - - - - - -+     +- - - - - - - - - - - - - +     + - - - - - -+
> +    '  Core #0   '     '          Core #1         '     '  Core #2   '
> +    '            '     '                          '     '            '
> +    ' +--------+ '     ' +--------+    +--------+ '     ' +--------+ '
> +    ' | Node-0 | - - - ->| Node-1 |    | Node-3 |<- - - - | Node-2 | '
> +    ' +--------+ '     ' +--------+    +--------+ '     ' +--------+ '
> +    '            '     '     |                    '     '      ^     '
> +    + - - - - - -+     +- - -|- - - - - - - - - - +     + - - -|- - -+
> +                             |                                 |
> +                             + - - - - - - - - - - - - - - - - +
> +
> +
>  In fast path
>  ~~~~~~~~~~~~
>  Typical fast-path code looks like below, where the application
> --
> 2.37.2
>
Yan, Zhirun June 8, 2023, 3:21 a.m. UTC | #2 
> -----Original Message-----
> From: Jerin Jacob <jerinjacobk@gmail.com>
> Sent: Wednesday, June 7, 2023 8:46 PM
> To: Yan, Zhirun <zhirun.yan@intel.com>
> Cc: dev@dpdk.org; jerinj@marvell.com; kirankumark@marvell.com;
> ndabilpuram@marvell.com; stephen@networkplumber.org;
> pbhagavatula@marvell.com; Liang, Cunming <cunming.liang@intel.com>; Wang,
> Haiyue <haiyue.wang@intel.com>; mattias.ronnblom
> <mattias.ronnblom@ericsson.com>
> Subject: Re: [PATCH v9 17/17] doc: update multicore dispatch model in graph
> guides
> 
> On Wed, Jun 7, 2023 at 9:30 AM Zhirun Yan <zhirun.yan@intel.com> wrote:
> >
> > Update graph documentation to introduce new multicore dispatch model.
> 
> Please squash this to relevant implementation patches, No need for separate
> patch. This is the contribution guideline followed.
> 
Got it. I will squash this to the patch of walk model choosing in patch 13.
> >
> > Signed-off-by: Haiyue Wang <haiyue.wang@intel.com>
> > Signed-off-by: Cunming Liang <cunming.liang@intel.com>
> > Signed-off-by: Zhirun Yan <zhirun.yan@intel.com>
> > ---
> >  doc/guides/prog_guide/graph_lib.rst | 68
> > +++++++++++++++++++++++++++--
> >  1 file changed, 64 insertions(+), 4 deletions(-)
> >
> > diff --git a/doc/guides/prog_guide/graph_lib.rst
> > b/doc/guides/prog_guide/graph_lib.rst
> > index 1cfdc86433..8c2c2816ed 100644
> > --- a/doc/guides/prog_guide/graph_lib.rst
> > +++ b/doc/guides/prog_guide/graph_lib.rst
> > @@ -189,14 +189,74 @@ In the above example, A graph object will be
> > created with ethdev Rx  node of port 0 and queue 0, all ipv4* nodes in
> > the system,  and ethdev tx node of all ports.
> >
> > -Multicore graph processing
> > -~~~~~~~~~~~~~~~~~~~~~~~~~~
> > -In the current graph library implementation, specifically,
> > -``rte_graph_walk()`` and ``rte_node_enqueue*`` fast path API
> > functions
> > +Graph models chossing
> 
> Graph models
> 
> > +~~~~~~~~~~~~~~~~~~~~~
> > +Currently, there are 2 different walking models. Use macro
> > +RTE_GRAPH_MODEL_SELECT to set the model in compile time. Also offers
> > +the ability to choose models in runtime
> 
> by not defining RTE_GRAPH_MODEL_SELECT.
> 
> > +For application, must #define RTE_GRAPH_MODEL_SELECT before including
> > +rte_graph_worker.h
> 
> Some rewording as suggestion.
> 
> Graph models
> ~~~~~~~~~~~~
> There are two different kinds of graph walking models. User can select the
> model using ``rte_graph_worker_model_set()`` API. If the application decides to
> use only one model,  the fast path check can be avoided by defining the model
> with RTE_GRAPH_MODEL_SELECT. For example:
> 
> .. code-block:: console
> 
> #define RTE_GRAPH_MODEL_SELECT RTE_GRAPH_MODEL_RTC #include
> "rte_graph_worker.h"
> 
> 

Thanks for your refine. I will update in next version.

> 
> > +
> > +In l3fwd-graph, set RTE_GRAPH_MODEL_SELECT as the model explicitly
> > +for performance-sensitive use case.
> > +Or set the macro as GRAPH_MODEL_MCORE_RUNTIME_SELECT. And parse
> > +``"--model=NAME"`` in cmdline and use
> > +``rte_graph_worker_model_set()`` to set the walking model in runtime.
> 
> Please move to doc/guides/sample_app_ug/l3_forward_graph.rst
> 
Yes, will move it  and squash this part into example patch.

> > +
> > +RTC (Run-To-Completion)
> > +^^^^^^^^^^^^^^^^^^^^^^^
> > +This is the default graph walking model. Specifically,
> > +``rte_graph_walk_rtc()`` and ``rte_node_enqueue*`` fast path API
> > +functions
> >  are designed to work on single-core to have better performance.
> >  The fast path API works on graph object, So the multi-core graph
> > processing strategy would be to create graph object PER WORKER.
> >
> > +Example:
> > +
> > +Graph: node-0 -> node-1 -> node-2 @Core0.
> > +
> > +.. code-block:: diff
> > +
> > +    + - - - - - - - - - - - - - - - - - - - - - +
> > +    '                  Core #0                  '
> > +    '                                           '
> > +    ' +--------+     +---------+     +--------+ '
> > +    ' | Node-0 | --> | Node-1  | --> | Node-2 | '
> > +    ' +--------+     +---------+     +--------+ '
> > +    '                                           '
> > +    + - - - - - - - - - - - - - - - - - - - - - +
> > +
> > +Dispatch model
> > +^^^^^^^^^^^^^^
> > +The dispatch model enables a cross-core dispatching mechanism which
> > +employs a scheduling work-queue to dispatch streams to other worker
> > +cores which being associated with the destination node.
> > +
> > +Use ``rte_graph_model_mcore_dispatch_lcore_affinity_set()`` to set
> > +lcore affinity with the node.
> > +Each worker core will have a graph repetition. Use
> > +``rte_graph_clone()`` to clone graph for each worker and
> > +use``rte_graph_model_mcore_dispatch_core_bind()`` to bind graph with the
> worker core.
> > +
> > +Example:
> > +
> > +Graph topo: node-0 -> Core1; node-1 -> node-2; node-2 -> node-3.
> > +Config graph: node-0 @Core0; node-1/3 @Core1; node-2 @Core2.
> > +
> > +.. code-block:: diff
> > +
> > +    + - - - - - -+     +- - - - - - - - - - - - - +     + - - - - - -+
> > +    '  Core #0   '     '          Core #1         '     '  Core #2   '
> > +    '            '     '                          '     '            '
> > +    ' +--------+ '     ' +--------+    +--------+ '     ' +--------+ '
> > +    ' | Node-0 | - - - ->| Node-1 |    | Node-3 |<- - - - | Node-2 | '
> > +    ' +--------+ '     ' +--------+    +--------+ '     ' +--------+ '
> > +    '            '     '     |                    '     '      ^     '
> > +    + - - - - - -+     +- - -|- - - - - - - - - - +     + - - -|- - -+
> > +                             |                                 |
> > +                             + - - - - - - - - - - - - - - - - +
> > +
> > +
> >  In fast path
> >  ~~~~~~~~~~~~
> >  Typical fast-path code looks like below, where the application
> > --
> > 2.37.2
> >
diff mbox series

Patch

diff --git a/doc/guides/prog_guide/graph_lib.rst b/doc/guides/prog_guide/graph_lib.rst
index 1cfdc86433..8c2c2816ed 100644
--- a/doc/guides/prog_guide/graph_lib.rst
+++ b/doc/guides/prog_guide/graph_lib.rst
@@ -189,14 +189,74 @@  In the above example, A graph object will be created with ethdev Rx
 node of port 0 and queue 0, all ipv4* nodes in the system,
 and ethdev tx node of all ports.
 
-Multicore graph processing
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-In the current graph library implementation, specifically,
-``rte_graph_walk()`` and ``rte_node_enqueue*`` fast path API functions
+Graph models chossing
+~~~~~~~~~~~~~~~~~~~~~
+Currently, there are 2 different walking models. Use macro
+RTE_GRAPH_MODEL_SELECT to set the model in compile time. Also offers the
+ability to choose models in runtime.
+For application, must #define RTE_GRAPH_MODEL_SELECT before including
+rte_graph_worker.h.
+
+In l3fwd-graph, set RTE_GRAPH_MODEL_SELECT as the model explicitly for
+performance-sensitive use case.
+Or set the macro as GRAPH_MODEL_MCORE_RUNTIME_SELECT. And parse
+``"--model=NAME"`` in cmdline and use ``rte_graph_worker_model_set()``
+to set the walking model in runtime.
+
+RTC (Run-To-Completion)
+^^^^^^^^^^^^^^^^^^^^^^^
+This is the default graph walking model. Specifically,
+``rte_graph_walk_rtc()`` and ``rte_node_enqueue*`` fast path API functions
 are designed to work on single-core to have better performance.
 The fast path API works on graph object, So the multi-core graph
 processing strategy would be to create graph object PER WORKER.
 
+Example:
+
+Graph: node-0 -> node-1 -> node-2 @Core0.
+
+.. code-block:: diff
+
+    + - - - - - - - - - - - - - - - - - - - - - +
+    '                  Core #0                  '
+    '                                           '
+    ' +--------+     +---------+     +--------+ '
+    ' | Node-0 | --> | Node-1  | --> | Node-2 | '
+    ' +--------+     +---------+     +--------+ '
+    '                                           '
+    + - - - - - - - - - - - - - - - - - - - - - +
+
+Dispatch model
+^^^^^^^^^^^^^^
+The dispatch model enables a cross-core dispatching mechanism which employs
+a scheduling work-queue to dispatch streams to other worker cores which
+being associated with the destination node.
+
+Use ``rte_graph_model_mcore_dispatch_lcore_affinity_set()`` to set lcore affinity
+with the node.
+Each worker core will have a graph repetition. Use ``rte_graph_clone()`` to clone
+graph for each worker and use``rte_graph_model_mcore_dispatch_core_bind()`` to
+bind graph with the worker core.
+
+Example:
+
+Graph topo: node-0 -> Core1; node-1 -> node-2; node-2 -> node-3.
+Config graph: node-0 @Core0; node-1/3 @Core1; node-2 @Core2.
+
+.. code-block:: diff
+
+    + - - - - - -+     +- - - - - - - - - - - - - +     + - - - - - -+
+    '  Core #0   '     '          Core #1         '     '  Core #2   '
+    '            '     '                          '     '            '
+    ' +--------+ '     ' +--------+    +--------+ '     ' +--------+ '
+    ' | Node-0 | - - - ->| Node-1 |    | Node-3 |<- - - - | Node-2 | '
+    ' +--------+ '     ' +--------+    +--------+ '     ' +--------+ '
+    '            '     '     |                    '     '      ^     '
+    + - - - - - -+     +- - -|- - - - - - - - - - +     + - - -|- - -+
+                             |                                 |
+                             + - - - - - - - - - - - - - - - - +
+
+
 In fast path
 ~~~~~~~~~~~~
 Typical fast-path code looks like below, where the application