Ubuntu Manpages

rte_common.h

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


#define __rte_aligned(a)
#define __rte_packed (RTE_DEPRECATED(__rte_packed) __attribute__((__packed__)))
#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_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)
#define __rte_format_printf(format_index, first_arg)
#define __rte_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)
#define RTE_INIT(func)
#define RTE_FINI_PRIO(func, prio)
#define RTE_FINI(func)
#define __rte_noreturn __attribute__((noreturn))
#define __rte_unreachable()
#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)
#define __rte_no_asan
#define RTE_PTR_ADD(ptr, x)
#define RTE_PTR_SUB(ptr, x)
#define RTE_PTR_DIFF(ptr1, ptr2)
#define RTE_PTR_UNQUAL(X)
#define RTE_CAST_PTR(type, ptr)
#define RTE_CAST_FIELD(var, field, type)
#define RTE_PTR_ALIGN_FLOOR(ptr, align)
#define RTE_ALIGN_FLOOR(val, align)
#define RTE_PTR_ALIGN_CEIL(ptr, align)
#define RTE_ALIGN_CEIL(val, align)
#define RTE_PTR_ALIGN(ptr, align)
#define RTE_ALIGN(val, align)
#define RTE_ALIGN_MUL_CEIL(v, mul)
#define RTE_ALIGN_MUL_FLOOR(v, mul)
#define RTE_ALIGN_MUL_NEAR(v, mul)
#define RTE_BUILD_BUG_ON(condition)
#define RTE_CACHE_LINE_MASK (RTE_CACHE_LINE_SIZE-1)
#define RTE_CACHE_LINE_ROUNDUP(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)
#define RTE_MAX(a, b)
#define RTE_MAX_T(a, b, t)
#define offsetof(TYPE, MEMBER)
#define container_of(ptr, type, member)
#define RTE_SWAP(a, b)
#define RTE_SIZEOF_FIELD(type, field)
#define RTE_STR(x)
#define RTE_FMT(fmt, ...)
#define RTE_LEN2MASK(ln, tp)
#define RTE_DIM(a)


typedef uint64_t phys_addr_t
typedef uint64_t rte_iova_t


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


__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]

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

Definition in file rte_common.h.

Value:

__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 121 of file rte_common.h.








Deprecated








See also


__rte_packed_begin



__rte_packed_end




Force a structure to be packed


Definition at line 144 of file rte_common.h.








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.


Definition at line 158 of file rte_common.h.








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


Definition at line 168 of file rte_common.h.








Macro to mark macros and defines scheduled for removal


Definition at line 188 of file rte_common.h.








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








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


Definition at line 208 of file rte_common.h.








Mark a function or variable to a weak reference.


Definition at line 219 of file rte_common.h.








Mark a function to be pure.


Definition at line 228 of file rte_common.h.








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


Definition at line 237 of file rte_common.h.








short definition to mark a function parameter unused


Definition at line 248 of file rte_common.h.








Mark pointer as restricted with regard to pointer aliasing.


Definition at line 255 of file rte_common.h.








Value:


(void)(x)




definition to mark a variable or function parameter as used so as
    to avoid a compiler warning


Definition at line 264 of file rte_common.h.








Value:


    __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 280 of file rte_common.h.








Value:


    __attribute__((section(name)))




Specify data or function section/segment.


Definition at line 292 of file rte_common.h.








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








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








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








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


Definition at line 339 of file rte_common.h.








Value:


static void __attribute__((constructor(RTE_PRIO(prio)), used)) func(void)




Run function before main() with high priority.




Parameters


func Constructor function.


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


Definition at line 361 of file rte_common.h.








Value:


    RTE_INIT_PRIO(func, LAST)




Run function before main() with low priority.




The constructor will be run after prioritized constructors.




Parameters


func Constructor function.


Definition at line 393 of file rte_common.h.








Value:


static void __attribute__((destructor(RTE_PRIO(prio)), used)) func(void)




Run after main() with low priority.




Parameters


func Destructor function name.


prio Priority number must be above 100. Lowest number is the last to
  run.


Definition at line 407 of file rte_common.h.








Value:


    RTE_FINI_PRIO(func, LAST)




Run after main() with high priority.




The destructor will be run before prioritized
  destructors.




Parameters


func Destructor function name.


Definition at line 434 of file rte_common.h.








Hint never returning function


Definition at line 443 of file rte_common.h.








Value:


__assume(0)




Hint point in program never reached


Definition at line 452 of file rte_common.h.








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








Force a function to be inlined


Definition at line 490 of file rte_common.h.








Force a function to be noinlined


Definition at line 499 of file rte_common.h.








Hint function in the hot path


Definition at line 508 of file rte_common.h.








Hint function in the cold path


Definition at line 517 of file rte_common.h.








Value:


__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 533 of file rte_common.h.








Disable AddressSanitizer on some code


Definition at line 546 of file rte_common.h.








Value:


((void*)((uintptr_t)(ptr) + (x)))




add a byte-value offset to a pointer


Definition at line 554 of file rte_common.h.








Value:


((void *)((uintptr_t)(ptr) - (x)))




subtract a byte-value offset from a pointer


Definition at line 559 of file rte_common.h.








Value:


((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 566 of file rte_common.h.








Value:


((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 574 of file rte_common.h.








Value:


((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 593 of file rte_common.h.








Value:


    (*(type *)((uintptr_t)(var) + offsetof(typeof(*(var)), field)))




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


Definition at line 598 of file rte_common.h.








Value:


    ((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 610 of file rte_common.h.








Value:


    (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 619 of file rte_common.h.








Value:


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








Value:


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








Value:


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








Value:


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








Value:


    ((((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 663 of file rte_common.h.








Value:


    (((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 671 of file rte_common.h.








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;    \
    })




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








Value:


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








Cache line mask.


Definition at line 721 of file rte_common.h.








Value:


RTE_ALIGN_CEIL(size, RTE_CACHE_LINE_SIZE)




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


Definition at line 724 of file rte_common.h.








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


Definition at line 736 of file rte_common.h.








Force alignment to cache line.


Definition at line 739 of file rte_common.h.








Force minimum cache line alignment.


Definition at line 742 of file rte_common.h.








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








Value:


    __extension__ ({ \
        typeof (a) _a = (a); \
        typeof (b) _b = (b); \
        _a < _b ? _a : _b; \
    })




Macro to return the minimum of two numbers


Definition at line 795 of file rte_common.h.








Value:


    ((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 809 of file rte_common.h.








Value:


    __extension__ ({ \
        typeof (a) _a = (a); \
        typeof (b) _b = (b); \
        _a > _b ? _a : _b; \
    })




Macro to return the maximum of two numbers


Definition at line 815 of file rte_common.h.








Value:


    ((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 829 of file rte_common.h.








Value:


__builtin_offsetof (TYPE, MEMBER)




Return the offset of a field in a structure.


Definition at line 836 of file rte_common.h.








Value:


            __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, struct wrapper, c);


Definition at line 858 of file rte_common.h.








Value:


    __extension__ ({ \
        typeof (a) _a = a; \
        a = b; \
        b = _a; \
    })




Swap two variables.


Definition at line 868 of file rte_common.h.








Value:


(sizeof(((type *)0)->field))




Get the size of a field in a structure.




Parameters


type 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 885 of file rte_common.h.








Value:


_RTE_STR(x)




Take a macro value and get a string version of it


Definition at line 889 of file rte_common.h.








Value:


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








Value:


    ((tp)((uint64_t)-1 >> (sizeof(uint64_t) * CHAR_BIT - (ln))))




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


Definition at line 901 of file rte_common.h.








Value:


(sizeof (a) / sizeof ((a)[0]))




Number of elements in the array.


Definition at line 905 of file rte_common.h.










typedef uint64_t phys_addr_t


Physical address


Definition at line 760 of file rte_common.h.






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












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




Parameters


ptr The pointer whose alignment is to be checked


align The 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 698 of file rte_common.h.








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


str String containing number to convert.


Returns


Number.








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


buf Buffer to write the string to.


buf_size Size of the buffer.


count Number to convert.


use_iec If true, use IEC units (1024-based), otherwise use SI units
  (1000-based).


unit Unit to append to the string (Like "B" for bytes). Can be
  NULL.


Returns


buf on success, NULL if the buffer is too small.






__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_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.










__extension__ typedef void* RTE_MARKER[0]


Generic marker for any place in a structure.


Definition at line 778 of file rte_common.h.






__extension__ typedef uint8_t RTE_MARKER8[0]


Marker for 1B alignment in a structure.


Definition at line 780 of file rte_common.h.






__extension__ typedef uint16_t RTE_MARKER16[0]


Marker for 2B alignment in a structure.


Definition at line 782 of file rte_common.h.






__extension__ typedef uint32_t RTE_MARKER32[0]


Marker for 4B alignment in a structure.


Definition at line 784 of file rte_common.h.






__extension__ typedef uint64_t RTE_MARKER64[0]


Marker for 8B alignment in a structure.


Definition at line 786 of file rte_common.h.








Generated automatically by Doxygen for DPDK from the source
  code.