From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <dev-bounces@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 <dev@dpdk.org>; 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 <bruce.richardson@intel.com>
To: dev@dpdk.org
Cc: david.marchand@redhat.com, Bruce Richardson <bruce.richardson@intel.com>,
=?UTF-8?q?Morten=20Br=C3=B8rup?= <mb@smartsharesystems.com>
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
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
<mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://mails.dpdk.org/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://mails.dpdk.org/listinfo/dev>,
<mailto:dev-request@dpdk.org?subject=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 <bruce.richardson@intel.com>
Acked-by: Morten Brørup <mb@smartsharesystems.com>
---
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.
--
2.45.2