4.12. FTASK Module

4.12.1. Module Files

4.12.1.1. Driver

  • src/app/task/ftask/ftask.c

  • src/app/task/ftask/ftask.h

4.12.1.1.1. FreeRTOS

  • src/app/task/ftask/freertos/ftask_freertos.c

4.12.1.2. Configuration

  • src/app/task/config/ftask_cfg.c

  • src/app/task/config/ftask_cfg.h

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_RunUserCodeIdle

This task SHOULD NOT be modified

Engine task

FTSK_CreateTaskEngine

FTSK_RunUserCodeEngine

This task SHOULD NOT be modified

1ms cyclic task

FTSK_CreateTaskCyclic1ms

FTSK_RunUserCodeCyclic1ms

User code can be put here

AFE non-cyclic task FTSK_CreateTaskAfe

FTSK_RunUserCodeAfe

User code can be put here

10ms cyclic task

FTSK_CreateTaskCyclic10ms

FTSK_RunUserCodeCyclic10ms

User code can be put here

I2C non-cyclic task FTSK_CreateTaskI2c

FTSK_RunUserCodeI2c

User code can be put here

100ms cyclic

FTSK_CreateTaskCyclic100ms

FTSK_RunUserCodeCyclic100ms

User code can be put here

100ms cyclic for algorithms

FTSK_CreateTaskCyclicAlgorithm100ms

FTSK_RunUserCodeCyclicAlgorithm100ms

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.4 Example of code that should not be modified by the user
1 void FTSK_RunUserCodeEngine(void) {
2     /* Warning: Do not change the content of this function */
3     /* See function definition doxygen comment for details */
4     DATA_Task();               /* Call database manager */
5     SYSM_CheckNotifications(); /* Check notifications from tasks */
6     /* Warning: Do not change the content of this function */
7     /* See function definition doxygen comment for details */
8 }

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)

  2. 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.5 Example of Task Creator Function
 1 void FTSK_CreateTaskEngine(void) {
 2     os_boot = OS_SCHEDULER_RUNNING;
 3     FTSK_InitializeUserCodeEngine();
 4     os_boot = OS_ENGINE_RUNNING;
 5
 6     OS_DelayTaskUntil(&os_schedulerStartTime, ftsk_taskDefinitionEngine.Phase);
 7     while (true) {
 8         /* notify system monitoring that task will be called */
 9         SYSM_Notify(SYSM_TASK_ID_ENGINE, SYSM_NOTIFY_ENTER, OS_GetTickCount());
10         /* user code implementation */
11         FTSK_RunUserCodeEngine();
12         /* notify system monitoring that task has been called */
13         SYSM_Notify(SYSM_TASK_ID_ENGINE, SYSM_NOTIFY_EXIT, OS_GetTickCount());
14     }
15 }

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_CreateTaskEngine 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_InitializeUserCodeEngine and FTSK_RunUserCodeEngine, FTSK_RunUserCodeIdle) and one that is for user/application code (FTSK_InitializeUserCodePreCyclicTasks). All tasks share the suffix FTSK_RunUserCode for a consistent implementation of the Task Creator Functions and are not meant to be changed.

4.12.2.3.1. FTSK_InitializeUserCodeEngine

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

4.12.2.3.2. FTSK_RunUserCodeEngine

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_RunUserCodeIdle

This task should not be modified.

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

4.12.2.3.4. FTSK_InitializeUserCodePreCyclicTasks

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_RunUserCodeCyclic1ms

Code that should be run every 1ms

FTSK_RunUserCodeAfe

Code for communication with AFE, continuously running task, must be blocked long enough (i.e., during bus communication) to leave CPU time for other tasks

FTSK_RunUserCodeCyclic10ms

Code that should be run every 10ms

FTSK_RunUserCodeI2c

Code for communication with I2C devices, continuously running task, must be blocked long enough (i.e., during bus communication) to leave CPU time for other tasks

FTSK_RunUserCodeCyclic100ms

Code that should be run every 100ms

FTSK_RunUserCodeCyclicAlgorithm100ms

Code that should be run every 100ms, but with a lower priority than FTSK_RunUserCodeCyclic100ms

4.12.3. Further Reading

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