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/19 00:33:34 UTC
[1/3] incubator-mynewt-site git commit: Event queue tutorial.
Repository: incubator-mynewt-site
Updated Branches:
refs/heads/master 4f897dde0 -> 90421ab65
Event queue tutorial.
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/bc8e257b
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/bc8e257b
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/bc8e257b
Branch: refs/heads/master
Commit: bc8e257b8e64f05d723ea4d9518359621bd58713
Parents: df9b6fb
Author: Marko Kiiskila <ma...@runtime.io>
Authored: Thu Mar 17 18:33:05 2016 -0700
Committer: Marko Kiiskila <ma...@runtime.io>
Committed: Thu Mar 17 18:33:05 2016 -0700
----------------------------------------------------------------------
docs/os/tutorials/event_queue.md | 345 ++++++++++++++++++++++++++++++++++
1 file changed, 345 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/bc8e257b/docs/os/tutorials/event_queue.md
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/event_queue.md b/docs/os/tutorials/event_queue.md
new file mode 100644
index 0000000..f135279
--- /dev/null
+++ b/docs/os/tutorials/event_queue.md
@@ -0,0 +1,345 @@
+# How to define a task which uses event queues to manage multiple events
+
+## Introduction
+
+Event queue is a mechanism by which you can serialize incoming events for your task. You can use it to get info about arrived hardware interrupts, callout expirations and messages from other tasks.
+
+Benefit of doing inter-task communication this way is that there should be less resources that need to be locked.
+
+Benefit of doing interrupt processing in a task context instead of inside interrupt context is that you are not blocking other HW interrupts when doing the work. The same goes for high priority tasks in the system; they're blocked until the interrupt handler returns. From task context you'll also be able to access other OS facilities; you can sleep while waiting for a lock, for example.
+
+## Example app
+
+Here I'm going to write an app which demonstrates the use of event queues for communication between tasks. I'll also use OS callouts for timer expiration, and another event from a GPIO interrupt.
+
+I use inputs from these 3 sources to toggle 3 GPIO outputs on my STM32F3discovery board.
+
+### Create project
+
+I start by creating a project, and populating it with repositories incubator-mynewt-core and mynewt_stm32f3. See [STM32F3 tutorial](STM32F303.md) if you need help with this.
+
+
+### Create application
+
+Here's what the pkg.yml looks for the application.
+
+```no-highlight
+[marko@IsMyLaptop:~/src/events]$ cat apps/event_sample/pkg.yml
+pkg.name: apps/event_sample
+pkg.type: app
+
+pkg.deps:
+ - "@apache-mynewt-core/libs/os"
+ - "@apache-mynewt-core/hw/hal"
+ - "@apache-mynewt-core/libs/console/stub"
+```
+
+### Initialize the event queue structure
+
+This must be done before anyone tries to place events to the queue. Here it's done before any task gets created. Initialization is done by calling *os_eventq_init()*.
+
+```c
+#define MY_TASK_PRIO 4
+#define MY_TASK_STACK_SZ 512
+
+static struct os_eventq my_eventq;
+static os_stack_t my_task_stack[MY_TASK_STACK_SZ];
+static struct os_task my_task_str;
+
+void
+init_tasks(void)
+{
+ struct os_task taskid;
+
+ os_eventq_init(&my_eventq);
+ os_task_init(&my_task_str, "task", my_task, NULL, MY_TASK_PRIO,
+ OS_WAIT_FOREVER, my_task_stack, MY_TASK_STACK_SZ);
+
+```
+
+### Processing events
+
+Here event processing is done inside *my_task*. The main loop of the task is pulling events from the queue, and then taking action. We look at the type of the event to figure out what to do.
+
+The code snippet shows what the main loop of the event handler looks like. Events are removed from the head of the queue using os_eventq_get
+
+```c
+void
+my_task(void *arg)
+{
+ struct os_event *ev;
+
+ while (1) {
+ ev = os_eventq_get(&my_eventq);
+ switch (ev->ev_type) {
+ /* more event types here */
+ default:
+ assert(0);
+ }
+ }
+}
+```
+
+### Event types
+
+You can define your own event types. Some numbers are already reserved by the OS, so you should not use those as your own types.
+
+Reserved event types are defined in *libs/os/include/os/os_eventq.h*. One example of a reserved type is OS_EVENT_T_TIMER, which is used as type in OS callouts.
+
+You should start your event numbers from *OS_EVENT_T_PERUSER*, and go higher.
+
+You are going to generate events from GPIO interrupt handler, from another task as well as from a callout. OS callout already has a type, but you'll need to define types for the other uses.
+
+```c
+#define MY_TASK_GPIO_EVENT (OS_EVENT_T_PERUSER)
+#define MY_TASK_TASK_EVENT (OS_EVENT_T_PERUSER + 1)
+```
+
+### Posting events from another task
+
+Events are posted to a queue by calling *os_eventq_put()*. You need to preallocate memory for the event structure. Here it's done by declaring the event structure as a global variable.
+
+Note that you can call *os_eventq_put()* with an event which has already been queued. In that case, the call has no effect; the position of the event is not changed within the queue.
+
+In the code snippet we declare the os_event structure, and initialize it. We also create the event generating task, and periodically post event to the event queue.
+
+```c
+#define GEN_TASK_PRIO 3
+#define GEN_TASK_STACK_SZ 512
+
+static struct os_event gen_task_ev;
+static os_stack_t gen_task_stack[GEN_TASK_STACK_SZ];
+static struct os_task gen_task_str;
+
+void
+gen_task(void *arg)
+{
+ while (1) {
+ os_time_delay(OS_TICKS_PER_SEC / 4);
+ os_eventq_put(&my_eventq, &gen_task_ev);
+ }
+}
+
+void
+init_tasks(void)
+{
+ /* .... */
+ gen_task_ev.ev_type = MY_TASK_TASK_EVENT;
+ os_task_init(&gen_task_str, "gen_task", gen_task, NULL, GEN_TASK_PRIO,
+ OS_WAIT_FOREVER, gen_task_stack, GEN_TASK_STACK_SZ);
+}
+```
+
+### Callout events
+
+You can get timer events delivered to your task's event queue with OS callout. Check [callout documentation](../core_os/callout/callout.md) for description on how to use the API.
+
+For this example, you'll use only one type of callout, so you can use the simpler structure.
+
+In the code snippet we declare the os_callout structure and initialize it. Then we arm the timer.
+
+```c
+static struct os_callout my_callout;
+
+void
+init_tasks(void)
+{
+ /* .... */
+
+ os_callout_init(&my_callout, &my_eventq, NULL);
+ os_callout_reset(&my_callout, OS_TICKS_PER_SEC);
+}
+
+```
+
+### Posting events from interrupt handler
+
+Another place where posting events makes sense is from an interrupt handler. In this tutorial you will do it when GPIO changes state.
+
+You'll use HAL GPIO interface to register a routine which is getting called from interrupt handler context. This routine will then post event to your queue.
+
+On STM32F3Discovery board, there is a button connected to PA0. Identifier for this GPIO pin is 0.
+
+```c
+static struct os_event gpio_ev;
+
+void
+init_tasks(void)
+{
+ /* .... */
+
+ gpio_ev.ev_type = MY_TASK_GPIO_EVENT;
+ hal_gpio_irq_init(0, my_gpio_irq, NULL, GPIO_TRIG_RISING,
+ GPIO_PULL_NONE);
+ hal_gpio_irq_enable(0);
+}
+
+static void
+my_gpio_irq(void *arg)
+{
+ os_eventq_put(&my_eventq, &gpio_ev);
+}
+```
+
+
+### Event processing finalized
+
+Now that you are posting events from different sources, you will fill in the parts in the task main loop to behave differently depending on event type.
+
+You'll drive different LEDs depending on what type of event arrived. LEDs on this board are connected to PE8, PE9, PE10 and so on. These have GPIO identifiers starting from 72 onwards.
+
+```c
+#define TASK_LED 72
+#define CALLOUT_LED 73
+#define GPIO_LED 74
+
+void
+init_tasks(void)
+{
+ /* .... */
+ hal_gpio_init_out(TASK_LED, 1);
+ hal_gpio_init_out(CALLOUT_LED, 1);
+ hal_gpio_init_out(GPIO_LED, 1);
+}
+```
+
+And the the new main loop for your task. Note that when callout event arrives, we re-arm the callout.
+
+```c
+void
+my_task(void *arg)
+{
+ struct os_event *ev;
+
+ while (1) {
+ ev = os_eventq_get(&my_eventq);
+ switch (ev->ev_type) {
+ case MY_TASK_TASK_EVENT:
+ hal_gpio_toggle(TASK_LED);
+ break;
+ case OS_EVENT_T_TIMER:
+ hal_gpio_toggle(CALLOUT_LED);
+ os_callout_reset(&my_callout, OS_TICKS_PER_SEC / 2);
+ break;
+ case MY_TASK_GPIO_EVENT:
+ hal_gpio_toggle(GPIO_LED);
+ break;
+ default:
+ assert(0);
+ }
+ }
+}
+```
+
+Now you're done. Once you load this to your board, the task LED will blink at interval of 250ms, callout LED with interval of 500ms, and GPIO led every time you press the button.
+
+
+### Code for the example
+
+```c
+#include <os/os.h>
+#include <bsp/bsp.h>
+#include <hal/hal_gpio.h>
+#include <assert.h>
+
+
+#define MY_TASK_PRIO 4
+#define MY_TASK_STACK_SZ 512
+
+#define GEN_TASK_PRIO 3
+#define GEN_TASK_STACK_SZ 512
+
+#define MY_TASK_GPIO_EVENT (OS_EVENT_T_PERUSER)
+#define MY_TASK_TASK_EVENT (OS_EVENT_T_PERUSER + 1)
+
+#define TASK_LED 72
+#define CALLOUT_LED 73
+#define GPIO_LED 74
+
+static struct os_eventq my_eventq;
+static os_stack_t my_task_stack[MY_TASK_STACK_SZ];
+static struct os_task my_task_str;
+
+static struct os_event gen_task_ev;
+static os_stack_t gen_task_stack[GEN_TASK_STACK_SZ];
+static struct os_task gen_task_str;
+
+static struct os_callout my_callout;
+
+static struct os_event gpio_ev;
+
+void
+my_task(void *arg)
+{
+ struct os_event *ev;
+
+ while (1) {
+ ev = os_eventq_get(&my_eventq);
+ switch (ev->ev_type) {
+ case MY_TASK_TASK_EVENT:
+ hal_gpio_toggle(TASK_LED);
+ break;
+ case OS_EVENT_T_TIMER:
+ hal_gpio_toggle(CALLOUT_LED);
+ os_callout_reset(&my_callout, OS_TICKS_PER_SEC / 2);
+ break;
+ case MY_TASK_GPIO_EVENT:
+ hal_gpio_toggle(GPIO_LED);
+ break;
+ default:
+ assert(0);
+ }
+ }
+}
+
+static void
+my_gpio_irq(void *arg)
+{
+ os_eventq_put(&my_eventq, &gpio_ev);
+}
+
+void
+gen_task(void *arg)
+{
+ while (1) {
+ os_time_delay(OS_TICKS_PER_SEC / 4);
+ os_eventq_put(&my_eventq, &gen_task_ev);
+ }
+}
+
+void
+init_tasks(void)
+{
+ os_eventq_init(&my_eventq);
+ os_task_init(&my_task_str, "task", my_task, NULL, MY_TASK_PRIO,
+ OS_WAIT_FOREVER, my_task_stack, MY_TASK_STACK_SZ);
+
+ gen_task_ev.ev_type = MY_TASK_TASK_EVENT;
+ os_task_init(&gen_task_str, "gen_task", gen_task, NULL, GEN_TASK_PRIO,
+ OS_WAIT_FOREVER, gen_task_stack, GEN_TASK_STACK_SZ);
+
+ os_callout_init(&my_callout, &my_eventq, NULL);
+ os_callout_reset(&my_callout, OS_TICKS_PER_SEC);
+
+ gpio_ev.ev_type = MY_TASK_GPIO_EVENT;
+ hal_gpio_irq_init(0, my_gpio_irq, NULL, GPIO_TRIG_RISING,
+ GPIO_PULL_NONE);
+ hal_gpio_irq_enable(0);
+
+ hal_gpio_init_out(TASK_LED, 1);
+ hal_gpio_init_out(CALLOUT_LED, 1);
+ hal_gpio_init_out(GPIO_LED, 1);
+}
+
+int
+main(int argc, char **argv)
+{
+ os_init();
+
+ init_tasks();
+ os_start();
+ assert(0);
+ return 0;
+}
+
+```
[3/3] incubator-mynewt-site git commit: tutorial added for task using
event queue to manage events. This closes #60. also fixes newt install
instruction links mentioned in multiple pages.
Posted by ad...@apache.org.
tutorial added for task using event queue to manage events. This closes #60. also fixes newt install instruction links mentioned in multiple pages.
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/90421ab6
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/90421ab6
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/90421ab6
Branch: refs/heads/master
Commit: 90421ab6558858652ae2ac1d07b3459690a3f99b
Parents: 245f869
Author: aditihilbert <ad...@runtime.io>
Authored: Fri Mar 18 16:33:23 2016 -0700
Committer: aditihilbert <ad...@runtime.io>
Committed: Fri Mar 18 16:33:23 2016 -0700
----------------------------------------------------------------------
docs/newt/install/newt_linux.md | 135 +++++++++++++++++++++++++++++
docs/newt/install/newt_mac.md | 141 +++++++++++++++++++++++++++++++
docs/newt/tutorials/newt_mac.md | 124 ---------------------------
docs/os/get_started/get_started.md | 6 +-
docs/os/get_started/introduction.md | 17 +++-
docs/os/tutorials/event_queue.md | 78 +++++++++++------
mkdocs.yml | 7 +-
7 files changed, 347 insertions(+), 161 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/90421ab6/docs/newt/install/newt_linux.md
----------------------------------------------------------------------
diff --git a/docs/newt/install/newt_linux.md b/docs/newt/install/newt_linux.md
new file mode 100644
index 0000000..351763c
--- /dev/null
+++ b/docs/newt/install/newt_linux.md
@@ -0,0 +1,135 @@
+## Install newt tool on Linux
+
+<br>
+
+### Getting your Mac Ready
+
+If you want to build the *newt* tool from its source code, follow the following steps:
+
+#### 1. Install git, libcurl
+
+```
+ $ sudo apt-get install git
+ $ sudo apt-get install libcurl4-gnutls-dev
+```
+
+<br>
+
+#### 2. Install Go, the programming language
+
+* Go language enviroment dictates a directory structure. Known in Go parlanace as workspace, it must contain three sibling directories with the directory names src, pkg and bin, as explained below.
+
+ * src contains Go source files organized into packages (one package per directory),
+
+ * pkg contains package objects, and
+
+ * bin contains executable commands.
+
+ The GOPATH environment variable specifies the location of your workspace. To setup this workspace environment, create a 'dev' directory and then a 'go' directory under it. Set the GOPATH environment variable to this directory where you will soon clone the *newt* tool repository.
+
+```
+ $ cd $HOME
+ $ mkdir -p dev/go
+ $ cd dev/go
+ $ export GOPATH=`pwd`
+```
+ (Note that you need to add export statements to ~/.bash_profile to export variables permanently. Don't forget to source the file for the change to go into effect.)
+
+<br>
+
+```
+ $ vi ~/.bash_profile
+ $ source ~/.bash_profile
+```
+
+<br>
+
+* Next, install Go. When installed, Go offers you as a developer a language enviroment (to compile Go code), construct Go packages (to assemble Go packages) and import Go code (from github). In the next step, you will use the Go commands to import *newt* repo into your local Go environment.
+
+```no-highlight
+ $ sudo apt-get install golang
+```
+
+<br>
+
+#### 3. Create local repository
+
+* Use Go commands to copy the directory (currently the ASF incubator directory). Be patient as it may take a minute or two. Check the directories installed.
+
+```no-highlight
+ $ go get mynewt.apache.org/newt/...
+```
+
+<br>
+
+* Check that newt.go is in place.
+```no-highlight
+ $ ls $GOPATH/src/mynewt.apache.org/newt
+ DISCLAIMER NOTICE newt newtvm viper
+ LICENSE README.md newtmgr util yaml
+```
+
+<br>
+
+#### 4. Build the Newt tool
+
+* Use Go to run the newt.go program to build the *newt* tool. The command `go install` compiles and writes the resulting executable to an output file named `newt`, which is then installed, along with its dependencies, in $GOPATH/bin. If you get errors it is likely because of path resolution issues. Try `go build` followed by `go install` in that case.
+
+```no-highlight
+ $ cd $GOPATH/src/mynewt.apache.org/newt/newt
+ $ go install
+ $ ls "$GOPATH"/bin/
+ newt newtmgr newtvm
+```
+
+<br>
+
+* At this point, you can try using *newt*. For example, check for the version number by typing 'newt version'. See all the possible commands available to a user of newt by typing 'newt -h'.
+
+ (Note: If you are going to be modifying the *newt* often and going to be compile the program every time you call it, you will want to store the command in a variable in your .bash_profile. So type in `export newt="go run $GOPATH/mynewt.apache.org/newt/newt/newt.go"` in your .bash_profile and execute it by calling `$newt` at the prompt instead of `newt`. Essentially, `$newt` calls `go run` which runs the compiled binary directly without producing an executable. Don't forget to reload the updated bash profile by typing `source ~/.bash_profile` at the prompt! )
+
+```
+ $ newt version
+ Newt version: 1.0
+ $ newt -h
+ Newt allows you to create your own embedded project based on the Mynewt
+ operating system. Newt provides both build and package management in a
+ single tool, which allows you to compose an embedded workspace, and set
+ of projects, and then build the necessary artifacts from those projects.
+ For more information on the Mynewt operating system, please visit
+ https://www.github.com/mynewt/documentation.
+
+ Please use the newt help command, and specify the name of the command
+ you want help for, for help on how to use a specific command
+
+ Usage:
+ newt [flags]
+ newt [command]
+
+ Examples:
+ newt
+ newt help [<command-name>]
+ For help on <command-name>. If not specified, print this message.
+
+
+ Available Commands:
+ version Display the Newt version number.
+ target Set and view target information
+ egg Commands to list and inspect eggs on a nest
+ nest Commands to manage nests & clutches (remote egg repositories)
+ help Help about any command
+
+ Flags:
+ -h, --help=false: help for newt
+ -l, --loglevel="WARN": Log level, defaults to WARN.
+ -q, --quiet=false: Be quiet; only display error output.
+ -s, --silent=false: Be silent; don't output anything.
+ -v, --verbose=false: Enable verbose output when executing commands.
+
+
+ Use "newt help [command]" for more information about a command.
+```
+
+<br>
+
+
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/90421ab6/docs/newt/install/newt_mac.md
----------------------------------------------------------------------
diff --git a/docs/newt/install/newt_mac.md b/docs/newt/install/newt_mac.md
new file mode 100644
index 0000000..7163f3f
--- /dev/null
+++ b/docs/newt/install/newt_mac.md
@@ -0,0 +1,141 @@
+## Install newt tool on your Mac
+
+### Getting your Mac Ready
+
+If you want to build the *newt* tool from its source code, follow the following steps:
+
+<br>
+
+#### 1. Install Homebrew on your Mac OS X
+
+* Do you have Homebrew? If not, open a terminal on your Mac and paste the following at a Terminal prompt. It will ask you for your sudo password.
+
+```no-highlight
+ $ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
+```
+ Alternatively, you can just extract (or `git clone`) Homebrew and install it to `/usr/local`.
+
+<br>
+
+#### 2. Install Go, the programming language
+
+* Go language enviroment dictates a directory structure. Known in Go parlanace as workspace, it must contain three sibling directories with the directory names src, pkg and bin, as explained below.
+
+ * src contains Go source files organized into packages (one package per directory),
+
+ * pkg contains package objects, and
+
+ * bin contains executable commands.
+
+ The GOPATH environment variable specifies the location of your workspace. To setup this workspace environment, create a 'dev' directory and then a 'go' directory under it. Set the GOPATH environment variable to this directory where you will soon clone the *newt* tool repository.
+
+<br>
+
+```no-highlight
+ $ cd $HOME
+ $ mkdir -p dev/go
+ $ cd dev/go
+ $ export GOPATH=`pwd`
+```
+ (Note that you need to add export statements to ~/.bash_profile to export variables permanently. Don't forget to source the file for the change to go into effect.)
+
+<br>
+
+```no-highlight
+ $ vi ~/.bash_profile
+ $ source ~/.bash_profile
+```
+
+<br>
+
+* Next, using *brew*, install Go. When installed, Go offers you as a developer a language enviroment (to compile Go code), construct Go packages (to assemble Go packages) and import Go code (from github). In the next step, you will use the Go commands to import *newt* repo into your local Go environment.
+
+```no-highlight
+ $ brew install go
+ ==>
+ ...
+ ...
+ ==> *Summary*
+ 🍺 /usr/local/Cellar/go/1.5.1: 5330 files, 273M
+```
+ Alternatively, you can download the Go package directly from (https://golang.org/dl/) instead of brewing it. Install it in /usr/local directory.
+
+<br>
+
+#### 3. Create local repository
+
+* Use Go commands to copy the directory (currently the ASF incubator directory). Be patient as it may take a minute or two. Check the directories installed.
+
+```no-highlight
+ $ go get mynewt.apache.org/newt/...
+
+```
+
+* Check that newt.go is in place.
+```no-highlight
+ $ ls $GOPATH/src/mynewt.apache.org/newt
+ DISCLAIMER NOTICE newt newtvm viper
+ LICENSE README.md newtmgr util yaml
+```
+
+<br>
+
+#### 4. Build the Newt tool
+
+* Use Go to run the newt.go program to build the *newt* tool. The command `go install` compiles and writes the resulting executable to an output file named `newt`, which is then installed, along with its dependencies, in $GOPATH/bin.
+
+```no-highlight
+ $ cd $GOPATH/src/mynewt.apache.org/newt/newt
+ $ go install
+ $ ls "$GOPATH"/bin/
+ newt newtmgr newtvm
+```
+
+<br>
+
+* At this point, you can try using *newt*. For example, check for the version number by typing 'newt version'. See all the possible commands available to a user of newt by typing 'newt -h'.
+
+ (Note: If you are going to be modifying the *newt* often and going to be compile the program every time you call it, you will want to store the command in a variable in your .bash_profile. So type in `export newt="go run $GOPATH/mynewt.apache.org/newt/newt/newt.go"` in your .bash_profile and execute it by calling `$newt` at the prompt instead of `newt`. Essentially, `$newt` calls `go run` which runs the compiled binary directly without producing an executable. Don't forget to reload the updated bash profile by typing `source ~/.bash_profile` at the prompt! )
+
+```no-highlight
+ $ newt version
+ Newt version: 1.0
+ $ newt -h
+ Newt allows you to create your own embedded project based on the Mynewt
+ operating system. Newt provides both build and package management in a
+ single tool, which allows you to compose an embedded workspace, and set
+ of projects, and then build the necessary artifacts from those projects.
+ For more information on the Mynewt operating system, please visit
+ https://www.github.com/mynewt/documentation.
+
+ Please use the newt help command, and specify the name of the command
+ you want help for, for help on how to use a specific command
+
+ Usage:
+ newt [flags]
+ newt [command]
+
+ Examples:
+ newt
+ newt help [<command-name>]
+ For help on <command-name>. If not specified, print this message.
+
+
+ Available Commands:
+ version Display the Newt version number.
+ target Set and view target information
+ egg Commands to list and inspect eggs on a nest
+ nest Commands to manage nests & clutches (remote egg repositories)
+ help Help about any command
+
+ Flags:
+ -h, --help=false: help for newt
+ -l, --loglevel="WARN": Log level, defaults to WARN.
+ -q, --quiet=false: Be quiet; only display error output.
+ -s, --silent=false: Be silent; don't output anything.
+ -v, --verbose=false: Enable verbose output when executing commands.
+
+
+ Use "newt help [command]" for more information about a command.
+```
+
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/90421ab6/docs/newt/tutorials/newt_mac.md
----------------------------------------------------------------------
diff --git a/docs/newt/tutorials/newt_mac.md b/docs/newt/tutorials/newt_mac.md
deleted file mode 100644
index 5abf385..0000000
--- a/docs/newt/tutorials/newt_mac.md
+++ /dev/null
@@ -1,124 +0,0 @@
-## Building newt tool on your Mac
-
-### Getting your Mac Ready
-
-If you want to build the *newt* tool from its source code, follow the following steps:
-#### 1. Install Homebrew on your Mac OS X
-
-* Do you have Homebrew? If not, open a terminal on your Mac and paste the following at a Terminal prompt. It will ask you for your sudo password.
-
-```no-highlight
- $ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
-```
- Alternatively, you can just extract (or `git clone`) Homebrew and install it to `/usr/local`.
-
-#### 2. Install Go, the programming language
-
-* Go language enviroment dictates a directory structure. Known in Go parlanace as workspace, it must contain three sibling directories with the directory names src, pkg and bin, as explained below.
-
- * src contains Go source files organized into packages (one package per directory),
-
- * pkg contains package objects, and
-
- * bin contains executable commands.
-
- The GOPATH environment variable specifies the location of your workspace. To setup this workspace environment, create a 'dev' directory and then a 'go' directory under it. Set the GOPATH environment variable to this directory where you will soon clone the *newt* tool repository.
-
-```no-highlight
- $ cd $HOME
- $ mkdir -p dev/go
- $ cd dev/go
- $ export GOPATH=`pwd`
-```
- (Note that you need to add export statements to ~/.bash_profile to export variables permanently. Don't forget to source the file for the change to go into effect.)
-
-```no-highlight
- $ vi ~/.bash_profile
- $ source ~/.bash_profile
-```
-* Next, using *brew*, install Go. When installed, Go offers you as a developer a language enviroment (to compile Go code), construct Go packages (to assemble Go packages) and import Go code (from github). In the next step, you will use the Go commands to import *newt* repo into your local Go environment.
-
-```no-highlight
- $ brew install go
- ==>
- ...
- ...
- ==> *Summary*
- 🍺 /usr/local/Cellar/go/1.5.1: 5330 files, 273M
-```
- Alternatively, you can download the Go package directly from (https://golang.org/dl/) instead of brewing it. Install it in /usr/local directory.
-
-
-#### 3. Create local repository
-
-* Use Go commands to copy the directory (currently the ASF incubator directory). Be patient as it may take a minute or two. Check the directories installed.
-
-```no-highlight
- $ go get mynewt.apache.org/newt/...
-
-```
-
-* Check that newt.go is in place.
-```no-highlight
- $ ls $GOPATH/src/mynewt.apache.org/newt
- DISCLAIMER NOTICE newt newtvm viper
- LICENSE README.md newtmgr util yaml
-```
-
-#### 4. Build the Newt tool
-
-* Use Go to run the newt.go program to build the *newt* tool. The command `go install` compiles and writes the resulting executable to an output file named `newt`, which is then installed, along with its dependencies, in $GOPATH/bin.
-
-```no-highlight
- $ cd $GOPATH/src/mynewt.apache.org/newt/newt
- $ go install
- $ ls "$GOPATH"/bin/
- newt newtmgr newtvm
-```
-* At this point, you can try using *newt*. For example, check for the version number by typing 'newt version'. See all the possible commands available to a user of newt by typing 'newt -h'.
-
- (Note: If you are going to be modifying the *newt* often and going to be compile the program every time you call it, you will want to store the command in a variable in your .bash_profile. So type in `export newt="go run $GOPATH/mynewt.apache.org/newt/newt/newt.go"` in your .bash_profile and execute it by calling `$newt` at the prompt instead of `newt`. Essentially, `$newt` calls `go run` which runs the compiled binary directly without producing an executable. Don't forget to reload the updated bash profile by typing `source ~/.bash_profile` at the prompt! )
-
-```no-highlight
- $ newt version
- Newt version: 1.0
- $ newt -h
- Newt allows you to create your own embedded project based on the Mynewt
- operating system. Newt provides both build and package management in a
- single tool, which allows you to compose an embedded workspace, and set
- of projects, and then build the necessary artifacts from those projects.
- For more information on the Mynewt operating system, please visit
- https://www.github.com/mynewt/documentation.
-
- Please use the newt help command, and specify the name of the command
- you want help for, for help on how to use a specific command
-
- Usage:
- newt [flags]
- newt [command]
-
- Examples:
- newt
- newt help [<command-name>]
- For help on <command-name>. If not specified, print this message.
-
-
- Available Commands:
- version Display the Newt version number.
- target Set and view target information
- egg Commands to list and inspect eggs on a nest
- nest Commands to manage nests & clutches (remote egg repositories)
- help Help about any command
-
- Flags:
- -h, --help=false: help for newt
- -l, --loglevel="WARN": Log level, defaults to WARN.
- -q, --quiet=false: Be quiet; only display error output.
- -s, --silent=false: Be silent; don't output anything.
- -v, --verbose=false: Enable verbose output when executing commands.
-
-
- Use "newt help [command]" for more information about a command.
-```
-* Without creating a project repository, you can't do a whole lot with the *newt tool. So you'll have to wait till you have downloaded an app to try out the tool.
-
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/90421ab6/docs/os/get_started/get_started.md
----------------------------------------------------------------------
diff --git a/docs/os/get_started/get_started.md b/docs/os/get_started/get_started.md
index 0f45918..0e4401e 100644
--- a/docs/os/get_started/get_started.md
+++ b/docs/os/get_started/get_started.md
@@ -2,9 +2,9 @@
If you are curious about Mynewt and want to get a quick feel for the project, you've come to the right place. We have three sets of instructions for you to try out.
-* [Installing Native Tools](native_tools.md) - to run Mynewt OS natively (on your machine)
-* [Creating Your First Project](project_create.md) - on simulated hardware
-* [Installing Cross Tools for ARM](cross_tools.md) - to get prepared to play with hardware
+* [Install Native Tools](native_tools.md) - to run Mynewt OS natively (on your machine)
+* [Create Your First Project](project_create.md) - on simulated hardware
+* [Install Cross Tools for ARM](cross_tools.md) - to get prepared to play with hardware
**Send us an email on the dev@ mailing list if you have comments or suggestions!** If you haven't joined the mailing list, you will find the links [here](../../community.md).
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/90421ab6/docs/os/get_started/introduction.md
----------------------------------------------------------------------
diff --git a/docs/os/get_started/introduction.md b/docs/os/get_started/introduction.md
index 2b3ac9c..a617ecc 100644
--- a/docs/os/get_started/introduction.md
+++ b/docs/os/get_started/introduction.md
@@ -43,12 +43,16 @@ Controller implementations.
peripheral functions, allowing developers to easily write cross-platform
code.
+<br>
+
### Newt ###
In order to provide all this functionality, and operate in an
extremely low resource environment, Mynewt provides a very fine-grained source
package management and build system tool, called *newt*.
-You can install and build *newt* for [Linux](http://mynewt.apache.org/newt/newt_linux/) or [Mac](http://mynewt.apache.org/newt/newt_mac/).
+You can install and build *newt* for [Linux](../../newt/install/newt_linux.md) or [Mac](../../newt/install/newt_mac.md).
+
+<br>
### Build your first Mynewt App with Newt ###
@@ -62,6 +66,8 @@ Installing skeleton in my_app...
Project my_app successfully created.
```
+<br>
+
Newt populates this new project with a base skeleton of a new Apache Mynewt
project. It has the following structure:
@@ -100,8 +106,7 @@ apache-mynewt-core
$
```
-*NOTE:* ```apache-mynewt-core``` may take a while to download, to see progress, use
-the ```-v``` (verbose) option to install.
+**NOTE:** ```apache-mynewt-core``` may take a while to download, to see progress, use the ```-v``` (verbose) option to install.
Once ```newt install``` has successfully finished, the contents of ```apache-mynewt-core```
@@ -141,6 +146,8 @@ $ tree -L2
<snip>
```
+<br>
+
As you can see, the core of the Apache Mynewt operating system has been brought
into your local directory!
@@ -172,6 +179,8 @@ $ newt run my_blinky_sim
(runs target my_blinky_sim on the simulator)
```
+<br>
+
At this point you have your first Mynewt application!
Apache Mynewt has a lot more functionality than just running simulated applications. It provides all
@@ -179,7 +188,7 @@ the features you'll need to cross-compile your application, run it on real hardw
full featured application.
If you're interested in learning more, a good next step is to choose a project to
-[Get Started](http://mynewt.apache.org/os/get_started/project1/) with, and begin to familiarize
+[get started](get_started.md) with, and begin to familiarize
yourself with operating within the newt environment. These projects will get your toolchain installed,
and get you blinking an LED with the Apache Mynewt OS.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/90421ab6/docs/os/tutorials/event_queue.md
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/event_queue.md b/docs/os/tutorials/event_queue.md
index f135279..2c3406f 100644
--- a/docs/os/tutorials/event_queue.md
+++ b/docs/os/tutorials/event_queue.md
@@ -1,25 +1,30 @@
-# How to define a task which uses event queues to manage multiple events
+## How to define a task which uses event queues to manage multiple events
-## Introduction
+### Introduction
Event queue is a mechanism by which you can serialize incoming events for your task. You can use it to get info about arrived hardware interrupts, callout expirations and messages from other tasks.
-Benefit of doing inter-task communication this way is that there should be less resources that need to be locked.
+The benefit of doing inter-task communication this way is that there should be less resources that need to be locked.
-Benefit of doing interrupt processing in a task context instead of inside interrupt context is that you are not blocking other HW interrupts when doing the work. The same goes for high priority tasks in the system; they're blocked until the interrupt handler returns. From task context you'll also be able to access other OS facilities; you can sleep while waiting for a lock, for example.
+The benefit of doing interrupt processing in a task context instead of inside an interrupt context is that you are not blocking other HW interrupts when doing the work. The same goes for high priority tasks in the system; they're blocked until the interrupt handler returns. From the task context you'll also be able to access other OS facilities; you can sleep while waiting for a lock, for example.
-## Example app
+<br>
-Here I'm going to write an app which demonstrates the use of event queues for communication between tasks. I'll also use OS callouts for timer expiration, and another event from a GPIO interrupt.
+### Example app
-I use inputs from these 3 sources to toggle 3 GPIO outputs on my STM32F3discovery board.
+Here you are going to write an app which demonstrates the use of event queues for communication between tasks. You will also use OS callouts for timer expiration and another event from a GPIO interrupt.
-### Create project
+You will use inputs from 3 sources to toggle 3 GPIO outputs on my STM32F3discovery board.
-I start by creating a project, and populating it with repositories incubator-mynewt-core and mynewt_stm32f3. See [STM32F3 tutorial](STM32F303.md) if you need help with this.
+<br>
+#### Create project
-### Create application
+You start by creating a project and populating it with repositories incubator-mynewt-core and mynewt_stm32f3. See [STM32F3 tutorial](STM32F303.md) if you need help with this. You can also read the tutorial on [Additional Repositories](add_repos.md) for a more thorough understanding.
+
+<br>
+
+#### Create application
Here's what the pkg.yml looks for the application.
@@ -34,14 +39,16 @@ pkg.deps:
- "@apache-mynewt-core/libs/console/stub"
```
-### Initialize the event queue structure
+<br>
+
+#### Initialize the event queue structure
This must be done before anyone tries to place events to the queue. Here it's done before any task gets created. Initialization is done by calling *os_eventq_init()*.
```c
#define MY_TASK_PRIO 4
#define MY_TASK_STACK_SZ 512
-
+
static struct os_eventq my_eventq;
static os_stack_t my_task_stack[MY_TASK_STACK_SZ];
static struct os_task my_task_str;
@@ -57,7 +64,9 @@ init_tasks(void)
```
-### Processing events
+<br>
+
+#### Processing events
Here event processing is done inside *my_task*. The main loop of the task is pulling events from the queue, and then taking action. We look at the type of the event to figure out what to do.
@@ -80,7 +89,9 @@ my_task(void *arg)
}
```
-### Event types
+<br>
+
+#### Event types
You can define your own event types. Some numbers are already reserved by the OS, so you should not use those as your own types.
@@ -95,7 +106,9 @@ You are going to generate events from GPIO interrupt handler, from another task
#define MY_TASK_TASK_EVENT (OS_EVENT_T_PERUSER + 1)
```
-### Posting events from another task
+<br>
+
+#### Posting events from another task
Events are posted to a queue by calling *os_eventq_put()*. You need to preallocate memory for the event structure. Here it's done by declaring the event structure as a global variable.
@@ -106,11 +119,11 @@ In the code snippet we declare the os_event structure, and initialize it. We als
```c
#define GEN_TASK_PRIO 3
#define GEN_TASK_STACK_SZ 512
-
+
static struct os_event gen_task_ev;
static os_stack_t gen_task_stack[GEN_TASK_STACK_SZ];
static struct os_task gen_task_str;
-
+
void
gen_task(void *arg)
{
@@ -119,7 +132,7 @@ gen_task(void *arg)
os_eventq_put(&my_eventq, &gen_task_ev);
}
}
-
+
void
init_tasks(void)
{
@@ -130,11 +143,13 @@ init_tasks(void)
}
```
-### Callout events
+<br>
+
+#### Callout events
You can get timer events delivered to your task's event queue with OS callout. Check [callout documentation](../core_os/callout/callout.md) for description on how to use the API.
-For this example, you'll use only one type of callout, so you can use the simpler structure.
+For this example, you'll use only one type of callout; so you can use the simpler structure.
In the code snippet we declare the os_callout structure and initialize it. Then we arm the timer.
@@ -152,13 +167,16 @@ init_tasks(void)
```
-### Posting events from interrupt handler
+<br>
+
+
+#### Posting events from interrupt handler
Another place where posting events makes sense is from an interrupt handler. In this tutorial you will do it when GPIO changes state.
-You'll use HAL GPIO interface to register a routine which is getting called from interrupt handler context. This routine will then post event to your queue.
+You'll use HAL GPIO interface to register a routine which is getting called from the interrupt handler context. This routine will then post event to your queue.
-On STM32F3Discovery board, there is a button connected to PA0. Identifier for this GPIO pin is 0.
+On STM32F3Discovery board, there is a button connected to PA0. The identifier for this GPIO pin is 0.
```c
static struct os_event gpio_ev;
@@ -181,10 +199,11 @@ my_gpio_irq(void *arg)
}
```
+<br>
-### Event processing finalized
+#### Event processing finalized
-Now that you are posting events from different sources, you will fill in the parts in the task main loop to behave differently depending on event type.
+Now that you are posting events from different sources, you will fill in the parts in the task main loop to trigger different behaviors depending on event type.
You'll drive different LEDs depending on what type of event arrived. LEDs on this board are connected to PE8, PE9, PE10 and so on. These have GPIO identifiers starting from 72 onwards.
@@ -203,14 +222,14 @@ init_tasks(void)
}
```
-And the the new main loop for your task. Note that when callout event arrives, we re-arm the callout.
+And here is the new main loop for your task. Note that when callout event arrives, we re-arm the callout.
```c
void
my_task(void *arg)
{
struct os_event *ev;
-
+
while (1) {
ev = os_eventq_get(&my_eventq);
switch (ev->ev_type) {
@@ -231,8 +250,11 @@ my_task(void *arg)
}
```
-Now you're done. Once you load this to your board, the task LED will blink at interval of 250ms, callout LED with interval of 500ms, and GPIO led every time you press the button.
+<br>
+
+Now you're done. Once you load this to your board, the task LED will blink at an interval of 250ms, the callout LED with an interval of 500ms, and the GPIO LED every time you press the button.
+<br>
### Code for the example
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/90421ab6/mkdocs.yml
----------------------------------------------------------------------
diff --git a/mkdocs.yml b/mkdocs.yml
index 6479529..5b398ff 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -29,6 +29,7 @@ pages:
- 'Air-quality Sensor project': 'os/tutorials/air_quality_sensor.md'
- 'Edit Docs': 'os/tutorials/how_to_edit_docs.md'
- 'Additional Repositories': 'os/tutorials/add_repos.md'
+ - 'A task that manages multiple events': 'os/tutorials/event_queue.md'
- OS User Guide:
- toc: 'os/os_user_guide.md'
- OS Core:
@@ -294,8 +295,10 @@ pages:
- toc: 'network/ble/ble_intro.md'
- Newt Tool Manual:
- Introduction: 'newt/newt_intro.md'
+ - Install:
+ - 'Install Newt on Mac': 'newt/install/newt_mac.md'
+ - 'Install Newt on Linux': 'newt/install/newt_linux.md'
- Tutorials:
- - 'Install Newt on Mac': 'newt/tutorials/newt_mac.md'
- 'Define a target': 'newt/tutorials/define_target.md'
- Manual:
- 'Command structure': 'newt/newt_ops.md'
@@ -308,7 +311,7 @@ pages:
- 'newt version': 'newt/command_list/newt_version.md'
- Newt Manager Manual:
- 'Introduction': 'newtmgr/overview.md'
- - 'Installing': 'newtmgr/installing.md'
+ - 'Install': 'newtmgr/installing.md'
- Tutorials:
- 'Sim Slinky': 'newtmgr/project-slinky.md'
- 'Target Slinky': 'newtmgr/project-target-slinky.md'
[2/3] incubator-mynewt-site git commit: Merge branch 'event_q' of
https://github.com/mkiiskila/incubator-mynewt-site
Posted by ad...@apache.org.
Merge branch 'event_q' of https://github.com/mkiiskila/incubator-mynewt-site
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/245f869e
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/245f869e
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/245f869e
Branch: refs/heads/master
Commit: 245f869e1a876f6bff972a8dccf68b0211b04151
Parents: 4f897dd bc8e257
Author: aditihilbert <ad...@runtime.io>
Authored: Fri Mar 18 13:51:57 2016 -0700
Committer: aditihilbert <ad...@runtime.io>
Committed: Fri Mar 18 13:51:57 2016 -0700
----------------------------------------------------------------------
docs/os/tutorials/event_queue.md | 345 ++++++++++++++++++++++++++++++++++
1 file changed, 345 insertions(+)
----------------------------------------------------------------------