Stacks Initialization Methods#

Standard Configuration Method
Advanced Configuration Method
Comparison Summary
Stack-Specific Pages

Most Micrium products share the same initialization method. This page provides information about two possible methods that you can use to configure and initialize Micrium modules. We recommend that you use the standard method first during development of your application because it is easier to tailor the modules to your application's needs. Once development is done, you can use the advanced method to save memory and code space and to make the initialization faster.

Standard Configuration Method#

This is the default method, and it is recommended that you start with this method.

This method consists of using default values for as many of the configuration fields as possible. These include task stack sizes and task priority, memory segment to use to allocate data, the maximum count of an item type, timeouts, etc. The application can then provide to the <Module>_Init() functions only the mandatory arguments, for which default values cannot be determined.

Using the <Module>_Configure...() function, the application can override any single parameter before the <Module>_Init() is called. These functions allow the application to set some values for the stack to use instead of the default ones. Some of these functions configure a single parameter, while others configure a group of related parameters via a structure. If the function requires a structure, you should follow these steps:

Copy the default configuration in a local structure.
Modify only the fields that the application needs to change.

It is possible to obtain the default configuration related to any <Module>_Init() function, they are defined in the same file than the <Module>_Init() function and are called <Module>_InitCfgDflt. This structure contains every default value related to that particular Init() function, so you can find the exact structure to copy in the local one (see Listing - Copy default configuration structure and call Module_Configure() function in the Stacks Initialization Methods page for an example). Normally, once the call to <Module>_Configure() is done, the configuration structure to which the pointer passed in parameter pointed to is no longer required to remain valid. Exceptions are indicated in the function header of the <Module>_Configure().

Listing - Copy default configuration structure and call Module_Configure() function#

#include <rtos/module/module.h>

void  MyFunction(void)
{
    MODULE_SUB_CFG  my_local_module_sub_cfg;
    RTOS_ERR        err;

    my_local_module_sub_cfg = Module_InitCfgDflt.SubCfg;  /* Copy the default values in the local struct.      */
    my_local_module_sub_cfg.Field1 = 4u;                  /* Specify new value for given field(s).             */

    Module_ConfigureSubCfg(&my_local_module_sub_cfg);     /* Call Module_Configure() for that sub-cfg.         */

    /* [...] */                                           /* Repeat, if required, for other configuration(s).  */

    Module_Init(&err);                                    /* Call Module_Init() after Configure call(s).       */
    if (RTOS_ERR_CODE_GET(err) != RTOS_ERR_NONE) {        /* Check err.                                        */
        /* Handle err. */
    }
}

Some properties cannot be configured pre-initialization and can only set once the initialization is completed. The functions to do this kind of operation are not called <Module>_Configure(), but should instead be called <Module>_xxxx_Set().

Advanced Configuration Method#

This method requires that you provide every optional configuration structure needed by every module. For every <Module>_Init() function, a corresponding const <MODULE>_INIT_CFG called <Module>_InitCfg must be defined and compiled by the application somewhere. When using this method, the modules will assume that such a configuration exists and will declare it as extern, and will assume the application will define it. To use this method, set RTOS_CFG_EXTERNALIZE_OPTIONAL_CFG_EN to DEF_ENABLED.

Neither the <Module>_Configure...() functions nor the <Module>_InitCfgDflt will be available if this method is used. Examples and templates containing the const <MODULE>_INIT_CFG called <Module>_InitCfg for each module are available.

This method uses less memory than the standard one because no copy of the configuration structures need be kept in memory by the stacks.

Listing - Example of configuration structure externalization#

const  MODULE_INIT_CFG  Module_InitCfg =
{
    .SubCfg =
    {
        .Field1 = 0u,
        .Field2 = 512u
    },
    .StkSizeElements = 256u,
    .StkPtr          = DEF_NULL,
    .MemSegPtr       = DEF_NULL
};

Comparison Summary#

Comparison Summary