bluetooth: controller: Add comments across ull

* Clarify certain functions and data structures in upper link layer.
 * Disambiguate node rx event done, add commentary.

MFIFO_DEQUEUE macro does string concatenation.
Thus MFIFO_DEQUEUE(done) does not refer to done (the stack local), but
mfifo_done.

No functional change expected.

Signed-off-by: Mark Ruvald Pedersen <mped@oticon.com>
This commit is contained in:
Mark Ruvald Pedersen 2019-02-14 10:04:17 +01:00 committed by Anas Nashif
commit a61938130b

View file

@ -116,10 +116,17 @@ static struct k_sem *sem_recv;
/* Entropy device */
static struct device *dev_entropy;
/* prepare and done event FIFOs */
/* Declare prepare-event FIFO: mfifo_prep: Queue of struct node_rx_event_done */
static MFIFO_DEFINE(prep, sizeof(struct lll_event), EVENT_PIPELINE_MAX);
static MFIFO_DEFINE(done, sizeof(void *), EVENT_PIPELINE_MAX);
/* Declare done-event FIFO: mfifo_done.
* Queue of pointers to struct node_rx_event_done.
* The actual backing behind these pointers is mem_done
*/
static MFIFO_DEFINE(done, sizeof(struct node_rx_event_done *),
EVENT_PIPELINE_MAX);
/* Backing storage for elements in mfifo_done */
static struct {
void *free;
u8_t pool[sizeof(struct node_rx_event_done) * EVENT_PIPELINE_MAX];
@ -169,7 +176,7 @@ static struct {
#define LINK_RX_POOL_SIZE (sizeof(memq_link_t) * (RX_CNT + 2 + \
BT_CTLR_MAX_CONN))
static struct {
u8_t quota_pdu;
u8_t quota_pdu; /* Number of un-utilized buffers */
void *free;
u8_t pool[LINK_RX_POOL_SIZE];
@ -352,6 +359,12 @@ void ll_reset(void)
LL_ASSERT(!err);
}
/**
* @brief Peek the next node_rx to send up to Host
* @details Tightly coupled with prio_recv_thread()
* Execution context: Controller thread
* @return TX completed
*/
u8_t ll_rx_get(void **node_rx, u16_t *handle)
{
struct node_rx_hdr *rx;
@ -379,6 +392,9 @@ ll_rx_get_again:
} while ((cmplt_prev != 0) ||
(cmplt_prev != cmplt_curr));
/* Do not send up buffers to Host thread that are
* marked for release
*/
if (rx->type == NODE_RX_TYPE_DC_PDU_RELEASE) {
(void)memq_dequeue(memq_ll_rx.tail,
&memq_ll_rx.head, NULL);
@ -411,6 +427,10 @@ ll_rx_get_again:
return cmplt;
}
/**
* @brief Commit the dequeue from memq_ll_rx, where ll_rx_get() did the peek
* @details Execution context: Controller thread
*/
void ll_rx_dequeue(void)
{
struct node_rx_hdr *rx = NULL;
@ -498,6 +518,13 @@ void ll_rx_dequeue(void)
case NODE_RX_TYPE_MESH_REPORT:
#endif /* CONFIG_BT_HCI_MESH_EXT */
/*
* We have just dequeued from memq_ll_rx; that frees up some
* quota for Link Layer. Note that we threw away the rx node
* we have just dequeued from memq_ll_rx. But, this is OK,
* since prio_recv_thread() peeked in memq_ll_rx via
* ll_rx_get() before.
*/
LL_ASSERT(mem_link_rx.quota_pdu < RX_CNT);
mem_link_rx.quota_pdu++;
@ -804,8 +831,15 @@ void ll_rx_put(memq_link_t *link, void *rx)
memq_enqueue(link, rx, &memq_ll_rx.tail);
}
/**
* @brief Permit another loop in the controller thread (prio_recv_thread)
* @details Execution context: ULL mayfly
*/
void ll_rx_sched(void)
{
/* sem_recv references the same semaphore (sem_prio_recv)
* in prio_recv_thread
*/
k_sem_give(sem_recv);
}
@ -1010,24 +1044,33 @@ void *ull_event_done_extra_get(void)
void *ull_event_done(void *param)
{
struct node_rx_event_done *done;
struct node_rx_event_done *evdone;
memq_link_t *link;
done = MFIFO_DEQUEUE(done);
if (!done) {
/* Obtain new node that signals "Done of an RX-event".
* Obtain this by dequeuing from the global 'mfifo_done' queue.
* Note that 'mfifo_done' is a queue of pointers, not of
* struct node_rx_event_done
*/
evdone = MFIFO_DEQUEUE(done);
if (!evdone) {
/* Not fatal if we can not obtain node, though
* we will loose the packets in software stack.
* If this happens during Conn Upd, this could cause LSTO
*/
return NULL;
}
link = done->hdr.link;
done->hdr.link = NULL;
link = evdone->hdr.link;
evdone->hdr.link = NULL;
done->hdr.type = NODE_RX_TYPE_EVENT_DONE;
done->param = param;
evdone->hdr.type = NODE_RX_TYPE_EVENT_DONE;
evdone->param = param;
ull_rx_put(link, done);
ull_rx_put(link, evdone);
ull_rx_sched();
return done;
return evdone;
}
u8_t ull_entropy_get(u8_t len, u8_t *rand)
@ -1082,10 +1125,14 @@ static inline int init_reset(void)
return 0;
}
/**
* @brief Allocate buffers for done events
*/
static inline void done_alloc(void)
{
u8_t idx;
/* mfifo_done is a queue of pointers */
while (MFIFO_ENQUEUE_IDX_GET(done, &idx)) {
memq_link_t *link;
struct node_rx_hdr *rx;
@ -1279,7 +1326,7 @@ static void rx_demux(void *param)
#if defined(CONFIG_BT_CONN)
struct node_tx *node_tx;
memq_link_t *link_tx;
u16_t handle;
u16_t handle; /* Handle to Ack TX */
#endif /* CONFIG_BT_CONN */
LL_ASSERT(rx);
@ -1311,6 +1358,11 @@ static void rx_demux(void *param)
} while (link);
}
/**
* @brief Dispatch rx objects
* @details Rx objects are only peeked, not dequeued yet.
* Execution context: ULL high priority Mayfly
*/
static inline void rx_demux_rx(memq_link_t *link, struct node_rx_hdr *rx)
{
/* Demux Rx objects */