1) Added Validation and Error Message page to the System Configuration and Initialization Section (updated mkdocs.yml and added sysconfig_error.md) 2) Updated the explanation for the examples for the restrictions field in sysinitconfig.md to better match the restriction violation error message that newt outputs. 3) Added writeup the user must use the MYNEWT_VAL() macro to reference a #define for a setting. 4) Cleanup formatting in sysinitconfig.md
Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/commit/78ad100b Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/78ad100b Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/78ad100b Branch: refs/heads/develop Commit: 78ad100bf6681888df5eb000bbb0166fcccc7a1d Parents: b377a22 Author: cwanda <[email protected]> Authored: Mon Jan 16 23:29:30 2017 -0800 Committer: cwanda <[email protected]> Committed: Tue Jan 17 21:52:40 2017 -0800 ---------------------------------------------------------------------- .../os/modules/sysinitconfig/sysconfig_error.md | 331 +++++++++++++++++++ docs/os/modules/sysinitconfig/sysinitconfig.md | 85 ++++- mkdocs.yml | 1 + 3 files changed, 400 insertions(+), 17 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/78ad100b/docs/os/modules/sysinitconfig/sysconfig_error.md ---------------------------------------------------------------------- diff --git a/docs/os/modules/sysinitconfig/sysconfig_error.md b/docs/os/modules/sysinitconfig/sysconfig_error.md new file mode 100644 index 0000000..e43e77d --- /dev/null +++ b/docs/os/modules/sysinitconfig/sysconfig_error.md @@ -0,0 +1,331 @@ +##Validation and Error Messages + +With multiple packages defining and overriding system configuration settings, it +is easy to introduce conflicts and violations that are difficult to find. The +`newt build <target-name>` command validates the setting definitions and value +overrides for all the packages in the target to ensure a valid and consistent build. +It aborts the build when it detects violations or ambiguities between packages. +The following sections describe the error conditions that newt detects and +the error messages that it outputs. For most errors, newt also outputs +the `Setting history` with the order of package overrides to help +you resolve the errors. + +**Note:** The `newt target config <target-name>` command also detects +errors and outputs error messages at the top of the command output. +The command outputs the package setting definitions and values after it +outputs the error messages. It is easy to miss the error messages at the top. + + +###Value Override Violations + +The newt tool uses package priorities to resolve override conflicts. It uses +the value override from the highest priority package when multiple +packages override the same setting. Newt checks for the following +override violations: + +* Ambiguity Violation - Two packages of the same priority override a setting with +different values. And no higher priority package overrides the setting. +* Lateral Violation - A Lib package overrides a setting that another Lib package defines. +* Priority Violation - A package overrides a setting defined by a package with higher or +equal priority (TODO: Add error message examples) + +####Example: Ambiguity Violation Error Message + +The following example shows the error message that newt outputs for an ambiguity violation: + +```no-highlight + +Error: Syscfg ambiguities detected: + Setting: LOG_NEWTMGR, Packages: [apps/slinky, apps/splitty] +Setting history (newest -> oldest): + LOG_NEWTMGR: [apps/splitty:0, apps/slinky:1, sys/log:0] + +``` + +The above error occurs because the `apps/slinky` and `apps/splitty` packages +in the split image target both override the same setting with different +values. The `apps/slinky` package sets the `sys/log` package `LOG_NEWTMGR` +setting to 1, and the `apps/splitty` package sets the setting to 0. The +overrides are ambiguous because both are `app` packages and +have the same priority. The following are excerpts of the defintion +and the two overrides from the `syscfg.yml` files that cause the error: + + +```no-highlight + +#Package: sys/log/ +syscfg.defs: + LOG_NEWTMGR: + description: 'Enables or disables newtmgr command tool logging' + value: 0 + +#Package: apps/slinky +syscfg.vals: + LOG_NEWTMGR: 1 + +#Package: apps/splitty +syscfg.vals: + LOG_NEWTMGR: 0 + +``` + +####Example: Lateral Violation Error Message + +The following example shows the error message that newt outputs for a lateral violation: + +```no-highlight + + +Error: Lateral overrides detected (bottom-priority packages cannot override settings): + Package: mgmt/newtmgr, Setting: LOG_NEWTMGR + +Setting history (newest -> oldest): + LOG_NEWTMGR: [sys/log:0] + +``` + +The above error occurs because the `mgmt/newtmgr` lib package +overrides the `LOG_NEWTMGR` setting that the `sys/log` lib package +defines. The following are excerpts of the definition and the override from the +`syscfg.yml` files that cause this error: + +```no-highlight + +#Package: sys/log +syscfg.defs: + LOG_NEWTMGR: + description: 'Enables or disables newtmgr command tool logging' + value: 0 + +#Package: mgmt/newtmgr +syscfg.vals: + LOG_NEWTMGR: 1 + +``` +<br> + +###Flash Area Violations + +For `flash_owner` type setting definitions, newt checks +for the following violations: + +* An undefined flash area is assigned to a setting. +* A flash area is assigned to multiple settings. + +####Example: Undefined Flash Area Error Message + +The following example shows the error message that newt outputs for an undefined flash area. + +```no-highlight + +Building target targets/sim_slinky +Error: Flash errors detected: + Setting REBOOT_LOG_FLASH_AREA specifies unknown flash area: FLASH_AREA_NOEXIST + +Setting history (newest -> oldest): + REBOOT_LOG_FLASH_AREA: [hw/bsp/native:FLASH_AREA_NOEXIST, sys/reboot:] + +``` +The above error occurs because the `hw/bsp/native` package assigns the +undefined `FLASH_AREA_NOEXIST` flash area to the `sys/reboot` package +`REBOOT_LOG_FLASH_AREA` setting. The following are excerpts of the definition +and the override from the `syscfg.yml` files that cause the error: + +```no-highlight + +#Package: sys/reboot +syscfg.defs: + REBOOT_LOG_FLASH_AREA: + description: 'Flash Area to use for reboot log.' + type: flash_owner + value: + +#Package: hw/bsp/native +syscfg.vals: + REBOOT_LOG_FLASH_AREA: FLASH_AREA_NOEXIST + +``` + +####Example: Multiple Flash Area Assignment Error Message + +The following example shows the error message that newt outputs when multiple +settings are assigned the same flash area: + +```no-highlight + +Error: Flash errors detected: + Multiple flash_owner settings specify the same flash area + settings: REBOOT_LOG_FLASH_AREA, CONFIG_FCB_FLASH_AREA + flash area: FLASH_AREA_NFFS + +Setting history (newest -> oldest): + CONFIG_FCB_FLASH_AREA: [hw/bsp/native:FLASH_AREA_NFFS, sys/config:] + REBOOT_LOG_FLASH_AREA: [apps/slinky:FLASH_AREA_NFFS, sys/reboot:] + +``` + +The above error occurs because the `hw/bsp/native` package assigns +the `FLASH_AREA_NFFS` flash area to the `sys/config/` package +`CONFIG_FCB_FLASH_AREA` setting, and the `apps/slinky` package +also assigns `FLASH_AREA_NFFS` to the `sys/reboot` package +`REBOOT_LOG_FLASH_AREA` setting. The following are excerpts of the +two definitions and the two overrides from the `syscfg.yml` files +that cause the error: + +```no-highlight + +# Package: sys/config +syscfg.defs.CONFIG_FCB: + CONFIG_FCB_FLASH_AREA: + description: 'The flash area for the Config Flash Circular Buffer' + type: 'flash_owner' + value: + +# Package: sys/reboot +syscfg.defs: + REBOOT_LOG_FLASH_AREA: + description: 'The flash area for the reboot log' + type: 'flash_owner' + value: + +#Package: hw/bsp/native +syscfg.vals: + CONFIG_FCB_FLASH_AREA: FLASH_AREA_NFFS + +#Package: apps/slinky +syscfg.vals: + REBOOT_LOG_FLASH_AREA: FLASH_AREA_NFFS + +``` +<br> +###Restriction Violations +For setting definitions with `restrictions` specified, newt checks for +the following violations: + +* A setting with a `$notnull` restriction does not have a value. +* For a setting with expression restrictions, some required setting +values in the expressions evaluate to false. + +####Example: $notnull Restriction Violation Error Message + +The following example shows the error message that newt outputs when +a setting with `$notnull` restriction does not have a value: + +```no-highlight + +Error: Syscfg restriction violations detected: + NFFS_FLASH_AREA must not be null + +Setting history (newest -> oldest): + NFFS_FLASH_AREA: [fs/nffs:] + +``` + +The above error occurs because the `fs/nffs` package defines the `NFFS_FLASH_AREA` +setting with a `$notnull` restriction and no packages override the setting. The +following is an excerpt of the definition in the `syscfg.yml` file that causes the error: + +```no-highlight + +#Package: fs/nffs +syscfg.defs: + NFFS_FLASH_AREA: + description: 'The flash area to use for the Newtron Flash File System' + type: flash_owner + value: + restrictions: + - $notnull +``` +####Example: Expression Restriction Violation Error Message + +The following example shows the error message that newt outputs for +an expression restriction violation: + +```no-highlight + +Error: Syscfg restriction violations detected: + CONFIG_FCB=1 requires CONFIG_FCB_FLASH_AREA be set, but CONFIG_FCB_FLASH_AREA= + +Setting history (newest -> oldest): + CONFIG_FCB: [targets/sim_slinky:1, sys/config:0] + CONFIG_FCB_FLASH_AREA: [sys/config:] + +``` + +The above error occurs because the `sys/config` package defines the `CONFIG_FCB` setting with +a restriction that when set, requires that the `CONFIG_FCB_FLASH_AREA` setting must +also be set. The following are excerpts of the definition and the override from the `syscfg.yml` +files that cause the error: + +```no-highlight + +# Package: sys/config +syscfg.defs: + CONFIG_FCB: + description: 'Uses Config Flash Circular Buffer' + value: 0 + restrictions: + - '!CONFIG_NFFS' + - 'CONFIG_FCB_FLASH_AREA' + +# Package: targets/sim_slinky +syscfg.vals: + CONFIG_FCB: 1 +``` +<br> +###Task Priority Violations + +For `task_priority` type setting definitions, newt checks for the following violations: + +* A task priority number is assigned to multiple settings. +* The task priority number is greater than 239. + +####Example: Duplicate Task Priority Assignment Error Message + +The following example shows the error message that newt outputs when +a task priority number is assigned to multiple settings. + +**Note:** The settings used in this example are not actual `apps/slinky` and `sys/shell` settings. +These settings are created for this example because currently only one Mynewt package +defines a `task_priority` type setting. + +```no-highlight + +Error: duplicate priority value: setting1=SHELL_TASK_PRIORITY setting2=SLINKY_TASK_PRIORITY pkg1=apps/slinky pkg2=sys/shell value=1 + +``` + +The above error occurs because the `apps/slinky` package defines a `SLINKY_TASK_PRIORITY` +setting with a default task priority of 1 and the `sys/shell` package also defines a +`SHELL_TASK_PRIORITY` setting with a default task priority of 1. + +####Example: Invalid Task Priority Error Message + +The following example shows the error message that newt outputs when +a setting is assigned an invalid task priority value: + +```no-highlight + +Error: invalid priority value: value too great (> 239); setting=SLINKY_TASK_PRIORITY value=240 pkg=apps/slinky + +``` + +The above error occurs because the `apps/slinky` package defines the `SLINKY_TASK_PRIORITY` setting +with 240 for the default task priority value. + +**Note:** Newt does not output the `Setting history` with task priority violation error messages. + + +<br> +###Duplicate System Configuration Setting Definition + +A setting definition must be unique. Newt checks that only one package in the +target defines a setting. The following example shows the error message that newt +outputs when multiple packages define the `LOG_NEWTMGR` setting: + +```no-highlight + +Error: setting LOG_NEWTMGR redefined + +``` +**Note:** Newt does not output the `Setting history` with duplicate setting error messages. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/78ad100b/docs/os/modules/sysinitconfig/sysinitconfig.md ---------------------------------------------------------------------- diff --git a/docs/os/modules/sysinitconfig/sysinitconfig.md b/docs/os/modules/sysinitconfig/sysinitconfig.md index 8feb6d8..40faf92 100644 --- a/docs/os/modules/sysinitconfig/sysinitconfig.md +++ b/docs/os/modules/sysinitconfig/sysinitconfig.md @@ -1,5 +1,4 @@ - -#System Configuration and Initialization +##System Configuration and Initialization 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: @@ -56,7 +55,7 @@ syscfg.defs: Each setting definition consists of the following key-value mapping: * A setting name for the key, such as `PKGA_SYSCFG_NAME1` in the syntax example above. -Note: A system configuration setting name must be unique. The newt tool aborts the build +**Note:** A system configuration setting name must be unique. The newt tool aborts the build when multiple packages define the same setting. * A mapping of fields for the value. Each field itself is a key-value pair of attributes. The field keys are `description`, `value`, `type`, and `restrictions`. They are described in following table: @@ -101,8 +100,8 @@ defined in the BSP flash map for your target board. <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> - 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. +<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> @@ -112,7 +111,7 @@ defined in the BSP flash map for your target board. <br> -####Examples of configuration settings +####Examples of Configuration Settings **Example 1:** The following example is an excerpt from the `sys/log` package `syscfg.yml` file. It defines the `LOG_LEVEL` configuration setting to specify the log level and the `LOG_NEWTMGR` configuration setting to specify whether @@ -208,7 +207,7 @@ syscfg.vals: PKGN_SYSCFG_NAME1: VALUEN ``` -Note: The newt tool ignores overrides of undefined system configuration settings. +**Note**: The newt tool ignores overrides of undefined system configuration settings. <br> @@ -229,7 +228,7 @@ The following package types are listed from highest to lowest priority: * App * unittest - A target can include either an app or unit test package, but not both. * BSP -* Lib - Includes all other system level packages such as os, lib, sdk, and compiler. +* 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.) It is recommended that you override defaults at the target level instead of updating individual package `syscfg.yml` files. @@ -239,7 +238,7 @@ package `syscfg.yml` files. ####Examples of Overrides **Example 4:** The following example is an excerpt from the `apps/slinky` package `syscfg.yml` file. The application package overrides, -in addition to other packages, the `sys/log` package system configuration settings defined in *Example 1*. It changes the LOG_NEWTMGR system configuration setting value from `0` to `1`. +in addition to other packages, the `sys/log` package system configuration settings defined in **Example 1**. It changes the LOG_NEWTMGR system configuration setting value from `0` to `1`. ```no-highlight @@ -291,32 +290,52 @@ syscfg.vals: <br> -###Generated syscfg.h +###Generated syscfg.h and Referencing System Configuration Settings The newt tool processes all the package `syscfg.yml` files and generates the `<target-path>/generated/include/syscfg/syscfg.h` include file with `#define` statements for each system configuration -setting defined. newt creates a `#define` for a setting name as follows: +setting defined. Newt creates a `#define` for a setting name as follows: * Adds the prefix `MYNEWT_VAL_`. * Replaces all occurrences of "/", "-", and " " in the setting name with "_". * Converts all characters to upper case. -For example, the #define for `my-config-name` setting name is `MYNEWT_VAL_MY_CONFIG_NAME`. +For example, the #define for my-config-name setting name is MYNEWT_VAL_MY_CONFIG_NAME. Newt groups the settings in `syscfg.h` by the packages that defined them. It also indicates the package that changed a system configuration setting value. +You must use the `MYNEWT_VAL()` macro to reference a #define of a setting name in your header and source files. +For example, to reference the `my-config-name` setting name, you use `MYNEWT_VAL(MY_CONFIG_NAME)`. + **Note:** You only need to include `syscfg/syscfg.h` in your source files to access the `syscfg.h` file. The newt tool sets the correct include path to build your target. -Here is an excerpt from a sample `syscfg.h` file generated for an app/slinky target. It lists -the `sys/log` package definitions and also indicates that `app/slinky` changed the value -for the `LOG_NEWTMGR` settings. +####Example of syscfg.h and How to Reference a Setting Name +**Example 6**: The following example are excerpts from a sample `syscfg.h` file generated for an app/slinky target and +from the `sys/log` package `log.c` file that shows how to reference a setting name. + +The `syscfg.h` file shows the `sys/log` package definitions and also indicates that `app/slinky` +changed the value for the `LOG_NEWTMGR` settings. ```no-highlight +/** + * This file was generated by Apache Newt (incubating) 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 */ @@ -344,6 +363,38 @@ for the `LOG_NEWTMGR` settings. #endif #endif + +``` + +The `log_init()` function in the `sys/log/src/log.c` file initializes the `sys/log` package. It checks the +`LOG_NEWTMGR` setting value, using `MYNEWT_VAL(LOG_NEWTMGR)`, to determine whether the target application +has enabled the `newtmgr log` functionality. It only registers the the callbacks to process the +`newtmgr log` commands when the setting value is non-zero. + +```no-highlight + +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 +} + ``` <br> @@ -381,9 +432,9 @@ You specify an init function in the `pkg.yml` file for a package as follows: where `stage_number` 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. - *Note:* The init function will be called at stage 0 if `pkg.init_stage` is not specified. + **Note:** The init function will be called at stage 0 if `pkg.init_stage` is not specified. -*Note:* You must include the `sysinit/sysinit.h` header file to access the `sysinit()` function. +**Note:** You must include the `sysinit/sysinit.h` header file to access the `sysinit()` function. <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/78ad100b/mkdocs.yml ---------------------------------------------------------------------- diff --git a/mkdocs.yml b/mkdocs.yml index f185829..8b7e427 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -351,6 +351,7 @@ pages: - toc: 'os/modules/logs/logs.md' - System Configuration And Initialization: - toc: 'os/modules/sysinitconfig/sysinitconfig.md' + - 'Validation and Error Messages': 'os/modules/sysinitconfig/sysconfig_error.md' - BLE User Guide: - NimBLE Introduction: 'network/ble/ble_intro.md' - NimBLE Security: 'network/ble/ble_sec.md'
