Apache Mynewt Operating System Kernel
======================================

.. toctree::
   :hidden:

   context_switch/context_switch
   task/task
   mutex/mutex
   semaphore/semaphore
   event_queue/event_queue
   callout/callout
   heap/heap
   memory_pool/memory_pool
   mbuf/mbuf
   cputime/os_cputime
   time/os_time
   sanity/sanity

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 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 provides features that the developer would otherwise need to
create on his/her own.

Core OS Features
~~~~~~~~~~~~~~~~

-  :doc:`Scheduler/context switching <context_switch/context_switch>`
-  :doc:`Time <time/os_time>`
-  :doc:`Tasks <task/task>`
-  :doc:`Event queues/callouts <event_queue/event_queue>`
-  :doc:`Semaphores <semaphore/semaphore>`
-  :doc:`Mutexes <mutex/mutex>`
-  :doc:`Memory pools <memory_pool/memory_pool>`
-  :doc:`Heap <heap/heap>`
-  :doc:`Mbufs <mbuf/mbuf>`
-  :doc:`Sanity <sanity/sanity>`
-  :doc:`Callouts <callout/callout>`
-  :doc:`Porting OS to other platforms <porting/port_os>`

Basic OS Application Creation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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 :doc:`../modules/sysinitconfig/sysinitconfig`
   for more details.)

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
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 :c:func:`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 :c:func:`os_sem_init()` for task2_sem inside
task2_handler(), task 1 would have called :c:func:`os_sem_pend()` using
task2_sem before task2_sem was initialized.

.. code:: c

        struct os_sem task1_sem;
        struct os_sem task2_sem;

        /* Task 1 handler function */
        void
        task1_handler(void *arg)
        {
            while (1) {
                /* Release semaphore to task 2 */
                os_sem_release(&task1_sem);

                /* Wait for semaphore from task 2 */
                os_sem_pend(&task2_sem, OS_TIMEOUT_NEVER);
            }
        }

        /* Task 2 handler function */
        void
        task2_handler(void *arg)
        {
            struct os_task *t;

            while (1) {
                /* Wait for semaphore from task1 */
                os_sem_pend(&task1_sem, OS_TIMEOUT_NEVER);

                /* Release task2 semaphore */
                os_sem_release(&task2_sem);
            }
        }


        /* Initialize task 1 exposed data objects */
        void
        task1_init(void)
        {
            /* Initialize task1 semaphore */
            os_sem_init(&task1_sem, 0);
        }

        /* Initialize task 2 exposed data objects */
        void
        task2_init(void)
        {
            /* Initialize task1 semaphore */
            os_sem_init(&task2_sem, 0);
        }

        /**
         * init_app_tasks
         *
         * 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 with the OS.
             */
            os_task_init(&task1, "task1", task1_handler, NULL, TASK1_PRIO,
                         OS_WAIT_FOREVER, task1_stack, TASK1_STACK_SIZE);

            os_task_init(&task2, "task2", task2_handler, NULL, TASK2_PRIO,
                         OS_WAIT_FOREVER, task2_stack, TASK2_STACK_SIZE);

            return 0;
        }

        /**
         * main
         *
         * 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(int argc, char **arg)
        {

            /* Perform system and package initialization */
            sysinit();

            /* Initialize application specific tasks */
            init_app_tasks();

            while (1) {
               os_eventq_run(os_eventq_dflt_get());
            }
            /* main never returns */
    }