Table of contents
1.5. Function of software timer service tasks
1.6. Software timer command queue
1.7. Software timer related configuration
1.8. One-shot timer and period timer
2. Software timer related API functions
2.1. Create software timer function
2.2. Enable software timer function
2.3. Stop the software timer function
2.4. Reset software timer function
2.5. Change the software timer timeout function
2.6. Delete software timer function
illustrate:
About the content:
1) The following contents are mostly conceptual understanding and step analysis
2) There is no personal sample code yet. The official sample code of FreeRTOS is used.
3) If you want to transplant the code for testing, please look elsewhere. There is no personal sample code for testing in the following content.
About others:
1) Operating system: win 10
2) Platform: keil 5 mdk
3) Language: c language
4) Board: STM32 series transplanted to FreeRTOS
1. Introduction to timer
1.1. Timer
Starting from the specified time, after a specified time, a timeout event is triggered. The user can customize the timer period.
1.2. Software timer
It refers to software with a timing function. You can set a timing period. When the specified time is reached, a callback function (also called a timeout function) is called. The user processes information in the callback function .
advantage:
1) The number of hardware timers is limited, and in theory, multiple software timers can be created as long as there is enough memory;
2) Easy to use and low cost.
shortcoming:
1) The software timer is not as accurate as the hardware timer (because it is based on the system clock, and the system clock interrupt priority is the lowest and is easily interrupted). For occasions requiring high accuracy, it is not recommended to use software timers.
1.3. Hardware timer
The chip itself comes with a timer module. The hardware timer has a very high accuracy (higher than the software timer). Every time the timer arrives, an interrupt is automatically triggered. The user processes the information in the interrupt service function .
1.4. FreeRTOS software timer
Features:
1) Can be cut. The software timer is a cuttable and configurable function. If you want to enable the software timer, you need to set the macro definition: configUSE_TIMERT configuration item to 1 (if not used, set it to 0);
2) Single and periodic, the software timer supports setting to: single timer or periodic timer.
important point:
1) The timeout callback function of the software timer is called by the software timer service task. The timeout callback function of the software timer itself is not a task, so API functions that may cause task blocking cannot be used in the callback function;
2) Software timer service task: When calling the function vTaskStartScheduler() to start the task scheduler, a task for managing software timers will be created. This task is called --> software timer service task.
1.5. Function of software timer service tasks
1) Responsible for the logical judgment of software timer timeout;
2) Call the timeout callback function of the timeout software timer;
3) Process the software timer command queue.
1.6. Software timer command queue
FreeRTOS provides many API functions related to software timers. Most of these API functions write messages to the timer queue (essentially sending commands). This queue is called the software timer command queue and is provided to FreeRTOS. Used by software timers and cannot be accessed directly by users.
For example: Define a task and start the timer (API function writes messages to the software timer command queue and sends commands) --> Software timer command queue --> Software timer task reads software timer command queue messages ( receive commands).
1.7. Software timer related configuration
1) If you want to enable the software timer, you need to set the macro definition: configUSE_TIMERT configuration item to 1 (set to 0 if not used). When starting the task scheduler, the service/daemon task prvTimerTask() of the software timer will be automatically created. ;
2) The priority of the software timer service task is configTIMER_TASK_PRIORITY=31 (maximum task priority);
3) The timer’s command queue length is configTIMER_QUEUE_LENGTH=5.
important point:
1) The timeout callback function of the software timer is called in the software timer service task. The service task is not dedicated to serving a certain timer. It also processes other timers, so the timer callback function --> Do not affect other timer tasks, that is, do not call API functions that will block tasks, such as: vTaskDelay();
2) API functions that access queues or semaphores with non-zero blocking time cannot be called.
Software timer status:
1) Sleeping state: The software timer can be referenced through its handle, but because it is not running, its timeout callback function will not be executed;
2) Running state: When the timer in the running state reaches the specified time, its timeout callback function will be called.
Note: The newly created software timer is in dormant state, that is, it is not running.
So how to change the software timer from sleep state to running state?
Send command queue!
1.8. One-shot timer and period timer
1) Single timer: Once the single timer times out, its software timer timeout callback function will be executed once and the timer will not be automatically restarted, but it can be manually restarted;
2) Periodic timer: Once started, the periodic timer will automatically restart after executing the callback function, thereby periodically executing its software timer callback function.
1.9. Software timer structure
Structure members:
typedef struct tmrTimerControl
{
const char * pcTimerName;
ListItem_t xTimerListItem;
TickType_t xTimerPeriodInTicks;
void * pvTimerID;
TimerCallbackFunction_t pxCallbackFunction;
#if ( configUSE_TRACE_FACILITY == 1 )
UBaseType_t uxTimerNumber;
#endif
uint8_t ucStatus;
} xTIMER;
meaning:
Name, pcTimerName, meaning: software timer name
Name, xTimerListItem, meaning: then timer list item
Name, xTimerPeriodInTicks, meaning: software timer period
Name, pvTimerID, meaning: software timer ID --> distinguish between different timers
Name, pxCallbackFunction, meaning: software timer callback function
Name, uxTimerNumber, meaning: software timer number, used for debugging
Name, ucStatus, meaning: status of software timer
2. Software timer related API functions
2.1. Create software timer function
Dynamically create function implementation:
TimerHandle_t xTimerCreate( const char * const pcTimerName,
const TickType_t xTimerPeriodInTicks,
const UBaseType_t uxAutoReload,
void * const pvTimerID,
TimerCallbackFunction_t pxCallbackFunction );
Parameter meaning:
Name, pcTimerName, meaning: software timer name
Name, xTimerPeriodInTicks, meaning: scheduled timeout time, unit: system clock beat
Name, uxAutoReload, meaning: timer mode, pdTRUE: periodic timer, pdFALSE: single-shot timer
Name, pvTimerID, meaning: software timer ID, used to distinguish multiple software timers when they share a callback function
Name, pxCallbackFunction, meaning: software timer timeout callback function
Return value meaning:
Return, NULL, meaning: software timer creation failed
Return, other values, meaning: the software timer is successfully created and the handle is returned
2.2. Enable software timer function
Code:
BaseType_t xTimerStart( TimerHandle_t xTimer, TickType_t xTicksToWait );
Parameter meaning:
Name, xTimer, meaning: handle of the software timer to be started
Name, xTicksToWait, meaning: maximum waiting time for sending commands to the software timer command queue
Return value meaning:
Return, pdPASS, meaning: software timer started successfully
Return, pdFAIL, meaning: software timer failed to start
2.3. Stop the software timer function
Code:
BaseType_t xTimerStop( TimerHandle_t xTimer, TickType_t xTicksToWait );
Parameter meaning:
Name, xTimer, meaning: handle of the software timer to be stopped
Name, xTicksToWait, meaning: maximum waiting time for sending commands to the software timer command queue
Return value meaning:
Return, pdPASS, meaning: software timer stopped successfully
Return, pdFAIL, meaning: software timer stop failed
2.4. Reset software timer function
Code:
BaseType_t xTimerReset( TimerHandle_t xTimer, TickType_t xTicksToWait );
Parameter meaning:
Name, xTimer, meaning: software timer handle to be reset
Name, xTicksToWait, meaning: maximum waiting time for sending commands to the software timer command queue
Return value meaning:
Return, pdPASS, meaning: software timer reset successful
Return, pdFAIL, meaning: software timer reset failed
illustrate:
This function will enable the software timer to restart timing. After reset, the software timer will start counting from 0 time units again.
2.5. Change the software timer timeout function
Code:
BaseType_t xTimerChangePeriod( TimerHandle_t xTimer,
TickType_t xNewPeriod,
TickType_t xTicksToWait );
Parameter meaning:
Name, xTimer, meaning: software timer handle to be updated
Name, xNewPeriod, meaning: new scheduled timeout, unit: system clock beat
Name, xTicksToWait, meaning: maximum waiting time for sending commands to the software timer command queue
Return value meaning:
Return, pdPASS, meaning: Software timer timeout time modified successfully
Return, pdFAIL, meaning: Software timer timeout time modification failed
2.6. Delete software timer function
Code:
BaseType_t xTimerDelete( TimerHandle_t xTimer, TickType_t xTicksToWait );
Parameter meaning:
Name, xTimer, meaning: software timer handle to be deleted
Name, xTicksToWait, meaning: maximum waiting time for sending commands to the software timer command queue