pbuf.h

Go to the documentation of this file.

/*
 * Copyright (c) 2023 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef ZEPHYR_INCLUDE_IPC_PBUF_H_
#define ZEPHYR_INCLUDE_IPC_PBUF_H_
 
#include <zephyr/cache.h>
#include <zephyr/devicetree.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define PBUF_PACKET_LEN_SZ sizeof(uint32_t)
 
/* Amount of data that is left unused to distinguish between empty and full. */
#define _PBUF_IDX_SIZE sizeof(uint32_t)
 
/* Minimal length of the data field in the buffer to store the smalest packet
 * possible.
 * (+1) for at least one byte of data.
 * (+_PBUF_IDX_SIZE) to distinguish buffer full and buffer empty.
 * Rounded up to keep wr/rd indexes pointing to aligned address.
 */
#define _PBUF_MIN_DATA_LEN ROUND_UP(PBUF_PACKET_LEN_SZ + 1 + _PBUF_IDX_SIZE, _PBUF_IDX_SIZE)
 
#if defined(CONFIG_ARCH_POSIX)
/* For the native simulated boards we need to modify some pointers at init */
#define PBUF_MAYBE_CONST
#else
#define PBUF_MAYBE_CONST const
#endif
 
struct pbuf_cfg {
        volatile uint32_t *rd_idx_loc;   /* Address of the variable holding
                                          * index value of the first valid byte
                                          * in data[].
                                          */
        volatile uint32_t *handshake_loc;/* Address of the variable holding
                                          * handshake information.
                                          */
        volatile uint32_t *wr_idx_loc;   /* Address of the variable holding
                                          * index value of the first free byte
                                          * in data[].
                                          */
        uint32_t dcache_alignment;       /* CPU data cache line size in bytes.
                                          * Used for validation - TODO: To be
                                          * replaced by flags.
                                          */
        uint32_t len;                    /* Length of data[] in bytes. */
        uint8_t *data_loc;               /* Location of the data[]. */
};
 
struct pbuf_data {
        volatile uint32_t wr_idx;       /* Index of the first holding first
                                         * free byte in data[]. Used for
                                         * writing.
                                         */
        volatile uint32_t rd_idx;       /* Index of the first holding first
                                         * valid byte in data[]. Used for
                                         * reading.
                                         */
};
 
 
struct pbuf {
        PBUF_MAYBE_CONST struct pbuf_cfg *const cfg; /* Configuration of the
                                                      * buffer.
                                                      */
        struct pbuf_data data;                  /* Data used to read and write
                                                 * to the buffer
                                                 */
};
 
#define PBUF_CFG_INIT(mem_addr, size, dcache_align, use_handshake)                      \
{                                                                                       \
        .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),                                             \
}
 
#define PBUF_HEADER_OVERHEAD(dcache_align) \
        (MAX(dcache_align, _PBUF_IDX_SIZE) + _PBUF_IDX_SIZE)
 
#define PBUF_DEFINE(name, mem_addr, size, dcache_align, use_handshake, compatibility)   \
        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,                                                     \
        }
 
int pbuf_tx_init(struct pbuf *pb);
 
int pbuf_rx_init(struct pbuf *pb);
 
int pbuf_write(struct pbuf *pb, const char *buf, uint16_t len);
 
int pbuf_read(struct pbuf *pb, char *buf, uint16_t len);
 
uint32_t pbuf_handshake_read(struct pbuf *pb);
 
void pbuf_handshake_write(struct pbuf *pb, uint32_t value);
 
int pbuf_get_initial_buf(struct pbuf *pb, volatile char **buf, uint16_t *len);
 
#ifdef __cplusplus
}
#endif
 
#endif /* ZEPHYR_INCLUDE_IPC_PBUF_H_ */