zephyr-netbuf

Zephyr Network Buffers (net_buf)

Overview

This skill provides expert knowledge on Zephyr's net_buf subsystem — a core memory management library used by networking, Bluetooth, and USB stacks. It covers pool creation, buffer lifecycle, data manipulation, and fragmentation patterns.

Key Concepts

Two Buffer Types:

• net_buf_simple — Lightweight, no reference counting, stack-allocatable. Use for constrained scenarios.
• net_buf — Full-featured with reference counting, fragmentation, user data. Use for passing through kernel objects (FIFOs).

Buffer Layout:

[__buf start] <-- headroom --> [data] <-- len --> [tailroom] <-- [__buf end]
                                  ^
                               data pointer

Workflow

1. Choose Buffer Type

Scenario	Use
Temporary parsing, stack allocation	net_buf_simple + NET_BUF_SIMPLE_DEFINE
Pool-based allocation, ref counting	net_buf + NET_BUF_POOL_DEFINE
Large/fragmented packets	net_buf with fragment chains

2. Pool Definition

For net_buf, define a pool at file scope:

#include <zephyr/net_buf.h>

/* Fixed-size buffers (most common) */
NET_BUF_POOL_DEFINE(my_pool,
    10,    /* count: number of buffers */
    128,   /* size: max data per buffer */
    4,     /* user_data_size: metadata per buffer */
    NULL); /* destroy callback (optional) */

Pool variants: See references/api.md for NET_BUF_POOL_VAR_DEFINE (variable size) and NET_BUF_POOL_HEAP_DEFINE (heap-backed).

3. Allocation & Lifecycle

/* Allocate (blocks until available or timeout) */
struct net_buf *buf = net_buf_alloc(&my_pool, K_FOREVER);

/* Reserve headroom for protocol headers */
net_buf_reserve(buf, HEADER_SIZE);

/* ... use buffer ... */

/* Release (returns to pool when refcount hits 0) */
net_buf_unref(buf);

Reference counting:

• net_buf_alloc() → refcount = 1
• net_buf_ref(buf) → increments refcount
• net_buf_unref(buf) → decrements; frees when 0