rte_bitmap.h(3)

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

💖 rte_bitmap.h — the library functions manual, but make it cute 💖

okay bestie, welcome to rte_bitmap.h(3) — it's a section 3 manual page, it lives in the Library Functions Manual, and it's literally the blueprint for DPDK's bitmap magic. sit down, hydrate, let's get into it 🫶

✨ NAME ✨

rte_bitmap.h — no cap, that's the whole name, she's serving header-file realness 💅

🌸 SYNOPSIS 🌸

First things first, the include stack. you gotta pull all of these in:

#include <string.h>
#include <rte_common.h>
#include <rte_config.h>
#include <rte_debug.h>
#include <rte_memory.h>
#include <rte_branch_prediction.h>
#include <rte_prefetch.h>

🎀 Data Structures 🎀

  • struct rte_bitmap — the main character herself 👑

🦋 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 void 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 💫

okay so the bitmap component is the girl who manages large arrays of bits for you — she does bit get, bit set, bit clear, and bit array scan operations. she's giving data structure, she's giving efficiency 💅

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), and here's the tea: each bit in array1 is associated with a whole full cache line (512/1024 bits) of bitmap bits, and those bitmap bits live in array2. So the bit in array1 is set only when there's at least one bit set within its associated array2 bits — otherwise that array1 bit gets cleared. And the read/write operations for array1 and array2 are always done in slabs of 64 bits. slay 🎀

⚠️ warning bestie, this is important ⚠️ This bitmap is not thread safe. no cap. If you want lock free operation on a specific bitmap instance, here are the rules: a single writer thread performing bit set/clear operations is allowed, and 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. iykyk 🙈

Definition in file rte_bitmap.h. 📍

👑 Function Documentation 👑

uint32_t rte_bitmap_get_memory_footprint (uint32_t n_bits) [inline], [static]

Bitmap memory footprint calculation 🧮 — she tells you how much room your bitmap is gonna need.

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.

struct rte_bitmap * rte_bitmap_init (uint32_t n_bits, uint8_t * mem, uint32_t mem_size) [inline], [static]

Bitmap initialization ✨ — the glow-up moment where your bitmap is born.

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.

void __rte_bitmap_clear_slab_overhead_bits (uint64_t * slabs, uint32_t slab_size, uint32_t pos) [inline], [static]

Bitmap clear slab overhead bits 🧹 — cleaning up the extra bits, no drama.

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.

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 🔥 — the maximalist version of rte_bitmap_init, every bit is showing up and showing out.

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.

void rte_bitmap_free (struct rte_bitmap * bmp) [inline], [static]

Bitmap free 🦋 — she's released.

💀 fair warning: this function does nothing in current implementation. literally nothing. she's a no-op and she's at peace with it.

Parameters

  • bmp — Handle to bitmap instance

Definition at line 291 of file rte_bitmap.h.

void rte_bitmap_reset (struct rte_bitmap * bmp) [inline], [static]

Bitmap reset 🔄 — back to a blank slate, fresh start energy.

Parameters

  • bmp — Handle to bitmap instance

Definition at line 303 of file rte_bitmap.h.

void rte_bitmap_prefetch0 (struct rte_bitmap * bmp, uint32_t pos) [inline], [static]

Bitmap location prefetch into CPU L1 cache ⚡ — pulling that spot into the fastest cache so future you doesn't have to wait.

Parameters

  • bmp — Handle to bitmap instance
  • pos — Bit position

Definition at line 319 of file rte_bitmap.h.

uint64_t rte_bitmap_get (struct rte_bitmap * bmp, uint32_t pos) [inline], [static]

Bitmap bit get 👀 — peeking at a single bit.

Parameters

  • bmp — Handle to bitmap instance
  • pos — Bit position

Returns

0 when bit is cleared, non-zero when bit is set ✨

Definition at line 340 of file rte_bitmap.h.

void rte_bitmap_set (struct rte_bitmap * bmp, uint32_t pos) [inline], [static]

Bitmap bit set 🌟 — flipping a bit ON, main character energy.

Parameters

  • bmp — Handle to bitmap instance
  • pos — Bit position

Definition at line 360 of file rte_bitmap.h.

void rte_bitmap_set_slab (struct rte_bitmap * bmp, uint32_t pos, uint64_t slab) [inline], [static]

Bitmap slab set 🧱 — setting a whole 64-bit slab at once, efficiency queen.

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 388 of file rte_bitmap.h.

void rte_bitmap_clear (struct rte_bitmap * bmp, uint32_t pos) [inline], [static]

Bitmap bit clear 🫧 — turning a bit OFF, clearing the vibes.

Parameters

  • bmp — Handle to bitmap instance
  • pos — Bit position

Definition at line 453 of file rte_bitmap.h.

int rte_bitmap_scan (struct rte_bitmap * bmp, uint32_t * pos, uint64_t * slab) [inline], [static]

Bitmap scan (with automatic wrap-around) 🔍💫 — the crown jewel, she scans and wraps around for you.

Parameters

  • bmp — Handle to bitmap instance
  • pos — When the function call returns 1, pos contains the position of the next set bit; otherwise pos is not modified.
  • slab — When the 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 the function call returns 0, slab is not modified.

Returns

0 if there is no bit set in the bitmap, 1 otherwise 🌈

Definition at line 562 of file rte_bitmap.h.

🧚 Author 🧚

Generated automatically by Doxygen for DPDK from the source code. (yes, a robot wrote it, and honestly? she ate 💅)

and that's the whole page bestie, you made it to the end 🎀 that was DPDK Version 25.11.3 of rte_bitmap.h(3) — go forth, set bits, clear bits, and remember: not thread safe, so keep your writer thread single and your readers patient. no cap, you're literally a bitmap expert now. periodt. 💖✨🦋

📦 where this page comes from