--- name: "rte_bitmap.h" 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_bitmap.h" --- # rte\_bitmap.h(3) ## NAME rte\_bitmap.h ## SYNOPSIS `#include `\ `#include `\ `#include `\ `#include `\ `#include `\ `#include `\ `#include `\ ### Data Structures struct **rte\_bitmap**\ ### Functions static uint32\_t **rte\_bitmap\_get\_memory\_footprint** (uint32\_t n\_bits)\ static struct **rte\_bitmap** \* **rte\_bitmap\_init** (uint32\_t n\_bits, uint8\_t \*mem, uint32\_t mem\_size)\ static void **\_\_rte\_bitmap\_clear\_slab\_overhead\_bits** (uint64\_t \*slabs, uint32\_t slab\_size, uint32\_t pos)\ static struct **rte\_bitmap** \* **rte\_bitmap\_init\_with\_all\_set** (uint32\_t n\_bits, uint8\_t \*mem, uint32\_t mem\_size)\ static int **rte\_bitmap\_free** (struct **rte\_bitmap** \*bmp)\ static void **rte\_bitmap\_reset** (struct **rte\_bitmap** \*bmp)\ static void **rte\_bitmap\_prefetch0** (struct **rte\_bitmap** \*bmp, uint32\_t pos)\ static uint64\_t **rte\_bitmap\_get** (struct **rte\_bitmap** \*bmp, uint32\_t pos)\ static void **rte\_bitmap\_set** (struct **rte\_bitmap** \*bmp, uint32\_t pos)\ static void **rte\_bitmap\_set\_slab** (struct **rte\_bitmap** \*bmp, uint32\_t pos, uint64\_t slab)\ static void **rte\_bitmap\_clear** (struct **rte\_bitmap** \*bmp, uint32\_t pos)\ static int **rte\_bitmap\_scan** (struct **rte\_bitmap** \*bmp, uint32\_t \*pos, uint64\_t \*slab)\ ## Detailed Description RTE Bitmap The bitmap component provides a mechanism to manage large arrays of bits through bit get/set/clear and bit array scan operations. The bitmap scan operation is optimized for 64-bit CPUs using 64/128 byte cache lines. The bitmap is hierarchically organized using two arrays (array1 and array2), with each bit in array1 being associated with a full cache line (512/1024 bits) of bitmap bits, which are stored in array2: the bit in array1 is set only when there is at least one bit set within its associated array2 bits, otherwise the bit in array1 is cleared. The read and write operations for array1 and array2 are always done in slabs of 64 bits. This bitmap is not thread safe. For lock free operation on a specific bitmap instance, a single writer thread performing bit set/clear operations is allowed, only the writer thread can do bitmap scan operations, while there can be several reader threads performing bit get operations in parallel with the writer thread. When the use of locking primitives is acceptable, the serialization of the bit set/clear and bitmap scan operations needs to be enforced by the caller, while the bit get operation does not require locking the bitmap. Definition in file **rte\_bitmap.h**. ## Function Documentation ### static uint32\_t rte\_bitmap\_get\_memory\_footprint (uint32\_t n\_bits)` [inline]`, ` [static]` Bitmap memory footprint calculation **Parameters** *n\_bits* Number of bits in the bitmap **Returns** Bitmap memory footprint measured in bytes on success, 0 on error Definition at line **148** of file **rte\_bitmap.h**. ### static struct rte\_bitmap \* rte\_bitmap\_init (uint32\_t n\_bits, uint8\_t \* mem, uint32\_t mem\_size)` [inline]`, ` [static]` Bitmap initialization **Parameters** *n\_bits* Number of pre-allocated bits in array2. \ *mem* Base address of array1 and array2. \ *mem\_size* Minimum expected size of bitmap. **Returns** Handle to bitmap instance. Definition at line **170** of file **rte\_bitmap.h**. ### static void \_\_rte\_bitmap\_clear\_slab\_overhead\_bits (uint64\_t \* slabs, uint32\_t slab\_size, uint32\_t pos)` [inline]`, ` [static]` Bitmap clear slab overhead bits. **Parameters** *slabs* Slab array. \ *slab\_size* Number of 64-bit slabs in the slabs array. \ *pos* The start bit position in the slabs to be cleared. Definition at line **216** of file **rte\_bitmap.h**. ### static struct rte\_bitmap \* rte\_bitmap\_init\_with\_all\_set (uint32\_t n\_bits, uint8\_t \* mem, uint32\_t mem\_size)` [inline]`, ` [static]` Bitmap initialization with all bits set **Parameters** *n\_bits* Number of pre-allocated bits in array2. \ *mem* Base address of array1 and array2. \ *mem\_size* Minimum expected size of bitmap. **Returns** Handle to bitmap instance. Definition at line **246** of file **rte\_bitmap.h**. ### static int rte\_bitmap\_free (struct rte\_bitmap \* bmp)` [inline]`, ` [static]` Bitmap free **Parameters** *bmp* Handle to bitmap instance **Returns** 0 upon success, error code otherwise Definition at line **291** of file **rte\_bitmap.h**. ### static void rte\_bitmap\_reset (struct rte\_bitmap \* bmp)` [inline]`, ` [static]` Bitmap reset **Parameters** *bmp* Handle to bitmap instance Definition at line **308** of file **rte\_bitmap.h**. ### static void rte\_bitmap\_prefetch0 (struct rte\_bitmap \* bmp, uint32\_t pos)` [inline]`, ` [static]` Bitmap location prefetch into CPU L1 cache **Parameters** *bmp* Handle to bitmap instance \ *pos* Bit position Definition at line **324** of file **rte\_bitmap.h**. ### static uint64\_t rte\_bitmap\_get (struct rte\_bitmap \* bmp, uint32\_t pos)` [inline]`, ` [static]` Bitmap bit get **Parameters** *bmp* Handle to bitmap instance \ *pos* Bit position **Returns** 0 when bit is cleared, non-zero when bit is set Definition at line **345** of file **rte\_bitmap.h**. ### static void rte\_bitmap\_set (struct rte\_bitmap \* bmp, uint32\_t pos)` [inline]`, ` [static]` Bitmap bit set **Parameters** *bmp* Handle to bitmap instance \ *pos* Bit position Definition at line **365** of file **rte\_bitmap.h**. ### static void rte\_bitmap\_set\_slab (struct rte\_bitmap \* bmp, uint32\_t pos, uint64\_t slab)` [inline]`, ` [static]` Bitmap slab set **Parameters** *bmp* Handle to bitmap instance \ *pos* Bit position identifying the array2 slab \ *slab* Value to be assigned to the 64-bit slab in array2 Definition at line **393** of file **rte\_bitmap.h**. ### static void rte\_bitmap\_clear (struct rte\_bitmap \* bmp, uint32\_t pos)` [inline]`, ` [static]` Bitmap bit clear **Parameters** *bmp* Handle to bitmap instance \ *pos* Bit position Definition at line **458** of file **rte\_bitmap.h**. ### static int rte\_bitmap\_scan (struct rte\_bitmap \* bmp, uint32\_t \* pos, uint64\_t \* slab)` [inline]`, ` [static]` Bitmap scan (with automatic wrap-around) **Parameters** *bmp* Handle to bitmap instance \ *pos* When function call returns 1, pos contains the position of the next set bit, otherwise not modified \ *slab* When function call returns 1, slab contains the value of the entire 64-bit slab where the bit indicated by pos is located. Slabs are always 64-bit aligned, so the position of the first bit of the slab (this bit is not necessarily set) is pos / 64. Once a slab has been returned by the bitmap scan operation, the internal pointers of the bitmap are updated to point after this slab, so the same slab will not be returned again if it contains more than one bit which is set. When function call returns 0, slab is not modified. **Returns** 0 if there is no bit set in the bitmap, 1 otherwise Definition at line **567** of file **rte\_bitmap.h**. ## Author Generated automatically by Doxygen for DPDK from the source code.