Configuration Manager (goal_cm)

he Configuration Manager provides an interface to handle configuration variables during runtime. If a NVM is available, the configuration variables can also be managed nonvolatile. Besides providing runtime configuration data the CM also provies an interface for the Device Manger Tool/ GOAL Manager Tool.
The Configuration Manager organizes the configuration data module-wise, called CM-module. Each CM-module contains a list of configuration variables, called CM-variables.

Figure: data structure and data flow of the Configuration Manager

Each CM-variable is uniquely identified by a CM-module-ID and a CM-variable-ID. The Configuration Manager allows to handle configuration variables of the CM-variable data types, see Chapter: GOAL data types. The CM-modules and CM-variables must be installed in state GOAL_FSA_INIT.
The configuration data in the NVM are extended by a CRC-sum to detect data errors. The applied CRC-algorithm is Fletcher-32 /Fletcher/.
The Configuration Manager differentiates between CM-variables with temporary and volatile values. CM-variables can be marked as temporary or stable by function goal_cmSetVarValue(). Temporary CM-variables can be manipulated after loading from the NVM via a callback function. Chapter: Callback functions describes all callback functions of the Configuration Manager.
If there are changes at the interface of the Configuration Manager to the NVM or changes at the variable list, the configuration data are not loaded from NVM. Changes on interfaces are identifiable by the version number GOAL_CM_VERSION of the Configuration Manager in the file ...\goal\goal_cm.h.
It is possible to assign a name to each CM-variable. This possibility must be activated/deactivated by the compiler-define GOAL_CM_NAMES.
The Configuration Manager can be controlled via the command line interface, see Chapter: Command line interface.

• GOAL files:

  • goal_cm.[h,c], goal_cm_id.h, goal_cm_t.h, goal_cm_cli.c, cm/goal_cm_cm.[h,c]

• example:

  • …\goal\appl\00410_goal\cfg_demo

Configuration

Compiler-defines

The following compiler-defines are available to configure the Configuration Manager:

• GOAL_CM_NAMES:

  • 0: CM-modules and CM-variables are identified by ID numbers (default)

  • 1: CM-modules and CM-variables are identified by ID numbers and names

CM-variables

The following CM-variables are available for the Configuration Manager:

Table: CM-variables for Configuration Manager

Callback functions

The Configuration Manager supports two kinds of callback functions:

• callback functions, which must be specified during implementation and

• callback functions, which can be specified during runtime

CM-variables based

During implementation callback functions

• for value validation and

• to inform the application about value changes

can be specified for each CM-variable. The specification of the callback functions is described in Chapter: Creating a CM-module and a variable list. The callback functions themselves are described in the following tables. The names of the callback functions are application-specific.

Table: description of callback function cbValidateFunc()

Table: description of callback function cbChangedFunc()

CM-module based

During runtime callback functions

• for customer-specific loading of CM-variables from the NVM,

• for customer-specific saving of CM-variables to the NVM,

• to change values for temporary CM-variables after loading from the NVM by function goal_cmLoad()

can be configured for each CM-module by function goal_cmAddModule(). The callback functions are described in the following tables. The names of the callback functions are application-specific.

Table: description of callback function cbLoadFunc()

Table: description of callback function cbSaveFunc()

Table: description of callback function cbTmpsetFunc()

Creating a CM-module and a variable list

The Configuration Manager provides a scheme for the creation of a CM-module and a list of CM-variables. It is recommended to use this scheme for application-specific CM-modules too.

1. For each CM-module a unique number is necessary.
   

   Code: Example of unique number

   #define APPL_CM_MOD_ID 0x00EE000 

2. The CM-variables, which shall be available via the Configuration Manager, must be specified and assigned to a CM-variable-ID. Because the CM-variable-ID is also used as list index, the counting has to start with 0 and must be consecutively. Create a enum for the CM-variable-IDs to access the configuration variable by a symbolic name.
   

   Code: Example of enum for the CM-variable-IDs

   typedef enum {
       APPL_CM_VAR_1,
       APPL_CM_VAR_2
   } APPL_CM_VARS_ID_T;

3. The CM-variables are listed with the following properties:
   

   1. CM-variable-ID,

   2. CM-variable data types of the CM-variable,

   3. maximal size of the CM-variable in byte,

   4. a callback function for the validation of the written value,

   5. a callback function to inform the application about the change of the variable's value and

   6. the name of the CM-variable, if naming is switched on by the compiler-define GOAL_CM_NAMES.
      Create a table with the properties for all CM-variables assigned to the CM-module. Each line of the table represents one CM-variable according to the structure GOAL_CM_VARENTRY_T. This structure contains the properties of the CM-variable and pointer references for the internal handling. Please set the internal pointer references to NULL. If no callback functions are available for validation and/or change reports, set the references also to NULL.
      

      Code: Example for GOAL_CM_NAMES = 0 with callback functions

      static GOAL_CM_VARENTRY_T applCmVars[] = { \
          {APPL_CM_VAR_1, GOAL_CM_UINT8, 1, NULL, applValidateFct, applChangeFct, NULL,
           NULL
          }, 
          {APPL_CM_VAR_2, GOAL_CM_UINT32, 4, NULL, applValidateFct, applChangeFct, NULL,
           NULL
          }
      }

      Code: Example for GOAL_CM_NAMES = 0 without callback functions

      static GOAL_CM_VARENTRY_T applCmVars[] = { \
          {APPL_CM_VAR_1, GOAL_CM_UINT8, 1, NULL, NULL, NULL, NULL, NULL}, 
          {APPL_CM_VAR_2, GOAL_CM_UINT32, 4, NULL, NULL, NULL, NULL, NULL}
      }

4. Now the created CM-module can be integrated in the code as described in Chapter: Creating a new CM-module.

Virtual Variables

GOAL CM supports virtual variables, which only are stored in memory and not written to the non volatile storage.
Virtual variables are created in stage GOAL_STAGE_CM_MOD_ADD using the function goal_cmRegVarVirtual().

Table: description of goal_cmRegVarVirtual()

Code: example of creating virtual cm variable

/* add virtual variables */
if (GOAL_RES_OK(res)) {
    res = goal_cmRegVarVirtual(
        2,					    /* module Id */
        CM_CM_VAR_SAVE,			/* variable Id */
        GOAL_CM_UINT8,			/* type */
        1,				        /* size */
        NULL,					/* validation callback */
        goal_cmCmSave			/* modification callback*/
    );
}

Command line interface

Table: description of cm set

Table: description of cm show

Implementation guidelines

Creating a new CM-module

1. Specify a unique CM-module-ID number, see Chapter: Creating a CM-module and a variable list.

2. Specify the list of CM-variables, see Chapter: Creating a CM-module and a variable list.

3. Create a variable for the CM-module-ID.
   

   Code: Create a variable for the CM-module-ID

   GOAL_CM_MODDEF_T cmMod;
   cmMod.modId = APPL_CM_MOD_ID;

4. Register the CM-variables by function goal_cmRegModule() in the state GOAL_FSA_INIT_APPL, stage GOAL_STAGE_CM_MOD_REG.
   

   Code: Register the CM-variables by function goal_cmRegModule()

   GOAL_STATUS_T res; /* GOAL return status */
   res = goal_cmRegModule(applCmVars); 

5. In stage GOAL_STAGE_CM_MOD_ADD add the CM-variable list to the CM-module by function goal_cmAddModule() in the state GOAL_FSA_INIT_APPL and do not specify callback functions for customer-specific nonvolatile load and save and the modification of temporary CM-variables after loading from NVM.
   

   Code: add the CM-variable list to the CM-module by function goal_cmAddModule()

   if (GOAL_RES_OK(res)) {
       res = goal_cmAddModule(&cmMod, applCmVars, NULL, NULL, NULL);
   }

6. Write a value to a CM-variable by function goal_cmSetVarValue().
   

   Code: Write a value to a CM-variable by function goal_cmSetVarValue()

   uint32_t val = 0x11223344;
   if (GOAL_RES_OK(res)) {
       res = goal_cmSetVarValue(APPL_CM_MOD_ID, APPL_CM_VAR_2, (void *)&val, 4, GOAL_FALSE, NULL);
   }

7. Read the value of a CM-variable about function goal_cmGetVarById().
   

   Code: Read the value of a CM-variable about function goal_cmGetVarById()

   GOAL_CM_VAR_T *pEntry;
   if (GOAL_RES_OK(res)) {
       res = goal_cmGetVarById(APPL_CM_MOD_ID, APPL_CM_VAR_2, &pEntry);
       if (GOAL_RES_OK(res)) {
           val = GOAL_CM_VAR_UINT32(pEntry);
       }
   }

Add a new CM-variable to a CM-module

1. Add the CM-variable to the variable list, see Chapter: Creating a CM-module and a variable list.

2. Create a variable for the CM-module-ID.
   
   Code: Create a variable for the CM-module-ID

   GOAL_CM_MODDEF_T cmMod;
   cmMod.modId = APPL_CM_MOD_ID; 

3. Register the CM-module by function goal_cmRegModule() in the state GOAL_FSA_INIT_APPL.
   

   Code: Register the CM-module by function goal_cmRegModule()

   GOAL_STATUS_T res; /* GOAL return status */
   res = goal_cmRegModule(applCmVars);

4. Add the CM-variable list to the CM-module by function goal_cmAddModule() in the state GOAL_FSA_INIT_APPL and do not specify callback functions for customer-specific nonvolatile load and save and the modification of temporary CM-variables after loading from NVM.
   

   Code: Add the CM-variable list to the CM-module by function goal_cmAddModule()

   if (GOAL_RES_OK(res)) {
       res = goal_cmAddModule(&cmMod, applCmVars, NULL, NULL, NULL);
   } 

5. Write a value to a CM-variable by the function goal_cmSetVarValue().
   

   Code: Write a value to a CM-variable

   uint8_t val = 0xA5;
   if (GOAL_RES_OK(res)) {
       res = goal_cmSetVarValue(APPL_CM_MOD_ID, APPL_CM_VAR_1, (void *)&val, 1, GOAL_FALSE, NULL);
   }

6. Read the value of a CM-variable by the function goal_cmGetVarById().
   

   Code: Read the value of a CM-variable

   GOAL_CM_VAR_T *pEntry;
   if (GOAL_RES_OK(res)) {
       res = goal_cmGetVarById(APPL_CM_MOD_ID, APPL_CM_VAR_1, &pEntry);
       if (GOAL_RES_OK(res)) {
           val = GOAL_CM_VAR_UINT8(pEntry);
       }
   }

Load and save CM-variables nonvolatile

1. Create a variable for the CM-module-ID.
   

   Code: Create a variable for the CM-module-ID

   GOAL_CM_MODDEF_T cmMod;
   cmMod.modId = APPL_CM_MOD_ID; 

2. Register the CM-module by function goal_cmRegModule() in the state GOAL_FSA_INIT_APPL
   

   Code: Register the CM-module by function goal_cmRegModule()

   GOAL_STATUS_T res; /* GOAL return status */
   res = goal_cmRegModule(applCmVars);

3. Add the CM-variable list to the CM-module by function goal_cmAddModule() in the state GOAL_FSA_INIT_APPL and do not specify callback functions for customer-specific nonvolatile load and save and the modification of temporary CM-variables after loading from NVM.
   

   Code: Add the CM-variable list to the CM-module by function goal_cmAddModule()

   if (GOAL_RES_OK(res)) {
       res = goal_cmAddModule(&cmMod, applCmVars, NULL, NULL, NULL);
   }

4. Load all CM-variables from NVM by function goal_cmLoad().
   

   Code: Load all CM-variables

   if (GOAL_RES_OK(res)) {
       res = goal_cmLoad();
   }

5. Write a value to a CM-variable by the function goal_cmSetVarValue().
   

   Code: Write a value to a CM-variable

   uint8_t val = 0xA5;
   if (GOAL_RES_OK(res)) {
       res = goal_cmSetVarValue(APPL_CM_MOD_ID, APPL_CM_VAR_1, (void *)&val, 1, GOAL_FALSE, NULL);
   }

6. Save all CM-variables nonvolatile by function goal_cmSave().
   

   Code: Save all CM-variables

   if (GOAL_RES_OK(res)) {
       res = goal_cmSave();
   }