mynewt-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ad...@apache.org
Subject [5/8] incubator-mynewt-site git commit: Added system config and init documentation. Updated mqueue documentation.
Date Sat, 07 Jan 2017 00:31:51 GMT
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/90eef887/develop/os/modules/sysinitconfig/sysinitconfig/index.html
----------------------------------------------------------------------
diff --git a/develop/os/modules/sysinitconfig/sysinitconfig/index.html b/develop/os/modules/sysinitconfig/sysinitconfig/index.html
new file mode 100644
index 0000000..e09de65
--- /dev/null
+++ b/develop/os/modules/sysinitconfig/sysinitconfig/index.html
@@ -0,0 +1,1018 @@
+<!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="canonical" href="http://mynewt.apache.org/os/modules/sysinitconfig/sysinitconfig/">
-->
+        <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">
+        <link href="../../../../extra.css" rel="stylesheet">
+
+        <!-- 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.0.0-b1</a> released (Dec 13, 2016)
+            </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="/latest/os/introduction">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>
+
+            <!-- Search, Navigation and Repo links -->
+            <ul class="nav navbar-nav navbar-right">
+                
+            </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="/develop/os/introduction"
+      selected="selected"
+    >
+      Version: develop (latest)
+    </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 ><a href="../../../core_os/mynewt_os/">OS Core</a>
+  
+  
+    </li>
+
+              
+          
+              
+                
+  
+  
+    <li ><a href="../../../core_os/porting/port_os/">Porting to your Platform</a>
+  
+  
+    </li>
+
+              
+          
+              
+                
+  
+  
+    <li ><a href="../../console/console/">Console</a>
+  
+  
+    </li>
+
+              
+          
+              
+                
+  
+  
+    <li ><a href="../../shell/shell/">Shell</a>
+  
+  
+    </li>
+
+              
+          
+              
+                
+  
+  
+    <li ><a href="../../split/split/">Split Images</a>
+  
+  
+    </li>
+
+              
+          
+              
+                
+  
+  
+    <li ><a href="../../bootloader/bootloader/">Bootloader</a>
+  
+  
+    </li>
+
+              
+          
+              
+                
+  
+  
+    <li><a href="
+  
+  
+  ../../fs/fs/fs/
+
+">File System</a>
+  
+  
+    </li>
+
+              
+          
+              
+                
+  
+  
+    <li ><a href="../../hal/hal/">Hardware Abstraction Layer</a>
+  
+  
+    </li>
+
+              
+          
+              
+                
+  
+  
+    <li ><a href="../../drivers/driver/">Drivers</a>
+  
+  
+    </li>
+
+              
+          
+              
+                
+  
+  
+    <li ><a href="../../testutil/testutil/">Test Utilities</a>
+  
+  
+    </li>
+
+              
+          
+              
+                
+  
+  
+    <li ><a href="../../devmgmt/newtmgr/">Device Management with Newt Manager</a>
+  
+  
+    </li>
+
+              
+          
+              
+                
+  
+  
+    <li ><a href="../../imgmgr/imgmgr/">Image Manager</a>
+  
+  
+    </li>
+
+              
+          
+              
+                
+    <li >
+      <a href="../../baselibc/">Baselibc library</a>
+    </li>
+
+              
+          
+              
+                
+  
+  
+    <li ><a href="../../elua/elua/">Embedded Lua</a>
+  
+  
+    </li>
+
+              
+          
+              
+                
+  
+  
+    <li ><a href="../../json/json/">JSON</a>
+  
+  
+    </li>
+
+              
+          
+              
+                
+  
+  
+    <li ><a href="../../fcb/fcb/">Flash Circular Buffer</a>
+  
+  
+    </li>
+
+              
+          
+              
+                
+  
+  
+    <li ><a href="../../stats/stats/">Stats</a>
+  
+  
+    </li>
+
+              
+          
+              
+                
+  
+  
+    <li ><a href="../../logs/logs/">Logs</a>
+  
+  
+    </li>
+
+              
+          
+              
+                
+  
+  
+    <li class="active"><a href="./">System Configuration And Initialization</a>
+  
+  
+    <ul>
+          
+              
+          
+    </ul>
+  
+    </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>
+
+              
+          
+    </ul>
+  
+    </li>
+
+        
+      
+        
+          
+  
+  
+    <li><a href="
+  ../../../../faq/how_to_edit_docs/
+">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 pull-right">
+    <li><a href="/develop/os/introduction">Docs</a></li>
+    
+    
+        
+          <li>&raquo; <a href="../../../os_user_guide/">OS User Guide</a></li>
+        
+      
+        
+          <li>&raquo; System Configuration And Initialization</li>
+        
+      
+      
+    
+    
+  </ul>
+</div>
+                        </div>
+                        
+                            <h1 id="system-configuration-and-initialization">System
Configuration and Initialization</h1>
+<p>This guide describes how Mynewt manages system configuration and initialization.
It shows you how to 
+tell Mynewt to use default or customized values to initialize packages that you develop or
use to build a target. This guide:</p>
+<ul>
+<li>Assumes you have read the <a href="../../../get_started/vocabulary/">Concepts</a>
section that describes the Mynewt 
+package hierarchy and its use of the <code>pkg.yml</code> and <code>syscfg.yml</code>
files.   </li>
+<li>Assumes you have read the <a href="../../../../newt/newt_operation/">Newt
Tool Theory of Operation</a> and are familiar with how newt determines 
+package dependencies for your target build.</li>
+<li>Covers only the system initialization for hardware independent packages. It does
not cover the Board Support Package (BSP) and other hardware dependent system initialization.
 </li>
+</ul>
+<p>Mynewt defines several configuration parameters in the <code>pkg.yml</code>
and <code>syscfg.yml</code> files. The newt tool uses this information to: </p>
+<ul>
+<li>Generate a system initialization function that calls all the package-specific system
initialization functions. </li>
+<li>Generate a system configuration header file that contains all the package configuration
settings and values.</li>
+<li>Display the system configuration settings and values in the <code>newt target
config</code> command.</li>
+</ul>
+<p>The benefits with this approach include:</p>
+<ul>
+<li>Allows Mynewt developers to reuse other packages and easily change their configuration
settings without updating source or header files when implementing new packages.</li>
+<li>Allows application developers to easily view the system configuration settings
and values and determine the values to override for a target build.</li>
+</ul>
+<p><br></p>
+<h3 id="system-configuration-setting-definitions-and-values">System Configuration Setting
Definitions and Values</h3>
+<p>A package can optionally:</p>
+<ul>
+<li>Define and expose the system configuration settings to allow other packages to
override 
+the default setting values. </li>
+<li>Override the system configuration setting values defined by the packages that it
depends on. </li>
+</ul>
+<p>You use the <code>defs</code> parameter in a <code>syscfg.yml</code>
file to define the system configuration settings 
+for a package. <code>defs</code> is a mapping (or associative array) of system
configuration setting definitions. It 
+has the following syntax:  </p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">syscfg.defs:
+    PKGA_SYSCFG_NAME1:
+       description:
+       value:
+       type:
+       restrictions:
+    PKGA_SYSCFG_NAME2:
+       description:
+       value:
+       type:
+       restrictions:
+</pre></div>
+
+
+<p><br></p>
+<p>Each setting definition consists of the following key-value mapping:  </p>
+<ul>
+<li>A setting name for the key, such as <code>PKGA_SYSCFG_NAME1</code>
in the syntax example above.
+Note: A system configuration setting name must be unique.  The newt tool aborts the build

+when multiple packages define the same setting. </li>
+<li>A mapping of fields for the value.  Each field itself is a key-value pair of attributes.
 The field keys are <code>description</code>, <code>value</code>,
<code>type</code>, and <code>restrictions</code>. They are described
in 
+following table:</li>
+</ul>
+<table style="width:90%", align="center">
+<tr>
+<th>Field</th>
+<th>Description</th>
+</tr>
+<tr>
+<td><code>description</code></td>
+<td>Describes the usage for the setting. <b>This field is optional.</b></td>
+<tr>
+<td><code>value<code></td>
+<td>Specifies the default value for the setting. <b>This field is required.</b>
The value depends on the <code>type</code> that you specify and can be an empty
string. 
+<tr>
+<td><code>type</code></td>
+<td>Specifies the data type for the <code>value</code> field. <b>This
field is optional.</b> You can specify one of three types:
+<ul>
+<li><code>raw</code> - The <code>value</code> data is uninterpreted.
This is the default <code>type</code>.</li>
+<li><code>task_priority</code> - Specifies a Mynewt task priority number.
 The task priority number assigned to each setting must be unique and between 0 and 239. 
<code>value</code> can be one of the following: 
+<ul>
+<li>A number between 0 and 239 - The task priority number to use for the setting.</li>
+<li><code>any</code> - Specify <code>any</code> to have newt
automatically assign a priority for the setting.  
+newt alphabetically orders all system configuration settings of this type and assigns the
next highest available 
+task priority number to each setting. </li>
+</ul>
+</li>
+<li><code>flash_owner</code> - Specifies a flash area. The <code>value</code>
should be the name of a flash area 
+defined in the BSP flash map for your target board. 
+</li>
+</ul>
+</td>
+</tr>
+<tr>
+<td><code>restrictions</code></td>
+<td>Specifies a list of restrictions on the setting value. <b>This field is optional.</b>
You can specify two formats:
+<ul>
+<li><code>$notnull</code> - Specifies that the setting cannot have the
empty string for a value. It essentially means that an empty string is not a sensible value
and a package must override it with an appropriate value. 
+<br>
+</li>
+<li><code>expression</code> - Specifies a boolean expression of the form
<code>[!]&ltrequired-setting>[if &ltbase-value>]</code>
+<br>Examples:
+<ul>
+<li><code>restrictions: !LOG_FCB</code> - Can only enable this setting
when <code>LOG_FCB</code> is false.
+<li><code>restrictions: LOG_FCB if 0 </code> - Can only disable this setting
when <code>LOG_FCB</code> is true.
+</ul>
+</li>
+</ul>
+</td>
+</tr>
+</table>
+
+<p><br></p>
+<h4 id="examples-of-configuration-settings">Examples of configuration settings</h4>
+<p><strong>Example 1:</strong> The following example is an excerpt from
the <code>sys/log</code> package <code>syscfg.yml</code> file. It
defines the 
+<code>LOG_LEVEL</code> configuration setting to specify the log level and the
<code>LOG_NEWTMGR</code> configuration setting to specify whether
+to enable or disable the newtmgr logging feature.</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">syscfg.defs:
+    LOG_LEVEL:
+        description: &#39;Log Level&#39;
+        value: 0
+        type: raw
+
+       ...       
+
+    LOG_NEWTMGR: 
+        description: &#39;Enables or disables newtmgr command tool logging&#39;
+        value: 0
+</pre></div>
+
+
+<p><br></p>
+<p><strong>Example 2:</strong> The following example is an excerpt from
the <code>net/nimble/controller</code> package <code>syscfg.yml</code>
file. It defines the <code>BLE_LL_PRIO</code> 
+configuration setting with a <code>task_priority</code> type and assigns task
priority 0 to the BLE link layer task.</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">syscfg.defs:
+    BLE_LL_PRIO:
+        description: &#39;BLE link layer task priority&#39;
+        type: &#39;task_priority&#39;
+        value: 0
+</pre></div>
+
+
+<p><br></p>
+<p><strong>Example 3:</strong> The following example is an excerpt from
the <code>fs/nffs</code> package <code>syscfg.yml</code> file. </p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">syscfg.defs:
+    NFFS_FLASH_AREA:
+        description: &#39;The flash area to use for the Newtron Flash File System&#39;
+        type: flash_owner
+        value:
+        restrictions:
+            - $notnull
+</pre></div>
+
+
+<p>It defines the <code>NFFS_FLASH_AREA</code> configuration setting with
a <code>flash_owner</code> type indicating that a flash area needs to be specified
for the Newtron Flash File System. The flash areas are typically defined by the BSP in its
<code>bsp.yml</code> file. For example, the <code>bsp.yml</code> for
nrf52dk board (<code>hw/bsp/nrf52dk/bsp.yml</code>)  defines an area named <code>FLASH_AREA_NFFS</code>:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">
   FLASH_AREA_NFFS:
+        user_id: 1
+        device: 0
+        offset: 0x0007d000
+        size: 12kB
+</pre></div>
+
+
+<p>The <code>syscfg.yml</code> file for the same board (<code>hw/bsp/nrf52dk/syscfg.yml</code>)
specifies that the above area be used for <code>NFFS_FLASH_AREA</code>.</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">syscfg.vals:
+    CONFIG_FCB_FLASH_AREA: FLASH_AREA_NFFS
+    REBOOT_LOG_FLASH_AREA: FLASH_AREA_REBOOT_LOG
+    NFFS_FLASH_AREA: FLASH_AREA_NFFS
+    COREDUMP_FLASH_AREA: FLASH_AREA_IMAGE_1
+</pre></div>
+
+
+<p>Note that the <code>fs/nffs/syscfg.yml</code> file indicates that the
<code>NFFS_FLASH_AREA</code> setting cannot be a null string; so a higher priority
package must set a non-null value to it. That is exactly what the BSP package does. For more
on priority of packages in setting values, see the next section.</p>
+<p><br></p>
+<h3 id="overriding-system-configuration-setting-values">Overriding System Configuration
Setting Values</h3>
+<p>A package may use the <code>vals</code> parameter in its <code>syscfg.yml</code>
file to override the configuration values defined
+by other packages.  This mechanism allows:</p>
+<ul>
+<li>Mynewt developers to implement a package and easily override the system configuration
setting values 
+   that are defined by the packages it depends on. </li>
+<li>Application developers to easily and cleanly override default configuration settings
in a single place and build a customized target. You can use the <code>newt target config
&lt;target-name&gt;</code> command to check all the system configuration setting
definitions and
+   values in your target to determine the setting values to override. See <a href="../../../../newt/command_list/newt_target/">newt
target</a>. </li>
+</ul>
+<p><code>vals</code> specifies the mappings of system configuration setting
name-value pairs as follows: </p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">syscfg.vals:
+    PKGA_SYSCFG_NAME1: VALUE1
+    PKGA_SYSCFG_NAME2: VALUE2
+              ...
+    PKGN_SYSCFG_NAME1: VALUEN
+</pre></div>
+
+
+<p>Note: The newt tool ignores overrides of undefined system configuration settings.
 </p>
+<p><br></p>
+<h4 id="resolving-override-conflicts">Resolving Override Conflicts</h4>
+<p>The newt tool uses package priorities to determine whether a package can override
a value and resolve conflicts when multiple packages override the same system configuration
setting. The following rules apply:</p>
+<ul>
+<li>A package can only override the default values of system configuration settings
that 
+  are defined by lower priority packages.</li>
+<li>When packages with different priorities override the same system configuration
setting value, newt uses 
+   the value from the highest priority package.</li>
+<li>Packages of equal priority cannot override the same system configuration setting
with different values. 
+   newt aborts the build unless a higher priority package also overrides the value.</li>
+</ul>
+<p>The following package types are listed from highest to lowest priority:</p>
+<ul>
+<li>Target</li>
+<li>App</li>
+<li>unittest - A target can include either an app or unit test package, but not both.</li>
+<li>BSP</li>
+<li>Lib - Includes all other system level packages such as os, lib, sdk, and compiler.</li>
+</ul>
+<p>It is recommended that you override defaults at the target level instead of updating
individual 
+package <code>syscfg.yml</code> files.</p>
+<p><br></p>
+<h4 id="examples-of-overrides">Examples of Overrides</h4>
+<p><strong>Example 4:</strong> The following example is an excerpt from
the <code>apps/slinky</code> package <code>syscfg.yml</code> file.
 The application package overrides, 
+in addition to other packages, the <code>sys/log</code> package system configuration
settings defined in <em>Example 1</em>. It changes the LOG_NEWTMGR system configuration
setting value from <code>0</code> to <code>1</code>.</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">syscfg.vals:
+    # Enable the shell task.
+    SHELL_TASK: 1
+
+       ...
+
+    # Enable newtmgr commands.
+    STATS_NEWTMGR: 1
+    LOG_NEWTMGR: 1
+</pre></div>
+
+
+<p><strong>Example 5:</strong> The following example are excerpts from
the <code>hw/bsp/native</code> package <code>bsp.yml</code> and <code>syscfg.yml</code>
files. 
+The package defines the flash areas for the BSP flash map in the <code>bsp.yml</code>
file, and sets the <code>NFFS_FLASH_AREA</code> 
+configuration setting value to use the flash area named <code>FLASH_AREA_NFFS</code>
in the <code>syscfg.yml</code> file.</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">bsp.flash_map:
+    areas:
+        # System areas.
+        FLASH_AREA_BOOTLOADER:
+            device: 0
+            offset: 0x00000000
+            size: 16kB
+
+             ...
+
+        # User areas.
+        FLASH_AREA_REBOOT_LOG:
+            user_id: 0
+            device: 0
+            offset: 0x00004000
+            size: 16kB
+        FLASH_AREA_NFFS:
+            user_id: 1
+            device: 0
+            offset: 0x00008000
+            size: 32kB
+
+
+syscfg.vals:
+    NFFS_FLASH_AREA: FLASH_AREA_NFFS
+</pre></div>
+
+
+<p><br></p>
+<h3 id="generated-syscfgh">Generated syscfg.h</h3>
+<p>The newt tool processes all the package <code>syscfg.yml</code> files
and generates the
+<code>&lt;target-path&gt;/generated/include/syscfg/syscfg.h</code> include
file with <code>#define</code> statements for each system configuration 
+setting defined.  newt creates a <code>#define</code> for a setting name as follows:
</p>
+<ul>
+<li>Adds the prefix <code>MYNEWT_VAL_</code>.</li>
+<li>Replaces all occurrences of "/", "-", and " " in the setting name with "_".</li>
+<li>Converts all characters to upper case.</li>
+</ul>
+<p>For example, the #define for <code>my-config-name</code> setting name
 is <code>MYNEWT_VAL_MY_CONFIG_NAME</code>.</p>
+<p>Newt groups the settings in <code>syscfg.h</code> by the packages that
defined them. It also indicates the 
+package that changed a system configuration setting value.  </p>
+<p><strong>Note:</strong> You only need to include <code>syscfg/syscfg.h</code>
in your source files to access the <code>syscfg.h</code> file.  The newt tool
sets the correct include path to build your target. </p>
+<p>Here is an excerpt from a sample <code>syscfg.h</code> file generated
for an app/slinky target.  It lists 
+the <code>sys/log</code> package definitions and also indicates that <code>app/slinky</code>
changed the value 
+for the <code>LOG_NEWTMGR</code> settings.  </p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">#ifndef
H_MYNEWT_SYSCFG_
+#define H_MYNEWT_SYSCFG_
+
+     ...
+
+/*** kernel/os */
+#ifndef MYNEWT_VAL_MSYS_1_BLOCK_COUNT
+#define MYNEWT_VAL_MSYS_1_BLOCK_COUNT (12)
+#endif
+
+#ifndef MYNEWT_VAL_MSYS_1_BLOCK_SIZE
+#define MYNEWT_VAL_MSYS_1_BLOCK_SIZE (292)
+#endif
+
+     ...
+
+/*** sys/log */
+
+#ifndef MYNEWT_VAL_LOG_LEVEL
+#define MYNEWT_VAL_LOG_LEVEL (0)
+#endif
+
+     ...
+
+/* Overridden by apps/slinky (defined by sys/log) */
+#ifndef MYNEWT_VAL_LOG_NEWTMGR
+#define MYNEWT_VAL_LOG_NEWTMGR (1)
+#endif
+
+#endif
+</pre></div>
+
+
+<p><br></p>
+<h3 id="system-initialization">System Initialization</h3>
+<p>An application's <code>main()</code> function must first call the Mynewt
<code>sysinit()</code> function to 
+initialize the software before it performs any other processing.
+<code>sysinit()</code> calls the <code>sysinit_app()</code> function
to perform system 
+initialization for the packages in the target.  You can, optionally, specify an 
+initialization function that <code>sysinit_app()</code> calls to initialize a
package. </p>
+<p>A package init function must have the following prototype:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">void
init_func_name(void)
+</pre></div>
+
+
+<p>Package init functions are called in stages to ensure that lower priority packages

+are initialized before higher priority packages.</p>
+<p>You specify an init function in the <code>pkg.yml</code> file for a
package as follows:</p>
+<ul>
+<li>
+<p>Use the <code>init_function</code> parameter to specify an init function
name. </p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">
  pkg.init_function: pkg_init_func_name
+</pre></div>
+
+
+<p>where <code>pkg_init_func_name</code> is the C function name of package
init function. </p>
+</li>
+<li>
+<p>Use the <code>init_stage</code> parameter to specify when to call the
package init function.</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">
  pkg.init_stage: stage_number
+</pre></div>
+
+
+<p>where <code>stage_number</code> is a number that indicates when this
init function is called relative to the other 
+   package init functions.  Mynewt calls the package init functions in increasing stage number
order
+   and in alphabetic order of init function names for functions in the same stage.
+   <em>Note:</em> The init function will be called at stage 0 if <code>pkg.init_stage</code>
is not specified.</p>
+</li>
+</ul>
+<p><em>Note:</em> You must include the <code>sysinit/sysinit.h</code>
header file to access the <code>sysinit()</code> function.</p>
+<p><br></p>
+<h4 id="generated-sysinit_app-function">Generated sysinit_app() Function</h4>
+<p>The newt tool processes the <code>init_function</code> and <code>init_stage</code>
parameters in all the pkg.yml files for a target,
+generates the <code>sysinit_app()</code> function in the <code>&lt;target-path&gt;/generated/src/&lt;target-name&gt;-sysinit_app.c</code>
file, and 
+includes the file in the build. Here is an example <code>sysinit_app()</code>
function:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">/**
+ * This file was generated by Apache Newt (incubating) version: 1.0.0-dev
+ */
+
+#if !SPLIT_LOADER
+
+void os_init(void);
+void split_app_init(void);
+void os_pkg_init(void);
+void imgmgr_module_init(void);
+void nmgr_pkg_init(void);
+
+      ...
+
+void console_pkg_init(void);
+void log_init(void);
+
+      ...
+
+void
+sysinit_app(void)
+{
+    os_init();
+
+    /*** Stage 0 */
+    /* 0.0: kernel/os */
+    os_pkg_init();
+    /* 0.1: sys/console/full */
+    console_pkg_init();
+
+        ...
+
+    /*** Stage 1 */
+    /* 1.0: sys/log */
+    log_init();
+
+        ...
+
+    /*** Stage 5 */
+    /* 5.0: boot/split */
+    split_app_init();
+    /* 5.1: mgmt/imgmgr */
+    imgmgr_module_init();
+    /* 5.2: mgmt/newtmgr */
+    nmgr_pkg_init();
+        ...
+}
+
+#endif
+</pre></div>
+
+
+<p><br></p>
+<h3 id="conditional-configurations">Conditional Configurations</h3>
+<p>You can use the system configuration setting values to conditionally specify parameter
values
+in <code>pkg.yml</code> and <code>syscfg.yml</code> files. The syntax
is:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">parameter_name.PKGA_SYSCFG_NAME:
+     parameter_value
+</pre></div>
+
+
+<p>This specifies that <code>parameter_value</code> is only set for <code>parameter_name</code>
if the <code>PKGA_SYSCFG_NAME</code> configuration setting value 
+is non-zero. Here is an example from the <code>libs/os</code> package <code>pkg.yml</code>
file:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">pkg.deps:
+    - sys/sysinit
+    - util/mem
+
+pkg.deps.OS_CLI
+    - sys/shell
+</pre></div>
+
+
+<p>This example specifies that the <code>os</code> package depends on the
<code>sysinit</code> and <code>mem</code> packages, and also depends
on the 
+<code>shell</code> package when <code>OS_CLI</code> is enabled. </p>
+<p>The newt tool aborts the build when it detects circular conditional dependencies.
</p>
+                        
+                        <div class="row">
+                            
+
+
+
+<ul class="nav nav-pills" style="margin-bottom: 10px">
+    <li>
+    
+    <a href=../../logs/logs/>
+        <span class="fa fa-arrow-left"></span>
+        Previous: Logs
+    </a>
+    
+    </li>
+    <li class="pull-right">
+    
+    <a href=../../../../network/ble/ble_intro/>
+        Next: NimBLE Introduction
+        <span class="fa fa-arrow-right"></span>
+    </a>
+    
+    </li>
+</ul>
+                        </div>
+                        <footer class="row">
+    <div class="col-xs-12">
+        
+            <p class="copyright">Copyright &copy; 2015 The Apache Software Foundation,
Licensed under the Apache License, Version 2.0 Apache and the Apache feather logo are trademarks
of The Apache Software Foundation.</p>
+        
+    </div>
+    <div class="col-xs-12">
+        <div class="logos">
+            <img src="/img/asf_logo_wide_small.png" alt="Apache" title="Apache">
+            <small class="footnote">
+                MyNewt is an effort undergoing incubation at The Apache Software Foundation
(ASF), sponsored by the Apache Incubator. Incubation is required of all newly accepted projects
until a further review indicates that the infrastructure, communications, and decision making
process have stabilized in a manner consistent with other successful ASF projects. While incubation
status is not necessarily a reflection of the completeness or stability of the code, it does
indicate that the project has yet to be fully endorsed by the ASF.
+            </small>
+            <img src="/img/egg-logo2.png" alt="Apache Incubator" title="Apache Incubator">
+        </div>
+    </div>
+</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>
+
+    </body>
+</html>
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/90eef887/develop/os/modules/testutil/test_assert/index.html
----------------------------------------------------------------------
diff --git a/develop/os/modules/testutil/test_assert/index.html b/develop/os/modules/testutil/test_assert/index.html
index 2c4473f..246b367 100644
--- a/develop/os/modules/testutil/test_assert/index.html
+++ b/develop/os/modules/testutil/test_assert/index.html
@@ -518,6 +518,17 @@
 
               
           
+              
+                
+  
+  
+    <li ><a href="../../sysinitconfig/sysinitconfig/">System Configuration And
Initialization</a>
+  
+  
+    </li>
+
+              
+          
     </ul>
   
     </li>

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/90eef887/develop/os/modules/testutil/test_case/index.html
----------------------------------------------------------------------
diff --git a/develop/os/modules/testutil/test_case/index.html b/develop/os/modules/testutil/test_case/index.html
index c69aefa..d332a27 100644
--- a/develop/os/modules/testutil/test_case/index.html
+++ b/develop/os/modules/testutil/test_case/index.html
@@ -518,6 +518,17 @@
 
               
           
+              
+                
+  
+  
+    <li ><a href="../../sysinitconfig/sysinitconfig/">System Configuration And
Initialization</a>
+  
+  
+    </li>
+
+              
+          
     </ul>
   
     </li>

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/90eef887/develop/os/modules/testutil/test_decl/index.html
----------------------------------------------------------------------
diff --git a/develop/os/modules/testutil/test_decl/index.html b/develop/os/modules/testutil/test_decl/index.html
index 00feaed..e3b32ef 100644
--- a/develop/os/modules/testutil/test_decl/index.html
+++ b/develop/os/modules/testutil/test_decl/index.html
@@ -518,6 +518,17 @@
 
               
           
+              
+                
+  
+  
+    <li ><a href="../../sysinitconfig/sysinitconfig/">System Configuration And
Initialization</a>
+  
+  
+    </li>
+
+              
+          
     </ul>
   
     </li>

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/90eef887/develop/os/modules/testutil/test_pass/index.html
----------------------------------------------------------------------
diff --git a/develop/os/modules/testutil/test_pass/index.html b/develop/os/modules/testutil/test_pass/index.html
index e4d35b4..b1f2f8f 100644
--- a/develop/os/modules/testutil/test_pass/index.html
+++ b/develop/os/modules/testutil/test_pass/index.html
@@ -518,6 +518,17 @@
 
               
           
+              
+                
+  
+  
+    <li ><a href="../../sysinitconfig/sysinitconfig/">System Configuration And
Initialization</a>
+  
+  
+    </li>
+
+              
+          
     </ul>
   
     </li>

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/90eef887/develop/os/modules/testutil/test_suite/index.html
----------------------------------------------------------------------
diff --git a/develop/os/modules/testutil/test_suite/index.html b/develop/os/modules/testutil/test_suite/index.html
index c8a1ce1..e2f7a48 100644
--- a/develop/os/modules/testutil/test_suite/index.html
+++ b/develop/os/modules/testutil/test_suite/index.html
@@ -518,6 +518,17 @@
 
               
           
+              
+                
+  
+  
+    <li ><a href="../../sysinitconfig/sysinitconfig/">System Configuration And
Initialization</a>
+  
+  
+    </li>
+
+              
+          
     </ul>
   
     </li>

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/90eef887/develop/os/modules/testutil/testutil/index.html
----------------------------------------------------------------------
diff --git a/develop/os/modules/testutil/testutil/index.html b/develop/os/modules/testutil/testutil/index.html
index 05edd58..ac64e92 100644
--- a/develop/os/modules/testutil/testutil/index.html
+++ b/develop/os/modules/testutil/testutil/index.html
@@ -458,6 +458,17 @@
 
               
           
+              
+                
+  
+  
+    <li ><a href="../../sysinitconfig/sysinitconfig/">System Configuration And
Initialization</a>
+  
+  
+    </li>
+
+              
+          
     </ul>
   
     </li>

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/90eef887/develop/os/modules/testutil/tu_init/index.html
----------------------------------------------------------------------
diff --git a/develop/os/modules/testutil/tu_init/index.html b/develop/os/modules/testutil/tu_init/index.html
index 2bb9679..02ac5f2 100644
--- a/develop/os/modules/testutil/tu_init/index.html
+++ b/develop/os/modules/testutil/tu_init/index.html
@@ -518,6 +518,17 @@
 
               
           
+              
+                
+  
+  
+    <li ><a href="../../sysinitconfig/sysinitconfig/">System Configuration And
Initialization</a>
+  
+  
+    </li>
+
+              
+          
     </ul>
   
     </li>

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/90eef887/develop/os/modules/testutil/tu_restart/index.html
----------------------------------------------------------------------
diff --git a/develop/os/modules/testutil/tu_restart/index.html b/develop/os/modules/testutil/tu_restart/index.html
index 1a26450..61f8047 100644
--- a/develop/os/modules/testutil/tu_restart/index.html
+++ b/develop/os/modules/testutil/tu_restart/index.html
@@ -518,6 +518,17 @@
 
               
           
+              
+                
+  
+  
+    <li ><a href="../../sysinitconfig/sysinitconfig/">System Configuration And
Initialization</a>
+  
+  
+    </li>
+
+              
+          
     </ul>
   
     </li>

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/90eef887/develop/os/os_user_guide/index.html
----------------------------------------------------------------------
diff --git a/develop/os/os_user_guide/index.html b/develop/os/os_user_guide/index.html
index 5e48fdc..7be9ce2 100644
--- a/develop/os/os_user_guide/index.html
+++ b/develop/os/os_user_guide/index.html
@@ -439,6 +439,17 @@
 
               
           
+              
+                
+  
+  
+    <li ><a href="../modules/sysinitconfig/sysinitconfig/">System Configuration
And Initialization</a>
+  
+  
+    </li>
+
+              
+          
     </ul>
   
     </li>

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/90eef887/develop/sitemap.xml
----------------------------------------------------------------------
diff --git a/develop/sitemap.xml b/develop/sitemap.xml
index 0867942..b33136b 100644
--- a/develop/sitemap.xml
+++ b/develop/sitemap.xml
@@ -4,7 +4,7 @@
     
     <url>
      <loc>http://mynewt.apache.org/</loc>
-     <lastmod>2017-01-02</lastmod>
+     <lastmod>2017-01-06</lastmod>
      <changefreq>daily</changefreq>
     </url>
     
@@ -13,7 +13,7 @@
         
     <url>
      <loc>http://mynewt.apache.org/pages/ble/</loc>
-     <lastmod>2017-01-02</lastmod>
+     <lastmod>2017-01-06</lastmod>
      <changefreq>daily</changefreq>
     </url>
         
@@ -22,7 +22,7 @@
     
     <url>
      <loc>http://mynewt.apache.org/quick-start/</loc>
-     <lastmod>2017-01-02</lastmod>
+     <lastmod>2017-01-06</lastmod>
      <changefreq>daily</changefreq>
     </url>
     
@@ -30,7 +30,7 @@
     
     <url>
      <loc>http://mynewt.apache.org/about/</loc>
-     <lastmod>2017-01-02</lastmod>
+     <lastmod>2017-01-06</lastmod>
      <changefreq>daily</changefreq>
     </url>
     
@@ -38,7 +38,7 @@
     
     <url>
      <loc>http://mynewt.apache.org/talks/</loc>
-     <lastmod>2017-01-02</lastmod>
+     <lastmod>2017-01-06</lastmod>
      <changefreq>daily</changefreq>
     </url>
     
@@ -46,7 +46,7 @@
     
     <url>
      <loc>http://mynewt.apache.org/download/</loc>
-     <lastmod>2017-01-02</lastmod>
+     <lastmod>2017-01-06</lastmod>
      <changefreq>daily</changefreq>
     </url>
     
@@ -54,7 +54,7 @@
     
     <url>
      <loc>http://mynewt.apache.org/community/</loc>
-     <lastmod>2017-01-02</lastmod>
+     <lastmod>2017-01-06</lastmod>
      <changefreq>daily</changefreq>
     </url>
     
@@ -62,7 +62,7 @@
     
     <url>
      <loc>http://mynewt.apache.org/events/</loc>
-     <lastmod>2017-01-02</lastmod>
+     <lastmod>2017-01-06</lastmod>
      <changefreq>daily</changefreq>
     </url>
     
@@ -71,7 +71,7 @@
         
     <url>
      <loc>http://mynewt.apache.org/os/introduction/</loc>
-     <lastmod>2017-01-02</lastmod>
+     <lastmod>2017-01-06</lastmod>
      <changefreq>daily</changefreq>
     </url>
         
@@ -83,7 +83,7 @@
         
     <url>
      <loc>http://mynewt.apache.org/os/get_started/vocabulary/</loc>
-     <lastmod>2017-01-02</lastmod>
+     <lastmod>2017-01-06</lastmod>
      <changefreq>daily</changefreq>
     </url>
         
@@ -123,13 +123,13 @@
         
     <url>
      <loc>http://mynewt.apache.org/faq/how_to_edit_docs/</loc>
-     <lastmod>2017-01-02</lastmod>
+     <lastmod>2017-01-06</lastmod>
      <changefreq>daily</changefreq>
     </url>
         
     <url>
      <loc>http://mynewt.apache.org/faq/answers/</loc>
-     <lastmod>2017-01-02</lastmod>
+     <lastmod>2017-01-06</lastmod>
      <changefreq>daily</changefreq>
     </url>
         



Mime
View raw message