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

[David Marchand <david.marchand@redhat.com>]

On Tue, Jun 24, 2025 at 3:41 PM Bruce Richardson
<bruce.richardson@intel.com> wrote:
>
> 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>
> ---
>  doc/guides/linux_gsg/build_sample_apps.rst |  7 +++----
>  doc/guides/linux_gsg/eal_args.include.rst  |  9 ---------

Please update FreeBSD docs too.


>  doc/guides/rel_notes/deprecation.rst       | 10 ++++++++++
>  lib/eal/common/eal_common_options.c        |  6 ++++++
>  lib/eal/include/rte_lcore.h                |  1 -
>  5 files changed, 19 insertions(+), 14 deletions(-)
>
> diff --git a/doc/guides/linux_gsg/build_sample_apps.rst b/doc/guides/linux_gsg/build_sample_apps.rst
> index 8b8026705b..9ce564e881 100644
> --- a/doc/guides/linux_gsg/build_sample_apps.rst
> +++ b/doc/guides/linux_gsg/build_sample_apps.rst
> @@ -126,10 +126,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 0-3) parameter is always mandatory for DPDK applications.

Not directly related to this patch, the -l/-c options are optional
since 2eba8d21f3c9 ("eal: restrict cores auto detection").


>  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 +150,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 6ee79877c1..b0cd757569 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
> @@ -75,15 +71,10 @@ Lcore-related options
>
>      Core ID that is used as main.
>
> -*   ``-s <service core mask>``
> -
> -    Hexadecimal bitmask of cores to be used as service cores.
> -
>  *   ``-S <service core list>``
>
>      List of cores to be used as service cores.
>
> -
>  Device-related options
>  ~~~~~~~~~~~~~~~~~~~~~~
>
> diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst
> index 36489f6e68..2ea898ff8a 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.
> +

Prefix is usually lower case, so eal:.

> +* 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
>

Otherwise this lgtm.


-- 
David Marchand