bluetooth: controller: Document mem, memq, util

Adds documentation-commentary to some infrastructure used by the LL.
It is a long-term effort to better document the LL.

Notably ticker and mayfly require more documentation; this will be
done later.

Signed-off-by: Mark Ruvald Pedersen <[email protected]>

Author: mped-oticon

subsys/bluetooth/controller/util/mem.c

@@ -17,8 +17,8 @@ void mem_init(void *mem_pool, u16_t mem_size, u16_t mem_count,
 {
 	*mem_head = mem_pool;
 
-	/* Store free mem_count after the list's next pointer at an aligned
-	 * memory location to ensure atomic read/write (in ARM for now).
+	/* Store free mem_count after the list's next pointer at an 32-bit
+	 * aligned memory location to ensure atomic read/write (in ARM for now).
 	 */
 	*((u16_t *)MROUND((u8_t *)mem_pool + sizeof(mem_pool))) = mem_count;
 
@@ -107,6 +107,10 @@ u16_t mem_index_get(void *mem, void *mem_pool, u16_t mem_size)
 	return ((u16_t)((u8_t *)mem - (u8_t *)mem_pool) / mem_size);
 }
 
+/**
+ * @brief  Copy bytes in reverse
+ * @details Example: [ 0x11 0x22 0x33 ] -> [ 0x33 0x22 0x11 ]
+ */
 void mem_rcopy(u8_t *dst, u8_t const *src, u16_t len)
 {
 	src += len;
@@ -115,6 +119,10 @@ void mem_rcopy(u8_t *dst, u8_t const *src, u16_t len)
 	}
 }
 
+/**
+ * @brief Determine if src[0..len-1] contains one or more non-zero bytes
+ * @return 0 if all bytes are zero; otherwise 1
+ */
 u8_t mem_nz(u8_t *src, u16_t len)
 {
 	while (len--) {
@@ -126,6 +134,9 @@ u8_t mem_nz(u8_t *src, u16_t len)
 	return 0;
 }
 
+/**
+ * @brief Unit test
+ */
 u32_t mem_ut(void)
 {
 #define BLOCK_SIZE  MROUND(10)

subsys/bluetooth/controller/util/mem.h

@@ -6,10 +6,34 @@
  */
 
 #ifndef MALIGN
+/**
+ * @brief Force compiler to place memory at-least on a x-byte boundary
+ * @details Compiler extension. Supported by GCC and Clang
+ */
 #define MALIGN(x) __attribute__((aligned(x)))
 #endif
 
 #ifndef MROUND
+/**
+ * @brief Round up to nearest multiple of 4, for unsigned integers
+ * @details
+ *   The addition of 3 forces x into the next multiple of 4. This is responsible
+ *   for the rounding in the the next step, to be Up.
+ *   For ANDing of ~3: We observe y & (~3) == (y>>2)<<2, and we recognize
+ *   (y>>2) as a floored division, which is almost undone by the left-shift. The
+ *   flooring can't be undone so have achieved a rounding.
+ *
+ *   Examples:
+ *    MROUND( 0) =  0
+ *    MROUND( 1) =  4
+ *    MROUND( 2) =  4
+ *    MROUND( 3) =  4
+ *    MROUND( 4) =  4
+ *    MROUND( 5) =  8
+ *    MROUND( 8) =  8
+ *    MROUND( 9) = 12
+ *    MROUND(13) = 16
+ */
 #define MROUND(x) (((u32_t)(x)+3) & (~((u32_t)3)))
 #endif
 

subsys/bluetooth/controller/util/memq.c

@@ -5,26 +5,66 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * FIFO-style "memory queue" permitting enqueue at tail and dequeue from head.
+ * Element's payload is a pointer to arbitrary memory.
+ *
+ * Implemented as a singly-linked list, with always one-more element.
+ * The linked list must always contain at least one link-element, as emptiness
+ * is given by head == tail.
+ * For a queue to be valid, it must be initialized with an initial link-element.
+ *
+ * Invariant: The tail element's mem pointer is DontCare.
+ *
+ * Note that at enqueue, memory is not coupled with its accompanying
+ * link-element, but the link-element before it!
+ *
+ * Call                    | State after call
+ * ------------------------+-------------------------------
+ * memq_init(I,H,T)        | H -> I[] <- T
+ * memq_enqueue(A,a,T);    | H -> I[a] -> A[] <- T
+ * memq_enqueue(B,b,T);    | H -> I[a] -> A[b] -> B[] <- T
+ * memq_dequeue(T,H,dest); | H -> A[b] -> B[] <- T  # I and a as return and dest
+ *
+ *   where H is the pointer to Head link-element (oldest element).
+ *   where T is the pointer to Tail link-element (newest element).
+ *   where I[]  means the initial link-element, whose mem pointer is DontCare.
+ *   where A[b] means the A'th link-element, whose mem pointer is b.
+ */
+
 #include <zephyr/types.h>
 #include <stddef.h>
 
 #include "memq.h"
 
-inline memq_link_t *memq_peek(memq_link_t *head, memq_link_t *tail, void **mem);
-
+/**
+ * @brief Initialize a memory queue to be empty and valid.
+ *
+ * @param link[in]  Initial link-element. Not associated with any mem
+ * @param head[out] Head of queue. Will be updated
+ * @param tail[out] Tail of queue. Will be updated
+ * @return          Initial link-element
+ */
 memq_link_t *memq_init(memq_link_t *link, memq_link_t **head, memq_link_t **tail)
 {
-	/* head and tail pointer to the initial link */
+	/* Head and tail pointer to the initial link - forms an empty queue */
 	*head = *tail = link;
 
 	return link;
 }
 
+/**
+ * @brief De-initialize a memory queue to be empty and invalid.
+ *
+ * @param head[in,out] Head of queue. Will be updated
+ * @param tail[in,out] Tail of queue. Will be updated
+ * @return             If empty, return initial link-element. Otherwise NULL
+ */
 memq_link_t *memq_deinit(memq_link_t **head, memq_link_t **tail)
 {
 	memq_link_t *link;
 
-	/* if head and tail are not equal, then queue is not empty */
+	/* If head and tail are not equal, then queue is not empty */
 	if (*head != *tail) {
 		return NULL;
 	}
@@ -35,47 +75,75 @@ memq_link_t *memq_deinit(memq_link_t **head, memq_link_t **tail)
 	return link;
 }
 
+/**
+ * @brief Enqueue at the tail of the queue
+ * @details Enqueue is destructive so tail will change to new tail
+ *
+ * @param link[in]     Element to become the new tail. Not associated mem
+ * @param mem[in]      Memory buffer. Will be owned by old tail
+ * @param tail[in,out] Tail of queue. Will be updated to point to link
+ * @return             New tail
+ */
 memq_link_t *memq_enqueue(memq_link_t *link, void *mem, memq_link_t **tail)
 {
-	/* make the current tail link's next point to new link */
+	/* Let the old tail element point to the new tail element */
 	(*tail)->next = link;
 
-	/* assign mem to current tail link's mem */
+	/* Let the old tail element point the the new memory */
 	(*tail)->mem = mem;
 
-	/* increment the tail! */
+	/* Update the tail-pointer to point to the new tail element.
+	 * The new tail-element is not expected to point to anything sensible
+	 */
 	*tail = link;
 
 	return link;
 }
 
+/**
+ * @brief Non-destructive peek of head of queue.
+ *
+ * @param head[in] Pointer to head link-element of queue
+ * @param tail[in] Pointer to tail link-element of queue
+ * @param mem[out] The memory pointed to by head-element
+ * @return         head or NULL if queue is empty
+ */
 memq_link_t *memq_peek(memq_link_t *head, memq_link_t *tail, void **mem)
 {
-	/* if head and tail are equal, then queue empty */
+	/* If head and tail are equal, then queue empty */
 	if (head == tail) {
 		return NULL;
 	}
 
-	/* extract the link's mem */
+	/* Extract the head link-element's memory */
 	if (mem) {
 		*mem = head->mem;
 	}
 
-	return head;
+	return head; /* queue was not empty */
 }
 
+/**
+ * @brief Remove and returns the head of queue.
+ * @details Dequeue is destructive so head will change to new head
+ *
+ * @param tail[in]     Pointer to tail link-element of queue
+ * @param head[in,out] Pointer to head link-element of queue. Will be updated
+ * @param mem[out]     The memory pointed to by head-element
+ * @return             head or NULL if queue is empty
+ */
 memq_link_t *memq_dequeue(memq_link_t *tail, memq_link_t **head, void **mem)
 {
-	memq_link_t *link;
+	memq_link_t *old_head;
 
-	/* use memq peek to get the link and mem */
-	link = memq_peek(*head, tail, mem);
-	if (!link) {
-		return link;
+	/* Use memq peek to get the old head and its mem */
+	old_head = memq_peek(*head, tail, mem);
+	if (old_head == NULL) {
+		return NULL; /* queue is empty */
 	}
 
-	/* increment the head to next link node */
-	*head = link->next;
+	/* Update the head-pointer to point to the new head element */
+	*head = old_head->next;
 
-	return link;
+	return old_head;
 }

subsys/bluetooth/controller/util/memq.h

@@ -5,9 +5,13 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * @brief   Element of a memory-queue
+ * @details Elements form a linked list, and as payload carries a pointer
+ */
 struct _memq_link {
-	struct _memq_link *next;
-	void              *mem;
+	struct _memq_link *next; /* permit chaining */
+	void              *mem;  /* payload */
 };
 
 typedef struct _memq_link memq_link_t;

subsys/bluetooth/controller/util/util.c

@@ -8,6 +8,17 @@
 #include <zephyr/types.h>
 #include "util.h"
 
+/**
+ * @brief Population count: Count the number of bits set to 1
+ * @details
+ * TODO: Faster methods available at [1].
+ * [1] http://graphics.stanford.edu/~seander/bithacks.html#CountBitsSetParallel
+ *
+ * @param octets     Data to count over
+ * @param octets_len Must not be bigger than 255/8 = 31 bytes
+ *
+ * @return popcnt of 'octets'
+ */
 u8_t util_ones_count_get(u8_t *octets, u8_t octets_len)
 {
 	u8_t one_count = 0U;