rte_ptr_compress.h(3)

📦
version 25.11.3 · 11 versions
, in ubuntu resolute, ubuntu stonking

💖 rte_ptr_compress.h — the rte_ptr_compress.h(3) glow-up 💖

okay bestie, sit down, hydrate, because today we're talking about the Library Functions Manual entry for rte_ptr_compress.h and it is genuinely one of the most lowkey iconic headers in DPDK. no cap.

✨ NAME ✨

rte_ptr_compress.h — it's giving "pointer compression and decompression functions" and it's serving exactly that 🎀

🌈 SYNOPSIS 🌈

first of all, the includes. she needs her little friends:

#include <stdint.h>
#include <inttypes.h>
#include <rte_bitops.h>
#include <rte_branch_prediction.h>
#include <rte_common.h>
#include <rte_debug.h>
#include <rte_vect.h>

🧚 Macros

#define
    RTE_PTR_COMPRESS_BITS_NEEDED_FOR_POINTER_WITHIN_RANGE(mem_length)
#define RTE_PTR_COMPRESS_BIT_SHIFT_FROM_ALIGNMENT(alignment)
#define RTE_PTR_COMPRESS_CAN_COMPRESS_16_SHIFT(mem_length,
    obj_alignment)
#define RTE_PTR_COMPRESS_CAN_COMPRESS_32_SHIFT(mem_length,
    obj_alignment)

🦋 Functions

static __rte_always_inline void rte_ptr_compress_32_shift (void
    *ptr_base, void *const *src_table, uint32_t *dest_table, size_t n,
    uint8_t bit_shift)
static __rte_always_inline void rte_ptr_decompress_32_shift (void
    *ptr_base, uint32_t const *src_table, void **dest_table, size_t n,
    uint8_t bit_shift)
static __rte_always_inline void rte_ptr_compress_16_shift (void
    *ptr_base, void *const *src_table, uint16_t *dest_table, size_t n,
    uint8_t bit_shift)
static __rte_always_inline void rte_ptr_decompress_16_shift (void
    *ptr_base, uint16_t const *src_table, void **dest_table, size_t n,
    uint8_t bit_shift)

👑 Detailed Description 👑

bestie. pointer compression and decompression functions. that's the whole vibe. 💅

so here's the tea: when you're passing arrays full of pointers between threads, that memory containing the pointers gets copied multiple times, and that is especially costly between cores. it's giving "why are we like this". ao these functions let us compress the pointers instead. obsessed.

compression takes advantage of the fact that pointers are usually located in a limited memory region. so we compress them by converting them to offsets from a base memory address. and offsets? offsets can be stored in fewer bytes. ate. 💖

the compression functions come in two varieties: 32-bit and 16-bit.

to determine how many bits are needed to compress the pointer, you calculate the biggest offset possible (highest value pointer - base pointer) and shift the value right according to alignment — shift by the exponent of the power of 2 of alignment: aligned by 4 → shift by 2, aligned by 8 → shift by 3, etc. the resulting value must fit in either 32 or 16 bits. and you may use the macros provided in this file to do it programmatically, which is the slay part. ✨

for a usage example and further explanation, please see this library's documentation in the programming guide. iykyk.

📌 Definition in file rte_ptr_compress.h.

🍓 Macro Definition Documentation 🍓

💜 #define RTE_PTR_COMPRESS_BITS_NEEDED_FOR_POINTER_WITHIN_RANGE( mem_length)

Value:

(((uint64_t)mem_length) < 2 ? 1 : \
    (sizeof(uint64_t) * CHAR_BIT - \
     rte_clz64((uint64_t)mem_length - 1)))

calculate how many bits are required to store pointers within a given memory region as offsets. this can help you decide which pointer compression functions can be used. very "let me do the math so you don't have to" of her. 🧮

Parameters

  • mem_length — length of the memory region the pointers are constrained to.

Returns

  • number of bits required to store a value.
Definition at line 56 of file rte_ptr_compress.h.

💜 #define RTE_PTR_COMPRESS_BIT_SHIFT_FROM_ALIGNMENT( alignment)

Value:

((alignment) == 0 ? 0 : rte_ctz64((uint64_t)alignment))

calculate how many bits in the address can be dropped without losing any information, thanks to the alignment of the address. no information lost?? that's the standard. 😌

Parameters

  • alignment — memory alignment.

Returns

  • size of shift allowed without dropping any information from the pointer.
Definition at line 70 of file rte_ptr_compress.h.

💜 #define RTE_PTR_COMPRESS_CAN_COMPRESS_16_SHIFT( mem_length, obj_alignment)

Value:

((RTE_PTR_COMPRESS_BITS_NEEDED_FOR_POINTER_WITHIN_RANGE(mem_length) - \
RTE_PTR_COMPRESS_BIT_SHIFT_FROM_ALIGNMENT(obj_alignment)) <= 16 ? 1 : 0)

determine if rte_ptr_compress_16_shift can be used to compress pointers that contain addresses of memory objects whose memory is aligned by a given amount and contained in a given memory region. it's a yes/no girlie and honestly? same.

Parameters

  • mem_length — the length of the memory region that contains the objects pointed to.
  • obj_alignment — the alignment of objects pointed to.

Returns

  • 1 if the function can be used, 0 otherwise.
Definition at line 85 of file rte_ptr_compress.h.

💜 #define RTE_PTR_COMPRESS_CAN_COMPRESS_32_SHIFT( mem_length, obj_alignment)

Value:

((RTE_PTR_COMPRESS_BITS_NEEDED_FOR_POINTER_WITHIN_RANGE(mem_length) - \
RTE_PTR_COMPRESS_BIT_SHIFT_FROM_ALIGNMENT(obj_alignment)) <= 32 ? 1 : 0)

determine if rte_ptr_compress_32_shift can be used to compress pointers that contain addresses of memory objects whose memory is aligned by a given amount and contained in a given memory region. literally the same energy as the 16 one but with bigger numbers ✨

Parameters

  • mem_length — the length of the memory region that contains the objects pointed to.
  • obj_alignment — the alignment of objects pointed to.

Returns

  • 1 if the function can be used, 0 otherwise.
Definition at line 101 of file rte_ptr_compress.h.

🫶 Function Documentation 🫶

🌸 __rte_always_inline void rte_ptr_compress_32_shift (void * ptr_base, void *const * src_table, uint32_t * dest_table, size_t n, uint8_t bit_shift) [static]

compress pointers into 32-bit offsets from a base pointer. 🎀

⚠️ Note — it is the programmer's responsibility to ensure the resulting offsets fit into 32 bits. alignment of the structures pointed to by the pointers allows us to drop bits from the offsets, and that's controlled by the bit_shift parameter. what this means, bestie: if structures are aligned by 8 bytes they must be within 32GB of the base pointer. if there is no such alignment guarantee, they must be within 4GB. that's the whole thing, don't be messy about it. 😭

Parameters

  • ptr_base — a pointer used to calculate offsets of pointers in src_table.
  • src_table — a pointer to an array of pointers.
  • dest_table — a pointer to an array of compressed pointers returned by this function.
  • n — the number of objects to compress, must be strictly positive.
  • bit_shift — byte alignment of memory pointed to by the pointers allows for bits to be dropped from the offset and hence widen the memory region that can be covered. this controls how many bits are right shifted.
Definition at line 129 of file rte_ptr_compress.h.

🌸 __rte_always_inline void rte_ptr_decompress_32_shift (void * ptr_base, uint32_t const * src_table, void ** dest_table, size_t n, uint8_t bit_shift) [static]

decompress pointers from 32-bit offsets from a base pointer. the un-girlbossing of the compression, we love to see it. 💅

Parameters

  • ptr_base — a pointer which was used to calculate offsets in src_table.
  • src_table — a pointer to an array to compressed pointers.
  • dest_table — a pointer to an array of decompressed pointers returned by this function.
  • n — the number of objects to decompress, must be strictly positive.
  • bit_shift — byte alignment of memory pointed to by the pointers allows for bits to be dropped from the offset and hence widen the memory region that can be covered. this controls how many bits are left shifted when pointers are recovered from the offsets.
Definition at line 190 of file rte_ptr_compress.h.

🌸 __rte_always_inline void rte_ptr_compress_16_shift (void * ptr_base, void *const * src_table, uint16_t * dest_table, size_t n, uint8_t bit_shift) [static]

compress pointers into 16-bit offsets from a base pointer. tiny offsets, big energy. 🦋

⚠️ Note — again, it is the programmer's responsibility to ensure the resulting offsets fit into 16 bits. alignment of the structures pointed to by the pointers allows us to drop bits from the offsets, and that's controlled by the bit_shift parameter. so: if structures are aligned by 8 bytes they must be within 256KB of the base pointer. if there is no such alignment guarantee, they must be within 64KB. 256KB!! she's compact!! 💀

Parameters

  • ptr_base — a pointer used to calculate offsets of pointers in src_table.
  • src_table — a pointer to an array of pointers.
  • dest_table — a pointer to an array of compressed pointers returned by this function.
  • n — the number of objects to compress, must be strictly positive.
  • bit_shift — byte alignment of memory pointed to by the pointers allows for bits to be dropped from the offset and hence widen the memory region that can be covered. this controls how many bits are right shifted.
Definition at line 254 of file rte_ptr_compress.h.

🌸 __rte_always_inline void rte_ptr_decompress_16_shift (void * ptr_base, uint16_t const * src_table, void ** dest_table, size_t n, uint8_t bit_shift) [static]

decompress pointers from 16-bit offsets from a base pointer. the reverse card, played flawlessly. 🎀

Parameters

  • ptr_base — a pointer which was used to calculate offsets in src_table.
  • src_table — a pointer to an array to compressed pointers.
  • dest_table — a pointer to an array of decompressed pointers returned by this function.
  • n — the number of objects to decompress, must be strictly positive.
  • bit_shift — byte alignment of memory pointed to by the pointers allows for bits to be dropped from the offset and hence widen the memory region that can be covered. this controls how many bits are left shifted when pointers are recovered from the offsets.
Definition at line 298 of file rte_ptr_compress.h.

🌟 Author 🌟

generated automatically by Doxygen for DPDK from the source code. not a human, just a little documentation robot doing her thing. no thoughts, just docs. 🤖💖

anyway bestie, that's the whole page — pointer compression, offsets, alignment shifts, and every single macro and function exactly where you left them. go compress something responsibly. remember: programmer's responsibility to check those offsets fit, i am not your size_t. 😭

mwah 💋 — this was DPDK, Version 25.11.3, and we're out 🫶✨

📦 where this page comes from