Minor edits to sysinitconfig.md file
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/0763285c Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/0763285c Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/0763285c Branch: refs/heads/develop Commit: 0763285c770647c67f32d3f7b8c15d7921143f30 Parents: 2f209db Author: aditihilbert <[email protected]> Authored: Fri Jan 6 16:21:55 2017 -0800 Committer: aditihilbert <[email protected]> Committed: Fri Jan 6 16:21:55 2017 -0800 ---------------------------------------------------------------------- docs/os/modules/sysinitconfig/sysinitconfig.md | 154 ++++++++++++-------- 1 file changed, 94 insertions(+), 60 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/0763285c/docs/os/modules/sysinitconfig/sysinitconfig.md ---------------------------------------------------------------------- diff --git a/docs/os/modules/sysinitconfig/sysinitconfig.md b/docs/os/modules/sysinitconfig/sysinitconfig.md index b4afe1b..8feb6d8 100644 --- a/docs/os/modules/sysinitconfig/sysinitconfig.md +++ b/docs/os/modules/sysinitconfig/sysinitconfig.md @@ -1,8 +1,8 @@ -##System Configuration and Initialization -This guide describes how Mynewt manages system configuration and initialization and shows you how to -configure Mynewt to use specific system initialization functions and system configuration setting values -for packages that you develop or use to build a target. This guide: +#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: * Assumes you have read the [Concepts](/os/get_started/vocabulary.md) section that describes the Mynewt package hierarchy and its use of the `pkg.yml` and `syscfg.yml` files. @@ -10,9 +10,7 @@ package hierarchy and its use of the `pkg.yml` and `syscfg.yml` files. package dependencies for your target build. * Covers only the system initialization for hardware independent packages. It does not cover the Board Support Package (BSP) and other hardware dependent system initialization. -Mynewt defines several configuration parameters in the `pkg.yml` and `syscfg.yml` files that let you -specify package initialization functions and define system configuration settings and values. -The newt tool uses this information from the `pkg.yml` and `syscfg.yml` files to: +Mynewt defines several configuration parameters in the `pkg.yml` and `syscfg.yml` files. The newt tool uses this information to: * Generate a system initialization function that calls all the package-specific system initialization functions. * Generate a system configuration header file that contains all the package configuration settings and values. @@ -23,19 +21,18 @@ The benefits with this approach include: * Allows Mynewt developers to reuse other packages and easily change their configuration settings without updating source or header files when implementing new packages. * Allows application developers to easily view the system configuration settings and values and determine the values to override for a target build. +<br> + ###System Configuration Setting Definitions and Values + A package can optionally: * Define and expose the system configuration settings to allow other packages to override the default setting values. * Override the system configuration setting values defined by the packages that it depends on. -You define package system configuration settings and override other package system configuration setting values -in the `syscfg.yml` file for a given package. - -####Defining System Configuration Settings -You use the `defs` parameter in a package `syscfg.yml` file to define the system configuration settings -for the package. `defs` is a mapping (or associative array) of system configuration setting definitions. It +You use the `defs` parameter in a `syscfg.yml` file to define the system configuration settings +for a package. `defs` is a mapping (or associative array) of system configuration setting definitions. It has the following syntax: ```no-highlight @@ -53,13 +50,15 @@ syscfg.defs: restrictions: ``` -Each system configuration setting definition consists of the following key-value mapping: -* A system configuration setting name for the key, such as `PKGA_SYSCFG_NAME1` in the syntax example above. -Note: A system configuration setting name must be unique. newt aborts the build -when multiple packages define the same system configuration setting. -* A mapping of system configuration setting fields for the value. Each field is a key-value pair of attributes for -the setting. The field keys are `description`, `value`, `type`, and `restrictions`. They are described in +<br> + +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 +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: <table style="width:90%", align="center"> @@ -69,13 +68,13 @@ following table: </tr> <tr> <td><code>description</code></td> -<td>Describes the usage for the setting. This field is optional.</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. This field is required. The value depends on the <code>type</code> that you specify and can be the empty string. +<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. This field is optional. You can specify one of three types: +<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: @@ -94,10 +93,9 @@ defined in the BSP flash map for your target board. </tr> <tr> <td><code>restrictions</code></td> -<td>Specifies a list of restrictions on the setting value. This is an optional field. You can specify two formats: +<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. A package must -override the value when the default <code>value</code> is the empty string. +<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> @@ -111,9 +109,12 @@ override the value when the default <code>value</code> is the empty string. </td> </tr> </table> -**Examples** -The following example is an excerpt from the `sys/log` package `syscfg.yml` file. It defines the +<br> + +####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 to enable or disable the newtmgr logging feature. @@ -133,7 +134,9 @@ syscfg.defs: ``` -The following example excerpt from the `net/nimble/controller` package `syscfg.yml` file defines the `BLE_LL_PRIO` +<br> + +**Example 2:** The following example is an excerpt from the `net/nimble/controller` package `syscfg.yml` file. It defines the `BLE_LL_PRIO` configuration setting with a `task_priority` type and assigns task priority 0 to the BLE link layer task. ```no-highlight @@ -146,9 +149,9 @@ syscfg.defs: ``` -The following example excerpt from the `fs/nffs` package `syscfg.yml` file defines the `NFFS_FLASH_AREA` -configuration setting with a `flash_owner` type to specify the flash area to use for the Newtron Flash File System. -It also indicates that the setting must have a value so a higher priority package must set the value. +<br> + +**Example 3:** The following example is an excerpt from the `fs/nffs` package `syscfg.yml` file. ```no-highlight @@ -159,18 +162,39 @@ syscfg.defs: value: restrictions: - $notnull +``` +It defines the `NFFS_FLASH_AREA` configuration setting with a `flash_owner` 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 `bsp.yml` file. For example, the `bsp.yml` for nrf52dk board (`hw/bsp/nrf52dk/bsp.yml`) defines an area named `FLASH_AREA_NFFS`: + +```no-highlight + FLASH_AREA_NFFS: + user_id: 1 + device: 0 + offset: 0x0007d000 + size: 12kB ``` +The `syscfg.yml` file for the same board (`hw/bsp/nrf52dk/syscfg.yml`) specifies that the above area be used for `NFFS_FLASH_AREA`. -####Overriding System Configuration Setting Values +```no-highlight +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 +``` + +Note that the `fs/nffs/syscfg.yml` file indicates that the `NFFS_FLASH_AREA` 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. + +<br> -You use the `vals` parameter in `syscfg.yml` files to override the system configuration setting default values defined +###Overriding System Configuration Setting Values + +A package may use the `vals` parameter in its `syscfg.yml` file to override the configuration values defined by other packages. This mechanism allows: * Mynewt developers to implement a package and easily override the system configuration setting values that are defined by the packages it depends on. -* Application developers to easily override the system configuration setting values and build a customized target. - You can use the `newt target config <target-name>` command to check all the system configuration setting definitions and +* Application developers to easily and cleanly override default configuration settings in a single place and build a customized target. You can use the `newt target config <target-name>` command to check all the system configuration setting definitions and values in your target to determine the setting values to override. See [newt target](/newt/command_list/newt_target.md). `vals` specifies the mappings of system configuration setting name-value pairs as follows: @@ -184,13 +208,13 @@ syscfg.vals: PKGN_SYSCFG_NAME1: VALUEN ``` -newt ignores overrides of undefined system configuration settings. +Note: The newt tool ignores overrides of undefined system configuration settings. + +<br> -**Resolving Override Conflicts** +####Resolving Override Conflicts -newt uses package priorities to determine whether a package can override a value and -to resolve conflicts when multiple packages override the same system configuration setting. -The following rules apply: +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: * A package can only override the default values of system configuration settings that are defined by lower priority packages. @@ -210,11 +234,12 @@ The following package types are listed from highest to lowest priority: It is recommended that you override defaults at the target level instead of updating individual package `syscfg.yml` files. -**Examples** +<br> + +####Examples of Overrides -The following example is an excerpt from the `apps/slinky` package `syscfg.yml` file. The package overrides, -in addition to other packages, the `sys/log` package system configuration settings defined in the -previous example. It changes the LOG_NEWTMGR system configuration setting value from `0` to `1`. +**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`. ```no-highlight @@ -230,7 +255,7 @@ syscfg.vals: ``` -The following example are excerpts from the `hw/bsp/native` package `bsp.yml` and `syscfg.yml` files. +**Example 5:** The following example are excerpts from the `hw/bsp/native` package `bsp.yml` and `syscfg.yml` files. The package defines the flash areas for the BSP flash map in the `bsp.yml` file, and sets the `NFFS_FLASH_AREA` configuration setting value to use the flash area named `FLASH_AREA_NFFS` in the `syscfg.yml` file. @@ -264,11 +289,13 @@ syscfg.vals: ``` -####Generated syscfg.h +<br> + +###Generated syscfg.h -newt processes all the package `syscfg.yml` files and generates the +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 definition. newt creates a `#define` for a system configuration 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 "_". @@ -276,14 +303,12 @@ setting definition. newt creates a `#define` for a system configuration setting 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 +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. -Note: You only need to include `syscfg/syscfg.h` in your source files to access the `syscfg.h` file. newt sets the correct include path to build your target. +**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. -**syscfg.h Example** - -This example is an excerpt from the `syscfg.h` file generated for an app/slinky target. It lists +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. @@ -321,6 +346,8 @@ for the `LOG_NEWTMGR` settings. #endif ``` +<br> + ### System Initialization An application's `main()` function must first call the Mynewt `sysinit()` function to @@ -328,6 +355,7 @@ initialize the software before it performs any other processing. `sysinit()` calls the `sysinit_app()` function to perform system initialization for the packages in the target. You can, optionally, specify an initialization function that `sysinit_app()` calls to initialize a package. + A package init function must have the following prototype: ```no-highlight @@ -344,21 +372,24 @@ You specify an init function in the `pkg.yml` file for a package as follows: pkg.init_function: pkg_init_func_name - `pkg_init_func_name` is the C function name of package init function. + where `pkg_init_func_name` is the C function name of package init function. * Use the `init_stage` parameter to specify when to call the package init function. pkg.init_stage: stage_number - `stage_number` is a number that indicates when this init function is called relative to the other + 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> #### Generated sysinit_app() Function -newt processes the `init_function` and `init_stage` parameters in all the pkg.yml files for a target, + +The newt tool processes the `init_function` and `init_stage` parameters in all the pkg.yml files for a target, generates the `sysinit_app()` function in the `<target-path>/generated/src/<target-name>-sysinit_app.c` file, and includes the file in the build. Here is an example `sysinit_app()` function: @@ -416,6 +447,8 @@ sysinit_app(void) ``` +<br> + ###Conditional Configurations You can use the system configuration setting values to conditionally specify parameter values in `pkg.yml` and `syscfg.yml` files. The syntax is: @@ -428,6 +461,7 @@ parameter_name.PKGA_SYSCFG_NAME: ``` This specifies that `parameter_value` is only set for `parameter_name` if the `PKGA_SYSCFG_NAME` configuration setting value is non-zero. Here is an example from the `libs/os` package `pkg.yml` file: + ``` pkg.deps: - sys/sysinit @@ -437,7 +471,7 @@ pkg.deps.OS_CLI - sys/shell ``` -This example specfies that the `os` package depends on the `sysinit` and `mem` packages, and also depends on the +This example specifies that the `os` package depends on the `sysinit` and `mem` packages, and also depends on the `shell` package when `OS_CLI` is enabled. -newt aborts the build when it detects circular conditional dependencies. +The newt tool aborts the build when it detects circular conditional dependencies.
