queue.h

00001 /*******************************************************************************
00002 * Author: Ismail Kose, Ismail.Kose@maximintegrated.com
00003 * Copyright (C) 2016 Maxim Integrated Products, Inc., All Rights Reserved.
00004 *
00005 * Permission is hereby granted, free of charge, to any person obtaining a
00006 * copy of this software and associated documentation files (the "Software"),
00007 * to deal in the Software without restriction, including without limitation
00008 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
00009 * and/or sell copies of the Software, and to permit persons to whom the
00010 * Software is furnished to do so, subject to the following conditions:
00011 *
00012 * The above copyright notice and this permission notice shall be included
00013 * in all copies or substantial portions of the Software.
00014 *
00015 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
00016 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
00017 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
00018 * IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES
00019 * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
00020 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
00021 * OTHER DEALINGS IN THE SOFTWARE.
00022 *
00023 * Except as contained in this notice, the name of Maxim Integrated
00024 * Products, Inc. shall not be used except as stated in the Maxim Integrated
00025 * Products, Inc. Branding Policy.
00026 *
00027 * The mere transfer of this software does not imply any licenses
00028 * of trade secrets, proprietary technology, copyrights, patents,
00029 * trademarks, maskwork rights, or any other form of intellectual
00030 * property whatsoever. Maxim Integrated Products, Inc. retains all
00031 * ownership rights.
00032 *******************************************************************************
00033 */
00034 
00035 #ifndef _QUEUE_H_
00036 #define _QUEUE_H_
00037 
00038 struct queue_t {
00039     void *wr; // write pointer
00040     void *rd; // read pointer
00041     void *base; // buffer base pointer
00042     int num_item; // number of data item
00043     int ovf_item; // Number of overflowed data
00044     int buffer_size; // buffer size in bytes
00045     int item_size; // data size
00046 };
00047 
00048 #ifdef __cplusplus
00049 extern "C" {
00050 #endif
00051 /**
00052  * @brief Queue initialization.
00053  * @param[in]       *q Points to the queue handle
00054  * @param[in]       *buf Points to external queue buffer
00055  * @param[in]       item_size Data size
00056  * @param[in]       buffer_size Total buffer size in bytes
00057  * @param[out]      *pDst points to output matrix structure
00058  * @return     The function returns 0: success
00059  *                              -EINVAL (-22): Invalid Pointer, data or parameters
00060  *                              -2: Queue buffer is full, no more space
00061  **/
00062 int queue_init(struct queue_t *q, void *buf, int item_size, int buffer_size);
00063 
00064 
00065 
00066 
00067 /**
00068  * @brief Data reset.
00069  * @param[in]       *q Points to the queue handle
00070  * @param[in]       *data Points to any type of data to put FIFO
00071  * @param[out]      *pDst Points to output matrix structure
00072  * @return     The function returns 0: success
00073  *                              -EINVAL (-22): Invalid Pointer
00074  *                              -2: Queue buffer is full, no more space
00075  **/
00076 int queue_reset(struct queue_t *q);
00077 
00078 
00079 /**
00080  * @brief Data enqueue.
00081  * @param[in]       *q points to the queue handle
00082  * @param[in]       *data points to any type of data to put FIFO
00083  * @return     The function returns 0: success
00084  *                              -EINVAL (-22): Invalid Pointer
00085  *                              -2: Queue buffer is full, no more space
00086  **/
00087 int enqueue(struct queue_t *q, void *data);
00088 
00089 
00090 /**
00091  * @brief Data dequeue.
00092  * @param[in]       *q points to the queue handle
00093  * @param[in]       *data points to any type of data to put FIFO
00094  * @param[out]      *data pop data from Queue
00095  * @return     The function returns 0: success
00096  *                              -EINVAL (-22): Invalid Pointer or data
00097  *                              -2: Queue buffer is empty
00098  **/
00099 int dequeue(struct queue_t *q, void *data);
00100 
00101 
00102 
00103 /**
00104  * @brief Queue Destroy
00105  * @param[in]       *q points to the queue handle
00106  **/
00107 void queue_destroy(struct queue_t *q);
00108 
00109 /**
00110  * @brief Number of elements in Queue
00111  * @param[in]       *q points to the queue handle
00112  * @return      number of elements
00113  **/
00114 int queue_len(struct queue_t *q);
00115 
00116 
00117 /*
00118     Reads the item from the front of queue but does not remove
00119 */
00120 /**
00121  * @brief Copies an item from the front of queue to data, but does not remove it from queue
00122  * @param[in]  *q points to the queue handle
00123  * @param[out]  Copy of item from front of the queue
00124  * @return      if value is greater than 0, return value is number of elements.
00125                 If value is less than 0, returns -EINVAL (-22)
00126  **/
00127 
00128 int queue_front(struct queue_t *q, void *data);
00129 
00130 /**
00131  * @brief Removes an item from front of queue
00132  * @param[in]   *q points to the queue handle
00133  * @return      status, success or fail
00134  **/
00135 int queue_pop(struct queue_t *q);
00136 
00137 /**
00138  * @brief       returns fifo usage info
00139  * @param[in]   *q points to the queue handle
00140  * @param[out]  *total returns total FIFO size in number of elements
00141  * @param[out]  *nm_item returns number of elements in FIFO
00142  * @return      status, success or fail
00143  *              -EINVAL (-22): Invalid Pointer, data or parameters
00144  **/
00145 int queue_usage(struct queue_t *q, int *total, int *nm_item);
00146 
00147 /**
00148  * @brief       Pops out delimiter terminated string
00149  * @param[in]   *q points to the queue handle
00150  * @param[out]  *buf output char array to write
00151  * @param[in]   delimiter Delimiter character, NULL for string
00152  * @param[in]   buffer_size Maximum buffer size to write the output char array
00153  * @return      status, string length if positive or fail if negative
00154  *              -EINVAL (-22): Invalid Pointer, data or parameters
00155  **/
00156 int dequeue_string(struct queue_t *q, char *buf, char delimiter, int buffer_size);
00157 
00158 /**
00159  * @brief       Pushes null terminated string (char array)
00160  * @param[in]   *q points to the queue handle
00161  * @param[in]   *data string(char array) to add it to the circullar buffer
00162  * @param[in]   sz 'data' length
00163  * @return      status, success or fail
00164  *              -EINVAL (-22): Invalid Pointer, data or parameters
00165  **/
00166 int enqueue_string(struct queue_t *q, char *data, int sz);
00167 
00168 #ifdef __cplusplus
00169 }
00170 #endif
00171 #endif //_QUEUE_H_