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:14:10PM +0100, Bruce Richardson wrote:
> 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.
> 
Now done a v5. I've tested on my system all the example commands to see
which needed quoting or not. Turns out that - at least on bash on ubuntu -
any of the lcore parameter values starting with "(" need quoting, while the
others do not. I've therefore adjusted the examples to put in quotes where
necessary (and only where necessary), and added just a note at the end of
the examples list, explaining that sometimes quoting is necessary.

/Bruce