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.
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.
The following example shows the error message that newt outputs for an ambiguity violation:
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:
#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
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:
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:
#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
For flash_owner
type setting definitions, newt checks for the following violations:
The following example shows the error message that newt outputs for an undefined flash area.
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:
#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
The following example shows the error message that newt outputs when multiple settings are assigned the same flash area:
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:
# 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
$notnull
restriction does not have a value.The following example shows the error message that newt outputs when a setting with $notnull
restriction does not have a value:
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:
#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:
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:
# 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
For task_priority
type setting definitions, newt checks for the following violations:
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.
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.
The following example shows the error message that newt outputs when a setting is assigned an invalid task priority value:
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.
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:
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:
newt target config show
command to see the configuration setting definitions and overrides.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:
#package: apps/slinky syscfg.vals: # Enable the shell task. SHELL_TASK: 1 ... # Enable newtmgr commands. STATS_NEWTMGR: 1 LOG_NEWMGR: 1
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:
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]
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.
# 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