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.richard...@intel.com>
Acked-by: Vipin Varghese <vipin.vargh...@amd.com>
Acked-By: Anatoly Burakov <anatoly.bura...@intel.com>
Acked-by: Konstantin Ananyev <konstantin.anan...@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
