[PATCH] doc: provide examples of using lcores EAL parameter

[PATCH] doc: provide examples of using lcores EAL parameter

[Bruce Richardson]

The "--lcores" EAL parameter has a very powerful syntax that can be used
to provide precise control over lcore mappings. The docs however, only
provided a minimal description of what it can do. Augment the docs by
providing some examples of use of the option, and what the resulting
core mappings would be.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/guides/linux_gsg/eal_args.include.rst | 25 +++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/doc/guides/linux_gsg/eal_args.include.rst b/doc/guides/linux_gsg/eal_args.include.rst
index 9cfbf7de84..081f09d353 100644
--- a/doc/guides/linux_gsg/eal_args.include.rst
+++ b/doc/guides/linux_gsg/eal_args.include.rst
@@ -29,6 +29,31 @@ Lcore-related options
     The grouping ``()`` can be omitted for single element group.
     The ``@`` can be omitted if cpus and lcores have the same value.
 
+    Examples:
+
+    ``--lcores=1-3``: Run threads on physical CPUs 1, 2 and 3,
+    with each thread having the same lcore id as the physical CPU id.
+
+    ``--lcores=1@(1,2)``: Run a single thread with lcore id 1,
+    but with that thread bound to both physical CPUs 1 and 2,
+    so it can run on either, as determined by the operating system.
+
+    ``--lcores='1@31,2@32,3@33'``: Run threads having internal lcore ids of 1, 2 and 3,
+    but with the threads being bound to physical CPUs 31, 32 and 33.
+
+    ``--lcores='(1-3)@(31-33)'``: Run three threads with lcore ids 1, 2 and 3.
+    Unlike the previous example above,
+    each of these threads is not bound to one specific lcore,
+    but rather, all three threads are instead bound to the three physical cores 31, 32 and 33.
+
+    ``--lcores=(1-3)@20``: Run three threads, with lcore ids 1, 2 and 3,
+    where all three threads are bound to (can only run on) physical CPU 20.
+
+.. Note::
+    Binding multiple DPDK lcores can cause problems with poor performance or deadlock when using
+    DPDK rings or memory pools or spinlocks.
+    Such a configuration should only be used with care.
+
 .. Note::
     At a given instance only one core option ``--lcores``, ``-l`` or ``-c`` can
     be used.
-- 
2.45.2

Re: [PATCH] doc: provide examples of using lcores EAL parameter

[Bruce Richardson]

On Mon, Apr 07, 2025 at 02:24:51PM +0100, Bruce Richardson wrote:
> The "--lcores" EAL parameter has a very powerful syntax that can be used
> to provide precise control over lcore mappings. The docs however, only
> provided a minimal description of what it can do. Augment the docs by
> providing some examples of use of the option, and what the resulting
> core mappings would be.
> 
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> ---
>  doc/guides/linux_gsg/eal_args.include.rst | 25 +++++++++++++++++++++++
>  1 file changed, 25 insertions(+)
> 
> diff --git a/doc/guides/linux_gsg/eal_args.include.rst b/doc/guides/linux_gsg/eal_args.include.rst
> index 9cfbf7de84..081f09d353 100644
> --- a/doc/guides/linux_gsg/eal_args.include.rst
> +++ b/doc/guides/linux_gsg/eal_args.include.rst
> @@ -29,6 +29,31 @@ Lcore-related options
>      The grouping ``()`` can be omitted for single element group.
>      The ``@`` can be omitted if cpus and lcores have the same value.
>  
> +    Examples:
> +
> +    ``--lcores=1-3``: Run threads on physical CPUs 1, 2 and 3,
> +    with each thread having the same lcore id as the physical CPU id.
> +
> +    ``--lcores=1@(1,2)``: Run a single thread with lcore id 1,
> +    but with that thread bound to both physical CPUs 1 and 2,
> +    so it can run on either, as determined by the operating system.
> +
> +    ``--lcores='1@31,2@32,3@33'``: Run threads having internal lcore ids of 1, 2 and 3,
> +    but with the threads being bound to physical CPUs 31, 32 and 33.
> +
> +    ``--lcores='(1-3)@(31-33)'``: Run three threads with lcore ids 1, 2 and 3.
> +    Unlike the previous example above,
> +    each of these threads is not bound to one specific lcore,
> +    but rather, all three threads are instead bound to the three physical cores 31, 32 and 33.
> +
> +    ``--lcores=(1-3)@20``: Run three threads, with lcore ids 1, 2 and 3,
> +    where all three threads are bound to (can only run on) physical CPU 20.
> +
> +.. Note::
> +    Binding multiple DPDK lcores can cause problems with poor performance or deadlock when using

I seem to have missed some words here. :-(
V2 will be done soon. However, I will wait before sending it in case there
is other feedback.

/Bruce

> +    DPDK rings or memory pools or spinlocks.
> +    Such a configuration should only be used with care.
> +
>  .. Note::
>      At a given instance only one core option ``--lcores``, ``-l`` or ``-c`` can
>      be used.
> -- 
> 2.45.2
> 

RE: [PATCH] doc: provide examples of using lcores EAL parameter

[Morten Brørup]

> From: Bruce Richardson [mailto:bruce.richardson@intel.com]
> Sent: Monday, 7 April 2025 15.25
> 
> The "--lcores" EAL parameter has a very powerful syntax that can be
> used
> to provide precise control over lcore mappings. The docs however, only
> provided a minimal description of what it can do. Augment the docs by
> providing some examples of use of the option, and what the resulting
> core mappings would be.
> 
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> ---
>  doc/guides/linux_gsg/eal_args.include.rst | 25 +++++++++++++++++++++++
>  1 file changed, 25 insertions(+)
> 
> diff --git a/doc/guides/linux_gsg/eal_args.include.rst
> b/doc/guides/linux_gsg/eal_args.include.rst
> index 9cfbf7de84..081f09d353 100644
> --- a/doc/guides/linux_gsg/eal_args.include.rst
> +++ b/doc/guides/linux_gsg/eal_args.include.rst
> @@ -29,6 +29,31 @@ Lcore-related options
>      The grouping ``()`` can be omitted for single element group.
>      The ``@`` can be omitted if cpus and lcores have the same value.
> 
> +    Examples:
> +
> +    ``--lcores=1-3``: Run threads on physical CPUs 1, 2 and 3,
> +    with each thread having the same lcore id as the physical CPU id.
> +
> +    ``--lcores=1@(1,2)``: Run a single thread with lcore id 1,
> +    but with that thread bound to both physical CPUs 1 and 2,
> +    so it can run on either, as determined by the operating system.
> +
> +    ``--lcores='1@31,2@32,3@33'``: Run threads having internal lcore
> ids of 1, 2 and 3,
> +    but with the threads being bound to physical CPUs 31, 32 and 33.

Maybe add "respectively": "[...] bound to respectively physical CPUs [...]".

> +
> +    ``--lcores='(1-3)@(31-33)'``: Run three threads with lcore ids 1,
> 2 and 3.
> +    Unlike the previous example above,
> +    each of these threads is not bound to one specific lcore,

lcore -> physical CPU

> +    but rather, all three threads are instead bound to the three
> physical cores 31, 32 and 33.

cores -> CPUs

> +
> +    ``--lcores=(1-3)@20``: Run three threads, with lcore ids 1, 2 and
> 3,
> +    where all three threads are bound to (can only run on) physical
> CPU 20.
> +
> +.. Note::
> +    Binding multiple DPDK lcores can cause problems with poor
> performance or deadlock when using

"[...] multiple DPDK lcores can cause problems [...]" ->
"[...] multiple DPDK lcores to the same physical CPU can cause problems [...]"

> +    DPDK rings or memory pools or spinlocks.
> +    Such a configuration should only be used with care.
> +
>  .. Note::
>      At a given instance only one core option ``--lcores``, ``-l`` or
> ``-c`` can
>      be used.
> --
> 2.45.2

With above changes,
Acked-by: Morten Brørup <mb@smartsharesystems.com>

[PATCH v2] doc: provide examples of using lcores EAL parameter

[Bruce Richardson]

The "--lcores" EAL parameter has a very powerful syntax that can be used
to provide precise control over lcore mappings. The docs however, only
provided a minimal description of what it can do. Augment the docs by
providing some examples of use of the option, and what the resulting
core mappings would be.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Acked-by: Morten Brørup <mb@smartsharesystems.com>
---
 doc/guides/linux_gsg/eal_args.include.rst | 27 +++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/doc/guides/linux_gsg/eal_args.include.rst b/doc/guides/linux_gsg/eal_args.include.rst
index 9cfbf7de84..aafe567bfa 100644
--- a/doc/guides/linux_gsg/eal_args.include.rst
+++ b/doc/guides/linux_gsg/eal_args.include.rst
@@ -29,6 +29,33 @@ Lcore-related options
     The grouping ``()`` can be omitted for single element group.
     The ``@`` can be omitted if cpus and lcores have the same value.
 
+    Examples:
+
+    ``--lcores=1-3``: Run threads on physical CPUs 1, 2 and 3,
+    with each thread having the same lcore id as the physical CPU id.
+
+    ``--lcores=1@(1,2)``: Run a single thread with lcore id 1,
+    but with that thread bound to both physical CPUs 1 and 2,
+    so it can run on either, as determined by the operating system.
+
+    ``--lcores='1@31,2@32,3@33'``: Run threads having internal lcore ids of 1, 2 and 3,
+    but with the threads being bound to physical CPUs 31, 32 and 33 respectively.
+
+    ``--lcores='(1-3)@(31-33)'``: Run three threads with lcore ids 1, 2 and 3.
+    Unlike the previous example above,
+    each of these threads is not bound to one specific physical CPU,
+    but rather, all three threads are instead bound to the three physical CPUs 31, 32 and 33.
+    This means that each of the three threads can move between the physical CPUs 31-33,
+    as decided by the OS as the application runs.
+
+    ``--lcores=(1-3)@20``: Run three threads, with lcore ids 1, 2 and 3,
+    where all three threads are bound to (can only run on) physical CPU 20.
+
+.. Note::
+    Binding multiple DPDK lcores to a single physical CPU can cause problems with poor performance
+    or deadlock when using DPDK rings or memory pools or spinlocks.
+    Such a configuration should only be used with care.
+
 .. Note::
     At a given instance only one core option ``--lcores``, ``-l`` or ``-c`` can
     be used.
-- 
2.45.2