From patchwork Tue May 13 16:17:08 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 153429 X-Patchwork-Delegate: david.marchand@redhat.com Return-Path: X-Original-To: patchwork@inbox.dpdk.org Delivered-To: patchwork@inbox.dpdk.org Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 24AE14673A; Tue, 13 May 2025 18:17:41 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 7CEED402DF; Tue, 13 May 2025 18:17:36 +0200 (CEST) Received: from mgamail.intel.com (mgamail.intel.com [192.198.163.14]) by mails.dpdk.org (Postfix) with ESMTP id A09B8402CA for ; Tue, 13 May 2025 18:17:34 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1747153055; x=1778689055; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=4nzgHQwQwh5UJWYPb1i4/2F1z0TnR30m5+spddFq48k=; b=iZdLDeRzKvRg7IsfjWZZtpASeAFHNcv3pU7cBKSbrJg+EoMeER+eDsVz c7DRPa6EfrevX+RShkDUAlBoNDYZ50C6mwSOGt3kSlShbCb2/ARkgrshv NvN7MQmKHKpURJOHGAARd4nz3vGaRH7GVynKWEhNgd7bg1hWS4GItT8XI h1N0f4m/7XatPJtSDo7flPpMhhobqgVFQFzHQIdeAv3yBXYDKciN5cGjH P05Yk7ySc7QSR6FMtHrRBmufHSogt/hG7gsEgBMW/C096x4vYEZ1GLp83 CRLgIh0QCsnBN8OvkF3kvIlLFKlZAVVDGdtFYDJtD4r/9xoB3eZ2URrD1 w==; X-CSE-ConnectionGUID: 6fg/P7d+Q92SZbh2lDBbBw== X-CSE-MsgGUID: Z1ejg/9tT46KYiWG/orMlg== X-IronPort-AV: E=McAfee;i="6700,10204,11432"; a="49130060" X-IronPort-AV: E=Sophos;i="6.15,285,1739865600"; d="scan'208";a="49130060" Received: from fmviesa009.fm.intel.com ([10.60.135.149]) by fmvoesa108.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 13 May 2025 09:17:34 -0700 X-CSE-ConnectionGUID: /i3GUHg+TW+FJfITWl8v7g== X-CSE-MsgGUID: tXulzHJMQaqXRP1muL00Uw== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.15,285,1739865600"; d="scan'208";a="138733214" Received: from unknown (HELO silpixa00401385.ir.intel.com) ([10.237.214.31]) by fmviesa009.fm.intel.com with ESMTP; 13 May 2025 09:17:33 -0700 From: Bruce Richardson To: dev@dpdk.org Cc: david.marchand@redhat.com, Bruce Richardson Subject: [PATCH v4 1/3] eal: deprecate old coremask-based EAL parameters Date: Tue, 13 May 2025 17:17:08 +0100 Message-ID: <20250513161710.410000-2-bruce.richardson@intel.com> X-Mailer: git-send-email 2.45.2 In-Reply-To: <20250513161710.410000-1-bruce.richardson@intel.com> References: <20250313113829.1480907-1-bruce.richardson@intel.com> <20250513161710.410000-1-bruce.richardson@intel.com> MIME-Version: 1.0 X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org 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. Signed-off-by: Bruce Richardson --- doc/guides/eventdevs/dlb2.rst | 6 +++--- doc/guides/faq/faq.rst | 8 +++----- doc/guides/linux_gsg/build_sample_apps.rst | 7 +++---- doc/guides/linux_gsg/eal_args.include.rst | 8 ++------ doc/guides/prog_guide/meson_ut.rst | 2 +- doc/guides/prog_guide/multi_proc_support.rst | 2 +- doc/guides/prog_guide/service_cores.rst | 8 ++++---- doc/guides/rel_notes/deprecation.rst | 10 ++++++++++ doc/guides/sample_app_ug/ip_frag.rst | 7 +------ doc/guides/sample_app_ug/ip_reassembly.rst | 7 +------ doc/guides/sample_app_ug/multi_process.rst | 14 +++++--------- doc/guides/sample_app_ug/qos_scheduler.rst | 2 +- doc/guides/sample_app_ug/test_pipeline.rst | 2 +- doc/guides/tools/testbbdev.rst | 2 +- lib/eal/common/eal_common_options.c | 6 ++++++ 15 files changed, 43 insertions(+), 48 deletions(-) diff --git a/doc/guides/eventdevs/dlb2.rst b/doc/guides/eventdevs/dlb2.rst index 2532d92888..d1b736830d 100644 --- a/doc/guides/eventdevs/dlb2.rst +++ b/doc/guides/eventdevs/dlb2.rst @@ -408,9 +408,9 @@ the DLB device locally available on the same tile along with other resources. To allocate optimal resources, probing is done for each producer port (PP) for a given CPU and the best performing ports are allocated to producers. The cpu used for probing is either the first -core of producer coremask (if present) or the second core of EAL -coremask. This will be extended later to probe for all CPUs in the -producer coremask or EAL coremask. Producer coremask can be passed +core of producer coremask DLB2 device parameter (if present) or the second core of EAL +core list. This will be extended later to probe for all CPUs in the +producer coremask or EAL core list. Producer coremask can be passed along with the BDF of the DLB devices. .. code-block:: console diff --git a/doc/guides/faq/faq.rst b/doc/guides/faq/faq.rst index 297cb5119e..ddcb018b3a 100644 --- a/doc/guides/faq/faq.rst +++ b/doc/guides/faq/faq.rst @@ -47,11 +47,9 @@ therefore all the hugepages are allocated on the wrong socket. To avoid this scenario, either lower the amount of hugepage memory available to 1 GB size (or less), or run the application with taskset affinitizing the application to a would-be main core. -For example, if your EAL coremask is 0xff0, the main core will usually be the first core in the coremask (0x10); this is what you have to supply to taskset:: +For example, if your EAL core list is '4-11', the main core will usually be the first core in the list (core 4); this is what you have to supply to taskset:: - taskset 0x10 ./l2fwd -l 4-11 -n 2 - -.. Note: Instead of '-c 0xff0' use the '-l 4-11' as a cleaner way to define lcores. + taskset -c 4 ./l2fwd -l 4-11 -n 2 In this way, the hugepages have a greater chance of being allocated to the correct socket. Additionally, a ``--socket-mem`` option could be used to ensure the availability of memory for each socket, so that if hugepages were allocated on @@ -167,7 +165,7 @@ Can I split packet RX to use DPDK and have an application's higher order functio ---------------------------------------------------------------------------------------------------------------- The DPDK's lcore threads are Linux pthreads bound onto specific cores. Configure the DPDK to do work on the same -cores and run the application's other work on other cores using the DPDK's "coremask" setting to specify which +cores and run the application's other work on other cores using the DPDK's "core list" (-l/--lcores) setting to specify which cores it should launch itself on. diff --git a/doc/guides/linux_gsg/build_sample_apps.rst b/doc/guides/linux_gsg/build_sample_apps.rst index 433839ecc7..c568549f26 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. 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 9cfbf7de84..7ffd2e2535 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 `` - - Set the hexadecimal bitmask of the cores to run on. - * ``-l `` List of cores to run on @@ -37,9 +33,9 @@ Lcore-related options Core ID that is used as main. -* ``-s `` +* ``-S `` - Hexadecimal bitmask of cores to be used as service cores. + List of cores to be used as service cores. Device-related options ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/guides/prog_guide/meson_ut.rst b/doc/guides/prog_guide/meson_ut.rst index 78cf3f845c..9bc52a30fc 100644 --- a/doc/guides/prog_guide/meson_ut.rst +++ b/doc/guides/prog_guide/meson_ut.rst @@ -60,7 +60,7 @@ Arguments of ``test()`` that can be provided in meson.build are as below: Note: the content of meson ``--test-args`` option and the content of ``args`` are appended when invoking the DPDK test binary. -Because of this, it is recommended not to set any default coremask or memory +Because of this, it is recommended not to set any default corelist or memory configuration in per test ``args`` and rather let users select what best fits their environment. If a test can't run, then it should be skipped, as described below. diff --git a/doc/guides/prog_guide/multi_proc_support.rst b/doc/guides/prog_guide/multi_proc_support.rst index 0c57145470..dd57b6f8c1 100644 --- a/doc/guides/prog_guide/multi_proc_support.rst +++ b/doc/guides/prog_guide/multi_proc_support.rst @@ -166,7 +166,7 @@ Some of these are documented below: so it is recommended that it be disabled only when absolutely necessary, and only when the implications of this change have been understood. -* All DPDK processes running as a single application and using shared memory must have distinct coremask/corelist arguments. +* All DPDK processes running as a single application and using shared memory must have distinct corelist arguments. It is not possible to have a primary and secondary instance, or two secondary instances, using any of the same logical cores. Attempting to do so can cause corruption of memory pool caches, among other issues. diff --git a/doc/guides/prog_guide/service_cores.rst b/doc/guides/prog_guide/service_cores.rst index d4e6c3d6e6..5284eeb96a 100644 --- a/doc/guides/prog_guide/service_cores.rst +++ b/doc/guides/prog_guide/service_cores.rst @@ -26,10 +26,10 @@ Service Core Initialization ~~~~~~~~~~~~~~~~~~~~~~~~~~~ There are two methods to having service cores in a DPDK application, either by -using the service coremask, or by dynamically adding cores using the API. -The simpler of the two is to pass the `-s` coremask argument to EAL, which will -take any cores available in the main DPDK coremask, and if the bits are also set -in the service coremask the cores become service-cores instead of DPDK +using the service corelist, or by dynamically adding cores using the API. +The simpler of the two is to pass the `-S` corelist argument to EAL, which will +take any cores available in the main DPDK corelist, and if also set +in the service corelist the cores become service-cores instead of DPDK application lcores. Enabling Services on Cores 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 `` commandline parameter is deprecated + and will be removed in a future release. + Use the ``-l `` or ``--lcores=`` parameters instead + to specify the cores to be used when running a DPDK application. + +* EAL: The ``-s `` commandline parameter is deprecated + and will be removed in a future release. + Use the ``-S `` 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/doc/guides/sample_app_ug/ip_frag.rst b/doc/guides/sample_app_ug/ip_frag.rst index 4b2071cbae..3f0b5ce5e7 100644 --- a/doc/guides/sample_app_ug/ip_frag.rst +++ b/doc/guides/sample_app_ug/ip_frag.rst @@ -67,12 +67,7 @@ To run the example in linux environment with 2 lcores (2,4) over 2 ports(0,2) wi .. code-block:: console .//examples/dpdk-ip_fragmentation -l 2,4 -n 3 -- -p 5 - EAL: coremask set to 14 - EAL: Detected lcore 0 on socket 0 - EAL: Detected lcore 1 on socket 1 - EAL: Detected lcore 2 on socket 0 - EAL: Detected lcore 3 on socket 1 - EAL: Detected lcore 4 on socket 0 + EAL: Detected CPU lcores: ... ... Initializing port 0 on lcore 2... Address:00:1B:21:76:FA:2C, rxq=0 txq=2,0 txq=4,1 diff --git a/doc/guides/sample_app_ug/ip_reassembly.rst b/doc/guides/sample_app_ug/ip_reassembly.rst index b8800dd9e7..e55ee7eb79 100644 --- a/doc/guides/sample_app_ug/ip_reassembly.rst +++ b/doc/guides/sample_app_ug/ip_reassembly.rst @@ -63,12 +63,7 @@ with 1 Rx queue per lcore: .. code-block:: console .//examples/dpdk-ip_reassembly -l 2,4 -n 3 -- -p 5 - EAL: coremask set to 14 - EAL: Detected lcore 0 on socket 0 - EAL: Detected lcore 1 on socket 1 - EAL: Detected lcore 2 on socket 0 - EAL: Detected lcore 3 on socket 1 - EAL: Detected lcore 4 on socket 0 + EAL: Detected CPU lcores: ... ... Initializing port 0 on lcore 2... Address:00:1B:21:76:FA:2C, rxq=0 txq=2,0 txq=4,1 diff --git a/doc/guides/sample_app_ug/multi_process.rst b/doc/guides/sample_app_ug/multi_process.rst index e2b1b16c84..29bca806e1 100644 --- a/doc/guides/sample_app_ug/multi_process.rst +++ b/doc/guides/sample_app_ug/multi_process.rst @@ -36,7 +36,7 @@ Running the Application ^^^^^^^^^^^^^^^^^^^^^^^ To run the application, start ``simple_mp`` binary in one terminal, -passing at least two cores in the coremask/corelist: +passing at least two cores in the corelist: .. code-block:: console @@ -50,11 +50,7 @@ The process should start successfully and display a command prompt as follows: .. code-block:: console $ .//examples/dpdk-simple_mp -l 0-1 -n 4 --proc-type=primary - EAL: coremask set to 3 - EAL: Detected lcore 0 on socket 0 - EAL: Detected lcore 1 on socket 0 - EAL: Detected lcore 2 on socket 0 - EAL: Detected lcore 3 on socket 0 + EAL: Detected CPU lcores: ... ... EAL: Requesting 2 pages of size 1073741824 @@ -72,7 +68,7 @@ The process should start successfully and display a command prompt as follows: simple_mp > To run the secondary process to communicate with the primary process, -again run the same binary setting at least two cores in the coremask/corelist: +again run the same binary setting at least two cores in the corelist: .. code-block:: console @@ -237,8 +233,8 @@ In addition to the EAL parameters, the application-specific parameters are: .. note:: In the server process, has a single thread using the lowest numbered lcore - in the coremask/corelist, performs all packet I/O. - If coremask/corelist parameter specifies with more than a single lcore bit set, + in the corelist, performs all packet I/O. + If corelist parameter specifies with more than a single lcore, an additional lcore will be used for a thread to print packet count periodically. The server application stores configuration data in shared memory, diff --git a/doc/guides/sample_app_ug/qos_scheduler.rst b/doc/guides/sample_app_ug/qos_scheduler.rst index 9936b99172..36ada4902c 100644 --- a/doc/guides/sample_app_ug/qos_scheduler.rst +++ b/doc/guides/sample_app_ug/qos_scheduler.rst @@ -194,7 +194,7 @@ Another example with 2 packet flow configurations using different ports but shar Note that independent cores for the packet flow configurations for each of the RX, WT and TX thread are also supported, providing flexibility to balance the work. -The EAL coremask/corelist is constrained to contain the default main core 1 and the RX, WT and TX cores only. +The EAL corelist is constrained to contain the default main core 1 and the RX, WT and TX cores only. Explanation ----------- diff --git a/doc/guides/sample_app_ug/test_pipeline.rst b/doc/guides/sample_app_ug/test_pipeline.rst index d57d08fb2c..818be93cd6 100644 --- a/doc/guides/sample_app_ug/test_pipeline.rst +++ b/doc/guides/sample_app_ug/test_pipeline.rst @@ -47,7 +47,7 @@ The application execution command line is: ./dpdk-test-pipeline [EAL options] -- -p PORTMASK --TABLE_TYPE -The -c or -l EAL CPU coremask/corelist option has to contain exactly 3 CPU cores. +The ``-l/--lcores`` EAL CPU corelist option has to contain exactly 3 CPU cores. The first CPU core in the core mask is assigned for core A, the second for core B and the third for core C. The PORTMASK parameter must contain 2 or 4 ports. diff --git a/doc/guides/tools/testbbdev.rst b/doc/guides/tools/testbbdev.rst index ddb8d787be..8677cd2c43 100644 --- a/doc/guides/tools/testbbdev.rst +++ b/doc/guides/tools/testbbdev.rst @@ -78,7 +78,7 @@ The following are the command-line options: ``-l NUM_LCORES, --num_lcores NUM_LCORES`` Specifies number of lcores to run. If not specified num_lcores is set - according to value from RTE configuration (EAL coremask) + according to value from RTE configuration (EAL corelist) ``-b BURST_SIZE [BURST_SIZE ...], --burst-size BURST_SIZE [BURST_SIZE ...]`` Specifies operations enqueue/dequeue burst size. If not specified burst_size is diff --git a/lib/eal/common/eal_common_options.c b/lib/eal/common/eal_common_options.c index b6fff7ec05..19c5997c7c 100644 --- a/lib/eal/common/eal_common_options.c +++ b/lib/eal/common/eal_common_options.c @@ -614,6 +614,9 @@ eal_parse_service_coremask(const char *coremask) int val; uint32_t taken_lcore_count = 0; + EAL_LOG(WARNING, "'-s ' is deprecated, and will be removed in a future release."); + EAL_LOG(WARNING, "\tUse '-S ' option instead."); + if (coremask == NULL) return -1; /* Remove all blank characters ahead and after . @@ -777,6 +780,9 @@ rte_eal_parse_coremask(const char *coremask, int *cores) cores[idx] = -1; idx = 0; + EAL_LOG(WARNING, "'-c ' option is deprecated, and will be removed in a future release"); + EAL_LOG(WARNING, "\tUse '-l ' or '--lcores=' option instead"); + /* Remove all blank characters ahead and after . * Remove 0x/0X if exists. */ From patchwork Tue May 13 16:17:09 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 153430 X-Patchwork-Delegate: david.marchand@redhat.com Return-Path: X-Original-To: patchwork@inbox.dpdk.org Delivered-To: patchwork@inbox.dpdk.org Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id BC3304673A; Tue, 13 May 2025 18:17:48 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id A375E402F0; Tue, 13 May 2025 18:17:38 +0200 (CEST) Received: from mgamail.intel.com (mgamail.intel.com [192.198.163.14]) by mails.dpdk.org (Postfix) with ESMTP id E7BFC402ED for ; Tue, 13 May 2025 18:17:36 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1747153057; x=1778689057; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=+qPpC2DPLRLBjVxPC2zSimMfgrNIHcnvtR7TKZWvR/o=; b=PbfvmVCHW+E3gxpo8qSMdyBSwE05g0LnY02b0BCrT2ox1BX03G5uaj1G 3pOORY5ah4quiNgs/U0W1hQK+3/nrzPaK8ynWHgQIp9viMW0e1toKVeTy l9CVKKsuIn0e9S3YNkGMng+Yb+Lxv662dc8V8B9lyvm9Sb98E6m2EvS2C YP+Aqjy2zuGnYv7zQ8vR47gBQCWNy0B0m51iJbhrW0uHr9rp+MfPboO43 3wy2YixOblawRseUQBa8iHhsj4E4P2I/y0iDd9VIdy/toOAQpBgELa8ox 5nV2Yv3jR7+kP0w3DGm7ZvyTTskNvJaNOsJUEabGwPsf/SJ7sDzcjoaPr w==; X-CSE-ConnectionGUID: 2w6TvWrqTBukpEZC5Ac5lw== X-CSE-MsgGUID: m53VnP71SqWPEvSgVnDEsA== X-IronPort-AV: E=McAfee;i="6700,10204,11432"; a="49130064" X-IronPort-AV: E=Sophos;i="6.15,285,1739865600"; d="scan'208";a="49130064" Received: from fmviesa009.fm.intel.com ([10.60.135.149]) by fmvoesa108.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 13 May 2025 09:17:36 -0700 X-CSE-ConnectionGUID: UuyRa3WZSBuHHs3xAsiifw== X-CSE-MsgGUID: gY6zyFPXR3KKdcbeKtjeHA== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.15,285,1739865600"; d="scan'208";a="138733223" Received: from unknown (HELO silpixa00401385.ir.intel.com) ([10.237.214.31]) by fmviesa009.fm.intel.com with ESMTP; 13 May 2025 09:17:35 -0700 From: Bruce Richardson To: dev@dpdk.org Cc: david.marchand@redhat.com, Bruce Richardson Subject: [PATCH v4 2/3] eal: merge corelist and core mapping options Date: Tue, 13 May 2025 17:17:09 +0100 Message-ID: <20250513161710.410000-3-bruce.richardson@intel.com> X-Mailer: git-send-email 2.45.2 In-Reply-To: <20250513161710.410000-1-bruce.richardson@intel.com> References: <20250313113829.1480907-1-bruce.richardson@intel.com> <20250513161710.410000-1-bruce.richardson@intel.com> MIME-Version: 1.0 X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org The "-l" EAL parameter supported a subset of the features that were provided by the "--lcores" long option. There is no need to have two different options with different behaviour in this case, so we can just eliminate the special-case handling for "-l", and have it as a shortened form of "--lcores". Signed-off-by: Bruce Richardson --- doc/guides/linux_gsg/eal_args.include.rst | 10 +- .../prog_guide/env_abstraction_layer.rst | 3 +- lib/eal/common/eal_common_options.c | 135 ++---------------- lib/eal/common/eal_options.h | 4 +- 4 files changed, 21 insertions(+), 131 deletions(-) diff --git a/doc/guides/linux_gsg/eal_args.include.rst b/doc/guides/linux_gsg/eal_args.include.rst index 7ffd2e2535..01fe6a3006 100644 --- a/doc/guides/linux_gsg/eal_args.include.rst +++ b/doc/guides/linux_gsg/eal_args.include.rst @@ -4,16 +4,14 @@ Lcore-related options ~~~~~~~~~~~~~~~~~~~~~ -* ``-l `` +* ``-l/--lcores `` List of cores to run on - The argument format is ``[-c2][,c3[-c4],...]`` - where ``c1``, ``c2``, etc are core indexes between 0 and 128. + Simplest argument format is ``[-c2][,c3[-c4],...]`` + where ``c1``, ``c2``, etc are core indexes between 0 and ``RTE_MAX_LCORE`` (default 128). -* ``--lcores `` - - Map lcore set to physical cpu set + This argument can also be used to map lcore set to physical cpu set The argument format is:: diff --git a/doc/guides/prog_guide/env_abstraction_layer.rst b/doc/guides/prog_guide/env_abstraction_layer.rst index 04214a05b2..fca9cc0afa 100644 --- a/doc/guides/prog_guide/env_abstraction_layer.rst +++ b/doc/guides/prog_guide/env_abstraction_layer.rst @@ -729,7 +729,7 @@ As EAL pthreads usually bind 1:1 to the physical CPU, the *_lcore_id* is typical When using multiple pthreads, however, the binding is no longer always 1:1 between an EAL pthread and a specified physical CPU. The EAL pthread may have affinity to a CPU set, and as such the *_lcore_id* will not be the same as the CPU ID. -For this reason, there is an EAL long option '--lcores' defined to assign the CPU affinity of lcores. +For this reason, there is an EAL option ``--lcores`` (or just ``-l``) defined to assign the CPU affinity of lcores. For a specified lcore ID or ID group, the option allows setting the CPU set for that EAL pthread. The format pattern: @@ -753,7 +753,6 @@ If a '\@cpu_set' value is not supplied, the value of 'cpu_set' will default to t lcore 8 runs on cpuset 0x100 (cpu 8). Using this option, for each given lcore ID, the associated CPUs can be assigned. -It's also compatible with the pattern of corelist('-l') option. non-EAL pthread support ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/lib/eal/common/eal_common_options.c b/lib/eal/common/eal_common_options.c index 19c5997c7c..ed514ec1d1 100644 --- a/lib/eal/common/eal_common_options.c +++ b/lib/eal/common/eal_common_options.c @@ -46,7 +46,6 @@ #define BITS_PER_HEX 4 #define LCORE_OPT_LST 1 #define LCORE_OPT_MSK 2 -#define LCORE_OPT_MAP 3 const char eal_short_options[] = @@ -921,85 +920,6 @@ eal_parse_service_corelist(const char *corelist) return 0; } -static int -eal_parse_corelist(const char *corelist, int *cores) -{ - unsigned int count = 0, i; - int lcores[RTE_MAX_LCORE]; - char *end = NULL; - int min, max; - int idx; - - for (idx = 0; idx < RTE_MAX_LCORE; idx++) - cores[idx] = -1; - - /* Remove all blank characters ahead */ - while (isblank(*corelist)) - corelist++; - - /* Get list of cores */ - min = -1; - do { - while (isblank(*corelist)) - corelist++; - if (*corelist == '\0') - return -1; - errno = 0; - idx = strtol(corelist, &end, 10); - if (errno || end == NULL) - return -1; - if (idx < 0) - return -1; - while (isblank(*end)) - end++; - if (*end == '-') { - min = idx; - } else if ((*end == ',') || (*end == '\0')) { - max = idx; - if (min == -1) - min = idx; - for (idx = min; idx <= max; idx++) { - bool dup = false; - - /* Check if this idx is already present */ - for (i = 0; i < count; i++) { - if (lcores[i] == idx) - dup = true; - } - if (dup) - continue; - if (count >= RTE_MAX_LCORE) { - EAL_LOG(ERR, "Too many lcores provided. Cannot exceed RTE_MAX_LCORE (%d)", - RTE_MAX_LCORE); - return -1; - } - lcores[count++] = idx; - } - min = -1; - } else - return -1; - corelist = end + 1; - } while (*end != '\0'); - - if (count == 0) - return -1; - - if (check_core_list(lcores, count)) - return -1; - - /* - * Now that we've got a list of cores no longer than RTE_MAX_LCORE, - * and no lcore in that list is greater than RTE_MAX_LCORE, populate - * the cores array. - */ - do { - count--; - cores[lcores[count]] = count; - } while (count != 0); - - return 0; -} - /* Changes the lcore id of the main thread */ static int eal_parse_main_lcore(const char *arg) @@ -1703,10 +1623,10 @@ eal_parse_common_option(int opt, const char *optarg, } if (core_parsed) { - EAL_LOG(ERR, "Option -c is ignored, because (%s) is set!", - (core_parsed == LCORE_OPT_LST) ? "-l" : - (core_parsed == LCORE_OPT_MAP) ? "--lcores" : - "-c"); + if (core_parsed == LCORE_OPT_MSK) + EAL_LOG(ERR, "Option '-c' passed multiple times to EAL"); + else + EAL_LOG(ERR, "Option -c is ignored, because option -l/--lcores used"); return -1; } @@ -1715,31 +1635,20 @@ eal_parse_common_option(int opt, const char *optarg, } /* corelist */ case 'l': { - int lcore_indexes[RTE_MAX_LCORE]; - if (eal_service_cores_parsed()) EAL_LOG(WARNING, "Service cores parsed before dataplane cores. Please ensure -l is before -s or -S"); - if (eal_parse_corelist(optarg, lcore_indexes) < 0) { - EAL_LOG(ERR, "invalid core list syntax"); - return -1; - } - if (update_lcore_config(lcore_indexes) < 0) { - char *available = available_cores(); - - EAL_LOG(ERR, - "invalid core list, please check specified cores are part of %s", - available); - free(available); + if (eal_parse_lcores(optarg) < 0) { + EAL_LOG(ERR, "invalid parameter for -l/--" OPT_LCORES); return -1; } if (core_parsed) { - EAL_LOG(ERR, "Option -l is ignored, because (%s) is set!", - (core_parsed == LCORE_OPT_MSK) ? "-c" : - (core_parsed == LCORE_OPT_MAP) ? "--lcores" : - "-l"); + if (core_parsed == LCORE_OPT_LST) + EAL_LOG(ERR, "Core list option passed multiple times to EAL"); + else + EAL_LOG(ERR, "Option '-l/--lcores' is ignored, because coremask option used"); return -1; } @@ -1926,23 +1835,6 @@ eal_parse_common_option(int opt, const char *optarg, } #endif /* !RTE_EXEC_ENV_WINDOWS */ - case OPT_LCORES_NUM: - if (eal_parse_lcores(optarg) < 0) { - EAL_LOG(ERR, "invalid parameter for --" - OPT_LCORES); - return -1; - } - - if (core_parsed) { - EAL_LOG(ERR, "Option --lcores is ignored, because (%s) is set!", - (core_parsed == LCORE_OPT_LST) ? "-l" : - (core_parsed == LCORE_OPT_MSK) ? "-c" : - "--lcores"); - return -1; - } - - core_parsed = LCORE_OPT_MAP; - break; case OPT_LEGACY_MEM_NUM: conf->legacy_mem = 1; break; @@ -2214,10 +2106,11 @@ eal_common_usage(void) printf("[options]\n\n" "EAL common options:\n" " -c COREMASK Hexadecimal bitmask of cores to run on\n" - " -l CORELIST List of cores to run on\n" - " The argument format is [-c2][,c3[-c4],...]\n" + " -l, --"OPT_LCORES" CORELIST\n" + " List of cores to run on\n" + " The basic argument format is [-c2][,c3[-c4],...]\n" " where c1, c2, etc are core indexes between 0 and %d\n" - " --"OPT_LCORES" COREMAP Map lcore set to physical cpu set\n" + " Can also be used to map lcore set to physical cpu set\n" " The argument format is\n" " '[<,lcores[@cpus]>...]'\n" " lcores and cpus list are grouped by '(' and ')'\n" diff --git a/lib/eal/common/eal_options.h b/lib/eal/common/eal_options.h index 95fb4f6108..7b84b7d778 100644 --- a/lib/eal/common/eal_options.h +++ b/lib/eal/common/eal_options.h @@ -17,6 +17,8 @@ enum { OPT_DEV_ALLOW_NUM = 'a', #define OPT_DEV_BLOCK "block" OPT_DEV_BLOCK_NUM = 'b', +#define OPT_LCORES "lcores" + OPT_LCORES_NUM = 'l', /* first long only option value must be >= 256, so that we won't * conflict with short options */ @@ -31,8 +33,6 @@ enum { OPT_HUGE_DIR_NUM, #define OPT_HUGE_UNLINK "huge-unlink" OPT_HUGE_UNLINK_NUM, -#define OPT_LCORES "lcores" - OPT_LCORES_NUM, #define OPT_LOG_COLOR "log-color" OPT_LOG_COLOR_NUM, #define OPT_LOG_LEVEL "log-level" From patchwork Tue May 13 16:17:10 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 153431 X-Patchwork-Delegate: david.marchand@redhat.com Return-Path: X-Original-To: patchwork@inbox.dpdk.org Delivered-To: patchwork@inbox.dpdk.org Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 93BAA4673A; Tue, 13 May 2025 18:17:57 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 32D7E40613; Tue, 13 May 2025 18:17:41 +0200 (CEST) Received: from mgamail.intel.com (mgamail.intel.com [192.198.163.14]) by mails.dpdk.org (Postfix) with ESMTP id 175BB4042F for ; Tue, 13 May 2025 18:17:38 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1747153059; x=1778689059; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=U6Y/5zlQcbfNged6ocupYBHYDfCjtOarOUxjoad3o9s=; b=QvBPxaW9RGVffdvLT+fXrXi+VGce5iORvaZQ8egW6J2+O5vWhh6WYlKl 8R+GYSA3srXa/01mKWo2eFSMUeVNSQRcWrAT2h4djf3l/wHtlnGAaTZwd pQRL/GxsJRmX+e85W/cHfIXHnTNkGxT0Jt3J86p1aenoQS2t0Xfs0OVjy 8xQDzwcY46KrJl6OnAYps6hjR/tnN0jdeeTQxrTdrhVoKc/jCxG9hhXJ+ aa2aK9szNTnHKUAGNrsEWU3ryfFHLvGx0QlO0Fg6DDFii4QqVRxoIsIoZ lX9EhGgWQq3xwuUM/7eBLVzHjVvHQcs8wmZbirw82vQzXl8kJPEJM16Sr w==; X-CSE-ConnectionGUID: +vqLfJqKRVuRnVD50Hp1Ew== X-CSE-MsgGUID: /VtddRQvTKqgv3bVbywlxg== X-IronPort-AV: E=McAfee;i="6700,10204,11432"; a="49130067" X-IronPort-AV: E=Sophos;i="6.15,285,1739865600"; d="scan'208";a="49130067" Received: from fmviesa009.fm.intel.com ([10.60.135.149]) by fmvoesa108.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 13 May 2025 09:17:39 -0700 X-CSE-ConnectionGUID: zQUyDWuCRamyEMqghjAnEw== X-CSE-MsgGUID: jLt9/31BSq+D1iEK4g6rDg== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.15,285,1739865600"; d="scan'208";a="138733229" Received: from unknown (HELO silpixa00401385.ir.intel.com) ([10.237.214.31]) by fmviesa009.fm.intel.com with ESMTP; 13 May 2025 09:17:37 -0700 From: Bruce Richardson To: dev@dpdk.org Cc: david.marchand@redhat.com, Bruce Richardson , =?utf-8?q?Morten_Br=C3=B8rup?= Subject: [PATCH v4 3/3] doc: provide examples of using lcores EAL parameter Date: Tue, 13 May 2025 17:17:10 +0100 Message-ID: <20250513161710.410000-4-bruce.richardson@intel.com> X-Mailer: git-send-email 2.45.2 In-Reply-To: <20250513161710.410000-1-bruce.richardson@intel.com> References: <20250313113829.1480907-1-bruce.richardson@intel.com> <20250513161710.410000-1-bruce.richardson@intel.com> MIME-Version: 1.0 X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org 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 Acked-by: Morten Brørup --- 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. + +.. Note:: + Binding multiple DPDK lcores to a single physical CPU can cause problems with poor performance + or deadlock when using DPDK rings or memory pools or spinlocks. + Such a configuration should only be used with care. + .. Note:: At a given instance only one core option ``--lcores``, ``-l`` or ``-c`` can be used.