Chained Memory Buffers

Classes
struct	os_mbuf_pool
struct	os_mbuf_pkthdr
struct	os_mbuf
struct	os_mqueue

Macros
#define	OS_MBUF_PKTHDR(__om)
#define	OS_MBUF_PKTHDR_TO_MBUF(__hdr)    (struct os_mbuf *)(void *)((uint8_t *)(__hdr) - sizeof(struct os_mbuf))
#define	OS_MBUF_PKTLEN(__om)   (OS_MBUF_PKTHDR(__om)->omp_len)
#define	OS_MBUF_DATA(__om, __type)    (__type) ((__om)->om_data)
#define	OS_MBUF_USRHDR(om)
#define	OS_MBUF_USRHDR_LEN(om)    ((om)->om_pkthdr_len - sizeof (struct os_mbuf_pkthdr))
#define	OS_MBUF_LEADINGSPACE(__om)   _os_mbuf_leadingspace(__om)
#define	OS_MBUF_TRAILINGSPACE(__om)   _os_mbuf_trailingspace(__om)

Functions
int	os_mqueue_init (struct os_mqueue *mq, ble_npl_event_fn *ev_cb, void *arg)
struct os_mbuf *	os_mqueue_get (struct os_mqueue *)
int	os_mqueue_put (struct os_mqueue *, struct ble_npl_eventq *, struct os_mbuf *)
int	os_msys_register (struct os_mbuf_pool *)
struct os_mbuf *	os_msys_get (uint16_t dsize, uint16_t leadingspace)
void	os_msys_reset (void)
struct os_mbuf *	os_msys_get_pkthdr (uint16_t dsize, uint16_t user_hdr_len)
int	os_msys_count (void)
int	os_msys_num_free (void)
int	os_mbuf_pool_init (struct os_mbuf_pool *, struct os_mempool *mp, uint16_t, uint16_t)
struct os_mbuf *	os_mbuf_get (struct os_mbuf_pool *omp, uint16_t)
struct os_mbuf *	os_mbuf_get_pkthdr (struct os_mbuf_pool *omp, uint8_t pkthdr_len)
struct os_mbuf *	os_mbuf_dup (struct os_mbuf *m)
struct os_mbuf *	os_mbuf_off (const struct os_mbuf *om, int off, uint16_t *out_off)
uint16_t	os_mbuf_len (const struct os_mbuf *om)
	Calculates the length of an mbuf chain.
int	os_mbuf_append (struct os_mbuf *m, const void *, uint16_t)
int	os_mbuf_appendfrom (struct os_mbuf *dst, const struct os_mbuf *src, uint16_t src_off, uint16_t len)
int	os_mbuf_free (struct os_mbuf *mb)
int	os_mbuf_free_chain (struct os_mbuf *om)
void	os_mbuf_adj (struct os_mbuf *mp, int req_len)
int	os_mbuf_cmpf (const struct os_mbuf *om, int off, const void *data, int len)
int	os_mbuf_cmpm (const struct os_mbuf *om1, uint16_t offset1, const struct os_mbuf *om2, uint16_t offset2, uint16_t len)
struct os_mbuf *	os_mbuf_prepend (struct os_mbuf *om, int len)
struct os_mbuf *	os_mbuf_prepend_pullup (struct os_mbuf *om, uint16_t len)
int	os_mbuf_copyinto (struct os_mbuf *om, int off, const void *src, int len)
void	os_mbuf_concat (struct os_mbuf *first, struct os_mbuf *second)
void *	os_mbuf_extend (struct os_mbuf *om, uint16_t len)
struct os_mbuf *	os_mbuf_pullup (struct os_mbuf *om, uint16_t len)
struct os_mbuf *	os_mbuf_trim_front (struct os_mbuf *om)
int	os_mbuf_widen (struct os_mbuf *om, uint16_t off, uint16_t len)
struct os_mbuf *	os_mbuf_pack_chains (struct os_mbuf *m1, struct os_mbuf *m2)

Detailed Description

Macro Definition Documentation

OS_MBUF_DATA

#define OS_MBUF_DATA	(		__om,
			__type
	)		(__type) ((__om)->om_data)

Access the data of a mbuf, and cast it to type

Parameters

__om	The mbuf to access, and cast
__type	The type to cast it to

OS_MBUF_LEADINGSPACE

#define OS_MBUF_LEADINGSPACE

(

__om

)

_os_mbuf_leadingspace(__om)

Returns the leading space (space at the beginning) of the mbuf. Works on both packet header, and regular mbufs, as it accounts for the additional space allocated to the packet header.

Parameters

__omp	Is the mbuf pool (which contains packet header length.)
__om	Is the mbuf in that pool to get the leadingspace for

Returns

Amount of leading space available in the mbuf

OS_MBUF_PKTHDR

#define OS_MBUF_PKTHDR

(

__om

)

Value:

    ((struct os_mbuf_pkthdr *)     \
    (void *)((uint8_t *)&(__om)->om_data + sizeof(struct os_mbuf)))

Get a packet header pointer given an mbuf pointer

OS_MBUF_PKTHDR_TO_MBUF

#define OS_MBUF_PKTHDR_TO_MBUF

(

__hdr

)

(struct os_mbuf *)(void *)((uint8_t *)(__hdr) - sizeof(struct os_mbuf))

Given a mbuf packet header pointer, return a pointer to the mbuf

OS_MBUF_PKTLEN

#define OS_MBUF_PKTLEN

(

__om

)

(OS_MBUF_PKTHDR(__om)->omp_len)

Gets the length of an entire mbuf chain. The specified mbuf must have a packet header.

OS_MBUF_TRAILINGSPACE

#define OS_MBUF_TRAILINGSPACE

(

__om

)

_os_mbuf_trailingspace(__om)

Returns the trailing space (space at the end) of the mbuf. Works on both packet header and regular mbufs.

Parameters

__omp	The mbuf pool for this mbuf
__om	Is the mbuf in that pool to get trailing space for

Returns

The amount of trailing space available in the mbuf

OS_MBUF_USRHDR

#define OS_MBUF_USRHDR

(

om

)

Value:

    (void *)((uint8_t *)om + sizeof (struct os_mbuf) +  \
             sizeof (struct os_mbuf_pkthdr))

Access the "user header" in the head of an mbuf chain.

Parameters

om	Pointer to the head of an mbuf chain.

OS_MBUF_USRHDR_LEN

#define OS_MBUF_USRHDR_LEN

(

om

)

((om)->om_pkthdr_len - sizeof (struct os_mbuf_pkthdr))

Retrieves the length of the user header in an mbuf.

Parameters

om	Pointer to the mbuf to query.

Function Documentation

os_mbuf_adj()

void os_mbuf_adj	(	struct os_mbuf *	mp,
		int	req_len
	)

Adjust the length of a mbuf, trimming either from the head or the tail of the mbuf.

Parameters

mp	The mbuf chain to adjust
req_len	The length to trim from the mbuf. If positive, trims from the head of the mbuf, if negative, trims from the tail of the mbuf.

os_mbuf_append()

int os_mbuf_append	(	struct os_mbuf *	m,
		const void *	data,
		uint16_t	len
	)

Append data onto a mbuf

Parameters

om	The mbuf to append the data onto
data	The data to append onto the mbuf
len	The length of the data to append

Returns

0 on success, and an error code on failure

os_mbuf_appendfrom()

int os_mbuf_appendfrom	(	struct os_mbuf *	dst,
		const struct os_mbuf *	src,
		uint16_t	src_off,
		uint16_t	len
	)

Reads data from one mbuf and appends it to another. On error, the specified data range may be partially appended. Neither mbuf is required to contain an mbuf packet header.

Parameters

dst	The mbuf to append to.
src	The mbuf to copy data from.
src_off	The absolute offset within the source mbuf chain to read from.
len	The number of bytes to append.

Returns

0 on success; OS_EINVAL if the specified range extends beyond the end of the source mbuf chain.

os_mbuf_cmpf()

int os_mbuf_cmpf	(	const struct os_mbuf *	om,
		int	off,
		const void *	data,
		int	len
	)

Performs a memory compare of the specified region of an mbuf chain against a flat buffer.

Parameters

om	The start of the mbuf chain to compare.
off	The offset within the mbuf chain to start the comparison.
data	The flat buffer to compare.
len	The length of the flat buffer.

Returns

0 if both memory regions are identical; A memcmp return code if there is a mismatch; INT_MAX if the mbuf is too short.

os_mbuf_cmpm()

int os_mbuf_cmpm	(	const struct os_mbuf *	om1,
		uint16_t	offset1,
		const struct os_mbuf *	om2,
		uint16_t	offset2,
		uint16_t	len
	)

Compares the contents of two mbuf chains. The ranges of the two chains to be compared are specified via the two offset parameters and the len parameter. Neither mbuf chain is required to contain a packet header.

Parameters

om1	The first mbuf chain to compare.
offset1	The absolute offset within om1 at which to start the comparison.
om2	The second mbuf chain to compare.
offset2	The absolute offset within om2 at which to start the comparison.
len	The number of bytes to compare.

Returns

0 if both mbuf segments are identical; A memcmp() return code if the segment contents differ; INT_MAX if a specified range extends beyond the end of its corresponding mbuf chain.

os_mbuf_concat()

void os_mbuf_concat	(	struct os_mbuf *	first,
		struct os_mbuf *	second
	)

Attaches a second mbuf chain onto the end of the first. If the first chain contains a packet header, the header's length is updated. If the second chain has a packet header, its header is cleared.

Parameters

first	The mbuf chain being attached to.
second	The mbuf chain that gets attached.

os_mbuf_copyinto()

int os_mbuf_copyinto	(	struct os_mbuf *	om,
		int	off,
		const void *	src,
		int	len
	)

Copies the contents of a flat buffer into an mbuf chain, starting at the specified destination offset. If the mbuf is too small for the source data, it is extended as necessary. If the destination mbuf contains a packet header, the header length is updated.

Parameters

omp	The mbuf pool to allocate from.
om	The mbuf chain to copy into.
off	The offset within the chain to copy to.
src	The source buffer to copy from.
len	The number of bytes to copy.

Returns

0 on success; nonzero on failure.

os_mbuf_dup()

struct os_mbuf * os_mbuf_dup

(

struct os_mbuf *

m

)

Duplicate a chain of mbufs. Return the start of the duplicated chain.

Parameters

omp	The mbuf pool to duplicate out of
om	The mbuf chain to duplicate

Returns

A pointer to the new chain of mbufs

os_mbuf_extend()

void * os_mbuf_extend	(	struct os_mbuf *	om,
		uint16_t	len
	)

Increases the length of an mbuf chain by the specified amount. If there is not sufficient room in the last buffer, a new buffer is allocated and appended to the chain. It is an error to request more data than can fit in a single buffer.

Parameters

omp
om	The head of the chain to extend.
len	The number of bytes to extend by.

Returns

A pointer to the new data on success; NULL on failure.

os_mbuf_free()

int os_mbuf_free

(

struct os_mbuf *

mb

)

Release a mbuf back to the pool

Parameters

omp	The Mbuf pool to release back to
om	The Mbuf to release back to the pool

Returns

0 on success, -1 on failure

os_mbuf_free_chain()

int os_mbuf_free_chain

(

struct os_mbuf *

om

)

Free a chain of mbufs

Parameters

omp	The mbuf pool to free the chain of mbufs into
om	The starting mbuf of the chain to free back into the pool

Returns

0 on success, -1 on failure

os_mbuf_get()

struct os_mbuf * os_mbuf_get	(	struct os_mbuf_pool *	omp,
		uint16_t	leadingspace
	)

Get an mbuf from the mbuf pool. The mbuf is allocated, and initialized prior to being returned.

Parameters

omp	The mbuf pool to return the packet from
leadingspace	The amount of leadingspace to put before the data section by default.

Returns

An initialized mbuf on success, and NULL on failure.

os_mbuf_get_pkthdr()

struct os_mbuf * os_mbuf_get_pkthdr	(	struct os_mbuf_pool *	omp,
		uint8_t	pkthdr_len
	)

Allocate a new packet header mbuf out of the os_mbuf_pool.

Parameters

omp	The mbuf pool to allocate out of
user_pkthdr_len	The packet header length to reserve for the caller.

Returns

A freshly allocated mbuf on success, NULL on failure.

os_mbuf_len()

uint16_t os_mbuf_len

(

const struct os_mbuf *

om

)

Calculates the length of an mbuf chain.

Calculates the length of an mbuf chain. If the mbuf contains a packet header, you should use OS_MBUF_PKTLEN() as a more efficient alternative to this function.

Parameters

om	The mbuf to measure.

Returns

The length, in bytes, of the provided mbuf chain.

os_mbuf_off()

struct os_mbuf * os_mbuf_off	(	const struct os_mbuf *	om,
		int	off,
		uint16_t *	out_off
	)

Locates the specified absolute offset within an mbuf chain. The offset can be one past than the total length of the chain, but no greater.

Parameters

om	The start of the mbuf chain to seek within.
off	The absolute address to find.
out_off	On success, this points to the relative offset within the returned mbuf.

Returns

The mbuf containing the specified offset on success. NULL if the specified offset is out of bounds.

os_mbuf_pack_chains()

struct os_mbuf * os_mbuf_pack_chains	(	struct os_mbuf *	m1,
		struct os_mbuf *	m2
	)

Creates a single chained mbuf from m1 and m2 utilizing all the available buffer space in all mbufs in the resulting chain. In other words, ensures there is no leading space in any mbuf in the resulting chain and trailing space only in the last mbuf in the chain. Mbufs from either chain may be freed if not needed. No mbufs are allocated. Note that mbufs from m2 are added to the end of m1. If m1 has a packet header, it is retained and length updated. If m2 has a packet header it is discarded. If m1 is NULL, NULL is returned and m2 is left untouched.

Parameters

m1	Pointer to first mbuf chain to pack
m2	Pointer to second mbuf chain to pack

Returns

struct os_mbuf* Pointer to resulting mbuf chain

os_mbuf_pool_init()

int os_mbuf_pool_init	(	struct os_mbuf_pool *	omp,
		struct os_mempool *	mp,
		uint16_t	buf_len,
		uint16_t	nbufs
	)

Initialize a pool of mbufs.

Parameters

omp	The mbuf pool to initialize
mp	The memory pool that will hold this mbuf pool
buf_len	The length of the buffer itself.
nbufs	The number of buffers in the pool

Returns

0 on success, error code on failure.

os_mbuf_prepend()

struct os_mbuf * os_mbuf_prepend	(	struct os_mbuf *	om,
		int	len
	)

Increases the length of an mbuf chain by adding data to the front. If there is insufficient room in the leading mbuf, additional mbufs are allocated and prepended as necessary. If this function fails to allocate an mbuf, the entire chain is freed.

The specified mbuf chain does not need to contain a packet header.

Parameters

omp	The mbuf pool to allocate from.
om	The head of the mbuf chain.
len	The number of bytes to prepend.

Returns

The new head of the chain on success; NULL on failure.

os_mbuf_prepend_pullup()

struct os_mbuf * os_mbuf_prepend_pullup	(	struct os_mbuf *	om,
		uint16_t	len
	)

Prepends a chunk of empty data to the specified mbuf chain and ensures the chunk is contiguous. If either operation fails, the specified mbuf chain is freed and NULL is returned.

Parameters

om	The mbuf chain to prepend to.
len	The number of bytes to prepend and pullup.

Returns

The modified mbuf on success; NULL on failure (and the mbuf chain is freed).

os_mbuf_pullup()

struct os_mbuf * os_mbuf_pullup	(	struct os_mbuf *	om,
		uint16_t	len
	)

Rearrange a mbuf chain so that len bytes are contiguous, and in the data area of an mbuf (so that OS_MBUF_DATA() will work on a structure of size len.) Returns the resulting mbuf chain on success, free's it and returns NULL on failure.

If there is room, it will add up to "max_protohdr - len" extra bytes to the contiguous region, in an attempt to avoid being called next time.

Parameters

omp	The mbuf pool to take the mbufs out of
om	The mbuf chain to make contiguous
len	The number of bytes in the chain to make contiguous

Returns

The contiguous mbuf chain on success, NULL on failure.

os_mbuf_trim_front()

struct os_mbuf * os_mbuf_trim_front

(

struct os_mbuf *

om

)

Removes and frees empty mbufs from the front of a chain. If the chain contains a packet header, it is preserved.

Parameters

om	The mbuf chain to trim.

Returns

The head of the trimmed mbuf chain.

os_mbuf_widen()

int os_mbuf_widen	(	struct os_mbuf *	om,
		uint16_t	off,
		uint16_t	len
	)

Increases the length of an mbuf chain by inserting a gap at the specified offset. The contents of the gap are indeterminate. If the mbuf chain contains a packet header, its total length is increased accordingly.

This function never frees the provided mbuf chain.

Parameters

om	The mbuf chain to widen.
off	The offset at which to insert the gap.
len	The size of the gap to insert.

Returns

0 on success; SYS_[...] error code on failure.

os_mqueue_get()

struct os_mbuf * os_mqueue_get

(

struct os_mqueue *

mq

)

Remove and return a single mbuf from the mbuf queue. Does not block.

Parameters

mq	The mbuf queue to pull an element off of.

Returns

The next mbuf in the queue, or NULL if queue has no mbufs.

os_mqueue_init()

int os_mqueue_init	(	struct os_mqueue *	mq,
		ble_npl_event_fn *	ev_cb,
		void *	arg
	)

Initializes an mqueue. An mqueue is a queue of mbufs that ties to a particular task's event queue. Mqueues form a helper API around a common paradigm: wait on an event queue until at least one packet is available, then process a queue of packets.

When mbufs are available on the queue, an event OS_EVENT_T_MQUEUE_DATA will be posted to the task's mbuf queue.

Parameters

mq	The mqueue to initialize
ev_cb	The callback to associate with the mqeueue event. Typically, this callback pulls each packet off the mqueue and processes them.
arg	The argument to associate with the mqueue event.

Returns

0 on success, non-zero on failure.

os_mqueue_put()

int os_mqueue_put	(	struct os_mqueue *	mq,
		struct ble_npl_eventq *	evq,
		struct os_mbuf *	m
	)

Adds a packet (i.e. packet header mbuf) to an mqueue. The event associated with the mqueue gets posted to the specified eventq.

Parameters

mq	The mbuf queue to append the mbuf to.
evq	The event queue to post an event to.
m	The mbuf to append to the mbuf queue.

Returns

0 on success, non-zero on failure.

os_msys_count()

int os_msys_count

(

void

)

Count the number of blocks in all the mbuf pools that are allocated.

Returns

total number of blocks allocated in Msys

os_msys_get()

struct os_mbuf * os_msys_get	(	uint16_t	dsize,
		uint16_t	leadingspace
	)

Allocate a mbuf from msys. Based upon the data size requested, os_msys_get() will choose the mbuf pool that has the best fit.

Parameters

dsize	The estimated size of the data being stored in the mbuf
leadingspace	The amount of leadingspace to allocate in the mbuf

Returns

A freshly allocated mbuf on success, NULL on failure.

os_msys_get_pkthdr()

struct os_mbuf * os_msys_get_pkthdr	(	uint16_t	dsize,
		uint16_t	user_hdr_len
	)

Allocate a packet header structure from the MSYS pool. See os_msys_register() for a description of MSYS.

Parameters

dsize	The estimated size of the data being stored in the mbuf
user_hdr_len	The length to allocate for the packet header structure

Returns

A freshly allocated mbuf on success, NULL on failure.

os_msys_num_free()

int os_msys_num_free

(

void

)

Return the number of free blocks in Msys

Returns

Number of free blocks available in Msys

os_msys_register()

int os_msys_register

(

struct os_mbuf_pool *

new_pool

)

MSYS is a system level mbuf registry. Allows the system to share packet buffers amongst the various networking stacks that can be running simultaeneously.

Mbuf pools are created in the system initialization code, and then when a mbuf is allocated out of msys, it will try and find the best fit based upon estimated mbuf size.

os_msys_register() registers a mbuf pool with MSYS, and allows MSYS to allocate mbufs out of it.

Parameters

new_pool

The pool to register with MSYS

Returns

0 on success, non-zero on failure

os_msys_reset()

void os_msys_reset

(

void

)

De-registers all mbuf pools from msys.