mynewt-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ma...@apache.org
Subject incubator-mynewt-site git commit: First stab at adding documentation for os_eventq.
Date Wed, 13 Jan 2016 23:13:30 GMT
Repository: incubator-mynewt-site
Updated Branches:
  refs/heads/master 62cd55ee7 -> 2e215108b


First stab at adding documentation for os_eventq.


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/2e215108
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/2e215108
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/2e215108

Branch: refs/heads/master
Commit: 2e215108bae24fd2325ab21c8ed58eb4891bd49b
Parents: 62cd55e
Author: Marko Kiiskila <marko@runtime.io>
Authored: Wed Jan 13 15:12:51 2016 -0800
Committer: Marko Kiiskila <marko@runtime.io>
Committed: Wed Jan 13 15:12:51 2016 -0800

----------------------------------------------------------------------
 docs/os/event_queue.md | 220 +++++++++++++++++++++++++++++++++++++-------
 1 file changed, 185 insertions(+), 35 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/2e215108/docs/os/event_queue.md
----------------------------------------------------------------------
diff --git a/docs/os/event_queue.md b/docs/os/event_queue.md
index 56648a2..b849e02 100644
--- a/docs/os/event_queue.md
+++ b/docs/os/event_queue.md
@@ -1,16 +1,59 @@
 # Event Queues
 
 
-Insert synopsis here
+Event queue is a way of serializing events arring to a task. This makes it easy to queue
processing to happen inside task's context. This would be done either from an interrupt handler,
or from another task.
 
+Events arrive in a form of a data structure *struct os_event*.
 
 ## Description
 
-Describe scheduler here
+Events are in form of a data structure *struct os_event*, and they are queued to data structure
*struct os_eventq*.
+
+Queue must be initialized before trying to add events to it. This is done using *os_eventq_init()*.
+
+Common way of using event queues is to have a task loop while calling *os_eventq_get()*,
waiting for work to do.
+Other tasks (or interrupts) then call *os_eventq_put()* to wake it up. Once event has been
queued task waiting on that queue is woken up, and will get a pointer to queued event structure.
+Processing task would then act according to event type.
+
+When *os_event* is queued, it should not be freed until processing task is done with it.
+
+It is assumed that there is only one task consuming events from an event queue. Only one
task should be sleeping on a particular *os_eventq* at a time.
+
+Note that os_callout subsystem assumes that event queue is used as the wakeup mechanism.
 
 ## Data structures
 
-Replace this with the list of data structures used, why, any neat features
+<code>
+```no-highlight
+struct os_event {
+    uint8_t ev_queued;
+    uint8_t ev_type;
+    void *ev_arg;
+    STAILQ_ENTRY(os_event) ev_next;
+};
+```
+</code>
+
+| Element | Description |
+|---------|-------------|
+| ev_queued | Internal field, which tells whether event is linked into an *os_eventq* already
|
+| ev_type | Type of an event. This should be unique, as it should be used by processing task
to figure out what the event means |
+| ev_arg | Can be used further as input to task processing this event |
+| ev_next | Linkage attaching this event to an event queue |
+
+<code>
+```no-highlight
+struct os_eventq {
+    struct os_task *evq_task;
+    STAILQ_HEAD(, os_event) evq_list;
+};
+```
+</code>
+
+| Element | Description |
+|---------|-------------|
+| evq_task | Pointer to task if there is task sleeping on *os_eventq_get()* |
+| evq_list | Queue head for list of events in this queue |
 
 ## List of Functions
 
@@ -19,8 +62,10 @@ Replace this with the list of data structures used, why, any neat features
 The functions available in this OS feature are:
 
 * [os_eventq_init](#os_eventq_init)
+* [os_eventq_put](#os_eventq_put)
 * [os_eventq_put2](#os_eventq_put2)
-* add the rest
+* [os_eventq_get](#os_eventq_get)
+* [os_eventq_remove](#os_eventq_remove)
 
 
 ## Function Reference
@@ -34,33 +79,92 @@ The functions available in this OS feature are:
     os_eventq_init(struct os_eventq *evq)
 ```
 
-<Insert short description>
+Initializes *struct os_eventq*, making it ready for use.
+
+#### Arguments
+
+| Arguments | Description |
+|-----------|-------------|
+| evq |  Pointer to event queue getting initialized  |
+
+#### Returned values
+
+None
+
+#### Notes
+
+Usually done at subsystem init time; before OS has been started, and before interrupts generating
events have been enabled.
+
+
+#### Example
+
+<Add text to set up the context for the example here>
+This initializes event queue used by newtmgr task.
+
+<code>
+```no-highlight
+struct os_eventq g_nmgr_evq;
+
+int
+nmgr_task_init(uint8_t prio, os_stack_t *stack_ptr, uint16_t stack_len)
+{
+    /* variable declarations here */
+
+    os_eventq_init(&g_nmgr_evq);
+
+    /* initialization continues here */
+}
+```
+</code>
+
+---------------------
+
+## <font color="#F2853F" style="font-size:24pt"> os_eventq_put</font>
+
+```no-highlight
+void
+os_eventq_put(struct os_eventq *evq, struct os_event *ev)
+```
+
+Queues an event to tail of the event queue.
 
 
 #### Arguments
 
 | Arguments | Description |
 |-----------|-------------|
-| xx |  explain argument xx  |
-| yy |  explain argument yy  |
+| evq |  Queue where event is being placed  |
+| ev |  Event which is being queued  |
+
 
 #### Returned values
 
-List any values returned.
-Error codes?
+N/A
 
 #### Notes 
 
-Any special feature/special benefit that we want to tout. 
-Does it need to be used with some other specific functions?
-Any caveats to be careful about (e.g. high memory requirements).
+Functionality is of *os_eventq_put2()*, but this is to be called from a task context only.
 
 #### Example
 
 <Add text to set up the context for the example here>
+This is used to pass info about an event to a task handling it.
 
 ```no-highlight
-<Insert the code snippet here>
+    /* Get an event structure off the queue */
+    ev = (struct os_event *)os_memblock_get(&g_hci_os_event_pool);
+    if (!ev) {
+        err = os_memblock_put(&g_hci_cmd_pool, hci_ev);
+        assert(err == OS_OK);
+        return -1;
+    }
+
+    /* Fill out the event and post to Link Layer */
+    ev->ev_queued = 0;
+    ev->ev_type = BLE_HOST_HCI_EVENT_CTLR_EVENT;
+    ev->ev_arg = hci_ev;
+    os_eventq_put(&ble_hs_evq, ev);
+
 ```
 
 ---------------------
@@ -68,74 +172,120 @@ Any caveats to be careful about (e.g. high memory requirements).
 ## <font color="#F2853F" style="font-size:24pt"> os_eventq_put2</font>
 
 ```no-highlight
-   <Insert function callout here >
+void
+os_eventq_put2(struct os_eventq *evq, struct os_event *ev, int isr)
 ```
 
-<Insert short description>
+Queues an event to tail of the event queue.
 
 
 #### Arguments
 
 | Arguments | Description |
 |-----------|-------------|
-| xx |  explain argument xx  |
-| yy |  explain argument yy  |
+| evq |  Queue where event is being placed  |
+| ev |  Event which is being queued  |
+| isr | Tells whether call is being made from within interrupt handler or not |
 
 #### Returned values
 
-List any values returned.
-Error codes?
+N/A
 
 #### Notes 
 
-Any special feature/special benefit that we want to tout. 
-Does it need to be used with some other specific functions?
-Any caveats to be careful about (e.g. high memory requirements).
+If the event has already been queued, nothing happens. Including event's relative position
within the queue itself.
+
+This can be called either from interrupt handler (in which case *isr* should be set to 1),
or from another task context (in which case *isr should be set as 0).
 
 #### Example
 
-<Add text to set up the context for the example here>
+This wakes up the task waiting on task1_evq, which processes console input (console input
comes from UART, and is passed in in interrupt context).
 
 ```no-highlight
-<Insert the code snippet here>
+static void
+my_cons_input(int full_line)
+{
+    os_eventq_put2(&task1_evq, &cons_ev, 1);
+}
 ```
 
 ---------------------
    
-## <font color="#F2853F" style="font-size:24pt"> next_one </font>
+## <font color="#F2853F" style="font-size:24pt"> os_eventq_get</font>
 
 ```no-highlight
-   <Insert function callout here >
+void
+os_eventq_get(struct os_eventq *evq)
 ```
 
-<Insert short description>
+Fetches the first event from a queue. Task will sleep until something gets queued.
 
 
 #### Arguments
 
 | Arguments | Description |
 |-----------|-------------|
-| xx |  explain argument xx  |
-| yy |  explain argument yy  |
+| evq |  Queue to wait on  |
+
 
 #### Returned values
 
-List any values returned.
-Error codes?
+Will return with a pointer to first *struct event* which is in the queue.
 
 #### Notes 
 
-Any special feature/special benefit that we want to tout. 
-Does it need to be used with some other specific functions?
-Any caveats to be careful about (e.g. high memory requirements).
 
 #### Example
 
 <Add text to set up the context for the example here>
+Main loop of an example task.
 
 ```no-highlight
-<Insert the code snippet here>
+    while (1) {
+        ev = os_eventq_get(&task1_evq);
+        assert(ev);
+        if (ev->ev_type == CONS_EV_TYPE) {
+			/* XXX do stuff */
+        }
+    }
+
 ```
 
 ---------------------
 
+## <font color="#F2853F" style="font-size:24pt"> os_eventq_remove</font>
+
+```no-highlight
+void
+os_eventq_remove(struct os_eventq *evq, struct os_event *ev)
+```
+
+Removes an event which has been placed in a queue.
+
+
+#### Arguments
+
+| Arguments | Description |
+|-----------|-------------|
+| evq |  Queue where event is being removed from |
+| ev |  Event which is being removed  |
+
+
+#### Returned values
+
+N/A
+
+#### Notes
+
+
+#### Example
+
+<Add text to set up the context for the example here>
+This is from os_callout_stop(). User wants to stop a callout from getting passed to a task.
If the event has already been queued, then remove it before it is seen.
+
+```no-highlight
+    if (c->c_evq) {
+        os_eventq_remove(c->c_evq, &c->c_ev);
+    }
+```
+


Mime
View raw message