[RFC PATCH v1 0/5] Adjust wording for NUMA vs. socket ID in DPDK

[Anatoly Burakov <anatoly.burakov@intel.com>]

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 -
Add internal API to get physical package ID [1]

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.

[1] This could be used to group lcores by physical package, see e.g. discussion
    under this patch: https://patches.dpdk.org/project/dpdk/cover/20240827151014.201-1-vipin.varghese@amd.com/

Anatoly Burakov (5):
  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
  lcore: store physical package ID internally

 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             | 28 +++++++++++++---
 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                  |  5 ++-
 lib/eal/common/eal_thread.h                   | 11 +++++++
 lib/eal/common/malloc_heap.c                  |  2 +-
 lib/eal/freebsd/eal.c                         |  2 +-
 lib/eal/freebsd/eal_lcore.c                   |  6 ++++
 lib/eal/include/rte_lcore.h                   | 25 +++++++-------
 lib/eal/linux/eal.c                           | 22 ++++++-------
 lib/eal/linux/eal_lcore.c                     | 28 ++++++++++++++++
 lib/eal/linux/eal_memory.c                    | 22 ++++++-------
 lib/eal/windows/eal.c                         |  2 +-
 lib/eal/windows/eal_lcore.c                   |  7 ++++
 33 files changed, 204 insertions(+), 124 deletions(-)

-- 
2.43.5