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

[Bruce Richardson <bruce.richardson@intel.com>]

On Wed, May 14, 2025 at 01:38:59PM +0200, Morten Brørup wrote:
> > From: Bruce Richardson [mailto:bruce.richardson@intel.com]
> > Sent: Tuesday, 13 May 2025 18.17
> > 
> > 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 01fe6a3006..d530215784 100644
> > --- a/doc/guides/linux_gsg/eal_args.include.rst
> > +++ b/doc/guides/linux_gsg/eal_args.include.rst
> > @@ -23,6 +23,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.
> 
> Just noticed...
> 
> Some examples use: --lcores=XYZ
> And some use: --lcores='XYZ'
> 
> Are the apostrophes required in some cases?
> If not, please remove them.
> 
Yes, they are required in some cases to stop the shell trying to interpret
special characters itself. For simplicity, all of these should be quoted I
think. Perhaps that could be just fixed on apply, otherwise I'm happy to do
a quick respin.

/Bruce