You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by ad...@apache.org on 2016/03/04 23:35:48 UTC
[1/3] incubator-mynewt-site git commit: Add mqueue documentation
Repository: incubator-mynewt-site
Updated Branches:
refs/heads/master 7aa609da4 -> a72d044cd
Add 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/736ca9a0
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/736ca9a0
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/736ca9a0
Branch: refs/heads/master
Commit: 736ca9a059a833cf2e941d055d76608b64fd764b
Parents: 7451406
Author: wes3 <wi...@micosa.io>
Authored: Thu Mar 3 22:53:32 2016 -0800
Committer: wes3 <wi...@micosa.io>
Committed: Thu Mar 3 22:53:32 2016 -0800
----------------------------------------------------------------------
docs/os/core_os/mbuf/mbuf.md | 12 ----
docs/os/core_os/mqueue/mqueue.md | 96 +++++++++++++++++++++++++++
docs/os/core_os/mqueue/os_mqueue_get.md | 44 ++++++++++++
docs/os/core_os/mqueue/os_mqueue_init.md | 35 ++++++++++
docs/os/core_os/mqueue/os_mqueue_put.md | 45 +++++++++++++
docs/os/core_os/msys/msys.md | 20 ++++++
mkdocs.yml | 2 +-
7 files changed, 241 insertions(+), 13 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/736ca9a0/docs/os/core_os/mbuf/mbuf.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/mbuf/mbuf.md b/docs/os/core_os/mbuf/mbuf.md
index 7b445b3..472d96a 100644
--- a/docs/os/core_os/mbuf/mbuf.md
+++ b/docs/os/core_os/mbuf/mbuf.md
@@ -156,18 +156,6 @@ mbuf_usage_example2(struct mbuf *rxpkt)
<br>
-# Msys
-
-msys stands for "system mbufs" and is set of API built on top of the mbuf code. The basic idea behind msys is the following. The developer can create different size mbuf pools and register them with msys. The application then allocates mbufs using the msys API (as opposed to the mbuf API). The msys code will choose the mbuf pool with the smallest mbufs that can accommodate the requested size.
-
-Let us walk through an example where the user registers three mbuf pools with msys: one with 32 byte mbufs, one with 256 and one with 2048. If the user requests an mbuf with 10 bytes, the 32-byte mbuf pool is used. If the request is for 33 bytes the 256 byte mbuf pool is used. If an mbuf data size is requested that is larger than any of the pools (say, 4000 bytes) the largest pool is used. While this behaviour may not be optimal in all cases that is the currently implemented behaviour. All this means is that the user is not guaranteed that a single mbuf can hold the requested data.
-
-The msys code will not allocate an mbuf from a larger pool if the chosen mbuf pool is empty. Similarly, the msys code will not chain together a number of smaller mbufs to accommodate the requested size. While this behaviour may change in future implementations the current code will simply return NULL. Using the above example, say the user requests 250 bytes. The msys code chooses the appropriate pool (i.e. the 256 byte mbuf pool) and attempts to allocate an mbuf from that pool. If that pool is empty, NULL is returned even though the 32 and 2048 byte pools are not empty.
-
-Note that no added descriptions on how to use the msys API are presented here (other than in the API descriptions themselves) as the msys API is used in exactly the same manner as the mbuf API. The only difference is that mbuf pools are added to msys by calling `os_msys_register().`
-
-<br>
-
## Data Structures
```no-highlight
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/736ca9a0/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 e69de29..93e3c7b 100644
--- a/docs/os/core_os/mqueue/mqueue.md
+++ b/docs/os/core_os/mqueue/mqueue.md
@@ -0,0 +1,96 @@
+# Mqueue
+
+Mqueue (Mbuf event queue) is a set of API 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 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 a task an event of type OS_EVENT_T_MQUEUE_DATA.
+
+<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.
+
+<br>
+
+
+```no-highlight
+uint32_t pkts_rxd;
+struct os_mqueue rxpkt_q;
+struct os_eventq my_task_evq;
+
+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);
+ }
+}
+
+int
+my_task_rx_data_func(struct os_mbuf *om)
+{
+ int rc;
+
+ rc = os_mqueue_put(&rxpkt_q, &my_task_evq, om);
+ if (rc != 0) {
+ return -1;
+ }
+
+ return 0;
+}
+
+void
+my_task_handler(void *arg)
+{
+ struct os_event *ev;
+ struct os_callout_func *cf;
+ int rc;
+
+ /* Initialize eventq */
+ os_eventq_init(&my_task_evq);
+
+ /* Initialize mqueue */
+ os_mqueue_init(&rxpkt_q, NULL);
+
+ 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;
+ }
+ }
+}
+
+```
+
+
+
+## Data Structures
+
+```no-highlight
+struct os_mqueue {
+ STAILQ_HEAD(, os_mbuf_pkthdr) mq_head;
+ struct os_event mq_ev;
+};
+```
+
+<br>
+
+## List of Functions
+
+The functions available in Mqueue are:
+
+* [os_mqueue_init](os_mqueue_init.md)
+* [os_mqueue_get](os_mqueue_get.md)
+* [os_mqueue_put](os_mqueue_put.md)
+
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/736ca9a0/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 e69de29..c07a6b0 100644
--- a/docs/os/core_os/mqueue/os_mqueue_get.md
+++ b/docs/os/core_os/mqueue/os_mqueue_get.md
@@ -0,0 +1,44 @@
+## <font color="#F2853F" style="font-size:24pt">os_mqueue_get</font>
+
+```no-highlight
+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.
+
+<br>
+
+#### Arguments
+
+| Arguments | Description |
+|-----------|-------------|
+| mq | Pointer to Mqueue structure |
+
+<br>
+
+#### Returned values
+
+The packet at the head of the queue or NULL if no packets are on the queue.
+
+<br>
+
+#### Example
+
+```no-highlight
+uint32_t pkts_rxd;
+struct os_mqueue rxpkt_q;
+
+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);
+ }
+}
+```
+
+---------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/736ca9a0/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 e69de29..4b71a49 100644
--- a/docs/os/core_os/mqueue/os_mqueue_init.md
+++ b/docs/os/core_os/mqueue/os_mqueue_init.md
@@ -0,0 +1,35 @@
+## <font color="#F2853F" style="font-size:24pt">os_mqueue_init</font>
+
+```no-highlight
+int os_mqueue_init(struct os_mqueue *mq, 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.
+
+<br>
+
+#### Arguments
+
+| Arguments | Description |
+|-----------|-------------|
+| mq | Pointer to a mqueue structure |
+| arg | Event argument |
+
+<br>
+
+#### Returned values
+
+0: success. All other values indicate an error
+
+<br>
+
+#### Example
+
+```no-highlight
+/* Declare mqueue */
+struct os_mqueue rxpkt_q;
+
+/* Initialize mqueue */
+os_mqueue_init(&rxpkt_q, NULL);
+```
+
+---------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/736ca9a0/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 e69de29..a8b379c 100644
--- a/docs/os/core_os/mqueue/os_mqueue_put.md
+++ b/docs/os/core_os/mqueue/os_mqueue_put.md
@@ -0,0 +1,45 @@
+## <font color="#F2853F" style="font-size:24pt">os_mqueue_put</font>
+
+```no-highlight
+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*.
+
+<br>
+
+#### Arguments
+
+| Arguments | Description |
+|-----------|-------------|
+| mq | Pointer to mqueue |
+| evq | Pointer to event queue where mqueue event should get posted |
+| m | Pointer to packet header mbuf |
+
+<br>
+
+#### Returned values
+
+0: success
+OS_EINVAL: the mbuf is not a packet header mbuf.
+
+<br>
+
+#### Example
+
+```no-highlight
+int
+my_task_rx_data_func(struct os_mbuf *om)
+{
+ int rc;
+
+ rc = os_mqueue_put(&rxpkt_q, &my_task_evq, om);
+ if (rc != 0) {
+ return -1;
+ }
+
+ return 0;
+}
+```
+
+---------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/736ca9a0/docs/os/core_os/msys/msys.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/msys/msys.md b/docs/os/core_os/msys/msys.md
index e69de29..2e910a3 100644
--- a/docs/os/core_os/msys/msys.md
+++ b/docs/os/core_os/msys/msys.md
@@ -0,0 +1,20 @@
+# Msys
+
+Msys stands for "system mbufs" and is a set of API built on top of the mbuf code. The basic idea behind msys is the following. The developer can create different size mbuf pools and register them with msys. The application then allocates mbufs using the msys API (as opposed to the mbuf API). The msys code will choose the mbuf pool with the smallest mbufs that can accommodate the requested size.
+
+Let us walk through an example where the user registers three mbuf pools with msys: one with 32 byte mbufs, one with 256 and one with 2048. If the user requests an mbuf with 10 bytes, the 32-byte mbuf pool is used. If the request is for 33 bytes the 256 byte mbuf pool is used. If an mbuf data size is requested that is larger than any of the pools (say, 4000 bytes) the largest pool is used. While this behaviour may not be optimal in all cases that is the currently implemented behaviour. All this means is that the user is not guaranteed that a single mbuf can hold the requested data.
+
+The msys code will not allocate an mbuf from a larger pool if the chosen mbuf pool is empty. Similarly, the msys code will not chain together a number of smaller mbufs to accommodate the requested size. While this behaviour may change in future implementations the current code will simply return NULL. Using the above example, say the user requests 250 bytes. The msys code chooses the appropriate pool (i.e. the 256 byte mbuf pool) and attempts to allocate an mbuf from that pool. If that pool is empty, NULL is returned even though the 32 and 2048 byte pools are not empty.
+
+Note that no added descriptions on how to use the msys API are presented here (other than in the API descriptions themselves) as the msys API is used in exactly the same manner as the mbuf API. The only difference is that mbuf pools are added to msys by calling `os_msys_register().`
+
+<br>
+
+## List of Functions
+
+The functions available in msys are:
+
+* [os_msys_get](os_msys_get.md)
+* [os_msys_get_pkthdr](os_msys_get_pkthdr.md)
+* [os_msys_register](os_msys_register.md)
+* [os_msys_reset](os_msys_reset.md)
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/736ca9a0/mkdocs.yml
----------------------------------------------------------------------
diff --git a/mkdocs.yml b/mkdocs.yml
index 488ba08..3a630e1 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -127,8 +127,8 @@ pages:
- MQueue:
- 'Overview': 'os/core_os/mqueue/mqueue.md'
- Functions:
- - 'os_mqueue_get': 'os/core_os/mqueue/os_mqueue_get.md'
- 'os_mqueue_init': 'os/core_os/mqueue/os_mqueue_init.md'
+ - 'os_mqueue_get': 'os/core_os/mqueue/os_mqueue_get.md'
- 'os_mqueue_put': 'os/core_os/mqueue/os_mqueue_put.md'
- Sanity:
- 'Overview': 'os/core_os/sanity/sanity.md'
[2/3] incubator-mynewt-site git commit: Merge branch 'mqueue' of
https://github.com/apache/incubator-mynewt-site
Posted by ad...@apache.org.
Merge branch 'mqueue' of https://github.com/apache/incubator-mynewt-site
This closes #30.
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/ebb9dcbc
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/ebb9dcbc
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/ebb9dcbc
Branch: refs/heads/master
Commit: ebb9dcbc81ffd964857c6577dcd23bac10874f68
Parents: 7aa609d 736ca9a
Author: aditihilbert <ad...@runtime.io>
Authored: Fri Mar 4 14:14:11 2016 -0800
Committer: aditihilbert <ad...@runtime.io>
Committed: Fri Mar 4 14:14:11 2016 -0800
----------------------------------------------------------------------
docs/os/core_os/mbuf/mbuf.md | 12 ----
docs/os/core_os/mqueue/mqueue.md | 96 +++++++++++++++++++++++++++
docs/os/core_os/mqueue/os_mqueue_get.md | 44 ++++++++++++
docs/os/core_os/mqueue/os_mqueue_init.md | 35 ++++++++++
docs/os/core_os/mqueue/os_mqueue_put.md | 45 +++++++++++++
docs/os/core_os/msys/msys.md | 20 ++++++
mkdocs.yml | 2 +-
7 files changed, 241 insertions(+), 13 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/ebb9dcbc/mkdocs.yml
----------------------------------------------------------------------
[3/3] incubator-mynewt-site git commit: mqueue documentation added.
This closes #30.
Posted by ad...@apache.org.
mqueue documentation added. This closes #30.
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/a72d044c
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/a72d044c
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/a72d044c
Branch: refs/heads/master
Commit: a72d044cd34c873e2aa78f4a50e0fc7e973d8eec
Parents: ebb9dcb
Author: aditihilbert <ad...@runtime.io>
Authored: Fri Mar 4 14:35:31 2016 -0800
Committer: aditihilbert <ad...@runtime.io>
Committed: Fri Mar 4 14:35:31 2016 -0800
----------------------------------------------------------------------
docs/os/core_os/mqueue/mqueue.md | 6 +++---
docs/os/core_os/mqueue/os_mqueue_put.md | 1 +
docs/os/core_os/msys/os_msys_register.md | 4 ----
docs/os/core_os/msys/os_msys_reset.md | 4 ----
4 files changed, 4 insertions(+), 11 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/a72d044c/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 93e3c7b..7344ac4 100644
--- a/docs/os/core_os/mqueue/mqueue.md
+++ b/docs/os/core_os/mqueue/mqueue.md
@@ -1,14 +1,14 @@
# Mqueue
-Mqueue (Mbuf event queue) is a set of API 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.
+Mqueue (Mbuf event queue) is a set of API 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 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 a task an event of type OS_EVENT_T_MQUEUE_DATA.
+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>
## 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 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.
<br>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/a72d044c/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 a8b379c..b12aef4 100644
--- a/docs/os/core_os/mqueue/os_mqueue_put.md
+++ b/docs/os/core_os/mqueue/os_mqueue_put.md
@@ -21,6 +21,7 @@ Adds a packet (i.e. packet header mbuf) to an mqueue. Post event to *evq*.
#### Returned values
0: success
+
OS_EINVAL: the mbuf is not a packet header mbuf.
<br>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/a72d044c/docs/os/core_os/msys/os_msys_register.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/msys/os_msys_register.md b/docs/os/core_os/msys/os_msys_register.md
index 8fb4257..c3726a0 100644
--- a/docs/os/core_os/msys/os_msys_register.md
+++ b/docs/os/core_os/msys/os_msys_register.md
@@ -21,10 +21,6 @@ Register an mbuf pool for use as a system mbuf pool. The pool should be initiali
<br>
-#### Notes
-
-<br>
-
#### Example
```no-highlight
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/a72d044c/docs/os/core_os/msys/os_msys_reset.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/msys/os_msys_reset.md b/docs/os/core_os/msys/os_msys_reset.md
index 1ed5875..a01bfd8 100644
--- a/docs/os/core_os/msys/os_msys_reset.md
+++ b/docs/os/core_os/msys/os_msys_reset.md
@@ -20,10 +20,6 @@ None
<br>
-#### Notes
-
-<br>
-
#### Example
```no-highlight