Inheritance diagram for NetStackMemoryManager:

Public Types
enum class	Lifetime { POOL_ALLOCATED , HEAP_ALLOCATED , CONSTANT , VOLATILE }

Public Member Functions
virtual net_stack_mem_buf_t *	alloc_heap (uint32_t size, uint32_t align)=0
	Allocates memory buffer from the heap.

virtual net_stack_mem_buf_t *	alloc_pool (uint32_t size, uint32_t align)=0
	Allocates memory buffer chain from a pool.

net_stack_mem_buf_t *	realloc_heap (net_stack_mem_buf_t *orig_buf, uint32_t new_align, std::optional< uint32_t > new_len=std::nullopt, std::optional< uint16_t > new_header_skip_size=std::nullopt)
	Reallocates a buffer or buffer chain as a contiguous (non-chained) heap buffer, freeing the original.

virtual uint32_t	get_pool_alloc_unit (uint32_t align) const =0
	Get memory buffer pool allocation unit.

uint32_t	get_pool_size ()
	Get memory buffer pool size.

virtual void	free (net_stack_mem_buf_t *buf)=0
	Free memory buffer chain.

virtual uint32_t	get_total_len (const net_stack_mem_buf_t *buf) const =0
	Return total length of a memory buffer chain.

virtual void	copy_to_buf (net_stack_mem_buf_t to_buf, const void ptr, uint32_t len)
	Copy from a raw buffer in memory to a memory buffer chain.

virtual uint32_t	copy_from_buf (void ptr, uint32_t len, const net_stack_mem_buf_t from_buf) const
	Copy from a memory buffer chain to a raw buffer in memory.

virtual void	cat (net_stack_mem_buf_t to_buf, net_stack_mem_buf_t cat_buf)=0
	Concatenate two memory buffer chains.

virtual net_stack_mem_buf_t *	get_next (const net_stack_mem_buf_t *buf) const =0
	Returns the next buffer.

size_t	count_buffers (const net_stack_mem_buf_t *buf)
	Count the number of buffers in a buffer chain.

virtual void *	get_ptr (const net_stack_mem_buf_t *buf) const =0
	Return pointer to the payload of the buffer.

virtual uint32_t	get_len (const net_stack_mem_buf_t *buf) const =0
	Return payload size of this individual buffer (NOT including any chained buffers)

virtual void	set_len (net_stack_mem_buf_t *buf, uint32_t len)=0
	Sets the payload size of the buffer.

virtual void	skip_header_space (net_stack_mem_buf_t *buf, int32_t amount)=0
	Skips (or un-skips) header space from the buffer.

void	restore_header_space (net_stack_mem_buf_t *buf, const int32_t amount)
	Restores previously skipped header space to the buffer.

virtual int32_t	get_header_skip_size (net_stack_mem_buf_t *buf)=0
	Get the total number of header bytes that are currently being skipped.

virtual Lifetime	get_lifetime (net_stack_mem_buf_t const *buf) const =0
	Gets the lifetime of the buffer.

void	set_on_pool_space_avail_cb (mbed::Callback< void()> cb)
	Set callback which will be called when pool space becomes available.

Protected Attributes
mbed::Callback< void()>	onPoolSpaceAvailCallback
	Callback which shall be called (if set) by the implementation after one or more buffer spaces become free in the pool.

Detailed Description

Definition at line 55 of file NetStackMemoryManager.h.

Member Enumeration Documentation

◆ Lifetime

enum class Lifetime

strong

Enumerator
POOL_ALLOCATED	Allocated from the memory manager's pool.
HEAP_ALLOCATED	Allocated from the memory manager's heap.
CONSTANT	Buffer points to constant data (e.g. in ROM) that will live forever.
VOLATILE	Buffer points to data from the application that will not live past the current network stack call.

Definition at line 303 of file NetStackMemoryManager.h.

Member Function Documentation

◆ alloc_heap()

virtual net_stack_mem_buf_t * alloc_heap	(	uint32_t	size,
		uint32_t	align
	)

pure virtual

Allocates memory buffer from the heap.

Memory buffer allocated from heap is always contiguous and can be arbitrary size.

Parameters

size	Size of the memory to allocate in bytes
align	Memory alignment requirement in bytes

Returns: Allocated memory buffer, or NULL in case of error

Implemented in NanostackMemoryManager.

◆ alloc_pool()

virtual net_stack_mem_buf_t * alloc_pool	(	uint32_t	size,
		uint32_t	align
	)

pure virtual

Allocates memory buffer chain from a pool.

Memory allocated from pool is contiguous if size is equal or less than (aligned) allocation unit, otherwise may be chained. Will typically come from fixed-size packet pool memory.

Parameters

size	Total size of the memory to allocate in bytes
align	Memory alignment requirement for each buffer in bytes

Returns: Allocated memory buffer chain, or NULL in case of error

Implemented in NanostackMemoryManager.

◆ realloc_heap()

net_stack_mem_buf_t * realloc_heap	(	net_stack_mem_buf_t *	orig_buf,
		uint32_t	new_align,
		std::optional< uint32_t >	new_len = `std::nullopt`,
		std::optional< uint16_t >	new_header_skip_size = `std::nullopt`
	)

Reallocates a buffer or buffer chain as a contiguous (non-chained) heap buffer, freeing the original.

Only the visible data in the source buffer is copied, not any skipped headers. Data from chained buffers will be copied.

Parameters

orig_buf	Original buffer. Will be freed whether or not the new buffer is allocated.
new_align	Alignment to allocate the new buffer with
new_len	If set, this length will be used instead of the buffer's original length
new_header_skip_size	If set, this header skip size will be set on the new buffer. If unset, no header skip will be set

Returns: Pointer to new buffer, or nullptr if allocation failed.

◆ get_pool_alloc_unit()

virtual uint32_t get_pool_alloc_unit ( uint32_t align ) const

pure virtual

Get memory buffer pool allocation unit.

Returns the maximum size of contiguous memory that can be allocated from a pool.

Parameters

align Memory alignment requirement in bytes

Returns: Contiguous memory size

Implemented in NanostackMemoryManager.

◆ get_pool_size()

uint32_t get_pool_size ( )

Get memory buffer pool size.

Returns: The number of pool buffers that can be allocated at any one time

Definition at line 123 of file NetStackMemoryManager.h.

◆ free()

virtual void free ( net_stack_mem_buf_t * buf )

pure virtual

Free memory buffer chain.

Frees all buffers from the chained list.

Parameters

buf	Memory buffer chain to be freed.

Implemented in NanostackMemoryManager.

◆ get_total_len()

virtual uint32_t get_total_len ( const net_stack_mem_buf_t * buf ) const

pure virtual

Return total length of a memory buffer chain.

Returns a total length of this buffer and any following buffers in the chain.

Parameters

buf	Memory buffer chain

Returns: Total length in bytes

Implemented in NanostackMemoryManager.

◆ copy_to_buf()

virtual void copy_to_buf	(	net_stack_mem_buf_t *	to_buf,
		const void *	ptr,
		uint32_t	len
	)

virtual

Copy from a raw buffer in memory to a memory buffer chain.

Copies data to a buffer chain. Copy operation does not adjust the lengths of the copied-to memory buffer chain, so chain total length must match the copied length.

Parameters

to_buf	Memory buffer chain to copy to
ptr	Pointer to data
len	Data length

◆ copy_from_buf()

virtual uint32_t copy_from_buf	(	void *	ptr,
		uint32_t	len,
		const net_stack_mem_buf_t *	from_buf
	)		const

virtual

Copy from a memory buffer chain to a raw buffer in memory.

Header skip bytes are processed, so the copy will begin AFTER the header bytes of from_buf

Parameters

len	Data length
ptr	Pointer to data
from_buf	Memory buffer chain to copy from

Returns: Length of the data that was copied

◆ cat()

virtual void cat	(	net_stack_mem_buf_t *	to_buf,
		net_stack_mem_buf_t *	cat_buf
	)

pure virtual

Concatenate two memory buffer chains.

Concatenates buffer chain to end of the other buffer chain. Concatenated-to buffer total length is adjusted accordingly. cat_buf must point to the start of a the chain. After concatenation to_buf's chain now owns those buffers, and they will be freed when the to_buf chain is freed.

Warning: It is forbidden for cat_buf to have skipped header bytes.

Parameters

to_buf	Memory buffer chain to concatenate to
cat_buf	Memory buffer chain to concatenate

Implemented in NanostackMemoryManager.

◆ get_next()

virtual net_stack_mem_buf_t * get_next ( const net_stack_mem_buf_t * buf ) const

pure virtual

Returns the next buffer.

Returns the next buffer from the memory buffer chain.

Parameters

buf	Memory buffer

Returns: The next memory buffer, or NULL if last

Implemented in NanostackMemoryManager.

◆ count_buffers()

size_t count_buffers ( const net_stack_mem_buf_t * buf )

Count the number of buffers in a buffer chain.

Parameters

buf	Memory buffer

Returns: The number of buffers in the chain

Definition at line 207 of file NetStackMemoryManager.h.

◆ get_ptr()

virtual void * get_ptr ( const net_stack_mem_buf_t * buf ) const

pure virtual

Return pointer to the payload of the buffer.

Note that this is affected by the current header skip size (see below)

Parameters

buf	Memory buffer

Returns: Pointer to the payload

Implemented in NanostackMemoryManager.

◆ get_len()

virtual uint32_t get_len ( const net_stack_mem_buf_t * buf ) const

pure virtual

Return payload size of this individual buffer (NOT including any chained buffers)

Note that this is affected by the current header skip size (see below)

Parameters

buf	Memory buffer

Returns: Size in bytes

Implemented in NanostackMemoryManager.

◆ set_len()

virtual void set_len	(	net_stack_mem_buf_t *	buf,
		uint32_t	len
	)

pure virtual

Sets the payload size of the buffer.

The allocated payload size will not change. It is not permitted to change the length of a buffer that is not the first (or only) in a chain.

Note that this is affected by the current header skip size (see below)

*Note as of Dec 2024: Different implementations (Nanostack vs LwIP) disagree about how to implement this operation. Specifically, if called on the head of a buffer chain, the LwIP implementation allows changing the length of the chain as a whole. However, the Nanostack implementation does not and only can change the length of the head buffer. For fear of breaking existing code, I do not want to change this behavior. So, if constructing a buffer chain, it is safest to set the buffer lengths first before building the chain.

Parameters

buf	Memory buffer
len	Payload size, must be less or equal to the allocated size

Implemented in NanostackMemoryManager.

◆ skip_header_space()

virtual void skip_header_space	(	net_stack_mem_buf_t *	buf,
		int32_t	amount
	)

pure virtual

Skips (or un-skips) header space from the buffer.

Skipping n bytes of header space causes the buffer's payload pointer to refer to a location n bytes after the base address of the packet buffer, and the length of the buffer to be decreased by n.

This is commonly used to skip protocol headers in network packets. For example, if you have an Ethernet frame, skipping 14 bytes of header space will cause the "start" of the packet buffer to point to the IP header instead.

Multiple calls to this function add together, so for example if you first skip 14 bytes, then -4, then 10, the result will be 20 total bytes of skipped header.

Parameters

buf	Buffer to operate on.
amount	Amount of header space to skip. Negative values are allowed and cause previously skipped header space to be removed.

Warning: Skipping a larger total header space than the size of the first buffer in the chain, or skipping a negative total header space, results in undefined behavior.

Implemented in NanostackMemoryManager.

◆ restore_header_space()

void restore_header_space	(	net_stack_mem_buf_t *	buf,
		const int32_t	amount
	)

Restores previously skipped header space to the buffer.

This function is the inverse of skip_header_space().

Parameters

buf	Buffer to operate on.
amount	Amount of header space to skip. Negative values are allowed and cause previously skipped header space to be removed.

Definition at line 289 of file NetStackMemoryManager.h.

◆ get_header_skip_size()

virtual int32_t get_header_skip_size ( net_stack_mem_buf_t * buf )

pure virtual

Get the total number of header bytes that are currently being skipped.

This is the aggregate result of all skip_header_space() / restore_header_space() calls.

Parameters

buf	Buffer to operate on.

Implemented in NanostackMemoryManager.

◆ get_lifetime()

virtual Lifetime get_lifetime ( net_stack_mem_buf_t const * buf ) const

pure virtual

Gets the lifetime of the buffer.

Parameters

buf	Memory buffer

Implemented in NanostackMemoryManager.

◆ set_on_pool_space_avail_cb()

void set_on_pool_space_avail_cb ( mbed::Callback< void()> cb )

Set callback which will be called when pool space becomes available.

Warning: The callback could be called from any thread, and should make no assumptions about being in the same thread as anything else.

Parameters

cb	Callback to call

Definition at line 325 of file NetStackMemoryManager.h.

Field Documentation

◆ onPoolSpaceAvailCallback

mbed::Callback<void()> onPoolSpaceAvailCallback

protected

Callback which shall be called (if set) by the implementation after one or more buffer spaces become free in the pool.

This is used by zero-copy Ethernet MACs as a hint that now is a good time to allocate fresh buffers off the pool into Ethernet descriptors. It is legal to call this function if you aren't totally sure new memory is available – the mac will try to allocate more buffers, and if it can't, oh well. However, it is not legal for memory to become available without a call to this function. Such a situation might lead to a lockup of the MAC due to not having memory allocated for Rx.

Definition at line 65 of file NetStackMemoryManager.h.

Public Types

Public Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ Lifetime

Member Function Documentation

◆ alloc_heap()

◆ alloc_pool()

◆ realloc_heap()

◆ get_pool_alloc_unit()

◆ get_pool_size()

◆ free()

◆ get_total_len()

◆ copy_to_buf()

◆ copy_from_buf()

◆ cat()

◆ get_next()

◆ count_buffers()

◆ get_ptr()

◆ get_len()

◆ set_len()

◆ skip_header_space()

◆ restore_header_space()

◆ get_header_skip_size()

◆ get_lifetime()

◆ set_on_pool_space_avail_cb()

Field Documentation

◆ onPoolSpaceAvailCallback