common: queue: Add ability to iterate over queue

This is done via:
* queue_begin(q) gets an iterator to the start of the list
* queue_next(q, &it) updates the iterator to the next element
** Once the iterator reaches the end, ptr will be NULL.
** If the queue was modified between the _begin and _next calls
   queue_next will terminate the iterator (set the ptr to NULL).

BUG=None
TEST=New unit tests
BRANCH=None

Change-Id: I643f544ed91bafac8e8b4c85545d4070f2d82610
Signed-off-by: Yuval Peress <peress@chromium.org>
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/1879715
Reviewed-by: Jack Rosenthal <jrosenth@chromium.org>

1 files changed, 28 insertions, 0 deletions

diff --git a/include/queue.h b/include/queue.h
index 8b431c57c4..6cf72563cb 100644
--- a/include/queue.h
+++ b/include/queue.h
@@ -8,6 +8,7 @@
 #define __CROS_EC_QUEUE_H
 
 #include "common.h"
+#include "util.h"
 
 #include <stddef.h>
 #include <stdint.h>
@@ -110,6 +111,33 @@ size_t queue_space(struct queue const *q);
 /* Return TRUE if the queue is full. */
 int queue_is_full(struct queue const *q);
 
+struct queue_iterator_state {
+	size_t offset;
+	size_t head;
+	size_t tail;
+};
+
+struct queue_iterator {
+	void *ptr;
+	struct queue_iterator_state _state;
+};
+
+/**
+ * Get a pointer to the first element (the head).
+ *
+ * @param q Pointer to the queue.
+ * @param it Pointer to an Iterator that will point to the first element.
+ */
+void queue_begin(struct queue const *q, struct queue_iterator *it);
+
+/**
+ * Get a pointer to the next element in the queue given a current iterator.
+ *
+ * @param q Pointer to a constant queue to query.
+ * @param it The iterator to move forward.
+ */
+void queue_next(struct queue const *q, struct queue_iterator *it);
+
 /*
  * Chunk based queue access.  A queue_chunk is a contiguous region of queue
  * buffer units.