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/08 08:50:37 UTC
[3/3] incubator-mynewt-site git commit: OS core description and
system level functions docs added. This closes #36.
OS core description and system level functions docs added. This closes #36.
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/9f2b076c
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/9f2b076c
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/9f2b076c
Branch: refs/heads/master
Commit: 9f2b076c4fe147f24153ee96fc3bd5ed0c793955
Parents: 7802513
Author: aditihilbert <ad...@runtime.io>
Authored: Mon Mar 7 23:50:25 2016 -0800
Committer: aditihilbert <ad...@runtime.io>
Committed: Mon Mar 7 23:50:25 2016 -0800
----------------------------------------------------------------------
custom-theme/manual_links.html | 1 +
docs/os/core_os/mynewt_os.md | 16 ++++++++++------
docs/os/core_os/os_start.md | 2 +-
docs/os/core_os/os_started.md | 2 +-
mkdocs.yml | 8 ++++----
5 files changed, 17 insertions(+), 12 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/9f2b076c/custom-theme/manual_links.html
----------------------------------------------------------------------
diff --git a/custom-theme/manual_links.html b/custom-theme/manual_links.html
index c0e05b4..b4615f6 100644
--- a/custom-theme/manual_links.html
+++ b/custom-theme/manual_links.html
@@ -1,3 +1,4 @@
+
<ul class="nav nav-pills">
{% set man_titles=['Mynewt OS Manual', 'Newt Manager Manual', 'Newt Tool Manual'] %}
{% set man_desc={'Mynewt OS Manual': 'Mynewt OS', 'Newt Manager Manual': 'Newt Mgr', 'Newt Tool Manual': 'Newt Tool'} %}
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/9f2b076c/docs/os/core_os/mynewt_os.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/mynewt_os.md b/docs/os/core_os/mynewt_os.md
index 56fa662..1a71186 100644
--- a/docs/os/core_os/mynewt_os.md
+++ b/docs/os/core_os/mynewt_os.md
@@ -1,11 +1,11 @@
# Mynewt Core OS
-The Mynewt Core OS is a multitasking, preemptive real-time operating system combining a scheduler with typical RTOS features such as mutexes, semaphores, memory pools, etc. The Mynewt Core OS also provides a number of useful utilities such as a task watchdog, networking stack memory buffers and time management API. Each of these features is described in detail in their own sections of the manual.
+The Mynewt Core OS is a multitasking, preemptive real-time operating system combining a scheduler with typical RTOS features such as mutexes, semaphores, memory pools, etc. The Mynewt Core OS also provides a number of useful utilities such as a task watchdog, networking stack memory buffers and time management API. Each of these features is described in detail in its own section of the manual.
A multitasking, preemptive operating system is one in which a number of different tasks can be instantiated and assigned a priority, with higher priority tasks running before lower priority tasks. Furthermore, if a lower priority task is running and a higher priority task wants to run, the lower priority task is halted and the higher priority task is allowed to run. In other words, the lower priority task is preempted by the higher priority task.
# Why use an OS?
-You may ask yourself "why do I need a multitasking preemptive OS"? The answer may indeed be that you do not. Some applications are simple and only require a polling loop. Others are more complex and may require that certain jobs are executed in a timely manner or before other jobs are executed. If you have a simple polling loop, you cant move on to service a job until the current job is done being serviced. With the Mynewt OS, the application developer need not worry about certain jobs taking too long or not executing in a timely fashion; the OS provides mechanisms to deal with these situations. Another benefit of using an OS is that it helps shield application developers form other application code being written; the developer does not have to worry (or has to worry less) about other application code behaving badly and causing undesirable behavior or preventing their code from executing properly. Other benefits of using an OS (and the Mynewt OS in particular) is that it also provid
es features that the developer would need to create on their own.
+You may ask yourself "why do I need a multitasking preemptive OS"? The answer may indeed be that you do not. Some applications are simple and only require a polling loop. Others are more complex and may require that certain jobs are executed in a timely manner or before other jobs are executed. If you have a simple polling loop, you cannot move on to service a job until the current job is done being serviced. With the Mynewt OS, the application developer need not worry about certain jobs taking too long or not executing in a timely fashion; the OS provides mechanisms to deal with these situations. Another benefit of using an OS is that it helps shield application developers from other application code being written; the developer does not have to worry (or has to worry less) about other application code behaving badly and causing undesirable behavior or preventing their code from executing properly. Other benefits of using an OS (and the Mynewt OS in particular) is that it also prov
ides features that the developer would otherwise need to create on his/her own.
# Core OS Features
@@ -26,15 +26,19 @@ You may ask yourself "why do I need a multitasking preemptive OS"? The answer ma
# Basic OS Application Creation
-Creating an application using the Mynewt Core OS is a relatively simple task: once you have installed the basic newt structure for your application and created your bsp, the developer initializes the os by calling `os_init()`, performs application specific initializations, and then starts the os by calling `os_start()`. The `os_init()` API performs two basic functions: calls architecture and bsp specific setup and initializes the idle task of the OS. This is required before the os is started. The os start API initializes the OS time tick interrupt and starts the highest priority task running (i.e starts the scheduler). Note that `os_start()` never returns; once called the device is either running in an application task context or in idle task context.
+Creating an application using the Mynewt Core OS is a relatively simple task: once you have installed the basic Newt Tool structure (build structure) for your application and created your BSP (Board Support Package), the developer initializes the OS by calling `os_init()`, performs application specific initializations, and then starts the os by calling `os_start()`.
-Initializing application modules and tasks can get somewhat complicated with RTOS's similar to Mynewt. Care must be taken that API provided by a task are initialized prior to being called by another (higher priority) task. For example, take a simple application with two tasks (tasks 1 and 2, with task 1 higher priority than task 2). Task 2 provides an API which has a semaphore lock and this semaphore is initialized by task 2 when the task handler for task 2 is called. Task 1 is expected to call this API.
+The `os_init()` API performs two basic functions: calls architecture and bsp specific setup and initializes the idle task of the OS. This is required before the OS is started. The OS start API initializes the OS time tick interrupt and starts the highest priority task running (i.e starts the scheduler). Note that `os_start()` never returns; once called the device is either running in an application task context or in idle task context.
-Consider the sequence of events when the OS is started. The scheduler starts running and picks the highest priority task (task 1 in this case). The task handler function for task 1 is called and will keep running until it yields execution. Before yielding, code in the task 1 handler function calls the API provided by task 2. The semaphore being accessed in the task 2 API has yet to be initialized since the task 2 handler function has not yet had a chance to run! This will lead to undesirable behavior and will need to be addressed by the application developer. Note that the Mynewt OS does guard against internal API being called before the OS has started (they will return error) but it does not safeguard application defined objects from access prior to initialization.
+Initializing application modules and tasks can get somewhat complicated with RTOS's similar to Mynewt. Care must be taken that the API provided by a task are initialized prior to being called by another (higher priority) task.
+
+For example, take a simple application with two tasks (tasks 1 and 2, with task 1 higher priority than task 2). Task 2 provides an API which has a semaphore lock and this semaphore is initialized by task 2 when the task handler for task 2 is called. Task 1 is expected to call this API.
+
+Consider the sequence of events when the OS is started. The scheduler starts running and picks the highest priority task (task 1 in this case). The task handler function for task 1 is called and will keep running until it yields execution. Before yielding, code in the task 1 handler function calls the API provided by task 2. The semaphore being accessed in the task 2 API has yet to be initialized since the task 2 handler function has not had a chance to run! This will lead to undesirable behavior and will need to be addressed by the application developer. Note that the Mynewt OS does guard against internal API being called before the OS has started (they will return error) but it does not safeguard application defined objects from access prior to initialization.
# Example
-One way to avoid initialization issues like the one described above is to perform task initializations prior to starting the OS. The code example shown below illustrates this concept. The application initializes the os, calls an application specific "task initialization" function and then starts the OS. The application task initialization function is responsible for initializing all the data objects that each task exposes to the other tasks. The tasks themselves are also initialized at this time (by calling `os_task_init()`).
+One way to avoid initialization issues like the one described above is to perform task initializations prior to starting the OS. The code example shown below illustrates this concept. The application initializes the OS, calls an application specific "task initialization" function, and then starts the OS. The application task initialization function is responsible for initializing all the data objects that each task exposes to the other tasks. The tasks themselves are also initialized at this time (by calling `os_task_init()`).
In the example, each task works in a ping-pong like fashion: task 1 wakes up, adds a token to semaphore 1 and then waits for a token from semaphore 2. Task 2 waits for a token on semaphore 1 and once it gets it, adds a token to semaphore 2. Notice that the semaphores are initialized by the application specific task initialization functions and not inside the task handler functions. If task 2 (being lower in priority than task 1) had called os_sem_init() for task2_sem inside task2_handler(), task 1 would have called os_sem_pend() using task2_sem before task2_sem was initialized.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/9f2b076c/docs/os/core_os/os_start.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/os_start.md b/docs/os/core_os/os_start.md
index 1b2ab0a..57fbde6 100644
--- a/docs/os/core_os/os_start.md
+++ b/docs/os/core_os/os_start.md
@@ -6,7 +6,7 @@ void os_start(void)
Starts the OS by initializing and enabling the OS time tick and starting the scheduler.
-This function does not return
+This function does not return.
<br>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/9f2b076c/docs/os/core_os/os_started.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/os_started.md b/docs/os/core_os/os_started.md
index 202dcb0..52e324c 100644
--- a/docs/os/core_os/os_started.md
+++ b/docs/os/core_os/os_started.md
@@ -15,7 +15,7 @@ None
<br>
#### Returned values
-Integer value with 0 meaning the OS has not been started and a 1 indicating the OS has been started (i.e. os_start() has been called).
+Integer value with 0 meaning the OS has not been started and 1 indicating the OS has been started (i.e. os_start() has been called).
<br>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/9f2b076c/mkdocs.yml
----------------------------------------------------------------------
diff --git a/mkdocs.yml b/mkdocs.yml
index 4ee867a..88cad1d 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -14,7 +14,8 @@ pages:
- Introduction: 'os/get_started/introduction.md'
- Get Started:
- 'Blinky, The First Project': 'os/get_started/project1.md'
- - 'Concepts': 'os/get_started/vocabulary.md'
+ - 'Concepts':
+ - toc: 'os/get_started/vocabulary.md'
- Tutorials:
- 'Blinky on STM32F303': 'os/tutorials/STM32F303.md'
- 'Blinky on nRF52': 'os/tutorials/nRF52.md'
@@ -24,9 +25,8 @@ pages:
- 'Edit Docs': 'os/tutorials/how_to_edit_docs.md'
- OS User Guide:
- OS Core:
- - OS Fundamentals:
- - Overview: 'os/core_os/mynewt_os.md'
- - Functions:
+ - toc: 'os/core_os/mynewt_os.md'
+ - System-level Functions:
- 'os_init': 'os/core_os/os_init.md'
- 'os_start': 'os/core_os/os_start.md'
- 'os_started': 'os/core_os/os_started.md'