mpsc_pbuf.h

Go to the documentation of this file.

/*
 * Copyright (c) 2021 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: Apache-2.0
 */
#ifndef ZEPHYR_INCLUDE_SYS_MPSC_PBUF_H_
#define ZEPHYR_INCLUDE_SYS_MPSC_PBUF_H_
 
#include <zephyr/kernel.h>
#include <zephyr/sys/mpsc_packet.h>
#include <string.h>
#include <stdint.h>
#include <stdbool.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/*
 * Multi producer, single consumer packet buffer allows to allocate variable
 * length consecutive space for storing a packet. When space is allocated
 * it can be filled by the user (except for the first 2 bits) and when packet
 * is ready it is committed. It is allowed to allocate another packet before
 * committing the previous one.
 *
 * If buffer is full and packet cannot be allocated then null is returned unless
 * overwrite mode is selected. In that mode, oldest entry are dropped (user is
 * notified) until allocation succeeds. It can happen that candidate for
 * dropping is currently being claimed. In that case, it is omitted and next
 * packet is dropped and claimed packet is marked as invalid when freeing.
 *
 * Reading packets is performed in two steps. First packet is claimed. Claiming
 * returns pointer to the packet within the buffer. Packet is freed when no
 * longer in use.
 */
 
#define MPSC_PBUF_SIZE_POW2 BIT(0)
 
#define MPSC_PBUF_MODE_OVERWRITE BIT(1)
 
#define MPSC_PBUF_MAX_UTILIZATION BIT(2)
 
#define MPSC_PBUF_FULL BIT(3)
 
/* Forward declaration */
struct mpsc_pbuf_buffer;
 
typedef uint32_t (*mpsc_pbuf_get_wlen)(const union mpsc_pbuf_generic *packet);
 
typedef void (*mpsc_pbuf_notify_drop)(const struct mpsc_pbuf_buffer *buffer,
                                      const union mpsc_pbuf_generic *packet);
 
struct mpsc_pbuf_buffer {
        uint32_t tmp_wr_idx;
 
        uint32_t wr_idx;
 
        uint32_t tmp_rd_idx;
 
        uint32_t rd_idx;
 
        uint32_t flags;
 
        struct k_spinlock lock;
 
        mpsc_pbuf_notify_drop notify_drop;
 
        mpsc_pbuf_get_wlen get_wlen;
 
        /* Buffer. */
        uint32_t *buf;
 
        /* Buffer size in 32 bit words. */
        uint32_t size;
 
        /* Store max buffer usage. */
        uint32_t max_usage;
 
        struct k_sem sem;
};
 
struct mpsc_pbuf_buffer_config {
        /* Pointer to a memory used for storing packets. */
        uint32_t *buf;
 
        /* Buffer size in 32 bit words. */
        uint32_t size;
 
        /* Callbacks. */
        mpsc_pbuf_notify_drop notify_drop;
        mpsc_pbuf_get_wlen get_wlen;
 
        /* Configuration flags. */
        uint32_t flags;
};
 
void mpsc_pbuf_init(struct mpsc_pbuf_buffer *buffer,
                    const struct mpsc_pbuf_buffer_config *config);
 
union mpsc_pbuf_generic *mpsc_pbuf_alloc(struct mpsc_pbuf_buffer *buffer,
                                         size_t wlen, k_timeout_t timeout);
 
void mpsc_pbuf_commit(struct mpsc_pbuf_buffer *buffer,
                        union mpsc_pbuf_generic *packet);
 
void mpsc_pbuf_put_word(struct mpsc_pbuf_buffer *buffer,
                        const union mpsc_pbuf_generic word);
 
void mpsc_pbuf_put_word_ext(struct mpsc_pbuf_buffer *buffer,
                            const union mpsc_pbuf_generic word,
                            const void *data);
 
void mpsc_pbuf_put_data(struct mpsc_pbuf_buffer *buffer,
                        const uint32_t *data, size_t wlen);
 
const union mpsc_pbuf_generic *mpsc_pbuf_claim(struct mpsc_pbuf_buffer *buffer);
 
void mpsc_pbuf_free(struct mpsc_pbuf_buffer *buffer,
                    const union mpsc_pbuf_generic *packet);
 
bool mpsc_pbuf_is_pending(struct mpsc_pbuf_buffer *buffer);
 
void mpsc_pbuf_get_utilization(struct mpsc_pbuf_buffer *buffer,
                               uint32_t *size, uint32_t *now);
 
int mpsc_pbuf_get_max_utilization(struct mpsc_pbuf_buffer *buffer, uint32_t *max);
#ifdef __cplusplus
}
#endif
 
#endif /* ZEPHYR_INCLUDE_SYS_MPSC_PBUF_H_ */