Packed Buffer API

Packed buffer API. More...

Data Structures
struct	pbuf_cfg
	Control block of packet buffer. More...
struct	pbuf_data
	Data block of the packed buffer. More...
struct	pbuf
	Scure packed buffer. More...

Macros
#define	PBUF_PACKET_LEN_SZ   sizeof(uint32_t)
	Size of packet length field.
#define	PBUF_CFG_INIT(mem_addr, size, dcache_align)
	Macro for configuration initialization.
#define	PBUF_HEADER_OVERHEAD(dcache_align)    (MAX(dcache_align, _PBUF_IDX_SIZE) + _PBUF_IDX_SIZE)
	Macro calculates memory overhead taken by the header in shared memory.
#define	PBUF_DEFINE(name, mem_addr, size, dcache_align)
	Statically define and initialize pbuf.

Functions
int	pbuf_init (struct pbuf *pb)
	Initialize the packet buffer.
int	pbuf_write (struct pbuf *pb, const char *buf, uint16_t len)
	Write specified amount of data to the packet buffer.
int	pbuf_read (struct pbuf *pb, char *buf, uint16_t len)
	Read specified amount of data from the packet buffer.

Detailed Description

Packed buffer API.

Macro Definition Documentation

PBUF_CFG_INIT

#define PBUF_CFG_INIT	(		mem_addr,
			size,
			dcache_align
	)

#include <zephyr/ipc/pbuf.h>

Value:

{                                                                                       \
        .rd_idx_loc = (uint32_t *)(mem_addr),                                           \
        .wr_idx_loc = (uint32_t *)((uint8_t *)(mem_addr) +                              \
                                MAX(dcache_align, _PBUF_IDX_SIZE)),                     \
        .data_loc = (uint8_t *)((uint8_t *)(mem_addr) +                                 \
                                MAX(dcache_align, _PBUF_IDX_SIZE) + _PBUF_IDX_SIZE),    \
        .len = (uint32_t)((uint32_t)(size) - MAX(dcache_align, _PBUF_IDX_SIZE) -        \
                                _PBUF_IDX_SIZE),                                        \
        .dcache_alignment = (dcache_align),                                             \
}

Macro for configuration initialization.

It is recommended to use this macro to initialize packed buffer configuration.

Parameters

mem_addr	Memory address for pbuf.
size	Size of the memory.
dcache_align	Data cache alignment.

PBUF_DEFINE

#define PBUF_DEFINE	(		name,
			mem_addr,
			size,
			dcache_align
	)

#include <zephyr/ipc/pbuf.h>

Value:

        BUILD_ASSERT(dcache_align >= 0,                                                 \
                        "Cache line size must be non negative.");                       \
        BUILD_ASSERT((size) > 0 && IS_PTR_ALIGNED_BYTES(size, _PBUF_IDX_SIZE),          \
                        "Incorrect size.");                                             \
        BUILD_ASSERT(IS_PTR_ALIGNED_BYTES(mem_addr, MAX(dcache_align, _PBUF_IDX_SIZE)), \
                        "Misaligned memory.");                                          \
        BUILD_ASSERT(size >= (MAX(dcache_align, _PBUF_IDX_SIZE) + _PBUF_IDX_SIZE +      \
                        _PBUF_MIN_DATA_LEN), "Insufficient size.");                     \
                                                                                        \
        static const struct pbuf_cfg cfg_##name =                                       \
                        PBUF_CFG_INIT(mem_addr, size, dcache_align);                    \
        static struct pbuf name = {                                                     \
                .cfg = &cfg_##name,                                                     \
        }

Statically define and initialize pbuf.

Parameters

name	Name of the pbuf.
mem_addr	Memory address for pbuf.
size	Size of the memory.
dcache_align	Data cache line size.

PBUF_HEADER_OVERHEAD

#define PBUF_HEADER_OVERHEAD

(

dcache_align

)

(MAX(dcache_align, _PBUF_IDX_SIZE) + _PBUF_IDX_SIZE)

#include <zephyr/ipc/pbuf.h>

Macro calculates memory overhead taken by the header in shared memory.

It contains the read index, write index and padding.

Parameters

dcache_align

Data cache alignment.

PBUF_PACKET_LEN_SZ

#define PBUF_PACKET_LEN_SZ   sizeof(uint32_t)

#include <zephyr/ipc/pbuf.h>

Size of packet length field.

Function Documentation

pbuf_init()

int pbuf_init

(

struct pbuf *

pb

)

#include <zephyr/ipc/pbuf.h>

Initialize the packet buffer.

This function initializes the packet buffer based on provided configuration. If the configuration is incorrect, the function will return error.

It is recommended to use PBUF_DEFINE macro for build time initialization.

Parameters

pb	Pointer to the packed buffer containing configuration and data. Configuration has to be fixed before the initialization.

Return values

0	on success.
-EINVAL	when the input parameter is incorrect.

pbuf_read()

int pbuf_read	(	struct pbuf *	pb,
		char *	buf,
		uint16_t	len
	)

#include <zephyr/ipc/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.

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. -EINVAL, if any of input parameter is incorrect. -ENOMEM, if message can not fit in provided buf. -EAGAIN, if not whole message is ready yet.

pbuf_write()

int pbuf_write	(	struct pbuf *	pb,
		const char *	buf,
		uint16_t	len
	)

#include <zephyr/ipc/pbuf.h>

Write specified amount of data to the packet buffer.

This function call writes specified amount of data to the packet buffer if the buffer will fit the data.

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.

Return values

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