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
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.
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.
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
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
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.
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
do_stuff()
will execute continuously each time the processor is not occupied by the critical task.
Class 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.
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.
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.
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.
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
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.
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.
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