Zephyr Project API 3.7.0
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
mpsc_pbuf.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2021 Nordic Semiconductor ASA
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6#ifndef ZEPHYR_INCLUDE_SYS_MPSC_PBUF_H_
7#define ZEPHYR_INCLUDE_SYS_MPSC_PBUF_H_
8
9#include <zephyr/kernel.h>
11#include <string.h>
12#include <stdint.h>
13#include <stdbool.h>
14
15#ifdef __cplusplus
16extern "C" {
17#endif
18
26/*
27 * Multi producer, single consumer packet buffer allows to allocate variable
28 * length consecutive space for storing a packet. When space is allocated
29 * it can be filled by the user (except for the first 2 bits) and when packet
30 * is ready it is committed. It is allowed to allocate another packet before
31 * committing the previous one.
32 *
33 * If buffer is full and packet cannot be allocated then null is returned unless
34 * overwrite mode is selected. In that mode, oldest entry are dropped (user is
35 * notified) until allocation succeeds. It can happen that candidate for
36 * dropping is currently being claimed. In that case, it is omitted and next
37 * packet is dropped and claimed packet is marked as invalid when freeing.
38 *
39 * Reading packets is performed in two steps. First packet is claimed. Claiming
40 * returns pointer to the packet within the buffer. Packet is freed when no
41 * longer in use.
42 */
43
52#define MPSC_PBUF_SIZE_POW2 BIT(0)
53
59#define MPSC_PBUF_MODE_OVERWRITE BIT(1)
60
62#define MPSC_PBUF_MAX_UTILIZATION BIT(2)
63
65#define MPSC_PBUF_FULL BIT(3)
66
69/* Forward declaration */
70struct mpsc_pbuf_buffer;
71
78typedef uint32_t (*mpsc_pbuf_get_wlen)(const union mpsc_pbuf_generic *packet);
79
86typedef void (*mpsc_pbuf_notify_drop)(const struct mpsc_pbuf_buffer *buffer,
87 const union mpsc_pbuf_generic *packet);
88
93
96
99
102
105
108
114
117
118 /* Buffer. */
120
121 /* Buffer size in 32 bit words. */
123
124 /* Store max buffer usage. */
126
127 struct k_sem sem;
128};
129
132 /* Pointer to a memory used for storing packets. */
134
135 /* Buffer size in 32 bit words. */
137
138 /* Callbacks. */
141
142 /* Configuration flags. */
144};
145
153 const struct mpsc_pbuf_buffer_config *config);
154
172 size_t wlen, k_timeout_t timeout);
173
181 union mpsc_pbuf_generic *packet);
182
194 const union mpsc_pbuf_generic word);
195
209 const union mpsc_pbuf_generic word,
210 const void *data);
211
224 const uint32_t *data, size_t wlen);
225
233
241 const union mpsc_pbuf_generic *packet);
242
251
259 uint32_t *size, uint32_t *now);
260
274#ifdef __cplusplus
275}
276#endif
277
278#endif /* ZEPHYR_INCLUDE_SYS_MPSC_PBUF_H_ */
ZTEST_BMEM int timeout
Definition main.c:31
uint32_t(* mpsc_pbuf_get_wlen)(const union mpsc_pbuf_generic *packet)
Callback prototype for getting length of a packet.
Definition mpsc_pbuf.h:78
bool mpsc_pbuf_is_pending(struct mpsc_pbuf_buffer *buffer)
Check if there are any message pending.
union mpsc_pbuf_generic * mpsc_pbuf_alloc(struct mpsc_pbuf_buffer *buffer, size_t wlen, k_timeout_t timeout)
Allocate a packet.
void mpsc_pbuf_init(struct mpsc_pbuf_buffer *buffer, const struct mpsc_pbuf_buffer_config *config)
Initialize a packet buffer.
void mpsc_pbuf_free(struct mpsc_pbuf_buffer *buffer, const union mpsc_pbuf_generic *packet)
Free a packet.
void mpsc_pbuf_get_utilization(struct mpsc_pbuf_buffer *buffer, uint32_t *size, uint32_t *now)
Get current memory utilization.
void mpsc_pbuf_put_data(struct mpsc_pbuf_buffer *buffer, const uint32_t *data, size_t wlen)
Put a packet into a buffer.
void mpsc_pbuf_put_word_ext(struct mpsc_pbuf_buffer *buffer, const union mpsc_pbuf_generic word, const void *data)
Put a packet consisting of a word and a pointer.
void(* mpsc_pbuf_notify_drop)(const struct mpsc_pbuf_buffer *buffer, const union mpsc_pbuf_generic *packet)
Callback called when packet is dropped.
Definition mpsc_pbuf.h:86
int mpsc_pbuf_get_max_utilization(struct mpsc_pbuf_buffer *buffer, uint32_t *max)
Get maximum memory utilization.
const union mpsc_pbuf_generic * mpsc_pbuf_claim(struct mpsc_pbuf_buffer *buffer)
Claim the first pending packet.
void mpsc_pbuf_commit(struct mpsc_pbuf_buffer *buffer, union mpsc_pbuf_generic *packet)
Commit a packet.
void mpsc_pbuf_put_word(struct mpsc_pbuf_buffer *buffer, const union mpsc_pbuf_generic word)
Put single word packet into a buffer.
Public kernel APIs.
__UINT32_TYPE__ uint32_t
Definition stdint.h:90
Kernel Spin Lock.
Definition spinlock.h:45
Kernel timeout type.
Definition sys_clock.h:65
MPSC packet buffer configuration.
Definition mpsc_pbuf.h:131
uint32_t * buf
Definition mpsc_pbuf.h:133
mpsc_pbuf_notify_drop notify_drop
Definition mpsc_pbuf.h:139
mpsc_pbuf_get_wlen get_wlen
Definition mpsc_pbuf.h:140
uint32_t flags
Definition mpsc_pbuf.h:143
uint32_t size
Definition mpsc_pbuf.h:136
MPSC packet buffer structure.
Definition mpsc_pbuf.h:90
uint32_t flags
Flags.
Definition mpsc_pbuf.h:104
struct k_spinlock lock
Lock.
Definition mpsc_pbuf.h:107
uint32_t * buf
Definition mpsc_pbuf.h:119
uint32_t wr_idx
Write index.
Definition mpsc_pbuf.h:95
uint32_t tmp_wr_idx
Temporary write index.
Definition mpsc_pbuf.h:92
uint32_t size
Definition mpsc_pbuf.h:122
mpsc_pbuf_notify_drop notify_drop
User callback called whenever packet is dropped.
Definition mpsc_pbuf.h:113
mpsc_pbuf_get_wlen get_wlen
Callback for getting packet length.
Definition mpsc_pbuf.h:116
uint32_t max_usage
Definition mpsc_pbuf.h:125
struct k_sem sem
Definition mpsc_pbuf.h:127
uint32_t tmp_rd_idx
Temporary read index.
Definition mpsc_pbuf.h:98
uint32_t rd_idx
Read index.
Definition mpsc_pbuf.h:101
static fdata_t data[2]
Definition test_fifo_contexts.c:15
static ZTEST_BMEM char buffer[8]
Definition test_mbox_api.c:433
static uint32_t now
Definition main.c:25
Generic packet header.
Definition mpsc_packet.h:49