fixed typos PR #148
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/637e3d81 Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/637e3d81 Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/637e3d81 Branch: refs/heads/asf-site Commit: 637e3d81252d56ae5cd80f84bffdca42baba35ec Parents: 44e6c0d Author: aditihilbert <[email protected]> Authored: Thu Feb 2 18:13:45 2017 -0800 Committer: aditihilbert <[email protected]> Committed: Thu Feb 2 18:13:45 2017 -0800 ---------------------------------------------------------------------- develop/mkdocs/search_index.json | 4 ++-- develop/os/modules/sysinitconfig/sysinitconfig/index.html | 2 +- latest/mkdocs/search_index.json | 4 ++-- latest/os/modules/sysinitconfig/sysinitconfig/index.html | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/637e3d81/develop/mkdocs/search_index.json ---------------------------------------------------------------------- diff --git a/develop/mkdocs/search_index.json b/develop/mkdocs/search_index.json index 8b86886..240c0f7 100644 --- a/develop/mkdocs/search_index.json +++ b/develop/mkdocs/search_index.json @@ -7762,12 +7762,12 @@ }, { "location": "/os/modules/sysinitconfig/sysinitconfig/", - "text": "System Configuration and Initialization\n\n\nThis guide describes how Mynewt manages system configuration and initialization. It shows you how to \ntell Mynewt to use default or customized values to initialize packages that you develop or use to build a target. This guide:\n\n\n\n\nAssumes you have read the \nConcepts\n section that describes the Mynewt \npackage hierarchy and its use of the \npkg.yml\n and \nsyscfg.yml\n files. \n\n\nAssumes you have read the \nNewt Tool Theory of Operation\n and are familiar with how newt determines \npackage dependencies for your target build.\n\n\nCovers only the system initialization for hardware independent packages. It does not cover the Board Support Package (BSP) and other hardware dependent system initialization. \n\n\n\n\nMynewt defines several configuration parameters in the \npkg.yml\n and \nsyscfg.yml\n files. The newt tool uses this information to: \n\n\n\n\nGenerate a system initialization function that calls all the package-specific ystem initialization functions. \n\n\nGenerate a system configuration header file that contains all the package configuration settings and values.\n\n\nDisplay the system configuration settings and values in the \nnewt target config\n command.\n\n\n\n\nThe benefits with this approach include:\n\n\n\n\nAllows Mynewt developers to reuse other packages and easily change their configuration settings without updating source or header files when implementing new packages.\n\n\nAllows application developers to easily view the system configuration settings and values and determine the values to override for a target build.\n\n\n\n\n\n\nSystem Configuration Setting Definitions and Values\n\n\nA package can optionally:\n\n\n\n\nDefine and expose the system configuration settings to allow other packages to override \nthe default setting values. \n\n\nOverride the system configuration setting values defined by the packages that it depends on. \n\n\n\n\nYou use the \ndef s\n parameter in a \nsyscfg.yml\n file to define the system configuration settings \nfor a package. \ndefs\n is a mapping (or associative array) of system configuration setting definitions. It \nhas the following syntax: \n\n\nsyscfg.defs:\n PKGA_SYSCFG_NAME1:\n description:\n value:\n type:\n restrictions:\n PKGA_SYSCFG_NAME2:\n description:\n value:\n type:\n restrictions:\n\n\n\n\n\n\n\nEach setting definition consists of the following key-value mapping: \n\n\n\n\nA setting name for the key, such as \nPKGA_SYSCFG_NAME1\n in the syntax example above.\n\nNote:\n A system configuration setting name must be unique. The newt tool aborts the build \nwhen multiple packages define the same setting. \n\n\nA mapping of fields for the value. Each field itself is a key-value pair of attributes. The field keys are \ndescription\n, \nvalue\n, \ntype\n, and \nrestrictions\n. They are described in \nfollowing table:\n\n\n\n\n\n\n\n\nFiel d\n\n\nDescription\n\n\n\n\n\n\ndescription\n\n\nDescribes the usage for the setting. \nThis field is optional.\n\n\n\n\nvalue\n\n\nSpecifies the default value for the setting. \nThis field is required.\n The value depends on the \ntype\n that you specify and can be an empty string. \n\n\n\ntype\n\n\nSpecifies the data type for the \nvalue\n field. \nThis field is optional.\n You can specify one of three types:\n\n\n\nraw\n - The \nvalue\n data is uninterpreted. This is the default \ntype\n.\n\n\ntask_priority\n - Specifies a Mynewt task priority number. The task priority number assigned to each setting must be unique and between 0 and 239. \nvalue\n can be one of the following: \n\n\n\nA number between 0 and 239 - The task priority number to use for the setting.\n\n\nany\n - Specify \nany\n to have newt automatically assign a priority for the setting. \nnewt alphabetically orders all system configuration settings of this type and assigns the next highest available \ntask priorit y number to each setting. \n\n\n\n\n\n\nflash_owner\n - Specifies a flash area. The \nvalue\n should be the name of a flash area \ndefined in the BSP flash map for your target board. \n\n\n\n\n\n\n\n\n\n\n\nrestrictions\n\n\nSpecifies a list of restrictions on the setting value. \nThis field is optional.\n You can specify two formats:\n\n\n\n$notnull\n - 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. \n\n\n\n\n\nexpression\n - Specifies a boolean expression of the form \n[!]\n>[if \n>]\n\n\nExamples:\n\n\n\nrestrictions: !LOG_FCB\n - When this setting is enabled, \nLOG_FCB\n must be disabled.\n\nrestrictions: LOG_FCB if 0 \n - When this setting is disabled, \nLOG_FCB\n must be enabled.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\nExamples of Configuration Settings\n\n\nExample 1:\n The following example is an excerpt from the \nsys/log/full\n package \nsyscfg.yml\n file. It defines the \n\nLOG_LEVEL\n configuration setting to specify the log level and the \nLOG_NEWTMGR\n configuration setting to specify whether\nto enable or disable the newtmgr logging feature.\n\n\nsyscfg.defs:\n LOG_LEVEL:\n description: \nLog Level\n\n value: 0\n type: raw\n\n ... \n\n LOG_NEWTMGR: \n description: \nEnables or disables newtmgr command tool logging\n\n value: 0\n\n\n\n\n\n\n\nExample 2:\n The following example is an excerpt from the \nnet/nimble/controller\n package \nsyscfg.yml\n file. It defines the \nBLE_LL_PRIO\n \nconfiguration setting with a \ntask_priority\n type and assigns task priority 0 to the BLE link layer task.\n\n\nsyscfg.defs:\n BLE_LL_PRIO:\n description: \nBLE link layer task priority\n\n type: \ntask_priority\n\n value: 0\n\n\n\n\n\n\n\nExample 3:\n The following example is an excerpt from the \nfs/nffs\n package \nsyscfg.yml\n file. \n\n\nsyscfg.de fs:\n NFFS_FLASH_AREA:\n description: \nThe flash area to use for the Newtron Flash File System\n\n type: flash_owner\n value:\n restrictions:\n - $notnull\n\n\n\n\n\nIt defines the \nNFFS_FLASH_AREA\n configuration setting with a \nflash_owner\n 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 \nbsp.yml\n file. For example, the \nbsp.yml\n for nrf52dk board (\nhw/bsp/nrf52dk/bsp.yml\n) defines an area named \nFLASH_AREA_NFFS\n:\n\n\n FLASH_AREA_NFFS:\n user_id: 1\n device: 0\n offset: 0x0007d000\n size: 12kB\n\n\n\n\n\nThe \nsyscfg.yml\n file for the same board (\nhw/bsp/nrf52dk/syscfg.yml\n) specifies that the above area be used for \nNFFS_FLASH_AREA\n.\n\n\nsyscfg.vals:\n CONFIG_FCB_FLASH_AREA: FLASH_AREA_NFFS\n REBOOT_LOG_FLASH_AREA: FLASH_AREA_REBOOT_LOG\n NFFS_FLASH_AREA: FLASH_AREA_NFFS\n COREDU MP_FLASH_AREA: FLASH_AREA_IMAGE_1\n\n\n\n\n\nNote that the \nfs/nffs/syscfg.yml\n file indicates that the \nNFFS_FLASH_AREA\n 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.\n\n\n\n\nOverriding System Configuration Setting Values\n\n\nA package may use the \nvals\n parameter in its \nsyscfg.yml\n file to override the configuration values defined\nby other packages. This mechanism allows:\n\n\n\n\nMynewt developers to implement a package and easily override the system configuration setting values \n that are defined by the packages it depends on. \n\n\nApplication developers to easily and cleanly override default configuration settings in a single place and build a customized target. You can use the \nnewt target config \ntarget-name\n command to check all the system configuration setting definitions and\n values in y our target to determine the setting values to override. See \nnewt target\n. \n\n\n\n\nvals\n specifies the mappings of system configuration setting name-value pairs as follows: \n\n\nsyscfg.vals:\n PKGA_SYSCFG_NAME1: VALUE1\n PKGA_SYSCFG_NAME2: VALUE2\n ...\n PKGN_SYSCFG_NAME1: VALUEN\n\n\n\n\n\nNote\n: The newt tool ignores overrides of undefined system configuration settings. \n\n\n\n\nResolving Override Conflicts\n\n\nThe 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:\n\n\n\n\nA package can only override the default values of system configuration settings that \n are defined by lower priority packages.\n\n\nWhen packages with different priorities override the same system configuration setting value, newt uses \n the value from the highest priority package.\n\n\nPackages of equal priority cannot ov erride the same system configuration setting with different values. \n newt aborts the build unless a higher priority package also overrides the value.\n\n\n\n\nThe following package types are listed from highest to lowest priority:\n\n\n\n\nTarget\n\n\nApp\n\n\nunittest - A target can include either an app or unit test package, but not both.\n\n\nBSP\n\n\nLib - Includes all other system level packages such as os, lib, sdk, and compiler. (Note that a Lib package cannot override other Lib package settings.)\n\n\n\n\nIt is recommended that you override defaults at the target level instead of updating individual \npackage \nsyscfg.yml\n files.\n\n\n\n\nExamples of Overrides\n\n\nExample 4:\n The following example is an excerpt from the \napps/slinky\n package \nsyscfg.yml\n file. The application package overrides, \nin addition to other packages, the \nsys/log/full\n package system configuration settings defined in \nExample 1\n. It changes the LOG_NEWTMGR system configuration setti ng value from \n0\n to \n1\n.\n\n\nsyscfg.vals:\n # Enable the shell task.\n SHELL_TASK: 1\n\n ...\n\n # Enable newtmgr commands.\n STATS_NEWTMGR: 1\n LOG_NEWTMGR: 1\n\n\n\n\n\nExample 5:\n The following example are excerpts from the \nhw/bsp/native\n package \nbsp.yml\n and \nsyscfg.yml\n files. \nThe package defines the flash areas for the BSP flash map in the \nbsp.yml\n file, and sets the \nNFFS_FLASH_AREA\n \nconfiguration setting value to use the flash area named \nFLASH_AREA_NFFS\n in the \nsyscfg.yml\n file.\n\n\nbsp.flash_map:\n areas:\n # System areas.\n FLASH_AREA_BOOTLOADER:\n device: 0\n offset: 0x00000000\n size: 16kB\n\n ...\n\n # User areas.\n FLASH_AREA_REBOOT_LOG:\n user_id: 0\n device: 0\n offset: 0x00004000\n size: 16kB\n FLASH_AREA_NFFS:\n user_id: 1\n device: 0\n offset: 0x00008000\n size: 32kB\n\n\nsyscfg.vals:\n NFFS_FLASH_AREA: FLASH_AREA_NFFS\n\n\n\n\n\n\n\nGenerated syscfg.h and Referencing System Configuration Settings\n\n\nThe newt tool processes all the package \nsyscfg.yml\n files and generates the\n\ntarget-path\n/generated/include/syscfg/syscfg.h\n include file with \n#define\n statements for each system configuration \nsetting defined. Newt creates a \n#define\n for a setting name as follows: \n\n\n\n\nAdds the prefix \nMYNEWT_VAL_\n.\n\n\nReplaces all occurrences of \"/\", \"-\", and \" \" in the setting name with \"_\".\n\n\nConverts all characters to upper case.\n\n\n\n\nFor example, the #define for my-config-name setting name is MYNEWT_VAL_MY_CONFIG_NAME.\n\n\nNewt groups the settings in \nsyscfg.h\n by the packages that defined them. It also indicates the \npackage that changed a system configuration setting value. \n\n\nYou must use the \nMYNEWT_VAL()\n macro to reference a #define of a setting name in your header and source fi les. \nFor example, to reference the \nmy-config-name\n setting name, you use \nMYNEWT_VAL(MY_CONFIG_NAME)\n.\n\n\nNote:\n You only need to include \nsyscfg/syscfg.h\n in your source files to access the \nsyscfg.h\n file. The newt tool sets the correct include path to build your target. \n\n\nExample of syscfg.h and How to Reference a Setting Name\n\n\nExample 6\n: The following example are excerpts from a sample \nsyscfg.h\n file generated for an app/slinky target and \nfrom the \nsys/log/full\n package \nlog.c\n file that shows how to reference a setting name.\n\n\nThe \nsyscfg.h\n file shows the \nsys/log/full\n package definitions and also indicates that \napp/slinky\n \nchanged the value for the \nLOG_NEWTMGR\n settings. \n\n\n/**\n * This file was generated by Apache Newt (incubating) version: 1.0.0-dev\n */\n\n#ifndef H_MYNEWT_SYSCFG_\n#define H_MYNEWT_SYSCFG_\n\n/**\n * This macro exists to ensure code includes this header when needed. If code\n * checks the existence of a setting directly via ifdef without including this\n * header, the setting macro will silently evaluate to 0. In contrast, an\n * attempt to use these macros without including this header will result in a\n * compiler error.\n */\n#define MYNEWT_VAL(x) MYNEWT_VAL_ ## x\n\n\n ...\n\n/*** kernel/os */\n#ifndef MYNEWT_VAL_MSYS_1_BLOCK_COUNT\n#define MYNEWT_VAL_MSYS_1_BLOCK_COUNT (12)\n#endif\n\n#ifndef MYNEWT_VAL_MSYS_1_BLOCK_SIZE\n#define MYNEWT_VAL_MSYS_1_BLOCK_SIZE (292)\n#endif\n\n ...\n\n/*** sys/log/full */\n\n#ifndef MYNEWT_VAL_LOG_LEVEL\n#define MYNEWT_VAL_LOG_LEVEL (0)\n#endif\n\n ...\n\n/* Overridden by apps/slinky (defined by sys/log/full) */\n#ifndef MYNEWT_VAL_LOG_NEWTMGR\n#define MYNEWT_VAL_LOG_NEWTMGR (1)\n#endif\n\n#endif\n\n\n\n\n\nThe \nlog_init()\n function in the \nsys/log/full/src/log.c\n file initializes the \nsys/log/full\n package. It checks the \n\nLOG_NEWTMGR\n setting value, using \nMYNEWT_VAL(LOG_NEWTMGR)\n, to determi ne whether the target application\nhas enabled the \nnewtmgr log\n functionality. It only registers the the callbacks to process the\n\nnewtmgr log\n commands when the setting value is non-zero.\n\n\nvoid\nlog_init(void)\n{\n int rc;\n\n /* Ensure this function only gets called by sysinit. */\n SYSINIT_ASSERT_ACTIVE();\n\n (void)rc;\n\n if (log_inited) {\n return;\n }\n log_inited = 1;\n ...\n\n#if MYNEWT_VAL(LOG_NEWTMGR)\n rc = log_nmgr_register_group();\n SYSINIT_PANIC_ASSERT(rc == 0);\n#endif\n}\n\n\n\n\n\n\n\nSystem Initialization\n\n\nDuring system startup, Mynewt creates a default event queue and a main task to process events from this queue. \nYou can override the \nOS_MAIN_TASK_PRIO\n and \nOS_MAIN_TASK_STACK_SIZE\n setting values defined by the \n\nkernel/os\n package to specify different task priority and stack size values.\n\n\nYour application's \nmain()\n function executes in the context of the main task and must perform the foll owing:\n\n\n\n\nAt the start of \nmain()\n, call the Mynewt \nsysinit()\n function to initialize \nthe packages before performing any other processing.\n\n\nAt the end of \nmain()\n, wait for and dispatch events from the default event queue in a forever loop. \n\n\n\n\nNote:\n You must include the \nsysinit/sysinit.h\n header file to access the \nsysinit()\n function.\n\n\nHere is an example of a \nmain()\n function:\n\n\nint\nmain(int argc, char **argv)\n{\n /* First, call sysinit() to perform the system and package initialization */\n sysinit();\n\n ... other application initialization processing....\n\n\n /* Last, process events from the default event queue. */\n while (1) {\n os_eventq_run(os_eventq_dflt_get());\n }\n /* main never returns */ \n}\n\n\n\n\n\n\n\nSpecifying Package Initialization Functions\n\n\nThe \nsysinit()\n function calls the \nsysinit_app()\n function to perform system \ninitialization for the packages in the target. You ca n, optionally, \nspecify one or more package initialization functions \nthat \nsysinit_app()\n calls to initialize a package. \n\n\nA package initialization function must have the following prototype:\n\n\nvoid init_func_name(void)\n\n\n\n\n\nPackage initialization functions are called in stages to ensure that lower priority\npackages are initialized before higher priority packages. A stage is an \ninteger value, 0 or higher, that specifies when an initialization function is \ncalled. Mynewt calls the package initialization functions \nin increasing stage number order. The call order for initialization functions with the \nsame stage number depends on the order the packages are processed,\nand you cannot rely on a specific call order for these functions. \n\n\nYou use the \npkg.init\n parameter in the \n\npkg.yml\n file to specify an initialization function and the stage number to call the function.\nYou can specify multiple initialization functions, with a different stage numbe r for each function,\nfor the parameter values. This feature allows packages with interdependencies to\nperform initialization in multiple stages. \n\n\nThe \npkg.init\n parameter has the following syntax in the \npkg.yml\n file: \n\n\npkg.init: \n pkg_init_func1_name: pkg_init_func1_stage \n pkg_init_func2_name: pkg_init_func2_stage \n\n ...\n\n pkg_init_funcN_name: pkg_init_funcN_stage\n\n\n\n\n\nwhere \npkg_init_func#_name\n is the C function name of an initialization function, and \npkg_init_func#_stage\n \nis an integer value, 0 or higher, that indicates the stage when the \npkg_init_func#_name\n function is called. \n\n\nNote:\n The \npkg.init_function\n and \npkg.init_stage\n parameters introduced in a previous release for \nspecifying a package initialization function and a stage number are deprecated and have been \nretained to support the legacy format. They will not \nbe maintained for future releases and we recommend that you migrate to use the \npkg.init\n parameter.\n\n\n\n\nGenerated sysinit_app() Function\n\n\nThe newt tool processes the \npkg.init\n parameters in all the \npkg.yml\n files for a target,\ngenerates the \nsysinit_app()\n function in the \ntarget-path\n/generated/src/\ntarget-name\n-sysinit_app.c\n file, and \nincludes the file in the build. Here is an example \nsysinit_app()\n function:\n\n\n**\n * This file was generated by Apache Newt (incubating) version: 1.0.0-dev\n */\n\n#if !SPLIT_LOADER\n\nvoid split_app_init(void);\nvoid os_pkg_init(void);\nvoid imgmgr_module_init(void);\n\n ...\n\nvoid stats_module_init(void);\n\nvoid\nsysinit_app(void)\n{\n\n /*** Stage 0 */\n /* 0.0: kernel/os */\n os_pkg_init();\n\n /*** Stage 2 */\n /* 2.0: sys/flash_map */\n flash_map_init();\n\n /*** Stage 10 */\n /* 10.0: sys/stats/full */\n stats_module_init();\n\n /*** Stage 20 */\n /* 20.0: sys/console/full */\n console_pkg_init();\n\n /*** Stage 100 */\n /* 100.0: sys/log /full */\n log_init();\n /* 100.1: sys/mfg */\n mfg_init();\n\n ....\n\n /*** Stage 300 */\n /* 300.0: sys/config */ \n config_pkg_init();\n\n /*** Stage 500 */\n /* 500.0: sys/id */\n id_init();\n /* 500.1: sys/shell */\n shell_init();\n\n ...\n\n /* 500.4: mgmt/imgmgr */\n imgmgr_module_init();\n\n /*** Stage 501 */\n /* 501.0: mgmt/newtmgr/transport/nmgr_shell */\n nmgr_shell_pkg_init();\n}\n#endif\n\n\n\n\n\n\n\nConditional Configurations\n\n\nYou can use the system configuration setting values to conditionally specify parameter values\nin \npkg.yml\n and \nsyscfg.yml\n files. The syntax is:\n\n\nparameter_name.PKGA_SYSCFG_NAME:\n parameter_value\n\n\n\n\n\nThis specifies that \nparameter_value\n is only set for \nparameter_name\n if the \nPKGA_SYSCFG_NAME\n configuration setting value \nis non-zero. Here is an example from the \nlibs/os\n package \npkg.yml\n file:\n\n\npkg.deps:\n - sys/sysinit\n - ut il/mem\n\npkg.deps.OS_CLI\n - sys/shell\n\n\n\n\n\nThis example specifies that the \nos\n package depends on the \nsysinit\n and \nmem\n packages, and also depends on the \n\nshell\n package when \nOS_CLI\n is enabled. \n\n\nThe newt tool aborts the build when it detects circular conditional dependencies.", + "text": "System Configuration and Initialization\n\n\nThis guide describes how Mynewt manages system configuration and initialization. It shows you how to \ntell Mynewt to use default or customized values to initialize packages that you develop or use to build a target. This guide:\n\n\n\n\nAssumes you have read the \nConcepts\n section that describes the Mynewt \npackage hierarchy and its use of the \npkg.yml\n and \nsyscfg.yml\n files. \n\n\nAssumes you have read the \nNewt Tool Theory of Operation\n and are familiar with how newt determines \npackage dependencies for your target build.\n\n\nCovers only the system initialization for hardware independent packages. It does not cover the Board Support Package (BSP) and other hardware dependent system initialization. \n\n\n\n\nMynewt defines several configuration parameters in the \npkg.yml\n and \nsyscfg.yml\n files. The newt tool uses this information to: \n\n\n\n\nGenerate a system initialization function that calls all the package-specific system initialization functions. \n\n\nGenerate a system configuration header file that contains all the package configuration settings and values.\n\n\nDisplay the system configuration settings and values in the \nnewt target config\n command.\n\n\n\n\nThe benefits with this approach include:\n\n\n\n\nAllows Mynewt developers to reuse other packages and easily change their configuration settings without updating source or header files when implementing new packages.\n\n\nAllows application developers to easily view the system configuration settings and values and determine the values to override for a target build.\n\n\n\n\n\n\nSystem Configuration Setting Definitions and Values\n\n\nA package can optionally:\n\n\n\n\nDefine and expose the system configuration settings to allow other packages to override \nthe default setting values. \n\n\nOverride the system configuration setting values defined by the packages that it depends on. \n\n\n\n\nYou use the \nde fs\n parameter in a \nsyscfg.yml\n file to define the system configuration settings \nfor a package. \ndefs\n is a mapping (or associative array) of system configuration setting definitions. It \nhas the following syntax: \n\n\nsyscfg.defs:\n PKGA_SYSCFG_NAME1:\n description:\n value:\n type:\n restrictions:\n PKGA_SYSCFG_NAME2:\n description:\n value:\n type:\n restrictions:\n\n\n\n\n\n\n\nEach setting definition consists of the following key-value mapping: \n\n\n\n\nA setting name for the key, such as \nPKGA_SYSCFG_NAME1\n in the syntax example above.\n\nNote:\n A system configuration setting name must be unique. The newt tool aborts the build \nwhen multiple packages define the same setting. \n\n\nA mapping of fields for the value. Each field itself is a key-value pair of attributes. The field keys are \ndescription\n, \nvalue\n, \ntype\n, and \nrestrictions\n. They are described in \nfollowing table:\n\n\n\n\n\n\n\n\nFie ld\n\n\nDescription\n\n\n\n\n\n\ndescription\n\n\nDescribes the usage for the setting. \nThis field is optional.\n\n\n\n\nvalue\n\n\nSpecifies the default value for the setting. \nThis field is required.\n The value depends on the \ntype\n that you specify and can be an empty string. \n\n\n\ntype\n\n\nSpecifies the data type for the \nvalue\n field. \nThis field is optional.\n You can specify one of three types:\n\n\n\nraw\n - The \nvalue\n data is uninterpreted. This is the default \ntype\n.\n\n\ntask_priority\n - Specifies a Mynewt task priority number. The task priority number assigned to each setting must be unique and between 0 and 239. \nvalue\n can be one of the following: \n\n\n\nA number between 0 and 239 - The task priority number to use for the setting.\n\n\nany\n - Specify \nany\n to have newt automatically assign a priority for the setting. \nnewt alphabetically orders all system configuration settings of this type and assigns the next highest available \ntask priori ty number to each setting. \n\n\n\n\n\n\nflash_owner\n - Specifies a flash area. The \nvalue\n should be the name of a flash area \ndefined in the BSP flash map for your target board. \n\n\n\n\n\n\n\n\n\n\n\nrestrictions\n\n\nSpecifies a list of restrictions on the setting value. \nThis field is optional.\n You can specify two formats:\n\n\n\n$notnull\n - 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. \n\n\n\n\n\nexpression\n - Specifies a boolean expression of the form \n[!]\n>[if \n>]\n\n\nExamples:\n\n\n\nrestrictions: !LOG_FCB\n - When this setting is enabled, \nLOG_FCB\n must be disabled.\n\nrestrictions: LOG_FCB if 0 \n - When this setting is disabled, \nLOG_FCB\n must be enabled.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\nExamples of Configuration Settings\n\n\nExample 1:\n The following example is an excerpt from the \nsys/log/full\n package \nsyscfg.yml\n file. It defines the \n\nLOG_LEVEL\n configuration setting to specify the log level and the \nLOG_NEWTMGR\n configuration setting to specify whether\nto enable or disable the newtmgr logging feature.\n\n\nsyscfg.defs:\n LOG_LEVEL:\n description: \nLog Level\n\n value: 0\n type: raw\n\n ... \n\n LOG_NEWTMGR: \n description: \nEnables or disables newtmgr command tool logging\n\n value: 0\n\n\n\n\n\n\n\nExample 2:\n The following example is an excerpt from the \nnet/nimble/controller\n package \nsyscfg.yml\n file. It defines the \nBLE_LL_PRIO\n \nconfiguration setting with a \ntask_priority\n type and assigns task priority 0 to the BLE link layer task.\n\n\nsyscfg.defs:\n BLE_LL_PRIO:\n description: \nBLE link layer task priority\n\n type: \ntask_priority\n\n value: 0\n\n\n\n\n\n\n\nExample 3:\n The following example is an excerpt from the \nfs/nffs\n package \nsyscfg.yml\n file. \n\n\nsyscfg.d efs:\n NFFS_FLASH_AREA:\n description: \nThe flash area to use for the Newtron Flash File System\n\n type: flash_owner\n value:\n restrictions:\n - $notnull\n\n\n\n\n\nIt defines the \nNFFS_FLASH_AREA\n configuration setting with a \nflash_owner\n 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 \nbsp.yml\n file. For example, the \nbsp.yml\n for nrf52dk board (\nhw/bsp/nrf52dk/bsp.yml\n) defines an area named \nFLASH_AREA_NFFS\n:\n\n\n FLASH_AREA_NFFS:\n user_id: 1\n device: 0\n offset: 0x0007d000\n size: 12kB\n\n\n\n\n\nThe \nsyscfg.yml\n file for the same board (\nhw/bsp/nrf52dk/syscfg.yml\n) specifies that the above area be used for \nNFFS_FLASH_AREA\n.\n\n\nsyscfg.vals:\n CONFIG_FCB_FLASH_AREA: FLASH_AREA_NFFS\n REBOOT_LOG_FLASH_AREA: FLASH_AREA_REBOOT_LOG\n NFFS_FLASH_AREA: FLASH_AREA_NFFS\n CORED UMP_FLASH_AREA: FLASH_AREA_IMAGE_1\n\n\n\n\n\nNote that the \nfs/nffs/syscfg.yml\n file indicates that the \nNFFS_FLASH_AREA\n 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.\n\n\n\n\nOverriding System Configuration Setting Values\n\n\nA package may use the \nvals\n parameter in its \nsyscfg.yml\n file to override the configuration values defined\nby other packages. This mechanism allows:\n\n\n\n\nMynewt developers to implement a package and easily override the system configuration setting values \n that are defined by the packages it depends on. \n\n\nApplication developers to easily and cleanly override default configuration settings in a single place and build a customized target. You can use the \nnewt target config \ntarget-name\n command to check all the system configuration setting definitions and\n values in your target to determine the setting values to override. See \nnewt target\n. \n\n\n\n\nvals\n specifies the mappings of system configuration setting name-value pairs as follows: \n\n\nsyscfg.vals:\n PKGA_SYSCFG_NAME1: VALUE1\n PKGA_SYSCFG_NAME2: VALUE2\n ...\n PKGN_SYSCFG_NAME1: VALUEN\n\n\n\n\n\nNote\n: The newt tool ignores overrides of undefined system configuration settings. \n\n\n\n\nResolving Override Conflicts\n\n\nThe 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:\n\n\n\n\nA package can only override the default values of system configuration settings that \n are defined by lower priority packages.\n\n\nWhen packages with different priorities override the same system configuration setting value, newt uses \n the value from the highest priority package.\n\n\nPackages of equal priority cannot o verride the same system configuration setting with different values. \n newt aborts the build unless a higher priority package also overrides the value.\n\n\n\n\nThe following package types are listed from highest to lowest priority:\n\n\n\n\nTarget\n\n\nApp\n\n\nunittest - A target can include either an app or unit test package, but not both.\n\n\nBSP\n\n\nLib - Includes all other system level packages such as os, lib, sdk, and compiler. (Note that a Lib package cannot override other Lib package settings.)\n\n\n\n\nIt is recommended that you override defaults at the target level instead of updating individual \npackage \nsyscfg.yml\n files.\n\n\n\n\nExamples of Overrides\n\n\nExample 4:\n The following example is an excerpt from the \napps/slinky\n package \nsyscfg.yml\n file. The application package overrides, \nin addition to other packages, the \nsys/log/full\n package system configuration settings defined in \nExample 1\n. It changes the LOG_NEWTMGR system configuration sett ing value from \n0\n to \n1\n.\n\n\nsyscfg.vals:\n # Enable the shell task.\n SHELL_TASK: 1\n\n ...\n\n # Enable newtmgr commands.\n STATS_NEWTMGR: 1\n LOG_NEWTMGR: 1\n\n\n\n\n\nExample 5:\n The following example are excerpts from the \nhw/bsp/native\n package \nbsp.yml\n and \nsyscfg.yml\n files. \nThe package defines the flash areas for the BSP flash map in the \nbsp.yml\n file, and sets the \nNFFS_FLASH_AREA\n \nconfiguration setting value to use the flash area named \nFLASH_AREA_NFFS\n in the \nsyscfg.yml\n file.\n\n\nbsp.flash_map:\n areas:\n # System areas.\n FLASH_AREA_BOOTLOADER:\n device: 0\n offset: 0x00000000\n size: 16kB\n\n ...\n\n # User areas.\n FLASH_AREA_REBOOT_LOG:\n user_id: 0\n device: 0\n offset: 0x00004000\n size: 16kB\n FLASH_AREA_NFFS:\n user_id: 1\n device: 0\n offset: 0x00008000\ n size: 32kB\n\n\nsyscfg.vals:\n NFFS_FLASH_AREA: FLASH_AREA_NFFS\n\n\n\n\n\n\n\nGenerated syscfg.h and Referencing System Configuration Settings\n\n\nThe newt tool processes all the package \nsyscfg.yml\n files and generates the\n\ntarget-path\n/generated/include/syscfg/syscfg.h\n include file with \n#define\n statements for each system configuration \nsetting defined. Newt creates a \n#define\n for a setting name as follows: \n\n\n\n\nAdds the prefix \nMYNEWT_VAL_\n.\n\n\nReplaces all occurrences of \"/\", \"-\", and \" \" in the setting name with \"_\".\n\n\nConverts all characters to upper case.\n\n\n\n\nFor example, the #define for my-config-name setting name is MYNEWT_VAL_MY_CONFIG_NAME.\n\n\nNewt groups the settings in \nsyscfg.h\n by the packages that defined them. It also indicates the \npackage that changed a system configuration setting value. \n\n\nYou must use the \nMYNEWT_VAL()\n macro to reference a #define of a setting name in your header and source f iles. \nFor example, to reference the \nmy-config-name\n setting name, you use \nMYNEWT_VAL(MY_CONFIG_NAME)\n.\n\n\nNote:\n You only need to include \nsyscfg/syscfg.h\n in your source files to access the \nsyscfg.h\n file. The newt tool sets the correct include path to build your target. \n\n\nExample of syscfg.h and How to Reference a Setting Name\n\n\nExample 6\n: The following example are excerpts from a sample \nsyscfg.h\n file generated for an app/slinky target and \nfrom the \nsys/log/full\n package \nlog.c\n file that shows how to reference a setting name.\n\n\nThe \nsyscfg.h\n file shows the \nsys/log/full\n package definitions and also indicates that \napp/slinky\n \nchanged the value for the \nLOG_NEWTMGR\n settings. \n\n\n/**\n * This file was generated by Apache Newt (incubating) version: 1.0.0-dev\n */\n\n#ifndef H_MYNEWT_SYSCFG_\n#define H_MYNEWT_SYSCFG_\n\n/**\n * This macro exists to ensure code includes this header when needed. If code\n * checks the existence of a setting directly via ifdef without including this\n * header, the setting macro will silently evaluate to 0. In contrast, an\n * attempt to use these macros without including this header will result in a\n * compiler error.\n */\n#define MYNEWT_VAL(x) MYNEWT_VAL_ ## x\n\n\n ...\n\n/*** kernel/os */\n#ifndef MYNEWT_VAL_MSYS_1_BLOCK_COUNT\n#define MYNEWT_VAL_MSYS_1_BLOCK_COUNT (12)\n#endif\n\n#ifndef MYNEWT_VAL_MSYS_1_BLOCK_SIZE\n#define MYNEWT_VAL_MSYS_1_BLOCK_SIZE (292)\n#endif\n\n ...\n\n/*** sys/log/full */\n\n#ifndef MYNEWT_VAL_LOG_LEVEL\n#define MYNEWT_VAL_LOG_LEVEL (0)\n#endif\n\n ...\n\n/* Overridden by apps/slinky (defined by sys/log/full) */\n#ifndef MYNEWT_VAL_LOG_NEWTMGR\n#define MYNEWT_VAL_LOG_NEWTMGR (1)\n#endif\n\n#endif\n\n\n\n\n\nThe \nlog_init()\n function in the \nsys/log/full/src/log.c\n file initializes the \nsys/log/full\n package. It checks the \n\nLOG_NEWTMGR\n setting value, using \nMYNEWT_VAL(LOG_NEWTMGR)\n, to determ ine whether the target application\nhas enabled the \nnewtmgr log\n functionality. It only registers the the callbacks to process the\n\nnewtmgr log\n commands when the setting value is non-zero.\n\n\nvoid\nlog_init(void)\n{\n int rc;\n\n /* Ensure this function only gets called by sysinit. */\n SYSINIT_ASSERT_ACTIVE();\n\n (void)rc;\n\n if (log_inited) {\n return;\n }\n log_inited = 1;\n ...\n\n#if MYNEWT_VAL(LOG_NEWTMGR)\n rc = log_nmgr_register_group();\n SYSINIT_PANIC_ASSERT(rc == 0);\n#endif\n}\n\n\n\n\n\n\n\nSystem Initialization\n\n\nDuring system startup, Mynewt creates a default event queue and a main task to process events from this queue. \nYou can override the \nOS_MAIN_TASK_PRIO\n and \nOS_MAIN_TASK_STACK_SIZE\n setting values defined by the \n\nkernel/os\n package to specify different task priority and stack size values.\n\n\nYour application's \nmain()\n function executes in the context of the main task and must perform the fol lowing:\n\n\n\n\nAt the start of \nmain()\n, call the Mynewt \nsysinit()\n function to initialize \nthe packages before performing any other processing.\n\n\nAt the end of \nmain()\n, wait for and dispatch events from the default event queue in a forever loop. \n\n\n\n\nNote:\n You must include the \nsysinit/sysinit.h\n header file to access the \nsysinit()\n function.\n\n\nHere is an example of a \nmain()\n function:\n\n\nint\nmain(int argc, char **argv)\n{\n /* First, call sysinit() to perform the system and package initialization */\n sysinit();\n\n ... other application initialization processing....\n\n\n /* Last, process events from the default event queue. */\n while (1) {\n os_eventq_run(os_eventq_dflt_get());\n }\n /* main never returns */ \n}\n\n\n\n\n\n\n\nSpecifying Package Initialization Functions\n\n\nThe \nsysinit()\n function calls the \nsysinit_app()\n function to perform system \ninitialization for the packages in the target. You c an, optionally, \nspecify one or more package initialization functions \nthat \nsysinit_app()\n calls to initialize a package. \n\n\nA package initialization function must have the following prototype:\n\n\nvoid init_func_name(void)\n\n\n\n\n\nPackage initialization functions are called in stages to ensure that lower priority\npackages are initialized before higher priority packages. A stage is an \ninteger value, 0 or higher, that specifies when an initialization function is \ncalled. Mynewt calls the package initialization functions \nin increasing stage number order. The call order for initialization functions with the \nsame stage number depends on the order the packages are processed,\nand you cannot rely on a specific call order for these functions. \n\n\nYou use the \npkg.init\n parameter in the \n\npkg.yml\n file to specify an initialization function and the stage number to call the function.\nYou can specify multiple initialization functions, with a different stage numb er for each function,\nfor the parameter values. This feature allows packages with interdependencies to\nperform initialization in multiple stages. \n\n\nThe \npkg.init\n parameter has the following syntax in the \npkg.yml\n file: \n\n\npkg.init: \n pkg_init_func1_name: pkg_init_func1_stage \n pkg_init_func2_name: pkg_init_func2_stage \n\n ...\n\n pkg_init_funcN_name: pkg_init_funcN_stage\n\n\n\n\n\nwhere \npkg_init_func#_name\n is the C function name of an initialization function, and \npkg_init_func#_stage\n \nis an integer value, 0 or higher, that indicates the stage when the \npkg_init_func#_name\n function is called. \n\n\nNote:\n The \npkg.init_function\n and \npkg.init_stage\n parameters introduced in a previous release for \nspecifying a package initialization function and a stage number are deprecated and have been \nretained to support the legacy format. They will not \nbe maintained for future releases and we recommend that you migrate to use the \npkg.init\n parameter.\n\n\n\n\nGenerated sysinit_app() Function\n\n\nThe newt tool processes the \npkg.init\n parameters in all the \npkg.yml\n files for a target,\ngenerates the \nsysinit_app()\n function in the \ntarget-path\n/generated/src/\ntarget-name\n-sysinit_app.c\n file, and \nincludes the file in the build. Here is an example \nsysinit_app()\n function:\n\n\n**\n * This file was generated by Apache Newt (incubating) version: 1.0.0-dev\n */\n\n#if !SPLIT_LOADER\n\nvoid split_app_init(void);\nvoid os_pkg_init(void);\nvoid imgmgr_module_init(void);\n\n ...\n\nvoid stats_module_init(void);\n\nvoid\nsysinit_app(void)\n{\n\n /*** Stage 0 */\n /* 0.0: kernel/os */\n os_pkg_init();\n\n /*** Stage 2 */\n /* 2.0: sys/flash_map */\n flash_map_init();\n\n /*** Stage 10 */\n /* 10.0: sys/stats/full */\n stats_module_init();\n\n /*** Stage 20 */\n /* 20.0: sys/console/full */\n console_pkg_init();\n\n /*** Stage 100 */\n /* 100.0: sys/lo g/full */\n log_init();\n /* 100.1: sys/mfg */\n mfg_init();\n\n ....\n\n /*** Stage 300 */\n /* 300.0: sys/config */ \n config_pkg_init();\n\n /*** Stage 500 */\n /* 500.0: sys/id */\n id_init();\n /* 500.1: sys/shell */\n shell_init();\n\n ...\n\n /* 500.4: mgmt/imgmgr */\n imgmgr_module_init();\n\n /*** Stage 501 */\n /* 501.0: mgmt/newtmgr/transport/nmgr_shell */\n nmgr_shell_pkg_init();\n}\n#endif\n\n\n\n\n\n\n\nConditional Configurations\n\n\nYou can use the system configuration setting values to conditionally specify parameter values\nin \npkg.yml\n and \nsyscfg.yml\n files. The syntax is:\n\n\nparameter_name.PKGA_SYSCFG_NAME:\n parameter_value\n\n\n\n\n\nThis specifies that \nparameter_value\n is only set for \nparameter_name\n if the \nPKGA_SYSCFG_NAME\n configuration setting value \nis non-zero. Here is an example from the \nlibs/os\n package \npkg.yml\n file:\n\n\npkg.deps:\n - sys/sysinit\n - u til/mem\n\npkg.deps.OS_CLI\n - sys/shell\n\n\n\n\n\nThis example specifies that the \nos\n package depends on the \nsysinit\n and \nmem\n packages, and also depends on the \n\nshell\n package when \nOS_CLI\n is enabled. \n\n\nThe newt tool aborts the build when it detects circular conditional dependencies.", "title": "toc" }, { "location": "/os/modules/sysinitconfig/sysinitconfig/#system-configuration-and-initialization", - "text": "This guide describes how Mynewt manages system configuration and initialization. It shows you how to \ntell 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 section that describes the Mynewt \npackage hierarchy and its use of the pkg.yml and syscfg.yml files. Assumes you have read the Newt Tool Theory of Operation and are familiar with how newt determines \npackage 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. The newt tool uses this information to: Generate a system initialization function that calls all the package-specific ystem initialization functions. Generate a system configura tion header file that contains all the package configuration settings and values. Display the system configuration settings and values in the newt target config command. 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.", + "text": "This guide describes how Mynewt manages system configuration and initialization. It shows you how to \ntell 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 section that describes the Mynewt \npackage hierarchy and its use of the pkg.yml and syscfg.yml files. Assumes you have read the Newt Tool Theory of Operation and are familiar with how newt determines \npackage 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. The newt tool uses this information to: Generate a system initialization function that calls all the package-specific system initialization functions. Generate a system configur ation header file that contains all the package configuration settings and values. Display the system configuration settings and values in the newt target config command. 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.", "title": "System Configuration and Initialization" }, { http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/637e3d81/develop/os/modules/sysinitconfig/sysinitconfig/index.html ---------------------------------------------------------------------- diff --git a/develop/os/modules/sysinitconfig/sysinitconfig/index.html b/develop/os/modules/sysinitconfig/sysinitconfig/index.html index 87ba2ae..2e1927f 100644 --- a/develop/os/modules/sysinitconfig/sysinitconfig/index.html +++ b/develop/os/modules/sysinitconfig/sysinitconfig/index.html @@ -561,7 +561,7 @@ package dependencies for your target build.</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 ystem initialization functions. </li> +<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>
