# Atmel Software Framework

vSemaphoreCreateMutex

semphr.

h

xSemaphoreHandle xSemaphoreCreateMutex( void )

Macro that implements a mutex semaphore by using the existing queue mechanism.

Mutexes created using this macro can be accessed using the xSemaphoreTake() and xSemaphoreGive() macros. The xSemaphoreTakeRecursive() and xSemaphoreGiveRecursive() macros should not be used.

This type of semaphore uses a priority inheritance mechanism so a task 'taking' a semaphore MUST ALWAYS 'give' the semaphore back once the semaphore it is no longer required.

Mutex type semaphores cannot be used from within interrupt service routines.

See vSemaphoreCreateBinary() for an alternative implementation that can be used for pure synchronisation (where one task or interrupt always 'gives' the semaphore and another always 'takes' the semaphore) and from within interrupt service routines.

Returns
xSemaphore Handle to the created mutex semaphore. Should be of type xSemaphoreHandle.

Example usage:

 xSemaphoreHandle xSemaphore;
 void vATask( void * pvParameters )
{
Semaphore cannot be used before a call to xSemaphoreCreateMutex().
This is a macro so pass the variable in directly.
xSemaphore = xSemaphoreCreateMutex();
    if( xSemaphore != NULL )
{
The semaphore was created successfully.
The semaphore can now be used.
}
}


h

xSemaphoreHandle xSemaphoreCreateRecursiveMutex( void )

Macro that implements a recursive mutex by using the existing queue mechanism.

Mutexes created using this macro can be accessed using the xSemaphoreTakeRecursive() and xSemaphoreGiveRecursive() macros. The xSemaphoreTake() and xSemaphoreGive() macros should not be used.

A mutex used recursively can be 'taken' repeatedly by the owner. The mutex doesn't become available again until the owner has called xSemaphoreGiveRecursive() for each successful 'take' request. For example, if a task successfully 'takes' the same mutex 5 times then the mutex will not be available to any other task until it has also 'given' the mutex back exactly five times.

This type of semaphore uses a priority inheritance mechanism so a task 'taking' a semaphore MUST ALWAYS 'give' the semaphore back once the semaphore it is no longer required.

Mutex type semaphores cannot be used from within interrupt service routines.

See vSemaphoreCreateBinary() for an alternative implementation that can be used for pure synchronisation (where one task or interrupt always 'gives' the semaphore and another always 'takes' the semaphore) and from within interrupt service routines.

Returns
xSemaphore Handle to the created mutex semaphore. Should be of type xSemaphoreHandle.

Example usage:

 xSemaphoreHandle xSemaphore;
 void vATask( void * pvParameters )
{
Semaphore cannot be used before a call to xSemaphoreCreateMutex().
This is a macro so pass the variable in directly.
xSemaphore = xSemaphoreCreateRecursiveMutex();
    if( xSemaphore != NULL )
{
The semaphore was created successfully.
The semaphore can now be used.
}
}