Network Buffer Management

Relevant source files

• axdriver_net/src/net_buf.rs

This document covers the sophisticated buffer allocation and management system used for high-performance network operations in the axdriver framework. The network buffer management provides efficient memory allocation, automatic resource cleanup, and optimized buffer layouts for packet processing.

For information about the network driver interface that uses these buffers, see Network Driver Interface. For details on how specific hardware implementations utilize this buffer system, see Hardware Implementations.

Buffer Structure and Layout

The core of the network buffer system is the NetBuf structure, which provides a flexible buffer layout optimized for network packet processing with separate header and packet regions.

NetBuf Memory Layout

flowchart TD
subgraph subGraph1["Size Tracking"]
    HL["header_len"]
    PL["packet_len"]
    CAP["capacity"]
end
subgraph subGraph0["NetBuf Memory Layout"]
    BP["buf_ptr"]
    H["Header Region"]
    P["Packet Region"]
    U["Unused Region"]
end

BP --> H
CAP --> U
H --> P
HL --> H
P --> U
PL --> P

The NetBuf structure implements a three-region memory layout where the header region stores protocol headers, the packet region contains the actual data payload, and unused space allows for future expansion without reallocation.

Sources: axdriver_net/src/net_buf.rs(L19 - L38) 

Core Buffer Operations

The buffer provides const methods for efficient access patterns and maintains safety through debug assertions that prevent region overlap.

Sources: axdriver_net/src/net_buf.rs(L43 - L103) 

Memory Pool Architecture

The NetBufPool provides high-performance buffer allocation through pre-allocated memory pools, eliminating the overhead of individual allocations during packet processing.

Pool Allocation Strategy

flowchart TD
subgraph subGraph2["Allocation Process"]
    ALLOC["alloc()"]
    OFFSET["pop offset from free_list"]
    NETBUF["create NetBuf"]
end
subgraph subGraph1["Memory Layout"]
    B0["Buffer 0"]
    B1["Buffer 1"]
    B2["Buffer 2"]
    BN["Buffer N"]
end
subgraph subGraph0["NetBufPool Structure"]
    POOL["pool: Vec"]
    FREELIST["free_list: Mutex>"]
    META["capacity, buf_len"]
end

ALLOC --> OFFSET
B0 --> B1
B1 --> B2
B2 --> BN
FREELIST --> OFFSET
META --> NETBUF
OFFSET --> NETBUF
POOL --> B0

The pool divides a large contiguous memory allocation into fixed-size buffers, maintaining a free list of available buffer offsets for O(1) allocation and deallocation operations.

Sources: axdriver_net/src/net_buf.rs(L133 - L165) 

Pool Configuration and Constraints

The pool validates buffer sizes against network protocol requirements and prevents invalid configurations through compile-time constants and runtime checks.

Sources: axdriver_net/src/net_buf.rs(L8 - L152) 

Buffer Lifecycle Management

The network buffer system implements RAII (Resource Acquisition Is Initialization) patterns for automatic memory management and integration with raw pointer operations for hardware drivers.

Allocation and Deallocation Flow

stateDiagram-v2
[*] --> PoolFree : "Pool initialized"
PoolFree --> Allocated : "alloc() / alloc_boxed()"
Allocated --> InUse : "NetBuf created"
InUse --> BufPtr : "into_buf_ptr()"
BufPtr --> Restored : "from_buf_ptr()"
Restored --> InUse : "NetBuf restored"
InUse --> Deallocated : "Drop trait"
BufPtr --> Deallocated : "Drop from ptr"
Deallocated --> PoolFree : "dealloc()"
PoolFree --> [*] : "Pool destroyed"

The lifecycle supports both high-level RAII management through Drop implementation and low-level pointer conversion for hardware driver integration.

Sources: axdriver_net/src/net_buf.rs(L105 - L131) 

Raw Pointer Integration

The buffer system provides conversion to and from NetBufPtr for integration with hardware drivers that require raw memory pointers:

This dual-mode operation allows the same buffer to be used efficiently in both safe Rust code and unsafe hardware interaction contexts.

Sources: axdriver_net/src/net_buf.rs(L104 - L123) 

Thread Safety and Concurrency

The buffer management system provides thread-safe operations through careful synchronization design:

flowchart TD
subgraph subGraph1["Concurrent Operations"]
    T1["Thread 1: alloc()"]
    T2["Thread 2: alloc()"]
    T3["Thread 3: drop()"]
end
subgraph subGraph0["Thread Safety Design"]
    NETBUF["NetBuf: Send + Sync"]
    POOL["NetBufPool: Arc"]
    FREELIST["free_list: Mutex>"]
end

NETBUF --> POOL
POOL --> FREELIST
T1 --> FREELIST
T2 --> FREELIST
T3 --> FREELIST

The NetBufPool uses Arc for shared ownership and Mutex protection of the free list, enabling concurrent allocation and deallocation from multiple threads while maintaining memory safety.

Sources: axdriver_net/src/net_buf.rs(L40 - L207) 

Integration with Network Drivers

The buffer management system integrates with the broader network driver ecosystem through standardized interfaces and efficient memory patterns designed for high-throughput network operations.

Buffer Type Relationships

flowchart TD
subgraph subGraph1["Driver Integration"]
    NETDRIVEROPS["NetDriverOps"]
    TRANSMIT["transmit()"]
    RECEIVE["receive()"]
    ALLOC["alloc_tx_buffer()"]
    RECYCLE["recycle_rx_buffer()"]
end
subgraph subGraph0["Buffer Types"]
    NETBUF["NetBuf"]
    NETBUFBOX["NetBufBox = Box"]
    NETBUFPTR["NetBufPtr"]
    POOL["NetBufPool"]
end

ALLOC --> NETBUFBOX
NETBUF --> NETBUFBOX
NETBUFBOX --> NETBUFPTR
NETDRIVEROPS --> ALLOC
NETDRIVEROPS --> RECEIVE
NETDRIVEROPS --> RECYCLE
NETDRIVEROPS --> TRANSMIT
POOL --> NETBUF
RECEIVE --> NETBUFBOX
RECYCLE --> NETBUFBOX
TRANSMIT --> NETBUFBOX

Network drivers utilize the buffer system through the NetDriverOps trait methods, providing standardized buffer allocation and recycling operations that maintain pool efficiency across different hardware implementations.

Sources: axdriver_net/src/net_buf.rs(L1 - L208)