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 2017/02/08 15:48:43 UTC
[1/2] incubator-mynewt-site git commit: Updated the docs to reflect
new system startup and initialization implementation. 1) Updated OS Core
Mynewt description:. - No longer use os_init,
and os_start. - Updated description and example on task depen
Repository: incubator-mynewt-site
Updated Branches:
refs/heads/develop 6e491445c -> 307f05af9
Updated the docs to reflect new system startup and initialization implementation.
1) Updated OS Core Mynewt description:.
- No longer use os_init, and os_start.
- Updated description and example on task dependencies and order of initialization.
No longer tell user to initalize data before starting the OS, since the OS has already started.
Tell user to initialize task share data before initializing tasks with OS.
2) Updated core OS task main() example.
3) Updated Console doc with new pkg.yml files in examples to use new paths. Minor edits and rewording.
4) Removed imgmgr_module_init from imgmgr
5) Core OS Shell: updated description, removed shell_task_init function, added shell_evq_set function.
6) Updated System initialization doc to use "infinite" instead of "forever" loop to be consistent with other docs.
This closes #150.
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/4e850f28
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/4e850f28
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/4e850f28
Branch: refs/heads/develop
Commit: 4e850f28aec16be3fa7cfce65de8316a48b8369b
Parents: 6e49144
Author: cwanda <wa...@happycity.com>
Authored: Sun Feb 5 20:19:24 2017 -0800
Committer: aditihilbert <ad...@runtime.io>
Committed: Wed Feb 8 06:18:36 2017 -0800
----------------------------------------------------------------------
docs/os/core_os/mynewt_os.md | 65 +++++++-------
docs/os/core_os/task/task.md | 22 +++--
docs/os/modules/console/console.md | 94 ++++++++++++---------
docs/os/modules/imgmgr/imgmgr.md | 1 -
docs/os/modules/shell/shell.md | 26 ++++--
docs/os/modules/shell/shell_evq_set.md | 23 +++++
docs/os/modules/sysinitconfig/sysinitconfig.md | 2 +-
mkdocs.yml | 9 +-
8 files changed, 146 insertions(+), 96 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/4e850f28/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 ecc695b..811f8c4 100644
--- a/docs/os/core_os/mynewt_os.md
+++ b/docs/os/core_os/mynewt_os.md
@@ -26,9 +26,15 @@ 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 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()`.
+Creating an application using the Mynewt Core OS is a relatively simple task. The main steps are:
+
+1. Install the basic Newt Tool structure (build structure) for your application.
+2. Create your BSP (Board Support Package).
+3. In your application `main()` function, call the `sysinit()` function to initialize
+the system and packages, perform application specific initialization, then
+wait and dispatch events from the OS default event
+queue in an infinite loop. (See [System Configuration and Initialization](/os/modules//sysinitconfig/sysinitconfig.md) for more details.)
-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.
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.
@@ -38,12 +44,19 @@ Consider the sequence of events when the OS is started. The scheduler starts run
###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 for the application to
+initialize the objects that are accessed by multiple tasks before it initializes the tasks with the OS.
+
+The code example shown below illustrates this concept. The application initializes system and packages, calls an application specific "task initialization" function, and dispatches events from the default event queue. 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.
```c
+
+ struct os_sem task1_sem;
+ struct os_sem task2_sem;
+
/* Task 1 handler function */
void
task1_handler(void *arg)
@@ -92,17 +105,22 @@ In the example, each task works in a ping-pong like fashion: task 1 wakes up, ad
/**
* init_app_tasks
*
- * Called by main.c after os_init(). This function performs initializations
- * that are required before tasks are running.
+ * This function performs initializations that are required before tasks run.
*
* @return int 0 success; error otherwise.
*/
static int
init_app_tasks(void)
{
+ /*
+ * Call task specific initialization functions to initialize any shared objects
+ * before initializing the tasks with the OS.
+ */
+ task1_init();
+ task2_init();
+
/*
- * Initialize tasks 1 and 2. Note that the task handlers are not called yet; they will
- * be called when the OS is started.
+ * Initialize tasks 1 and 2 with the OS.
*/
os_task_init(&task1, "task1", task1_handler, NULL, TASK1_PRIO,
OS_WAIT_FOREVER, task1_stack, TASK1_STACK_SIZE);
@@ -110,41 +128,32 @@ In the example, each task works in a ping-pong like fashion: task 1 wakes up, ad
os_task_init(&task2, "task2", task2_handler, NULL, TASK2_PRIO,
OS_WAIT_FOREVER, task2_stack, TASK2_STACK_SIZE);
- /* Call task specific initialization functions. */
- task1_init();
- task2_init();
-
return 0;
}
/**
* main
*
- * The main function for the application. This function initializes the os, calls
- * the application specific task initialization function. then starts the
- * OS. We should not return from os start!
+ * The main function for the application. This function initializes the system and packages,
+ * calls the application specific task initialization function, then waits and dispatches
+ * events from the OS default event queue in an infinite loop.
*/
int
- main(void)
+ main(int argc, char **arg)
{
- int i;
- int rc;
- uint32_t seed;
- /* Initialize OS */
- os_init();
+ /* Perform system and package initialization */
+ sysinit();
/* Initialize application specific tasks */
init_app_tasks();
- /* Start the OS */
- os_start();
-
- /* os start should never return. If it does, this should be an error */
- assert(0);
+ while (1) {
+ os_eventq_run(os_eventq_dflt_get());
+ }
+ /* main never returns */
+}
- return rc;
- }
```
###OS Functions
@@ -152,7 +161,5 @@ In the example, each task works in a ping-pong like fashion: task 1 wakes up, ad
The functions available at the OS level are:
-* [os_init](os_init.md)
-* [os_start](os_start.md)
* [os_started](os_started.md)
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/4e850f28/docs/os/core_os/task/task.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/task/task.md b/docs/os/core_os/task/task.md
index 6ec0685..48ad829 100644
--- a/docs/os/core_os/task/task.md
+++ b/docs/os/core_os/task/task.md
@@ -58,7 +58,7 @@ tasks. This information is of type `os_task_info` and is described below.
The following is a very simple example showing a single application task. This
task simply toggles an LED at a one second interval.
-```c
+```c
/* Create a simple "project" with a task that blinks a LED every second */
/* Define task stack and task object */
@@ -83,23 +83,21 @@ void my_task_func(void *arg) {
}
/* This is the main function for the project */
-int main(void) {
- int rc;
+int main(int argc, char **argv)
+{
- /* Initialize OS */
- os_init();
+ /* Perform system and package initialization */
+ sysinit();
/* Initialize the task */
os_task_init(&my_task, "my_task", my_task_func, NULL, MY_TASK_PRIO,
OS_WAIT_FOREVER, my_task_stack, MY_STACK_SIZE);
- /* Start the OS */
- os_start();
-
- /* os start should never return. If it does, this should be an error */
- assert(0);
-
- return rc;
+ /* Process events from the default event queue. */
+ while (1) {
+ os_eventq_run(os_eventq_dflt_get());
+ }
+ /* main never returns */
}
```
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/4e850f28/docs/os/modules/console/console.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/console/console.md b/docs/os/modules/console/console.md
index 9d5b738..43483b8 100644
--- a/docs/os/modules/console/console.md
+++ b/docs/os/modules/console/console.md
@@ -1,11 +1,10 @@
#Console
-The console is an operating system window where users interact with system programs of the operating system
-or a console application by entering text input (typically from a keyboard) and reading text output
-(typically on the computer terminal or monitor). The text written on the console brings some information
-and is a sequence of characters sent by the OS or programs running on the OS.
-
+The console is an operating system window where users interact with the OS subsystems or a console
+application. A user typically inputs text from a keyboard and reads the OS output text on a computer
+monitor. The text are sent as a sequence of characters between the user and the OS.
+
Support is currently available for console access via the serial port on the hardware board.
@@ -13,46 +12,65 @@ Support is currently available for console access via the serial port on the har
In the Mynewt OS, the console library comes in two versions:
-* full - containing the full implementation
-* stub - containing stubs for the API
+* The `sys/console/full` package implements the complete console functionality and API.
+
+* The `sys/console/stub` package implements stubs for the API.
-Both of these have a `pkg.yml` file which states that they provide the `console` API. If a pkg uses
-this API, it should list `console` as a requirement. For example, the shell pkg is defined by the
-following pkg.yml file:
+Both packages export the `console` API, and any package that uses
+the console API must list `console` as a requirement. For example, the shell package defines the following `pkg.yml`
+file:
```no-highlight
- pkg.name: libs/shell
- pkg.vers: 0.1
- pkg.deps:
- - libs/os
- - libs/util
- pkg.reqs:
- - console
- pkg.identities:
- - SHELL
+
+pkg.name: sys/shell
+pkg.deps:
+ - kernel/os
+ - encoding/base64
+ - time/datetime
+ - util/crc
+pkg.req_apis:
+ - console
+
```
-The project .yml file decides which version of the console pkg should be included.
-If a project requires the full console capability it lists dependency `libs/console/full` in its pkg.yml
-file. On the other hand, a project may not have a physical console (e.g. a UART port to connect a terminal to)
-but may have a dependency on a pkg that has console capability. In that case you would use a console stub.
+The project `pkg.yml` file specifies the version of the console package to use.
+A project that requires the full console capability must list the `sys/console/full` package as a dependency
+in its `pkg.yml` file.
+An example is the `slinky` application. It requires the full console capability and has the following
+`pkg.yml` file:
-Another example would be the bootloader project where we want to keep the size of the image small. It includes
-the `libs/os` pkg that can print out messages on a console (e.g. if there is a hard fault) and the `libs/util`
-pkg that uses the full console (but only if SHELL is present to provide a CLI). However, we do not want to use
-any console I/O capability in this particular bootloader project to keep the size small. We simply use the console
-stub instead, and the pkg.yml file for the project boot pkg looks like the following:
+```no-highlight
+pkg.name: apps/slinky
+pkg.deps:
+ - test/flash_test
+ - mgmt/imgmgr
+ - mgmt/newtmgr
+ - mgmt/newtmgr/transport/nmgr_shell
+ - kernel/os
+ - boot/bootutil
+ - sys/shell
+ - sys/console/full
+ ...
+ - sys/id
+```
+
+On the other hand, a project may not have a physical console (e.g. a UART port to connect a terminal to)
+but may have a dependency on a package that has console capability. In this case, you use
+the console stub API and list the `sys/console/stub` package as a dependency in its `pkg.yml` file.
+
+An example is the bootloader project where we want to keep the size of the image small. It includes
+the `kernel/os` package that can print out messages on a console (e.g. if there is a hard fault).
+However, we do not want to use any console I/O capability in this particular bootloader project to
+keep the size small. The project uses the console stub API and has the following `pkg.yml` file:
```no-highlight
- project.name: boot
- project.identities: bootloader
- project.pkgs:
- - libs/os
- - libs/bootutil
- - libs/nffs
- - libs/console/stub
- - libs/util
+pkg.name: apps/boot
+pkg.deps:
+ - boot/bootutil
+ - kernel/os
+ - sys/console/stub
+
```
Console has 2 modes for transmit; *blocking mode* and *non-blocking mode*. Usually the *non-blocking mode* is the
@@ -65,8 +83,8 @@ want to output info related to that crash.
Console, by default, echoes everything it receives back. Terminal programs expect this, and is a way for the user to
know that the console is connected and responsive. Whether echoing happens or not can be controlled programmatically.
-The Console also has a prompt that is configurable. It is off by default but can be turned on programatically. The
-prompt cahracter can also be changed by the user.
+The Console also has a prompt that is configurable. It is off by default but can be turned on programmatically. The
+prompt character can also be changed by the user.
###Data structures
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/4e850f28/docs/os/modules/imgmgr/imgmgr.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/imgmgr/imgmgr.md b/docs/os/modules/imgmgr/imgmgr.md
index 4c49593..faa9a57 100644
--- a/docs/os/modules/imgmgr/imgmgr.md
+++ b/docs/os/modules/imgmgr/imgmgr.md
@@ -29,6 +29,5 @@ The functions available in imgmgr are:
| Function | Description |
|---------|-------------|
-| [imgmgr_module_init](imgmgr_module_init.md) | Registers image manager commands with newtmgr. |
| [imgr_ver_parse](imgr_ver_parse.md) | Parses character string containing specified image version number and writes that to given image_version struct. |
| [imgr_ver_str](imgr_ver_str.md) | Takes version string from specified image_version struct and formats it into a printable string. |
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/4e850f28/docs/os/modules/shell/shell.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/shell/shell.md b/docs/os/modules/shell/shell.md
index 208f9fb..ff05c98 100644
--- a/docs/os/modules/shell/shell.md
+++ b/docs/os/modules/shell/shell.md
@@ -1,20 +1,28 @@
# Shell
-The shell is package sitting on top of console, handling 2 jobs: processing console input and implementing
-[newtmgr](../../../newtmgr/overview.md) line protocol over serial line. Shell runs in its own task.
+The shell runs above the console and provides two functionalities:
+
+* Processes console input.
+* Implements the [newtmgr](../../../newtmgr/overview.md) line protocol over serial transport.
+
+The `sys/shell` package implements the shell. The shell uses the OS default event queue
+for shell events and runs in the context of the main task. An application can, optionally,
+specify a dedicated event queue for the shell to use.
###Description
-* Shell's first job is directing incoming commands to other subsystems. It parses the incoming character string
-and splits it into tokens. Then it looks for the subsystem to handle this command based on the first token of input.
+* The shell's first job is to direct incoming commands to other subsystems. It parses the incoming character string
+into tokens and uses the first token to determine the subsystem command handler to call to process the command.
- * Subsystems register their command handlers using `shell_cmd_register()`. When shell calls the command handler, it passes the other tokens as arguments.
+ * Subsystems register their command handlers using the `shell_cmd_register()`
+ function. When shell calls the command handler, it passes the other tokens as arguments.
* A few commands are currently available in the shell - `tasks`, `log`, `echo`, `date` and `prompt`.
-* Shell's second job is doing framing, encoding and decoding newtmgr protocol when it's carried over the console.
-Protocol handler (libs/newtmgr) registers itself using `shell_nlip_input_register()`, and shell calls the registered
-handler for every frame. Outgoing frames for the protocol are sent using `shell_nlip_output()`.
+* The shell's second job is to handle packet framing, encoding, and decoding of newtmgr protocol messages that are
+sent over the console. The Newtmgr serial transport package (`mgmt/newtmgr/transport/newtmgr_shell`)
+calls the `shell_nlip_input_register()` function to register a handler that the shell calls when it
+receives newtmgr request messages.
<br>
@@ -121,8 +129,8 @@ The functions available in this OS feature are:
| Function | Description |
|---------|-------------|
-| [shell_task_init](shell_task_init.md) | Initializes the shell package. This creates a task for shell, and registers few commands on its own. |
| [shell_cmd_register](shell_cmd_register.md) | Registers a handler for incoming console commands. |
| [shell_nlip_input_register](shell_nlip_input_register.md) | Registers a handler for incoming newtmgr messages. |
| [shell_nlip_output](shell_nlip_output.md) | Queue outgoing newtmgr message for transmission. |
+| [shell_evq_set](shell_evq_set.md) | Specifies a dedicated event queue for shell events. |
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/4e850f28/docs/os/modules/shell/shell_evq_set.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/shell/shell_evq_set.md b/docs/os/modules/shell/shell_evq_set.md
new file mode 100644
index 0000000..daa2064
--- /dev/null
+++ b/docs/os/modules/shell/shell_evq_set.md
@@ -0,0 +1,23 @@
+## <font color="F2853F" style="font-size:24pt"> shell_task_init</font>
+
+```c
+void shell_evq_set(struct os_eventq *evq)
+```
+
+Specifies an event queue to use for shell events. You must create the event queue
+and the task to process events from the queue before calling this function.
+
+By default, shell uses the OS default event queue and executes in the context
+of the main task that Mynewt creates.
+
+#### Arguments
+
+| Arguments | Description |
+|-----------|-------------|
+| `evq` | Pointer to the event queue to use for shell events.|
+
+#### Returned values
+None
+
+#### Notes
+
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/4e850f28/docs/os/modules/sysinitconfig/sysinitconfig.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/sysinitconfig/sysinitconfig.md b/docs/os/modules/sysinitconfig/sysinitconfig.md
index dc0a682..c3a639a 100644
--- a/docs/os/modules/sysinitconfig/sysinitconfig.md
+++ b/docs/os/modules/sysinitconfig/sysinitconfig.md
@@ -409,7 +409,7 @@ Your application's `main()` function executes in the context of the main task an
* At the start of `main()`, call the Mynewt `sysinit()` function to initialize
the packages before performing any other processing.
-* At the end of `main()`, wait for and dispatch events from the default event queue in a forever loop.
+* At the end of `main()`, wait for and dispatch events from the default event queue in an infinite loop.
**Note:** You must include the `sysinit/sysinit.h` header file to access the `sysinit()` function.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/4e850f28/mkdocs.yml
----------------------------------------------------------------------
diff --git a/mkdocs.yml b/mkdocs.yml
index a584058..fc43b49 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -68,10 +68,8 @@ pages:
- toc: 'os/os_user_guide.md'
- OS Core:
- 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'
+ - 'Functions':
+ - 'os_started': 'os/core_os/os_started.md'
- Scheduler:
- toc: 'os/core_os/context_switch/context_switch.md'
- 'Functions':
@@ -210,10 +208,10 @@ pages:
- Shell:
- toc: 'os/modules/shell/shell.md'
- 'Functions':
- - 'shell_task_init': 'os/modules/shell/shell_task_init.md'
- 'shell_cmd_register': 'os/modules/shell/shell_cmd_register.md'
- 'shell_nlip_input_register': 'os/modules/shell/shell_nlip_input_register.md'
- 'shell_nlip_output': 'os/modules/shell/shell_nlip_output.md'
+ - 'shell_evq_set' : 'os/modules/shell/shell_evq_set.md'
- Split Images:
- toc: 'os/modules/split/split.md'
- Bootloader:
@@ -318,7 +316,6 @@ pages:
- Image Manager:
- toc: 'os/modules/imgmgr/imgmgr.md'
- 'Functions':
- - 'imgmgr_module_init': 'os/modules/imgmgr/imgmgr_module_init.md'
- 'imgr_ver_parse': 'os/modules/imgmgr/imgr_ver_parse.md'
- 'imgr_ver_str': 'os/modules/imgmgr/imgr_ver_str.md'
- 'Baselibc library': 'os/modules/baselibc.md'
[2/2] incubator-mynewt-site git commit: fixed title of
shell_evq_set.md
Posted by ad...@apache.org.
fixed title of shell_evq_set.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/307f05af
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/307f05af
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/307f05af
Branch: refs/heads/develop
Commit: 307f05af93aecb7ca5f113c77f6a4fbb86bc4e77
Parents: 4e850f2
Author: aditihilbert <ad...@runtime.io>
Authored: Wed Feb 8 07:14:49 2017 -0800
Committer: aditihilbert <ad...@runtime.io>
Committed: Wed Feb 8 07:14:49 2017 -0800
----------------------------------------------------------------------
docs/os/modules/shell/shell_evq_set.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/307f05af/docs/os/modules/shell/shell_evq_set.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/shell/shell_evq_set.md b/docs/os/modules/shell/shell_evq_set.md
index daa2064..b0d9097 100644
--- a/docs/os/modules/shell/shell_evq_set.md
+++ b/docs/os/modules/shell/shell_evq_set.md
@@ -1,4 +1,4 @@
-## <font color="F2853F" style="font-size:24pt"> shell_task_init</font>
+## <font color="F2853F" style="font-size:24pt"> shell_evq_set</font>
```c
void shell_evq_set(struct os_eventq *evq)