Google Git
Sign in
apache / mynewt-site / refs/heads/asf-site / . / v1_2_0 / os / modules / sysinitconfig / sysinitconfig / index.html
blob: 805ffab392c77090b3e1d1882a3672cda7ab3d2f [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.12.0, Apache NimBLE 1.7.0 </a> released (April 4, 2024)
</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_12_0/" >
Version: 1.12.0
</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" selected="selected" >
Version: 1.2.0
</option>
<option value="/v1_1_0/os/introduction" >
Version: 1.1.0
</option>
<option value="/v1_0_0/os/introduction" >
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 ><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="../../sensor_framework/sensor_framework_overview/">Sensor Framework</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="../../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>
<li >
<a href="../sysconfig_error/">Validation and Error Messages</a>
</li>
</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>
<li >
<a href="../../../../known_issues/">Known Issues</a>
</li>
</ul>
</li>
<li><a href="
../../../../newt/install/prev_releases/
">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; System Configuration And Initialization</li>
<li>&raquo; <a href="os/os_user_guide/">OS User Guide</a></li>
<li>&raquo; <a href="os/introduction/">Mynewt Documentation</a></li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/apache/mynewt-site/blob/master/docs/os/modules/sysinitconfig/sysinitconfig.md"
class="icon icon-github"> Edit on GitHub</a>
</li>
</ul>
</div>
</div>
<div class="alert alert-warning">
<p>
Version 1.2.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>
<h2 id="system-configuration-and-initialization">System Configuration and Initialization</h2>
<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="/os/get_started/vocabulary.md">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.md">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%;"><span></span><code>syscfg.defs:
PKGA_SYSCFG_NAME1:
description:
value:
type:
restrictions:
PKGA_SYSCFG_NAME2:
description:
value:
type:
restrictions:
</code></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.
<strong>Note:</strong> 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> - When this setting is enabled, <code>LOG_FCB</code> must be disabled.
<li><code>restrictions: LOG_FCB if 0 </code> - When this setting is disabled, <code>LOG_FCB</code> must be enabled.
</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/full</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%;"><span></span><code>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
</code></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%;"><span></span><code>syscfg.defs:
BLE_LL_PRIO:
description: &#39;BLE link layer task priority&#39;
type: &#39;task_priority&#39;
value: 0
</code></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%;"><span></span><code>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
</code></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%;"><span></span><code> FLASH_AREA_NFFS:
user_id: 1
device: 0
offset: 0x0007d000
size: 12kB
</code></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%;"><span></span><code>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
</code></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 show &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.md">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%;"><span></span><code>syscfg.vals:
PKGA_SYSCFG_NAME1: VALUE1
PKGA_SYSCFG_NAME2: VALUE2
...
PKGN_SYSCFG_NAME1: VALUEN
</code></pre></div>
<p><strong>Note</strong>: 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. (Note that a Lib package cannot override other Lib package settings.)</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/full</code> package system configuration settings defined in <strong>Example 1</strong>. 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%;"><span></span><code>syscfg.vals:
# Enable the shell task.
SHELL_TASK: 1
...
# Enable newtmgr commands.
STATS_NEWTMGR: 1
LOG_NEWTMGR: 1
</code></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%;"><span></span><code>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
</code></pre></div>
<p><br></p>
<h3 id="generated-syscfgh-and-referencing-system-configuration-settings">Generated syscfg.h and Referencing System Configuration Settings</h3>
<p>The newt tool processes all the package <code>syscfg.yml</code> files and generates the
<code>bin/&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 my-config-name setting name is MYNEWT_VAL_MY_CONFIG_NAME.</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>You must use the <code>MYNEWT_VAL()</code> macro to reference a #define of a setting name in your header and source files.
For example, to reference the <code>my-config-name</code> setting name, you use <code>MYNEWT_VAL(MY_CONFIG_NAME)</code>.</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>
<h4 id="example-of-syscfgh-and-how-to-reference-a-setting-name">Example of syscfg.h and How to Reference a Setting Name</h4>
<p><strong>Example 6</strong>: The following example are excerpts from a sample <code>syscfg.h</code> file generated for an app/slinky target and
from the <code>sys/log/full</code> package <code>log.c</code> file that shows how to reference a setting name.</p>
<p>The <code>syscfg.h</code> file shows the <code>sys/log/full</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%;"><span></span><code>/**
* This file was generated by Apache Newt version: 1.0.0-dev
*/
#ifndef H_MYNEWT_SYSCFG_
#define H_MYNEWT_SYSCFG_
/**
* This macro exists to ensure code includes this header when needed. If code
* checks the existence of a setting directly via ifdef without including this
* header, the setting macro will silently evaluate to 0. In contrast, an
* attempt to use these macros without including this header will result in a
* compiler error.
*/
#define MYNEWT_VAL(x) MYNEWT_VAL_ ## x
...
/*** 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/full */
#ifndef MYNEWT_VAL_LOG_LEVEL
#define MYNEWT_VAL_LOG_LEVEL (0)
#endif
...
/* Overridden by apps/slinky (defined by sys/log/full) */
#ifndef MYNEWT_VAL_LOG_NEWTMGR
#define MYNEWT_VAL_LOG_NEWTMGR (1)
#endif
#endif
</code></pre></div>
<p>The <code>log_init()</code> function in the <code>sys/log/full/src/log.c</code> file initializes the <code>sys/log/full</code> package. It checks the
<code>LOG_NEWTMGR</code> setting value, using <code>MYNEWT_VAL(LOG_NEWTMGR)</code>, to determine whether the target application
has enabled the <code>newtmgr log</code> functionality. It only registers the the callbacks to process the
<code>newtmgr log</code> commands when the setting value is non-zero.</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>void
log_init(void)
{
int rc;
/* Ensure this function only gets called by sysinit. */
SYSINIT_ASSERT_ACTIVE();
(void)rc;
if (log_inited) {
return;
}
log_inited = 1;
...
#if MYNEWT_VAL(LOG_NEWTMGR)
rc = log_nmgr_register_group();
SYSINIT_PANIC_ASSERT(rc == 0);
#endif
}
</code></pre></div>
<p><br></p>
<h3 id="system-initialization">System Initialization</h3>
<p>During system startup, Mynewt creates a default event queue and a main task to process events from this queue.
You can override the <code>OS_MAIN_TASK_PRIO</code> and <code>OS_MAIN_TASK_STACK_SIZE</code> setting values defined by the
<code>kernel/os</code> package to specify different task priority and stack size values.</p>
<p>Your application's <code>main()</code> function executes in the context of the main task and must perform the following:</p>
<ul>
<li>At the start of <code>main()</code>, call the Mynewt <code>sysinit()</code> function to initialize
the packages before performing any other processing.</li>
<li>At the end of <code>main()</code>, wait for and dispatch events from the default event queue in an infinite loop. </li>
</ul>
<p><strong>Note:</strong> You must include the <code>sysinit/sysinit.h</code> header file to access the <code>sysinit()</code> function.</p>
<p>Here is an example of a <code>main()</code> function:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>int
main(int argc, char **argv)
{
/* First, call sysinit() to perform the system and package initialization */
sysinit();
... other application initialization processing....
/* Last, process events from the default event queue. */
while (1) {
os_eventq_run(os_eventq_dflt_get());
}
/* main never returns */
}
</code></pre></div>
<p><br></p>
<h4 id="specifying-package-initialization-functions">Specifying Package Initialization Functions</h4>
<p>The <code>sysinit()</code> function calls the <code>sysinit_app()</code> function to perform system
initialization for the packages in the target. You can, optionally,
specify one or more package initialization functions
that <code>sysinit_app()</code> calls to initialize a package. </p>
<p>A package initialization function must have the following prototype:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>void init_func_name(void)
</code></pre></div>
<p>Package initialization functions are called in stages to ensure that lower priority
packages are initialized before higher priority packages. A stage is an
integer value, 0 or higher, that specifies when an initialization function is
called. Mynewt calls the package initialization functions
in increasing stage number order. The call order for initialization functions with the
same stage number depends on the order the packages are processed,
and you cannot rely on a specific call order for these functions. </p>
<p>You use the <code>pkg.init</code> parameter in the
<code>pkg.yml</code> file to specify an initialization function and the stage number to call the function.
You can specify multiple initialization functions, with a different stage number for each function,
for the parameter values. This feature allows packages with interdependencies to
perform initialization in multiple stages. </p>
<p>The <code>pkg.init</code> parameter has the following syntax in the <code>pkg.yml</code> file: </p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>pkg.init:
pkg_init_func1_name: pkg_init_func1_stage
pkg_init_func2_name: pkg_init_func2_stage
...
pkg_init_funcN_name: pkg_init_funcN_stage
</code></pre></div>
<p>where <code>pkg_init_func#_name</code> is the C function name of an initialization function, and <code>pkg_init_func#_stage</code>
is an integer value, 0 or higher, that indicates the stage when the <code>pkg_init_func#_name</code> function is called. </p>
<p><strong>Note:</strong> The <code>pkg.init_function</code> and <code>pkg.init_stage</code> parameters introduced in a previous release for
specifying a package initialization function and a stage number are deprecated and have been
retained to support the legacy format. They will not
be maintained for future releases and we recommend that you migrate to use the <code>pkg.init</code> parameter.</p>
<p><br></p>
<h4 id="generated-sysinit_app-function">Generated sysinit_app() Function</h4>
<p>The newt tool processes the <code>pkg.init</code> parameters in all the <code>pkg.yml</code> 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%;"><span></span><code>**
* This file was generated by Apache Newt (incubating) version: 1.0.0-dev
*/
#if !SPLIT_LOADER
void split_app_init(void);
void os_pkg_init(void);
void imgmgr_module_init(void);
...
void stats_module_init(void);
void
sysinit_app(void)
{
/*** Stage 0 */
/* 0.0: kernel/os */
os_pkg_init();
/*** Stage 2 */
/* 2.0: sys/flash_map */
flash_map_init();
/*** Stage 10 */
/* 10.0: sys/stats/full */
stats_module_init();
/*** Stage 20 */
/* 20.0: sys/console/full */
console_pkg_init();
/*** Stage 100 */
/* 100.0: sys/log/full */
log_init();
/* 100.1: sys/mfg */
mfg_init();
....
/*** Stage 300 */
/* 300.0: sys/config */
config_pkg_init();
/*** Stage 500 */
/* 500.0: sys/id */
id_init();
/* 500.1: sys/shell */
shell_init();
...
/* 500.4: mgmt/imgmgr */
imgmgr_module_init();
/*** Stage 501 */
/* 501.0: mgmt/newtmgr/transport/nmgr_shell */
nmgr_shell_pkg_init();
}
#endif
</code></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%;"><span></span><code>parameter_name.PKGA_SYSCFG_NAME:
parameter_value
</code></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%;"><span></span><code>pkg.deps:
- sys/sysinit
- util/mem
pkg.deps.OS_CLI
- sys/shell
</code></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>
</li>
<li class="pull-right">
</li>
</ul>
</div>
<footer class="row">
<div class="col-xs-12">
<p class="copyright">Apache Mynewt 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>