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/02/26 18:47:24 UTC
[1/3] incubator-mynewt-site git commit: MYNEWT-146: add task
documentation to core os manual
Repository: incubator-mynewt-site
Updated Branches:
refs/heads/master 287136d06 -> 82f5d63c5
MYNEWT-146: add task documentation to core os manual
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/22c090fb
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/22c090fb
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/22c090fb
Branch: refs/heads/master
Commit: 22c090fb0493913e81fe0459730b564e4a30c8dc
Parents: 0f9e111
Author: wes3 <wi...@micosa.io>
Authored: Thu Feb 25 14:46:35 2016 -0800
Committer: wes3 <wi...@micosa.io>
Committed: Thu Feb 25 14:46:35 2016 -0800
----------------------------------------------------------------------
docs/os/core_os/task/_clear_stack.md | 0
docs/os/core_os/task/os_task_count.md | 28 +++
docs/os/core_os/task/os_task_info_get_next.md | 61 ++++++
docs/os/core_os/task/os_task_init.md | 48 +++++
docs/os/core_os/task/os_task_next_id.md | 0
docs/os/core_os/task/os_task_sanity_checkin.md | 34 +++
docs/os/core_os/task/task.md | 217 +++++++++++++++++++-
7 files changed, 381 insertions(+), 7 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/22c090fb/docs/os/core_os/task/_clear_stack.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/task/_clear_stack.md b/docs/os/core_os/task/_clear_stack.md
deleted file mode 100644
index e69de29..0000000
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/22c090fb/docs/os/core_os/task/os_task_count.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/task/os_task_count.md b/docs/os/core_os/task/os_task_count.md
index e69de29..b3935dc 100644
--- a/docs/os/core_os/task/os_task_count.md
+++ b/docs/os/core_os/task/os_task_count.md
@@ -0,0 +1,28 @@
+## <font color="F2853F" style="font-size:24pt"> os_task_count</font>
+
+```no-highlight
+uint8_t os_task_count(void);
+```
+Returns the number of tasks that have been created.
+
+<br>
+#### Arguments
+
+None
+
+<br>
+#### Returned values
+
+unsigned 8-bit integer representing number of tasks created
+
+<br>
+#### Example
+
+```no-highlight
+
+ uint8_t num_tasks;
+
+ num_tasks = os_task_count();
+```
+
+---------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/22c090fb/docs/os/core_os/task/os_task_info_get_next.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/task/os_task_info_get_next.md b/docs/os/core_os/task/os_task_info_get_next.md
index e69de29..a239829 100644
--- a/docs/os/core_os/task/os_task_info_get_next.md
+++ b/docs/os/core_os/task/os_task_info_get_next.md
@@ -0,0 +1,61 @@
+## <font color="F2853F" style="font-size:24pt"> os_task_info_get_next</font>
+
+```no-highlight
+struct os_task *os_task_info_get_next(const struct os_task *prev, struct os_task_info *oti);
+```
+Populates the os task info structure pointed to by *oti* with task information.
+The task populating the *oti* structure is either the first task on the task
+list if *prev* is NULL, or the next task in the task list (the next pointer of
+*prev*).
+
+If there are no tasks initialized, NULL is returned. Otherwise, the task
+structure used to populate *oti* is returned.
+
+<br>
+#### Arguments
+
+| Arguments | Description |
+|-----------|-------------|
+| prev | Pointer to previous task in task list. If NULL, use first task on list |
+| oti | Pointer to `os_task_info` structure where task information will be stored |
+
+<br>
+#### Returned values
+
+Returns a pointer to the os task structure that was used to populate the task
+information structure. NULL means that no tasks were created.
+
+<br>
+#### Example
+
+```no-highlight
+
+void
+get_task_info(void)
+{
+ struct os_task *prev_task;
+ struct os_task_info oti;
+
+ console_printf("Tasks: \n");
+ prev_task = NULL;
+ while (1) {
+ prev_task = os_task_info_get_next(prev_task, &oti);
+ if (prev_task == NULL) {
+ break;
+ }
+
+ console_printf(" %s (prio: %u, tid: %u, lcheck: %lu, ncheck: %lu, "
+ "flags: 0x%x, ssize: %u, susage: %u, cswcnt: %lu, "
+ "tot_run_time: %lums)\n",
+ oti.oti_name, oti.oti_prio, oti.oti_taskid,
+ (unsigned long)oti.oti_last_checkin,
+ (unsigned long)oti.oti_next_checkin, oti.oti_flags,
+ oti.oti_stksize, oti.oti_stkusage, (unsigned long)oti.oti_cswcnt,
+ (unsigned long)oti.oti_runtime);
+
+ }
+}
+
+```
+
+---------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/22c090fb/docs/os/core_os/task/os_task_init.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/task/os_task_init.md b/docs/os/core_os/task/os_task_init.md
index e69de29..022f050 100644
--- a/docs/os/core_os/task/os_task_init.md
+++ b/docs/os/core_os/task/os_task_init.md
@@ -0,0 +1,48 @@
+## <font color="F2853F" style="font-size:24pt"> os_task_init</font>
+
+```no-highlight
+int os_task_init(struct os_task *t, char *name, os_task_func_t func, void *arg,
+ uint8_t prio, os_time_t sanity_itvl, os_stack_t *stack_bottom,
+ uint16_t stack_size)
+```
+
+Called to create a task. This adds the task object to the list of ready to run
+tasks.
+
+<br>
+#### Arguments
+
+| Arguments | Description |
+|-----------|-------------|
+| t | Pointer to task |
+| name | Task name |
+| func | Task function |
+| arg | Generic argument to pass to task |
+| prio | Priority of task |
+| sanity_itvl | The interval at which the sanity task will check to see if this task is sill alive |
+| stack_bottom | Pointer to bottom of stack. |
+| stack_size | The size of the stack. NOTE: this is not in bytes! It is the number of `os_stack_t` elements allocated (generally 32-bits each) |
+
+<br>
+#### Returned values
+
+OS_OK: task initialization successful.
+
+All other error codes indicate an internal error.
+
+<br>
+#### Example
+
+```no-highlight
+
+ /* Create the task */
+ int rc;
+
+ os_stack_t my_task_stack[MY_STACK_SIZE];
+
+ rc = os_task_init(&my_task, "my_task", my_task_func, NULL, MY_TASK_PRIO,
+ OS_WAIT_FOREVER, my_task_stack, MY_STACK_SIZE);
+ assert(rc == OS_OK);
+```
+
+---------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/22c090fb/docs/os/core_os/task/os_task_next_id.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/task/os_task_next_id.md b/docs/os/core_os/task/os_task_next_id.md
deleted file mode 100644
index e69de29..0000000
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/22c090fb/docs/os/core_os/task/os_task_sanity_checkin.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/task/os_task_sanity_checkin.md b/docs/os/core_os/task/os_task_sanity_checkin.md
index e69de29..1f77a3d 100644
--- a/docs/os/core_os/task/os_task_sanity_checkin.md
+++ b/docs/os/core_os/task/os_task_sanity_checkin.md
@@ -0,0 +1,34 @@
+## <font color="F2853F" style="font-size:24pt"> os_task_sanity_checkin</font>
+
+```no-highlight
+int os_task_sanity_checkin(struct os_task *t)
+```
+Used by a task to check in to the sanity task. This informs the sanity task that
+*task* is still alive and working normally.
+
+<br>
+#### Arguments
+
+| Arguments | Description |
+|-----------|-------------|
+| t | Pointer to task |
+
+<br>
+#### Returned values
+
+OS_OK: sanity check-in successful
+
+All other error codes indicate an error.
+
+<br>
+#### Example
+
+```no-highlight
+ int rc;
+
+ rc = os_task_sanity_checkin(&my_task);
+ assert(rc == OS_OK);
+
+```
+
+---------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/22c090fb/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 cc80328..6a2a591 100644
--- a/docs/os/core_os/task/task.md
+++ b/docs/os/core_os/task/task.md
@@ -1,24 +1,227 @@
# Task
+A task, along with the scheduler, forms the basis of the Mynewt OS. A task
+consists of two basic elements: a task stack and a task function. The task
+function is basically a forever loop, waiting for some "event" to wake it up.
+There are two methods used to signal a task that it has work to do: event queues
+and semaphores (see the appropriate manual sections for descriptions of these
+features).
+
+The Mynewt OS is a multi-tasking, preemptive OS. Every task is assigned a task
+priority (from 0 to 255), with 0 being the highest priority task. If a higher
+priority task than the current task wants to run, the scheduler preempts the
+currently running task and switches context to the higher priority task. This is
+just a fancy way of saying that the processor stack pointer now points to the
+stack of the higher priority task and the task resumes execution where it left
+off.
-Insert synopsis here
-
+Tasks run to completion unless they are preempted by a higher priority task. The
+developer must insure that tasks eventually "sleep"; otherwise lower priority
+tasks will never get a chance to run (actually, any task lower in priority than
+the task that never sleeps). A task will be put to sleep in the following cases:
+it puts itself to sleep using `os_time_delay()`, it waits on an event queue
+which is empty or attempts to obtain a mutex or a semaphore that is currently
+owned by another task.
+
+Note that other sections of the manual describe these OS features in more
+detail.
## Description
-Describe OS feature here
+In order to create a task two data structures need to be defined: the task
+object (struct os_task) and its associated stack. Determining the stack size can
+be a bit tricky; generally developers should not declare large local variables
+on the stack so that task stacks can be of limited size. However, all
+applications are different and the developer must choose the stack size
+accordingly. NOTE: be careful when declaring your stack! The stack is in units
+of `os_stack_t` sized elements (generally 32-bits). Looking at the example given
+below and assuming `os_stack_t` is defined to be a 32-bit unsigned value,
+"my_task_stack" will use 256 bytes.
+
+A task must also have an associated "task function". This is the function that
+will be called when the task is first run. This task function should never
+return!
+
+In order to inform the Mynewt OS of the new task and to have it added to the
+scheduler, the `os_task_init()` function is called. Once `os_task_init()` is
+called, the task is made ready to run and is added to the active task list. Note
+that a task can be initialized (started) before or after the os has started
+(i.e. before `os_start()` is called) but must be initialized after the os has
+been initialized (i.e. 'os_init' has been called). In most of the examples and
+current Mynewt projects, the os is initialized, tasks are initialized, and the
+the os is started. Once the os has started, the highest priority task will be
+the first task set to run.
+
+Information about a task can be obtained using the `os_task_info_get_next()`
+API. Developers can walk the list of tasks to obtain information on all created
+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.
+
+```no-highlight
+/* Create a simple "project" with a task that blinks a LED every second */
+
+/* Define task stack and task object */
+#define MY_TASK_PRI (OS_TASK_PRI_HIGHEST)
+#define MY_STACK_SIZE (64)
+struct os_task my_task;
+os_stack_t my_task_stack[MY_STACK_SIZE];
+
+/* This is the task function */
+void my_task_func(void *arg) {
+ /* Set the led pin as an output */
+ hal_gpio_init_out(LED_BLINK_PIN, 1);
+
+ /* The task is a forever loop that does not return */
+ while (1) {
+ /* Wait one second */
+ os_time_delay(1000);
+
+ /* Toggle the LED */
+ hal_gpio_toggle(LED_BLINK_PIN);
+ }
+}
+
+/* This is the main function for the project */
+int main(void) {
+ int rc;
+
+ /* Initialize OS */
+ os_init();
+
+ /* 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;
+}
+```
## Data structures
-Replace this with the list of data structures used, why, any neat features
+```no-highlight
+/* The highest and lowest task priorities */
+#define OS_TASK_PRI_HIGHEST (0)
+#define OS_TASK_PRI_LOWEST (0xff)
+
+/* Task states */
+typedef enum os_task_state {
+ OS_TASK_READY = 1,
+ OS_TASK_SLEEP = 2
+} os_task_state_t;
+
+/* Task flags */
+#define OS_TASK_FLAG_NO_TIMEOUT (0x0001U)
+#define OS_TASK_FLAG_SEM_WAIT (0x0002U)
+#define OS_TASK_FLAG_MUTEX_WAIT (0x0004U)
+
+typedef void (*os_task_func_t)(void *);
+
+#define OS_TASK_MAX_NAME_LEN (32)
+```
+<br>
+```no-highlight
+struct os_task {
+ os_stack_t *t_stackptr;
+ os_stack_t *t_stacktop;
+ uint16_t t_stacksize;
+ uint16_t t_flags;
+
+ uint8_t t_taskid;
+ uint8_t t_prio;
+ uint8_t t_state;
+ uint8_t t_pad;
+
+ char *t_name;
+ os_task_func_t t_func;
+ void *t_arg;
+
+ void *t_obj;
+
+ struct os_sanity_check t_sanity_check;
+
+ os_time_t t_next_wakeup;
+ os_time_t t_run_time;
+ uint32_t t_ctx_sw_cnt;
+
+ /* Global list of all tasks, irrespective of run or sleep lists */
+ STAILQ_ENTRY(os_task) t_os_task_list;
+
+ /* Used to chain task to either the run or sleep list */
+ TAILQ_ENTRY(os_task) t_os_list;
+
+ /* Used to chain task to an object such as a semaphore or mutex */
+ SLIST_ENTRY(os_task) t_obj_list;
+};
+```
+
+| **Element** | **Description** |
+|-----------|-------------|
+| t_stackptr | Current stack pointer |
+| t_stacktop | The address of the top of the task stack. The stack grows downward |
+| t_stacksize | The size of the stack, in units of os_stack_t (not bytes!) |
+| t_flags | Task flags (see flag definitions) |
+| t_taskid | A numeric id assigned to each task |
+| t_prio | The priority of the task. The lower the number, the higher the priority |
+| t_state | The task state (see state definitions) |
+| t_pad | padding (for alignment) |
+| t_name | Name of task |
+| t_func | Pointer to task function |
+| t_obj | Generic object used by mutexes and semaphores when the task is waiting on a mutex or semaphore
+| t_sanity_check | Sanity task data structure |
+| t_next_wakeup | OS time when task is next scheduled to wake up |
+| t_run_time | The amount of os time ticks this task has been running |
+| t_ctx_sw_cnt | The number of times that this task has been run |
+| t_os_task_list | List pointer for global task list. All tasks are placed on this list |
+| t_os_list | List pointer used by either the active task list or the sleeping task list |
+| t_obj_list | List pointer for tasks waiting on a semaphore or mutex |
+
+<br>
+```no-highlight
+struct os_task_info {
+ uint8_t oti_prio;
+ uint8_t oti_taskid;
+ uint8_t oti_state;
+ uint8_t oti_flags;
+ uint16_t oti_stkusage;
+ uint16_t oti_stksize;
+ uint32_t oti_cswcnt;
+ uint32_t oti_runtime;
+ os_time_t oti_last_checkin;
+ os_time_t oti_next_checkin;
+
+ char oti_name[OS_TASK_MAX_NAME_LEN];
+};
+```
+
+| **Element** | **Description** |
+|-----------|-------------|
+| oti_prio | Task priority |
+| oti_taskid | Task id |
+| oti_state | Task state |
+| oti_flags | Task flags |
+| oti_stkusage | Amount of stack used by the task (in os_stack_t units) |
+| oti_stksize | The size of the stack (in os_stack_t units) |
+| oti_cswcnt | The context switch count |
+| oti_runtime | The amount of time that the task has run (in os time ticks) |
+| oti_last_checkin | The time (os time) at which this task last checked in to the sanity task |
+| oti_next_checkin | The time (os time) at which this task last checked in to the sanity task |
+| oti_name | Name of the task |
+
+<br>
## List of Functions
The functions available in task are:
-* [_clear_stack](_clear_stack.md)
+* [os_task_init](os_task_init.md)
* [os_task_count](os_task_count.md)
* [os_task_info_get_next](os_task_info_get_next.md)
-* [os_task_init](os_task_init.md)
-* [os_task_next_id](os_task_next_id.md)
* [os_task_sanity_checkin](os_task_sanity_checkin.md)
[3/3] incubator-mynewt-site git commit: Updating for pull request#9
OS_tasks removed unnecessary pages in mkdocs.yml
Posted by ad...@apache.org.
Updating for pull request#9 OS_tasks removed unnecessary pages in mkdocs.yml
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/82f5d63c
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/82f5d63c
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/82f5d63c
Branch: refs/heads/master
Commit: 82f5d63c50f9135b445dda2e266deb709512cd30
Parents: b9c5cad
Author: aditihilbert <ad...@runtime.io>
Authored: Fri Feb 26 09:42:32 2016 -0800
Committer: aditihilbert <ad...@runtime.io>
Committed: Fri Feb 26 09:42:32 2016 -0800
----------------------------------------------------------------------
docs/os/get_started/vocabulary.md | 2 +-
mkdocs.yml | 2 --
2 files changed, 1 insertion(+), 3 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/82f5d63c/docs/os/get_started/vocabulary.md
----------------------------------------------------------------------
diff --git a/docs/os/get_started/vocabulary.md b/docs/os/get_started/vocabulary.md
index fad8199..127531f 100644
--- a/docs/os/get_started/vocabulary.md
+++ b/docs/os/get_started/vocabulary.md
@@ -1,4 +1,4 @@
-## Understanding Newt Terms
+## Glossary
### Application repository or app
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/82f5d63c/mkdocs.yml
----------------------------------------------------------------------
diff --git a/mkdocs.yml b/mkdocs.yml
index 71fa39d..dd291b9 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -48,11 +48,9 @@ pages:
- Tasks:
- 'Overview': 'os/core_os/task/task.md'
- 'Functions':
- - '_clear_stack': 'os/core_os/task/_clear_stack.md'
- 'os_task_count': 'os/core_os/task/os_task_count.md'
- 'os_task_info_get_next': 'os/core_os/task/os_task_info_get_next.md'
- 'os_task_init': 'os/core_os/task/os_task_init.md'
- - 'os_task_next_id': 'os/core_os/task/os_task_next_id.md'
- 'os_task_sanity_checkin': 'os/core_os/task/os_task_sanity_checkin.md'
- Event Queues:
- 'Overview': 'os/core_os/event_queue/event_queue.md'
[2/3] incubator-mynewt-site git commit: Merge branch 'os_tasks' of
https://github.com/apache/incubator-mynewt-site
Posted by ad...@apache.org.
Merge branch 'os_tasks' of https://github.com/apache/incubator-mynewt-site
This closes #9
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/b9c5cad9
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/b9c5cad9
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/b9c5cad9
Branch: refs/heads/master
Commit: b9c5cad9d8145ee3b9ba2dab5834ad223ed4690a
Parents: 287136d 22c090f
Author: aditihilbert <ad...@runtime.io>
Authored: Thu Feb 25 15:05:03 2016 -0800
Committer: aditihilbert <ad...@runtime.io>
Committed: Fri Feb 26 09:36:45 2016 -0800
----------------------------------------------------------------------
docs/os/core_os/task/_clear_stack.md | 0
docs/os/core_os/task/os_task_count.md | 28 +++
docs/os/core_os/task/os_task_info_get_next.md | 61 ++++++
docs/os/core_os/task/os_task_init.md | 48 +++++
docs/os/core_os/task/os_task_next_id.md | 0
docs/os/core_os/task/os_task_sanity_checkin.md | 34 +++
docs/os/core_os/task/task.md | 217 +++++++++++++++++++-
7 files changed, 381 insertions(+), 7 deletions(-)
----------------------------------------------------------------------