@ -145,10 +145,23 @@ typedef QueueHandle_t SemaphoreHandle_t;
* semphr . h
* < pre > SemaphoreHandle_t xSemaphoreCreateBinary ( void ) < / pre >
*
* Creates a new binary semaphore instance , and returns a handle by which the
* new semaphore can be referenced .
*
* In many usage scenarios it is faster and more memory efficient to use a
* direct to task notification in place of a binary semaphore !
* http : //www.freertos.org/RTOS-task-notifications.html
*
* Internally , within the FreeRTOS implementation , binary semaphores use a block
* of memory , in which the semaphore structure is stored . If a binary semaphore
* is created using xSemaphoreCreateBinary ( ) then the required memory is
* automatically dynamically allocated inside the xSemaphoreCreateBinary ( )
* function . ( see http : //www.freertos.org/a00111.html). If a binary semaphore
* is created using xSemaphoreCreateBinaryStatic ( ) then the application writer
* can instead optionally provide the memory that will get used by the binary
* semaphore . xSemaphoreCreateBinaryStatic ( ) therefore allows a binary
* semaphore to be created without using any dynamic memory allocation .
*
* The old vSemaphoreCreateBinary ( ) macro is now deprecated in favour of this
* xSemaphoreCreateBinary ( ) function . Note that binary semaphores created using
* the vSemaphoreCreateBinary ( ) macro are created in a state such that the
@ -156,11 +169,6 @@ typedef QueueHandle_t SemaphoreHandle_t;
* created using xSemaphoreCreateBinary ( ) are created in a state such that the
* the semaphore must first be ' given ' before it can be ' taken ' .
*
* Function that creates a semaphore by using the existing queue mechanism .
* The queue length is 1 as this is a binary semaphore . The data size is 0
* as nothing is actually stored - all that is important is whether the queue is
* empty or full ( the binary semaphore is available or not ) .
*
* This type of semaphore can be used for pure synchronisation between tasks or
* between an interrupt and a task . The semaphore need not be given back once
* obtained , so one task / interrupt can continuously ' give ' the semaphore while
@ -168,7 +176,8 @@ typedef QueueHandle_t SemaphoreHandle_t;
* semaphore does not use a priority inheritance mechanism . For an alternative
* that does use priority inheritance see xSemaphoreCreateMutex ( ) .
*
* @ return Handle to the created semaphore .
* @ return Handle to the created semaphore , or NULL if the memory required to
* hold the semaphore ' s data structures could not be allocated .
*
* Example usage :
< pre >
@ -176,7 +185,7 @@ typedef QueueHandle_t SemaphoreHandle_t;
void vATask ( void * pvParameters )
{
// Semaphore cannot be used before a call to vSemaphoreCreateBinary ().
// Semaphore cannot be used before a call to xSemaphoreCreateBinary ().
// This is a macro so pass the variable in directly.
xSemaphore = xSemaphoreCreateBinary ( ) ;
@ -187,13 +196,78 @@ typedef QueueHandle_t SemaphoreHandle_t;
}
}
< / pre >
* \ defgroup vSemaphoreCreateBinary v SemaphoreCreateBinary
* \ defgroup xSemaphoreCreateBinary x SemaphoreCreateBinary
* \ ingroup Semaphores
*/
# define xSemaphoreCreateBinary() xQueueGenericCreate( ( UBaseType_t ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH, NULL, NULL, queueQUEUE_TYPE_BINARY_SEMAPHORE )
/**
* semphr . h
* < pre > SemaphoreHandle_t xSemaphoreCreateBinaryStatic ( StaticSemaphore_t * pxSemaphoreBuffer ) < / pre >
*
* Creates a new binary semaphore instance , and returns a handle by which the
* new semaphore can be referenced .
*
* NOTE : In many usage scenarios it is faster and more memory efficient to use a
* direct to task notification in place of a binary semaphore !
* http : //www.freertos.org/RTOS-task-notifications.html
*
* Internally , within the FreeRTOS implementation , binary semaphores use a block
* of memory , in which the semaphore structure is stored . If a binary semaphore
* is created using xSemaphoreCreateBinary ( ) then the required memory is
* automatically dynamically allocated inside the xSemaphoreCreateBinary ( )
* function . ( see http : //www.freertos.org/a00111.html). If a binary semaphore
* is created using xSemaphoreCreateBinaryStatic ( ) then the application writer
* can instead optionally provide the memory that will get used by the binary
* semaphore . xSemaphoreCreateBinaryStatic ( ) therefore allows a binary
* semaphore to be created without using any dynamic memory allocation .
*
* This type of semaphore can be used for pure synchronisation between tasks or
* between an interrupt and a task . The semaphore need not be given back once
* obtained , so one task / interrupt can continuously ' give ' the semaphore while
* another continuously ' takes ' the semaphore . For this reason this type of
* semaphore does not use a priority inheritance mechanism . For an alternative
* that does use priority inheritance see xSemaphoreCreateMutex ( ) .
*
* @ param pxSemaphoreBuffer If pxSemaphoreBuffer is NULL then the memory
* required to hold the semaphore ' s data structures will be allocated
* dynamically , just as when a semaphore is created using
* xSemaphoreCreateBinary ( ) . If pxSemaphoreBuffer is not NULL then it must
* point to a variable of type StaticSemaphore_t , which will then be used to
* hold the semaphore ' s data structure , removing the need for the memory to be
* allocated dynamically .
*
* @ return If pxSemaphoreBuffer is not NULL then the function will not attempt
* any dynamic memory allocation , and a handle to the created semaphore will
* always be returned . If pxSemaphoreBuffer is NULL then the function will
* attempt to dynamically allocate the memory required to hold the semaphore ' s
* data structures . In this case , if the allocation succeeds then a handle to
* the created semaphore will be returned , and if the allocation fails NULL will
* be returned .
*
* Example usage :
< pre >
SemaphoreHandle_t xSemaphore = NULL ;
StaticSemaphore_t xSemaphoreBuffer ;
void vATask ( void * pvParameters )
{
// Semaphore cannot be used before a call to xSemaphoreCreateBinary().
// The semaphore's data structures will be placed in the xSemaphoreBuffer
// variable, the address of which is passed into the function. The
// function's parameter is not NULL, so the function will not attempt any
// dynamic memory allocation, and therefore the function will not return
// return NULL.
xSemaphore = xSemaphoreCreateBinary ( & xSemaphoreBuffer ) ;
// Rest of task code goes here.
}
< / pre >
* \ defgroup xSemaphoreCreateBinaryStatic xSemaphoreCreateBinaryStatic
* \ ingroup Semaphores
*/
# if( configSUPPORT_STATIC_ALLOCATION == 1 )
# define xSemaphoreCreateBinaryStatic( pxStaticQueue ) xQueueGenericCreate( ( UBaseType_t ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH, NULL, pxStaticQueue, queueQUEUE_TYPE_BINARY_SEMAPHORE )
# define xSemaphoreCreateBinaryStatic( pxStatic Semaphore ) xQueueGenericCreate( ( UBaseType_t ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH, NULL, pxStaticSemaphor e, queueQUEUE_TYPE_BINARY_SEMAPHORE )
# endif /* configSUPPORT_STATIC_ALLOCATION */
/**
@ -204,7 +278,7 @@ typedef QueueHandle_t SemaphoreHandle_t;
* ) < / pre >
*
* < i > Macro < / i > to obtain a semaphore . The semaphore must have previously been
* created with a call to v SemaphoreCreateBinary( ) , xSemaphoreCreateMutex ( ) or
* created with a call to x SemaphoreCreateBinary( ) , xSemaphoreCreateMutex ( ) or
* xSemaphoreCreateCounting ( ) .
*
* @ param xSemaphore A handle to the semaphore being taken - obtained when
@ -227,7 +301,7 @@ typedef QueueHandle_t SemaphoreHandle_t;
void vATask ( void * pvParameters )
{
// Create the semaphore to guard a shared resource.
vSemaphoreCreateBinary ( xSemaphore ) ;
xSemaphore = xSemaphoreCreateBinary ( ) ;
}
// A task that uses the semaphore.
@ -376,7 +450,7 @@ typedef QueueHandle_t SemaphoreHandle_t;
* < pre > xSemaphoreGive ( SemaphoreHandle_t xSemaphore ) < / pre >
*
* < i > Macro < / i > to release a semaphore . The semaphore must have previously been
* created with a call to v SemaphoreCreateBinary( ) , xSemaphoreCreateMutex ( ) or
* created with a call to x SemaphoreCreateBinary( ) , xSemaphoreCreateMutex ( ) or
* xSemaphoreCreateCounting ( ) . and obtained using sSemaphoreTake ( ) .
*
* This macro must not be used from an ISR . See xSemaphoreGiveFromISR ( ) for
@ -400,7 +474,7 @@ typedef QueueHandle_t SemaphoreHandle_t;
void vATask ( void * pvParameters )
{
// Create the semaphore to guard a shared resource.
vSemaphoreCreateBinary ( xSemaphore ) ;
xSemaphore = vSemaphoreCreateBinary ( ) ;
if ( xSemaphore ! = NULL )
{
@ -541,7 +615,7 @@ typedef QueueHandle_t SemaphoreHandle_t;
) < / pre >
*
* < i > Macro < / i > to release a semaphore . The semaphore must have previously been
* created with a call to v SemaphoreCreateBinary( ) or xSemaphoreCreateCounting ( ) .
* created with a call to x SemaphoreCreateBinary( ) or xSemaphoreCreateCounting ( ) .
*
* Mutex type semaphores ( those created using a call to xSemaphoreCreateMutex ( ) )
* must not be used with this macro .
@ -632,7 +706,7 @@ typedef QueueHandle_t SemaphoreHandle_t;
) < / pre >
*
* < i > Macro < / i > to take a semaphore from an ISR . The semaphore must have
* previously been created with a call to v SemaphoreCreateBinary( ) or
* previously been created with a call to x SemaphoreCreateBinary( ) or
* xSemaphoreCreateCounting ( ) .
*
* Mutex type semaphores ( those created using a call to xSemaphoreCreateMutex ( ) )
@ -661,12 +735,22 @@ typedef QueueHandle_t SemaphoreHandle_t;
* semphr . h
* < pre > SemaphoreHandle_t xSemaphoreCreateMutex ( void ) < / pre >
*
* < i > Macro < / i > that implements a mutex semaphore by using the existing queue
* mechanism .
* Creates a new mutex type semaphore instance , and returns a handle by which
* the new mutex can be referenced .
*
* Mutexes created using this macro can be accessed using the xSemaphoreTake ( )
* Internally , within the FreeRTOS implementation , mutex semaphores use a block
* of memory , in which the mutex structure is stored . If a mutex is created
* using xSemaphoreCreateMutex ( ) then the required memory is automatically
* dynamically allocated inside the xSemaphoreCreateMutex ( ) function . ( see
* http : //www.freertos.org/a00111.html). If a mutex is created using
* xSemaphoreCreateMutexStatic ( ) then the application writer can instead
* optionally provide the memory that will get used by the mutex .
* xSemaphoreCreateMutexStatic ( ) therefore allows a mutex to be created without
* using any dynamic memory allocation .
*
* Mutexes created using this function can be accessed using the xSemaphoreTake ( )
* and xSemaphoreGive ( ) macros . The xSemaphoreTakeRecursive ( ) and
* xSemaphoreGiveRecursive ( ) macros should not be used .
* xSemaphoreGiveRecursive ( ) macros must 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
@ -674,13 +758,14 @@ typedef QueueHandle_t SemaphoreHandle_t;
*
* Mutex type semaphores cannot be used from within interrupt service routines .
*
* See v SemaphoreCreateBinary( ) for an alternative implementation that can be
* See x SemaphoreCreateBinary( ) 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 .
*
* @ return xSemaphore Handle to the created mutex semaphore . Should be of type
* SemaphoreHandle_t .
* @ return If the mutex was successfully created then a handle to the created
* semaphore is returned . If there was not enough heap to allocate the mutex
* data structures then NULL is returned .
*
* Example usage :
< pre >
@ -699,13 +784,75 @@ typedef QueueHandle_t SemaphoreHandle_t;
}
}
< / pre >
* \ defgroup vSemaphoreCreateMutex v SemaphoreCreateMutex
* \ defgroup xSemaphoreCreateMutex x SemaphoreCreateMutex
* \ ingroup Semaphores
*/
# define xSemaphoreCreateMutex() xQueueCreateMutex( queueQUEUE_TYPE_MUTEX, NULL )
# if( configSUPPORT_STATIC_ALLOCATION == 1 )
# define xSemaphoreCreateMutexStatic( pxStaticQueue ) xQueueCreateMutex( queueQUEUE_TYPE_MUTEX, ( pxStaticQueue ) )
/**
* semphr . h
* < pre > SemaphoreHandle_t xSemaphoreCreateMutexStatic ( StaticSemaphore_t * pxMutexBuffer ) < / pre >
*
* Creates a new mutex type semaphore instance , and returns a handle by which
* the new mutex can be referenced .
*
* Internally , within the FreeRTOS implementation , mutex semaphores use a block
* of memory , in which the mutex structure is stored . If a mutex is created
* using xSemaphoreCreateMutex ( ) then the required memory is automatically
* dynamically allocated inside the xSemaphoreCreateMutex ( ) function . ( see
* http : //www.freertos.org/a00111.html). If a mutex is created using
* xSemaphoreCreateMutexStatic ( ) then the application writer can instead
* optionally provide the memory that will get used by the mutex .
* xSemaphoreCreateMutexStatic ( ) therefore allows a mutex to be created without
* using any dynamic memory allocation .
*
* Mutexes created using this function can be accessed using the xSemaphoreTake ( )
* and xSemaphoreGive ( ) macros . The xSemaphoreTakeRecursive ( ) and
* xSemaphoreGiveRecursive ( ) macros must 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 xSemaphoreCreateBinary ( ) 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 .
*
* @ param pxMutexBuffer If pxMutexBuffer is NULL then the memory required to
* hold the mutex ' s data structures will be allocated dynamically , just as when
* a mutex is created using xSemaphoreCreateMutex ( ) . If pxMutexBuffer is not
* NULL then it must point to a variable of type StaticSemaphore_t , which will
* then be used to hold the mutex ' s data structure , removing the need for
* the memory to be allocated dynamically .
*
* @ return If the mutex was successfully created then a handle to the created
* mutex is returned . If pxMutexBuffer was NULL , and there was not enough
* heap to allocate the mutex data structures , then NULL is returned .
*
* Example usage :
< pre >
SemaphoreHandle_t xSemaphore ;
StaticSemaphore_t xMutexBuffer ;
void vATask ( void * pvParameters )
{
// A mutex cannot be used before it has been created. xMutexBuffer is
// into xSemaphoreCreateMutexStatic() so no dynamic memory allocation is
// attempted.
xSemaphore = xSemaphoreCreateMutexStatic ( & xMutexBuffer ) ;
// As no dynamic memory allocation was performed, xSemaphore cannot be NULL,
// so there is no need to check it.
}
< / pre >
* \ defgroup xSemaphoreCreateMutexStatic xSemaphoreCreateMutexStatic
* \ ingroup Semaphores
*/
# if( configSUPPORT_STATIC_ALLOCATION == 1 )
# define xSemaphoreCreateMutexStatic( pxMutexBuffer ) xQueueCreateMutex( queueQUEUE_TYPE_MUTEX, ( pxMutexBuffer ) )
# endif /* configSUPPORT_STATIC_ALLOCATION */
@ -713,12 +860,23 @@ typedef QueueHandle_t SemaphoreHandle_t;
* semphr . h
* < pre > SemaphoreHandle_t xSemaphoreCreateRecursiveMutex ( void ) < / pre >
*
* < i > Macro < / i > that implements a recursive mutex by using the existing queue
* mechanism .
* Creates a new recursive mutex type semaphore instance , and returns a handle
* by which the new recursive mutex can be referenced .
*
* Internally , within the FreeRTOS implementation , recursive mutexs use a block
* of memory , in which the mutex structure is stored . If a recursive mutex is
* created using xSemaphoreCreateRecursiveMutex ( ) then the required memory is
* automatically dynamically allocated inside the
* xSemaphoreCreateRecursiveMutex ( ) function . ( see
* http : //www.freertos.org/a00111.html). If a recursive mutex is created using
* xSemaphoreCreateRecursiveMutexStatic ( ) then the application writer can
* instead optionally provide the memory that will get used by the mutex .
* xSemaphoreCreateRecursiveMutexStatic ( ) therefore allows a recursive mutex to
* be created without using any dynamic memory allocation .
*
* Mutexes created using this macro can be accessed using the
* xSemaphoreTakeRecursive ( ) and xSemaphoreGiveRecursive ( ) macros . The
* xSemaphoreTake ( ) and xSemaphoreGive ( ) macros should not be used .
* xSemaphoreTake ( ) and xSemaphoreGive ( ) macros must 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
@ -733,13 +891,13 @@ typedef QueueHandle_t SemaphoreHandle_t;
*
* Mutex type semaphores cannot be used from within interrupt service routines .
*
* See v SemaphoreCreateBinary( ) for an alternative implementation that can be
* See x SemaphoreCreateBinary( ) 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 .
*
* @ return xSemaphore Handle to the created mutex semaphore . Should be of type
* SemaphoreHandle_t .
* SemaphoreHandle_t .
*
* Example usage :
< pre >
@ -758,11 +916,85 @@ typedef QueueHandle_t SemaphoreHandle_t;
}
}
< / pre >
* \ defgroup vSemaphoreCreateMutex vSemaphoreCreat eMutex
* \ defgroup xSemaphoreCreateRecursiveMutex xSemaphoreCreateRecursiv eMutex
* \ ingroup Semaphores
*/
# define xSemaphoreCreateRecursiveMutex() xQueueCreateMutex( queueQUEUE_TYPE_RECURSIVE_MUTEX, NULL )
/**
* semphr . h
* < pre > SemaphoreHandle_t xSemaphoreCreateRecursiveMutexStatic ( StaticSemaphore_t * pxMutexBuffer ) < / pre >
*
* Creates a new recursive mutex type semaphore instance , and returns a handle
* by which the new recursive mutex can be referenced .
*
* Internally , within the FreeRTOS implementation , recursive mutexs use a block
* of memory , in which the mutex structure is stored . If a recursive mutex is
* created using xSemaphoreCreateRecursiveMutex ( ) then the required memory is
* automatically dynamically allocated inside the
* xSemaphoreCreateRecursiveMutex ( ) function . ( see
* http : //www.freertos.org/a00111.html). If a recursive mutex is created using
* xSemaphoreCreateRecursiveMutexStatic ( ) then the application writer can
* instead optionally provide the memory that will get used by the mutex .
* xSemaphoreCreateRecursiveMutexStatic ( ) therefore allows a recursive mutex to
* be created without using any dynamic memory allocation .
*
* Mutexes created using this macro can be accessed using the
* xSemaphoreTakeRecursive ( ) and xSemaphoreGiveRecursive ( ) macros . The
* xSemaphoreTake ( ) and xSemaphoreGive ( ) macros must 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 xSemaphoreCreateBinary ( ) 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 .
*
* @ param pxMutexBuffer If pxMutexBuffer is NULL then the memory required to
* hold the recursive mutex ' s data structures will be allocated dynamically ,
* just as when a recursive mutex is created using
* xSemaphoreCreateRecursiveMutex ( ) . If pxMutexBuffer is not NULL then it must
* point to a variable of type StaticSemaphore_t , which will then be used to
* hold the recursive mutex ' s data structure , removing the need for the memory
* to be allocated dynamically .
*
* @ return If the recursive mutex was successfully created then a handle to the
* created recursive mutex is returned . If pxMutexBuffer was NULL , and there
* was not enough heap to allocate the mutex data structures , then NULL is
* returned .
*
* Example usage :
< pre >
SemaphoreHandle_t xSemaphore ;
StaticSemaphore_t xMutexBuffer ;
void vATask ( void * pvParameters )
{
// A recursive semaphore cannot be used before it is created. Here a
// recursive mutex is created using xSemaphoreCreateRecursiveMutexStatic().
// The address of xMutexBuffer is passed into the function, and will hold
// the mutexes data structures - so no dynamic memory allocation will be
// attempted.
xSemaphore = xSemaphoreCreateRecursiveMutexStatic ( & xMutexBuffer ) ;
// As no dynamic memory allocation was performed, xSemaphore cannot be NULL,
// so there is no need to check it.
}
< / pre >
* \ defgroup xSemaphoreCreateRecursiveMutexStatic xSemaphoreCreateRecursiveMutexStatic
* \ ingroup Semaphores
*/
# if( configSUPPORT_STATIC_ALLOCATION == 1 )
# define xSemaphoreCreateRecursiveMutexStatic( pxStaticSemaphore ) xQueueCreateMutex( queueQUEUE_TYPE_RECURSIVE_MUTEX, pxStaticSemaphore )
# endif /* configSUPPORT_STATIC_ALLOCATION */
@ -771,8 +1003,19 @@ typedef QueueHandle_t SemaphoreHandle_t;
* semphr . h
* < pre > SemaphoreHandle_t xSemaphoreCreateCounting ( UBaseType_t uxMaxCount , UBaseType_t uxInitialCount ) < / pre >
*
* < i > Macro < / i > that creates a counting semaphore by using the existing
* queue mechanism .
* Creates a new counting semaphore instance , and returns a handle by which the
* new counting semaphore can be referenced .
*
* Internally , within the FreeRTOS implementation , counting semaphores use a
* block of memory , in which the counting semaphore structure is stored . If a
* counting semaphore is created using xSemaphoreCreateCounting ( ) then the
* required memory is automatically dynamically allocated inside the
* xSemaphoreCreateCounting ( ) function . ( see
* http : //www.freertos.org/a00111.html). If a counting semaphore is created
* using xSemaphoreCreateCountingStatic ( ) then the application writer can
* instead optionally provide the memory that will get used by the counting
* semaphore . xSemaphoreCreateCountingStatic ( ) therefore allows a counting
* semaphore to be created without using any dynamic memory allocation .
*
* Counting semaphores are typically used for two things :
*
@ -830,8 +1073,91 @@ typedef QueueHandle_t SemaphoreHandle_t;
*/
# define xSemaphoreCreateCounting( uxMaxCount, uxInitialCount ) xQueueCreateCountingSemaphore( ( uxMaxCount ), ( uxInitialCount ), ( NULL ) )
/**
* semphr . h
* < pre > SemaphoreHandle_t xSemaphoreCreateCountingStatic ( UBaseType_t uxMaxCount , UBaseType_t uxInitialCount , StaticSemaphore_t * pxSemaphoreBuffer ) < / pre >
*
* Creates a new counting semaphore instance , and returns a handle by which the
* new counting semaphore can be referenced .
*
* Internally , within the FreeRTOS implementation , counting semaphores use a
* block of memory , in which the counting semaphore structure is stored . If a
* counting semaphore is created using xSemaphoreCreateCounting ( ) then the
* required memory is automatically dynamically allocated inside the
* xSemaphoreCreateCounting ( ) function . ( see
* http : //www.freertos.org/a00111.html). If a counting semaphore is created
* using xSemaphoreCreateCountingStatic ( ) then the application writer can
* instead optionally provide the memory that will get used by the counting
* semaphore . xSemaphoreCreateCountingStatic ( ) therefore allows a counting
* semaphore to be created without using any dynamic memory allocation .
*
* Counting semaphores are typically used for two things :
*
* 1 ) Counting events .
*
* In this usage scenario an event handler will ' give ' a semaphore each time
* an event occurs ( incrementing the semaphore count value ) , and a handler
* task will ' take ' a semaphore each time it processes an event
* ( decrementing the semaphore count value ) . The count value is therefore
* the difference between the number of events that have occurred and the
* number that have been processed . In this case it is desirable for the
* initial count value to be zero .
*
* 2 ) Resource management .
*
* In this usage scenario the count value indicates the number of resources
* available . To obtain control of a resource a task must first obtain a
* semaphore - decrementing the semaphore count value . When the count value
* reaches zero there are no free resources . When a task finishes with the
* resource it ' gives ' the semaphore back - incrementing the semaphore count
* value . In this case it is desirable for the initial count value to be
* equal to the maximum count value , indicating that all resources are free .
*
* @ param uxMaxCount The maximum count value that can be reached . When the
* semaphore reaches this value it can no longer be ' given ' .
*
* @ param uxInitialCount The count value assigned to the semaphore when it is
* created .
*
* @ param pxSemaphoreBuffer If pxSemaphoreBuffer is NULL then the memory
* required to hold the semaphore ' s data structures will be allocated
* dynamically , just as when a counting semaphore is created using
* xSemaphoreCreateCounting ( ) . If pxSemaphoreBuffer is not NULL then it must
* point to a variable of type StaticSemaphore_t , which will then be used to
* hold the semaphore ' s data structure , removing the need for the memory
* to be allocated dynamically .
*
* @ return If the counting semaphore was successfully created then a handle to
* the created counting semaphore is returned . If pxSemaphoreBuffer was NULL ,
* and there was not enough heap to allocate the counting semaphore data
* structures , then NULL is returned .
*
* Example usage :
< pre >
SemaphoreHandle_t xSemaphore ;
StaticSemaphore_t xSemaphoreBuffer ;
void vATask ( void * pvParameters )
{
SemaphoreHandle_t xSemaphore = NULL ;
// Counting semaphore cannot be used before they have been created. Create
// a counting semaphore using xSemaphoreCreateCountingStatic(). The max
// value to which the semaphore can count is 10, and the initial value
// assigned to the count will be 0. The address of xSemaphoreBuffer is
// passed in and will be used to hold the semaphore structure, so no dynamic
// memory allocation will be used.
xSemaphore = xSemaphoreCreateCounting ( 10 , 0 , & xSemaphoreBuffer ) ;
// No memory allocation was attempted so xSemaphore cannot be NULL, so there
// is no need to check its value.
}
< / pre >
* \ defgroup xSemaphoreCreateCountingStatic xSemaphoreCreateCountingStatic
* \ ingroup Semaphores
*/
# if( configSUPPORT_STATIC_ALLOCATION == 1 )
# define xSemaphoreCreateCountingStatic( uxMaxCount, uxInitialCount, pxStaticSemaphore ) xQueueCreateCountingSemaphore( ( uxMaxCount ), ( uxInitialCount ), ( pxStaticSemaphore ) )
# define xSemaphoreCreateCountingStatic( uxMaxCount, uxInitialCount, pxS emaphoreBuffer ) xQueueCreateCountingSemaphore( ( uxMaxCount ), ( uxInitialCount ), ( pxSemaphoreBuffer ) )
# endif /* configSUPPORT_STATIC_ALLOCATION */
/**
Richard Barry
9 years ago