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_MAYBE_CONST   const
#define	PBUF_CFG_INIT(mem_addr, size, dcache_align, use_handshake)
	Macro for configuration initialization.
#define	PBUF_HEADER_OVERHEAD(dcache_align)
	Macro calculates memory overhead taken by the header in shared memory.
#define	PBUF_DEFINE(name, mem_addr, size, dcache_align, use_handshake, compatibility)
	Statically define and initialize pbuf.

Functions
int	pbuf_tx_init (struct pbuf *pb)
	Initialize the Tx packet buffer.
int	pbuf_rx_init (struct pbuf *pb)
	Initialize the Rx 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.
uint32_t	pbuf_handshake_read (struct pbuf *pb)
	Read handshake word from pbuf.
void	pbuf_handshake_write (struct pbuf *pb, uint32_t value)
	Write handshake word to pbuf.
int	pbuf_get_initial_buf (struct pbuf *pb, volatile char **buf, uint16_t *len)
	Get first buffer from pbuf.

Detailed Description

Packed buffer API .

Macro Definition Documentation

PBUF_CFG_INIT

#define PBUF_CFG_INIT	(		mem_addr,
			size,
			dcache_align,
			use_handshake )

#include <zephyr/ipc/pbuf.h>

Value:

{                                                                                       \
        .rd_idx_loc = (uint32_t *)(mem_addr),                                           \
        .handshake_loc = use_handshake ? (uint32_t *)((uint8_t *)(mem_addr) +           \
                                _PBUF_IDX_SIZE) : NULL,                                 \
        .wr_idx_loc = (uint32_t *)((uint8_t *)(mem_addr) + MAX(dcache_align,            \
                                (use_handshake ? 2 : 1) * _PBUF_IDX_SIZE)),             \
        .data_loc = (uint8_t *)((uint8_t *)(mem_addr) +                                 \
                                MAX(dcache_align, (use_handshake ? 2 : 1) *             \
                                                  _PBUF_IDX_SIZE) + _PBUF_IDX_SIZE),    \
        .len = (uint32_t)((uint32_t)(size) - MAX(dcache_align,                          \
                        (use_handshake ? 2 : 1) * _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.
use_handshake	Add handshake word inside shared memory that can be access with pbuf_handshake_read and pbuf_handshake_write.

PBUF_DEFINE

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

#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.");                     \
        BUILD_ASSERT(!(compatibility) || (dcache_align) >= 8,                           \
                "Data cache alignment must be at least 8 if compatibility is enabled.");\
        static PBUF_MAYBE_CONST struct pbuf_cfg cfg_##name =                            \
                        PBUF_CFG_INIT(mem_addr, size, dcache_align, use_handshake);     \
        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.
use_handshake	Add handshake word inside shared memory that can be access with pbuf_handshake_read and pbuf_handshake_write.

PBUF_HEADER_OVERHEAD

#define PBUF_HEADER_OVERHEAD

(

dcache_align

)

#include <zephyr/ipc/pbuf.h>

Value:

        (MAX(dcache_align, _PBUF_IDX_SIZE) + _PBUF_IDX_SIZE)

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_MAYBE_CONST

#define PBUF_MAYBE_CONST   const

#include <zephyr/ipc/pbuf.h>

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_get_initial_buf()

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

#include <zephyr/ipc/pbuf.h>

Get first buffer from pbuf.

This function retrieves buffer located at the beginning of queue. It will be continuous block since it is the first buffer.

Parameters

	pb	A buffer from which data will be read.
[out]	buf	A pointer to output pointer to the date of the first buffer.
[out]	len	A pointer to output length the first buffer.

Return values

0	on success. -EINVAL when there is no buffer at the beginning of queue.

pbuf_handshake_read()

uint32_t pbuf_handshake_read

(

struct pbuf *

pb

)

#include <zephyr/ipc/pbuf.h>

Read handshake word from pbuf.

The pb must be defined with "PBUF_DEFINE" with "use_handshake" set.

Parameters

pb	A buffer from which data will be read.

Return values

uint32_t

The handshake word value.

pbuf_handshake_write()

void pbuf_handshake_write	(	struct pbuf *	pb,
		uint32_t	value )

#include <zephyr/ipc/pbuf.h>

Write handshake word to pbuf.

The pb must be defined with "PBUF_DEFINE" with "use_handshake" set.

Parameters

pb	A buffer to which data will be written.
value	A handshake value.

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_rx_init()

int pbuf_rx_init

(

struct pbuf *

pb

)

#include <zephyr/ipc/pbuf.h>

Initialize the Rx packet buffer.

This function initializes the Rx packet buffer. 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_tx_init()

int pbuf_tx_init

(

struct pbuf *

pb

)

#include <zephyr/ipc/pbuf.h>

Initialize the Tx packet buffer.

This function initializes the Tx 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_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.