doc, devtools: discourage new __rte_always_inline
RFC 1/1 doc, devtools: discourage new __rte_always_inline
Modern compilers at -O2 make good inlining decisions for small static inline functions; forced inlining via __rte_always_inline should be reserved for cases where it is required for correctness or for documented measured performance reasons.
Document the policy in the coding style guide and add a checkpatches.sh entry that warns when new uses of the attribute are introduced.
--- devtools/checkpatches.sh | 8 ++++++++ doc/guides/contributing/coding_style.rst | 25 +++++++++++++++++++++++- 2 files changed, 32 insertions(+), 1 deletion(-)
devtools/checkpatches.sh +8 -0
@@ -137,6 +137,14 @@ check_forbidden_additions() { # <patch> -f $(dirname $(readlink -f $0))/check-forbidden-tokens.awk \ "$1" || res=1 + # forbid new use of __rte_always_inline + awk -v FOLDERS="lib drivers app examples" \ + -v EXPRESSIONS='\\<__rte_always_inline\\>' \ + -v RET_ON_FAIL=1 \ + -v MESSAGE='Adding __rte_always_inline; prefer plain inline' \ + -f $(dirname $(readlink -f $0))/check-forbidden-tokens.awk \ + "$1" || res=1 + # refrain from using compiler __rte_atomic_thread_fence() # It should be avoided on x86 for SMP case. awk -v FOLDERS="lib drivers app examples" \
doc/guides/contributing/coding_style.rst +24 -1
@@ -747,11 +747,34 @@ Static Variables and Functions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * All functions and variables that are local to a file must be declared as ``static`` because it can often help the compiler to do some optimizations (such as, inlining the code). -* Functions that should be inlined should to be declared as ``static inline`` and can be defined in a .c or a .h file. +* Functions that should be inlined should be declared as ``static inline`` and can be defined in a .c or a .h file. .. note:: Static functions defined in a header file must be declared as ``static inline`` in order to prevent compiler warnings about the function being unused. +Use of ``__rte_always_inline`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``__rte_always_inline`` attribute forces the compiler to inline a function regardless of its size or call-graph heuristics. +Prefer plain ``inline`` (or no annotation at all for static functions) and let the compiler decide. +Modern compilers at ``-O2`` make good inlining decisions for small ``static inline`` functions in headers, +and forced inlining can hurt performance by inflating function bodies, increasing register pressure, and overriding profile-guided optimization. + +``__rte_always_inline`` should only be used when one of the following applies: + +* The function contains ``__builtin_constant_p`` checks that gate a constant-folded fast path, and the optimization is lost if the function is not inlined into the caller. + Examples include byte-order helpers and length-dispatched copy/compare routines. + +* The function wraps inline assembly or a compiler intrinsic whose correctness depends on being inlined into the caller's register context (for example, intrinsics requiring a compile-time constant argument). + +* Measurement on a representative workload shows that the annotation is required to retain performance, and the reason is documented in the commit message that introduces it. + +Each use must be justified at the point it is introduced. Adding ``__rte_always_inline`` because nearby code uses it is not a justification; +if the constant or intrinsic that requires inlining is several call levels up the call chain, +restructure the code rather than annotating the entire chain. + +The complementary attribute ``__rte_noinline`` is useful for explicitly marking cold paths (error handling, initialization, slow-path fallbacks) where outlining the function can reduce instruction-cache pressure on the hot path. + Const Attribute ~~~~~~~~~~~~~~~
Signature · 1 line
2.53.0
Quoted 8 lines
From: Stephen Hemminger [mailto:[email protected]]
Sent: Wednesday, 27 May 2026 18.38Modern compilers at -O2 make good inlining decisions for small static inline functions; forced inlining via
__rte_always_inlineshould be reserved for cases where it is required for correctness or for documented measured performance reasons.
Quoted 5 lines
Document the policy in the coding style guide and add a
checkpatches.shentry that warns when new uses of the attribute are introduced.Signed-off-by Stephen Hemminger <[email protected]>
Plenty of code in DPDK is based on ancient compiler behavior; let's not add new code based on old compiler behavior. I guess developers keep blindly adding __rte_always_inline, only because it's already everywhere.
Good initiative to stop that bad habit.
Slightly extreme forbidding it in checkpatches.sh, but it's probably the only way to force people to stop and think.
Quoted 63 lines
--- devtools/checkpatches.sh | 8 ++++++++ doc/guides/contributing/coding_style.rst | 25 +++++++++++++++++++++++- 2 files changed, 32 insertions(+), 1 deletion(-)devtools/checkpatches.sh +8
-0@@ -137,6 +137,14 @@ check_forbidden_additions() { # <patch> -f $(dirname $(readlink -f $0))/check-forbidden-tokens.awk \ "$1" || res=1 + # forbid new use of __rte_always_inline + awk -v FOLDERS="lib drivers app examples" \ + -v EXPRESSIONS='\\<__rte_always_inline\\>' \ + -v RET_ON_FAIL=1 \ + -v MESSAGE='Adding __rte_always_inline; prefer plain inline' \ + -f $(dirname $(readlink -f $0))/check-forbidden-tokens.awk \ + "$1" || res=1 +devtools/checkpatches.sh +0
-0# refrain from using compiler __rte_atomic_thread_fence() # It should be avoided on x86 for SMP case. awk -v FOLDERS="lib drivers app examples" \doc/guides/contributing/coding_style.rst +0
-0@@ -747,11 +747,34 @@ Static Variables and Functions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * All functions and variables that are local to a file must bedeclared as ``static`` because it can often help the compiler to do some optimizations (such as, inlining the code).
-* Functions that should be inlined should to be declared as ``static inline`` and can be defined in a .c or a .h file.
+* Functions that should be inlined should be declared as ``static inline`` and can be defined in a .c or a .h file... note::
Static functions defined in a header file must be declared as
``static inline`` in order to prevent compiler warnings about the function being unused.doc/guides/contributing/coding_style.rst +4
-0+Use of ``__rte_always_inline`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``__rte_always_inline`` attribute forces the compiler to inline afunction regardless of its size or call-graph heuristics. +Prefer plain ``inline`` (or no annotation at all for static functions) and let the compiler decide.
+Modern compilers at ``-O2`` make good inlining decisions for small ``static inline`` functions in headers,
+and forced inlining can hurt performance by inflating function bodies, increasing register pressure, and overriding profile-guided optimization.
+
+``__rte_always_inline`` should only be used when one of the following applies:
doc/guides/contributing/coding_style.rst
Quoted 2 lines
doc/guides/contributing/coding_style.rst +2
-0+ +* The function contains ``__builtin_constant_p`` checks that gate a
__builtin_constant_p -> __rte_constant
Quoted 14 lines
constant-folded fast path, and the optimization is lost if the function is not inlined into the caller.
+ Examples include byte-order helpers and length-dispatched copy/compare routines.doc/guides/contributing/coding_style.rst +2
-0+ +* The function wraps inline assembly or a compiler intrinsic whosecorrectness depends on being inlined into the caller's register context (for example, intrinsics requiring a compile-time constant argument).
doc/guides/contributing/coding_style.rst +2
-0+ +* Measurement on a representative workload shows that the annotationis required to retain performance, and the reason is documented in the commit message that introduces it.
doc/guides/contributing/coding_style.rst +2
-0+ +Each use must be justified at the point it is introduced. Adding
Quoted 5 lines
``__rte_always_inline`` because nearby code uses it is not a justification;
+if the constant or intrinsic that requires inlining is several call levels up the call chain,
+restructure the code rather than annotating the entire chain.
Please add something similar to the description of the macro in rte_common.h.
Quoted 5 lines
doc/guides/contributing/coding_style.rst +2
-0+ +The complementary attribute ``__rte_noinline`` is useful forexplicitly marking cold paths (error handling, initialization, slow- path fallbacks) where outlining the function can reduce instruction- cache pressure on the hot path.
Same comment:
Please add something similar to the description of the macro in rte_common.h.
<feature creep>
Many macros in rte_common.h have insufficient descriptions. </feature creep>
Quoted 6 lines
+
Const Attribute
~~~~~~~~~~~~~~~--
2.53.0
With comments above fixed,
PATCH v2 1/1 doc, eal, devtools: discourage new __rte_always_inline
In reply to Stephen HemmingerModern compilers at -O2 make good inlining decisions for small static inline functions; forced inlining via __rte_always_inline should be reserved for cases where it is required for correctness or for documented measured performance reasons.
Document the policy in the coding style guide and add a checkpatches.sh entry that flags when new uses of the attribute are introduced. Checkpatches is not an absolute blocker to acceptance, only an indicator that more review is needed.
Add additional comments about use of __rte_always_inline, __rte_noinline, __rte_hot, and __rte_cold to the rte_common.h to aid developers.
--- devtools/checkpatches.sh | 8 +++++ doc/guides/contributing/coding_style.rst | 26 ++++++++++++++++- lib/eal/include/rte_common.h | 37 ++++++++++++++++++++++-- 3 files changed, 68 insertions(+), 3 deletions(-)
devtools/checkpatches.sh +8 -0
@@ -137,6 +137,14 @@ check_forbidden_additions() { # <patch> -f $(dirname $(readlink -f $0))/check-forbidden-tokens.awk \ "$1" || res=1 + # forbid new use of __rte_always_inline + awk -v FOLDERS="lib drivers app examples" \ + -v EXPRESSIONS='\\<__rte_always_inline\\>' \ + -v RET_ON_FAIL=1 \ + -v MESSAGE='Adding __rte_always_inline; prefer plain inline' \ + -f $(dirname $(readlink -f $0))/check-forbidden-tokens.awk \ + "$1" || res=1 + # refrain from using compiler __rte_atomic_thread_fence() # It should be avoided on x86 for SMP case. awk -v FOLDERS="lib drivers app examples" \
doc/guides/contributing/coding_style.rst +25 -1
@@ -747,11 +747,35 @@ Static Variables and Functions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * All functions and variables that are local to a file must be declared as ``static`` because it can often help the compiler to do some optimizations (such as, inlining the code). -* Functions that should be inlined should to be declared as ``static inline`` and can be defined in a .c or a .h file. +* Functions that should be inlined should be declared as ``static inline`` and can be defined in a .c or a .h file. .. note:: Static functions defined in a header file must be declared as ``static inline`` in order to prevent compiler warnings about the function being unused. +Use of ``__rte_always_inline`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``__rte_always_inline`` attribute forces the compiler to inline a function regardless of its size or call-graph heuristics. +Prefer plain ``inline`` (or no annotation at all for static functions) and let the compiler decide. +Modern compilers at ``-O2`` make good inlining decisions for small ``static inline`` functions in headers, +and forced inlining can hurt performance by inflating function bodies, increasing register pressure, and overriding profile-guided optimization. + +``__rte_always_inline`` should only be used when one of the following applies: + +* The function contains ``__rte_constant()`` checks that gate a constant-folded fast path, + and the optimization is lost if the function is not inlined into the caller. + Examples include byte-order helpers and length-dispatched copy/compare routines. + +* The function wraps inline assembly or a compiler intrinsic whose correctness depends on being inlined into the caller's register context (for example, intrinsics requiring a compile-time constant argument). + +* Measurement on a representative workload shows that the annotation is required to retain performance, and the reason is documented in the commit message that introduces it. + +Each use must be justified at the point it is introduced. Adding ``__rte_always_inline`` because nearby code uses it is not a justification; +if the constant or intrinsic that requires inlining is several call levels up the call chain, +restructure the code rather than annotating the entire chain. + +The complementary attribute ``__rte_noinline`` is useful for explicitly marking cold paths (error handling, initialization, slow-path fallbacks) where outlining the function can reduce instruction-cache pressure on the hot path. + Const Attribute ~~~~~~~~~~~~~~~
lib/eal/include/rte_common.h +35 -2
@@ -482,7 +482,22 @@ static void __attribute__((destructor(RTE_PRIO(prio)), used)) func(void)#endif /** -* Force a function to be inlined +* Force a function to be inlined, regardless of the compiler's size and +* call-graph heuristics. +* +* Prefer plain @c inline (or no annotation on a static function) and let the compiler decide. +* Modern compilers at -O2 inline small static functions well, +* and forcing it can hurt by inflating call sites, raising register pressure, +* and overriding profile-guided optimization. +* +* Reserve this attribute for cases where inlining is required for +* correctness, or for a documented and measured performance reason, e.g. +* - a constant-folded fast path gated by @c __rte_constant() that is lost +* unless the function is inlined into the caller; +* - a wrapper around inline asm or an intrinsic that needs a +* compile-time-constant argument from the caller's context. +* +* See the DPDK coding style guide for the full policy. */ #ifdef RTE_TOOLCHAIN_MSVC #define __rte_always_inline __forceinline
@@ -491,7 +506,11 @@ static void __attribute__((destructor(RTE_PRIO(prio)), used)) func(void)#endif /** -* Force a function to be noinlined +* Force a function not to be inlined. +* +* Useful for explicitly outlining cold paths such as error handling, +* initialization, slow-path fallbacks, so they do not bloat the hot path +* or add to its instruction-cache footprint. */ #ifdef RTE_TOOLCHAIN_MSVC #define __rte_noinline __declspec(noinline)
@@ -501,6 +520,12 @@ static void __attribute__((destructor(RTE_PRIO(prio)), used)) func(void)/** * Hint function in the hot path +* +* The compiler may optimize the function more aggressively, treat calls +* to it as likely for branch prediction, and group it with other hot +* functions to improve instruction-cache locality. This affects code +* placement and prediction, not inlining; combine with an inline +* annotation if both are wanted. */ #ifdef RTE_TOOLCHAIN_MSVC #define __rte_hot
@@ -510,6 +535,14 @@ static void __attribute__((destructor(RTE_PRIO(prio)), used)) func(void)/** * Hint function in the cold path +* +* The compiler optimizes the function for size rather than speed, +* marks branches that reach it as unlikely, and may move it to a separate +* section to keep it off the hot path and reduce instruction-cache +* pressure there. +* +* Suitable for error handling, logging, and setup/teardown code. +* Functions marked @c __rte_noreturn are already treated as cold. */ #ifdef RTE_TOOLCHAIN_MSVC #define __rte_cold
Signature · 1 line
2.53.0
RE: [PATCH v2] doc, eal, devtools: discourage new __rte_always_inline
Quoted 13 lines
From: Stephen Hemminger [mailto:[email protected]]
Sent: Monday, 1 June 2026 19.21Modern compilers at -O2 make good inlining decisions for small static inline functions; forced inlining via
__rte_always_inlineshould be reserved for cases where it is required for correctness or for documented measured performance reasons.Document the policy in the coding style guide and add a
checkpatches.shentry that flags when new uses of the attribute are introduced. Checkpatches is not an absolute blocker to acceptance, only an indicator that more review is needed.
Quoted 6 lines
Add additional comments about use of
__rte_always_inline,__rte_noinline,__rte_hot, and__rte_coldto therte_common.hto aid developers.Signed-off-by Stephen Hemminger <[email protected]>---
RE: [PATCH v2] doc, eal, devtools: discourage new __rte_always_inline
In reply to Stephen HemmingerQuoted 176 lines
Modern compilers at -O2 make good inlining decisions for small static inline functions; forced inlining via
__rte_always_inlineshould be reserved for cases where it is required for correctness or for documented measured performance reasons.Document the policy in the coding style guide and add a
checkpatches.shentry that flags when new uses of the attribute are introduced. Checkpatches is not an absolute blocker to acceptance, only an indicator that more review is needed.Add additional comments about use of
__rte_always_inline,__rte_noinline,__rte_hot, and__rte_coldto therte_common.hto aid developers.Signed-off-by Stephen Hemminger <[email protected]>--- devtools/checkpatches.sh | 8 +++++ doc/guides/contributing/coding_style.rst | 26 ++++++++++++++++- lib/eal/include/rte_common.h | 37 ++++++++++++++++++++++-- 3 files changed, 68 insertions(+), 3 deletions(-)devtools/checkpatches.sh +8
-0@@ -137,6 +137,14 @@ check_forbidden_additions() { # <patch> -f $(dirname $(readlink -f $0))/check-forbidden-tokens.awk \ "$1" || res=1 + # forbid new use of __rte_always_inline + awk -v FOLDERS="lib drivers app examples" \ + -v EXPRESSIONS='\\<__rte_always_inline\\>' \ + -v RET_ON_FAIL=1 \ + -v MESSAGE='Adding __rte_always_inline; prefer plain inline' \ + -f $(dirname $(readlink -f $0))/check-forbidden-tokens.awk \ + "$1" || res=1 + # refrain from using compiler __rte_atomic_thread_fence() # It should be avoided on x86 for SMP case. awk -v FOLDERS="lib drivers app examples" \doc/guides/contributing/coding_style.rst +0
-0@@ -747,11 +747,35 @@ Static Variables and Functions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * All functions and variables that are local to a file must be declared as ``static``because it can often help the compiler to do some optimizations (such as, inlining the code).
-* Functions that should be inlined should to be declared as ``static inline`` and can be defined in a .c or a .h file.
+* Functions that should be inlined should be declared as ``static inline`` and can be defined in a .c or a .h file... note::
Static functions defined in a header file must be declared as ``static
inline`` in order to prevent compiler warnings about the function being unused.doc/guides/contributing/coding_style.rst +4
-0+Use of ``__rte_always_inline`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``__rte_always_inline`` attribute forces the compiler to inline a functionregardless of its size or call-graph heuristics.
+Prefer plain ``inline`` (or no annotation at all for static functions) and let the compiler decide.
+Modern compilers at ``-O2`` make good inlining decisions for small ``static inline`` functions in headers,
+and forced inlining can hurt performance by inflating function bodies, increasing register pressure, and overriding profile-guided optimization.doc/guides/contributing/coding_style.rst +4
-0+ +``__rte_always_inline`` should only be used when one of the following applies: + +* The function contains ``__rte_constant()`` checks that gate a constant-foldedfast path,
doc/guides/contributing/coding_style.rst +2
-0+ and the optimization is lost if the function is not inlined into the caller. + Examples include byte-order helpers and length-dispatched copy/compareroutines.
doc/guides/contributing/coding_style.rst +2
-0+ +* The function wraps inline assembly or a compiler intrinsic whose correctnessdepends on being inlined into the caller's register context (for example, intrinsics requiring a compile-time constant argument).
doc/guides/contributing/coding_style.rst +2
-0+ +* Measurement on a representative workload shows that the annotation isrequired to retain performance, and the reason is documented in the commit message that introduces it.
doc/guides/contributing/coding_style.rst +2
-0+ +Each use must be justified at the point it is introduced. Adding``__rte_always_inline`` because nearby code uses it is not a justification; +if the constant or intrinsic that requires inlining is several call levels up the call chain,
doc/guides/contributing/coding_style.rst +3
-0+restructure the code rather than annotating the entire chain. + +The complementary attribute ``__rte_noinline`` is useful for explicitly markingcold paths (error handling, initialization, slow-path fallbacks) where outlining the function can reduce instruction-cache pressure on the hot path.
doc/guides/contributing/coding_style.rst +1
-0+ Const Attribute ~~~~~~~~~~~~~~~lib/eal/include/rte_common.h +4
-1@@ -482,7 +482,22 @@ static void __attribute__((destructor(RTE_PRIO(prio)), used)) func(void)#endif /** -* Force a function to be inlined +* Force a function to be inlined, regardless of the compiler's size and +* call-graph heuristics. +* +* Prefer plain @c inline (or no annotation on a static function) and let the compiler decide.
+ * Modern compilers at -O2 inline small static functions well,
+ * and forcing it can hurt by inflating call sites, raising register pressure,
+ * and overriding profile-guided optimization.
+ *
+ * Reserve this attribute for cases where inlining is required for
+ * correctness, or for a documented and measured performance reason, e.g.
+ * - a constant-folded fast path gated by @c__rte_constant()that is lost
+ * unless the function is inlined into the caller;
+ * - a wrapper around inline asm or an intrinsic that needs a
+ * compile-time-constant argument from the caller's context.
+ *
+ * See the DPDK coding style guide for the full policy.
*/
#ifdefRTE_TOOLCHAIN_MSVC
#define__rte_always_inline__forceinlinelib/eal/include/rte_common.h +5
-1@@ -491,7 +506,11 @@ static void __attribute__((destructor(RTE_PRIO(prio)), used)) func(void)#endif /** -* Force a function to be noinlined +* Force a function not to be inlined. +* +* Useful for explicitly outlining cold paths such as error handling, +* initialization, slow-path fallbacks, so they do not bloat the hot path +* or add to its instruction-cache footprint. */ #ifdef RTE_TOOLCHAIN_MSVC #define
__rte_noinline__declspec(noinline)lib/eal/include/rte_common.h +6
-0@@ -501,6 +520,12 @@ static void __attribute__((destructor(RTE_PRIO(prio)), used)) func(void)/** * Hint function in the hot path +* +* The compiler may optimize the function more aggressively, treat calls +* to it as likely for branch prediction, and group it with other hot +* functions to improve instruction-cache locality. This affects code +* placement and prediction, not inlining; combine with an inline +* annotation if both are wanted. */#ifdef RTE_TOOLCHAIN_MSVC #define
__rte_hotlib/eal/include/rte_common.h +8
-0@@ -510,6 +535,14 @@ static void __attribute__((destructor(RTE_PRIO(prio)), used)) func(void)/** * Hint function in the cold path +* +* The compiler optimizes the function for size rather than speed, +* marks branches that reach it as unlikely, and may move it to a separate +* section to keep it off the hot path and reduce instruction-cache +* pressure there. +* +* Suitable for error handling, logging, and setup/teardown code. +* Functions marked @c __rte_noreturn are already treated as cold. */#ifdef RTE_TOOLCHAIN_MSVC
Quoted 2 lines
#define
__rte_cold
--
Quoted 1 line
2.53.0
Re: [PATCH v2] doc, eal, devtools: discourage new __rte_always_inline
In reply to Stephen Hemminger01/06/2026 19:21, Stephen Hemminger:
Quoted 10 lines
Modern compilers at -O2 make good inlining decisions for small static inline functions; forced inlining via
__rte_always_inlineshould be reserved for cases where it is required for correctness or for documented measured performance reasons.Document the policy in the coding style guide and add a
checkpatches.shentry that flags when new uses of the attribute are introduced. Checkpatches is not an absolute blocker to acceptance, only an indicator that more review is needed.
Quoted 5 lines
Add additional comments about use of
__rte_always_inline,__rte_noinline,__rte_hot, and__rte_coldto therte_common.hto aid developers.Signed-off-by Stephen Hemminger <[email protected]>
Applied, thanks.