mirror of
https://github.com/RIOT-OS/RIOT.git
synced 2025-12-13 08:33:49 +01:00
285 lines
8.3 KiB
C
285 lines
8.3 KiB
C
/*
|
|
* SPDX-FileCopyrightText: 2016 Kaspar Schleiser <kaspar@schleiser.de>
|
|
* SPDX-FileCopyrightText: 2013 Freie Universität Berlin
|
|
* SPDX-License-Identifier: LGPL-2.1-only
|
|
*/
|
|
|
|
#pragma once
|
|
|
|
/**
|
|
* @ingroup core_util
|
|
* @{
|
|
*
|
|
* @file
|
|
* @brief Circular integer buffer interface
|
|
* @details This structure provides an organizational interface
|
|
* and combined with an memory array forms a circular buffer.
|
|
*
|
|
* @author Kaspar Schleiser <kaspar@schleiser.de>
|
|
*
|
|
* @warning This API is NOT thread-safe.
|
|
*
|
|
* @note It may appear that the functions would be thread safe if the
|
|
* management data structure is only ever accessed by a single
|
|
* consumer and a singler producer on platforms where loads and
|
|
* stores to `unsigned int` is atomic. But even this is not the
|
|
* case, as this would require careful use of memory barriers to
|
|
* ensure correct order of memory accesses. So: Just make sure
|
|
* to use either a mutex or to disable interrupts to ensure
|
|
* exclusive access as indicated in the API doc.
|
|
*/
|
|
|
|
#include "assert.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**
|
|
* @brief circular integer buffer structure
|
|
*/
|
|
typedef struct {
|
|
unsigned int read_count; /**< number of (successful) read accesses */
|
|
unsigned int write_count; /**< number of (successful) write accesses */
|
|
unsigned int mask; /**< Size of buffer -1, i.e. mask of the bits */
|
|
} cib_t;
|
|
|
|
/**
|
|
* @brief Initialize cib_t to a given size.
|
|
*
|
|
* @param[in] SIZE Size of the buffer, must not exceed
|
|
* (`UINT_MAX` + 1) / 2.
|
|
* Should be equal to 0 or power of 2.
|
|
*/
|
|
#define CIB_INIT(SIZE) { 0, 0, (SIZE)-1 }
|
|
|
|
/**
|
|
* @brief Initialize @p cib to 0 and set buffer size to @p size.
|
|
*
|
|
* @param[out] cib Buffer to initialize.
|
|
* Must not be NULL.
|
|
* @param[in] size Size of the buffer, must not exceed
|
|
* (`UINT_MAX` + 1) / 2.
|
|
* Should be equal to 0 or power of 2.
|
|
*/
|
|
static inline void cib_init(cib_t *__restrict cib, unsigned int size)
|
|
{
|
|
/* check if size is a power of 2 by comparing it to its complement */
|
|
assert(!(size & (size - 1)));
|
|
|
|
cib_t c = CIB_INIT(size);
|
|
|
|
*cib = c;
|
|
}
|
|
|
|
/**
|
|
* @brief Returns the total capacity (`size` parameter of @ref cib_init()) of
|
|
* a cib_t
|
|
*
|
|
* @param[in] cib the cib_t to check.
|
|
* Must not be NULL.
|
|
* @return The total size of @p cib.
|
|
*/
|
|
static inline unsigned int cib_size(const cib_t *cib)
|
|
{
|
|
return cib->mask + 1;
|
|
}
|
|
|
|
/**
|
|
* @brief Calculates difference between cib_put() and cib_get() accesses.
|
|
*
|
|
* @param[in] cib the cib_t to check.
|
|
* Must not be NULL.
|
|
* @return How often cib_get() can be called before @p cib is empty.
|
|
*
|
|
* @warning This function is not thread safe. (The caller needs to ensure
|
|
* exclusive access to the `cib_t`.)
|
|
*/
|
|
static inline unsigned int cib_avail(const cib_t *cib)
|
|
{
|
|
return cib->write_count - cib->read_count;
|
|
}
|
|
|
|
/**
|
|
* @brief Check if cib is full.
|
|
*
|
|
* @param[in] cib the cib_t to check.
|
|
* Must not be NULL.
|
|
* @return 1 if cib_put() would return "-1", 0 otherwise
|
|
*
|
|
* @warning This function is not thread safe. (The caller needs to ensure
|
|
* exclusive access to the `cib_t`.)
|
|
*/
|
|
static inline unsigned int cib_full(const cib_t *cib)
|
|
{
|
|
return ((int)cib_avail(cib)) > ((int)cib->mask);
|
|
}
|
|
|
|
/**
|
|
* @brief Get the index of the next item in buffer.
|
|
*
|
|
* @param[in,out] cib corresponding *cib* to buffer.
|
|
* Must not be NULL.
|
|
* @return index of next item
|
|
* @retval -1 if the buffer is empty
|
|
*
|
|
* @warning This function is not thread safe. (The caller needs to ensure
|
|
* exclusive access to the `cib_t`.)
|
|
*/
|
|
static inline int cib_get(cib_t *__restrict cib)
|
|
{
|
|
if (cib_avail(cib)) {
|
|
return (int)(cib->read_count++ & cib->mask);
|
|
}
|
|
|
|
return -1;
|
|
}
|
|
|
|
/**
|
|
* @brief Get the index of an item in the buffer without removing anything.
|
|
*
|
|
* Offset 0 is the next item in the buffer that would be returned by
|
|
* `cip_get()`, offset 1 would be the following, and so on.
|
|
*
|
|
* Unsafe version, *must not* pass an offset that is larger than the number of
|
|
* items currently in the buffer!
|
|
*
|
|
* @param[in,out] cib corresponding *cib* to buffer.
|
|
* Must not be NULL.
|
|
* @param[in] offset offset from front of buffer
|
|
*
|
|
* @return index of item
|
|
* @retval -1 if no item at @p offset exists in the buffer
|
|
*
|
|
* @warning This function is not thread safe. (The caller needs to ensure
|
|
* exclusive access to the `cib_t` and must not release that exclusive
|
|
* access between the call to @ref cib_avail and this function.)
|
|
*/
|
|
static inline int cib_peek_at_unsafe(const cib_t *__restrict cib, unsigned offset)
|
|
{
|
|
return (cib->read_count + offset) & cib->mask;
|
|
}
|
|
|
|
/**
|
|
* @brief Get the index of an item in the buffer without removing anything.
|
|
*
|
|
* Offset 0 is the next item in the buffer that would be returned by
|
|
* `cip_get()`, offset 1 would be the following, and so on.
|
|
*
|
|
* @param[in,out] cib corresponding *cib* to buffer.
|
|
* Must not be NULL.
|
|
* @param[in] offset offset from front of buffer
|
|
*
|
|
* @return index of item
|
|
* @retval -1 if no item at @p offset exists in the buffer
|
|
*
|
|
* @warning This function is not thread safe. (The caller needs to ensure
|
|
* exclusive access to the `cib_t`.)
|
|
*/
|
|
static inline int cib_peek_at(const cib_t *__restrict cib, unsigned offset)
|
|
{
|
|
if (offset < cib_avail(cib)) {
|
|
return cib_peek_at_unsafe(cib, offset);
|
|
}
|
|
|
|
return -1;
|
|
}
|
|
|
|
/**
|
|
* @brief Get the index of the next item in buffer without removing it.
|
|
*
|
|
* Unsafe version, *must not* be called if buffer is empty!
|
|
*
|
|
* @param[in,out] cib corresponding *cib* to buffer.
|
|
* Must not be NULL.
|
|
* @return index of next item
|
|
* @retval -1 if the buffer is empty
|
|
*
|
|
* @warning This function is not thread safe. (The caller needs to ensure
|
|
* exclusive access to the `cib_t` and must not release that exclusive
|
|
* access between the call to @ref cib_avail and this function.)
|
|
*/
|
|
static inline int cib_peek_unsafe(const cib_t *__restrict cib)
|
|
{
|
|
return cib_peek_at_unsafe(cib, 0);
|
|
}
|
|
|
|
/**
|
|
* @brief Get the index of the next item in buffer without removing it.
|
|
*
|
|
* @param[in,out] cib corresponding *cib* to buffer.
|
|
* Must not be NULL.
|
|
* @return index of next item
|
|
* @retval -1 if the buffer is empty
|
|
*
|
|
* @warning This function is not thread safe. (The caller needs to ensure
|
|
* exclusive access to the `cib_t`.)
|
|
*/
|
|
static inline int cib_peek(const cib_t *__restrict cib)
|
|
{
|
|
return cib_peek_at(cib, 0);
|
|
}
|
|
|
|
/**
|
|
* @brief Get the index of the next item in buffer.
|
|
*
|
|
* Unsafe version, *must not* be called if buffer is empty!
|
|
*
|
|
* @param[in,out] cib corresponding *cib* to buffer.
|
|
* Must not be NULL.
|
|
* @return index of next item
|
|
*
|
|
* @warning This function is not thread safe. (The caller needs to ensure
|
|
* exclusive access to the `cib_t`.)
|
|
*/
|
|
static inline int cib_get_unsafe(cib_t *cib)
|
|
{
|
|
return (int)(cib->read_count++ & cib->mask);
|
|
}
|
|
|
|
/**
|
|
* @brief Get index for item in buffer to put to.
|
|
*
|
|
* @param[in,out] cib corresponding *cib* to buffer.
|
|
* Must not be NULL.
|
|
* @return index of item to put to
|
|
* @retval -1 if the buffer is full
|
|
*
|
|
* @warning This function is not thread safe. (The caller needs to ensure
|
|
* exclusive access to the `cib_t`.)
|
|
*/
|
|
static inline int cib_put(cib_t *__restrict cib)
|
|
{
|
|
unsigned int avail = cib_avail(cib);
|
|
|
|
/* We use a signed compare, because the mask is -1u for an empty CIB. */
|
|
if ((int)avail <= (int)cib->mask) {
|
|
return (int)(cib->write_count++ & cib->mask);
|
|
}
|
|
|
|
return -1;
|
|
}
|
|
|
|
/**
|
|
* @brief Get index for item in buffer to put to.
|
|
*
|
|
* Unsafe version, *must not* be called if buffer is full!
|
|
*
|
|
* @param[in,out] cib corresponding *cib* to buffer.
|
|
* Must not be NULL.
|
|
* @return index of item to put to
|
|
*
|
|
* @warning This function is not thread safe. (The caller needs to ensure
|
|
* exclusive access to the `cib_t`.)
|
|
*/
|
|
static inline int cib_put_unsafe(cib_t *cib)
|
|
{
|
|
return (int)(cib->write_count++ & cib->mask);
|
|
}
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
/** @} */
|