| <!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" selected="selected" > |
| 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" > |
| 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>» System Configuration And Initialization</li> |
| |
| |
| |
| <li>» <a href="os/os_user_guide/">OS User Guide</a></li> |
| |
| |
| |
| <li>» <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.3.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>[!]<required-setting>[if <base-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: 'Log Level' |
| value: 0 |
| type: raw |
| |
| ... |
| |
| LOG_NEWTMGR: |
| description: 'Enables or disables newtmgr command tool logging' |
| 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: 'BLE link layer task priority' |
| type: 'task_priority' |
| 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: 'The flash area to use for the Newtron Flash File System' |
| 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 <target-name></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/<target-path>/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><target-path>/generated/src/<target-name>-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> |