On Fri, Nov 06, 2026 at 05:32:51PM +0800, fengchengwen wrote: > On 11/6/2026 4:50 PM, Bruce Richardson wrote: > > On Fri, Nov 06, 2026 at 08:46:32AM +0000, Bruce Richardson wrote: > >> On Fri, Nov 06, 2026 at 02:14:36PM +0800, Chengwen Feng wrote: > >>> From: Chengwen Feng <[email protected]> > >>> > >>> This is a new version of the "use NUMA node terminology" series, > >>> which converted the whole tree to the NUMA node terminology > >>> (about 227 patches). > >>> > >>> Following the review feedback, this version takes a staged > >>> approach. This series only contains the groundwork, there is no > >>> tree-wide replacement patch: > >>> > >>> 1/2 doc: deprecate socket terminology in favor of NUMA node > >>> 2/2 cocci: add script for NUMA node terminology renames > >>> > >>> The deprecation notice announces the socket_id to numa_node field > >>> renames of the public structures and the deprecation of the > >>> socket-named functions, the rte_malloc_socket_stats structure and > >>> the SOCKET_ID_ANY macro. The old names are kept as deprecated > >>> aliases for one release, giving applications a full release > >>> window to migrate. > >>> > >>> Once the notice has completed a release cycle, the coccinelle > >>> script will be used to generate a single tree-wide conversion > >>> patch, instead of the previous large series of small patches > >>> which overloaded the CI. > >>> > >>> The script covers the mechanical source renames: API function > >>> call sites, macros, the rte_malloc_socket_stats structure, and > >>> socket_id member accesses. Coccinelle cannot express every > >>> needed change: designated initializers, union field declarations, > >>> documentation and string literals require manual adjustments; it > >>> also silently skips functions whose signature carries attribute > >>> macros it does not know (e.g. __rte_unused). The same applies to > >>> the fields named "socket" in rte_graph and rte_bbdev_queue_conf, > >>> where a generic rename rule would over-match. > >>> > >>> The replacement names follow the libnuma node semantics while > >>> keeping the existing DPDK memory allocation model: bare node > >>> getters (rte_numa_node(), rte_numa_node_count(), > >>> rte_numa_node_by_idx(), rte_cpu_numa_node(), > >>> rte_lcore_to_numa_node()), an rte_malloc_onnode() allocation > >>> family shaped after libnuma's numa_alloc_onnode(), and > >>> rte_malloc_heap_get_numa_node(). > >>> > >>> Series-changes: 2 > >>> - only the deprecation notice and the coccinelle script, the > >>> tree-wide conversion patch will be submitted after the notice > >>> completes a release cycle > >>> - keep old names as deprecated aliases for one release window > >>> - cover the full rename set in the script (malloc family, > >>> rte_cpu_socket_id, rte_cryptodev_socket_id, > >>> rte_ml_dev_socket_id, rte_malloc_socket_stats) > >>> - use a "Terminology change" tag in the deprecation notice as > >>> the rename spans several libraries > >>> - name the replacements after libnuma semantics > >>> (rte_numa_node(), rte_malloc_onnode(), ...) > >>> > >>> Chengwen Feng (2): > >>> doc: deprecate socket terminology in favor of NUMA node > >>> cocci: add script for NUMA node terminology renames > >>> > >> I worry a bit about the churn and compatibilty issues such a widespread > >> rename sould cause. These are some very widely used, common APIs that have > >> been around since the earliest days of DPDK. At minimum I think we need to > >> keep the old functions around for well longer than just one release window > >> after deprecation - a multi-year deprecation and removal plan would be > >> better to avoid suddenly breaking every DPDK end-application out there. > >> > > > > Might an alternative solution be to just document that DPDK historically > > uses "socket" as a synonym for numa node, even though such a term is > > inaccurate. Just accept the less-than-optimal naming as a historical > > oddity? > > I share the concern about compatibility impact given how ubiquitous these > APIs are. > It is important to separate two steps: > 1) Updating DPDK internal code to use the new NUMA naming via the cocci script > 2) Removing the deprecated socket-named aliases for applications > > The first step only cleans the in-tree codebase. The old aliases can stay > present > for applications for a multi-year period, and their removal can be scheduled > independently, not immediately after one release cycle. > > Keeping the existing names and only updating documentation is a pragmatic > option, > but it does not resolve the recurring confusion between CPU socket and NUMA > node. > This mismatch still misleads new developers and triggers topology-related > bugs. > > I am willing to follow community consensus on the deprecation timeline and > the overall approach. >
Yes, good point about the first option being entirely safe, and only the second affecting compatibility. Therefore, I'm ok with adding the new versions of the functions/macros etc. with the new names. /Bruce
