4.12. FTASK Module

4.12.1. Module Files

4.12.1.1. Driver

• src/app/task/ftask/ftask.c (API, source)

• src/app/task/ftask/ftask.h (API, source)

4.12.1.2. Configuration

• src/app/task/config/ftask_cfg.c (API, source)

• src/app/task/config/ftask_cfg.h (API, source)

4.12.1.3. Unit Test

• tests/unit/app/task/config/test_ftask_cfg.c

• tests/unit/app/task/ftask/test_ftask.c

4.12.2. Detailed Description

Note

The module name, and therefore all related file names, are prefixed with an f. The rationale behind this naming convention is that the operating system already provides a file named task.h and with using the f prefix it is unambiguous what file is meant.

foxBMS 2 uses five tasks, which are all configured in the ftask module. Table 4.1) shows

• the name by which the task is commonly referred to,

• the task creator function that creates the actual task,

• the user code function that is called periodically and

• purpose of the function.

The Engine task is the task with the highest priority and should not be modified (see Section 4.12.2.3.2).

The Idle task is not counted as a real task and is only mentioned for the sake of completeness and should not be modified (see Section 4.12.2.3.3).

Table 4.1 common task names, the function that creates the task and the function that is run cyclically

Common name	Task Creator Function	User Code Function	Comment
Idle task	-	FTSK_UserCodeIdle	This task SHOULD NOT be modified
Engine task	FTSK_TaskCreatorEngine	FTSK_UserCodeEngine	This task SHOULD NOT be modified
1ms cyclic task	FTSK_TaskCreatorCyclic1ms	FTSK_UserCodeCyclic1ms	User code can be put here
10ms cyclic task	FTSK_TaskCreatorCyclic10ms	FTSK_UserCodeCyclic10ms	User code can be put here
100ms cyclic	FTSK_TaskCreatorCyclic100ms	FTSK_UserCodeCyclic10ms	User code can be put here
100ms cyclic for algorithms	FTSK_TaskCreatorCyclicAlgorithm100ms	FTSK_UserCodeCyclicAlgorithm100ms	User code can be put here

The following sections show how tasks are created, configured and how task behavior can be changed. Code sections that are not meant to be modified by user are indicated in the code, e.g., for the Engine task:

Listing 4.1 Example of code that should not be modified by the user

 void FTSK_UserCodeEngine(void) {
     /* Warning: Do not change the content of this function */
     /* See function definition doxygen comment for details */
     DATA_Task();               /* Call database manager */
     SYSM_CheckNotifications(); /* Check notifications from tasks */
     /* Warning: Do not change the content of this function */
     /* See function definition doxygen comment for details */
 }

4.12.2.1. Task Creation

Warning

Task Creator Functions generally do not need to be modified by the user. User/application specific code should be implemented in the User Code Functions.

FTSK_CreateTasks creates these 4 tasks on startup. The procedure is the same for all tasks:

1. Try to create a static task (using the Task Creator Function) 1. Assert if this does not work.

The Task Creator Functions bind User Code Functions into the tasks. This is best explained using the example of the Engine task:

• Line 3: Run an initializer function before the task starts.

• Line 5: Delay the phase as specified in the configuration.

• Line 6: The task should run forever.

• Line 10: Bind the User Code Function to the task.

Before and after the the User Code Function is run, the System Monitoring Module is notified that either the User Code Function will be run or has run. This enables to determine if a task returns within the expected time frame.

Listing 4.2 Example of Task Creator Function

 void FTSK_TaskCreatorEngine(void) {
     os_boot = OS_SCHEDULER_RUNNING;
     FTSK_UserCodeEngineInit();
     os_boot = OS_ENGINE_RUNNING;

     OS_DelayTaskUntil(&os_schedulerStartTime, ftsk_taskDefinitionEngine.Phase);
     while (1) {
         /* notify system monitoring that task will be called */
         SYSM_Notify(SYSM_TASK_ID_ENGINE, SYSM_NOTIFY_ENTER, OS_GetTickCount());
         /* user code implementation */
         FTSK_UserCodeEngine();
         /* notify system monitoring that task has been called */
         SYSM_Notify(SYSM_TASK_ID_ENGINE, SYSM_NOTIFY_EXIT, OS_GetTickCount());
     }
 }

The other cyclic tasks are basically generated the same way. The main difference is that there is not a separate initialization function but one common for all other cyclic tasks. These other cyclic tasks do not start until the Task Creator Function FTSK_TaskCreatorEngine has set the boot state to os_boot = OS_ENGINE_RUNNING and the common initialization function for these tasks has finished.

4.12.2.2. Task Configuration

The tasks are configured in ftask_cfg.c regarding their startup phase, cycle time, priority and stack size.

4.12.2.3. Special User Tasks

There are four special user functions, three of these should not be modified by the user/application ( FTSK_UserCodeEngineInit and FTSK_UserCodeEngine, FTSK_UserCodeIdle) and one that is for user/application code (FTSK_UserCodePreCyclicTasksInitialization). All tasks share the suffix FTSK_UserCode for a consistent implementation of the Task Creator Functions and are not meant to be changed.

4.12.2.3.1. FTSK_UserCodeEngineInit

Before any tasks can start the database needs to be initialized. The database initialization is done by FTSK_UserCodeEngineInit().

4.12.2.3.2. FTSK_UserCodeEngine

This task should not be modified.

This task triggers the database and the system monitoring modules. The database module copies all data from the queue into the database variables. The system monitoring checks that all tasks run within their specified time frames.

4.12.2.3.3. FTSK_UserCodeIdle

This task should not be modified.

This task is bound to the operating system idle hook (vApplicationIdleHook).

4.12.2.3.4. FTSK_UserCodePreCyclicTasksInitialization

Peripherals and resources that need to be usable as soon as the periodic tasks are running are initialized here.

4.12.2.4. User Tasks

The functions shown in Table 4.2 are provided by the ftask module to run user/application specific code:

Table 4.2 ftask User Code Functions

Function	Description
FTSK_UserCodeCyclic1ms	Code that should be run every 1ms
FTSK_UserCodeCyclic10ms	Code that should be run every 10ms
FTSK_UserCodeCyclic100ms	Code that should be run every 100ms
FTSK_UserCodeCyclicAlgorithm100ms	Code that should be run every 100ms, but with a lower priority than FTSK_UserCodeCyclic100ms

4.12.3. Further Reading

A How-to is found in How to Use the FTASK Module.