Skip to end of metadata
Go to start of metadata

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:

  1. Copy the default configuration in a local structure.
  2. 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 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().

#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. */
    }
}
Listing - Copy default configuration structure and call Module_Configure() function

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.

const  MODULE_INIT_CFG  Module_InitCfg =
{
    .SubCfg =
    {
        .Field1 = 0u,
        .Field2 = 512u
    },
    .StkSizeElements = 256u,
    .StkPtr          = DEF_NULL,
    .MemSegPtr       = DEF_NULL
};
Listing - Example of configuration structure externalization

Comparison Summary

OperationStandard MethodAdvanced Method
Initialize the module(Optional) Call <Module>_Configure...(), to change configurations from their default values.
Call <Module>_Init(...).
Define a <Module>_InitCfg for every <Module>_Init(...) that the application will call, specify a value for every field of the struct. Call <Module>_Init(...).
Recover the default configuration structureGlobal variable <Module>_InitCfgDflt contains it.Not available with this method.
Specify new configuration valuesCall <Module>_Configure...() with the relevant parameter(s) for every parameter (or structure of parameter) that needs to be configured differently than its default value.Change the values specified in the relevant <Module>_InitCfg .
Change properties (task priority, timeouts, etc.) after the initialization is done.Call the relevant <Module>_...Set() function.Call the relevant <Module>_...Set() function.

Stack-Specific Pages

  • No labels