| 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. |
| |
| .. contents:: |
| :local: |
| :depth: 2 |
| |
| **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. |
| - Priority Violation - A package overrides a setting defined by a |
| package with higher or equal priority. |
| |
| **Note:** A package may override the default value for a setting that |
| it defines. For example, a package defines a setting with a default |
| value but needs to conditionally override the value based on another |
| setting value. |
| |
| Example: Ambiguity Violation Error Message |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| The following example shows the error message that newt outputs for an |
| ambiguity violation: |
| |
| .. code-block:: console |
| |
| 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/full: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/full`` |
| 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: |
| |
| .. code-block:: yaml |
| |
| #Package: sys/log/full |
| 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: Priority Violation Error Message |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| The following example shows the error message that newt outputs for a |
| priority violation where a package tries to change the setting that was |
| defined by another package at the same priority level: |
| |
| .. code-block:: console |
| |
| Error: Priority violations detected (Packages can only override settings defined by packages of lower priority): |
| Package: mgmt/newtmgr overriding setting: LOG_NEWTMGR defined by sys/log/full |
| |
| Setting history (newest -> oldest): |
| LOG_NEWTMGR: [sys/log/full:0] |
| |
| The above error occurs because the ``mgmt/newtmgr`` lib package |
| overrides the ``LOG_NEWTMGR`` setting that the ``sys/log/full`` lib |
| package defines. The following are excerpts of the definition and the |
| override from the ``syscfg.yml`` files that cause this error: |
| |
| .. code-block:: yaml |
| |
| #Package: sys/log/full |
| syscfg.defs: |
| LOG_NEWTMGR: |
| description: 'Enables or disables newtmgr command tool logging' |
| value: 0 |
| |
| #Package: mgmt/newtmgr |
| syscfg.vals: |
| LOG_NEWTMGR: 1 |
| |
| 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. |
| |
| .. code-block:: console |
| |
| 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: |
| |
| .. code-block:: yaml |
| |
| #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: |
| |
| .. code-block:: console |
| |
| 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: |
| |
| .. code-block:: yaml |
| |
| # 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 |
| |
| 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: |
| |
| .. code-block:: console |
| |
| |
| 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: |
| |
| .. code-block:: yaml |
| |
| #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: |
| |
| .. code-block:: console |
| |
| 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: |
| |
| .. code-block:: yaml |
| |
| # 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 |
| |
| 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. |
| |
| .. code-block:: console |
| |
| 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: |
| |
| .. code-block:: console |
| |
| 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. |
| |
| 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: |
| |
| .. code-block:: console |
| |
| Error: setting LOG_NEWTMGR redefined |
| |
| **Note:** Newt does not output the ``Setting history`` with duplicate |
| setting error messages. |
| |
| Override of Undefined System Configuration Setting |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| The ``newt build`` command ignores overrides of undefined system |
| configuration settings. The command does not print a warning when you |
| run it with the default log level. If you override a setting and the |
| value is not assigned to the setting, you may have misspelled the |
| setting name or a package no longer defines the setting. You have two |
| options to troubleshoot this problem: |
| |
| - Run the ``newt target config show`` command to see the configuration |
| setting definitions and overrides. |
| - Run the ``newt build -ldebug`` command to build your target with |
| DEBUG log level. |
| |
| Note: The ``newt build -ldebug`` command generates lots of output and we |
| recommend that you use the ``newt target config show`` command option. |
| |
| Example: Ignoring Override of Undefined Setting Message |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| The following example shows that the ``apps/slinky`` application |
| overrides the ``LOG_NEWTMGR`` setting but omits the **T** as an example |
| of an error and overrides the misspelled **LOG\_NEWMGR** setting. Here |
| is an excerpt from its ``syscfg.yml`` file: |
| |
| .. code-block:: yaml |
| |
| #package: apps/slinky |
| syscfg.vals: |
| # Enable the shell task. |
| SHELL_TASK: 1 |
| ... |
| |
| # Enable newtmgr commands. |
| STATS_NEWTMGR: 1 |
| LOG_NEWMGR: 1 |
| |
| The ``newt target config show slinky_sim`` command outputs the |
| following WARNING message: |
| |
| .. code-block:: console |
| |
| 2017/02/18 17:19:12.119 [WARNING] Ignoring override of undefined settings: |
| 2017/02/18 17:19:12.119 [WARNING] LOG_NEWMGR |
| 2017/02/18 17:19:12.119 [WARNING] NFFS_FLASH_AREA |
| 2017/02/18 17:19:12.119 [WARNING] Setting history (newest -> oldest): |
| 2017/02/18 17:19:12.119 [WARNING] LOG_NEWMGR: [apps/slinky:1] |
| 2017/02/18 17:19:12.119 [WARNING] NFFS_FLASH_AREA: [hw/bsp/native:FLASH_AREA_NFFS] |
| |
| The ``newt build -ldebug slinky_sim`` command outputs the following |
| DEBUG message: |
| |
| .. code-block:: console |
| |
| 2017/02/18 17:06:21.451 [DEBUG] Ignoring override of undefined settings: |
| 2017/02/18 17:06:21.451 [DEBUG] LOG_NEWMGR |
| 2017/02/18 17:06:21.451 [DEBUG] NFFS_FLASH_AREA |
| 2017/02/18 17:06:21.451 [DEBUG] Setting history (newest -> oldest): |
| 2017/02/18 17:06:21.451 [DEBUG] LOG_NEWMGR: [apps/slinky:1] |
| 2017/02/18 17:06:21.451 [DEBUG] NFFS_FLASH_AREA: [hw/bsp/native:FLASH_AREA_NFFS] |
| |
| BSP Package Overrides Undefined Configuration Settings |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| You might see a warning that indicates your application's BSP package is |
| overriding some undefined settings. As you can see from the previous |
| example, the WARNING message shows that the ``hw/bsp/native`` package is |
| overriding the undefined ``NFFS_FLASH_AREA`` setting. This is not an |
| error because of the way a BSP package defines and assigns its flash |
| areas to packages that use flash memory. |
| |
| A BSP package defines, in its ``bsp.yml`` file, a flash area map of the |
| flash areas on the board. A package that uses flash memory must define a |
| flash area configuration setting name. The BSP package overrides the |
| package's flash area setting with one of the flash areas from its flash |
| area map. A BSP package overrides the flash area settings for all |
| packages that use flash memory because it does not know the packages |
| that an application uses. When an application does not include one of |
| these packages, the flash area setting for the package is undefined. You |
| will see a message that indicates the BSP package overrides this |
| undefined setting. |
| |
| Here are excerpts from the ``hw/bsp/native`` package's ``bsp.yml`` and |
| ``syscfg.yml`` files for the ``slinky_sim`` target. The BSP package |
| defines the flash area map in its ``bsp.yml`` file and overrides the |
| flash area settings for all packages in its ``syscfg.yml`` file. The |
| ``slinky_sim`` target does not use the ``fs/nffs`` package which defines |
| the ``NFFS_FLASH_AREA`` setting. Newt warns that the ``hw/bsp/native`` |
| packages overrides the undefined ``NFFS_FLASH_AREA`` setting. |
| |
| .. code-block:: yaml |
| |
| # hw/bsp/native bsp.yml |
| bsp.flash_map: |
| areas: |
| # System areas. |
| FLASH_AREA_BOOTLOADER: |
| device: 0 |
| offset: 0x00000000 |
| size: 16kB |
| |
| ... |
| |
| FLASH_AREA_IMAGE_SCRATCH: |
| device: 0 |
| offset: 0x000e0000 |
| size: 128kB |
| |
| # 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 |
| |
| # hw/bsp/native syscfg.yml |
| syscfg.vals: |
| NFFS_FLASH_AREA: FLASH_AREA_NFFS |
| CONFIG_FCB_FLASH_AREA: FLASH_AREA_NFFS |
| REBOOT_LOG_FLASH_AREA: FLASH_AREA_REBOOT_LOG |