SPSC (Single producer, single consumer) packet buffer API

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

Topics
	SPSC packet buffer flags

Data Structures
struct	spsc_pbuf_common
	First part of packet buffer control block. More...
struct	spsc_pbuf_ext_cache
	Remaining part of a packet buffer when cache is used. More...
struct	spsc_pbuf_ext_nocache
	Remaining part of a packet buffer when cache is not used. More...
struct	spsc_pbuf
	Single producer, single consumer packet buffer. More...

Macros
#define	CONFIG_SPSC_PBUF_REMOTE_DCACHE_LINE   0
#define	SPSC_PBUF_MAX_LEN   0xFF00
	Maximum packet length.

Functions
static uint32_t	spsc_pbuf_capacity (struct spsc_pbuf *pb)
	Get buffer capacity.
struct spsc_pbuf *	spsc_pbuf_init (void *buf, size_t blen, uint32_t flags)
	Initialize the packet buffer.
int	spsc_pbuf_write (struct spsc_pbuf *pb, const char *buf, uint16_t len)
	Write specified amount of data to the packet buffer.
int	spsc_pbuf_alloc (struct spsc_pbuf *pb, uint16_t len, char **buf)
	Allocate space in the packet buffer.
void	spsc_pbuf_commit (struct spsc_pbuf *pb, uint16_t len)
	Commit packet to the buffer.
int	spsc_pbuf_read (struct spsc_pbuf *pb, char *buf, uint16_t len)
	Read specified amount of data from the packet buffer.
uint16_t	spsc_pbuf_claim (struct spsc_pbuf *pb, char **buf)
	Claim packet from the buffer.
void	spsc_pbuf_free (struct spsc_pbuf *pb, uint16_t len)
	Free the packet to the buffer.
int	spsc_pbuf_get_utilization (struct spsc_pbuf *pb)
	Get maximum utilization of the packet buffer.

Detailed Description

Single producer, single consumer packet buffer API .

Macro Definition Documentation

CONFIG_SPSC_PBUF_REMOTE_DCACHE_LINE

#define CONFIG_SPSC_PBUF_REMOTE_DCACHE_LINE   0

#include <zephyr/sys/spsc_pbuf.h>

SPSC_PBUF_MAX_LEN

#define SPSC_PBUF_MAX_LEN   0xFF00

#include <zephyr/sys/spsc_pbuf.h>

Maximum packet length.

Function Documentation

spsc_pbuf_alloc()

int spsc_pbuf_alloc	(	struct spsc_pbuf *	pb,
		uint16_t	len,
		char **	buf )

#include <zephyr/sys/spsc_pbuf.h>

Allocate space in the packet buffer.

This function attempts to allocate len bytes of continuous memory within the packet buffer. An internal padding is added at the end of the buffer, if wrapping occurred during allocation. Apart from padding, allocation does not change the state of the buffer so if after allocation packet is not needed a commit is not needed.

Allocated buffer must be committed (spsc_pbuf_commit) to make the packet available for reading.

Packet buffer ensures that allocated buffers are 32 bit word aligned.

Note

If data cache is used, it is the user responsibility to write back the new data.

Parameters

[in]	pb	A buffer to which to write.
[in]	len	Allocation length. Must be positive. If less than SPSC_PBUF_MAX_LEN then if requested length cannot be allocated, an attempt to allocate largest possible is performed (which may include adding wrap padding). If SPSC_PBUF_MAX_LEN is used then an attempt to allocate largest buffer without applying wrap padding is performed.
[out]	buf	Location where buffer address is written on successful allocation.

Return values

non-negative	Amount of space that got allocated. Can be equal or smaller than p len.
-EINVAL	if len is forbidden.

spsc_pbuf_capacity()

static uint32_t spsc_pbuf_capacity ( struct spsc_pbuf * pb )

inlinestatic

#include <zephyr/sys/spsc_pbuf.h>

Get buffer capacity.

This value is the amount of data that is dedicated for storing packets. Since each packet is prefixed with 2 byte length header, longest possible packet is less than that.

Parameters

pb

A buffer.

Returns

Packet buffer capacity.

spsc_pbuf_claim()

uint16_t spsc_pbuf_claim	(	struct spsc_pbuf *	pb,
		char **	buf )

#include <zephyr/sys/spsc_pbuf.h>

Claim packet from the buffer.

It claims a single packet from the buffer in the order of the commitment by the spsc_pbuf_commit function. The first committed packet will be claimed first. The returned buffer is 32 bit word aligned and points to the continuous memory. Claimed packet must be freed using the spsc_pbuf_free function.

Note

If data cache is used, cache is invalidate on the packet.

Parameters

[in]	pb	A buffer from which packet will be claimed.
[in,out]	buf	A location where claimed packet address is written. It is 32 bit word aligned and points to the continuous memory.

Return values

0	No packets in the buffer.
positive	packet length.

spsc_pbuf_commit()

void spsc_pbuf_commit	(	struct spsc_pbuf *	pb,
		uint16_t	len )

#include <zephyr/sys/spsc_pbuf.h>

Commit packet to the buffer.

Commit a packet which was previously allocated (spsc_pbuf_alloc). If cache is used, cache writeback is performed on the written data.

Parameters

pb	A buffer to which to write.
len	Packet length. Must be equal or less than the length used for allocation.

spsc_pbuf_free()

void spsc_pbuf_free	(	struct spsc_pbuf *	pb,
		uint16_t	len )

#include <zephyr/sys/spsc_pbuf.h>

Free the packet to the buffer.

Packet must be claimed (spsc_pbuf_claim) before it can be freed.

Parameters

pb	A packet buffer from which packet was claimed.
len	Claimed packet length.

spsc_pbuf_get_utilization()

int spsc_pbuf_get_utilization

(

struct spsc_pbuf *

pb

)

#include <zephyr/sys/spsc_pbuf.h>

Get maximum utilization of the packet buffer.

Function can be used to tune the buffer size. Feature is enabled by CONFIG_SPSC_PBUF_UTILIZATION. Utilization is updated by the consumer.

Parameters

pb	A packet buffer.

Return values

-ENOTSUP	Feature not enabled.
non-negative	Maximum utilization.

spsc_pbuf_init()

struct spsc_pbuf * spsc_pbuf_init	(	void *	buf,
		size_t	blen,
		uint32_t	flags )

#include <zephyr/sys/spsc_pbuf.h>

Initialize the packet buffer.

This function initializes the packet buffer on top of a dedicated memory region.

Parameters

buf	Pointer to a memory region on which buffer is created. When cache is used it must be aligned to Z_SPSC_PBUF_DCACHE_LINE, otherwise it must be 32 bit word aligned.
blen	Length of the buffer. Must be large enough to contain the internal structure and at least two bytes of data (one is reserved for written messages length).
flags	Option flags. See SPSC packet buffer flags.

Return values

struct	spsc_pbuf* Pointer to the created buffer. The pointer points to the same address as buf.
NULL	Invalid buffer alignment.

spsc_pbuf_read()

int spsc_pbuf_read	(	struct spsc_pbuf *	pb,
		char *	buf,
		uint16_t	len )

#include <zephyr/sys/spsc_pbuf.h>

Read specified amount of data from the packet buffer.

Single read allows to read the message send by the single write. The provided p buf must be big enough to store the whole message.

It combines spsc_pbuf_claim and spsc_pbuf_free into a single call.

Parameters

pb	A buffer from which data will be read.
buf	Data pointer to which read data will be written. If NULL, len of stored message is returned.
len	Number of bytes to be read from the buffer.

Return values

int	Bytes read, negative error code on fail. Bytes to be read, if buf == NULL. -ENOMEM, if message can not fit in provided buf. -EAGAIN, if not whole message is ready yet.

spsc_pbuf_write()

int spsc_pbuf_write	(	struct spsc_pbuf *	pb,
		const char *	buf,
		uint16_t	len )

#include <zephyr/sys/spsc_pbuf.h>

Write specified amount of data to the packet buffer.

It combines spsc_pbuf_alloc and spsc_pbuf_commit into a single call.

Parameters

pb	A buffer to which to write.
buf	Pointer to the data to be written to the buffer.
len	Number of bytes to be written to the buffer. Must be positive but less than SPSC_PBUF_MAX_LEN.

Return values

int	Number of bytes written, negative error code on fail. -EINVAL, if len == 0. -ENOMEM, if len is bigger than the buffer can fit.