rte_common.h

       Generated automatically by Doxygen for DPDK from the source code.

DPDK                                             Version 24.11.2                                 rte_common.h(3)

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

       Definition in file rte_common.h.

staticintrte_is_aligned(constvoid*const__rte_restrictptr,constunsignedintalign)[inline],[static]
       Checks if a pointer is aligned to a given power-of-two value

       Parametersptr The pointer whose alignment is to be checked
           align The power-of-two value to which the ptr should be aligned

       ReturnsTrue(1) where the pointer is correctly aligned, false(0) otherwise

       Definition at line 586 of file rte_common.h.

   uint64_trte_str_to_size(constchar*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.

       Parametersstr String containing number to convert.

       Returns
           Number.

   __rte_noreturnvoidrte_exit(intexit_code,constchar*format,...)
       Function to terminate the application immediately, printing an error message and returning the exit_code
       back to the shell.

       This function never returns

       Parametersexit_code The exit code to be returned by the application
           format The 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.

#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).

       Definition at line 89 of file rte_common.h.

   __extension__structrte_vxlan_gpe_hdr__rte_packed__attribute__((__packed__))
       Force a structure to be packed

       Definition at line 108 of file rte_common.h.

   #define__rte_may_alias__attribute__((__may_alias__))
       Macro to mark a type that is not subject to type-based aliasing rules

       Definition at line 117 of file rte_common.h.

   #defineRTE_DEPRECATED(x)
       Macro to mark macros and defines scheduled for removal

       Definition at line 137 of file rte_common.h.

   #define__rte_weak__attribute__((__weak__))
       Mark a function or variable to a weak reference.

       Definition at line 143 of file rte_common.h.

   #define__rte_pure__attribute__((pure))
       Mark a function to be pure.

       Definition at line 151 of file rte_common.h.

   #define__rte_used__attribute__((used))
       Force symbol to be generated even if it appears to be unused.

       Definition at line 160 of file rte_common.h.

   #define__rte_unused__attribute__((__unused__))
       short definition to mark a function parameter unused

       Definition at line 171 of file rte_common.h.

   #define__rte_restrict__restrict
       Mark pointer as restricted with regard to pointer aliasing.

       Definition at line 178 of file rte_common.h.

   #defineRTE_SET_USED(x)(void)(x)
       definition to mark a variable or function parameter as used so as to avoid a compiler warning

       Definition at line 187 of file rte_common.h.

   #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 203 of file rte_common.h.

   #define__rte_section(name)__attribute__((section(name)))
       Specify data or function section/segment.

       Definition at line 215 of file rte_common.h.

   #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 228 of file rte_common.h.

   #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 241 of file rte_common.h.

   #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 251 of file rte_common.h.

   #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 262 of file rte_common.h.

   #defineRTE_INIT_PRIO(func,prio)staticvoid__attribute__((constructor(RTE_PRIO(prio)),used))func(void)

       Run function before main() with high priority.

       Parametersfunc Constructor function.
           prio Priority number must be above 100. Lowest number is the first to run.

       Definition at line 284 of file rte_common.h.

   #defineRTE_INIT(func)RTE_INIT_PRIO(func,LAST)
       Run function before main() with low priority.

       The constructor will be run after prioritized constructors.

       Parametersfunc Constructor function.

       Definition at line 316 of file rte_common.h.

   #defineRTE_FINI_PRIO(func,prio)staticvoid__attribute__((destructor(RTE_PRIO(prio)),used))func(void)
       Run after main() with low priority.

       Parametersfunc Destructor function name.
           prio Priority number must be above 100. Lowest number is the last to run.

       Definition at line 330 of file rte_common.h.

   #defineRTE_FINI(func)RTE_FINI_PRIO(func,LAST)
       Run after main() with high priority.

       The destructor will be run before prioritized destructors.

       Parametersfunc Destructor function name.

       Definition at line 357 of file rte_common.h.

   #define__rte_noreturn__attribute__((noreturn))
       Hint never returning function

       Definition at line 366 of file rte_common.h.

   #define__rte_unreachable()__assume(0)
       Hint point in program never reached

       Definition at line 375 of file rte_common.h.

   #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.

       __rte_warn_unused_result int foo();

       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
        }

       Definition at line 404 of file rte_common.h.

   #define__rte_always_inlineinline__attribute__((always_inline))
       Force a function to be inlined

       Definition at line 413 of file rte_common.h.

   #define__rte_noinline__attribute__((noinline))
       Force a function to be noinlined

       Definition at line 419 of file rte_common.h.

   #define__rte_hot__attribute__((hot))
       Hint function in the hot path

       Definition at line 424 of file rte_common.h.

   #define__rte_cold__attribute__((cold))
       Hint function in the cold path

       Definition at line 432 of file rte_common.h.

   #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 448 of file rte_common.h.

   #define__rte_no_asan
       Disable AddressSanitizer on some code

       Definition at line 461 of file rte_common.h.

   #defineRTE_PTR_ADD(ptr,x)((void*)((uintptr_t)(ptr)+(x)))
       add a byte-value offset to a pointer

       Definition at line 469 of file rte_common.h.

   #defineRTE_PTR_SUB(ptr,x)((void*)((uintptr_t)(ptr)-(x)))
       subtract a byte-value offset from a pointer

       Definition at line 474 of file rte_common.h.

   #defineRTE_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.

       Definition at line 481 of file rte_common.h.

   #defineRTE_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 486 of file rte_common.h.

   #defineRTE_PTR_ALIGN_FLOOR(ptr,align)((typeof(ptr))RTE_ALIGN_FLOOR((uintptr_t)(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 higher than the first parameter. Second parameter
       must be a power-of-two value.

       Definition at line 498 of file rte_common.h.

   #defineRTE_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.

       Definition at line 507 of file rte_common.h.

   #defineRTE_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. 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.

       Definition at line 516 of file rte_common.h.

   #defineRTE_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.

       Definition at line 525 of file rte_common.h.

   #defineRTE_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 535 of file rte_common.h.

   #defineRTE_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

       Definition at line 544 of file rte_common.h.

   #defineRTE_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 551 of file rte_common.h.

   #defineRTE_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 559 of file rte_common.h.

   #defineRTE_ALIGN_MUL_NEAR(v,mul)Value:.PP
           __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;  \
           })
       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 567 of file rte_common.h.

   #defineRTE_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 604 of file rte_common.h.

   #defineRTE_CACHE_LINE_MASK(RTE_CACHE_LINE_SIZE-1)
       Cache line mask.

       Definition at line 609 of file rte_common.h.

   #defineRTE_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 612 of file rte_common.h.

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

       Definition at line 624 of file rte_common.h.

   #define__rte_cache_aligned__rte_aligned(RTE_CACHE_LINE_SIZE)
       Force alignment to cache line.

       Definition at line 627 of file rte_common.h.

   #define__rte_cache_min_aligned__rte_aligned(RTE_CACHE_LINE_MIN_SIZE)
       Force minimum cache line alignment.

       Definition at line 630 of file rte_common.h.

   #defineRTE_CACHE_GUARD_RTE_CACHE_GUARD_HELPER1(__COUNTER__)
       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.

       Definition at line 643 of file rte_common.h.

   #defineRTE_MIN(a,b)Value:.PP
           __extension__ ({ \
               typeof (a) _a = (a); \
               typeof (b) _b = (b); \
               _a < _b ? _a : _b; \
           })
       Macro to return the minimum of two numbers

       Definition at line 683 of file rte_common.h.

   #defineRTE_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 697 of file rte_common.h.

   #defineRTE_MAX(a,b)Value:.PP
           __extension__ ({ \
               typeof (a) _a = (a); \
               typeof (b) _b = (b); \
               _a > _b ? _a : _b; \
           })
       Macro to return the maximum of two numbers

       Definition at line 703 of file rte_common.h.

   #defineRTE_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 717 of file rte_common.h.

   #defineoffsetof(TYPE,MEMBER)__builtin_offsetof(TYPE,MEMBER)
       Return the offset of a field in a structure.

       Definition at line 724 of file rte_common.h.

   #definecontainer_of(ptr,type,member)Value:.PP
                   __extension__ ({        \
                   const typeof(((type *)0)->member) *_ptr = (ptr); \
                   __rte_unused type *_target_ptr =    \
                       (type *)(ptr);              \
                   (type *)(((uintptr_t)_ptr) - offsetof(type, member)); \
               })
       Return pointer to the wrapping struct instance.

       Example:

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

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

       Definition at line 746 of file rte_common.h.

   #defineRTE_SWAP(a,b)Value:.PP
           __extension__ ({ \
               typeof (a) _a = a; \
               a = b; \
               b = _a; \
           })
       Swap two variables.

       Definition at line 756 of file rte_common.h.

   #defineRTE_SIZEOF_FIELD(type,field)(sizeof(((type*)0)->field))
       Get the size of a field in a structure.

       Parameterstype The type of the structure.
           field The field in the structure.

       Returns
           The size of the field in the structure, in bytes.

       Definition at line 773 of file rte_common.h.

   #defineRTE_STR(x)_RTE_STR(x)
       Take a macro value and get a string version of it

       Definition at line 777 of file rte_common.h.

   #defineRTE_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 784 of file rte_common.h.

   #defineRTE_LEN2MASK(ln,tp)((tp)((uint64_t)-1>>(sizeof(uint64_t)*CHAR_BIT-(ln))))
       Mask value of type 'tp' for the first 'ln' bit set.

       Definition at line 789 of file rte_common.h.

   #defineRTE_DIM(a)(sizeof(a)/sizeof((a)[0]))
       Number of elements in the array.

       Definition at line 793 of file rte_common.h.

       rte_common.h

       #include <assert.h>
       #include <limits.h>
       #include <stdint.h>
       #include <stdalign.h>
       #include <rte_config.h>
       #include <rte_os.h>

   Macros
       #define __rte_aligned(a)   __attribute__((__aligned__(a)))
       #define __rte_packed   __attribute__((__packed__))
       #define __rte_may_alias   __attribute__((__may_alias__))
       #define RTE_DEPRECATED(x)
       #define __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)   ((void*)((uintptr_t)(ptr) + (x)))
       #define RTE_PTR_SUB(ptr,  x)   ((void *)((uintptr_t)(ptr) - (x)))
       #define RTE_PTR_DIFF(ptr1,  ptr2)   ((uintptr_t)(ptr1) - (uintptr_t)(ptr2))
       #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), 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_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(__COUNTER__)
       #define RTE_MIN(a,  b)
       #define RTE_MIN_T(a,  b,  t)       ((t)(a) < (t)(b) ? (t)(a) : (t)(b))
       #define RTE_MAX(a,  b)
       #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_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]))

   Typedefstypedef uint64_t phys_addr_ttypedef uint64_t rte_iova_tFunctions
       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_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]

typedefuint64_tphys_addr_t
       Physical address

       Definition at line 648 of file rte_common.h.

   typedefuint64_trte_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 658 of file rte_common.h.

__extension__typedefvoid*RTE_MARKER[0]
       Generic marker for any place in a structure.

       Definition at line 666 of file rte_common.h.

   __extension__typedefuint8_tRTE_MARKER8[0]
       Marker for 1B alignment in a structure.

       Definition at line 668 of file rte_common.h.

   __extension__typedefuint16_tRTE_MARKER16[0]
       Marker for 2B alignment in a structure.

       Definition at line 670 of file rte_common.h.

   __extension__typedefuint32_tRTE_MARKER32[0]
       Marker for 4B alignment in a structure.

       Definition at line 672 of file rte_common.h.

   __extension__typedefuint64_tRTE_MARKER64[0]
       Marker for 8B alignment in a structure.

       Definition at line 674 of file rte_common.h.