len0rd/FreeRTOS-Kernel
1
0
Fork 0
mirror of https://github.com/FreeRTOS/FreeRTOS-Kernel.git synced 2025-08-18 09:08:33 -04:00
Code Issues Projects Releases Packages Wiki Activity

Add vTaskGetTaskInfo() function that allows a TaskStatus_t structure to be returned for an individual task (previously information could only be obtained for all the tasks at once).

Browse source 
Add a member to the TaskStatus_t structure that is used to return the base address of the stack used by the task being queried.
Add xTaskGetTaskHandle() that allows the handle of a task to be looked up from the task's text name.
Continue to document the macros that allow RTOS objects to be created using statically allocated memory.
Introduced vApplicationDaemonTaskStartupHook(), which allows initialisation that that needs to be executed after the scheduler has been started to be executed from the RTOS daemon task.
Call prvResetNextTaskUnblockTime() in xTaskResumeAll() if a task is moved from the pending ready list - this can prevent an unnecessary wake from sleep mode if a task is unblocked by an interrupt while in a low power tickless state.
This commit is contained in:
Richard Barry 2016-01-28 16:59:57 +00:00
parent b514f4fa4e
commit 802af0150c
11 changed files with 838 additions and 147 deletions
Download patch file Download diff file Expand all files Collapse all files

394
FreeRTOS/Source/include/semphr.h
View file

@ -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 vSemaphoreCreateBinary
* \defgroup xSemaphoreCreateBinary xSemaphoreCreateBinary
* \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( pxStaticSemaphore ) xQueueGenericCreate( ( UBaseType_t ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH, NULL, pxStaticSemaphore, 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 vSemaphoreCreateBinary(), xSemaphoreCreateMutex() or
* created with a call to xSemaphoreCreateBinary(), 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 vSemaphoreCreateBinary(), xSemaphoreCreateMutex() or
* created with a call to xSemaphoreCreateBinary(), 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 vSemaphoreCreateBinary() or xSemaphoreCreateCounting().
* created with a call to xSemaphoreCreateBinary() 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 vSemaphoreCreateBinary() or
* previously been created with a call to xSemaphoreCreateBinary() 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 vSemaphoreCreateBinary() for an alternative implementation that can be
* 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.
*
* @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 vSemaphoreCreateMutex
* \defgroup xSemaphoreCreateMutex xSemaphoreCreateMutex
* \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 vSemaphoreCreateBinary() for an alternative implementation that can be
* 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.
*
* @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 vSemaphoreCreateMutex
* \defgroup xSemaphoreCreateRecursiveMutex xSemaphoreCreateRecursiveMutex
* \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, pxSemaphoreBuffer ) xQueueCreateCountingSemaphore( ( uxMaxCount ), ( uxInitialCount ), ( pxSemaphoreBuffer ) )
#endif /* configSUPPORT_STATIC_ALLOCATION */
/**