.TH "rte_ptr_compress.h" 3 "Version 25.11.0" "DPDK" \" -*- nroff -*- .ad l .nh .SH NAME rte_ptr_compress.h .SH SYNOPSIS .br .PP \fR#include \fP .br \fR#include \fP .br \fR#include \fP .br \fR#include \fP .br \fR#include \fP .br \fR#include \fP .br \fR#include \fP .br .SS "Macros" .in +1c .ti -1c .RI "#define \fBRTE_PTR_COMPRESS_BITS_NEEDED_FOR_POINTER_WITHIN_RANGE\fP(mem_length)" .br .ti -1c .RI "#define \fBRTE_PTR_COMPRESS_BIT_SHIFT_FROM_ALIGNMENT\fP(alignment)" .br .ti -1c .RI "#define \fBRTE_PTR_COMPRESS_CAN_COMPRESS_16_SHIFT\fP(mem_length, obj_alignment)" .br .ti -1c .RI "#define \fBRTE_PTR_COMPRESS_CAN_COMPRESS_32_SHIFT\fP(mem_length, obj_alignment)" .br .in -1c .SS "Functions" .in +1c .ti -1c .RI "static \fB__rte_always_inline\fP void \fBrte_ptr_compress_32_shift\fP (void *ptr_base, void *const *src_table, uint32_t *dest_table, size_t n, uint8_t bit_shift)" .br .ti -1c .RI "static \fB__rte_always_inline\fP void \fBrte_ptr_decompress_32_shift\fP (void *ptr_base, uint32_t const *src_table, void **dest_table, size_t n, uint8_t bit_shift)" .br .ti -1c .RI "static \fB__rte_always_inline\fP void \fBrte_ptr_compress_16_shift\fP (void *ptr_base, void *const *src_table, uint16_t *dest_table, size_t n, uint8_t bit_shift)" .br .ti -1c .RI "static \fB__rte_always_inline\fP void \fBrte_ptr_decompress_16_shift\fP (void *ptr_base, uint16_t const *src_table, void **dest_table, size_t n, uint8_t bit_shift)" .br .in -1c .SH "Detailed Description" .PP Pointer compression and decompression functions\&. .PP 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\&. .PP 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\&. .PP The compression functions come in two varieties: 32-bit and 16-bit\&. .PP 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\&. .PP For usage example and further explanation please see this library's documentation in the programming guide\&. .PP Definition in file \fBrte_ptr_compress\&.h\fP\&. .SH "Macro Definition Documentation" .PP .SS "#define RTE_PTR_COMPRESS_BITS_NEEDED_FOR_POINTER_WITHIN_RANGE( mem_length)" \fBValue:\fP .nf (((uint64_t)mem_length) < 2 ? 1 : \\ (sizeof(uint64_t) * CHAR_BIT \- \\ rte_clz64((uint64_t)mem_length \- 1))) .PP .fi 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\&. .PP \fBParameters\fP .RS 4 \fImem_length\fP Length of the memory region the pointers are constrained to\&. .RE .PP \fBReturns\fP .RS 4 Number of bits required to store a value\&. .RE .PP .PP Definition at line \fB56\fP of file \fBrte_ptr_compress\&.h\fP\&. .SS "#define RTE_PTR_COMPRESS_BIT_SHIFT_FROM_ALIGNMENT( alignment)" \fBValue:\fP .nf ((alignment) == 0 ? 0 : rte_ctz64((uint64_t)alignment)) .PP .fi Calculate how many bits in the address can be dropped without losing any information thanks to the alignment of the address\&. .PP \fBParameters\fP .RS 4 \fIalignment\fP Memory alignment\&. .RE .PP \fBReturns\fP .RS 4 Size of shift allowed without dropping any information from the pointer\&. .RE .PP .PP Definition at line \fB70\fP of file \fBrte_ptr_compress\&.h\fP\&. .SS "#define RTE_PTR_COMPRESS_CAN_COMPRESS_16_SHIFT( mem_length, obj_alignment)" \fBValue:\fP .nf ((RTE_PTR_COMPRESS_BITS_NEEDED_FOR_POINTER_WITHIN_RANGE(mem_length) \- \\ RTE_PTR_COMPRESS_BIT_SHIFT_FROM_ALIGNMENT(obj_alignment)) <= 16 ? 1 : 0) .PP .fi 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\&. .PP \fBParameters\fP .RS 4 \fImem_length\fP The length of the memory region that contains the objects pointed to\&. .br \fIobj_alignment\fP The alignment of objects pointed to\&. .RE .PP \fBReturns\fP .RS 4 1 if function can be used, 0 otherwise\&. .RE .PP .PP Definition at line \fB85\fP of file \fBrte_ptr_compress\&.h\fP\&. .SS "#define RTE_PTR_COMPRESS_CAN_COMPRESS_32_SHIFT( mem_length, obj_alignment)" \fBValue:\fP .nf ((RTE_PTR_COMPRESS_BITS_NEEDED_FOR_POINTER_WITHIN_RANGE(mem_length) \- \\ RTE_PTR_COMPRESS_BIT_SHIFT_FROM_ALIGNMENT(obj_alignment)) <= 32 ? 1 : 0) .PP .fi 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\&. .PP \fBParameters\fP .RS 4 \fImem_length\fP The length of the memory region that contains the objects pointed to\&. .br \fIobj_alignment\fP The alignment of objects pointed to\&. .RE .PP \fBReturns\fP .RS 4 1 if function can be used, 0 otherwise\&. .RE .PP .PP Definition at line \fB101\fP of file \fBrte_ptr_compress\&.h\fP\&. .SH "Function Documentation" .PP .SS "\fB__rte_always_inline\fP void rte_ptr_compress_32_shift (void * ptr_base, void *const * src_table, uint32_t * dest_table, size_t n, uint8_t bit_shift)\fR [static]\fP" Compress pointers into 32-bit offsets from base pointer\&. .PP \fBNote\fP .RS 4 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\&. .RE .PP \fBParameters\fP .RS 4 \fIptr_base\fP A pointer used to calculate offsets of pointers in src_table\&. .br \fIsrc_table\fP A pointer to an array of pointers\&. .br \fIdest_table\fP A pointer to an array of compressed pointers returned by this function\&. .br \fIn\fP The number of objects to compress, must be strictly positive\&. .br \fIbit_shift\fP 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\&. .RE .PP .PP Definition at line \fB129\fP of file \fBrte_ptr_compress\&.h\fP\&. .SS "\fB__rte_always_inline\fP void rte_ptr_decompress_32_shift (void * ptr_base, uint32_t const * src_table, void ** dest_table, size_t n, uint8_t bit_shift)\fR [static]\fP" Decompress pointers from 32-bit offsets from base pointer\&. .PP \fBParameters\fP .RS 4 \fIptr_base\fP A pointer which was used to calculate offsets in src_table\&. .br \fIsrc_table\fP A pointer to an array to compressed pointers\&. .br \fIdest_table\fP A pointer to an array of decompressed pointers returned by this function\&. .br \fIn\fP The number of objects to decompress, must be strictly positive\&. .br \fIbit_shift\fP 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\&. .RE .PP .PP Definition at line \fB190\fP of file \fBrte_ptr_compress\&.h\fP\&. .SS "\fB__rte_always_inline\fP void rte_ptr_compress_16_shift (void * ptr_base, void *const * src_table, uint16_t * dest_table, size_t n, uint8_t bit_shift)\fR [static]\fP" Compress pointers into 16-bit offsets from base pointer\&. .PP \fBNote\fP .RS 4 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\&. .RE .PP \fBParameters\fP .RS 4 \fIptr_base\fP A pointer used to calculate offsets of pointers in src_table\&. .br \fIsrc_table\fP A pointer to an array of pointers\&. .br \fIdest_table\fP A pointer to an array of compressed pointers returned by this function\&. .br \fIn\fP The number of objects to compress, must be strictly positive\&. .br \fIbit_shift\fP 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\&. .RE .PP .PP Definition at line \fB254\fP of file \fBrte_ptr_compress\&.h\fP\&. .SS "\fB__rte_always_inline\fP void rte_ptr_decompress_16_shift (void * ptr_base, uint16_t const * src_table, void ** dest_table, size_t n, uint8_t bit_shift)\fR [static]\fP" Decompress pointers from 16-bit offsets from base pointer\&. .PP \fBParameters\fP .RS 4 \fIptr_base\fP A pointer which was used to calculate offsets in src_table\&. .br \fIsrc_table\fP A pointer to an array to compressed pointers\&. .br \fIdest_table\fP A pointer to an array of decompressed pointers returned by this function\&. .br \fIn\fP The number of objects to decompress, must be strictly positive\&. .br \fIbit_shift\fP 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\&. .RE .PP .PP Definition at line \fB298\fP of file \fBrte_ptr_compress\&.h\fP\&. .SH "Author" .PP Generated automatically by Doxygen for DPDK from the source code\&.