Google Git
Sign in
apache / mynewt-site / 8528acea806ecedcedbaec90568a1524b3ae623d / . / v1_0_0 / os / core_os / mynewt_os / index.html
blob: 1c2de2f16c20d6166394017f54437c12532d6cdc [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<!-- This is broken by doc revisioning.
-->
<link rel="shortcut icon" href="../../../img/favicon.ico">
<title>toc - Apache Mynewt</title>
<link href="../../../css/bootstrap-3.0.3.min.css" rel="stylesheet">
<link rel="stylesheet" href="../../../css/highlight.css">
<link href="../../../css/base.css" rel="stylesheet">
<link href="../../../css/custom.css" rel="stylesheet">
<link href="../../../css/v2.css" rel="stylesheet">
<link href="https://fonts.googleapis.com/css?family=Lato" rel="stylesheet">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css">
<!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
<script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
<![endif]-->
<script>
(function(i, s, o, g, r, a, m) {
i["GoogleAnalyticsObject"] = r;
(i[r] =
i[r] ||
function() {
(i[r].q = i[r].q || []).push(arguments);
}),
(i[r].l = 1 * new Date());
(a = s.createElement(o)), (m = s.getElementsByTagName(o)[0]);
a.async = 1;
a.src = g;
m.parentNode.insertBefore(a, m);
})(window, document, "script", "//www.google-analytics.com/analytics.js", "ga");
ga("create", "UA-72162311-1", "auto");
ga("send", "pageview");
</script>
</head>
<body class="toc">
<div class="container">
<div class="row v2-main-banner">
<a class="logo-cell" href="/">
<img class="logo" src="/img/logo.png">
</a>
<div class="tagline-cell">
<h4 class="tagline">An OS to build, deploy and securely manage billions of devices</h4>
</div>
<div class="news-cell">
<div class="well">
<h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.11.0, Apache NimBLE 1.6.0 </a> released (September 7, 2023)
</div>
</div>
</div>
</div>
<nav id="navbar" class="navbar navbar-inverse affix-top" data-spy="affix" data-offset-top="150" role="navigation">
<div class="container">
<!-- Collapsed navigation -->
<div class="navbar-header">
<!-- Expander button -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
</div>
<!-- Expanded navigation -->
<div class="navbar-collapse collapse">
<!-- Main navigation -->
<ul class="nav navbar-nav navbar-right">
<li
class=""
>
<a href="/"><i class="fa fa-home" style="font-size: larger;"></i></a>
</li>
<li
class="important"
>
<a href="/quick-start/">Quick Start</a>
</li>
<li
class=""
>
<a href="/about/">About</a>
</li>
<li
class=""
>
<a href="/talks/">Talks</a>
</li>
<li
class="active"
>
<a href="/documentation/">Documentation</a>
</li>
<li
class=""
>
<a href="/download/">Download</a>
</li>
<li
class=""
>
<a href="/community/">Community</a>
</li>
<li
class=""
>
<a href="/events/">Events</a>
</li>
</ul>
</div>
</div>
</nav>
<div class="container">
<div class="row">
<div class="col-md-3 v2-sidebar sidebar-container"><div id="docSidebar" class="hidden-print" role="complementary">
<div class="top">
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../../../search.html" method="get">
<div class="form-group">
<input type="text" name="q" class="form-control" placeholder="Search documentation" />
</div>
</form>
</div>
</div>
<ul class="toc-nav">
<li class="doc-version"><select class="form-control" onchange="if (this.value) window.location.href=this.value">
<option value="/latest">
Version: master
</option>
<option value="/v1_11_0/" >
Version: 1.11.0
</option>
<option value="/v1_10_0/" >
Version: 1.10.0
</option>
<option value="/v1_9_0/" >
Version: 1.9.0
</option>
<option value="/v1_8_0/" >
Version: 1.8.0
</option>
<option value="/v1_7_0/" >
Version: 1.7.0
</option>
<option value="/v1_6_0/" >
Version: 1.6.0
</option>
<option value="/v1_5_0/" >
Version: 1.5.0
</option>
<option value="/v1_4_0/" >
Version: 1.4.0
</option>
<option value="/v1_3_0/os/introduction" >
Version: 1.3.0
</option>
<option value="/v1_2_0/os/introduction" >
Version: 1.2.0
</option>
<option value="/v1_1_0/os/introduction" >
Version: 1.1.0
</option>
<option value="/v1_0_0/os/introduction" selected="selected" >
Version: 1.0.0
</option>
<option value="/v0_9_0/os/introduction" >
Version: 0.9.0
</option>
</select></li>
<li ><a href="../../introduction/">Mynewt Documentation</a>
<ul>
<li ><a href="../../get_started/get_started/">Basic Setup</a>
</li>
<li >
<a href="../../get_started/vocabulary/">Concepts</a>
</li>
<li ><a href="../../tutorials/tutorials/">Tutorials</a>
</li>
<li ><a href="../../os_user_guide/">OS User Guide</a>
<ul>
<li class="active"><a href="./">OS Core</a>
<ul>
<li><a href="
../os_started/
">Functions</a>
</li>
<li ><a href="../context_switch/context_switch/">Scheduler</a>
</li>
<li ><a href="../cputime/os_cputime/">CPU Time</a>
</li>
<li ><a href="../time/os_time/">OS Time</a>
</li>
<li ><a href="../task/task/">Tasks</a>
</li>
<li ><a href="../event_queue/event_queue/">Event Queues</a>
</li>
<li ><a href="../semaphore/semaphore/">Semaphores</a>
</li>
<li ><a href="../mutex/mutex/">Mutexes</a>
</li>
<li ><a href="../memory_pool/memory_pool/">Memory Pools</a>
</li>
<li ><a href="../heap/heap/">Heap</a>
</li>
<li><a href="
../mbuf/mbuf/
">Memory Buffers</a>
</li>
<li ><a href="../sanity/sanity/">Sanity</a>
</li>
<li ><a href="../callout/callout/">Callouts</a>
</li>
</ul>
</li>
<li ><a href="../porting/port_os/">Porting to your Platform</a>
</li>
<li ><a href="../../modules/console/console/">Console</a>
</li>
<li ><a href="../../modules/shell/shell/">Shell</a>
</li>
<li ><a href="../../modules/split/split/">Split Images</a>
</li>
<li ><a href="../../modules/bootloader/bootloader/">Bootloader</a>
</li>
<li><a href="
../../modules/fs/fs/fs/
">File System</a>
</li>
<li ><a href="../../modules/hal/hal/">Hardware Abstraction Layer</a>
</li>
<li ><a href="../../modules/drivers/driver/">Drivers</a>
</li>
<li ><a href="../../modules/testutil/testutil/">Test Utilities</a>
</li>
<li ><a href="../../modules/devmgmt/newtmgr/">Device Management with Newt Manager</a>
</li>
<li ><a href="../../modules/imgmgr/imgmgr/">Image Manager</a>
</li>
<li >
<a href="../../modules/baselibc/">Baselibc library</a>
</li>
<li ><a href="../../modules/json/json/">JSON</a>
</li>
<li ><a href="../../modules/fcb/fcb/">Flash Circular Buffer</a>
</li>
<li ><a href="../../modules/stats/stats/">Stats</a>
</li>
<li ><a href="../../modules/logs/logs/">Logs</a>
</li>
<li ><a href="../../modules/sysinitconfig/sysinitconfig/">System Configuration And Initialization</a>
</li>
</ul>
</li>
<li><a href="
../../../network/ble/ble_intro/
">BLE User Guide</a>
</li>
<li ><a href="../../../newt/newt_intro/">Newt Tool Guide</a>
</li>
<li ><a href="../../../newtmgr/overview/">Newt Manager Guide</a>
</li>
<li >
<a href="../../../known_issues/">Known Issues</a>
</li>
</ul>
</li>
<li><a href="
../../../faq/go_env/
">Appendix</a>
</li>
</ul>
</div></div>
<div class="col-md-9" role="main">
<div class="doc-header">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="/documentation/">Docs</a></li>
<li>&raquo; OS Core</li>
<li>&raquo; <a href="os/os_user_guide/">OS User Guide</a></li>
<li>&raquo; <a href="os/introduction/">Mynewt Documentation</a></li>
</ul>
</div>
</div>
<div class="alert alert-warning">
<p>
Version 1.0.0 is not the most recent version of the Apache Mynewt
documentation. Click <a href="/latest">here</a> to read the latest
version.
</p>
</div>
<h1 id="mynewt-core-os">Mynewt Core OS</h1>
<p>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.</p>
<p>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.</p>
<h3 id="why-use-an-os">Why use an OS?</h3>
<p>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. </p>
<h3 id="core-os-features">Core OS Features</h3>
<p><Insert basic feature descriptions, how the various pieces fit together etc., what's special in Mynewt OS></p>
<ul>
<li><a href="../context_switch/context_switch/">Scheduler/context switching</a></li>
<li><a href="../time/os_time/">Time</a></li>
<li><a href="../task/task/">Tasks</a></li>
<li><a href="../event_queue/event_queue/">Event queues/callouts</a></li>
<li><a href="../semaphore/semaphore/">Semaphores</a></li>
<li><a href="../mutex/mutex/">Mutexes</a></li>
<li><a href="../memory_pool/memory_pool/">Memory pools</a></li>
<li><a href="../heap/heap/">Heap</a></li>
<li><a href="../mbuf/mbuf/">Mbufs</a></li>
<li><a href="../sanity/sanity/">Sanity</a></li>
<li><a href="../callout/callout/">Callouts</a></li>
<li><a href="../porting/port_os/">Porting OS to other platforms</a></li>
</ul>
<h3 id="basic-os-application-creation">Basic OS Application Creation</h3>
<p>Creating an application using the Mynewt Core OS is a relatively simple task. The main steps are:</p>
<ol>
<li>Install the basic Newt Tool structure (build structure) for your application.</li>
<li>Create your BSP (Board Support Package).</li>
<li>In your application <code>main()</code> function, call the <code>sysinit()</code> 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 <a href="/os/modules//sysinitconfig/sysinitconfig.md">System Configuration and Initialization</a> for more details.) </li>
</ol>
<p>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. </p>
<p>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.</p>
<p>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.</p>
<h3 id="example">Example</h3>
<p>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.</p>
<p>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 <code>os_task_init()</code>). </p>
<p>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 <code>os_sem_init()</code> for task2_sem inside <code>task2_handler()</code>, task 1 would have called <code>os_sem_pend()</code> using task2_sem before task2_sem was initialized.</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code> <span style="color: #A90D91">struct</span> <span style="color: #3F6E75">os_sem</span> <span style="color: #000000">task1_sem</span>;
<span style="color: #A90D91">struct</span> <span style="color: #3F6E75">os_sem</span> <span style="color: #000000">task2_sem</span>;
<span style="color: #177500">/* Task 1 handler function */</span>
<span style="color: #A90D91">void</span>
<span style="color: #000000">task1_handler</span>(<span style="color: #A90D91">void</span> <span style="color: #000000">*arg</span>)
{
<span style="color: #A90D91">while</span> (<span style="color: #1C01CE">1</span>) {
<span style="color: #177500">/* Release semaphore to task 2 */</span>
<span style="color: #000000">os_sem_release</span>(<span style="color: #000000">&amp;task1_sem</span>);
<span style="color: #177500">/* Wait for semaphore from task 2 */</span>
<span style="color: #000000">os_sem_pend</span>(<span style="color: #000000">&amp;task2_sem</span>, <span style="color: #000000">OS_TIMEOUT_NEVER</span>);
}
}
<span style="color: #177500">/* Task 2 handler function */</span>
<span style="color: #A90D91">void</span>
<span style="color: #000000">task2_handler</span>(<span style="color: #A90D91">void</span> <span style="color: #000000">*arg</span>)
{
<span style="color: #A90D91">struct</span> <span style="color: #3F6E75">os_task</span> <span style="color: #000000">*t</span>;
<span style="color: #A90D91">while</span> (<span style="color: #1C01CE">1</span>) {
<span style="color: #177500">/* Wait for semaphore from task1 */</span>
<span style="color: #000000">os_sem_pend</span>(<span style="color: #000000">&amp;task1_sem</span>, <span style="color: #000000">OS_TIMEOUT_NEVER</span>);
<span style="color: #177500">/* Release task2 semaphore */</span>
<span style="color: #000000">os_sem_release</span>(<span style="color: #000000">&amp;task2_sem</span>);
}
}
<span style="color: #177500">/* Initialize task 1 exposed data objects */</span>
<span style="color: #A90D91">void</span>
<span style="color: #000000">task1_init</span>(<span style="color: #A90D91">void</span>)
{
<span style="color: #177500">/* Initialize task1 semaphore */</span>
<span style="color: #000000">os_sem_init</span>(<span style="color: #000000">&amp;task1_sem</span>, <span style="color: #1C01CE">0</span>);
}
<span style="color: #177500">/* Initialize task 2 exposed data objects */</span>
<span style="color: #A90D91">void</span>
<span style="color: #000000">task2_init</span>(<span style="color: #A90D91">void</span>)
{
<span style="color: #177500">/* Initialize task1 semaphore */</span>
<span style="color: #000000">os_sem_init</span>(<span style="color: #000000">&amp;task2_sem</span>, <span style="color: #1C01CE">0</span>);
}
<span style="color: #177500">/**</span>
<span style="color: #177500"> * init_app_tasks</span>
<span style="color: #177500"> * </span>
<span style="color: #177500"> * This function performs initializations that are required before tasks run. </span>
<span style="color: #177500"> * </span>
<span style="color: #177500"> * @return int 0 success; error otherwise.</span>
<span style="color: #177500"> */</span>
<span style="color: #A90D91">static</span> <span style="color: #A90D91">int</span>
<span style="color: #000000">init_app_tasks</span>(<span style="color: #A90D91">void</span>)
{
<span style="color: #177500">/* </span>
<span style="color: #177500"> * Call task specific initialization functions to initialize any shared objects </span>
<span style="color: #177500"> * before initializing the tasks with the OS.</span>
<span style="color: #177500"> */</span>
<span style="color: #000000">task1_init</span>();
<span style="color: #000000">task2_init</span>();
<span style="color: #177500">/*</span>
<span style="color: #177500"> * Initialize tasks 1 and 2 with the OS. </span>
<span style="color: #177500"> */</span>
<span style="color: #000000">os_task_init</span>(<span style="color: #000000">&amp;task1</span>, <span style="color: #C41A16">&quot;task1&quot;</span>, <span style="color: #000000">task1_handler</span>, <span style="color: #A90D91">NULL</span>, <span style="color: #000000">TASK1_PRIO</span>,
<span style="color: #000000">OS_WAIT_FOREVER</span>, <span style="color: #000000">task1_stack</span>, <span style="color: #000000">TASK1_STACK_SIZE</span>);
<span style="color: #000000">os_task_init</span>(<span style="color: #000000">&amp;task2</span>, <span style="color: #C41A16">&quot;task2&quot;</span>, <span style="color: #000000">task2_handler</span>, <span style="color: #A90D91">NULL</span>, <span style="color: #000000">TASK2_PRIO</span>,
<span style="color: #000000">OS_WAIT_FOREVER</span>, <span style="color: #000000">task2_stack</span>, <span style="color: #000000">TASK2_STACK_SIZE</span>);
<span style="color: #A90D91">return</span> <span style="color: #1C01CE">0</span>;
}
<span style="color: #177500">/**</span>
<span style="color: #177500"> * main</span>
<span style="color: #177500"> * </span>
<span style="color: #177500"> * The main function for the application. This function initializes the system and packages, </span>
<span style="color: #177500"> * calls the application specific task initialization function, then waits and dispatches </span>
<span style="color: #177500"> * events from the OS default event queue in an infinite loop. </span>
<span style="color: #177500"> */</span>
<span style="color: #A90D91">int</span>
<span style="color: #000000">main</span>(<span style="color: #A90D91">int</span> <span style="color: #000000">argc</span>, <span style="color: #A90D91">char</span> <span style="color: #000000">**arg</span>)
{
<span style="color: #177500">/* Perform system and package initialization */</span>
<span style="color: #000000">sysinit</span>();
<span style="color: #177500">/* Initialize application specific tasks */</span>
<span style="color: #000000">init_app_tasks</span>();
<span style="color: #A90D91">while</span> (<span style="color: #1C01CE">1</span>) {
<span style="color: #000000">os_eventq_run</span>(<span style="color: #000000">os_eventq_dflt_get</span>());
}
<span style="color: #177500">/* main never returns */</span>
}
</code></pre></div>
<h3 id="os-functions">OS Functions</h3>
<p>The functions available at the OS level are:</p>
<ul>
<li><a href="../os_started/">os_started</a></li>
</ul>
<div class="row">
<ul class="nav nav-pills" style="margin-bottom: 10px">
<li>
</li>
<li class="pull-right">
</li>
</ul>
</div>
<footer class="row">
<div class="col-xs-12">
<p class="copyright">Apache Mynewt (incubating) is available under Apache License, version 2.0.</p>
</div>
<div class="col-xs-12">
<div class="logos">
<a href="https://www.apache.org/">
<img src="/img/asf_logo_wide_small.png" alt="Apache" title="Apache">
</a>
<p>
Copyright © 2015-2021 The Apache Software Foundation.<br>
<small class="footnote">
Apache Mynewt, Mynewt, Apache, the Apache feather logo, and the Apache Mynewt
project logo are either registered trademarks or trademarks of the Apache
Software Foundation in the United States and other countries.
</small>
</p>
<a href="">
<img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" />
</a>
</div>
</div>
<a href="https://www.apache.org/licenses/">
<button class="button-footer-asf">
License
</button>
</a>
<a href="https://www.apache.org/foundation/sponsorship.html">
<button class="button-footer-asf">
Sponsorship
</button>
</a>
<a href="https://www.apache.org/foundation/thanks.html">
<button class="button-footer-asf">
Thanks
</button>
</a>
<a href="https://www.apache.org/security/">
<button class="button-footer-asf">
Security
</button>
</a>
<a href="https://apache.org/events/current-event">
<button class="button-footer-asf">
ASF Events
</button>
</a>
</footer>
</div>
</div>
</div>
<script src="../../../js/jquery-1.10.2.min.js"></script>
<script src="../../../js/bootstrap-3.0.3.min.js"></script>
<script src="../../../js/highlight.pack.js"></script>
<script src="../../../js/base.js"></script>
<script src="../../../js/custom.js"></script>
<script src="search/main.js"></script>
</body>
</html>