One, the header file

#include "FreeRTOS.h"
#include "semphr.h"

Two, mutual exclusion

2.1 Basic concepts

Mutex, also known as mutual exclusion semaphore (essentially a semaphore), is a special binary semaphore, which is different from a semaphore in that it supports mutex ownership, recursive access, and features to prevent priority inversion , Used to achieve exclusive treatment of critical resources. There are only two states of mutex at any time, unlocked or locked . When the mutex is held by the task, the mutex is in a locked state, and the task obtains the ownership of the mutex. When the task releases the mutex, the mutex is in an unlocked state, and the task loses ownership of the mutex. When a task holds a mutex, other tasks can no longer unlock or hold the mutex. The task holding the mutex can also obtain the lock again without being suspended. This is the recursive access, which is the characteristic of the recursive mutex. This characteristic is very different from the general semaphore. In, because there is no available semaphore, when the task recursively acquires the semaphore, the active suspension of the task will eventually form a deadlock.

If you want to use for synchronization (between tasks or between tasks and interrupt) implementation, a binary semaphore may be a better choice, although the task and interrupt synchronization mutex can also be used for tasks and task, but mutual Expulsion is more an interlock used to protect resources.

The mutex used for interlocking can act as a token to protect resources. When a task wants to access a certain resource, it must first obtain the token. When the task has finished using the resource, it must return the token so that other tasks can access the resource. Is it very familiar? It is the same in our binary semaphore, which is used to protect critical resources and ensure orderly access to multitasking. Only when the task acquires the semaphore can it start using the protected resources, and release the semaphore when it is used up, and the next task can acquire the semaphore so that the protected resources can be used. But another potential problem that semaphores can cause is task priority inversion. The mutexes provided by FreeRTOS can use priority inheritance algorithms to reduce the impact of priority inversion problems. Therefore, it is generally recommended to use mutexes for the protection of critical resources.

2.2 Operation mechanism

When using mutexes to handle simultaneous access to critical resources by different tasks, tasks can only access resources if they want to obtain the mutex. Once a task successfully obtains the mutex, the mutex will immediately become locked. Other tasks will not be able to access this resource because they cannot obtain the mutex. The task will wait according to the user-defined waiting time. After the mutex is released by the held task, other tasks can obtain the mutex and gain access. The critical resource, the mutex is locked again at this time, so that it can be ensured that only one task is accessing the critical resource at any time, ensuring the safety of critical resource operations.

2.3 Mutex and Recursive Mutex

Mutex is more suitable for situations that may cause priority inversion.
Recursive mutexes are more suitable for situations where tasks may acquire mutexes multiple times. This can avoid deadlocks caused by multiple recursive holdings of the same task.

3. Related API description

3.1 xSemaphoreCreateMutex

Used to create a mutex and return a mutex handle.

function	#define xSemaphoreCreateMutex() xQueueCreateMutex( queueQUEUE_TYPE_MUTEX )
parameter	no
return value	Mutex handle

To use this function must be FreeRTOSConfig.hin the configSUPPORT_DYNAMIC_ALLOCATIONdefined to be enabled.

At the same time we must be FreeRTOSConfig.hin the configUSE_MUTEXESdefined to be enabled.

3.2 xSemaphoreCreateRecursiveMutex

Used to create a recursive mutex, a mutex that is not recursive is created by the function xSemaphoreCreateMutex() or xSemaphoreCreateMutexStatic(), and can only be acquired by the same task once. If the same task wants to acquire it again, it will fail. Recursive semaphore is the opposite. It can be acquired many times by the same task, and it needs to be released as many times as it is acquired. The recursive semaphore, like the mutex, implements the priority inheritance mechanism, which can reduce the anti-generation of priority inversion.

function	#define xSemaphoreCreateRecursiveMutex() xQueueCreateMutex( queueQUEUE_TYPE_RECURSIVE_MUTEX )
parameter	no
return value	Recursive mutex handle

3.3 vSemaphoreDelete

Used to delete a semaphore, including binary semaphore, counting semaphore, mutex and recursive
mutex. If there are tasks blocked on the semaphore, do not delete the semaphore.

function	void vSemaphoreDelete( SemaphoreHandle_t xSemaphore )
parameter	xSemaphore: semaphore handle
return value	no

3.4 xSemaphoreTake

It is used to obtain semaphore without interrupt protection. The acquired semaphore objects can be binary semaphores, counting semaphores and mutexes, but recursive mutexes cannot be acquired using this API function.

function	xSemaphoreTake( SemaphoreHandle_t xSemaphore, TickType_t xBlockTime )
parameter	xSemaphore: semaphore handle xBlockTime: the maximum timeout time for waiting for the semaphore to be available, in tick (that is, the system tick period). If the macro INCLUDE_vTaskSuspend is defined as 1 and the formal parameter xTicksToWait is set to portMAX_DELAY, the task will always be blocked on the semaphore (that is, there is no timeout period)
return value	Return pdTRUE on success, otherwise return errQUEUE_EMPTY

3.5 xSemaphoreTakeRecursive

The macro used to obtain the recursive mutex is the same as the mutex acquisition function. xSemaphoreTakeRecursive() is also a macro definition. It finally uses the existing queue mechanism. The actual execution function is xQueueTakeMutexRecursive(). Before obtaining the recursive mutex, it must be created by the function xSemaphoreCreateRecursiveMutex(). It should be noted that this function cannot be used to obtain the mutex created by the function xSemaphoreCreateMutex().

function	#define xSemaphoreTakeRecursive( xMutex, xBlockTime ) xQueueTakeMutexRecursive( ( xMutex ), ( xBlockTime ) )
parameter	xMutex: semaphore handle xBlockTime: if it is not a task that holds a mutex to obtain an invalid mutex, the task will wait for the user to specify a timeout period, in tick (ie the system tick period). If the macro INCLUDE_vTaskSuspend is defined as 1 and the formal parameter xTicksToWait is set to portMAX_DELAY, the task will always be blocked on the recursive mutex (that is, there is no timeout)
return value	Return pdTRUE on success, otherwise return errQUEUE_EMPTY

function

#define xSemaphoreTakeRecursive( xMutex, xBlockTime ) xQueueTakeMutexRecursive( ( xMutex ), ( xBlockTime ) )

parameter

xMutex: semaphore handle
xBlockTime: if it is not a task that holds a mutex to obtain an invalid mutex, the task will wait for the user to specify a timeout period, in tick (ie the system tick period). If the macro INCLUDE_vTaskSuspend is defined as 1 and the formal parameter xTicksToWait is set to portMAX_DELAY, the task will always be blocked on the recursive mutex (that is, there is no timeout)

return value

Return pdTRUE on success, otherwise return errQUEUE_EMPTY

To use this function must be FreeRTOSConfig.hin the configUSE_RECURSIVE_MUTEXESdefined to be enabled.

3.6 xSemaphoreGive

The macro used to release the semaphore. The released semaphore object must have been created, and can be used to release binary semaphores, counting semaphores, and mutexes, but cannot release the recursive mutex created by the function xSemaphoreCreateRecursiveMutex(). In addition, this function cannot be used in interrupts.

function	xSemaphoreGive( SemaphoreHandle_t xSemaphore )
parameter	xSemaphore: semaphore handle
return value	Return pdTRUE on success, otherwise return pdFALSE

3.7 xSemaphoreGiveRecursive

Used to release a recursive mutex. Tasks that have already acquired the recursive mutex can repeatedly acquire the recursive mutex. If you use the xSemaphoreTakeRecursive() function to successfully obtain the recursive mutex several times, you must use the xSemaphoreGiveRecursive() function to return it several times. Before that, the recursive mutex is in an invalid state, and other tasks cannot obtain the recursive mutex. When using this function interface, only the task that has the ownership of the mutex can release it. Each time the recursive mutex is released, its count value is reduced by 1. When the count value of the mutex is 0 (that is, the holding task has released all holding operations), the mutex becomes unlocked, and the tasks waiting on the mutex will be awakened. If the priority of the task is temporarily increased by the priority inversion mechanism of the mutex, then when the mutex is released, the priority of the task will return to the originally set priority.

function	#define xSemaphoreGiveRecursive( xMutex ) xQueueGiveMutexRecursive( ( xMutex ) )
parameter	xMutex: semaphore handle
return value	Return pdTRUE on success, otherwise return pdFALSE