PowerAPI is meant to deploy easily Real-time programs that must guarantee response within specified time constraints. In that context, scheduling is the action of asigning computing ressources to perform tasks.

Include

Note

#include <TaskAPI.h>

Make sure that Task API is included

Deploying a real time control task

Having a periodical code execution is key to real time applications. It is easy to spawn one using the TaskAPI.

The control task sources

You can have different source calling the control task.

The control task is synchronous, it means that it is called at fixed period. So we need some kind of timer calling the control, this timer is considered as the source. There are two sources :
- The PWM carrier
- An independant timer

The PWM carrier

The carrier has a period called the switching period, we can use it to call the control task after a fixed number of switching period.

PWM control task

On the figure above, the switching period is 5µs (200Khz) and we call the control every 10 switching cycle so 50µs (20Khz).

Warning

There are limitations when using this method :
- You need to start the a PWM to start the control task
- You can only have control period which are multiple of the switching period
- You can not have a control period inferior to the switching period

Tip

Synchronizing the control task period with PWM period can be usefull when you try to synchronize PWM between several SPIN or TWIST, in that case the control task is also synchronized between the board.

Independant timer

A simple timer not related to the PWM can be used to compute the control task period. We choose one of the MCU timer (the timer 6), to which we give our control period and this timer will call the control task each period.

timer source

Tip

With an independant timer you can choose any value in µs as the control period, there is not the same limitation as the PWM source.

Warning

The disavantage of such method is that since it is independant from the PWM you can't have synchronization between several control task modules.

Initialization sequence

Note

Periodic task based on PWM sourcePeriodic task based on Timer6

1. Create the critical task and link it to the function to be called and choose hrtim as the source source. task.createCritical(critical_function, control_period, source_hrtim);
2. Start the critical function. task.startCritical()

1. Create the critical task and link it to the function to be called and choose tim6 as the source. task.createCritical(critical_function, control_period, source_tim6);
2. Start the critical function. task.startCritical()

Example

20kHz Periodic task based on PWM10kHz Periodic task based on Timer6

    task.createCritical(my_critical_function, 50, source_hrtim); 
    task.startCritical();

    task.createCritical(my_critical_function, 100, source_tim6);
    task.startCritical();

Tip

Having a control Task is required for synchronous measurements to work correctly.

Non time critical tasks

In the powerAPI, non time critical tasks are refered as background tasks.

Priority between critical and non-critical task

The control task has priority over any other task. It will preempts any background task. The control task can not be preempted. That is why it is also refered as an uninteruptible task.

task priority

Pseudo periodicity of non-critical task

Non-critical tasks aren't synchronous, meaning they're not recurring at regular intervals. Instead, they operate in a pseudo-periodic manner: we can temporarily halt them for a specific duration, during which they remain inactive. Below, in the illustration we suspend the background task for a period of 500ms. After 500ms we can execute again the background task, but we need to end the control task to do that (the critical task is uninteruptible).

Initialization sequence

Note

1. Create the background task and link it to the function to be called. task.createBackground(function)
2. Start the background function. task.startCritical()

Example

Spawning a background taskMaking it pseudo periodic

    void my_background_function(){
        do_stuff();
    }
    task.createBackground(my_background_function);

In that case do_stuff() will execute continuously each time the processor is not occupied by the critical task.

    void my_background_function(){
        do_stuff();
        suspendBackgroundUs(500);
    }

In that case after executing do_stuff(); the task will be suspended for 500us and resumed after. It creates a pseudo periodical task, runs every 500us + the time taken to execute do_stuff().

Class TaskAPI

ClassList > TaskAPI

Public Functions

Type	Name
int8_t	createBackground (task_function_t routine) Creates a background task. Background tasks are asynchronous tasks that run in the background when there is no critical task running.
int8_t	createCritical (task_function_t periodic_task, uint32_t task_period_us, scheduling_interrupt_source_t int_source=source_hrtim) Creates a time critial task. A critical task is an Uninterruptible Synchronous Task that uses a precise timer to execute a periodic, non-interruptible user task. Use this function to define such a task. Only one task of this kind can be defined. This function can be used to redefine (replace) a previously defined uninterruptible synchronous task, but the previously defined task must have been suspended (or never started). An error will be returned if the previously defined task is still running.
void	startBackground (uint8_t task_number) Use this function to start a previously defined background task using its task number.
void	startCritical (bool manage_data_acquisition=true) Use this function to start a previously defined a critical task.
void	stopBackground (uint8_t task_number) Use this function to stop a previously started background task using its task number.
void	stopCritical () Stop the previously started critical task. A critical task is an Uninterruptible Synchronous Task that uses a precise timer to execute a periodic, non-interruptible user task. The task can be then resumed by calling startCritical() again.
void	suspendBackgroundMs (uint32_t duration_ms) This function allows to suspend a background task for a specified duration expressed in milliseconds. For example, you can call this function at the end of a background task function, when there is no need for the task to run permanently.
void	suspendBackgroundUs (uint32_t duration_us) This function allows to suspend a background task for a specified duration expressed in microseconds. For example, you can call this function at the end of a background task function, when there is no need for the task to run permanently.

Public Functions Documentation

function createBackground

Creates a background task. Background tasks are asynchronous tasks that run in the background when there is no critical task running.

int8_t TaskAPI::createBackground (
    task_function_t routine
)

Parameters:

routine Pointer to the void(void) function that will act as the task main function.

Returns:

Number assigned to the task. Will be -1 if max number of asynchronous task has been reached. In such a case, the task definition is ignored. Increase maximum number of asynchronous tasks in prj.conf if required.

function createCritical

Creates a time critial task. A critical task is an Uninterruptible Synchronous Task that uses a precise timer to execute a periodic, non-interruptible user task. Use this function to define such a task. Only one task of this kind can be defined. This function can be used to redefine (replace) a previously defined uninterruptible synchronous task, but the previously defined task must have been suspended (or never started). An error will be returned if the previously defined task is still running.

int8_t TaskAPI::createCritical (
    task_function_t periodic_task,
    uint32_t task_period_us,
    scheduling_interrupt_source_t int_source=source_hrtim
)

Parameters:

periodic_task Pointer to the void(void) function to be executed periodically.
task_period_us Period of the function in µs. Allowed range: 1 to 6553 µs. If interrupt source is HRTIM, this value MUST be an integer multiple of the HRTIM period.
int_source Interrupt source that triggers the task. By default, the HRTIM is the source, but this optional parameter can be provided to set TIM6 as the source in case the HRTIM is not used or if the task can't be correlated to an HRTIM event. Allowed values are source_hrtim and source_tim6.

Returns:

0 if everything went well, -1 if there was an error defining the task. An error can occur notably when an uninterruptible task has already been defined previously.

function startBackground

Use this function to start a previously defined background task using its task number.

void TaskAPI::startBackground (
    uint8_t task_number
)

Background tasks are asynchronous tasks that run in the background when there is no critical task running.

Parameters:

task_number Number of the task to start, obtained using the defineAsynchronousTask() function.

function startCritical

Use this function to start a previously defined a critical task.

void TaskAPI::startCritical (
    bool manage_data_acquisition=true
)

A critical task is an Uninterruptible Synchronous Task that uses a precise timer to execute a periodic, non-interruptible user task.

If no value is provided for the parameter and Data Acquisition has not been started yet, Scheduling will automatically start Data Acquisition. Thus, make sure all ADC configuration has been carried out before starting the uninterruptible task.

Parameters:

manage_data_acquisition Set to false if you want the Scheduling module to not be in charge of Data Acquisition scheduling. If set to false, Data Acquisition has to be manually started if you want to use it.

function stopBackground

Use this function to stop a previously started background task using its task number.

void TaskAPI::stopBackground (
    uint8_t task_number
)

Background tasks are asynchronous tasks that run in the background when there is no critical task running. The task can be then resumed by calling startAsynchronousTask() again.

Parameters:

task_number Number of the task to start, obtained using the defineAsynchronousTask() function.

function stopCritical

Stop the previously started critical task. A critical task is an Uninterruptible Synchronous Task that uses a precise timer to execute a periodic, non-interruptible user task. The task can be then resumed by calling startCritical() again.

void TaskAPI::stopCritical ()

function suspendBackgroundMs

This function allows to suspend a background task for a specified duration expressed in milliseconds. For example, you can call this function at the end of a background task function, when there is no need for the task to run permanently.

void TaskAPI::suspendBackgroundMs (
    uint32_t duration_ms
)

DO NOT use this function in a critical task!

function suspendBackgroundUs

This function allows to suspend a background task for a specified duration expressed in microseconds. For example, you can call this function at the end of a background task function, when there is no need for the task to run permanently.

void TaskAPI::suspendBackgroundUs (
    uint32_t duration_us
)

DO NOT use this function in a critical task!

The documentation for this class was generated from the following file docs/core/zephyr/modules/owntech_task_api/zephyr/public_api/TaskAPI.h