MPSC (Multi producer, single consumer) packet buffer API

Multi producer, single consumer packet buffer API . More...

Topics
	MPSC (Multi producer, single consumer) packet header
	Multi producer, single consumer packet header .
	MPSC packet buffer flags

Data Structures
struct	mpsc_pbuf_buffer
	MPSC packet buffer structure. More...
struct	mpsc_pbuf_buffer_config
	MPSC packet buffer configuration. More...

Typedefs
typedef uint32_t(*	mpsc_pbuf_get_wlen) (const union mpsc_pbuf_generic *packet)
	Callback prototype for getting length of a packet.
typedef void(*	mpsc_pbuf_notify_drop) (const struct mpsc_pbuf_buffer *buffer, const union mpsc_pbuf_generic *packet)
	Callback called when packet is dropped.

Functions
void	mpsc_pbuf_init (struct mpsc_pbuf_buffer *buffer, const struct mpsc_pbuf_buffer_config *config)
	Initialize a packet buffer.
union mpsc_pbuf_generic *	mpsc_pbuf_alloc (struct mpsc_pbuf_buffer *buffer, size_t wlen, k_timeout_t timeout)
	Allocate a packet.
void	mpsc_pbuf_commit (struct mpsc_pbuf_buffer *buffer, union mpsc_pbuf_generic *packet)
	Commit a packet.
void	mpsc_pbuf_put_word (struct mpsc_pbuf_buffer *buffer, const union mpsc_pbuf_generic word)
	Put single word packet into a buffer.
void	mpsc_pbuf_put_word_ext (struct mpsc_pbuf_buffer *buffer, const union mpsc_pbuf_generic word, const void *data)
	Put a packet consisting of a word and a pointer.
void	mpsc_pbuf_put_data (struct mpsc_pbuf_buffer *buffer, const uint32_t *data, size_t wlen)
	Put a packet into a buffer.
const union mpsc_pbuf_generic *	mpsc_pbuf_claim (struct mpsc_pbuf_buffer *buffer)
	Claim the first pending packet.
void	mpsc_pbuf_free (struct mpsc_pbuf_buffer *buffer, const union mpsc_pbuf_generic *packet)
	Free a packet.
bool	mpsc_pbuf_is_pending (struct mpsc_pbuf_buffer *buffer)
	Check if there are any message pending.
void	mpsc_pbuf_get_utilization (struct mpsc_pbuf_buffer *buffer, uint32_t *size, uint32_t *now)
	Get current memory utilization.
int	mpsc_pbuf_get_max_utilization (struct mpsc_pbuf_buffer *buffer, uint32_t *max)
	Get maximum memory utilization.

Detailed Description

Multi producer, single consumer packet buffer API .

Typedef Documentation

mpsc_pbuf_get_wlen

typedef uint32_t(* mpsc_pbuf_get_wlen) (const union mpsc_pbuf_generic *packet)

#include <zephyr/sys/mpsc_pbuf.h>

Callback prototype for getting length of a packet.

Parameters

packet

User packet.

Returns

Size of the packet in 32 bit words.

mpsc_pbuf_notify_drop

typedef void(* mpsc_pbuf_notify_drop) (const struct mpsc_pbuf_buffer *buffer, const union mpsc_pbuf_generic *packet)

#include <zephyr/sys/mpsc_pbuf.h>

Callback called when packet is dropped.

Parameters

buffer	Packet buffer.
packet	Packet that is being dropped.

Function Documentation

mpsc_pbuf_alloc()

union mpsc_pbuf_generic * mpsc_pbuf_alloc	(	struct mpsc_pbuf_buffer *	buffer,
		size_t	wlen,
		k_timeout_t	timeout )

#include <zephyr/sys/mpsc_pbuf.h>

Allocate a packet.

If a buffer is configured to overwrite mode then if there is no space to allocate a new buffer, oldest packets are dropped. Otherwise allocation fails and null pointer is returned.

Parameters

buffer	Buffer.
wlen	Number of words to allocate.
timeout	Timeout. If called from thread context it will pend for given timeout if packet cannot be allocated before dropping the oldest or returning null.

Returns

Pointer to the allocated space or null if it cannot be allocated.

mpsc_pbuf_claim()

const union mpsc_pbuf_generic * mpsc_pbuf_claim

(

struct mpsc_pbuf_buffer *

buffer

)

#include <zephyr/sys/mpsc_pbuf.h>

Claim the first pending packet.

Parameters

buffer

Buffer.

Returns

Pointer to the claimed packet or null if none available.

mpsc_pbuf_commit()

void mpsc_pbuf_commit	(	struct mpsc_pbuf_buffer *	buffer,
		union mpsc_pbuf_generic *	packet )

#include <zephyr/sys/mpsc_pbuf.h>

Commit a packet.

Parameters

buffer	Buffer.
packet	Pointer to a packet allocated by mpsc_pbuf_alloc.

mpsc_pbuf_free()

void mpsc_pbuf_free	(	struct mpsc_pbuf_buffer *	buffer,
		const union mpsc_pbuf_generic *	packet )

#include <zephyr/sys/mpsc_pbuf.h>

Free a packet.

Parameters

buffer	Buffer.
packet	Packet.

mpsc_pbuf_get_max_utilization()

int mpsc_pbuf_get_max_utilization	(	struct mpsc_pbuf_buffer *	buffer,
		uint32_t *	max )

#include <zephyr/sys/mpsc_pbuf.h>

Get maximum memory utilization.

Parameters

[in,out]	buffer	Buffer.
[out]	max	Maximum buffer usage in bytes.

retval 0 if utilization data collected successfully. retval -ENOTSUP if Collecting utilization data is not supported.

mpsc_pbuf_get_utilization()

void mpsc_pbuf_get_utilization	(	struct mpsc_pbuf_buffer *	buffer,
		uint32_t *	size,
		uint32_t *	now )

#include <zephyr/sys/mpsc_pbuf.h>

Get current memory utilization.

Parameters

[in,out]	buffer	Buffer.
[out]	size	Buffer size in bytes.
[out]	now	Current buffer usage in bytes.

mpsc_pbuf_init()

void mpsc_pbuf_init	(	struct mpsc_pbuf_buffer *	buffer,
		const struct mpsc_pbuf_buffer_config *	config )

#include <zephyr/sys/mpsc_pbuf.h>

Initialize a packet buffer.

Parameters

buffer	Buffer.
config	Configuration.

mpsc_pbuf_is_pending()

bool mpsc_pbuf_is_pending

(

struct mpsc_pbuf_buffer *

buffer

)

#include <zephyr/sys/mpsc_pbuf.h>

Check if there are any message pending.

Parameters

buffer

Buffer.

Return values

true	if pending.
false	if no message is pending.

mpsc_pbuf_put_data()

void mpsc_pbuf_put_data	(	struct mpsc_pbuf_buffer *	buffer,
		const uint32_t *	data,
		size_t	wlen )

#include <zephyr/sys/mpsc_pbuf.h>

Put a packet into a buffer.

Copy data into a buffer. Note that 2 bits of a first word is used by the buffer.

Parameters

buffer	Buffer.
data	First word of data must contain MPSC_PBUF_HDR with valid bit set.
wlen	Packet size in words.

mpsc_pbuf_put_word()

void mpsc_pbuf_put_word	(	struct mpsc_pbuf_buffer *	buffer,
		const union mpsc_pbuf_generic	word )

#include <zephyr/sys/mpsc_pbuf.h>

Put single word packet into a buffer.

Function is optimized for storing a packet which fit into a single word. Note that 2 bits of that word is used by the buffer.

Parameters

buffer	Buffer.
word	Packet content consisting of MPSC_PBUF_HDR with valid bit set and data on remaining bits.

mpsc_pbuf_put_word_ext()

void mpsc_pbuf_put_word_ext	(	struct mpsc_pbuf_buffer *	buffer,
		const union mpsc_pbuf_generic	word,
		const void *	data )

#include <zephyr/sys/mpsc_pbuf.h>

Put a packet consisting of a word and a pointer.

• Function is optimized for storing packet consisting of a word and a pointer. Note that 2 bits of a first word is used by the buffer.

Parameters

buffer	Buffer.
word	First word of a packet consisting of MPSC_PBUF_HDR with valid bit set and data on remaining bits.
data	User data.