Detailed Description

This API provides support for buffers tailored towards packets.

Data Structures
union	mmpkt_metadata_ptr
	Union of pointer types for mmpkt metadata. More...

struct	mmpkt
	Core mmpkt data structure. More...

struct	mmpkt_ops
	Operations data structure for mmpkt. More...

struct	mmpkt_list
	Structure that can be used as the head of a linked list of mmpkts that counts its length. More...

Macros
#define	MM_FAST_ROUND_UP(x, m) ((((x)-1) \| ((m)-1)) + 1)
	Round `x` up to the next multiple of `m` (where `m` is a power of 2). More...

Functions
static void	mmpkt_init (struct mmpkt mmpkt, uint8_t buf, uint32_t buf_len, uint32_t data_start_offset, const struct mmpkt_ops *ops)
	Initialize an mmpkt header with the given values. More...

static struct mmpkt *	mmpkt_init_buf (uint8_t buf, uint32_t buf_len, uint32_t space_at_start, uint32_t space_at_end, uint32_t metadata_size, const struct mmpkt_ops ops)
	Initialize an mmpkt in a single buffer using the given values. More...

struct mmpkt *	mmpkt_alloc_on_heap (uint32_t space_at_start, uint32_t space_at_end, uint32_t metadata_size)
	Allocate a new mmpkt on the heap (using mmosal_malloc()). More...

void	mmpkt_release (struct mmpkt *mmpkt)
	Release a reference to the given mmpkt. More...

static struct mmpktview *	mmpkt_open (struct mmpkt *mmpkt)
	Open a view of the given mmpkt. More...

static void	mmpkt_close (struct mmpktview **view)
	Close the given view. More...

static struct mmpkt *	mmpkt_from_view (struct mmpktview *view)
	Get the underlying mmpkt from an opened view. More...

static uint8_t *	mmpkt_get_data_start (struct mmpktview *view)
	Gets a pointer to the start of the data in the mmpkt. More...

static uint8_t *	mmpkt_get_data_end (struct mmpktview *view)
	Gets a pointer to the end of the data in the mmpkt. More...

static uint32_t	mmpkt_peek_data_length (struct mmpkt *mmpkt)
	Peek the length of the data currently from an unopened mmpkt. More...

static uint32_t	mmpkt_get_data_length (struct mmpktview *view)
	Gets the length of the data currently in the mmpkt. More...

static uint32_t	mmpkt_available_space_at_start (struct mmpktview *view)
	Returns the amount of space available for prepending to the data in the buffer. More...

static uint32_t	mmpkt_available_space_at_end (struct mmpktview *view)
	Returns the amount of space available for appending to the data in the buffer. More...

static uint8_t *	mmpkt_prepend (struct mmpktview *view, uint32_t len)
	Reserves space immediately before the data currently in the given mmpkt and returns a pointer to this space. More...

static void	mmpkt_prepend_data (struct mmpktview view, const uint8_t data, uint32_t len)
	Prepends the given data to the data already in the mmpkt. More...

static uint8_t *	mmpkt_append (struct mmpktview *view, uint32_t len)
	Reserves space immediately after the data currently in the given mmpkt and returns a pointer to this space. More...

static void	mmpkt_append_data (struct mmpktview view, const uint8_t data, uint32_t len)
	Appends the given data to the data already in the mmpkt. More...

static union mmpkt_metadata_ptr	mmpkt_get_metadata (struct mmpkt *mmpkt)
	Retrieve a reference to the metadata associated with the given mmpkt. More...

static void	mmpkt_adjust_start_offset (struct mmpkt *mmpkt, int32_t delta)
	Adjust the start offset of an mmpkt. More...

static uint8_t *	mmpkt_remove_from_start (struct mmpktview *view, uint32_t len)
	Remove data from the start of the mmpkt. More...

static uint8_t *	mmpkt_remove_from_end (struct mmpktview *view, uint32_t len)
	Remove data from the end of the mmpkt. More...

static void	mmpkt_truncate (struct mmpkt *mmpkt, uint32_t len)
	Truncate the mmpkt data to the given length. More...

static struct mmpkt *	mmpkt_get_next (struct mmpkt *mmpkt)
	Get the `next` pointer embedded in the mmpkt. More...

static void	mmpkt_set_next (struct mmpkt mmpkt, struct mmpkt next)
	Set the `next` pointer embedded in the mmpkt. More...

static bool	mmpkt_contains_ptr (struct mmpktview view, const void ptr)
	Check whether the given pointer is pointing inside the mmpkt's buffer. More...

Macro Definition Documentation

◆ MM_FAST_ROUND_UP

#define MM_FAST_ROUND_UP	(	x,
		m
	)	((((x)-1) \| ((m)-1)) + 1)

Round x up to the next multiple of m (where m is a power of 2).

Warning: m must be a power of 2.

Definition at line 34 of file mmpkt.h.

Function Documentation

◆ mmpkt_adjust_start_offset()

static void mmpkt_adjust_start_offset	(	struct mmpkt *	mmpkt,
		int32_t	delta
	)

inlinestatic

Adjust the start offset of an mmpkt.

This is only allowable when the mmpkt is empty (i.e., data_len is 0).

Parameters

mmpkt	The mmpkt to operate on.
delta	Difference between the current start offset and the new start offset (this may be negative, but the new start offset must not be less than 0).

Definition at line 439 of file mmpkt.h.

◆ mmpkt_alloc_on_heap()

struct mmpkt * mmpkt_alloc_on_heap	(	uint32_t	space_at_start,
		uint32_t	space_at_end,
		uint32_t	metadata_size
	)

Allocate a new mmpkt on the heap (using mmosal_malloc()).

Parameters

space_at_start	Amount of space to reserve at start of buffer.
space_at_end	Amount of space to reserve at end of buffer.
metadata_size	Size of metadata (0 for no metadata).

Note: start_offset will be set to space_at_start, and buf_len will be the sum of space_at_start and space_at_end (rounded up to a multiple of 4).

Returns: newly allocated mmpkt on success or NULL on failure.

◆ mmpkt_append()

static uint8_t * mmpkt_append	(	struct mmpktview *	view,
		uint32_t	len
	)

inlinestatic

Reserves space immediately after the data currently in the given mmpkt and returns a pointer to this space.

For a function that also copies data in, see mmpkt_append_data().

Warning: len must be less than or equal to mmpkt_available_space_at_end().

Parameters

view	The opened mmpkt to operate on.
len	Length of data to be append.

Returns: a pointer to the place in the buffer where the data should be put.

Definition at line 395 of file mmpkt.h.

◆ mmpkt_append_data()

static void mmpkt_append_data	(	struct mmpktview *	view,
		const uint8_t *	data,
		uint32_t	len
	)

inlinestatic

Appends the given data to the data already in the mmpkt.

Warning: len must be less than or equal to mmpkt_available_space_at_start().

Parameters

view	The opened mmpkt to operate on.
data	The data to be prepended.
len	Length of data to be prepended.

Definition at line 413 of file mmpkt.h.

◆ mmpkt_available_space_at_end()

static uint32_t mmpkt_available_space_at_end ( struct mmpktview * view )

inlinestatic

Returns the amount of space available for appending to the data in the buffer.

Parameters

view	The opened mmpkt to operate on.

Returns: the available space in bytes.

Definition at line 337 of file mmpkt.h.

◆ mmpkt_available_space_at_start()

static uint32_t mmpkt_available_space_at_start ( struct mmpktview * view )

inlinestatic

Returns the amount of space available for prepending to the data in the buffer.

Parameters

view	The opened mmpkt to operate on.

Returns: the available space in bytes.

Definition at line 324 of file mmpkt.h.

◆ mmpkt_close()

static void mmpkt_close ( struct mmpktview ** view )

inlinestatic

Close the given view.

Parameters

[in,out] view Pointer to a variable holding the view to be closed. This will be modified to indicate it is no longer valid.

Definition at line 247 of file mmpkt.h.

◆ mmpkt_contains_ptr()

static bool mmpkt_contains_ptr	(	struct mmpktview *	view,
		const void *	ptr
	)

inlinestatic

Check whether the given pointer is pointing inside the mmpkt's buffer.

Note: This checks against the full buffer, which includes any unused regions at the beginning and end of the buffer which do not contain valid packet data.

Parameters

view	The opened mmpkt to operate on.
ptr	The pointer to check.

Returns: true if the pointer points into the buffer.

Definition at line 548 of file mmpkt.h.

◆ mmpkt_from_view()

static struct mmpkt * mmpkt_from_view ( struct mmpktview * view )

inlinestatic

Get the underlying mmpkt from an opened view.

Parameters

view	View of an mmpkt.

Returns: the underlying mmpkt.

Definition at line 259 of file mmpkt.h.

◆ mmpkt_get_data_end()

static uint8_t * mmpkt_get_data_end ( struct mmpktview * view )

inlinestatic

Gets a pointer to the end of the data in the mmpkt.

Parameters

view	The opened mmpkt to operate on.

Returns: a pointer to the end of the data in the mmpkt.

Definition at line 284 of file mmpkt.h.

◆ mmpkt_get_data_length()

static uint32_t mmpkt_get_data_length ( struct mmpktview * view )

inlinestatic

Gets the length of the data currently in the mmpkt.

Parameters

view	The opened mmpkt to operate on.

Returns: the length of the data currently in the mmpkt (note that this is different from the length of the available buffer space).

Definition at line 311 of file mmpkt.h.

◆ mmpkt_get_data_start()

static uint8_t * mmpkt_get_data_start ( struct mmpktview * view )

inlinestatic

Gets a pointer to the start of the data in the mmpkt.

Parameters

view	The opened mmpkt to operate on.

Returns: a pointer to the start of the data in the mmpkt.

Definition at line 271 of file mmpkt.h.

◆ mmpkt_get_metadata()

static union mmpkt_metadata_ptr mmpkt_get_metadata ( struct mmpkt * mmpkt )

static

Retrieve a reference to the metadata associated with the given mmpkt.

Parameters

mmpkt The mmpkt to operate on.

Returns: a reference to the mmpkt metadata.

Definition at line 426 of file mmpkt.h.

◆ mmpkt_get_next()

static struct mmpkt * mmpkt_get_next ( struct mmpkt * mmpkt )

inlinestatic

Get the next pointer embedded in the mmpkt.

Used by the mmpkt_list structure for making linked lists of mmpkts.

Parameters

mmpkt The mmpkt to operate on.

Returns: pointer to the next mmpkt in the chain (may be NULL).

Definition at line 519 of file mmpkt.h.

◆ mmpkt_init()

static void mmpkt_init	(	struct mmpkt *	mmpkt,
		uint8_t *	buf,
		uint32_t	buf_len,
		uint32_t	data_start_offset,
		const struct mmpkt_ops *	ops
	)

inlinestatic

Initialize an mmpkt header with the given values.

Parameters

mmpkt	mmpkt to initialize.
buf	Pointer to buffer.
buf_len	Length of `buf`.
data_start_offset	Initial value for `start_offset`.
ops	Operations data structure.

Definition at line 125 of file mmpkt.h.

◆ mmpkt_init_buf()

static struct mmpkt * mmpkt_init_buf	(	uint8_t *	buf,
		uint32_t	buf_len,
		uint32_t	space_at_start,
		uint32_t	space_at_end,
		uint32_t	metadata_size,
		const struct mmpkt_ops *	ops
	)

inlinestatic

Initialize an mmpkt in a single buffer using the given values.

Parameters

buf	Pointer to buffer.
buf_len	Length of `buf`.
space_at_start	Amount of space to reserve at start of buffer.
space_at_end	Amount of space to reserve at end of buffer.
metadata_size	Size of metadata (0 for no metadata).
ops	Operations data structure.

Note: buf_len must be large enough to contain the mmkpt header, the data buffer (rounded up to the nearest 4 bytes) and metadata (rounded up to the nearest 4 bytes).

Returns: a pointer to the initialized mmpkt (will be the same address as buf) or NULL on error (buf length too short).

Definition at line 152 of file mmpkt.h.

◆ mmpkt_open()

static struct mmpktview * mmpkt_open ( struct mmpkt * mmpkt )

inlinestatic

Open a view of the given mmpkt.

Packets must be opened before the contents of their buffer can be accessed. Most of the functions below expect to be passed an opened view of a packet to operate on.

The view must be closed by calling mmpkt_close() before the packet is released by mmpkt_release().

Parameters

mmpkt The mmpkt to be opened.

Returns: a pointer representing the opened view.

Definition at line 236 of file mmpkt.h.

◆ mmpkt_peek_data_length()

static uint32_t mmpkt_peek_data_length ( struct mmpkt * mmpkt )

inlinestatic

Peek the length of the data currently from an unopened mmpkt.

Parameters

mmpkt The unopened mmpkt to operate on.

Returns: the length of the data currently in the mmpkt (note that this is different from the length of the available buffer space).

Definition at line 298 of file mmpkt.h.

◆ mmpkt_prepend()

static uint8_t * mmpkt_prepend	(	struct mmpktview *	view,
		uint32_t	len
	)

inlinestatic

Reserves space immediately before the data currently in the given mmpkt and returns a pointer to this space.

For a function that also copies data in, see mmpkt_prepend_data().

Warning: len must be less than or equal to mmpkt_available_space_at_start().

Parameters

view	The opened mmpkt to operate on.
len	Length of data to be prepended.

Returns: a pointer to the place in the buffer where the data should be put.

Definition at line 356 of file mmpkt.h.

◆ mmpkt_prepend_data()

static void mmpkt_prepend_data	(	struct mmpktview *	view,
		const uint8_t *	data,
		uint32_t	len
	)

inlinestatic

Prepends the given data to the data already in the mmpkt.

Warning: len must be less than or equal to mmpkt_available_space_at_start().; The memory area pointed to by data must not overlap with the mmpkt data.

Parameters

view	The opened mmpkt to operate on.
data	The data to be prepended.
len	Length of data to be prepended.

Definition at line 376 of file mmpkt.h.

◆ mmpkt_release()

void mmpkt_release ( struct mmpkt * mmpkt )

Release a reference to the given mmpkt.

If this was the last reference (addition_ref_cnt was 0) then the mmpkt will be freed using the appropriate op callback.

Parameters

mmpkt The mmpkt to release reference to. May be NULL.

◆ mmpkt_remove_from_end()

static uint8_t * mmpkt_remove_from_end	(	struct mmpktview *	view,
		uint32_t	len
	)

inlinestatic

Remove data from the end of the mmpkt.

Parameters

view	The opened mmpkt to operate on.
len	Length of data to remove.

Returns: a pointer to the removed data or NULL if the mmpkt data length was less than len.

Definition at line 480 of file mmpkt.h.

◆ mmpkt_remove_from_start()

static uint8_t * mmpkt_remove_from_start	(	struct mmpktview *	view,
		uint32_t	len
	)

inlinestatic

Remove data from the start of the mmpkt.

Parameters

view	The opened mmpkt to operate on.
len	Length of data to remove.

Returns: a pointer to the removed data or NULL if the mmpkt data length was less than len.

Definition at line 454 of file mmpkt.h.

◆ mmpkt_set_next()

static void mmpkt_set_next	(	struct mmpkt *	mmpkt,
		struct mmpkt *	next
	)

inlinestatic

Set the next pointer embedded in the mmpkt.

Used by the mmpkt_list structure for making linked lists of mmpkts.

Parameters

mmpkt	The mmpkt to operate on.
next	The next mmpkt in the chain.

Definition at line 532 of file mmpkt.h.

◆ mmpkt_truncate()

static void mmpkt_truncate	(	struct mmpkt *	mmpkt,
		uint32_t	len
	)

inlinestatic

Truncate the mmpkt data to the given length.

Parameters

mmpkt	mmpkt to operate on.
len	New data length. (Must be less than or equal to the data length of the mmpkt).

Definition at line 504 of file mmpkt.h.

Detailed Description

Data Structures

Macros

Functions

Macro Definition Documentation

◆ MM_FAST_ROUND_UP

Function Documentation

◆ mmpkt_adjust_start_offset()

◆ mmpkt_alloc_on_heap()

◆ mmpkt_append()

◆ mmpkt_append_data()

◆ mmpkt_available_space_at_end()

◆ mmpkt_available_space_at_start()

◆ mmpkt_close()

◆ mmpkt_contains_ptr()

◆ mmpkt_from_view()

◆ mmpkt_get_data_end()

◆ mmpkt_get_data_length()

◆ mmpkt_get_data_start()

◆ mmpkt_get_metadata()

◆ mmpkt_get_next()

◆ mmpkt_init()

◆ mmpkt_init_buf()

◆ mmpkt_open()

◆ mmpkt_peek_data_length()

◆ mmpkt_prepend()

◆ mmpkt_prepend_data()

◆ mmpkt_release()

◆ mmpkt_remove_from_end()

◆ mmpkt_remove_from_start()

◆ mmpkt_set_next()

◆ mmpkt_truncate()