DPDK 26.11.0-rc2
Macros | Typedefs | Functions | Variables
rte_common.h File Reference
#include <assert.h>
#include <limits.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdalign.h>
#include <rte_compat.h>
#include <rte_config.h>
#include <rte_os.h>

Go to the source code of this file.

Macros

#define __rte_aligned(a)   __attribute__((__aligned__(a)))
 
#define __rte_packed_begin
 
#define __rte_may_alias   __attribute__((__may_alias__))
 
#define RTE_DEPRECATED(x)
 
#define __rte_diagnostic_push   _Pragma("GCC diagnostic push")
 
#define __rte_diagnostic_ignored_wcast_qual   _Pragma("GCC diagnostic ignored \"-Wcast-qual\"")
 
#define __rte_diagnostic_ignored_array_bounds    _Pragma("GCC diagnostic ignored \"-Warray-bounds\"")
 
#define __rte_weak   RTE_DEPRECATED(__rte_weak) __attribute__((__weak__))
 
#define __rte_pure   __attribute__((pure))
 
#define __rte_used   __attribute__((used))
 
#define __rte_unused   __attribute__((__unused__))
 
#define __rte_restrict   __restrict
 
#define RTE_SET_USED(x)   (void)(x)
 
#define __rte_format_printf(format_index, first_arg)    __attribute__((format(printf, format_index, first_arg)))
 
#define __rte_section(name)    __attribute__((section(name)))
 
#define __rte_alloc_size(...)
 
#define __rte_alloc_align(argno)
 
#define __rte_malloc
 
#define __rte_dealloc(dealloc, argno)
 
#define RTE_INIT_PRIO(func, prio)   static void __attribute__((constructor(RTE_PRIO(prio)), used)) func(void)
 
#define RTE_INIT(func)    RTE_INIT_PRIO(func, LAST)
 
#define RTE_FINI_PRIO(func, prio)   static void __attribute__((destructor(RTE_PRIO(prio)), used)) func(void)
 
#define RTE_FINI(func)    RTE_FINI_PRIO(func, LAST)
 
#define __rte_noreturn   __attribute__((noreturn))
 
#define __rte_unreachable()   __assume(0)
 
#define __rte_warn_unused_result   __attribute__((warn_unused_result))
 
#define __rte_always_inline   inline __attribute__((always_inline))
 
#define __rte_noinline   __attribute__((noinline))
 
#define __rte_hot   __attribute__((hot))
 
#define __rte_cold   __attribute__((cold))
 
#define __rte_assume(condition)   __assume(condition)
 
#define __rte_no_asan
 
#define RTE_PTR_ADD(ptr, x)
 
#define RTE_PTR_SUB(ptr, x)
 
#define RTE_PTR_DIFF(ptr1, ptr2)   ((uintptr_t)(ptr1) - (uintptr_t)(ptr2))
 
#define RTE_PTR_UNQUAL(X)   ((void *)(uintptr_t)(X))
 
#define RTE_CAST_PTR(type, ptr)   ((type)(uintptr_t)(ptr))
 
#define RTE_CAST_FIELD(var, field, type)    (*(type *)((uintptr_t)(var) + offsetof(typeof(*(var)), field)))
 
#define RTE_PTR_ALIGN_FLOOR(ptr, align)    ((typeof(ptr))RTE_ALIGN_FLOOR((uintptr_t) ((ptr) __rte_ptr_arith_add_zero), align))
 
#define RTE_ALIGN_FLOOR(val, align)    (typeof(val))((val) & (~((typeof(val))((align) - 1))))
 
#define RTE_PTR_ALIGN_CEIL(ptr, align)    RTE_PTR_ALIGN_FLOOR((typeof(ptr))RTE_PTR_ADD(ptr, (align) - 1), align)
 
#define RTE_ALIGN_CEIL(val, align)    RTE_ALIGN_FLOOR(((val) + ((typeof(val)) (align) - 1)), align)
 
#define RTE_PTR_ALIGN(ptr, align)   RTE_PTR_ALIGN_CEIL(ptr, align)
 
#define RTE_ALIGN(val, align)   RTE_ALIGN_CEIL(val, align)
 
#define RTE_ALIGN_MUL_CEIL(v, mul)    ((((v) + (typeof(v))(mul) - 1) / ((typeof(v))(mul))) * (typeof(v))(mul))
 
#define RTE_ALIGN_MUL_FLOOR(v, mul)    (((v) / ((typeof(v))(mul))) * (typeof(v))(mul))
 
#define RTE_ALIGN_MUL_NEAR(v, mul)
 
#define RTE_DIV_ROUND_UP(n, d)   (((n) + (d) - 1) / (d))
 
#define RTE_BUILD_BUG_ON(condition)   do { static_assert(!(condition), #condition); } while (0)
 
#define RTE_CACHE_LINE_MASK   (RTE_CACHE_LINE_SIZE-1)
 
#define RTE_CACHE_LINE_ROUNDUP(size)   RTE_ALIGN_CEIL(size, RTE_CACHE_LINE_SIZE)
 
#define RTE_CACHE_LINE_MIN_SIZE   64
 
#define __rte_cache_aligned   __rte_aligned(RTE_CACHE_LINE_SIZE)
 
#define __rte_cache_min_aligned   __rte_aligned(RTE_CACHE_LINE_MIN_SIZE)
 
#define RTE_CACHE_GUARD   _RTE_CACHE_GUARD_HELPER1(__LINE__)
 
#define RTE_MIN(a, b)
 
#define RTE_MIN3(a, b, c)
 
#define RTE_MIN_T(a, b, t)    ((t)(a) < (t)(b) ? (t)(a) : (t)(b))
 
#define RTE_MAX(a, b)
 
#define RTE_MAX3(a, b, c)
 
#define RTE_MAX_T(a, b, t)    ((t)(a) > (t)(b) ? (t)(a) : (t)(b))
 
#define offsetof(TYPE, MEMBER)   __builtin_offsetof (TYPE, MEMBER)
 
#define container_of(ptr, type, member)
 
#define RTE_SWAP(a, b)
 
#define RTE_SIZEOF_FIELD(type, field)   (sizeof(((type *)0)->field))
 
#define RTE_STR(x)   _RTE_STR(x)
 
#define _RTE_CONCAT2(a, b)   a ## b
 
#define RTE_FMT(fmt, ...)   fmt "%.0s", __VA_ARGS__ ""
 
#define RTE_LEN2MASK(ln, tp)    ((tp)((uint64_t)-1 >> (sizeof(uint64_t) * CHAR_BIT - (ln))))
 
#define RTE_DIM(a)   (sizeof (a) / sizeof ((a)[0]))
 

Typedefs

typedef uint64_t unaligned_uint64_t __rte_aligned(1)
 
typedef uint64_t phys_addr_t
 
typedef uint64_t rte_iova_t
 

Functions

static int rte_is_aligned (const void *const __rte_restrict ptr, const unsigned int align)
 
uint64_t rte_str_to_size (const char *str)
 
__rte_experimental char * rte_size_to_str (char *buf, int buf_size, uint64_t count, bool use_iec, const char *unit)
 
__rte_noreturn void rte_exit (int exit_code, const char *format,...) __rte_format_printf(2
 

Variables

__extension__ typedef void * RTE_MARKER [0]
 
__extension__ typedef uint8_t RTE_MARKER8 [0]
 
__extension__ typedef uint16_t RTE_MARKER16 [0]
 
__extension__ typedef uint32_t RTE_MARKER32 [0]
 
__extension__ typedef uint64_t RTE_MARKER64 [0]
 

Detailed Description

Generic, commonly-used macro and inline function definitions for DPDK.

Definition in file rte_common.h.

Macro Definition Documentation

◆ __rte_aligned

#define __rte_aligned (   a)    __attribute__((__aligned__(a)))

Force type alignment

This macro should be used when alignment of a struct or union type is required. For toolchain compatibility it should appear between the {struct,union} keyword and tag. e.g.

struct __rte_aligned(8) tag { ... };

If alignment of an object/variable is required then this macro should not be used, instead prefer C11 alignas(a).

Examples
examples/multi_process/symmetric_mp/main.c.

Definition at line 149 of file rte_common.h.

◆ __rte_packed_begin

#define __rte_packed_begin

Force a structure to be packed Usage: struct __rte_packed_begin mystruct { ... } __rte_packed_end; union __rte_packed_begin myunion { ... } __rte_packed_end; Note: alignment attributes when present should precede __rte_packed_begin.

Examples
examples/l3fwd-power/main.c, and examples/ptpclient/ptpclient.c.

Definition at line 176 of file rte_common.h.

◆ __rte_may_alias

#define __rte_may_alias   __attribute__((__may_alias__))

Macro to mark a type that is not subject to type-based aliasing rules

Definition at line 186 of file rte_common.h.

◆ RTE_DEPRECATED

#define RTE_DEPRECATED (   x)

Macro to mark macros and defines scheduled for removal

Definition at line 206 of file rte_common.h.

◆ __rte_diagnostic_push

#define __rte_diagnostic_push   _Pragma("GCC diagnostic push")

Macros to cause the compiler to remember the state of the diagnostics as of each push, and restore to that point at each pop.

Definition at line 214 of file rte_common.h.

◆ __rte_diagnostic_ignored_wcast_qual

#define __rte_diagnostic_ignored_wcast_qual   _Pragma("GCC diagnostic ignored \"-Wcast-qual\"")

Macro to disable compiler warnings about removing a type qualifier from the target type.

Definition at line 226 of file rte_common.h.

◆ __rte_diagnostic_ignored_array_bounds

#define __rte_diagnostic_ignored_array_bounds    _Pragma("GCC diagnostic ignored \"-Warray-bounds\"")

Macro to disable compiler warnings about invalid array bounds access.

Definition at line 235 of file rte_common.h.

◆ __rte_weak

#define __rte_weak   RTE_DEPRECATED(__rte_weak) __attribute__((__weak__))

Mark a function or variable to a weak reference.

Definition at line 247 of file rte_common.h.

◆ __rte_pure

#define __rte_pure   __attribute__((pure))

Mark a function to be pure.

Definition at line 256 of file rte_common.h.

◆ __rte_used

#define __rte_used   __attribute__((used))

Force symbol to be generated even if it appears to be unused.

Definition at line 265 of file rte_common.h.

◆ __rte_unused

#define __rte_unused   __attribute__((__unused__))

short definition to mark a function parameter unused

Examples
examples/bond/main.c, examples/cmdline/commands.c, examples/cmdline/parse_obj_list.c, examples/distributor/main.c, examples/ethtool/ethtool-app/ethapp.c, examples/ethtool/ethtool-app/main.c, examples/ethtool/lib/rte_ethtool.c, examples/eventdev_pipeline/main.c, examples/fips_validation/fips_validation_aes.c, examples/fips_validation/fips_validation_ccm.c, examples/fips_validation/fips_validation_cmac.c, examples/fips_validation/fips_validation_gcm.c, examples/fips_validation/fips_validation_hmac.c, examples/fips_validation/fips_validation_sha.c, examples/fips_validation/fips_validation_tdes.c, examples/fips_validation/fips_validation_xts.c, examples/flow_filtering/snippets/snippet_match_gre.c, examples/flow_filtering/snippets/snippet_match_integrity_flags.c, examples/flow_filtering/snippets/snippet_match_ipv4.c, examples/flow_filtering/snippets/snippet_match_mpls.c, examples/flow_filtering/snippets/snippet_match_nsh.c, examples/flow_filtering/snippets/snippet_match_packet_type.c, examples/flow_filtering/snippets/snippet_match_port_affinity.c, examples/flow_filtering/snippets/snippet_match_roce_ib_bth.c, examples/flow_filtering/snippets/snippet_match_vxlan_gbp.c, examples/flow_filtering/snippets/snippet_modify_ecn.c, examples/flow_filtering/snippets/snippet_random_match.c, examples/flow_filtering/snippets/snippet_re_route_to_kernel.c, examples/flow_filtering/snippets/snippet_switch_granularity.c, examples/helloworld/main.c, examples/ip_fragmentation/main.c, examples/ip_reassembly/main.c, examples/ipsec-secgw/ipsec-secgw.c, examples/ipsec-secgw/ipsec_worker.c, examples/ipsec-secgw/parser.c, examples/ipv4_multicast/main.c, examples/l2fwd-event/l2fwd_common.c, examples/l2fwd-jobstats/main.c, examples/l2fwd-keepalive/main.c, examples/l2fwd-keepalive/shm.c, examples/l2fwd-macsec/main.c, examples/l2fwd/main.c, examples/l3fwd-power/main.c, examples/l3fwd/l3fwd_acl.c, examples/l3fwd/l3fwd_em.c, examples/l3fwd/l3fwd_event.c, examples/l3fwd/l3fwd_fib.c, examples/l3fwd/l3fwd_lpm.c, examples/l3fwd/main.c, examples/link_status_interrupt/main.c, examples/multi_process/client_server_mp/mp_server/main.c, examples/multi_process/hotplug_mp/commands.c, examples/multi_process/simple_mp/main.c, examples/multi_process/simple_mp/mp_commands.c, examples/multi_process/symmetric_mp/main.c, examples/ntb/ntb_fwd.c, examples/packet_ordering/main.c, examples/pipeline/cli.c, examples/pipeline/thread.c, examples/ptp_tap_relay_sw/ptp_tap_relay_sw.c, examples/qos_meter/main.c, examples/qos_sched/cmdline.c, examples/qos_sched/main.c, examples/rxtx_callbacks/main.c, examples/server_node_efd/efd_server/main.c, examples/timer/main.c, examples/vdpa/main.c, examples/vhost/main.c, examples/vhost_blk/blk.c, examples/vhost_blk/vhost_blk.c, examples/vm_power_manager/channel_manager.c, examples/vm_power_manager/channel_monitor.c, examples/vm_power_manager/guest_cli/vm_power_cli_guest.c, examples/vm_power_manager/main.c, examples/vm_power_manager/oob_monitor_nop.c, examples/vm_power_manager/vm_power_cli.c, examples/vmdq/main.c, and examples/vmdq_dcb/main.c.

Definition at line 276 of file rte_common.h.

◆ __rte_restrict

#define __rte_restrict   __restrict

Mark pointer as restricted with regard to pointer aliasing.

Definition at line 283 of file rte_common.h.

◆ RTE_SET_USED

#define RTE_SET_USED (   x)    (void)(x)

◆ __rte_format_printf

#define __rte_format_printf (   format_index,
  first_arg 
)     __attribute__((format(printf, format_index, first_arg)))

Check format string and its arguments at compile-time.

GCC on Windows assumes MS-specific format string by default, even if the underlying stdio implementation is ANSI-compliant, so this must be overridden.

Definition at line 308 of file rte_common.h.

◆ __rte_section

#define __rte_section (   name)     __attribute__((section(name)))

Specify data or function section/segment.

Definition at line 320 of file rte_common.h.

◆ __rte_alloc_size

#define __rte_alloc_size (   ...)

Tells compiler that the function returns a value that points to memory, where the size is given by the one or two arguments. Used by compiler to validate object size.

Definition at line 333 of file rte_common.h.

◆ __rte_alloc_align

#define __rte_alloc_align (   argno)

Tells the compiler that the function returns a value that points to memory aligned by a function argument.

Note: not enabled on Clang because it warns if align argument is zero.

Definition at line 346 of file rte_common.h.

◆ __rte_malloc

#define __rte_malloc

Tells the compiler this is a function like malloc and that the pointer returned cannot alias any other pointer (ie new memory).

Definition at line 356 of file rte_common.h.

◆ __rte_dealloc

#define __rte_dealloc (   dealloc,
  argno 
)

With recent GCC versions also able to track that proper deallocator function is used for this pointer.

Definition at line 367 of file rte_common.h.

◆ RTE_INIT_PRIO

#define RTE_INIT_PRIO (   func,
  prio 
)    static void __attribute__((constructor(RTE_PRIO(prio)), used)) func(void)

Run function before main() with high priority.

Parameters
funcConstructor function.
prioPriority number must be above 100. Lowest number is the first to run.

Definition at line 389 of file rte_common.h.

◆ RTE_INIT

#define RTE_INIT (   func)     RTE_INIT_PRIO(func, LAST)

Run function before main() with low priority.

The constructor will be run after prioritized constructors.

Parameters
funcConstructor function.

Definition at line 421 of file rte_common.h.

◆ RTE_FINI_PRIO

#define RTE_FINI_PRIO (   func,
  prio 
)    static void __attribute__((destructor(RTE_PRIO(prio)), used)) func(void)

Run after main() with low priority.

Parameters
funcDestructor function name.
prioPriority number must be above 100. Lowest number is the last to run.

Definition at line 435 of file rte_common.h.

◆ RTE_FINI

#define RTE_FINI (   func)     RTE_FINI_PRIO(func, LAST)

Run after main() with high priority.

The destructor will be run before prioritized destructors.

Parameters
funcDestructor function name.

Definition at line 462 of file rte_common.h.

◆ __rte_noreturn

#define __rte_noreturn   __attribute__((noreturn))

◆ __rte_unreachable

#define __rte_unreachable ( )    __assume(0)

Hint point in program never reached

Definition at line 480 of file rte_common.h.

◆ __rte_warn_unused_result

#define __rte_warn_unused_result   __attribute__((warn_unused_result))

Issue a warning in case the function's return value is ignored.

The use of this attribute should be restricted to cases where ignoring the marked function's return value is almost always a bug. With GCC, some effort is required to make clear that ignoring the return value is intentional. The usual void-casting method to mark something unused as used does not suppress the warning with this compiler.

void ignore_foo_result(void) {
foo(); // generates a warning with all compilers
(void)foo(); // still generates the warning with GCC (but not clang)
int unused __rte_unused;
unused = foo(); // does the trick with all compilers
}
#define __rte_unused
Definition: rte_common.h:276
#define __rte_warn_unused_result
Definition: rte_common.h:509

Definition at line 509 of file rte_common.h.

◆ __rte_always_inline

#define __rte_always_inline   inline __attribute__((always_inline))

Force a function to be inlined, regardless of the compiler's size and call-graph heuristics.

Prefer plain 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 __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.

Examples
examples/eventdev_pipeline/pipeline_worker_generic.c, examples/eventdev_pipeline/pipeline_worker_tx.c, examples/ipsec-secgw/ipsec_worker.c, examples/l2fwd-event/l2fwd_event.c, examples/l3fwd/l3fwd_em.c, examples/l3fwd/l3fwd_fib.c, examples/l3fwd/l3fwd_lpm.c, examples/packet_ordering/main.c, examples/vhost/main.c, and examples/vhost/virtio_net.c.

Definition at line 534 of file rte_common.h.

◆ __rte_noinline

#define __rte_noinline   __attribute__((noinline))

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.

Examples
examples/l2fwd-event/l2fwd_event.c, examples/l3fwd/l3fwd_em.c, examples/l3fwd/l3fwd_fib.c, examples/l3fwd/l3fwd_lpm.c, and examples/packet_ordering/main.c.

Definition at line 547 of file rte_common.h.

◆ __rte_hot

#define __rte_hot   __attribute__((hot))

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.

Definition at line 562 of file rte_common.h.

◆ __rte_cold

#define __rte_cold   __attribute__((cold))

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 __rte_noreturn are already treated as cold.

Definition at line 579 of file rte_common.h.

◆ __rte_assume

#define __rte_assume (   condition)    __assume(condition)

Hint precondition

Warning
Depending on the compiler, any code in condition might be executed. This currently only occurs with GCC prior to version 13.

Definition at line 595 of file rte_common.h.

◆ __rte_no_asan

#define __rte_no_asan

Disable AddressSanitizer on some code

Definition at line 608 of file rte_common.h.

◆ RTE_PTR_ADD

#define RTE_PTR_ADD (   ptr,
  x 
)
Value:
(1 ? (void *)((char *)((ptr) __rte_ptr_arith_add_zero) + (x)) : \
((ptr) __rte_ptr_arith_add_zero))

Add a byte-value offset to a pointer.

Parameters
ptrThe pointer (must be non-NULL).
xByte offset to add.
Returns
void* (or const void* / volatile void* / const volatile void* preserving qualifiers). Returning void* prevents the compiler from making alignment assumptions based on the pointer type, which is important when doing byte-offset arithmetic that may cross struct boundaries or result in unaligned pointers.
Examples
examples/ipsec-secgw/esp.c, and examples/ipsec-secgw/ipsec_worker.c.

Definition at line 643 of file rte_common.h.

◆ RTE_PTR_SUB

#define RTE_PTR_SUB (   ptr,
  x 
)
Value:
(1 ? (void *)((char *)((ptr) __rte_ptr_arith_add_zero) - (x)) : \
((ptr) __rte_ptr_arith_add_zero))

Subtract a byte-value offset from a pointer.

Parameters
ptrThe pointer (must be non-NULL).
xByte offset to subtract.
Returns
void* (or const void* / volatile void* / const volatile void* preserving qualifiers). Returning void* prevents the compiler from making alignment assumptions based on the pointer type, which is important when doing byte-offset arithmetic that may cross struct boundaries or result in unaligned pointers.

Definition at line 678 of file rte_common.h.

◆ RTE_PTR_DIFF

#define RTE_PTR_DIFF (   ptr1,
  ptr2 
)    ((uintptr_t)(ptr1) - (uintptr_t)(ptr2))

get the difference between two pointer values, i.e. how far apart in bytes are the locations they point two. It is assumed that ptr1 is greater than ptr2.

Examples
examples/ipsec-secgw/sa.c, examples/ipsec-secgw/sp4.c, and examples/ipsec-secgw/sp6.c.

Definition at line 688 of file rte_common.h.

◆ RTE_PTR_UNQUAL

#define RTE_PTR_UNQUAL (   X)    ((void *)(uintptr_t)(X))

Macro to discard qualifiers (such as const, volatile, restrict) from a pointer, without the compiler emitting a warning.

Definition at line 696 of file rte_common.h.

◆ RTE_CAST_PTR

#define RTE_CAST_PTR (   type,
  ptr 
)    ((type)(uintptr_t)(ptr))

Macro to cast a pointer to a specific type, without the compiler emitting a warning about discarding qualifiers.

Warning
When casting a pointer to point to a larger type, the resulting pointer may be misaligned, which results in undefined behavior. E.g.:

struct s { uint16_t a; uint8_t b; uint8_t c; uint8_t d; } v; uint16_t * p = RTE_CAST_PTR(uint16_t *, &v.c); // "p" is not 16 bit aligned!

Definition at line 715 of file rte_common.h.

◆ RTE_CAST_FIELD

#define RTE_CAST_FIELD (   var,
  field,
  type 
)     (*(type *)((uintptr_t)(var) + offsetof(typeof(*(var)), field)))

Workaround to cast a const field of a structure to non-const type.

Definition at line 720 of file rte_common.h.

◆ RTE_PTR_ALIGN_FLOOR

#define RTE_PTR_ALIGN_FLOOR (   ptr,
  align 
)     ((typeof(ptr))RTE_ALIGN_FLOOR((uintptr_t) ((ptr) __rte_ptr_arith_add_zero), align))

Macro to align a pointer to a given power-of-two.

Aligns the pointer down to the specified alignment boundary.

Parameters
ptrThe pointer (must be non-NULL).
alignAlignment boundary (must be a power-of-two value).
Returns
Aligned pointer of the same type as ptr, pointing to an address no higher than ptr. Returns pointer of same type as input, preserving const/volatile qualifiers. Since alignment operations guarantee proper alignment, the return type matches the input type.

Definition at line 759 of file rte_common.h.

◆ RTE_ALIGN_FLOOR

#define RTE_ALIGN_FLOOR (   val,
  align 
)     (typeof(val))((val) & (~((typeof(val))((align) - 1))))

Macro to align a value to a given power-of-two. The resultant value will be of the same type as the first parameter, and will be no bigger than the first parameter. Second parameter must be a power-of-two value.

Examples
examples/l3fwd/l3fwd_fib.c.

Definition at line 769 of file rte_common.h.

◆ RTE_PTR_ALIGN_CEIL

#define RTE_PTR_ALIGN_CEIL (   ptr,
  align 
)     RTE_PTR_ALIGN_FLOOR((typeof(ptr))RTE_PTR_ADD(ptr, (align) - 1), align)

Macro to align a pointer to a given power-of-two.

Aligns the pointer up to the specified alignment boundary.

Parameters
ptrThe pointer (must be non-NULL).
alignAlignment boundary (must be a power-of-two value).
Returns
Aligned pointer of the same type as ptr, pointing to an address no lower than ptr. Returns pointer of same type as input, preserving const/volatile qualifiers. Since alignment operations guarantee proper alignment, the return type matches the input type.

Definition at line 808 of file rte_common.h.

◆ RTE_ALIGN_CEIL

#define RTE_ALIGN_CEIL (   val,
  align 
)     RTE_ALIGN_FLOOR(((val) + ((typeof(val)) (align) - 1)), align)

Macro to align a value to a given power-of-two. The resultant value will be of the same type as the first parameter, and will be no lower than the first parameter. Second parameter must be a power-of-two value.

Examples
examples/bbdev_app/main.c, examples/fips_validation/fips_dev_self_test.c, and examples/ipsec-secgw/esp.c.

Definition at line 818 of file rte_common.h.

◆ RTE_PTR_ALIGN

#define RTE_PTR_ALIGN (   ptr,
  align 
)    RTE_PTR_ALIGN_CEIL(ptr, align)

Macro to align a pointer to a given power-of-two. The resultant pointer will be a pointer of the same type as the first parameter, and point to an address no lower than the first parameter. Second parameter must be a power-of-two value. This function is the same as RTE_PTR_ALIGN_CEIL

Definition at line 828 of file rte_common.h.

◆ RTE_ALIGN

#define RTE_ALIGN (   val,
  align 
)    RTE_ALIGN_CEIL(val, align)

Macro to align a value to a given power-of-two. The resultant value will be of the same type as the first parameter, and will be no lower than the first parameter. Second parameter must be a power-of-two value. This function is the same as RTE_ALIGN_CEIL

Examples
examples/l2fwd-crypto/main.c.

Definition at line 837 of file rte_common.h.

◆ RTE_ALIGN_MUL_CEIL

#define RTE_ALIGN_MUL_CEIL (   v,
  mul 
)     ((((v) + (typeof(v))(mul) - 1) / ((typeof(v))(mul))) * (typeof(v))(mul))

Macro to align a value to the multiple of given value. The resultant value will be of the same type as the first parameter and will be no lower than the first parameter.

Definition at line 844 of file rte_common.h.

◆ RTE_ALIGN_MUL_FLOOR

#define RTE_ALIGN_MUL_FLOOR (   v,
  mul 
)     (((v) / ((typeof(v))(mul))) * (typeof(v))(mul))

Macro to align a value to the multiple of given value. The resultant value will be of the same type as the first parameter and will be no higher than the first parameter.

Definition at line 852 of file rte_common.h.

◆ RTE_ALIGN_MUL_NEAR

#define RTE_ALIGN_MUL_NEAR (   v,
  mul 
)
Value:
__extension__ ({ \
typeof(v) ceil = RTE_ALIGN_MUL_CEIL(v, mul); \
typeof(v) floor = RTE_ALIGN_MUL_FLOOR(v, mul); \
(ceil - (v)) > ((v) - floor) ? floor : ceil; \
})
#define RTE_ALIGN_MUL_FLOOR(v, mul)
Definition: rte_common.h:852
#define RTE_ALIGN_MUL_CEIL(v, mul)
Definition: rte_common.h:844

Macro to align value to the nearest multiple of the given value. The resultant value might be greater than or less than the first parameter whichever difference is the lowest.

Definition at line 860 of file rte_common.h.

◆ RTE_DIV_ROUND_UP

#define RTE_DIV_ROUND_UP (   n,
  d 
)    (((n) + (d) - 1) / (d))

Macro to divide dividend n by divisor d, rounding up if d does not divide n.

Parameters
nDividend. Must be a non-negative integer to round correctly.
dDivisor. Must be a positive integer. Evaluated twice.
Returns
Result of dividing n by d, rounded up.
Note
The divisor d is evaluated twice. Arguments must not have side effects.
Both n and d must be non-negative to round correctly.
The sum (n) + (d) - 1 can wrap around if n is close to the maximum representable value of its type (e.g. RTE_DIV_ROUND_UP(UINT32_MAX, 2) on uint32_t wraps to 0).

Definition at line 884 of file rte_common.h.

◆ RTE_BUILD_BUG_ON

#define RTE_BUILD_BUG_ON (   condition)    do { static_assert(!(condition), #condition); } while (0)

Triggers an error at compilation time if the condition is true.

The do { } while(0) exists to workaround a bug in clang (#55821) where it would not handle _Static_assert in a switch case.

Definition at line 916 of file rte_common.h.

◆ RTE_CACHE_LINE_MASK

#define RTE_CACHE_LINE_MASK   (RTE_CACHE_LINE_SIZE-1)

Cache line mask.

Definition at line 921 of file rte_common.h.

◆ RTE_CACHE_LINE_ROUNDUP

#define RTE_CACHE_LINE_ROUNDUP (   size)    RTE_ALIGN_CEIL(size, RTE_CACHE_LINE_SIZE)

Return the first cache-aligned value greater or equal to size.

Definition at line 924 of file rte_common.h.

◆ RTE_CACHE_LINE_MIN_SIZE

#define RTE_CACHE_LINE_MIN_SIZE   64

Cache line size in terms of log2 Minimum Cache line size.

Definition at line 936 of file rte_common.h.

◆ __rte_cache_aligned

#define __rte_cache_aligned   __rte_aligned(RTE_CACHE_LINE_SIZE)

◆ __rte_cache_min_aligned

#define __rte_cache_min_aligned   __rte_aligned(RTE_CACHE_LINE_MIN_SIZE)

Force minimum cache line alignment.

Definition at line 942 of file rte_common.h.

◆ RTE_CACHE_GUARD

#define RTE_CACHE_GUARD   _RTE_CACHE_GUARD_HELPER1(__LINE__)

Empty cache lines, to guard against false sharing-like effects on systems with a next-N-lines hardware prefetcher.

Use as spacing between data accessed by different lcores, to prevent cache thrashing on hardware with speculative prefetching.

Note: Although COUNTER would be better for uniqueness, it is not yet (March 2026) part of the C standard, so compilation would fail when building in pedantic mode.

Definition at line 959 of file rte_common.h.

◆ RTE_MIN

#define RTE_MIN (   a,
  b 
)

◆ RTE_MIN3

#define RTE_MIN3 (   a,
  b,
  c 
)
Value:
__extension__ ({ \
typeof (a) _a_min3 = (a); \
typeof (b) _b_min3 = (b); \
typeof (c) _c_min3 = (c); \
_a_min3 < _b_min3 ? \
(_a_min3 < _c_min3 ? _a_min3 : _c_min3) : \
(_b_min3 < _c_min3 ? _b_min3 : _c_min3); \
})

Macro to return the minimum of three numbers

Definition at line 1009 of file rte_common.h.

◆ RTE_MIN_T

#define RTE_MIN_T (   a,
  b,
  t 
)     ((t)(a) < (t)(b) ? (t)(a) : (t)(b))

Macro to return the minimum of two numbers

As opposed to RTE_MIN, it does not use temporary variables so it is not safe if a or b is an expression. Yet it is guaranteed to be constant for use in static_assert().

Definition at line 1026 of file rte_common.h.

◆ RTE_MAX

#define RTE_MAX (   a,
  b 
)

◆ RTE_MAX3

#define RTE_MAX3 (   a,
  b,
  c 
)
Value:
__extension__ ({ \
typeof (a) _a_max3 = (a); \
typeof (b) _b_max3 = (b); \
typeof (c) _c_max3 = (c); \
_a_max3 > _b_max3 ? \
(_a_max3 > _c_max3 ? _a_max3 : _c_max3) : \
(_b_max3 > _c_max3 ? _b_max3 : _c_max3); \
})

Macro to return the maximum of three numbers

Definition at line 1042 of file rte_common.h.

◆ RTE_MAX_T

#define RTE_MAX_T (   a,
  b,
  t 
)     ((t)(a) > (t)(b) ? (t)(a) : (t)(b))

Macro to return the maximum of two numbers

As opposed to RTE_MAX, it does not use temporary variables so it is not safe if a or b is an expression. Yet it is guaranteed to be constant for use in static_assert().

Definition at line 1059 of file rte_common.h.

◆ offsetof

#define offsetof (   TYPE,
  MEMBER 
)    __builtin_offsetof (TYPE, MEMBER)

◆ container_of

#define container_of (   ptr,
  type,
  member 
)
Value:
__extension__ ({ \
const typeof(((type *)0)->member) *_ptr = (ptr); \
__rte_unused type *_target_ptr = \
(type *)(ptr); \
(type *)(((uintptr_t)_ptr) - offsetof(type, member)); \
})
#define offsetof(TYPE, MEMBER)
Definition: rte_common.h:1066

Return pointer to the wrapping struct instance.

Example:

struct wrapper { ... struct child c; ... };

struct child *x = obtain(...); struct wrapper *w = container_of(x, struct wrapper, c);

Definition at line 1088 of file rte_common.h.

◆ RTE_SWAP

#define RTE_SWAP (   a,
  b 
)
Value:
__extension__ ({ \
typeof (a) _a = a; \
a = b; \
b = _a; \
})

Swap two variables.

Definition at line 1098 of file rte_common.h.

◆ RTE_SIZEOF_FIELD

#define RTE_SIZEOF_FIELD (   type,
  field 
)    (sizeof(((type *)0)->field))

Get the size of a field in a structure.

Parameters
typeThe type of the structure.
fieldThe field in the structure.
Returns
The size of the field in the structure, in bytes.

Definition at line 1115 of file rte_common.h.

◆ RTE_STR

#define RTE_STR (   x)    _RTE_STR(x)

Take a macro value and get a string version of it

Examples
examples/vhost_crypto/main.c.

Definition at line 1119 of file rte_common.h.

◆ _RTE_CONCAT2

#define _RTE_CONCAT2 (   a,
  b 
)    a ## b

Concatenate two tokens after expanding macros in both.

Definition at line 1122 of file rte_common.h.

◆ RTE_FMT

#define RTE_FMT (   fmt,
  ... 
)    fmt "%.0s", __VA_ARGS__ ""

ISO C helpers to modify format strings using variadic macros. This is a replacement for the ", ## __VA_ARGS__" GNU extension. An empty s argument is appended to avoid a dangling comma.

Definition at line 1130 of file rte_common.h.

◆ RTE_LEN2MASK

#define RTE_LEN2MASK (   ln,
  tp 
)     ((tp)((uint64_t)-1 >> (sizeof(uint64_t) * CHAR_BIT - (ln))))

Mask value of type "tp" for the first "ln" bit set.

Examples
examples/ip_fragmentation/main.c, examples/ip_reassembly/main.c, and examples/l3fwd-power/main.c.

Definition at line 1135 of file rte_common.h.

◆ RTE_DIM

#define RTE_DIM (   a)    (sizeof (a) / sizeof ((a)[0]))

Typedef Documentation

◆ __rte_aligned

struct __rte_aligned

Integer types with no alignment requirement.

LACPDU structure (5.4.2 in 802.1AX documentation).

LACPDU frame: Contains ethernet header and LACPDU.

ARP header.

IPv6 Routing Extension Header

< System priority (unused in current implementation)

< System ID - Member MAC address, same as bonding MAC address

< Speed information (implementation dependent) and duplex.

< Priority of this (unused in current implementation)

< Port number. It corresponds to member port id.

Definition at line 160 of file rte_common.h.

◆ phys_addr_t

typedef uint64_t phys_addr_t

Physical address

Definition at line 964 of file rte_common.h.

◆ rte_iova_t

typedef uint64_t rte_iova_t

IO virtual address type. When the physical addressing mode (IOVA as PA) is in use, the translation from an IO virtual address (IOVA) to a physical address is a direct mapping, i.e. the same value. Otherwise, in virtual mode (IOVA as VA), an IOMMU may do the translation.

Definition at line 974 of file rte_common.h.

Function Documentation

◆ rte_is_aligned()

static int rte_is_aligned ( const void *const __rte_restrict  ptr,
const unsigned int  align 
)
inlinestatic

Checks if a pointer is aligned to a given power-of-two value

Parameters
ptrThe pointer whose alignment is to be checked
alignThe power-of-two value to which the ptr should be aligned
Returns
True(1) where the pointer is correctly aligned, false(0) otherwise

Definition at line 898 of file rte_common.h.

◆ rte_str_to_size()

uint64_t rte_str_to_size ( const char *  str)

Converts a numeric string to the equivalent uint64_t value. As well as straight number conversion, also recognises the suffixes k, m and g for kilobytes, megabytes and gigabytes respectively.

If a negative number is passed in i.e. a string with the first non-black character being "-", zero is returned. Zero is also returned in the case of an error with the strtoull call in the function.

Parameters
strString containing number to convert.
Returns
Number.

◆ rte_size_to_str()

__rte_experimental char * rte_size_to_str ( char *  buf,
int  buf_size,
uint64_t  count,
bool  use_iec,
const char *  unit 
)
Warning
EXPERIMENTAL: this API may change without prior notice.

Converts the uint64_t value provided to a human-readable string. It null-terminates the string, truncating the data if needed. An optional unit (like "B") can be provided as a string. It will be appended to the number, and a space will be inserted before the unit if needed.

Sample outputs: (1) "use_iec" disabled, (2) "use_iec" enabled, (3) "use_iec" enabled and "B" as unit. 0 : "0", "0", "0 B" 700 : "700", "700", "700 B" 1000 : "1.00 k", "1000", "1000 B" 1024 : "1.02 k", "1.00 ki", "1.00 kiB" 21474836480 : "21.5 G", "20.0 Gi", "20.0 GiB" 109951162777600 : "110 T", "100 Ti", "100 TiB"

Parameters
bufBuffer to write the string to.
buf_sizeSize of the buffer.
countNumber to convert.
use_iecIf true, use IEC units (1024-based), otherwise use SI units (1000-based).
unitUnit to append to the string (Like "B" for bytes). Can be NULL.
Returns
buf on success, NULL if the buffer is too small.

◆ rte_exit()

__rte_noreturn void rte_exit ( int  exit_code,
const char *  format,
  ... 
)

Function to terminate the application immediately, printing an error message and returning the exit_code back to the shell.

This function never returns

Parameters
exit_codeThe exit code to be returned by the application
formatThe format string to be used for printing the message. This can include printf format characters which will be expanded using any further parameters to the function.
Examples
examples/bbdev_app/main.c, examples/bond/main.c, examples/distributor/main.c, examples/dma/dmafwd.c, examples/ethtool/ethtool-app/main.c, examples/eventdev_pipeline/main.c, examples/eventdev_pipeline/pipeline_worker_generic.c, examples/eventdev_pipeline/pipeline_worker_tx.c, examples/fips_validation/main.c, examples/flow_filtering/main.c, examples/flow_filtering/snippets/snippet_match_port_affinity.c, examples/ip_fragmentation/main.c, examples/ip_reassembly/main.c, examples/ipsec-secgw/ipsec-secgw.c, examples/ipsec-secgw/rt.c, examples/ipsec-secgw/sa.c, examples/ipsec-secgw/sp4.c, examples/ipsec-secgw/sp6.c, examples/ipv4_multicast/main.c, examples/l2fwd-cat/l2fwd-cat.c, examples/l2fwd-crypto/main.c, examples/l2fwd-jobstats/main.c, examples/l2fwd-keepalive/main.c, examples/l2fwd-macsec/main.c, examples/l2fwd/main.c, examples/l3fwd-graph/main.c, examples/l3fwd-power/main.c, examples/l3fwd/em_route_parse.c, examples/l3fwd/l3fwd_acl.c, examples/l3fwd/l3fwd_em.c, examples/l3fwd/l3fwd_event.c, examples/l3fwd/l3fwd_fib.c, examples/l3fwd/l3fwd_lpm.c, examples/l3fwd/lpm_route_parse.c, examples/l3fwd/main.c, examples/link_status_interrupt/main.c, examples/multi_process/client_server_mp/mp_client/client.c, examples/multi_process/client_server_mp/mp_server/init.c, examples/multi_process/simple_mp/main.c, examples/multi_process/symmetric_mp/main.c, examples/ntb/ntb_fwd.c, examples/packet_ordering/main.c, examples/ptp_tap_relay_sw/ptp_tap_relay_sw.c, examples/ptpclient/ptpclient.c, examples/qos_meter/main.c, examples/qos_sched/cfg_file.c, examples/qos_sched/init.c, examples/rxtx_callbacks/main.c, examples/server_node_efd/efd_node/node.c, examples/server_node_efd/efd_server/init.c, examples/service_cores/main.c, examples/skeleton/basicfwd.c, examples/vdpa/main.c, examples/vhost/main.c, examples/vhost_blk/vhost_blk.c, examples/vhost_crypto/main.c, examples/vm_power_manager/guest_cli/main.c, examples/vm_power_manager/main.c, examples/vmdq/main.c, and examples/vmdq_dcb/main.c.

Variable Documentation

◆ RTE_MARKER

__extension__ typedef void* RTE_MARKER[0]

Generic marker for any place in a structure.

Definition at line 982 of file rte_common.h.

◆ RTE_MARKER8

__extension__ typedef uint8_t RTE_MARKER8[0]

Marker for 1B alignment in a structure.

Definition at line 984 of file rte_common.h.

◆ RTE_MARKER16

__extension__ typedef uint16_t RTE_MARKER16[0]

Marker for 2B alignment in a structure.

Definition at line 986 of file rte_common.h.

◆ RTE_MARKER32

__extension__ typedef uint32_t RTE_MARKER32[0]

Marker for 4B alignment in a structure.

Definition at line 988 of file rte_common.h.

◆ RTE_MARKER64

__extension__ typedef uint64_t RTE_MARKER64[0]

Marker for 8B alignment in a structure.

Definition at line 990 of file rte_common.h.