Line data Source code
1 0 : /* 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> 10 : #include <zephyr/sys/mpsc_packet.h> 11 : #include <string.h> 12 : #include <stdint.h> 13 : #include <stdbool.h> 14 : 15 : #ifdef __cplusplus 16 : extern "C" { 17 : #endif 18 : 19 : /** 20 : * @brief Multi producer, single consumer packet buffer API 21 : * @defgroup mpsc_buf MPSC (Multi producer, single consumer) packet buffer API 22 : * @ingroup datastructure_apis 23 : * @{ 24 : */ 25 : 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 : 44 : /**@defgroup MPSC_PBUF_FLAGS MPSC packet buffer flags 45 : * @{ 46 : */ 47 : 48 : /** @brief Flag indicating that buffer size is power of 2. 49 : * 50 : * When buffer size is power of 2 then optimizations are applied. 51 : */ 52 1 : #define MPSC_PBUF_SIZE_POW2 BIT(0) 53 : 54 : /** @brief Flag indicating buffer full policy. 55 : * 56 : * If flag is set then when allocating from a full buffer oldest packets are 57 : * dropped. When flag is not set then allocation returns null. 58 : */ 59 1 : #define MPSC_PBUF_MODE_OVERWRITE BIT(1) 60 : 61 : /** @brief Flag indicating that maximum buffer usage is tracked. */ 62 1 : #define MPSC_PBUF_MAX_UTILIZATION BIT(2) 63 : 64 : /** @brief Flag indicated that buffer is currently full. */ 65 1 : #define MPSC_PBUF_FULL BIT(3) 66 : 67 : /**@} */ 68 : 69 : /* Forward declaration */ 70 : struct mpsc_pbuf_buffer; 71 : 72 : /** @brief Callback prototype for getting length of a packet. 73 : * 74 : * @param packet User packet. 75 : * 76 : * @return Size of the packet in 32 bit words. 77 : */ 78 1 : typedef uint32_t (*mpsc_pbuf_get_wlen)(const union mpsc_pbuf_generic *packet); 79 : 80 : /** @brief Callback called when packet is dropped. 81 : * 82 : * @param buffer Packet buffer. 83 : * 84 : * @param packet Packet that is being dropped. 85 : */ 86 1 : typedef void (*mpsc_pbuf_notify_drop)(const struct mpsc_pbuf_buffer *buffer, 87 : const union mpsc_pbuf_generic *packet); 88 : 89 : /** @brief MPSC packet buffer structure. */ 90 1 : struct mpsc_pbuf_buffer { 91 : /** Temporary write index. */ 92 1 : uint32_t tmp_wr_idx; 93 : 94 : /** Write index. */ 95 1 : uint32_t wr_idx; 96 : 97 : /** Temporary read index. */ 98 1 : uint32_t tmp_rd_idx; 99 : 100 : /** Read index. */ 101 1 : uint32_t rd_idx; 102 : 103 : /** Flags. */ 104 1 : uint32_t flags; 105 : 106 : /** Lock. */ 107 1 : struct k_spinlock lock; 108 : 109 : /** User callback called whenever packet is dropped. 110 : * 111 : * May be NULL if unneeded. 112 : */ 113 1 : mpsc_pbuf_notify_drop notify_drop; 114 : 115 : /** Callback for getting packet length. */ 116 1 : mpsc_pbuf_get_wlen get_wlen; 117 : 118 : /* Buffer. */ 119 0 : uint32_t *buf; 120 : 121 : /* Buffer size in 32 bit words. */ 122 0 : uint32_t size; 123 : 124 : /* Store max buffer usage. */ 125 0 : uint32_t max_usage; 126 : 127 0 : struct k_sem sem; 128 : }; 129 : 130 : /** @brief MPSC packet buffer configuration. */ 131 1 : struct mpsc_pbuf_buffer_config { 132 : /* Pointer to a memory used for storing packets. */ 133 0 : uint32_t *buf; 134 : 135 : /* Buffer size in 32 bit words. */ 136 0 : uint32_t size; 137 : 138 : /* Callbacks. */ 139 0 : mpsc_pbuf_notify_drop notify_drop; 140 0 : mpsc_pbuf_get_wlen get_wlen; 141 : 142 : /* Configuration flags. */ 143 0 : uint32_t flags; 144 : }; 145 : 146 : /** @brief Initialize a packet buffer. 147 : * 148 : * @param buffer Buffer. 149 : * 150 : * @param config Configuration. 151 : */ 152 1 : void mpsc_pbuf_init(struct mpsc_pbuf_buffer *buffer, 153 : const struct mpsc_pbuf_buffer_config *config); 154 : 155 : /** @brief Allocate a packet. 156 : * 157 : * If a buffer is configured to overwrite mode then if there is no space to 158 : * allocate a new buffer, oldest packets are dropped. Otherwise allocation 159 : * fails and null pointer is returned. 160 : * 161 : * @param buffer Buffer. 162 : * 163 : * @param wlen Number of words to allocate. 164 : * 165 : * @param timeout Timeout. If called from thread context it will pend for given 166 : * timeout if packet cannot be allocated before dropping the oldest or 167 : * returning null. 168 : * 169 : * @return Pointer to the allocated space or null if it cannot be allocated. 170 : */ 171 1 : union mpsc_pbuf_generic *mpsc_pbuf_alloc(struct mpsc_pbuf_buffer *buffer, 172 : size_t wlen, k_timeout_t timeout); 173 : 174 : /** @brief Commit a packet. 175 : * 176 : * @param buffer Buffer. 177 : * 178 : * @param packet Pointer to a packet allocated by @ref mpsc_pbuf_alloc. 179 : */ 180 1 : void mpsc_pbuf_commit(struct mpsc_pbuf_buffer *buffer, 181 : union mpsc_pbuf_generic *packet); 182 : 183 : /** @brief Put single word packet into a buffer. 184 : * 185 : * Function is optimized for storing a packet which fit into a single word. 186 : * Note that 2 bits of that word is used by the buffer. 187 : * 188 : * @param buffer Buffer. 189 : * 190 : * @param word Packet content consisting of MPSC_PBUF_HDR with valid bit set 191 : * and data on remaining bits. 192 : */ 193 1 : void mpsc_pbuf_put_word(struct mpsc_pbuf_buffer *buffer, 194 : const union mpsc_pbuf_generic word); 195 : 196 : /** @brief Put a packet consisting of a word and a pointer. 197 : * * 198 : * Function is optimized for storing packet consisting of a word and a pointer. 199 : * Note that 2 bits of a first word is used by the buffer. 200 : * 201 : * @param buffer Buffer. 202 : * 203 : * @param word First word of a packet consisting of MPSC_PBUF_HDR with valid 204 : * bit set and data on remaining bits. 205 : * 206 : * @param data User data. 207 : */ 208 1 : void mpsc_pbuf_put_word_ext(struct mpsc_pbuf_buffer *buffer, 209 : const union mpsc_pbuf_generic word, 210 : const void *data); 211 : 212 : /** @brief Put a packet into a buffer. 213 : * 214 : * Copy data into a buffer. 215 : * Note that 2 bits of a first word is used by the buffer. 216 : * 217 : * @param buffer Buffer. 218 : * 219 : * @param data First word of data must contain MPSC_PBUF_HDR with valid bit set. 220 : * 221 : * @param wlen Packet size in words. 222 : */ 223 1 : void mpsc_pbuf_put_data(struct mpsc_pbuf_buffer *buffer, 224 : const uint32_t *data, size_t wlen); 225 : 226 : /** @brief Claim the first pending packet. 227 : * 228 : * @param buffer Buffer. 229 : * 230 : * @return Pointer to the claimed packet or null if none available. 231 : */ 232 1 : const union mpsc_pbuf_generic *mpsc_pbuf_claim(struct mpsc_pbuf_buffer *buffer); 233 : 234 : /** @brief Free a packet. 235 : * 236 : * @param buffer Buffer. 237 : * 238 : * @param packet Packet. 239 : */ 240 1 : void mpsc_pbuf_free(struct mpsc_pbuf_buffer *buffer, 241 : const union mpsc_pbuf_generic *packet); 242 : 243 : /** @brief Check if there are any message pending. 244 : * 245 : * @param buffer Buffer. 246 : * 247 : * @retval true if pending. 248 : * @retval false if no message is pending. 249 : */ 250 1 : bool mpsc_pbuf_is_pending(struct mpsc_pbuf_buffer *buffer); 251 : 252 : /** @brief Get current memory utilization. 253 : * 254 : * @param[in, out] buffer Buffer. 255 : * @param[out] size Buffer size in bytes. 256 : * @param[out] now Current buffer usage in bytes. 257 : */ 258 1 : void mpsc_pbuf_get_utilization(struct mpsc_pbuf_buffer *buffer, 259 : uint32_t *size, uint32_t *now); 260 : 261 : /** @brief Get maximum memory utilization. 262 : * 263 : * @param[in, out] buffer Buffer. 264 : * @param[out] max Maximum buffer usage in bytes. 265 : * 266 : * retval 0 if utilization data collected successfully. 267 : * retval -ENOTSUP if Collecting utilization data is not supported. 268 : */ 269 1 : int mpsc_pbuf_get_max_utilization(struct mpsc_pbuf_buffer *buffer, uint32_t *max); 270 : /** 271 : * @} 272 : */ 273 : 274 : #ifdef __cplusplus 275 : } 276 : #endif 277 : 278 : #endif /* ZEPHYR_INCLUDE_SYS_MPSC_PBUF_H_ */
