Diff: Utilities/queue.h

Revision:

1:f60eafbf009a

Child:

3:2fe2ff1ca0dc

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Utilities/queue.h	Wed Apr 10 14:56:25 2019 +0300
@@ -0,0 +1,288 @@
+/*******************************************************************************
+* Author: Ismail Kose, Ismail.Kose@maximintegrated.com
+* Copyright (C) 2016 Maxim Integrated Products, Inc., All Rights Reserved.
+*
+* Permission is hereby granted, free of charge, to any person obtaining a
+* copy of this software and associated documentation files (the "Software"),
+* to deal in the Software without restriction, including without limitation
+* the rights to use, copy, modify, merge, publish, distribute, sublicense,
+* and/or sell copies of the Software, and to permit persons to whom the
+* Software is furnished to do so, subject to the following conditions:
+*
+* The above copyright notice and this permission notice shall be included
+* in all copies or substantial portions of the Software.
+*
+* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+* IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES
+* OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+* ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+* OTHER DEALINGS IN THE SOFTWARE.
+*
+* Except as contained in this notice, the name of Maxim Integrated
+* Products, Inc. shall not be used except as stated in the Maxim Integrated
+* Products, Inc. Branding Policy.
+*
+* The mere transfer of this software does not imply any licenses
+* of trade secrets, proprietary technology, copyrights, patents,
+* trademarks, maskwork rights, or any other form of intellectual
+* property whatsoever. Maxim Integrated Products, Inc. retains all
+* ownership rights.
+*******************************************************************************
+*/
+
+#ifndef _QUEUE_H_
+#define _QUEUE_H_
+#include <stdio.h>
+#include <string.h>
+#include <stdint.h>
+#include <stdlib.h>
+#include <stdbool.h>
+#include <errno.h>
+
+#ifndef UNIT_TEST
+#include "platform.h"
+#else
+#ifndef enter_critical_section
+#define enter_critical_section()
+#endif
+
+#ifndef exit_critical_section
+#define exit_critical_section()
+#endif
+
+#ifndef pr_info
+#define pr_info(...) printf(__VA_ARGS__)
+#endif
+#endif
+
+#define QUEUE_USAGE_STATS
+
+struct queue_t {
+	char *wr; // write pointer
+	char *rd; // read pointer
+	char *base; // buffer base pointer
+	int num_item; // number of data item
+	int ovf_item; // Number of overflowed data
+	int buffer_size; // buffer size in bytes
+	int max_buffer_size; // buffer size in bytes
+	int item_size; // data size
+	char *name;
+#ifdef QUEUE_USAGE_STATS
+	int pop_cnt;
+	int push_cnt;
+	int stats_period_cnt;
+#endif
+};
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief		Queue initialization.
+ * @param[in]   *q Points to the queue handle
+ * @param[in]   *buf Points to external queue buffer
+ * @param[in]   item_size Data size
+ * @param[in]   buffer_size Total buffer size in bytes
+ * @param[out]  *pDst points to output matrix structure
+ * @return	The function returns 0: success
+ *               -EINVAL (-22): Invalid Pointer, data or parameters
+ *               -2: Queue buffer is full, no more space
+ **/
+int queue_init(struct queue_t *q, void *buf, int item_size, int buffer_size);
+
+
+
+/**
+ * @brief		Queue initialization by name.
+ * @param[in]   *q Points to the queue handle
+ * @param[in]   *buf Points to external queue buffer
+ * @param[in]   item_size Data size
+ * @param[in]   buffer_size Total buffer size in bytes
+ * @param[out]  *pDst points to output matrix structure
+ * @param[in]   Set queue name for debugging
+ * @return      The function returns 0: success
+ *               -EINVAL (-22): Invalid Pointer, data or parameters
+ *               -2: Queue buffer is full, no more space
+ **/
+int queue_init_by_name(struct queue_t *q, void *buf, int item_size, int buffer_size, const char *name);
+
+
+
+/**
+ * @brief		Reset queue
+ * @param[in]   *q Points to the queue handle
+ * @param[in]   *data Points to any type of data to put FIFO
+ * @param[out]  *pDst Points to output matrix structure
+ * @return      The function returns 0: success
+ *               -EINVAL (-22): Invalid Pointer
+ *
+ **/
+int queue_reset(struct queue_t *q);
+
+
+
+/**
+ * @brief		Update item size and reset queue. Usign of this command requires exta cauion.
+ * @param[in]   *q Points to the queue handle
+ * @return     The function returns 0: success
+ *					-EINVAL (-22): Invalid Pointer
+ *
+ **/
+int queue_update_items_size(struct queue_t *q, int item_size);
+
+
+
+/**
+ * @brief		Data enqueue.
+ * @param[in]   *q points to the queue handle
+ * @param[in]   *data points to any type of data to put FIFO
+ * @return      The function returns 0: success
+ *               -EINVAL (-22): Invalid Pointer
+ *               -2: Queue buffer is full, no more space
+ **/
+int enqueue(struct queue_t *q, void *data);
+
+
+
+/**
+ * @brief		Data dequeue.
+ * @param[in]   *q points to the queue handle
+ * @param[in]   *data points to any type of data to put FIFO
+ * @param[out]  *data pop data from Queue
+ * @return      The function returns 0: success
+ *               -EINVAL (-22): Invalid Pointer or data
+ *               -2: Queue buffer is empty
+ **/
+int dequeue(struct queue_t *q, void *data);
+
+
+
+/**
+ * @brief		Queue Destroy
+ * @param[in]   *q points to the queue handle
+ **/
+void queue_destroy(struct queue_t *q);
+
+
+
+/**
+ * @brief		Number of elements in Queue
+ * @param[in]   *q points to the queue handle
+ * @return		number of elements
+ **/
+int queue_len(struct queue_t *q);
+
+
+
+/**
+ * @brief		Copies an item from the front of queue to data, but does not remove it from queue
+ * @param[in]  *q points to the queue handle
+ * @param[out]  Copy of item from front of the queue
+ * @return		if value is greater than 0, return value is number of elements.
+				If value is less than 0, returns -EINVAL (-22)
+ **/
+int queue_front(struct queue_t *q, void *data);
+
+
+
+/**
+ * @brief		Copies n items from the front of the queue, but does not remove them
+ * @param[in]	*q - points to the queue handle
+ * @param[out]	*data - The buffer to hold copied data
+ * @param[in]	n - the number of items to remove
+ * @param[in]	buf_sz - input *data buffer size
+ * @return		0: success
+ *                -EINVAL (-22): Invalid pointer
+ *                -2: Queue contains less than n items
+ */
+int queue_front_n(struct queue_t *q, void *data, int n, int buf_sz);
+
+
+
+/**
+ * @brief		Removes an item from front of queue
+ * @param[in]	*q points to the queue handle
+ * @return		status, success or fail
+ **/
+int queue_pop(struct queue_t *q);
+
+/**
+ * @brief		Removes n items from the front of the queue
+ * @param[in]	*q - points to the queue handle
+ * @param[in]	n - the number of items to remove
+ * @return		0: success
+ *                -EINVAL (-22): Invalid pointer
+ *                -2: Queue contains less than n items
+ */
+int queue_pop_n(struct queue_t *q, int n);
+
+
+
+/**
+ * @brief		Checks if queue is fill
+ * @param[in]	*q points to the queue handle
+ * @return		true (full), false (not full)
+ *
+ **/
+bool queue_is_full(struct queue_t *q);
+
+
+
+/**
+ * @brief		returns fifo usage info
+ * @param[in]	*q points to the queue handle
+ * @param[out]	*total returns total FIFO size in number of elements
+ * @param[out]	*nm_item returns number of elements in FIFO
+ * @return		status, success or fail
+ *               -EINVAL (-22): Invalid Pointer, data or parameters
+ **/
+int queue_usage(struct queue_t *q, int *total, int *nm_item);
+
+
+
+/**
+ * @brief		Pops out delimiter terminated string
+ * @param[in]	*q points to the queue handle
+ * @param[out]	*buf output char array to write
+ * @param[in]	buffer_size Maximum buffer size to write the output char array
+ * @return		status, string length if positive or fail if negative
+ *               -EINVAL (-22): Invalid Pointer, data or parameters
+ **/
+int dequeue_string(struct queue_t *q, char *buf, int buffer_size);
+
+
+
+/**
+ * @brief		Pushes null terminated string (char array)
+ * @param[in]	*q points to the queue handle
+ * @param[in]	*data string(char array) to add it to the circullar buffer
+ * @param[in]	sz 'data' length
+ * @return		status, success or fail
+ *               -EINVAL (-22): Invalid Pointer, data or parameters
+ **/
+int enqueue_string(struct queue_t *q, char *data, int sz);
+
+
+/**
+ * @brief		Counts length of string in queue
+ * @param[in]	*q points to the queue handle
+ * @return		status, success or fail
+ *               -EINVAL (-22): Invalid Pointer, data or parameters
+ *               if ret >= 0, string length
+ **/
+int queue_str_len(struct queue_t *q);
+
+
+
+void queue_n_test(void);
+
+int enqueue_test(struct queue_t *q, void *data);
+int dequeue_test(struct queue_t *q, void *data);
+
+#ifdef __cplusplus
+}
+#endif
+#endif //_QUEUE_H_