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/11/18 01:21:53 UTC
[1/8] incubator-mynewt-site git commit: Updated Repos tutorial
Repository: incubator-mynewt-site
Updated Branches:
refs/heads/develop 38b20a681 -> 7dd4891e7
Updated Repos 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/b1afc81a
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/b1afc81a
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/b1afc81a
Branch: refs/heads/develop
Commit: b1afc81a077f8ab40b9437aea562e87fade0677d
Parents: ed14270
Author: David G. Simmons <sa...@mac.com>
Authored: Mon Nov 14 13:35:44 2016 -0500
Committer: David G. Simmons <sa...@mac.com>
Committed: Mon Nov 14 13:35:44 2016 -0500
----------------------------------------------------------------------
docs/index.md | 5 +++-
docs/os/tutorials/repo/add_repos.md | 14 +++++++---
docs/os/tutorials/repo/create_repo.md | 40 ++++++++++++++++++++---------
docs/os/tutorials/repo/upgrade_repo.md | 4 +++
mkdocs.yml | 3 +--
5 files changed, 47 insertions(+), 19 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/b1afc81a/docs/index.md
----------------------------------------------------------------------
diff --git a/docs/index.md b/docs/index.md
index bc1906c..0c9732e 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1 +1,4 @@
-Apache Mynewt is a real-time, modular operating system for connected IoT devices that need to operate for long periods of time under power, memory, and storage constraints. The first connectivity stack offered is BLE 4.2.
+Apache Mynewt is a real-time, modular operating system for
+connected IoT devices that need to operate for long periods
+of time under power, memory, and storage constraints. The
+first connectivity stack offered is BLE 4.2.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/b1afc81a/docs/os/tutorials/repo/add_repos.md
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/repo/add_repos.md b/docs/os/tutorials/repo/add_repos.md
index 22098fa..e280c8e 100644
--- a/docs/os/tutorials/repo/add_repos.md
+++ b/docs/os/tutorials/repo/add_repos.md
@@ -105,7 +105,7 @@ after `github.com` in the repo path. Consider the repository
* **repo** -- The name of the repo. On github, this is the name after
the username described above. Consider the repository
-`https://github.com/apache/incubator-mynewt-core`. It has username
+`https://github.com/apache/incubator-mynewt-core`. It has path
`incubator-mynewt-core`. This is a path to the source control
and should not be confused with the name of the repo that you used in the
`repository.<name>` declaration above. That name is contained elsewhere
@@ -182,9 +182,15 @@ Here is the `repository.yml` file from the apache-Mynewt-core:
```no-highlight
repo.name: apache-mynewt-core
repo.versions:
- "0.7.9": "Mynewt_0_8_0_b2_tag"
- "0-latest": "0.7.9"
- "0.8-latest": "0.7.9"
+ "0.0.0": "develop"
+ "0.7.9": "mynewt_0_8_0_b2_tag"
+ "0.8.0": "mynewt_0_8_0_tag"
+ "0.9.0": "mynewt_0_9_0_tag"
+ "0.9.1": "master"
+ "0-latest": "0.9.0"
+ "0-dev": "0.9.1"
+ "0.8-latest": "0.8.0"
+ "0.9-latest": "0.9.0"
```
<br>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/b1afc81a/docs/os/tutorials/repo/create_repo.md
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/repo/create_repo.md b/docs/os/tutorials/repo/create_repo.md
index 1e1927e..63ade07 100644
--- a/docs/os/tutorials/repo/create_repo.md
+++ b/docs/os/tutorials/repo/create_repo.md
@@ -1,10 +1,19 @@
## Create a Repo out of a Project
-In order to create a repository out of a project, all you need to do is create a `repository.yml` file, and check it into the master branch of your project.
+In order to create a repository out of a project, all you need to do is create a
+`repository.yml` file, and check it into the master branch of your project.
-**NOTE:** Currently only github source control service is supported by our package management system, but support for plain git will be added soon.
+**NOTE:** Currently only github source control service is supported by our
+package management system, but support for plain git is planned for a future
+version.
-The repository.yml defines all versions of the repository and the corresponding source control tags that these versions correspond to. As an example, if the repository.yml file has the following content, it means there is one version of the apache-mynewt-core operating system available, which is `0.0.0` (implying we haven't released yet!). Such a version number corresponds to the "develop" branch in this repository. `0-latest` would also resolved to this same `0.0.0` version. The next section explains the versioning system a bit more.
+The `repository.yml` defines all versions of the repository and the corresponding
+source control tags that these versions correspond to. As an example, if the
+`repository.yml` file has the following content, it means there is one version
+of the apache-mynewt-core operating system available, which is `0.0.0` (implying we
+haven't released yet!). Such a version number corresponds to the "develop" branch
+in this repository. `0-latest` would also resolved to this same `0.0.0` version.
+The next section explains the versioning system a bit more.
```
$ more repository.yml
@@ -39,7 +48,8 @@ repo.versions:
It contains the following:
* **repo.name** The external name that is used to include the library in
-your `project.yml` file. This is the name you in include in the `project.repositories` variable when adding this repository to your project.
+your `project.yml` file. This is the name you in include in the `project.repositories`
+variable when adding this repository to your project.
* **repo.versions** A description of what versions to give the user depending
on the settings in their `project.yml` file. See below for a thorough description
on versioning. Its a flexible mapping between version numbers and git branches.
@@ -70,9 +80,9 @@ or
The stability string can be one of 3 pre-defined stability values.
-1. stable -- A stable release version of the repository
-2. dev -- A development version from the repository
-3. latest -- The latest from the repository
+1. `stable` -- A stable release version of the repository
+2. `dev` -- A development version from the repository
+3. `latest` -- The latest from the repository
In your `project.yml` file you can specify different combinations of
the version number and stability value. For example:
@@ -95,7 +105,9 @@ You **cannot** specify a stability string with a fully numbered version, e.g.
A `repository.yml` file contains information to match this version request
into a git branch to fetch for your project.
-It's up to you as the repository maintainer to map these to actual github branches of the repository. For example, let's say in a fictitious repository the following are defined.
+It's up to you as the repository maintainer to map these to actual github branches
+of the repository. For example, let's say in a fictitious repository the
+following are defined.
```no-highlight
repo.versions:
@@ -115,7 +127,8 @@ repo.versions:
```
When the `project.yml` file asks for `1.2-stable` it will be resolved to version
-`1.2.0` which in turn will resolve to a specific branch `xxx_branch_1_2_0`. This is the branch that `newt` will fetch into the project with that `project.yml` file.
+`1.2.0` which in turn will resolve to a specific branch `xxx_branch_1_2_0`.
+This is the branch that `newt` will then fetch into the project with that `project.yml` file.
<br>
@@ -140,13 +153,16 @@ develop.repositories:
This would tell Newt that for anything that resolves to the develop
branch, this repository requires the sterlys-little-repo repository.
-Dependencies are resolved circularly by the newt tool, and every dependent repository is placed as a sibling in the repos directory. Currently, if two repositories have the same name, they will conflict and bad things will happen.
+Dependencies are resolved circularly by the newt tool, and every
+dependent repository is placed as a sibling in the repos directory.
+Currently, if two repositories have the same name, they will conflict
+and bad things will happen.
When a repository is installed to the repos/ directory, the current
-version of that repository is written to the "project.state" file. The
+version of that repository is written to the `project.state` file. The
project state file contains the currently installed version of any given
repository. This way, the current set of repositories can be recreated
-from the project.state file reliably, whereas the project.yml file can
+from the `project.state` file reliably, whereas the `project.yml` file can
have higher level directives (i.e. include 0.8-stable.)
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/b1afc81a/docs/os/tutorials/repo/upgrade_repo.md
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/repo/upgrade_repo.md b/docs/os/tutorials/repo/upgrade_repo.md
index c44fab8..475535a 100644
--- a/docs/os/tutorials/repo/upgrade_repo.md
+++ b/docs/os/tutorials/repo/upgrade_repo.md
@@ -12,3 +12,7 @@ Newt upgrade will look at the current desired version in `project.yml`,
and compare it to the version in `project.state`. If these two differ, it
will upgrade the dependency. Upgrade works not just for the dependency
in `project.yml`, but for all the sub-dependencies that they might have.
+
+If you have changed any settings in the `project.yml` file, you should run
+`newt upgrade` to ensure that your repos are all up to date with the versions
+specified in your `project.yml` file.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/b1afc81a/mkdocs.yml
----------------------------------------------------------------------
diff --git a/mkdocs.yml b/mkdocs.yml
index f39ac4c..02bca04 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -37,8 +37,7 @@ pages:
- toc: 'os/tutorials/repo/add_repos.md'
- 'Upgrade a repo': 'os/tutorials/repo/upgrade_repo.md'
- 'Turn project into a repo': 'os/tutorials/repo/create_repo.md'
- - 'A Sample Lesson':
- - 'Lesson Unit on Tasks and Priority Management': 'os/tutorials/tasks_lesson.md'
+ - 'Tasks and Priority Management': 'os/tutorials/tasks_lesson.md'
- 'Enable Wi-Fi on Arduino Zero': 'os/tutorials/wi-fi_on_arduino.md'
- 'Write a Test Suite for a Package': 'os/tutorials/unit_test.md'
- 'Air-quality Sensor project': 'os/tutorials/air_quality_sensor.md'
[8/8] incubator-mynewt-site git commit: Updated events in mkdocs.yml.
This closes #126.
Posted by ad...@apache.org.
Updated events in mkdocs.yml. This closes #126.
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/7dd4891e
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/7dd4891e
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/7dd4891e
Branch: refs/heads/develop
Commit: 7dd4891e715079c4377293224c9858e0dbd95c9f
Parents: 2f8ea17
Author: aditihilbert <ad...@runtime.io>
Authored: Thu Nov 17 17:06:16 2016 -0800
Committer: aditihilbert <ad...@runtime.io>
Committed: Thu Nov 17 17:06:40 2016 -0800
----------------------------------------------------------------------
mkdocs.yml | 16 ++++++++--------
1 file changed, 8 insertions(+), 8 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/7dd4891e/mkdocs.yml
----------------------------------------------------------------------
diff --git a/mkdocs.yml b/mkdocs.yml
index 5ead976..db4ffc3 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -522,15 +522,15 @@ extra:
Chapter 6 - Packaging it: 'Packages for distribution delineates the process of creating complete packages to load on your embedded device to get it up, connected, and ready for remote management.'
events:
event 1:
- title: 'ARM TechCon'
- description: 'See Apache Mynewt in action in Booth #805. Watch it enable a variety of functionalities on different boards!'
- location: "Santa Clara Convention Center, Santa Clara, CA, USA"
- date: '25-27 October, 2016'
+ title: 'Embedded Systems Conference'
+ description: 'Meet up to discuss Apache Mynewt.'
+ location: "San Jose Convention Center, San Jose, CA, USA"
+ date: '6-8 December, 2016'
event 2:
- title: 'Linaro Connect - Keynote Presentation'
- description: 'LAS16-104: Mynewt Technical Overview. Apache Mynewt developers will be available until September 28th to meet and discuss Mynewt OS and associated Newt tool.'
- location: "Grand Ballroom C, JW Marriott Resort and Spa Hotel, Las Vegas, NV"
- date: 'Time: 16:10 - 16:45, Date: 26 September 2016, 2016'
+ title: 'CES'
+ description: 'Contact runtime.io or email us at dev@mynewt.incubator.apache.org to check out and discuss Apache Mynewt and its many uses.'
+ location: "Las Vegas, NV"
+ date: '5-8 January, 2017'
copyright: 'Copyright © 2015 The Apache Software Foundation, Licensed under the Apache License, Version 2.0 Apache and the Apache feather logo are trademarks of The Apache Software Foundation.'
[7/8] incubator-mynewt-site git commit: Edits to event_queue and
related descriptions
Posted by ad...@apache.org.
Edits to event_queue and related descriptions
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/2f8ea17b
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/2f8ea17b
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/2f8ea17b
Branch: refs/heads/develop
Commit: 2f8ea17b1fcf1a41b0ff75115d0e86d829234965
Parents: 306590a
Author: aditihilbert <ad...@runtime.io>
Authored: Thu Nov 17 16:36:38 2016 -0800
Committer: aditihilbert <ad...@runtime.io>
Committed: Thu Nov 17 16:36:38 2016 -0800
----------------------------------------------------------------------
docs/os/core_os/event_queue/event_queue.md | 27 +++++---------------
.../core_os/event_queue/os_eventq_dflt_set.md | 2 +-
docs/os/core_os/event_queue/os_eventq_inited.md | 2 +-
docs/os/tutorials/repo/create_repo.md | 2 +-
docs/os/tutorials/tasks_lesson.md | 4 +--
5 files changed, 12 insertions(+), 25 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/2f8ea17b/docs/os/core_os/event_queue/event_queue.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/event_queue/event_queue.md b/docs/os/core_os/event_queue/event_queue.md
index 9ff8800..f4ec8e5 100644
--- a/docs/os/core_os/event_queue/event_queue.md
+++ b/docs/os/core_os/event_queue/event_queue.md
@@ -1,13 +1,11 @@
# Event Queues
-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`.
+Event queue is a way for a task to serialize events sent to it. This makes it easy to process events required to happen inside the task's context. Events may arrive either from an interrupt handler, or from another task.
### Description
-Events are in form the of a data structure `struct os_event` and
+Events arrive in form the of a data structure `struct os_event` and
they are queued to another data structure `struct os_eventq`.
The Event Queue must be initialized before trying to add events to
@@ -15,15 +13,8 @@ it. This is done using `os_eventq_init()`.
A 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. This
-method of event handling requires that the task handler itself would dispatch the
-events based on the event's type.
-
-Mynewt has moved the event dispatching logic out of the task handler and instead the
-logic is built in to each event via a callback function pointer. The task handler no longer
-needs to dispatch events based on their types but instead can simply pull events
-off the queue and call it's callback handler.
+to wake it up. Once an event has been queued, the task waiting on that queue is woken up. The event dispatching logic is built into each event via a callback function pointer. The task handler can simply pull events
+off the queue and call its callback handler. The processing task would then act according to the event type.
When `os_event` is queued, it should not be freed until processing task is done with it.
@@ -51,12 +42,8 @@ struct os_event {
| `ev_arg` | Can be used further as input to task processing this event |
| `ev_next` | Linkage attaching this event to an event queue |
-With the addition of a callback function pointer, the dispatch logic
-is moved out of the task handler and gets built into each event. A
-task handler now just pulls an event off its queue and blindly calls
-its callback function. A helper function was added to do just this:
-`os_eventq_run()`. As an example, the task handler
-for the bleprph application is below:
+With the callback function pointer, the dispatch logic gets built into each event. The task handler simply pulls an event off its queue and blindly calls its callback function. A helper function was added to do just this:
+`os_eventq_run()`. As an example, the task handler for the bleprph application is below:
```c
static void
@@ -70,7 +57,7 @@ bleprph_task_handler(void *unused)
The callback associated with an event is specified when the event gets
initialized. For example, here are some statically-initialized events
-in the nimble host:
+in the NimBLE host:
```c
static void ble_hs_event_tx_notify(struct os_event *ev);
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/2f8ea17b/docs/os/core_os/event_queue/os_eventq_dflt_set.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/event_queue/os_eventq_dflt_set.md b/docs/os/core_os/event_queue/os_eventq_dflt_set.md
index 7d411d0..05592a1 100644
--- a/docs/os/core_os/event_queue/os_eventq_dflt_set.md
+++ b/docs/os/core_os/event_queue/os_eventq_dflt_set.md
@@ -5,7 +5,7 @@
os_eventq_dflt_set(struct os_eventq *evq)
```
-Sets `struct os_eventq`, as te default event queue
+Sets `struct os_eventq` as the default event queue
#### Arguments
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/2f8ea17b/docs/os/core_os/event_queue/os_eventq_inited.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/event_queue/os_eventq_inited.md b/docs/os/core_os/event_queue/os_eventq_inited.md
index 5f81071..0d0511a 100644
--- a/docs/os/core_os/event_queue/os_eventq_inited.md
+++ b/docs/os/core_os/event_queue/os_eventq_inited.md
@@ -5,7 +5,7 @@
os_eventq_inited(const struct os_eventq *evq)
```
-Check if event queue `const struct os_eventq`, is it ready for use.
+Check if event queue `const struct os_eventq` is ready for use.
#### Arguments
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/2f8ea17b/docs/os/tutorials/repo/create_repo.md
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/repo/create_repo.md b/docs/os/tutorials/repo/create_repo.md
index 63ade07..21ec9c5 100644
--- a/docs/os/tutorials/repo/create_repo.md
+++ b/docs/os/tutorials/repo/create_repo.md
@@ -48,7 +48,7 @@ repo.versions:
It contains the following:
* **repo.name** The external name that is used to include the library in
-your `project.yml` file. This is the name you in include in the `project.repositories`
+your `project.yml` file. This is the name you include in the `project.repositories`
variable when adding this repository to your project.
* **repo.versions** A description of what versions to give the user depending
on the settings in their `project.yml` file. See below for a thorough description
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/2f8ea17b/docs/os/tutorials/tasks_lesson.md
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/tasks_lesson.md b/docs/os/tutorials/tasks_lesson.md
index 70801ed..b3a21de 100644
--- a/docs/os/tutorials/tasks_lesson.md
+++ b/docs/os/tutorials/tasks_lesson.md
@@ -22,7 +22,7 @@ You will need the following equipment:
##Build Your Application
To save time, we will simply modify the Blinky app. We'll add the Task Management code to
-the Blinky App. Follow the [*Arduino Zero Blinky tutorial*](http://mynewt.apache.org/os/tutorials/arduino_zero/)
+the Blinky app. Follow the [*Arduino Zero Blinky tutorial*](http://mynewt.apache.org/os/tutorials/arduino_zero/)
to create a new project and build your bootloader and application. Finally, build and
load the application to your Arduino to verify that everything is in order. Now let\u2019s get started!
@@ -412,4 +412,4 @@ your application. In the end, the way you manage your tasks depends on the conte
application. You should assign priorities based on execution time, urgency, and frequency, among
other things.
-Keep blinking and happy hacking!
\ No newline at end of file
+Keep blinking and happy hacking!
[3/8] incubator-mynewt-site git commit: Updated roadmap features in
about.md
Posted by ad...@apache.org.
Updated roadmap features in about.md
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/092e763a
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/092e763a
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/092e763a
Branch: refs/heads/develop
Commit: 092e763aabc7ac042f5659ff2a127c3d904d87e4
Parents: 54755cb
Author: aditihilbert <ad...@runtime.io>
Authored: Tue Nov 15 11:20:05 2016 -0800
Committer: aditihilbert <ad...@runtime.io>
Committed: Tue Nov 15 11:20:05 2016 -0800
----------------------------------------------------------------------
docs/about.md | 12 +++++-------
1 file changed, 5 insertions(+), 7 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/092e763a/docs/about.md
----------------------------------------------------------------------
diff --git a/docs/about.md b/docs/about.md
index 5ba9e00..db59904 100644
--- a/docs/about.md
+++ b/docs/about.md
@@ -2,13 +2,11 @@
Some upcoming features:
-* Host-only BLE stack
-* Serial upgrade of image in bootloader
-* HAL redesign to abstract across a diverse set of chip peripherals ([View discussion thread](http://mail-archives.apache.org/mod_mbox/incubator-mynewt-dev/201606.mbox/%3C06CB0682-8F67-4C3F-93E4-6A20444487A1%40apache.org%3E))
-* HAL for SPI access (master and slave)
-* Ability for drivers to turn on/off low power settings automatically
-* Support for Wi-Fi controllers via a socket interface
-
+* Full IP support
+* Low power support with ability for drivers to turn on/off low power settings automatically
+* Sensor API, see [discussion thread](https://lists.apache.org/list.html?dev@mynewt.apache.org:dfr=June%201|dto=2016-11-14:%22Sensor%20Drivers%22)
+* Support for MIPS architecture
+* Support for additional boards
<font color="#F2853F"> The detailed roadmap is tracked on [JIRA for Mynewt](https://issues.apache.org/jira/browse/MYNEWT/?selectedTab=com.atlassian.jira.jira-projects-plugin:roadmap-panel). </font>
[5/8] incubator-mynewt-site git commit: Minor updates
Posted by ad...@apache.org.
Minor updates
Some minor editing fixes
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/5fd69a64
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/5fd69a64
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/5fd69a64
Branch: refs/heads/develop
Commit: 5fd69a6454df8532962edcf587c33378f7b22354
Parents: 6072f7e
Author: David G. Simmons <sa...@mac.com>
Authored: Thu Nov 17 12:23:12 2016 -0500
Committer: David G. Simmons <sa...@mac.com>
Committed: Thu Nov 17 12:23:12 2016 -0500
----------------------------------------------------------------------
docs/os/tutorials/tasks_lesson.md | 161 ++++++++++++++++++++++-------
docs/os/tutorials/wi-fi_on_arduino.md | 2 +-
2 files changed, 127 insertions(+), 36 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/5fd69a64/docs/os/tutorials/tasks_lesson.md
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/tasks_lesson.md b/docs/os/tutorials/tasks_lesson.md
index 060381b..70801ed 100644
--- a/docs/os/tutorials/tasks_lesson.md
+++ b/docs/os/tutorials/tasks_lesson.md
@@ -2,10 +2,16 @@
#Core OS Lesson: Tasks and Priority Management
**Target Platform: Arduino M0 Pro** (or legacy Arduino Zero or Zero Pro, but not Arduino M0)
-This lesson is designed to teach core OS concepts and strategies encountered when building applications using Mynewt. Specifically, this lesson will cover tasks, simple multitasking, and priority management running on an Arduino M0 Pro.
+This lesson is designed to teach core OS concepts and strategies encountered when
+building applications using Mynewt. Specifically, this lesson will cover tasks,
+simple multitasking, and priority management running on an Arduino M0 Pro.
##Prerequisites
-Before starting, you should read about Mynewt in the [*Introduction*](http://mynewt.apache.org/os/introduction/) section and complete the [*QuickStart*](http://mynewt.apache.org/os/get_started/get_started/) guide and the [*Blinky*](http://mynewt.apache.org/os/tutorials/arduino_zero/) tutorial. Furthermore, it may be helpful to take a peek at the [*task documentation*](http://mynewt.apache.org/os/core_os/task/task/) for additional insights.
+Before starting, you should read about Mynewt in the [*Introduction*](http://mynewt.apache.org/os/introduction/)
+section and complete the [*QuickStart*](http://mynewt.apache.org/os/get_started/get_started/)
+guide and the [*Blinky*](http://mynewt.apache.org/os/tutorials/arduino_zero/) tutorial.
+Furthermore, it may be helpful to take a peek at the [*task documentation*](http://mynewt.apache.org/os/core_os/task/task/)
+for additional insights.
##Equipment
You will need the following equipment:
@@ -15,21 +21,32 @@ You will need the following equipment:
- USB to Micro USB Cable
##Build Your Application
-To save time, we will simply modify the Blinky app as it has the basic task structure already implemented. Follow the [*Arduino Zero Blinky tutorial*](http://mynewt.apache.org/os/tutorials/arduino_zero/) to create a new project and build your bootloader and application. Finally, build and load the application to your Arduino to verify that everything is in order. Now let\u2019s get started!
+To save time, we will simply modify the Blinky app. We'll add the Task Management code to
+the Blinky App. Follow the [*Arduino Zero Blinky tutorial*](http://mynewt.apache.org/os/tutorials/arduino_zero/)
+to create a new project and build your bootloader and application. Finally, build and
+load the application to your Arduino to verify that everything is in order. Now let\u2019s get started!
##Create a New Task
-The purpose of this section is to give an introduction to the important aspects of tasks and how to properly initialize them. First, let\u2019s define a second task called `work_task` in main.c (located in apps/blinky/src):
+The purpose of this section is to give an introduction to the important aspects of tasks
+and how to properly initialize them. First, let\u2019s define a second task called `work_task`
+in main.c (located in apps/blinky/src):
```c
struct os_task work_task;
```
-A task is represented by the [*os_task*](http://mynewt.apache.org/os/core_os/task/task/#data-structures) struct which will hold the task\u2019s information (name, state, priority, etc.). A task is made up of two main elements, a task function (also known as a task handler) and a task stack.
+A task is represented by the [*os_task*](http://mynewt.apache.org/os/core_os/task/task/#data-structures)
+struct which will hold the task\u2019s information (name, state, priority, etc.). A task is made up of two
+main elements, a task function (also known as a task handler) and a task stack.
Next, let\u2019s take a look at what is required to initialize our new task.
### Task Stack
-The task stack is an array of type `os_stack_t` which holds the program stack frames. Mynewt gives us the ability to set the stack size for a task giving the application developer room to optimize memory usage. Since we\u2019re not short on memory, our `blinky_stack` and `work_stack` are plenty large for the purpose of this lesson. Notice that the elements in our task stack are of type `os_stack_t` which are generally 32 bits, making our entire stack 1024 Bytes.
+The task stack is an array of type `os_stack_t` which holds the program stack frames. Mynewt gives
+us the ability to set the stack size for a task giving the application developer room to optimize
+memory usage. Since we\u2019re not short on memory, our `blinky_stack` and `work_stack` are plenty large
+for the purpose of this lesson. Notice that the elements in our task stack are of type `os_stack_t`
+which are generally 32 bits, making our entire stack 1024 Bytes.
```c
#define WORK_STACK_SIZE OS_STACK_ALIGN(256)
@@ -40,7 +57,10 @@ The task stack is an array of type `os_stack_t` which holds the program stack fr
Note: The `OS_STACK_ALIGN` macro is used to align the stack based on the hardware architecture.
### Task Function
-The task function is essentially an infinite loop which waits for some \u201cevent\u201d to wake it up. In our Blinky app the task function, named `blinky_task_handler()`, is initially called when we call `os_start()` in `main()`. In general, the task function is where the majority of work is done by a task. Let\u2019s write a task function for `work_task` called `work_task_handler()`:
+The task function is essentially an infinite loop which waits for some \u201cevent\u201d to wake it up. In our
+Blinky app the task function, named `blinky_task_handler()`, is initially called when we call `os_start()`
+in `main()`. In general, the task function is where the majority of work is done by a task. Let\u2019s write
+a task function for `work_task` called `work_task_handler()`:
```c
void
@@ -59,10 +79,15 @@ work_task_handler(void *arg)
}
```
-The task function is called when the task is initially put into the *running* state by the scheduler. We use an infinite loop to ensure that the task function never returns. Our assertion that the current task's handler is the same as our task handler is for illustration purposes only and does not need to be in most task functions.
+The task function is called when the task is initially put into the *running* state by the scheduler.
+We use an infinite loop to ensure that the task function never returns. Our assertion that the current
+task's handler is the same as our task handler is for illustration purposes only and does not need to
+be in most task functions.
### Task Priority
-As a preemptive, multitasking RTOS, Mynewt decides which tasks to run based on which has a higher priority; the highest priority being 0 and the lowest 255. Thus, before initializing our task, we must choose a priority defined as a macro variable.
+As a preemptive, multitasking RTOS, Mynewt decides which tasks to run based on which has a higher
+priority; the highest priority being 0 and the lowest 255. Thus, before initializing our task, we
+must choose a priority defined as a macro variable.
Let\u2019s set the priority of `work_task` to 0, because everyone knows that work is more important than blinking.
```c
@@ -70,7 +95,9 @@ Let\u2019s set the priority of `work_task` to 0, because everyone knows that work i
```
### Initialization
-To initialize a new task we use [*os_task_init()*](http://mynewt.apache.org/os/core_os/task/os_task_init/) which takes a number of arguments including our new task function, stack, and priority. Much like `blinky_task`, we\u2019re going to initialize `work_task` inside `init_tasks` to keep our main function clean.
+To initialize a new task we use [*os_task_init()*](http://mynewt.apache.org/os/core_os/task/os_task_init/)
+which takes a number of arguments including our new task function, stack, and priority. Much like `blinky_task`,
+we\u2019re going to initialize `work_task` inside `init_tasks` to keep our main function clean.
```c
int
@@ -124,9 +151,16 @@ os_task_init(&mytask, "mytask", mytask_handler, NULL,
```
##Task Priority, Preempting, and Context Switching
-A preemptive RTOS is one in which a higher priority task that is *ready to run* will preempt (i.e. take the place of) the lower priority task which is *running*. When a lower priority task is preempted by a higher priority task, the lower priority task\u2019s context data (stack pointer, registers, etc.) is saved and the new task is switched in.
+A preemptive RTOS is one in which a higher priority task that is *ready to run* will preempt (i.e. take the
+place of) the lower priority task which is *running*. When a lower priority task is preempted by a higher
+priority task, the lower priority task\u2019s context data (stack pointer, registers, etc.) is saved and the new
+task is switched in.
-In our example, `work_task` has a higher priority than `blinky_task` and, because it is never put into a *sleep* state, holds the processor focus on its context. Let\u2019s give `work_task` a delay and some simulated work to keep it busy. Because the delay is measured in os ticks, the actual number of ticks per second is dependent on the board. Therefore, we multiply `OS_TICKS_PER_SEC`, which is defined in the MCU, by the number of seconds we wish to delay.
+In our example, `work_task` has a higher priority than `blinky_task` and, because it is never put into a
+*sleep* state, holds the processor focus on its context. Let\u2019s give `work_task` a delay and some simulated
+work to keep it busy. Because the delay is measured in os ticks, the actual number of ticks per second is
+dependent on the board. Therefore, we multiply `OS_TICKS_PER_SEC`, which is defined in the MCU, by the
+number of seconds we wish to delay.
```c
void
@@ -155,27 +189,38 @@ In order to notice the LED changing, modify the time delay in `blinky_task_handl
```c
os_time_delay(OS_TICKS_PER_SEC/10);
```
-Before we run the app, let\u2019s predict the behavior. With the newest additions to `work_task_handler()`, our first action will be to sleep for three seconds. This will allow `blinky_task` to take over the CPU and blink to its heart\u2019s content. After three seconds, `work_task` will wake up and be made *ready to run*, causing it to preempt `blinky_task`. The LED will then remain lit for a short period while `work_task` loops, then blink again for another three seconds while `work_task` sleeps.
+Before we run the app, let\u2019s predict the behavior. With the newest additions to `work_task_handler()`,
+our first action will be to sleep for three seconds. This will allow `blinky_task` to take over the CPU
+and blink to its heart\u2019s content. After three seconds, `work_task` will wake up and be made *ready to run*,
+causing it to preempt `blinky_task`. The LED will then remain lit for a short period while `work_task`
+loops, then blink again for another three seconds while `work_task` sleeps.
Voila, you should see that our prediction was correct!
###Priority Management Considerations
-When projects grow in scope, from blinking LEDs into more sophisticated applications, the number of tasks needed increases alongside complexity. It remains important, then, that each of our tasks is capable of doing its work within a reasonable amount of time.
+When projects grow in scope, from blinking LEDs into more sophisticated applications, the number of
+tasks needed increases alongside complexity. It remains important, then, that each of our tasks is
+capable of doing its work within a reasonable amount of time.
-Some tasks, such as the Shell task, execute quickly and require almost instantaneous response. Therefore, the Shell task should be given a high priority. On the other hand, tasks which may be communicating over a network, or processing data, should be given a low priority in order to not hog the CPU.
+Some tasks, such as the Shell task, execute quickly and require almost instantaneous response. Therefore,
+the Shell task should be given a high priority. On the other hand, tasks which may be communicating over
+a network, or processing data, should be given a low priority in order to not hog the CPU.
-The diagram below showcases the different scheduling patterns we. would expect from swapping blinky and work tasks priorities.
+The diagram below showcases the different scheduling patterns we. would expect from swapping blinky and
+work tasks priorities.
-In the second case where `blinky_task` has a higher priority, the \u201cwork\u201d done by `work_task` would be executed during the millisecond delays in `blinky_task`, saving us idle time compared to the first case.
+In the second case where `blinky_task` has a higher priority, the \u201cwork\u201d done by `work_task` would be
+executed during the millisecond delays in `blinky_task`, saving us idle time compared to the first case.
**Note:** Defining the same priority for two tasks leads to somewhat undefined behavior and should be avoided.
##Comparing Priority Strategies
-Instead of stepping through a bunch of changes to our blinky app, clone my task lesson application from github and copy an existing target.
+Instead of stepping through a bunch of changes to our blinky app, clone my task lesson application from
+github and copy an existing target.
Change directory into apps and clone the repository to get our new
files:
@@ -192,21 +237,31 @@ Set a new app location.
$ newt target set task_tgt app=apps/mynewt_tasks_lesson
```
-Now let\u2019s take a look at our new code. First, notice that we have abandoned blinking, instead choosing to use the [*console*](http://mynewt.apache.org/latest/os/modules/console/console/) and [*shell*](http://mynewt.apache.org/latest/os/modules/shell/shell/) to follow our tasks through execution.
+Now let\u2019s take a look at our new code. First, notice that we have abandoned blinking, instead choosing t
+o use the [*console*](http://mynewt.apache.org/latest/os/modules/console/console/) and [*shell*](http://mynewt.apache.org/latest/os/modules/shell/shell/)
+to follow our tasks through execution.
Additionally, we have a number of different tasks:
- **Task A** (`a_task`):
- **Priority**: 3 \u2192 2
- - **Description**: Task A is supposed to represent a task which frequently does a small amount of work, such as one which rapidly polls a sensor for data. Much like `blinky_task`, Task A will loop 10,000 times then wait 1 millisecond. Priority is changed by `timer_task` after the first simulation.
+ - **Description**: Task A is supposed to represent a task which frequently does a small amount
+ of work, such as one which rapidly polls a sensor for data. Much like `blinky_task`, Task A will
+ loop 10,000 times then wait 1 millisecond. Priority is changed by `timer_task` after the first simulation.
- **Task B** (`b_task`):
- **Priority**: 2 \u2192 3
- - **Description**: Task B is supposed to represent a task which does a large amount of work relatively infrequently, such as one which sends/receives data from the cloud. Like work\_task, Task B will loop 1,000,000 times then wait 3 seconds. Priority is changed by timer\_task after the first simulation.
+ - **Description**: Task B is supposed to represent a task which does a large amount of work
+ relatively infrequently, such as one which sends/receives data from the cloud. Like work\_task,
+ Task B will loop 1,000,000 times then wait 3 seconds. Priority is changed by timer\_task after
+ the first simulation.
- **Timer Task** (`timer_task`):
- **Priority**: 1
- - **Description**: With default settings, Timer Task will wait 20 seconds then print the first simulations data for Task A and B. Timer task will then swap A and B\u2019s priorities and restart the simulation. After the second simulation, timer will again print simulation data then compare the two and calculate a final speedup (simulation2 / simulation1).
+ - **Description**: With default settings, Timer Task will wait 20 seconds then print the first
+ simulations data for Task A and B. Timer task will then swap A and B\u2019s priorities and restart the
+ simulation. After the second simulation, timer will again print simulation data then compare the
+ two and calculate a final speedup (simulation2 / simulation1).
- **Shell Task**:
- **Priority**: 0
@@ -214,7 +269,9 @@ Additionally, we have a number of different tasks:
### Connecting to the Serial Console
-Before running our new app, we must first connect to the serial console. First make sure the mynewt_arduino_zero repository is set to the develop branch. (Remove once changes have been moved to master).
+Before running our new app, we must first connect to the serial console. First make sure the
+mynewt_arduino_zero repository is set to the develop branch. (Remove once changes have been
+moved to master).
```
$ cd repos/mynewt_arduino_zero
$ git checkout develop
@@ -227,7 +284,8 @@ $ ls /dev/tty.*
/dev/tty.Bluetooth-Incoming-Port /dev/tty.usbmodem14132
```
-In the same window, connect to the serial port using a serial communication program. In this case I\u2019ll be using mincom as it can scroll through output.
+In the same window, connect to the serial port using a serial communication program.
+In this case I\u2019ll be using mincom as it can scroll through output.
```c
$ minicom -D /dev/tty.usbmodem14132 -b 115200
```
@@ -302,23 +360,56 @@ Starting First Simulation...
```
-The console output reaffirms our previous prediction and makes both the scheduling differences and subsequent efficiency boost far more apparent. Let\u2019s take a look at scheduling differences before we delve into efficiency.
-
-In the first case, where Task B\u2019s priority is higher than that of Task A, we see A get starved by Task B\u2019s long execution time. **Starvation** occurs when one task hogs the processor, essentially \u201cstarving\u201d other tasks which also need to run. At the end of the first 20 second simulation period, Task A has only run for 1.4 seconds compared to task B\u2019s 17 second running time \u2013 ouch. As explained before, processes which are expected to run for long periods of time (e.g. network communication, data processing) should be given higher priorities in order to combat starvation.
-
-In the second simulation with priorities swapped, we can see Task B only running during the millisecond delays when Task A is *sleeping*. Although having Task B only run during these delays slows its execution time, we benefit from un-starving Task A and using the processor at a higher efficiency.
-
-The bottom line speedup gives us an immediate and clear indication that we have improved our ability to process work (i.e throughput). In our second run, we processed an additional 400,000 loop iterations, equating to a 26% increase in efficiency. On a standard multi-core processor found in every modern PC, a 1.26 speedup would be an ok result to adding multithreading capabilities to a serial program. However, we accomplished this by simply setting priorities on a single core processor \u2013 not bad!
-
-NOTE: Usually the the term \u201cspeedup\u201d is used within a parallel programming context and refers to the change in execution time between a serial and parallel program executing over the same problem. In this case we\u2019re using the term loosely to illustrate the priority change\u2019s effect on scheduling and throughput in our specific context.
+The console output reaffirms our previous prediction and makes both the scheduling differences
+and subsequent efficiency boost far more apparent. Let\u2019s take a look at scheduling differences
+before we delve into efficiency.
+
+In the first case, where Task B\u2019s priority is higher than that of Task A, we see A get starved
+by Task B\u2019s long execution time. **Starvation** occurs when one task hogs the processor, essentially
+\u201cstarving\u201d other tasks which also need to run. At the end of the first 20 second simulation period,
+Task A has only run for 1.4 seconds compared to task B\u2019s 17 second running time \u2013 ouch. As explained
+before, processes which are expected to run for long periods of time (e.g. network communication,
+data processing) should be given higher priorities in order to combat starvation.
+
+In the second simulation with priorities swapped, we can see Task B only running during the
+millisecond delays when Task A is *sleeping*. Although having Task B only run during these
+delays slows its execution time, we benefit from un-starving Task A and using the processor
+at a higher efficiency.
+
+The bottom line speedup gives us an immediate and clear indication that we have improved our
+ability to process work (i.e throughput). In our second run, we processed an additional 400,000
+loop iterations, equating to a 26% increase in efficiency. On a standard multi-core processor
+found in every modern PC, a 1.26 speedup would be an ok result to adding multithreading capabilities
+to a serial program. However, we accomplished this by simply setting priorities on a single core
+processor \u2013 not bad!
+
+NOTE: Usually the the term \u201cspeedup\u201d is used within a parallel programming context and refers
+to the change in execution time between a serial and parallel program executing over the same
+problem. In this case we\u2019re using the term loosely to illustrate the priority change\u2019s effect
+on scheduling and throughput in our specific context.
### Efficiency Isn\u2019t Everything
-Using the processor during every OS tick isn\u2019t always the best course of action. If we modify Task A\u2019s delay to a tenth of a millisecond and turn off the console output, we can boost our speedup to 1.44. This, however, reduces our ability to process work from Task B who ends up only completing 18% of its work cycle after the second simulation. That would mean, at that rate, Task B would take over a minute to finish one cycle.
+Using the processor during every OS tick isn\u2019t always the best course of action. If we modify
+Task A\u2019s delay to a tenth of a millisecond and turn off the console output, we can boost our
+speedup to 1.44. This, however, reduces our ability to process work from Task B who ends up
+only completing 18% of its work cycle after the second simulation. That would mean, at that
+rate, Task B would take over a minute to finish one cycle.
Feel free to play around with the testing parameters to study the different changes yourself!
##Conclusion
-Moving forward, tasks are just the tip of the iceberg. The [*scheduler*](http://mynewt.apache.org/latest/os/core_os/context_switch/context_switch/), [*event queues*](http://mynewt.apache.org/latest/os/core_os/event_queue/event_queue/), [*semaphores*](http://mynewt.apache.org/latest/os/core_os/semaphore/semaphore/), and [*mutexes*](http://mynewt.apache.org/latest/os/core_os/mutex/mutex/) also add to tasks functionality, increasing our ability as the developer to control greater numbers of tasks more intricately. For example, when we switch the tasks priority, we have to tell the scheduler that our tasks priorities have changed, allowing us us to use priorities dynamically. When running multiple tasks, logging through either the built-in [*Logs*](http://mynewt.apache.org/latest/os/modules/logs/logs/) module (not covered in this lesson) or through the serial console/shell can be very useful for debugging your application. In the end, the way you manage your tasks depends on the context
of your application. You should assign priorities based on execution time, urgency, and frequency, among other things.
+Moving forward, tasks are just the tip of the iceberg. The [*scheduler*](http://mynewt.apache.org/latest/os/core_os/context_switch/context_switch/),
+[*event queues*](http://mynewt.apache.org/latest/os/core_os/event_queue/event_queue/),
+[*semaphores*](http://mynewt.apache.org/latest/os/core_os/semaphore/semaphore/), and
+[*mutexes*](http://mynewt.apache.org/latest/os/core_os/mutex/mutex/) also add to tasks functionality,
+increasing our ability as the developer to control greater numbers of tasks more intricately. For
+example, when we switch the tasks priority, we have to tell the scheduler that our tasks priorities
+have changed, allowing us us to use priorities dynamically. When running multiple tasks, logging
+through either the built-in [*Logs*](http://mynewt.apache.org/latest/os/modules/logs/logs/) module
+(not covered in this lesson) or through the serial console/shell can be very useful for debugging
+your application. In the end, the way you manage your tasks depends on the context of your
+application. You should assign priorities based on execution time, urgency, and frequency, among
+other things.
Keep blinking and happy hacking!
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/5fd69a64/docs/os/tutorials/wi-fi_on_arduino.md
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/wi-fi_on_arduino.md b/docs/os/tutorials/wi-fi_on_arduino.md
index 977f6d8..5f7085b 100644
--- a/docs/os/tutorials/wi-fi_on_arduino.md
+++ b/docs/os/tutorials/wi-fi_on_arduino.md
@@ -15,7 +15,7 @@ You will need the following equipment
* An Arduino Zero, Zero Pro or M0 Pro.
**Note:** Mynewt has not been tested on Arduino M0 which has no internal debugger support.
-* An Arduino Wi-Fi Shield 101
+* An [Arduino Wi-Fi Shield 101](https://www.adafruit.com/product/2891)
* A computer that can connect to the Arduino board over USB
* A local Wi-Fi network that the computer is connected to and which the Arduino board can join.
* A USB cable (Type A to micro B) that can connect the computer to the Arduino (or a USB hub between the computer and the Arduino board)
[4/8] incubator-mynewt-site git commit: Updated Event Q
Posted by ad...@apache.org.
Updated Event Q
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/6072f7e5
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/6072f7e5
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/6072f7e5
Branch: refs/heads/develop
Commit: 6072f7e5110234bf56d1251b1d031fc66d04b23e
Parents: b1afc81
Author: David G. Simmons <sa...@mac.com>
Authored: Wed Nov 16 13:50:03 2016 -0500
Committer: David G. Simmons <sa...@mac.com>
Committed: Wed Nov 16 13:50:03 2016 -0500
----------------------------------------------------------------------
docs/os/core_os/event_queue/event_queue.md | 89 ++++++++++++++++----
.../core_os/event_queue/os_eventq_dflt_get.md | 42 +++++++++
.../core_os/event_queue/os_eventq_dflt_set.md | 45 ++++++++++
docs/os/core_os/event_queue/os_eventq_inited.md | 47 +++++++++++
mkdocs.yml | 5 +-
5 files changed, 211 insertions(+), 17 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/6072f7e5/docs/os/core_os/event_queue/event_queue.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/event_queue/event_queue.md b/docs/os/core_os/event_queue/event_queue.md
index 748673e..9ff8800 100644
--- a/docs/os/core_os/event_queue/event_queue.md
+++ b/docs/os/core_os/event_queue/event_queue.md
@@ -7,13 +7,23 @@ Events arrive in a form of a data structure `struct os_event`.
### Description
-Events are in form of a data structure `struct os_event`, and they are queued to data structure `struct os_eventq`.
+Events are in form the of a data structure `struct os_event` and
+they are queued to another data structure `struct os_eventq`.
-Queue must be initialized before trying to add events to it. This is done using `os_eventq_init()`.
+The Event 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.
+A 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. This
+method of event handling requires that the task handler itself would dispatch the
+events based on the event's type.
+
+Mynewt has moved the event dispatching logic out of the task handler and instead the
+logic is built in to each event via a callback function pointer. The task handler no longer
+needs to dispatch events based on their types but instead can simply pull events
+off the queue and call it's callback handler.
When `os_event` is queued, it should not be freed until processing task is done with it.
@@ -24,9 +34,11 @@ Note that [os_callout](../callout/callout.md) subsystem assumes that event queue
### Data structures
```c
+typedef void os_event_fn(struct os_event *ev);
+
struct os_event {
uint8_t ev_queued;
- uint8_t ev_type;
+ os_event_fn *ev_cb;
void *ev_arg;
STAILQ_ENTRY(os_event) ev_next;
};
@@ -34,13 +46,53 @@ struct os_event {
| 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 |
+| `ev_queued` | Internal field, which tells whether event is linked into an *os_eventq* already |
+| `ev_cb` | A callback function pointer that is called when a new event arrives on the queue |
+| `ev_arg` | Can be used further as input to task processing this event |
+| `ev_next` | Linkage attaching this event to an event queue |
+
+With the addition of a callback function pointer, the dispatch logic
+is moved out of the task handler and gets built into each event. A
+task handler now just pulls an event off its queue and blindly calls
+its callback function. A helper function was added to do just this:
+`os_eventq_run()`. As an example, the task handler
+for the bleprph application is below:
+```c
+static void
+bleprph_task_handler(void *unused)
+{
+ while (1) {
+ os_eventq_run(&bleprph_evq);
+ }
+}
+```
+
+The callback associated with an event is specified when the event gets
+initialized. For example, here are some statically-initialized events
+in the nimble host:
```c
+static void ble_hs_event_tx_notify(struct os_event *ev);
+static void ble_hs_event_reset(struct os_event *ev);
+
+/** OS event - triggers tx of pending notifications and indications. */
+static struct os_event ble_hs_ev_tx_notifications = {
+ .ev_cb = ble_hs_event_tx_notify,
+};
+
+/** OS event - triggers a full reset. */
+static struct os_event ble_hs_ev_reset = {
+ .ev_cb = ble_hs_event_reset,
+};
+```
+
+The callback function receives a single parameter: a
+pointer to the event being processed. If the event is allocated
+dynamically, the callback function should free the event.
+
+
+```c
struct os_eventq {
struct os_task *evq_task;
STAILQ_HEAD(, os_event) evq_list;
@@ -50,8 +102,8 @@ struct os_eventq {
| 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 |
+| `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
@@ -60,8 +112,13 @@ The functions available in event queue feature are:
| **Function** | **Description** |
|---------|-------------|
-| [os_eventq_get](os_eventq_get.md) | Fetches the first event from a queue. Task will sleep until something gets queued. |
-| [os_eventq_init](os_eventq_init.md) | Initializes the given event queue, making it ready for use. |
-| [os_eventq_put](os_eventq_put.md) | Queues an event to tail of the event queue. |
-| [os_eventq_remove](os_eventq_remove.md) | Removes an event which has been placed in a queue. |
+| [`os_eventq_init`](os_eventq_init.md) | Initializes the given event queue, making it ready for use. |
+| [`os_eventq_inited`](os_eventq_inited.md) | Has the event queue been initialized. |
+| [`os_eventq_get`](os_eventq_get.md) | Fetches the first event from a queue. Task will sleep until something gets queued. |
+| [`os_eventq_put`](os_eventq_put.md) | Queues an event to tail of the event queue. |
+| [`os_eventq_remove`](os_eventq_remove.md) | Removes an event which has been placed in a queue. |
+| [`os_eventq_dflt_set`](os_eventq_dflt_set.md) | Set the default event queue. |
+| [`os_eventq_dflt_get`](os_eventq_dflt_get.md) | Get the default event queue. |
+
+
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/6072f7e5/docs/os/core_os/event_queue/os_eventq_dflt_get.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/event_queue/os_eventq_dflt_get.md b/docs/os/core_os/event_queue/os_eventq_dflt_get.md
new file mode 100644
index 0000000..b174b7e
--- /dev/null
+++ b/docs/os/core_os/event_queue/os_eventq_dflt_get.md
@@ -0,0 +1,42 @@
+## <font color="F2853F" style="font-size:24pt"> os_eventq_dflt_get</font>
+
+```c
+ struct os_eventq
+ *os_eventq_dflt_get(void)
+```
+
+Get the default event queue that was set
+
+#### Arguments
+
+None
+
+#### Returned values
+
+`struct os_eventq *` A pointer to the default event queue, if set.
+
+#### Notes
+
+None
+
+
+#### Example
+
+<Add text to set up the context for the example here>
+This checks the default event queue and sets it if not already set.
+
+
+```c
+struct os_eventq g_my_evq;
+
+int
+event_q_check()
+{
+ if(os_eventq_dflt_get() == NULL)
+ {
+ os_eventq_dflt_set(g_my_evq);
+ }
+
+}
+```
+
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/6072f7e5/docs/os/core_os/event_queue/os_eventq_dflt_set.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/event_queue/os_eventq_dflt_set.md b/docs/os/core_os/event_queue/os_eventq_dflt_set.md
new file mode 100644
index 0000000..7d411d0
--- /dev/null
+++ b/docs/os/core_os/event_queue/os_eventq_dflt_set.md
@@ -0,0 +1,45 @@
+## <font color="F2853F" style="font-size:24pt"> os_eventq_dflt_set</font>
+
+```c
+ void
+ os_eventq_dflt_set(struct os_eventq *evq)
+```
+
+Sets `struct os_eventq`, as te default event queue
+
+#### Arguments
+
+| Arguments | Description |
+|-----------|-------------|
+| `evq` | Pointer to default event queue to use |
+
+#### 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 sets the default event queue used by newtmgr task.
+
+
+```c
+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);
+ os_eventq_dflt_set(&g_nmgr_evq);
+
+ /* initialization continues here */
+}
+```
+
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/6072f7e5/docs/os/core_os/event_queue/os_eventq_inited.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/event_queue/os_eventq_inited.md b/docs/os/core_os/event_queue/os_eventq_inited.md
new file mode 100644
index 0000000..5f81071
--- /dev/null
+++ b/docs/os/core_os/event_queue/os_eventq_inited.md
@@ -0,0 +1,47 @@
+## <font color="F2853F" style="font-size:24pt"> os_eventq_inited</font>
+
+```c
+ int
+ os_eventq_inited(const struct os_eventq *evq)
+```
+
+Check if event queue `const struct os_eventq`, is it ready for use.
+
+#### Arguments
+
+| Arguments | Description |
+|-----------|-------------|
+| `evq` | Pointer to event queue to check |
+
+#### Returned values
+
+`0` if event queue is ready
+
+#### Notes
+
+If an event queue was properly initialized (and the proper checks were done at initialization)
+this check is not needed prior to using an event queue.
+
+
+#### Example
+
+<Add text to set up the context for the example here>
+This checks an event queue before using it.
+
+
+```c
+struct os_eventq g_my_evq;
+
+int
+my_task_init(uint8_t prio, os_stack_t *stack_ptr, uint16_t stack_len)
+{
+ /* variable declarations here */
+
+ if(os_eventq_inited(&g_my_evq))
+ {
+ /* deal with the event queue */
+ };
+
+}
+```
+
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/6072f7e5/mkdocs.yml
----------------------------------------------------------------------
diff --git a/mkdocs.yml b/mkdocs.yml
index 02bca04..f87a837 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -95,10 +95,13 @@ pages:
- Event Queues:
- toc: 'os/core_os/event_queue/event_queue.md'
- 'Functions':
- - 'os_eventq_get': 'os/core_os/event_queue/os_eventq_get.md'
- 'os_eventq_init': 'os/core_os/event_queue/os_eventq_init.md'
+ - 'os_eventq_inited': 'os/core_os/event_queue/os_eventq_inited.md'
+ - 'os_eventq_get': 'os/core_os/event_queue/os_eventq_get.md'
- 'os_eventq_put': 'os/core_os/event_queue/os_eventq_put.md'
- 'os_eventq_remove': 'os/core_os/event_queue/os_eventq_remove.md'
+ - 'os_eventq_dflt_set': 'os/core_os/event_queue/os_eventq_dflt_set.md'
+ - 'os_eventq_dflt_get': 'os/core_os/event_queue/os_eventq_dflt_get.md'
- Semaphores:
- toc: 'os/core_os/semaphore/semaphore.md'
- 'Functions':
[2/8] incubator-mynewt-site git commit: This closes #118.
Posted by ad...@apache.org.
This closes #118.
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/54755cb9
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/54755cb9
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/54755cb9
Branch: refs/heads/develop
Commit: 54755cb9dda1f8f18528f52d5c222d5ae7b75cdf
Parents: 38b20a6 b1afc81
Author: aditihilbert <ad...@runtime.io>
Authored: Mon Nov 14 18:10:23 2016 -0800
Committer: aditihilbert <ad...@runtime.io>
Committed: Mon Nov 14 18:10:23 2016 -0800
----------------------------------------------------------------------
docs/os/tutorials/repo/add_repos.md | 14 +++++++---
docs/os/tutorials/repo/create_repo.md | 40 ++++++++++++++++++++---------
docs/os/tutorials/repo/upgrade_repo.md | 4 +++
mkdocs.yml | 3 +--
4 files changed, 43 insertions(+), 18 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/54755cb9/mkdocs.yml
----------------------------------------------------------------------
[6/8] incubator-mynewt-site git commit: Merge branch 'develop' of
https://github.com/davidgs/incubator-mynewt-site into develop
Posted by ad...@apache.org.
Merge branch 'develop' of https://github.com/davidgs/incubator-mynewt-site into develop
This closes #126.
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/306590aa
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/306590aa
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/306590aa
Branch: refs/heads/develop
Commit: 306590aa3ef1bbe9ae39c3e0327e21ee89f5ac83
Parents: 092e763 5fd69a6
Author: aditihilbert <ad...@runtime.io>
Authored: Thu Nov 17 14:06:18 2016 -0800
Committer: aditihilbert <ad...@runtime.io>
Committed: Thu Nov 17 14:06:18 2016 -0800
----------------------------------------------------------------------
docs/os/core_os/event_queue/event_queue.md | 89 ++++++++--
.../core_os/event_queue/os_eventq_dflt_get.md | 42 +++++
.../core_os/event_queue/os_eventq_dflt_set.md | 45 ++++++
docs/os/core_os/event_queue/os_eventq_inited.md | 47 ++++++
docs/os/tutorials/tasks_lesson.md | 161 +++++++++++++++----
docs/os/tutorials/wi-fi_on_arduino.md | 2 +-
mkdocs.yml | 5 +-
7 files changed, 338 insertions(+), 53 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/306590aa/mkdocs.yml
----------------------------------------------------------------------