queue.h

00001 /*******************************************************************************
00002 * Copyright (C) Maxim Integrated Products, Inc., All rights Reserved.
00003 * 
00004 * This software is protected by copyright laws of the United States and
00005 * of foreign countries. This material may also be protected by patent laws
00006 * and technology transfer regulations of the United States and of foreign
00007 * countries. This software is furnished under a license agreement and/or a
00008 * nondisclosure agreement and may only be used or reproduced in accordance
00009 * with the terms of those agreements. Dissemination of this information to
00010 * any party or parties not specified in the license agreement and/or
00011 * nondisclosure agreement is expressly prohibited.
00012 *
00013 * The above copyright notice and this permission notice shall be included
00014 * in all copies or substantial portions of the Software.
00015 *
00016 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
00017 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
00018 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
00019 * IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES
00020 * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
00021 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
00022 * OTHER DEALINGS IN THE SOFTWARE.
00023 *
00024 * Except as contained in this notice, the name of Maxim Integrated
00025 * Products, Inc. shall not be used except as stated in the Maxim Integrated
00026 * Products, Inc. Branding Policy.
00027 *
00028 * The mere transfer of this software does not imply any licenses
00029 * of trade secrets, proprietary technology, copyrights, patents,
00030 * trademarks, maskwork rights, or any other form of intellectual
00031 * property whatsoever. Maxim Integrated Products, Inc. retains all
00032 * ownership rights.
00033 *******************************************************************************
00034 */
00035 
00036 #ifndef _QUEUE_H_
00037 #define _QUEUE_H_
00038 #include <stdio.h>
00039 #include <string.h>
00040 #include <stdint.h>
00041 #include <stdlib.h>
00042 #include <stdbool.h>
00043 #include <errno.h>
00044 
00045 #ifndef UNIT_TEST
00046 #include "platform.h"
00047 #else
00048 #ifndef enter_critical_section
00049 #define enter_critical_section()
00050 #endif
00051 
00052 #ifndef exit_critical_section
00053 #define exit_critical_section()
00054 #endif
00055 
00056 #ifndef pr_info
00057 #define pr_info(...) printf(__VA_ARGS__)
00058 #endif
00059 #endif
00060 
00061 #define QUEUE_USAGE_STATS
00062 
00063 struct queue_t {
00064     char *wr; // write pointer
00065     char *rd; // read pointer
00066     char *base; // buffer base pointer
00067     int num_item; // number of data item
00068     int ovf_item; // Number of overflowed data
00069     int buffer_size; // buffer size in bytes
00070     int max_buffer_size; // buffer size in bytes
00071     int item_size; // data size
00072     char *name;
00073 #ifdef QUEUE_USAGE_STATS
00074     int pop_cnt;
00075     int push_cnt;
00076     int stats_period_cnt;
00077 #endif
00078 };
00079 
00080 #ifdef __cplusplus
00081 extern "C" {
00082 #endif
00083 
00084 /**
00085  * @brief       Queue initialization.
00086  * @param[in]   *q Points to the queue handle
00087  * @param[in]   *buf Points to external queue buffer
00088  * @param[in]   item_size Data size
00089  * @param[in]   buffer_size Total buffer size in bytes
00090  * @param[out]  *pDst points to output matrix structure
00091  * @return  The function returns 0: success
00092  *               -EINVAL (-22): Invalid Pointer, data or parameters
00093  *               -2: Queue buffer is full, no more space
00094  **/
00095 int queue_init(struct queue_t *q, void *buf, int item_size, int buffer_size);
00096 
00097 
00098 
00099 /**
00100  * @brief       Queue initialization by name.
00101  * @param[in]   *q Points to the queue handle
00102  * @param[in]   *buf Points to external queue buffer
00103  * @param[in]   item_size Data size
00104  * @param[in]   buffer_size Total buffer size in bytes
00105  * @param[out]  *pDst points to output matrix structure
00106  * @param[in]   Set queue name for debugging
00107  * @return      The function returns 0: success
00108  *               -EINVAL (-22): Invalid Pointer, data or parameters
00109  *               -2: Queue buffer is full, no more space
00110  **/
00111 int queue_init_by_name(struct queue_t *q, void *buf, int item_size, int buffer_size, const char *name);
00112 
00113 
00114 
00115 /**
00116  * @brief       Reset queue
00117  * @param[in]   *q Points to the queue handle
00118  * @param[in]   *data Points to any type of data to put FIFO
00119  * @param[out]  *pDst Points to output matrix structure
00120  * @return      The function returns 0: success
00121  *               -EINVAL (-22): Invalid Pointer
00122  *
00123  **/
00124 int queue_reset(struct queue_t *q);
00125 
00126 
00127 
00128 /**
00129  * @brief       Update item size and reset queue. Usign of this command requires exta cauion.
00130  * @param[in]   *q Points to the queue handle
00131  * @return     The function returns 0: success
00132  *                  -EINVAL (-22): Invalid Pointer
00133  *
00134  **/
00135 int queue_update_items_size(struct queue_t *q, int item_size);
00136 
00137 
00138 
00139 /**
00140  * @brief       Data enqueue.
00141  * @param[in]   *q points to the queue handle
00142  * @param[in]   *data points to any type of data to put FIFO
00143  * @return      The function returns 0: success
00144  *               -EINVAL (-22): Invalid Pointer
00145  *               -2: Queue buffer is full, no more space
00146  **/
00147 int enqueue(struct queue_t *q, void *data);
00148 
00149 
00150 
00151 /**
00152  * @brief       Data dequeue.
00153  * @param[in]   *q points to the queue handle
00154  * @param[in]   *data points to any type of data to put FIFO
00155  * @param[out]  *data pop data from Queue
00156  * @return      The function returns 0: success
00157  *               -EINVAL (-22): Invalid Pointer or data
00158  *               -2: Queue buffer is empty
00159  **/
00160 int dequeue(struct queue_t *q, void *data);
00161 
00162 
00163 
00164 /**
00165  * @brief       Queue Destroy
00166  * @param[in]   *q points to the queue handle
00167  **/
00168 void queue_destroy(struct queue_t *q);
00169 
00170 
00171 
00172 /**
00173  * @brief       Number of elements in Queue
00174  * @param[in]   *q points to the queue handle
00175  * @return      number of elements
00176  **/
00177 int queue_len(struct queue_t *q);
00178 
00179 
00180 
00181 /**
00182  * @brief       Copies an item from the front of queue to data, but does not remove it from queue
00183  * @param[in]  *q points to the queue handle
00184  * @param[out]  Copy of item from front of the queue
00185  * @return      if value is greater than 0, return value is number of elements.
00186                 If value is less than 0, returns -EINVAL (-22)
00187  **/
00188 int queue_front(struct queue_t *q, void *data);
00189 
00190 
00191 
00192 /**
00193  * @brief       Copies n items from the front of the queue, but does not remove them
00194  * @param[in]   *q - points to the queue handle
00195  * @param[out]  *data - The buffer to hold copied data
00196  * @param[in]   n - the number of items to remove
00197  * @param[in]   buf_sz - input *data buffer size
00198  * @return      0: success
00199  *                -EINVAL (-22): Invalid pointer
00200  *                -2: Queue contains less than n items
00201  */
00202 int queue_front_n(struct queue_t *q, void *data, int n, int buf_sz);
00203 
00204 
00205 
00206 /**
00207  * @brief       Removes an item from front of queue
00208  * @param[in]   *q points to the queue handle
00209  * @return      status, success or fail
00210  **/
00211 int queue_pop(struct queue_t *q);
00212 
00213 /**
00214  * @brief       Removes n items from the front of the queue
00215  * @param[in]   *q - points to the queue handle
00216  * @param[in]   n - the number of items to remove
00217  * @return      0: success
00218  *                -EINVAL (-22): Invalid pointer
00219  *                -2: Queue contains less than n items
00220  */
00221 int queue_pop_n(struct queue_t *q, int n);
00222 
00223 
00224 
00225 /**
00226  * @brief       Checks if queue is fill
00227  * @param[in]   *q points to the queue handle
00228  * @return      true (full), false (not full)
00229  *
00230  **/
00231 bool queue_is_full(struct queue_t *q);
00232 
00233 
00234 
00235 /**
00236  * @brief       returns fifo usage info
00237  * @param[in]   *q points to the queue handle
00238  * @param[out]  *total returns total FIFO size in number of elements
00239  * @param[out]  *nm_item returns number of elements in FIFO
00240  * @return      status, success or fail
00241  *               -EINVAL (-22): Invalid Pointer, data or parameters
00242  **/
00243 int queue_usage(struct queue_t *q, int *total, int *nm_item);
00244 
00245 
00246 
00247 /**
00248  * @brief       Pops out delimiter terminated string
00249  * @param[in]   *q points to the queue handle
00250  * @param[out]  *buf output char array to write
00251  * @param[in]   buffer_size Maximum buffer size to write the output char array
00252  * @return      status, string length if positive or fail if negative
00253  *               -EINVAL (-22): Invalid Pointer, data or parameters
00254  **/
00255 int dequeue_string(struct queue_t *q, char *buf, int buffer_size);
00256 
00257 
00258 
00259 /**
00260  * @brief       Pushes null terminated string (char array)
00261  * @param[in]   *q points to the queue handle
00262  * @param[in]   *data string(char array) to add it to the circullar buffer
00263  * @param[in]   sz 'data' length
00264  * @return      status, success or fail
00265  *               -EINVAL (-22): Invalid Pointer, data or parameters
00266  **/
00267 int enqueue_string(struct queue_t *q, char *data, int sz);
00268 
00269 
00270 /**
00271  * @brief       Counts length of string in queue
00272  * @param[in]   *q points to the queue handle
00273  * @return      status, success or fail
00274  *               -EINVAL (-22): Invalid Pointer, data or parameters
00275  *               if ret >= 0, string length
00276  **/
00277 int queue_str_len(struct queue_t *q);
00278 
00279 
00280 
00281 void queue_n_test(void);
00282 
00283 int enqueue_test(struct queue_t *q, void *data);
00284 int dequeue_test(struct queue_t *q, void *data);
00285 
00286 #ifdef __cplusplus
00287 }
00288 #endif
00289 #endif //_QUEUE_H_