From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 5208545DAB; Tue, 26 Nov 2024 14:14:57 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 21EC540E36; Tue, 26 Nov 2024 14:14:57 +0100 (CET) Received: from mgamail.intel.com (mgamail.intel.com [198.175.65.15]) by mails.dpdk.org (Postfix) with ESMTP id 683254064A for ; Tue, 26 Nov 2024 14:14:55 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1732626896; x=1764162896; h=from:to:subject:date:message-id:mime-version: content-transfer-encoding; bh=y0MxiMKKto16pXlGsx8653h7lxcuGWJvo0UG4xmER88=; b=I9Jcrbfvl9AOFaFC8PCzZKwFUnsNa4xWacCkS8z2s1kudNsT3n9zU9A1 E7/c/IrlqN4JE3WnNjIhRrk969WaXIhhplT5q/dG8sENoV538Ls5UDvnX BfWbxCylvpnuqVVoMOdJ8JwCpKsBndG7ZOsUpcgfvBuvxj/vISJYsPnjH 8DiKcaQ5L/c6xqqSM2Ek3beBCHFv5Bazeh6uMrmo5qSU9oNt9tkDcDXKQ DpWri0KZhnZ6WHGpvm5QAnooR3h0r5sjHpUfRw0ASq08GVHpqyM7JaOvH WFxJaaHcJ3n1h+BL5Vlw5fQb4iGs6wfObGJ3PLYzFE75O+lLsWGQ4w/4f g==; X-CSE-ConnectionGUID: REO+K6JeQ4WC4rie9oQzLw== X-CSE-MsgGUID: AaKDUTYVSd2UAOYxa0ehSg== X-IronPort-AV: E=McAfee;i="6700,10204,11268"; a="36447014" X-IronPort-AV: E=Sophos;i="6.12,186,1728975600"; d="scan'208";a="36447014" Received: from orviesa007.jf.intel.com ([10.64.159.147]) by orvoesa107.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 26 Nov 2024 05:14:54 -0800 X-CSE-ConnectionGUID: MgXPWLzjRPu/7bo0Vc02MQ== X-CSE-MsgGUID: 4gUyemKyRKKoH+Ypi2zuBg== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.12,186,1728975600"; d="scan'208";a="92013303" Received: from silpixa00401119.ir.intel.com ([10.55.129.167]) by orviesa007.jf.intel.com with ESMTP; 26 Nov 2024 05:14:54 -0800 From: Anatoly Burakov To: dev@dpdk.org Subject: [PATCH v1 0/4] Adjust wording for NUMA vs. socket ID in DPDK Date: Tue, 26 Nov 2024 13:14:46 +0000 Message-ID: X-Mailer: git-send-email 2.43.5 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit 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 While initially, DPDK has used the term "socket ID" to refer to physical package ID, the last time DPDK read "physical_package_id" for socket ID was ~9 years ago, so it's been a while since we've actually switched over to using the term "socket" to mean "NUMA node". This wasn't a problem before, as most systems had one NUMA node per physical socket. However, in the last few years, more and more systems have multiple NUMA nodes per physical CPU socket. Since DPDK used NUMA nodes already, the transition was pretty seamless, however now we're faced with a situation when most of our documentation still uses outdated terms, and our API is ripe with references to "sockets" when in actuality we mean "NUMA nodes". This could be a source of confusion. While completely renaming all of our API's would be a huge effort, will take a long time and arguably wouldn't even be worth the API breakages (given that this mismatch between terminology and reality is implicitly understood by most people working on DPDK, and so this isn't so much of a problem in practice), we can do some tweaks around the edges and at least document this unfortunate reality. This patchset suggests the following changes: - Update rte_socket/rte_lcore documentation to refer to NUMA nodes rather than sockets - Rename internal structures' fields to better reflect this intention - Rename --socket-mem/--socket-limit flags to refer to NUMA rather than sockets The documentation is updated to refer to new EAL flags, but is otherwise left untouched, and instead the entry in "glossary" is amended to indicate that when DPDK documentation refers to "sockets", it actually means "NUMA ID's". As next steps, we could rename all API parameters to refer to NUMA ID rather than socket ID - this would not break neither API nor ABI, and instead would be a documentation change in practice. RFCv1 -> v1: - Dropped patch 5 - Updated error messages in patch 4 to refer to old flags as well Anatoly Burakov (4): eal: update socket ID API documentation lcore: rename socket ID to NUMA ID eal: rename socket ID to NUMA ID in internal config eal: rename --socket-mem/--socket-limit doc/guides/faq/faq.rst | 4 +-- doc/guides/howto/lm_bond_virtio_sriov.rst | 2 +- doc/guides/howto/lm_virtio_vhost_user.rst | 2 +- doc/guides/howto/pvp_reference_benchmark.rst | 4 +-- .../virtio_user_for_container_networking.rst | 2 +- doc/guides/linux_gsg/build_sample_apps.rst | 20 +++++------ doc/guides/linux_gsg/linux_eal_parameters.rst | 16 ++++----- doc/guides/nics/mlx4.rst | 2 +- doc/guides/nics/mlx5.rst | 2 +- .../prog_guide/env_abstraction_layer.rst | 12 +++---- doc/guides/prog_guide/glossary.rst | 5 ++- doc/guides/prog_guide/multi_proc_support.rst | 2 +- doc/guides/sample_app_ug/bbdev_app.rst | 6 ++-- doc/guides/sample_app_ug/ipsec_secgw.rst | 6 ++-- doc/guides/sample_app_ug/vdpa.rst | 2 +- doc/guides/sample_app_ug/vhost.rst | 4 +-- lib/eal/common/eal_common_dynmem.c | 14 ++++---- lib/eal/common/eal_common_lcore.c | 10 +++--- lib/eal/common/eal_common_options.c | 33 ++++++++++--------- lib/eal/common/eal_common_thread.c | 12 +++---- lib/eal/common/eal_internal_cfg.h | 10 +++--- lib/eal/common/eal_options.h | 8 +++-- lib/eal/common/eal_private.h | 2 +- lib/eal/common/malloc_heap.c | 2 +- lib/eal/freebsd/eal.c | 2 +- lib/eal/include/rte_lcore.h | 25 +++++++------- lib/eal/linux/eal.c | 28 +++++++++------- lib/eal/linux/eal_memory.c | 22 ++++++------- lib/eal/windows/eal.c | 2 +- 29 files changed, 137 insertions(+), 124 deletions(-) -- 2.43.5