Bluetooth: controller: Added comments related to AD data double buffering

Added inline comments explaining the implementation of AD
data PDU double buffering.

Signed-off-by: Vinayak Kariappa Chettimada <vich@nordicsemi.no>

subsys/bluetooth/controller/ll_sw/nordic/lll/lll_adv.c

@@ -153,6 +153,14 @@ int lll_adv_data_init(struct lll_adv_pdu *pdu)
 
 int lll_adv_data_reset(struct lll_adv_pdu *pdu)
 {
+	/* NOTE: this function is used on HCI reset to mem-zero the structure
+	 *       members that otherwise was zero-ed by the architecture
+	 *       startup code that zero-ed the .bss section.
+	 *       pdu[0] element in the array is not initialized as subsequent
+	 *       call to lll_adv_data_init will allocate a PDU buffer and
+	 *       assign that.
+	 */
+
 	pdu->first = 0U;
 	pdu->last = 0U;
 	pdu->pdu[1] = NULL;
@@ -349,6 +357,10 @@ int lll_adv_scan_req_report(struct lll_adv *lll, struct pdu_adv *pdu_adv_rx,
 }
 #endif /* CONFIG_BT_CTLR_SCAN_REQ_NOTIFY */
 
+
+/* Helper function to initialize data variable both at power up and on
+ * HCI reset.
+ */
 static int init_reset(void)
 {
 	/* Initialize AC PDU pool */

subsys/bluetooth/controller/ll_sw/nordic/lll/lll_adv.h

@@ -10,6 +10,14 @@
 #define BT_CTLR_ADV_SET 1
 #endif /* CONFIG_BT_CTLR_ADV_SET */
 
+/* Structure used to double buffer pointers of AD Data PDU buffer.
+ * The first and last members are used to make modification to AD data to be
+ * context safe. Thread always appends or updates the buffer pointed to
+ * the array element indexed by the member last.
+ * LLL in the ISR context, checks, traverses to the valid pointer indexed
+ * by the member first, such that the buffer is the latest commited by
+ * the thread context.
+ */
 struct lll_adv_pdu {
 	uint8_t volatile first;
 	uint8_t          last;

subsys/bluetooth/controller/ll_sw/ull.c

@@ -418,6 +418,16 @@ void ll_reset(void)
 {
 	int err;
 
+	/* Note: The sequence of reset control flow is as follows:
+	 * - Reset ULL context, i.e. stop ULL scheduling, abort LLL events etc.
+	 * - Reset LLL context, i.e. post LLL event abort, let LLL cleanup its
+	 *   variables, if any.
+	 * - Reset ULL static variables (which otherwise was mem-zeroed in cases
+	 *   if power-on reset wherein architecture startup mem-zeroes .bss
+	 *   sections.
+	 * - Initialize ULL context variable, similar to on-power-up.
+	 */
+
 #if defined(CONFIG_BT_BROADCASTER)
 	/* Reset adv state */
 	err = ull_adv_reset();
@@ -520,7 +530,7 @@ void ll_reset(void)
 	}
 
 #if defined(CONFIG_BT_BROADCASTER)
-	/* Finalize after adv state reset */
+	/* Finalize after adv state LLL context reset */
 	err = ull_adv_reset_finalize();
 	LL_ASSERT(!err);
 #endif /* CONFIG_BT_BROADCASTER */