GOAL state machine

The GOAL system provides a state machine for system and application startup and shutdown, simplified shown in Figure GOAL state machine. The state machine is managed by the GOAL core module main.

 

Figure: GOAL state machine

 

Table: GOAL states

GOAL state

GOAL sub-state

Action(s)

GOAL_FSA_INIT

GOAL_FSA_INIT_APPL

application-specific initialization before GOAL components are initialized

GOAL_FSA_INIT_GOAL

initialization of GOAL components including the initialization of the GOAL platform

GOAL_FSA_INIT_APPL_SETUP

application-specific initializations depending on GOAL core modules and configuration of the GOAL system

GOAL_FSA_OPERATION

normal operation including the execution of loop-controlled functions

GOAL_FSA_FINISH

halt or reset the GOAL system

 

Table: GOAL state transitions (see Figure: GOAL state machine)

GOAL state transition

Event(s)

1

automatic transition after power-on or reset

2

automatic transition if application was initialized successful

3

automatic transition if all GOAL components and the application was initialized successful

4

an error occurred during initialization

5

automatic transition if GOAL system was configured

6

a severe error was occurred during normal operation

7

GOAL system is halted

8

GOAL system is reset and re-starts again

GOAL IDs

GOAL implements a concept of creating and identifying instances of objects by IDs. One could create two instances of a SPI driver, each operating on a different channel. Those two instances would then be identified by different IDs.
If only one instance of an object of specific type is created, the default ID of GOAL_ID_DEFAULT can be used. This ID can be reused for different types (e.g. for a driver and for a Media Interface), since they are directly realted to the object type.
Beside that each software component uses different IDs for identification or logging. Those IDs are defined in goal/goal_id.h. Here is an excerpt:

Code: goal ID list excerpt

#define GOAL_ID_DEFAULT (0) /**< GOAL : Default ID */ #define GOAL_ID_BM (1) /**< GOAL : Bitmap Handling */ #define GOAL_ID_CM (2) /**< GOAL : Config Manager */ #define GOAL_ID_CTC (3) /**< GOAL : CTC */ #define GOAL_ID_ETH (4) /**< GOAL : Ethernet */ #define GOAL_ID_LIST (5) /**< GOAL : List Management */ #define GOAL_ID_LOCK (6) /**< GOAL : Lock Management */ #define GOAL_ID_LOG (7) /**< GOAL : Logging */ #define GOAL_ID_MAIN (8) /**< GOAL : Main */ #define GOAL_ID_MEM (9) /**< GOAL : Memory Management */ #define GOAL_ID_MI (10) /**< GOAL : Media Interface */ #define GOAL_ID_MA (11) /**< GOAL : Media Adapter */ #define GOAL_ID_NET (12) /**< GOAL : TCP/IP Networking */ #define GOAL_ID_REG (13) /**< GOAL : Register Handling */ #define GOAL_ID_RPC (14) /**< GOAL : RPC (CTC) */ #define GOAL_ID_TGT (15) /**< GOAL : Target */ #define GOAL_ID_DRV (16) /**< GOAL : Driver */ #define GOAL_ID_TASK (17) /**< GOAL : Task Management */ #define GOAL_ID_TMR (18) /**< GOAL : Timer Management */

GOAL initialization

All GOAL components are initialized in state GOAL_FSA_INIT. The initialization covers:

  • application-specific initializations in state GOAL_FSA_INIT_APPL,

  • the embedding of initialization functions in the GOAL initialization process by staging,

  • the initialization of each GOAL component,

  • the combination of GOAL components by registration in state GOAL_FSA_INIT_GOAL,

  • the installation of loop-controlled processes and

  • application-specific configurations in state GOAL_FSA_INIT_APPL_SETUP.


All necessary services must be created and initialized in the state GOAL_FSA_INIT, because it is only allowed to allocate memory in this state.

Staging

The GOAL system organizes the initialization process in stages. GOAL uses fixed stages. Each GOAL core module has own stages. Some further stages complete the range of stages. Normally there are two stages for each module:

  • GOAL_STAGE_*_PRE: The initialization function shall be executed. This stage represents the start of initialization of the considered component.

  • GOAL_STAGE_*: The initialization function is finished. This stage represents the end of initialization of the considered component.


Each GOAL component, also the application, can enter callback functions on every stage. The order of the stages determines the order of execution of the callback functions. It is possible to add more than one callback function to a stage. The order of execution of the callback functions within a single stage is determined by the order of registration. The callback functions are listed in the stage table, see Figure: function order at staging.
Each stage is identified by a stage-ID, defined in the enum GOAL_STAGES_T in <GOAL>/goal/goal_main.h. The callback functions with the smallest stage-ID are executed first. Platform-specific initializations assigned to the smallest stage-IDs, followed by GOAL core modules and GOAL extension modules. Table: some stages usefull for applications lists some stages, which are most interesting from the application point of view.

 

Table: some stages useful for applications

Stage

Description

GOAL_STAGE_TARGET_PRE

for the initialization of the platform

GOAL_STAGE_TARGET

indicate, that the initialization of the platform is ready

GOAL_STAGE_BOARD_PRE

for additional initialization of the board

GOAL_STAGE_BOARD

indicate, that the initialization of the board is ready

GOAL_STAGE_MODULES_PRE

for the initialization of GOAL extension modules or the application

GOAL_STAGE_MODULES

indicate, that the initialization of GOAL extension modules or the application is ready

GOAL_STAGE_GOAL_PRE

for the last initialization steps in state GOAL_FSA_INIT_GOAL

GOAL_STAGE_GOAL

indicate, that the initialization of all GOAL components is ready

 

Each entry in the stage table contains a stage-ID, the direction type and a callback function. There are two direction types:

  • GOAL_STAGE_INIT: These stage table entries are processed in state GOAL_FSA_INIT_GOAL.

  • GOAL_STAGE_SHUTDOWN: This direction type is reserved for future use.

 

Figure: function order at staging


At the beginning of state GOAL_FSA_INIT_GOAL the GOAL core modules and GOAL extension modules register their callback functions. After registration the callback functions are executed.
For the example in Figure: function order at staging the initialization functions are called in the following order:

1.1 fct_targetInitPart1()
1.2 fct_targetInitPart2()

n.1 fct_targetGoalReady()

Platform API

During initialization GOAL requires the function goal_targetInitPre() to initialize the used platform:

Prototype

GOAL_STATUS_T goal_targetInitPre(void)

Description

This indication function initializes the complete platform and is called in the state GOAL_FSA_INIT_GOAL in stage GOAL_STAGE_TARGET_PRE.

Parameters

None

Return values

GOAL return status, see Chapter: GOAL status

Category

Mandatory

Registration of media interfaces, media adapters and drivers

GOAL allows to combine various hardware and software components with each other. The various components are connected to each other by a registration.
The platform-specific drivers are connected to platform-independent media adapters (MA). Media adapters represent a generic driver interface. Media adapters can be connected to media interfaces (MI). Media interfaces represent a generic connection interface between a media adapter and a special higher layer module.


Example 1: A GOAL device shall store parameters in the nonvolatile memory (NVM). The parameters are split in different blocks. The GOAL device uses the Synergy S7 platform. The GOAL device has to initialize and register the following GOAL components:

  1. Initialize the GOAL driver for the access to the NVM for the Synergy S7 platform. The GOAL driver handles the accesses to the memory hardware.

  2. The GOAL driver registers to the MA for the nonvolatile storage itself. The MA for the nonvolatile storage provides a generic interface for accesses to the memory hardware.

  3. The different memory blocks are managed about various memory regions. The MI for the nonvolatile storage provides the management of memory regions and is added to the GOAL project. The MI relates to the MA for the nonvolatile storage by a registration.

  4. The application specifies a memory region for each parameter block. Each region is registered to the MI for the nonvolatile storage.

The media interfaces and the media adapters can be identified by MI or MA unique ID's. The MI-IDs and MA-IDs have separate lists and are independent from each other. During registration a unique handle is created for each ID. Normally the registration is done in stage GOAL_STAGE_TARGET_PRE in state GOAL_FSA_INIT_GOAL.


Example 2: The registration of the media interface, media adapter and driver are shown for MCTC over SPI:

  1. Define a MA-ID and a MI-ID in …\goal\plat\board\...\goal_target_board.h or use default ID GOAL_ID_DEFAULT.

  2. Register the SPI driver in <GOAL>/plat/board/…/goal_target_board.c, thus creating a media adapter (MA):

    Code: SPI driver registration

    /* register SPI driver */ res = goal_drvSpiSynReg(GOAL_ID_DEFAULT, 0); if (GOAL_RES_ERR(res)) { goal_logErr("failed to register Synergy SPI driver"); return res; }
  3. Register the MCTC MI with ID to the SPI MA as a parameter. The created MI will also utilize the ID GOAL_ID_DEFAULT. Since SPI MA and MCTC MI are of different type, this is ok.

    Code: MCTC MI registration

    /* register a new MCTC MI */ res = goal_miMctcSpiReg( GOAL_ID_DEFAULT, GOAL_ID_DEFAULT, mpMiDmRead, mpMiDmWrite); if (GOAL_RES_ERR(res)) { goal_logInfo("Unable to reg MI SPI"); return res; }

Depending on the media type and the driver the registration functions can require different parameters.
Some drivers generate the MA-ID according to an implemented rule automatically. The rule is documented
in the suitable GOAL Platform Manual.

Application-specific indication function for initialization

Application-specific initializations are implemented about the indication function appl_init() located in <GOAL>/ appl/.../goal_appl.c normally:

Prototype

GOAL_STATUS_T appl_init (void)

Description

This indication function allows to include application-specific initialization steps before the GOAL core modules or GOAL extension modules are initialized. GOAL core modules must not be used. This indication function is called by GOAL automatically in state GOAL_FSA_INIT_APPL_INIT.

Parameters

None

Return values

GOAL return status, see Chapter: GOAL status

Category

Optional
If appl_init()does not exist in the application, GOAL uses an empty default function.

Install loop-controlled processes

Functions with low priority can be executed loop-controlled in the state GOAL_FSA_OPERATION. GOAL provides a loop mechanism, called GOAL loop. There are the following possibilities to install application-specific loop functions in the GOAL loop:

  • implementation of the indication function appl_loop() or

  • append the functions, which shall be called loop-controlled, to the list of loop functions.

Loop functions run in the main loop context of GOAL, thus these functions should be limited in execution time to minimize the effect on other loop functions. Longer processes should be split into multiple sequential steps.

Implementation of appl_loop()

GOAL provides the indication function appl_loop()for calling application-specific functions in the GOAL loop:

Prototype

void appl_loop (void)

Description

This indication function allows to execute application-specific functions loop-controlled. This indication function is called in the GOAL loop in state GOAL_FSA_OPERATION.

Parameters

None

Return values

None

Category

optional
If appl_loop() does not exist in the application, GOAL uses an empty default function.


Example 3: The function applUpdate() shall be called loop-controlled. This function is implemented in the indication function appl_loop().

Code: appl_loop example usage

Function list

GOAL provides a further possibility to integrate application-specific functions in the GOAL loop. GOAL manages all functions, which shall be executed in the GOAL loop in state GOAL_FSA_OPERATION about a function list. A function can be added to the loop function list by function goal_mainLoopReg(). Each loop function must have the following function prototype:

Code: prototype loop functions

The loop function list is created in state GOAL_FSA_INIT. At the beginning of state GOAL_FSA_INIT_APPL the loop function list is empty. The application can register loop functions. The GOAL core modules and GOAL extension modules register their loop functions in state GOAL_FSA_INIT_GOAL.
The order of execution of the loop functions depends on the order of registration. The first registered loop function is executed at first.


Example 4: The function applUserLoop() shall be executed loop-controlled. The registration is made in appl_init().

Code: registration of appl user loop

Example 5: The function applDeviceLoop() shall be executed loop-controlled. The registration is made in appl_setup().

Code: registration of device loop

Example 6: The function applFunc() shall be executed loop-controlled. The registration is made during initialization. In Example 7 the function applActivate() is registered and called during initialization. The loop function is registered in this initialization function.

Code: registration of appl loop function

Application-specific indication function for configuration

After initialization the application has the possibility to configure the GOAL system. The GOAL system expects the configuration in the indication function appl_setup() located in …\goal\appl\...\goal_appl.c normally:

Prototype

GOAL_STATUS_T appl_setup (void)

Description

This indication function allows to configure the GOAL system after initialization. This indication function is called by GOAL automatically in state GOAL_FSA_INIT_APPL_SETUP.

Parameters

None

Return values

GOAL return status, see Chapter: GOAL status

Category

Optional
If appl_setup() does not exist in the application, GOAL uses an empty default function.

Integration of user functions in staging system

The stage table is created in state GOAL_FSA_INIT. At the beginning of state GOAL_FSA_INIT_APPL the stage table is empty. Its entries are registered in the indication function appl_init() or by the GOAL core modules and GOAL extension modules in state GOAL_FSA_INIT_GOAL. The registration is made by function goal_mainStageReg(). Each callback function must have the following function prototype:

Code: callback function prototype

All staged initialization functions are executed after registration in the state GOAL_FSA_INIT_GOAL.

Example 7: At the end of the initialization the application-specific function applActivate() shall be called. applActivate() is assigned to stage GOAL_STAGE_GOAL. A new entry for the stage table is created about the declaration of stageReady. This new entry is appended to the stage table by function goal_mainStageReg(). The registration is located in the indication function appl_init().

Code: registration of stage function

GOAL evaluates the return value of staging functions. If such a function returns an error, the goal initialization will fail.

GOAL operation

In the state GOAL_FSA_OPERATION the GOAL system executes tasks, interrupt routines and loop-controlled functions. The loop-controlled functions are executed by calling the function goal_loop() in the main() function or in a task regularly without a valid cycle time. In goal_loop() the function appl_loop() and/or the listed loop functions are executed. The registration of loop functions is described in Chapter: Application-specific indication function for initialization.

GOAL finish

Halt

The GOAL system is stopped. The halt behavior is platform-specific and described in the suitable GOAL Platform Manual. GOAL requires the indication function goal_targetHalt() as platform API function:

Prototype

void goal_targetHalt(void)

Description

This indication function stops the program.

Parameters

None

Return values

None

Category

Mandatory

Reset

The GOAL system is reset and starts again. The reset behavior is platform-specific and described in the suitable GOAL Platform Manual. GOAL requires the indication function goal_targetReset() as platform API function:

Prototype

void goal_targetReset(void)

Description

This indication function resets the platform and re-starts the program.

Parameters

none

Return values

none

Category

mandatory