--- name: "RTE_PTR_COMPRESS_BIT_SHIFT_FROM_ALIGNMENT" section: "3" platform: "linux" package: "dpdk-doc" version: "24.11.4-0+deb13u1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/rte_ptr_compress.h" --- # RTE\_PTR\_COMPRESS\_BIT\_SHIFT\_FROM\_ALIGNMENT(3) Part of [rte\_ptr\_compress.h(3)](/rte_ptr_compress.h/3.md). ## NAME rte\_ptr\_compress.h ## SYNOPSIS `#include `\ `#include `\ `#include `\ `#include `\ `#include `\ `#include `\ `#include `\ ### Macros \#define **RTE\_PTR\_COMPRESS\_BITS\_NEEDED\_FOR\_POINTER\_WITHIN\_RANGE**(mem\_length)\ \#define **RTE\_PTR\_COMPRESS\_BIT\_SHIFT\_FROM\_ALIGNMENT**(alignment) ((alignment) == 0 ? 0 : **rte\_ctz64**((uint64\_t)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 Pointer compression and decompression functions. When passing arrays full of pointers between threads, memory containing the pointers is copied multiple times which is especially costly between cores. These functions allow us to compress the pointers. Compression takes advantage of the fact that pointers are usually located in a limited memory region. We compress them by converting them to offsets from a base memory address. Offsets can be stored in fewer bytes. The compression functions come in two varieties: 32-bit and 16-bit. To determine how many bits are needed to compress the pointer, calculate the biggest offset possible (highest value pointer - base pointer) and shift the value right according to alignment (shift by 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. You may use the macros provided in this file to do it programmatically. For usage example and further explanation please see this library's documentation in the programming guide. Definition in file **rte\_ptr\_compress.h**. ## Macro Definition Documentation ### #define RTE\_PTR\_COMPRESS\_BITS\_NEEDED\_FOR\_POINTER\_WITHIN\_RANGE(mem\_length) **Value:**.PP ``` (((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 decide which pointer compression functions can be used. **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) ((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. **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:**.PP ``` ((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. **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 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:**.PP ``` ((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. **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 function can be used, 0 otherwise. Definition at line **101** of file **rte\_ptr\_compress.h**. ## Function Documentation ### 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]` Compress pointers into 32-bit offsets from base pointer. **Note** It is 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. This is controlled by the bit\_shift parameter. This means that 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. **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**. ### 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]` Decompress pointers from 32-bit offsets from base pointer. **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**. ### 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]` Compress pointers into 16-bit offsets from base pointer. **Note** It is 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. This is controlled by the bit\_shift parameter. This means that 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. **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**. ### 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)` [static]` Decompress pointers from 16-bit offsets from base pointer. **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.