[PATCH 32/39] eal: clarify docs on params taking lcore IDs

[Bruce Richardson]

The documentation doesn't make clear how the parameters to service core
and main lcore EAL flags relate to the regular --lcores parameter when
mapping lcores to physical CPU ids.

For example, when looking to add service cores to process run using the
command "/path/to/app -R -l 40-50", it's not clear whether the service
cores list parameter should be "-S 49-50" i.e. physical CPU ids, or "-S
9-10" i.e.  logical lcore IDs. Update the docs to make it clear its the
latter.

Signed-off-by: Bruce Richardson <bruce.richardson at intel.com>
---
 doc/guides/linux_gsg/eal_args.include.rst | 38 +++++++++++++++++++++--
 lib/eal/common/eal_option_list.h          |  6 ++--
 2 files changed, 38 insertions(+), 6 deletions(-)

diff --git a/doc/guides/linux_gsg/eal_args.include.rst b/doc/guides/linux_gsg/eal_args.include.rst
index 32c24c8e41..33281ecec3 100644
--- a/doc/guides/linux_gsg/eal_args.include.rst
+++ b/doc/guides/linux_gsg/eal_args.include.rst
@@ -89,13 +89,45 @@ Lcore-related options
     and the use of ``()`` for core groupings,
     are not allowed when ``-R`` or ``--remap-lcore-ids`` is also used.
 
-*   ``--main-lcore <core ID>``
+*   ``--main-lcore <lcore ID>``
 
-    Core ID that is used as main.
+    Set the lcore ID to use for the main thread.
+    The value is a DPDK lcore ID, not a physical CPU ID,
+    and must be present in the enabled lcore set (as configured by ``-l``/``--lcores``).
+
+    In the simple case, without any explicit lcore-to-CPU mapping,
+    lcore IDs equal physical CPU IDs so the distinction does not matter.
+    The two differ when ``-R``/``--remap-lcore-ids`` assigns sequential lcore IDs to higher-numbered physical CPUs,
+    or when the ``@`` mapping syntax in ``--lcores`` is used.
+    In those cases the lcore ID must be specified here, not the physical CPU ID.
+
+    Example using ``--lcores`` explicit mapping:
+    ``--lcores=1 at 31,2 at 32,3 at 33 --main-lcore 2`` selects the thread with lcore ID 2,
+    running on physical CPU 32, as the main thread.
+
+    Example using ``-R`` remapping:
+    ``-l 31-33 -R --main-lcore 1`` starts three threads on physical CPUs 31, 32 and 33, remapped to lcore IDs 0, 1 and 2.
+    ``--main-lcore 1`` selects the thread remapped to lcore ID 1, which runs on physical CPU 32.
 
 *   ``-S, --service-corelist <service core list>``
 
-    List of cores to be used as service cores.
+    List of lcore IDs to be used as service cores.
+    The list format is the same as for ``-l``/``--lcores``:
+    a comma-separated set of lcore IDs or ranges (e.g. ``2,3`` or ``2-5``).
+    Each specified lcore ID must be present in the enabled lcore set.
+
+    The values are lcore IDs, not physical CPU IDs.
+    In the simple case, without any explicit lcore-to-CPU mapping, the two are equal so the distinction does not matter.
+    When using ``-R``/``--remap-lcore-ids`` or the ``@`` mapping syntax in ``--lcores``, lcore IDs and physical CPU IDs differ,
+    and the lcore IDs must be used here.
+
+    Example using ``--lcores`` explicit mapping:
+    ``--lcores=1 at 31,2 at 32,3 at 33 -S 2,3`` assigns the threads with
+    lcore IDs 2 and 3 (running on physical CPUs 32 and 33) as service cores.
+
+    Example using ``-R`` remapping:
+    ``-l 31-33 -R -S 1,2`` starts three threads on physical CPUs 31, 32 and 33, remapped to lcore IDs 0, 1 and 2.
+    ``-S 1,2`` assigns the threads with lcore IDs 1 and 2 (running on physical CPUs 32 and 33) as service cores.
 
 
 Device-related options
diff --git a/lib/eal/common/eal_option_list.h b/lib/eal/common/eal_option_list.h
index b72f243cc6..2b94e4f22f 100644
--- a/lib/eal/common/eal_option_list.h
+++ b/lib/eal/common/eal_option_list.h
@@ -47,7 +47,7 @@ BOOL_ARG("--legacy-mem", NULL, "Enable legacy memory behavior", legacy_mem)
 OPT_STR_ARG("--log-color", NULL, "Enable/disable color in log output", log_color)
 LIST_ARG("--log-level", NULL, "Log level for loggers; use log-level=help for list of log types and levels", log_level)
 OPT_STR_ARG("--log-timestamp", NULL, "Enable/disable timestamp in log output", log_timestamp)
-STR_ARG("--main-lcore", NULL, "Select which core to use for the main thread", main_lcore)
+STR_ARG("--main-lcore", NULL, "Lcore ID to use for the main thread", main_lcore)
 STR_ARG("--mbuf-pool-ops-name", NULL, "User defined mbuf default pool ops name", mbuf_pool_ops_name)
 STR_ARG("--memory-channels", "-n", "Number of memory channels per socket", memory_channels)
 STR_ARG("--memory-ranks", "-r", "Force number of memory ranks (don't detect)", memory_ranks)
@@ -61,8 +61,8 @@ BOOL_ARG("--no-telemetry", NULL, "Disable telemetry", no_telemetry)
 LIST_ARG("--pagesz-mem", NULL, "Memory allocation per hugepage size (format: <pagesz>:<limit>, e.g. 2M:32G). Repeat option for multiple page sizes.", pagesz_mem)
 STR_ARG("--proc-type", NULL, "Type of process (primary|secondary|auto)", proc_type)
 OPT_STR_ARG("--remap-lcore-ids", "-R", "Remap lcore IDs to be contiguous starting from 0, or supplied value", remap_lcore_ids)
-STR_ARG("--service-corelist", "-S", "List of cores to use for service threads", service_corelist)
-STR_ARG("--service-coremask", "-s", "[Deprecated] Bitmask of cores to use for service threads", service_coremask)
+STR_ARG("--service-corelist", "-S", "List of lcore IDs to use for service threads", service_corelist)
+STR_ARG("--service-coremask", "-s", "[Deprecated] Bitmask of lcore IDs to use for service threads", service_coremask)
 BOOL_ARG("--single-file-segments", NULL, "Store all pages within single files (per-page-size, per-node)", single_file_segments)
 BOOL_ARG("--telemetry", NULL, "Enable telemetry", telemetry)
 LIST_ARG("--vdev", NULL, "Add a virtual device to the system; format=<driver><id>[,key=val,...]", vdev)
-- 
2.53.0