common: queue: Update chunk struct and get read/write logic

This change updates the queue_get_write_chunk and
queue_get_read_chunk logic to return an updated queue_chunk.
The new chunk uses a void * for the buffer and replaces length
with count. This more tightly aligns to how the rest of the
queue functions operate. Further, it adds the ability to
offset the write chunk. This is important as it allows wrapping.
For example:

With a queue of 8 units, 1 byte each. Assume H=2, T=5. Previously,
we were only able to ever get the 3 bytes at 5-7. Using the offset
of 3 though, we can now also get the 2 byte write chunk 0-1.

BUG=chromium:966506
BRANCH=None
TEST=Added unit tests

Change-Id: I40216c36aa0dc95ec4d15fc587d4b1f08a17ef73
Signed-off-by: Yuval Peress <peress@chromium.org>
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/1637415
Reviewed-by: Enrico Granata <egranata@chromium.org>
Reviewed-by: Jett Rink <jettrink@chromium.org>

1 files changed, 19 insertions, 7 deletions

diff --git a/include/queue.h b/include/queue.h
index 29cab07383..bf952b0b53 100644
--- a/include/queue.h
+++ b/include/queue.h
@@ -112,26 +112,38 @@ int queue_is_full(struct queue const *q);
 
 /*
  * Chunk based queue access.  A queue_chunk is a contiguous region of queue
- * buffer bytes, not units.  It may represent either free space in the queue
- * or entries.
+ * buffer units.
  */
 struct queue_chunk {
-	size_t  length;
-	uint8_t *buffer;
+	size_t  count;
+	void *buffer;
 };
 
 /*
  * Return the largest contiguous block of free space from the tail of the
- * queue.  This may not be all of the available free space in the queue.  Once
- * some or all of the free space has been written to you must call
+ * queue + offset.  This may not be all of the available free space in the
+ * queue.  Once some or all of the free space has been written to you must call
  * queue_advance_tail to update the queue.  You do not need to fill all of the
  * free space returned before calling queue_advance_tail, and you may call
  * queue_advance tail multiple times for a single chunk.  But you must not
  * advance the tail more than the length of the chunk, or more than the actual
  * number of units that you have written to the free space represented by the
  * chunk.
+ *
+ * Since this function returns continuous space, offset will allow accessing
+ * writable memory that is wrapped. For example:
+ *
+ *  *: Used entry
+ *  -: Free space
+ *
+ *    H  T
+ * |--***---|
+ *
+ * A call to queue_get_write_chunk(&q, 0) will return 3 entries starting at T.
+ * To be able to also write the 2 leading writable indicies, we'll need to use
+ * queue_get_write_chunk(&q, 3), which will return 2 entries at queue index 0.
  */
-struct queue_chunk queue_get_write_chunk(struct queue const *q);
+struct queue_chunk queue_get_write_chunk(struct queue const *q, size_t offset);
 
 /*
  * Return the largest contiguous block of units from the head of the queue.