taler-xotp_fw

xOTP generator firmware
Log | Files | Refs | Submodules | README

ringbuffer.h (4796B)

      1 /**
      2  * @file ringbuffer.h
      3  * @author Adrian STEINER (steia19@bfh.ch)
      4  * @brief Base ringbuffer header file for handling an unspecific data in a ring buffer design
      5  * @version 0.2
      6  * @date 2024-03-15
      7  * @date 2025-02-13
      8  *
      9  * @copyright (C) 2025 Adrian STEINER
     10  * This program is free software: you can redistribute it and/or modify
     11  * it under the terms of the GNU General Public License as published by
     12  * the Free Software Foundation, either version 3 of the License, or
     13  * (at your option) any later version.
     14  *
     15  * This program is distributed in the hope that it will be useful,
     16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
     17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     18  * GNU General Public License for more details.
     19  *
     20  * You should have received a copy of the GNU General Public License
     21  * along with this program.  If not, see <https: //www.gnu.org/licenses/>.
     22  *
     23  */
     24 
     25 #ifndef RINGBUFFER_H
     26 #define RINGBUFFER_H
     27 
     28 #ifdef __cplusplus
     29 extern "C" {
     30 #endif
     31 
     32 #include <stdbool.h>
     33 #include <stdint.h>
     34 
     35 /**
     36  * @brief Ringbuffer The ring buffer handler structure
     37  *
     38  */
     39 typedef struct {
     40   void *dataBuffer; ///< buffer array reference
     41   uint32_t length;  ///< array length of buffer
     42   uint32_t headPos; ///< current head position (first element)
     43   uint32_t tailPos; ///< current tail position, (where a new element can inserted)
     44   uint32_t elmSize; ///< Size of an element in the buffer (use sizeof operator of an element)
     45 } ringbuffer_handler;
     46 
     47 /**
     48  * @brief Used to encode different errors. This StatusTypes are used to send back meaningful
     49  * information to the caller of module functions.
     50  *
     51  */
     52 typedef enum {
     53   RINGBUFFER_OK = 0,         ///< No error
     54   RINGBUFFER_OVERFLOW,       ///< Buffer is full and no new data can be inserted
     55   RINGBUFFER_EMPTY,          ///< current ring buffer is empty
     56   RINGBUFFER_ARGUMENT_ERROR, ///< Argument is not valid
     57   RINGBUFFER_ERROR           ///< Error in function or user copy callback function
     58 } ringbuffer_StatusType;
     59 
     60 /**
     61  * @brief Initialize a ring buffer structure
     62  *
     63  * @param rbHandler Reference to a ring buffer structure
     64  * @param buffer Reference to the buffer array
     65  * @param length The length of the buffer
     66  * @param elmSize Size of an element in the buffer
     67  * @param ccbHandler A function pointer to a element copy function
     68  * @return Status code -- see ringbuffer_StatusType
     69  */
     70 ringbuffer_StatusType ringbuffer_init(ringbuffer_handler *rbHandler, void *buffer, uint32_t length, uint32_t elmSize);
     71 
     72 /**
     73  * @brief Destroy ring buffer structure
     74  *
     75  * @param rbHandler Reference to an initialized ring buffer structure.
     76  * @return Address of the buffer.
     77  * Note: Use the returned address to free the memory if it has been allocated on heap.
     78  */
     79 void *ringbuffer_destroy(ringbuffer_handler *rbHandler);
     80 
     81 /**
     82  * @brief Enqueue an element at the tail of the ring buffer.
     83  *
     84  * @param rbHandler Reference to the ring buffer structure
     85  * @param data The data to insert into the ring buffer
     86  * @return Status code -- see ringbuffer_StatusType
     87  */
     88 ringbuffer_StatusType ringbuffer_enqueue(ringbuffer_handler *rbHandler, void *data);
     89 
     90 /**
     91  * @brief Dequeue an element from the head of the ring buffer
     92  *
     93  * @param rbHandler Reference to the ringbuffer structure
     94  * @param data The data which will be dequeued from the ringbuffer
     95  * @return Status code -- see ringbuffer_StatusType
     96  */
     97 ringbuffer_StatusType ringbuffer_dequeue(ringbuffer_handler *rbHandler, void **data);
     98 
     99 /**
    100  * @brief Return the reference to the data at the head of the ring buffer without dequeuing it.
    101  *
    102  * @param rbHandler Reference to the ring buffer structure
    103  * @return Data stored in the element at the head of the ring buffer, or NULL if the queue is empty.
    104  */
    105 void *ringbuffer_peek(const ringbuffer_handler *rbHandler);
    106 
    107 /**
    108  * @brief Number of elements stored in the ring buffer
    109  *
    110  * @param rbHandler Reference to the ring buffer structure
    111  * @return uint32_t Number of elements in the ring buffer
    112  */
    113 uint32_t ringbuffer_size(const ringbuffer_handler *rbHandler);
    114 
    115 /**
    116  * @brief Check whether buffer is full
    117  *
    118  * @param rbHandler Reference to the ring buffer structure
    119  * @return True if buffer is full, False otherwise
    120  */
    121 bool ringbuffer_isFull(const ringbuffer_handler *rbHandler);
    122 
    123 /**
    124  * @brief Check whether buffer is empty
    125  *
    126  * @param rbHandler Reference to the ring buffer structure
    127  * @return True if buffer is empty, False otherwise
    128  */
    129 bool ringbuffer_isEmpty(const ringbuffer_handler *rbHandler);
    130 
    131 /**
    132  * @brief Clears the ringbuffer. Results to set tail and head index to the same level.
    133  *
    134  * @param rbHandler Reference to the ring buffer structure
    135  * @return Status code -- see ringbuffer_StatusType
    136  */
    137 ringbuffer_StatusType ringbuffer_clear(ringbuffer_handler *rbHandler);
    138 
    139 #ifdef __cplusplus
    140 }
    141 #endif
    142 
    143 #endif