[PATCH v2] eal: deprecate old coremask-based EAL parameters

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

As the number of cores/cpus on platforms has increased over the years,
the use of coremasks rather than core-lists for identifying DPDK cores
has become more and more unwieldy. At this point, let's deprecate the
coremask-based EAL parameters for future removal, and point users to the
core-list based versions instead.

Depends-on: series-35540 ("use core lists not masks in documentation")

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Acked-by: Vipin Varghese <vipin.varghese@amd.com>
Acked-By: Anatoly Burakov <anatoly.burakov@intel.com>
Acked-by: Konstantin Ananyev <konstantin.ananyev@huawei.com>
---
V2:
* updated freebsd GSG doc
* additional changes to linux GSG sample apps section
* removed a couple of outdated references to coremask/list being mandatory
* made EAL prefix lower-case in deprecation doc
---
 doc/guides/freebsd_gsg/build_sample_apps.rst |  8 +++-----
 doc/guides/linux_gsg/build_sample_apps.rst   | 18 +++++++-----------
 doc/guides/linux_gsg/eal_args.include.rst    |  4 ----
 doc/guides/rel_notes/deprecation.rst         | 10 ++++++++++
 lib/eal/common/eal_common_options.c          |  6 ++++++
 lib/eal/include/rte_lcore.h                  |  1 -
 6 files changed, 26 insertions(+), 21 deletions(-)

diff --git a/doc/guides/freebsd_gsg/build_sample_apps.rst b/doc/guides/freebsd_gsg/build_sample_apps.rst
index 7bdd88e56d..a9124624f7 100644
--- a/doc/guides/freebsd_gsg/build_sample_apps.rst
+++ b/doc/guides/freebsd_gsg/build_sample_apps.rst
@@ -61,10 +61,9 @@ A large number of options can be given to the EAL when running an
 application. A full list of options can be got by passing `--help` to a
 DPDK application. Some of the EAL options for FreeBSD are as follows:
 
-*   ``-c COREMASK`` or ``-l CORELIST``:
-    A hexadecimal bit mask of the cores to run on.  Note that core numbering
-    can change between platforms and should be determined beforehand. The corelist
-    is a list of cores to use instead of a core mask.
+*   ``-l CORELIST``:
+    A list of the cores to run on, for example: ``-l 1-3``, or ``-l 1,3,5-10``.
+    Note that core numbering can change between platforms and should be determined beforehand.
 
 *   ``-b <domain:bus:devid.func>``:
     Blocklisting of ports; prevent EAL from using specified PCI device
@@ -94,7 +93,6 @@ Other options, specific to Linux and are not supported under FreeBSD are as foll
 *   ``--file-prefix``:
     The prefix text used for hugepage filenames.
 
-The ``-c`` or ``-l`` option is mandatory; the others are optional.
 
 .. _running_non_root:
 
diff --git a/doc/guides/linux_gsg/build_sample_apps.rst b/doc/guides/linux_gsg/build_sample_apps.rst
index 5746a623f8..668705177e 100644
--- a/doc/guides/linux_gsg/build_sample_apps.rst
+++ b/doc/guides/linux_gsg/build_sample_apps.rst
@@ -33,16 +33,15 @@ The following is the list of options that can be given to the EAL:
 
 .. code-block:: console
 
-    ./rte-app [-c COREMASK | -l CORELIST] [-n NUM] [-b <domain:bus:devid.func>] \
+    ./rte-app [-l CORELIST] [-n NUM] [-b <domain:bus:devid.func>] \
               [--numa-mem=MB,...] [-d LIB.so|DIR] [-m MB] [-r NUM] [-v] [--file-prefix] \
 	      [--proc-type <primary|secondary|auto>]
 
 The EAL options are as follows:
 
-* ``-c COREMASK`` or ``-l CORELIST``:
-  An hexadecimal bit mask of the cores to run on. Note that core numbering can
-  change between platforms and should be determined beforehand. The corelist is
-  a set of core numbers instead of a bitmap core mask.
+* ``-l CORELIST``:
+  An list of the cores to run on, for example: ``-l 1-3`` or ``-l 1,3,5-10``.
+  Note that core numbering can change between platforms and should be determined beforehand.
 
 * ``-n NUM``:
   Number of memory channels per processor socket.
@@ -108,8 +107,6 @@ The EAL options are as follows:
   Store memory segments in fewer files (dynamic memory mode only - does not
   affect legacy memory mode).
 
-The ``-c`` or ``-l`` and option is mandatory; the others are optional.
-
 Copy the DPDK application binary to your target, then run the application as follows
 (assuming the platform has four memory channels per processor socket,
 and that cores 0-3 are present and are to be used for running the application)::
@@ -126,10 +123,9 @@ and that cores 0-3 are present and are to be used for running the application)::
 Logical Core Use by Applications
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The coremask (-c 0x0f) or corelist (-l 0-3) parameter is always mandatory for DPDK applications.
-Each bit of the mask corresponds to the equivalent logical core number as reported by Linux. The preferred corelist option is a cleaner method to define cores to be used.
+The corelist (``-l``/``--lcores``) parameter is generally used for DPDK applications to specify the cores on which the application should run.
 Since these logical core numbers, and their mapping to specific cores on specific NUMA sockets, can vary from platform to platform,
-it is recommended that the core layout for each platform be considered when choosing the coremask/corelist to use in each case.
+it is recommended that the core layout for each platform be considered when choosing the corelist to use in each case.
 
 On initialization of the EAL layer by a DPDK application, the logical cores to be used and their socket location are displayed.
 This information can also be determined for all cores on the system by examining the ``/proc/cpuinfo`` file, for example, by running cat ``/proc/cpuinfo``.
@@ -151,7 +147,7 @@ This can be useful when using other processors to understand the mapping of the
 
 .. warning::
 
-    The logical core layout can change between different board layouts and should be checked before selecting an application coremask/corelist.
+    The logical core layout can change between different board layouts and should be checked before selecting an application corelist.
 
 Hugepage Memory Use by Applications
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/guides/linux_gsg/eal_args.include.rst b/doc/guides/linux_gsg/eal_args.include.rst
index 359721eb6a..9c90ee5110 100644
--- a/doc/guides/linux_gsg/eal_args.include.rst
+++ b/doc/guides/linux_gsg/eal_args.include.rst
@@ -4,10 +4,6 @@
 Lcore-related options
 ~~~~~~~~~~~~~~~~~~~~~
 
-*   ``-c <core mask>``
-
-    Set the hexadecimal bitmask of the cores to run on.
-
 *   ``-l/--lcores <core list>``
 
     List of cores to run on
diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst
index 36489f6e68..2d95540562 100644
--- a/doc/guides/rel_notes/deprecation.rst
+++ b/doc/guides/rel_notes/deprecation.rst
@@ -17,6 +17,16 @@ Other API and ABI deprecation notices are to be posted below.
 Deprecation Notices
 -------------------
 
+* eal: The ``-c <coremask>`` commandline parameter is deprecated
+  and will be removed in a future release.
+  Use the ``-l <corelist>`` or ``--lcores=<corelist>`` parameters instead
+  to specify the cores to be used when running a DPDK application.
+
+* eal: The ``-s <service-coremask>`` commandline parameter is deprecated
+  and will be removed in a future release.
+  Use the ``-S <service-corelist>`` parameter instead
+  to specify the cores to be used for background services in DPDK.
+
 * build: The ``enable_kmods`` option is deprecated and will be removed in a future release.
   Setting/clearing the option has no impact on the build.
   Instead, kernel modules will be always built for OS's where out-of-tree kernel modules
diff --git a/lib/eal/common/eal_common_options.c b/lib/eal/common/eal_common_options.c
index 83b6fc7e89..f0a9ddeeb7 100644
--- a/lib/eal/common/eal_common_options.c
+++ b/lib/eal/common/eal_common_options.c
@@ -616,6 +616,9 @@ eal_parse_service_coremask(const char *coremask)
 	int val;
 	uint32_t taken_lcore_count = 0;
 
+	EAL_LOG(WARNING, "'-s <service-coremask>' is deprecated, and will be removed in a future release.");
+	EAL_LOG(WARNING, "\tUse '-S <service-corelist>' option instead.");
+
 	if (coremask == NULL)
 		return -1;
 	/* Remove all blank characters ahead and after .
@@ -779,6 +782,9 @@ rte_eal_parse_coremask(const char *coremask, int *cores)
 		cores[idx] = -1;
 	idx = 0;
 
+	EAL_LOG(WARNING, "'-c <coremask>' option is deprecated, and will be removed in a future release");
+	EAL_LOG(WARNING, "\tUse '-l <corelist>' or '--lcores=<corelist>' option instead");
+
 	/* Remove all blank characters ahead and after .
 	 * Remove 0x/0X if exists.
 	 */
diff --git a/lib/eal/include/rte_lcore.h b/lib/eal/include/rte_lcore.h
index 44959779a1..10f965b4f0 100644
--- a/lib/eal/include/rte_lcore.h
+++ b/lib/eal/include/rte_lcore.h
@@ -102,7 +102,6 @@ unsigned int rte_lcore_count(void);
  * When option -c or -l is given, the index corresponds
  * to the order in the list.
  * For example:
- * -c 0x30, lcore 4 has index 0, and 5 has index 1.
  * -l 22,18 lcore 22 has index 0, and 18 has index 1.
  *
  * @param lcore_id
-- 
2.48.1