erkin yucel / mbed-os

mbed os with nrf51 internal bandgap enabled to read battery level

Dependents:   BLE_file_test BLE_Blink ExternalEncoder

docs/events.md@0:f269e3021894, 2016-10-23 (annotated)

Committer:
elessair
Date:
Sun Oct 23 15:10:02 2016 +0000
Revision:
0:f269e3021894
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
elessair 0:f269e3021894 1 # About the mbed OS event loop
elessair 0:f269e3021894 2
elessair 0:f269e3021894 3 One of the optional mbed OS features is an event loop mechanism that can be used to defer the execution of code in a different context. In particular, a common uses of an event loop is to postpone the execution of a code sequence from an interrupt handler to an user context. This is useful because of the specific constraints of code that runs in an interrupt handler:
elessair 0:f269e3021894 4
elessair 0:f269e3021894 5 - the execution of certain functions (notably some functions in the C library) is not safe.
elessair 0:f269e3021894 6 - various RTOS objects and functions can't be used from an interrupt context.
elessair 0:f269e3021894 7 - as a general rule, the code needs to finish as fast as possible, to allow other interrupts to be handled.
elessair 0:f269e3021894 8
elessair 0:f269e3021894 9 The event loop offers a solution to these issues in the form of an API that can be used to defer execution of code from the interrupt context to the user context. More generally, the event loop can be used anywhere in a program (not necessarily in an interrupt handler) to defer code execution to a different context.
elessair 0:f269e3021894 10
elessair 0:f269e3021894 11 # Overview of the mbed OS event loop
elessair 0:f269e3021894 12
elessair 0:f269e3021894 13 An event loop has two main components:
elessair 0:f269e3021894 14
elessair 0:f269e3021894 15 1. an **event queue**, used to store events. In mbed OS, *events* are pointers to functions (and optionally function arguments).
elessair 0:f269e3021894 16 2. an **event loop** that extracts events from the queue and executes them.
elessair 0:f269e3021894 17
elessair 0:f269e3021894 18 The mbed OS event queue is implemented by the [mbed-events library](http://github.com/ARMmbed/mbed-os/tree/master/events). It's a good idea to go through the [README of mbed-events](https://github.com/ARMmbed/mbed-os/blob/master/events/README.md), as it shows how to use the event queue.
elessair 0:f269e3021894 19
elessair 0:f269e3021894 20 The event loop must be created and started manually. The simplest way to achieve that is to create a `Thread` and run the event queue's `dispatch` method in the thread:
elessair 0:f269e3021894 21
elessair 0:f269e3021894 22 ```
elessair 0:f269e3021894 23 #include "mbed.h"
elessair 0:f269e3021894 24 #include "mbed_events.h"
elessair 0:f269e3021894 25
elessair 0:f269e3021894 26 // Create a queue that can hold a maximum of 32 events
elessair 0:f269e3021894 27 Queue queue(32 * EVENTS_EVENT_SIZE);
elessair 0:f269e3021894 28 // Create a thread that'll run the event queue's dispatch function
elessair 0:f269e3021894 29 Thread t;
elessair 0:f269e3021894 30
elessair 0:f269e3021894 31 int main () {
elessair 0:f269e3021894 32 // Start the event queue's dispatch thread
elessair 0:f269e3021894 33 t.start(callback(&queue, &EventQueue::dispatch_forever));
elessair 0:f269e3021894 34 ...
elessair 0:f269e3021894 35 }
elessair 0:f269e3021894 36 ```
elessair 0:f269e3021894 37
elessair 0:f269e3021894 38 Note that although this document assumes the presence of a single event loop in the system, there's nothing preventing the programmer to run more than one event loop, simply by following the create/start pattern above for each of them.
elessair 0:f269e3021894 39
elessair 0:f269e3021894 40 ## Using the event loop
elessair 0:f269e3021894 41
elessair 0:f269e3021894 42 Once the event loop is created, it can be used for posting events. Let's consider a very simple example of a program that attaches two interrupt handlers for an InterruptIn object, using the InterruptIn `rise` and `fall` functions. The `rise` handler will run in interrupt context, while the `fall` handler will run in user context (more specifically, in the context of the event loop's thread). The full code for the example can be found below:
elessair 0:f269e3021894 43
elessair 0:f269e3021894 44 ```
elessair 0:f269e3021894 45 #include "mbed.h"
elessair 0:f269e3021894 46 #include "mbed_events.h"
elessair 0:f269e3021894 47
elessair 0:f269e3021894 48 DigitalOut led1(LED1);
elessair 0:f269e3021894 49 InterruptIn sw(SW2);
elessair 0:f269e3021894 50 EventQueue queue(32 * EVENTS_EVENT_SIZE);
elessair 0:f269e3021894 51 Thread t;
elessair 0:f269e3021894 52
elessair 0:f269e3021894 53 void rise_handler(void) {
elessair 0:f269e3021894 54 printf("rise_handler in context %p\r\n", Thread::gettid());
elessair 0:f269e3021894 55 // Toggle LED
elessair 0:f269e3021894 56 led1 = !led1;
elessair 0:f269e3021894 57 }
elessair 0:f269e3021894 58
elessair 0:f269e3021894 59 void fall_handler(void) {
elessair 0:f269e3021894 60 printf("fall_handler in context %p\r\n", Thread::gettid());
elessair 0:f269e3021894 61 // Toggle LED
elessair 0:f269e3021894 62 led1 = !led1;
elessair 0:f269e3021894 63 }
elessair 0:f269e3021894 64
elessair 0:f269e3021894 65 int main() {
elessair 0:f269e3021894 66 // Start the event queue
elessair 0:f269e3021894 67 t.start(callback(&queue, &EventQueue::dispatch_forever));
elessair 0:f269e3021894 68 printf("Starting in context %p\r\n", Thread::gettid());
elessair 0:f269e3021894 69 // The 'rise' handler will execute in IRQ context
elessair 0:f269e3021894 70 sw.rise(rise_handler);
elessair 0:f269e3021894 71 // The 'fall' handler will execute in the context of thread 't'
elessair 0:f269e3021894 72 sw.fall(queue.event(fall_handler));
elessair 0:f269e3021894 73 }
elessair 0:f269e3021894 74
elessair 0:f269e3021894 75 ```
elessair 0:f269e3021894 76
elessair 0:f269e3021894 77 The above code executes two handler functions (`rise_handler` and `fall_handler`) in two different contexts:
elessair 0:f269e3021894 78
elessair 0:f269e3021894 79 1. in interrupt context when a rising edge is detected on `SW2` (`rise_handler`).
elessair 0:f269e3021894 80 2. in the context of the event loop's thread function when a falling edge is detected on `SW2` (`fall_handler`). `queue.event()` is called with `fall_handler` as an argument to specify that `fall_handler` will run in user context instead of interrupt context.
elessair 0:f269e3021894 81
elessair 0:f269e3021894 82 This is the output of the above program on a FRDM-K64F board after resetting the board and pressing the SW2 button twice:
elessair 0:f269e3021894 83
elessair 0:f269e3021894 84 ```
elessair 0:f269e3021894 85 Starting in context 0x20002c50
elessair 0:f269e3021894 86 fall_handler in context 0x20002c90
elessair 0:f269e3021894 87 rise_handler in context 0x0
elessair 0:f269e3021894 88 fall_handler in context 0x20002c90
elessair 0:f269e3021894 89 rise_handler in context 0x0
elessair 0:f269e3021894 90 ```
elessair 0:f269e3021894 91
elessair 0:f269e3021894 92 The program starts in the context of the thread that runs the `main` function (`0x29992c5`). When the uses presses SW2, `fall_handler` is automatically queued in the event queue, and it runs later in the context of thread `t` (`0x20002c90`). When the user releases the button, `rise_handler` is executed immediately, and it displays `0x0`, indicating that the code runs in interrupt context.
elessair 0:f269e3021894 93
elessair 0:f269e3021894 94 The code for `rise_handler` is problematic, since it calls `printf` in interrupt context, which is a potentially unsafe operation. Fortunately, this is exactly the kind of problem that event queues can solve. We can make the code safe by running `rise_handler` in user context (like we already do with `fall_handler`) by replacing this line:
elessair 0:f269e3021894 95
elessair 0:f269e3021894 96 ```
elessair 0:f269e3021894 97 sw.rise(rise_handler);
elessair 0:f269e3021894 98 ```
elessair 0:f269e3021894 99
elessair 0:f269e3021894 100 with this line:
elessair 0:f269e3021894 101
elessair 0:f269e3021894 102 ```
elessair 0:f269e3021894 103 sw.rise(queue.event(rise_handler));
elessair 0:f269e3021894 104 ```
elessair 0:f269e3021894 105
elessair 0:f269e3021894 106 The code is safe now, but we might've introduced another problem: latency. After the change above, the call to `rise_handler` will be queued, which means that it doesn't run immediately after the interrupt is raised anymore. For this example code, this isn't a problem, but some applications might require the code to respond as fast as possible to an interrupt. Let's assume that `rise_handler` must toggle the LED as quickly as possible in response to the user's action on SW2. To do that, in must run in interrupt context. However, `rise_handler` still needs to print a message indicating that the handler was called, but that's problematic since it's not safe to call `printf` from an interrupt context. The solution is to split `rise_handler` in two parts: the time critical part will run in interrupt context, while the non-critical part (displaying the message) will run in user context. This is easily doable using `queue.call`:
elessair 0:f269e3021894 107
elessair 0:f269e3021894 108 ```
elessair 0:f269e3021894 109 void rise_handler_user_context(void) {
elessair 0:f269e3021894 110 printf("rise_handler_user_context in context %p\r\n", Thread::gettid());
elessair 0:f269e3021894 111 }
elessair 0:f269e3021894 112
elessair 0:f269e3021894 113 void rise_handler(void) {
elessair 0:f269e3021894 114 // Execute the time critical part first
elessair 0:f269e3021894 115 led1 = !led1;
elessair 0:f269e3021894 116 // The rest can execute later in user context (and can contain code that's not interrupt safe).
elessair 0:f269e3021894 117 // We use the 'queue.call' function to add an event (the call to 'rise_handler_user_context') to the queue.
elessair 0:f269e3021894 118 queue.call(rise_handler_user_context);
elessair 0:f269e3021894 119 }
elessair 0:f269e3021894 120
elessair 0:f269e3021894 121 ```
elessair 0:f269e3021894 122
elessair 0:f269e3021894 123 After replacing the code for `rise_handler` as above, the output of our example becomes:
elessair 0:f269e3021894 124
elessair 0:f269e3021894 125 ```
elessair 0:f269e3021894 126 Starting in context 0x20002c50
elessair 0:f269e3021894 127 fall_handler in context 0x20002c90
elessair 0:f269e3021894 128 rise_handler_user_context in context 0x20002c90
elessair 0:f269e3021894 129 fall_handler in context 0x20002c90
elessair 0:f269e3021894 130 rise_handler_user_context in context 0x20002c90
elessair 0:f269e3021894 131 ```
elessair 0:f269e3021894 132
elessair 0:f269e3021894 133 The scenario above (splitting an interrupt handler's code into time critical code and non-time critical code) is another common pattern that's easily implemented with event queues. Another thing to learn from this example is that queuing code that's not interrupt safe is not the only thing that event queues can be used for. Any kind of code can be queued and deferred for later execution.
elessair 0:f269e3021894 134
elessair 0:f269e3021894 135 We used `InterruptIn` for the example above, but the same kind of code can be used with any `attach()`-like functions in the SDK. Example include `Serial::attach()`, `Ticker::attach()`, `Ticker::attach_us()`, `Timeout::attach()`.
elessair 0:f269e3021894 136
elessair 0:f269e3021894 137 ## Where to go from here
elessair 0:f269e3021894 138
elessair 0:f269e3021894 139 We just scratched the surface of how event queues work in mbed OS. The `EventQueue` and `Event` classes in the `mbed-events` library offer a lot of features that are not covered in this document, including calling functions with arguments, queueing functions to be called after a delay, or queueing functions to be called periodically. The [README of the mbed-events library](https://github.com/ARMmbed/mbed-os/blob/master/events/README.md) shows more ways to use events and event queues. For more details about how the events library is implemented, check [this file](https://github.com/ARMmbed/mbed-os/blob/master/events/equeue/README.md).