Update mqueue documentation.
Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/commit/90f65b68 Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/90f65b68 Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/90f65b68 Branch: refs/heads/develop Commit: 90f65b68734e08b504e81515d8d01477b2e854fa Parents: e7332c5 Author: Christopher Collins <[email protected]> Authored: Thu Jan 5 17:33:02 2017 -0800 Committer: Christopher Collins <[email protected]> Committed: Thu Jan 5 17:33:02 2017 -0800 ---------------------------------------------------------------------- docs/os/core_os/mqueue/mqueue.md | 40 +++++++++++++-------------- docs/os/core_os/mqueue/os_mqueue_get.md | 6 ++-- docs/os/core_os/mqueue/os_mqueue_init.md | 25 ++++++++++++++--- docs/os/core_os/mqueue/os_mqueue_put.md | 9 +++--- 4 files changed, 46 insertions(+), 34 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/90f65b68/docs/os/core_os/mqueue/mqueue.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mqueue/mqueue.md b/docs/os/core_os/mqueue/mqueue.md index 08a8e5f..2868983 100644 --- a/docs/os/core_os/mqueue/mqueue.md +++ b/docs/os/core_os/mqueue/mqueue.md @@ -1,14 +1,17 @@ # Mqueue -Mqueue (Mbuf event queue) is a set of APIs built on top of the mbuf and event queue code. A typical networking stack operation is to put a packet on a queue and post an event to the task handling that queue. Mqueue was designed to provide a common API so that individual packages would not each have to create similar code. +The mqueue construct allows a task to wake up when it receives data. Typically, this data is in the form of packets received over a network. A common networking stack operation is to put a packet on a queue and post an event to the task monitoring that queue. When the task handles the event, it processes each packet on the packet queue. -The mqueue data structure consists of a queue head pointer (a "stailq" queue; a singly linked list with head structure having a pointer to the start and end of the list) and an os event structure. Packets (packet header mbufs) are added to the queue using the `omp_next` pointer in the `os_mbuf_pkthdr` structure of the mbuf. The event is used to post to the task an event of type `OS_EVENT_T_MQUEUE_DATA`. - -<br> +<br> ### Using Mqueue -The following code sample will demonstrate how to use an mqueue. This is a simple example where packets are put on a "receive queue" and a task processes that "receive queue" by incrementing the total number of packet received and then freeing the packet. Not shown in the code example is a call `my_task_rx_data_func`. Presumably, some other code will call this API. +The following code sample demonstrates how to use an mqueue. In this example: + +* packets are put on a receive queue +* a task processes each packet on the queue (increments a receive counter) + +Not shown in the code example is a call `my_task_rx_data_func`. Presumably, some other code will call this API. <br> @@ -18,23 +21,29 @@ uint32_t pkts_rxd; struct os_mqueue rxpkt_q; struct os_eventq my_task_evq; +/** + * Removes each packet from the receive queue and processes it. + */ void process_rx_data_queue(void) { struct os_mbuf *om; - /* Drain all packets off queue and process them */ while ((om = os_mqueue_get(&rxpkt_q)) != NULL) { ++pkts_rxd; os_mbuf_free_chain(om); } } +/** + * Called when a packet is received. + */ int my_task_rx_data_func(struct os_mbuf *om) { int rc; + /* Enqueue the received packet and wake up the listening task. */ rc = os_mqueue_put(&rxpkt_q, &my_task_evq, om); if (rc != 0) { return -1; @@ -56,25 +65,15 @@ my_task_handler(void *arg) /* Initialize mqueue */ os_mqueue_init(&rxpkt_q, NULL); + /* Process each event posted to our eventq. When there are no events to + * process, sleep until one arrives. + */ while (1) { - ev = os_eventq_get(&my_task_evq); - switch (ev->ev_type) { - - case OS_EVENT_T_MQUEUE_DATA: - process_rx_data_queue(); - break; - - default: - assert(0); - break; - } + os_eventq_run(&my_task_evq); } } - ``` - - ### Data Structures ```c @@ -95,4 +94,3 @@ The functions available in Mqueue are: | [os_mqueue_init](os_mqueue_init.md) | Initializes an mqueue. | | [os_mqueue_get](os_mqueue_get.md) | Retrieves a packet off an Mqueue. | | [os_mqueue_put](os_mqueue_put.md) | Adds a packet (i.e. packet header mbuf) to an mqueue. | - http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/90f65b68/docs/os/core_os/mqueue/os_mqueue_get.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mqueue/os_mqueue_get.md b/docs/os/core_os/mqueue/os_mqueue_get.md index e54ef8e..001f7dc 100644 --- a/docs/os/core_os/mqueue/os_mqueue_get.md +++ b/docs/os/core_os/mqueue/os_mqueue_get.md @@ -4,7 +4,7 @@ struct os_mbuf *os_mqueue_get(struct os_mqueue *mq) ``` -Retrieves a packet off an Mqueue. Returns a pointer to the mbuf at the head of the mbuf chain. **NULL** if no packets are on the queue. +Retrieves a packet off an mqueue. Returns a pointer to the mbuf at the head of the mbuf chain or **NULL** if no packets are on the queue. <br> @@ -12,7 +12,7 @@ Retrieves a packet off an Mqueue. Returns a pointer to the mbuf at the head of t | Arguments | Description | |-----------|-------------| -| `mq` | Pointer to Mqueue structure | +| `mq` | The mqueue to retrieve an mbuf from. | <br> @@ -40,5 +40,3 @@ process_rx_data_queue(void) } } ``` - - http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/90f65b68/docs/os/core_os/mqueue/os_mqueue_init.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mqueue/os_mqueue_init.md b/docs/os/core_os/mqueue/os_mqueue_init.md index ff0b04f..880d648 100644 --- a/docs/os/core_os/mqueue/os_mqueue_init.md +++ b/docs/os/core_os/mqueue/os_mqueue_init.md @@ -1,9 +1,24 @@ ## <font color="#F2853F" style="font-size:24pt">os_mqueue_init</font> ```c -int os_mqueue_init(struct os_mqueue *mq, void *arg) +int +os_mqueue_init(struct os_mqueue *mq, os_event_fn *ev_cb, void *arg) ``` -Initializes an queue. Sets the event argument in the os event of the mqueue to `arg`. Sets type of event to `OS_EVENT_T_MQUEUE_DATA`. + +Initializes an mqueue. An mqueue is a queue of mbufs that ties to a particular task's event queue. Mqueues form a helper API around a common paradigm: wait on an event queue until at least one packet is available, then process a queue of packets. + +#### Arguments + +| Arguments | Description | +|-----------|-------------| +| `mq` | The mqueue to initialize | +| `ev_cb` | The callback to associate with the mqeueue event. Typically, this callback pulls each packet off the mqueue and processes them. +| `arg` | The argument to associate with the mqueue event. + +@return 0 on success, non-zero on failure. + + +Initializes an mqueue. Sets the event argument in the os event of the mqueue to `arg`. <br> @@ -25,10 +40,12 @@ Initializes an queue. Sets the event argument in the os event of the mqueue to ` #### Example ```c +/* Event callback to execute when a packet is received. */ +extern void process_rx_data_queue(void); + /* Declare mqueue */ struct os_mqueue rxpkt_q; /* Initialize mqueue */ -os_mqueue_init(&rxpkt_q, NULL); +os_mqueue_init(&rxpkt_q, process_rx_data_queue, NULL); ``` - http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/90f65b68/docs/os/core_os/mqueue/os_mqueue_put.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mqueue/os_mqueue_put.md b/docs/os/core_os/mqueue/os_mqueue_put.md index d5f4b13..c65041e 100644 --- a/docs/os/core_os/mqueue/os_mqueue_put.md +++ b/docs/os/core_os/mqueue/os_mqueue_put.md @@ -4,7 +4,7 @@ int os_mqueue_put(struct os_mqueue *mq, struct os_eventq *evq, struct os_mbuf *m) ``` -Adds a packet (i.e. packet header mbuf) to an mqueue. Post event to `evq`. +Adds a packet (i.e. packet header mbuf) to an mqueue. The event associated with the mqueue gets posted to the specified eventq. <br> @@ -12,9 +12,9 @@ Adds a packet (i.e. packet header mbuf) to an mqueue. Post event to `evq`. | Arguments | Description | |-----------|-------------| -| `mq` | Pointer to mqueue | -| `evq` | Pointer to event queue where mqueue event should get posted | -| `m` | Pointer to packet header mbuf | +| `mq` | The mbuf queue to append the mbuf to. | +| `evq` | The event queue to post an event to. | +| `m` | The mbuf to append to the mbuf queue. | <br> @@ -42,4 +42,3 @@ my_task_rx_data_func(struct os_mbuf *om) return 0; } ``` -
