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

Rename configNUMBER_OF_TASK_NOTIFICATIONS to configTASK_NOTIFICATION_ARRAY_ENTRIES.

Browse source 
Update the function documentation for all task notification functions in include/task.h.
This commit is contained in:
RichardBarry 2020-05-26 12:16:25 -07:00
parent ae4c1a1dea
commit f50ecce925
3 changed files with 431 additions and 158 deletions
Download patch file Download diff file Expand all files Collapse all files

12
include/FreeRTOS.h
View file

@ -834,12 +834,12 @@ hold explicit before calling the code. */
#define configUSE_TASK_NOTIFICATIONS 1 #define configUSE_TASK_NOTIFICATIONS 1
#endif #endif
#ifndef configNUMBER_OF_TASK_NOTIFICATIONS #ifndef configTASK_NOTIFICATION_ARRAY_ENTRIES
#define configNUMBER_OF_TASK_NOTIFICATIONS 1 #define configTASK_NOTIFICATION_ARRAY_ENTRIES 1
#endif #endif
#if configNUMBER_OF_TASK_NOTIFICATIONS < 1 #if configTASK_NOTIFICATION_ARRAY_ENTRIES < 1
#error configNUMBER_OF_TASK_NOTIFICATIONS must be at least 1 #error configTASK_NOTIFICATION_ARRAY_ENTRIES must be at least 1
#endif #endif
#ifndef configUSE_POSIX_ERRNO #ifndef configUSE_POSIX_ERRNO
@ -1152,8 +1152,8 @@ typedef struct xSTATIC_TCB
struct _reent xDummy17; struct _reent xDummy17;
#endif #endif
#if ( configUSE_TASK_NOTIFICATIONS == 1 ) #if ( configUSE_TASK_NOTIFICATIONS == 1 )
uint32_t ulDummy18[ configNUMBER_OF_TASK_NOTIFICATIONS ]; uint32_t ulDummy18[ configTASK_NOTIFICATION_ARRAY_ENTRIES ];
uint8_t ucDummy19[ configNUMBER_OF_TASK_NOTIFICATIONS ]; uint8_t ucDummy19[ configTASK_NOTIFICATION_ARRAY_ENTRIES ];
#endif #endif
#if ( tskSTATIC_AND_DYNAMIC_ALLOCATION_POSSIBLE != 0 ) #if ( tskSTATIC_AND_DYNAMIC_ALLOCATION_POSSIBLE != 0 )
uint8_t uxDummy20; uint8_t uxDummy20;

557
include/task.h
View file

@ -58,7 +58,7 @@ extern "C" {
/* The direct to task notification feature used to have only a single notification /* The direct to task notification feature used to have only a single notification
per task. Now there is an array of notifications per task that is dimensioned by per task. Now there is an array of notifications per task that is dimensioned by
configNUMBER_OF_TASK_NOTIFICATIONS. For backward compatibility, any use of the configTASK_NOTIFICATION_ARRAY_ENTRIES. For backward compatibility, any use of the
original direct to task notification defaults to using the first index in the original direct to task notification defaults to using the first index in the
array. */ array. */
#define tskDEFAULT_INDEX_TO_NOTIFY ( 0 ) #define tskDEFAULT_INDEX_TO_NOTIFY ( 0 )
@ -1780,13 +1780,22 @@ uint32_t ulTaskGetIdleRunTimeCounter( void ) PRIVILEGED_FUNCTION;
/** /**
* task. h * task. h
* <PRE>BaseType_t xTaskNotifyIndexed( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction );</PRE>
* <PRE>BaseType_t xTaskNotify( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction );</PRE> * <PRE>BaseType_t xTaskNotify( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction );</PRE>
* *
* configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this * See http://www.FreeRTOS.org/RTOS-task-notifications.html for details.
* function to be available.
* *
* When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these
* "notification value", which is a 32-bit unsigned integer (uint32_t). * functions to be available.
*
* Sends a direct to task notification to a task, with an optional value and
* action.
*
* Each task has a private array of "notification values" (or 'notifications'),
* each of which is a 32-bit unsigned integer (uint32_t). The constant
* configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
* array, and (for backward compatibility) defaults to 1 if left undefined.
* Prior to FreeRTOS V10.4.0 there was only one notification value per task.
* *
* Events can be sent to a task using an intermediary object. Examples of such * Events can be sent to a task using an intermediary object. Examples of such
* objects are queues, semaphores, mutexes and event groups. Task notifications * objects are queues, semaphores, mutexes and event groups. Task notifications
@ -1794,28 +1803,46 @@ uint32_t ulTaskGetIdleRunTimeCounter( void ) PRIVILEGED_FUNCTION;
* an intermediary object. * an intermediary object.
* *
* A notification sent to a task can optionally perform an action, such as * A notification sent to a task can optionally perform an action, such as
* update, overwrite or increment the task's notification value. In that way * update, overwrite or increment one of the task's notification values. In
* task notifications can be used to send data to a task, or be used as light * that way task notifications can be used to send data to a task, or be used as
* weight and fast binary or counting semaphores. * light weight and fast binary or counting semaphores.
* *
* A notification sent to a task will remain pending until it is cleared by the * A task can use xTaskNotifyWaitIndexed() to [optionally] block to wait for a
* task calling xTaskNotifyWait() or ulTaskNotifyTake(). If the task was * notification to be pending, or ulTaskNotifyTakeIndexed() to [optionally] block
* already in the Blocked state to wait for a notification when the notification * to wait for a notification value to have a non-zero value. The task does
* arrives then the task will automatically be removed from the Blocked state
* (unblocked) and the notification cleared.
*
* A task can use xTaskNotifyWait() to [optionally] block to wait for a
* notification to be pending, or ulTaskNotifyTake() to [optionally] block
* to wait for its notification value to have a non-zero value. The task does
* not consume any CPU time while it is in the Blocked state. * not consume any CPU time while it is in the Blocked state.
* *
* See http://www.FreeRTOS.org/RTOS-task-notifications.html for details. * A notification sent to a task will remain pending until it is cleared by the
* task calling xTaskNotifyWaitIndexed() or ulTaskNotifyTakeIndexed() (or their
* un-indexed equivalents). If the task was already in the Blocked state to
* wait for a notification when the notification arrives then the task will
* automatically be removed from the Blocked state (unblocked) and the
* notification cleared.
*
* **NOTE** Each notification within the array operates independently - a task
* can only block on one notification within the array at a time and will not be
* unblocked by a notification sent to any other array index.
*
* Backward compatibility information:
* Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
* all task notification API functions operated on that value. Replacing the
* single notification value with an array of notification values necessitated a
* new set of API functions that could address specific notifications within the
* array. xTaskNotify() is the original API function, and remains backward
* compatible by always operating on the notification value at index 0 in the
* array. Calling xTaskNotify() is equivalent to calling xTaskNotifyIndexed()
* with the uxIndexToNotify parameter set to 0.
* *
* @param xTaskToNotify The handle of the task being notified. The handle to a * @param xTaskToNotify The handle of the task being notified. The handle to a
* task can be returned from the xTaskCreate() API function used to create the * task can be returned from the xTaskCreate() API function used to create the
* task, and the handle of the currently running task can be obtained by calling * task, and the handle of the currently running task can be obtained by calling
* xTaskGetCurrentTaskHandle(). * xTaskGetCurrentTaskHandle().
* *
* @param uxIndexToNotify The index within the target task's array of
* notification values to which the notification is to be sent. uxIndexToNotify
* must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotify() does
* not have this parameter and always sends notifications to index 0.
*
* @param ulValue Data that can be sent with the notification. How the data is * @param ulValue Data that can be sent with the notification. How the data is
* used depends on the value of the eAction parameter. * used depends on the value of the eAction parameter.
* *
@ -1823,58 +1850,88 @@ uint32_t ulTaskGetIdleRunTimeCounter( void ) PRIVILEGED_FUNCTION;
* value, if at all. Valid values for eAction are as follows: * value, if at all. Valid values for eAction are as follows:
* *
* eSetBits - * eSetBits -
* The task's notification value is bitwise ORed with ulValue. xTaskNofify() * The target notification value is bitwise ORed with ulValue.
* always returns pdPASS in this case. * xTaskNofifyIndexed() always returns pdPASS in this case.
* *
* eIncrement - * eIncrement -
* The task's notification value is incremented. ulValue is not used and * The target notification value is incremented. ulValue is not used and
* xTaskNotify() always returns pdPASS in this case. * xTaskNotifyIndexed() always returns pdPASS in this case.
* *
* eSetValueWithOverwrite - * eSetValueWithOverwrite -
* The task's notification value is set to the value of ulValue, even if the * The target notification value is set to the value of ulValue, even if the
* task being notified had not yet processed the previous notification (the * task being notified had not yet processed the previous notification at the
* task already had a notification pending). xTaskNotify() always returns * same array index (the task already had a notification pending at that index).
* pdPASS in this case. * xTaskNotifyIndexed() always returns pdPASS in this case.
* *
* eSetValueWithoutOverwrite - * eSetValueWithoutOverwrite -
* If the task being notified did not already have a notification pending then * If the task being notified did not already have a notification pending at the
* the task's notification value is set to ulValue and xTaskNotify() will * same array index then the target notification value is set to ulValue and
* return pdPASS. If the task being notified already had a notification * xTaskNotifyIndexed() will return pdPASS. If the task being notified already
* pending then no action is performed and pdFAIL is returned. * had a notification pending at the same array index then no action is
* performed and pdFAIL is returned.
* *
* eNoAction - * eNoAction -
* The task receives a notification without its notification value being * The task receives a notification at the specified array index without the
* updated. ulValue is not used and xTaskNotify() always returns pdPASS in * notification value at that index being updated. ulValue is not used and
* this case. * xTaskNotifyIndexed() always returns pdPASS in this case.
* *
* pulPreviousNotificationValue - * pulPreviousNotificationValue -
* Can be used to pass out the subject task's notification value before any * Can be used to pass out the subject task's notification value before any
* bits are modified by the notify function. * bits are modified by the notify function.
* *
* @return Dependent on the value of eAction. See the description of the * @return Dependent on the value of eAction. See the description of the
* eAction parameter. * eAction parameter.
* *
* \defgroup xTaskNotify xTaskNotify * \defgroup xTaskNotifyIndexed xTaskNotifyIndexed
* \ingroup TaskNotifications * \ingroup TaskNotifications
*/ */
BaseType_t xTaskGenericNotify( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue ) PRIVILEGED_FUNCTION; BaseType_t xTaskGenericNotify( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue ) PRIVILEGED_FUNCTION;
#define xTaskNotify( xTaskToNotify, ulValue, eAction ) xTaskGenericNotify( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), NULL ) #define xTaskNotify( xTaskToNotify, ulValue, eAction ) xTaskGenericNotify( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), NULL )
#define xTaskNotifyIndexed( xTaskToNotify, uxIndexToNotify, ulValue, eAction ) xTaskGenericNotify( ( xTaskToNotify ), ( uxIndexToNotify ), ( ulValue ), ( eAction ), NULL ) #define xTaskNotifyIndexed( xTaskToNotify, uxIndexToNotify, ulValue, eAction ) xTaskGenericNotify( ( xTaskToNotify ), ( uxIndexToNotify ), ( ulValue ), ( eAction ), NULL )
/**
* task. h
* <PRE>BaseType_t xTaskNotifyAndQueryIndexed( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotifyValue );</PRE>
* <PRE>BaseType_t xTaskNotifyAndQuery( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotifyValue );</PRE>
*
* See http://www.FreeRTOS.org/RTOS-task-notifications.html for details.
*
* xTaskNotifyAndQueryIndexed() performs the same operation as
* xTaskNotifyIndexed() with the addition that it also returns the subject
* task's prior notification value (the notification value at the time the
* function is called rather than when the function returns) in the additional
* pulPreviousNotifyValue parameter.
*
* xTaskNotifyAndQuery() performs the same operation as xTaskNotify() with the
* addition that it also returns the subject task's prior notification value
* (the notification value as it was at the time the function is called, rather
* than when the function returns) in the additional pulPreviousNotifyValue
* parameter.
*
* \defgroup xTaskNotifyAndQueryIndexed xTaskNotifyAndQueryIndexed
* \ingroup TaskNotifications
*/
#define xTaskNotifyAndQuery( xTaskToNotify, ulValue, eAction, pulPreviousNotifyValue ) xTaskGenericNotify( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), ( pulPreviousNotifyValue ) ) #define xTaskNotifyAndQuery( xTaskToNotify, ulValue, eAction, pulPreviousNotifyValue ) xTaskGenericNotify( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), ( pulPreviousNotifyValue ) )
#define xTaskNotifyAndQueryIndexed( xTaskToNotify, uxIndexToNotify, ulValue, eAction, pulPreviousNotifyValue ) xTaskGenericNotify( ( xTaskToNotify ), ( uxIndexToNotify ), ( ulValue ), ( eAction ), ( pulPreviousNotifyValue ) ) #define xTaskNotifyAndQueryIndexed( xTaskToNotify, uxIndexToNotify, ulValue, eAction, pulPreviousNotifyValue ) xTaskGenericNotify( ( xTaskToNotify ), ( uxIndexToNotify ), ( ulValue ), ( eAction ), ( pulPreviousNotifyValue ) )
/** /**
* task. h * task. h
* <PRE>BaseType_t xTaskNotifyIndexedFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, BaseType_t *pxHigherPriorityTaskWoken );</PRE>
* <PRE>BaseType_t xTaskNotifyFromISR( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, BaseType_t *pxHigherPriorityTaskWoken );</PRE> * <PRE>BaseType_t xTaskNotifyFromISR( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, BaseType_t *pxHigherPriorityTaskWoken );</PRE>
* *
* configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this * See http://www.FreeRTOS.org/RTOS-task-notifications.html for details.
* function to be available.
* *
* When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these
* "notification value", which is a 32-bit unsigned integer (uint32_t). * functions to be available.
* *
* A version of xTaskNotify() that can be used from an interrupt service routine * A version of xTaskNotifyIndexed() that can be used from an interrupt service
* (ISR). * routine (ISR).
*
* Each task has a private array of "notification values" (or 'notifications'),
* each of which is a 32-bit unsigned integer (uint32_t). The constant
* configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
* array, and (for backward compatibility) defaults to 1 if left undefined.
* Prior to FreeRTOS V10.4.0 there was only one notification value per task.
* *
* Events can be sent to a task using an intermediary object. Examples of such * Events can be sent to a task using an intermediary object. Examples of such
* objects are queues, semaphores, mutexes and event groups. Task notifications * objects are queues, semaphores, mutexes and event groups. Task notifications
@ -1882,22 +1939,40 @@ BaseType_t xTaskGenericNotify( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexTo
* an intermediary object. * an intermediary object.
* *
* A notification sent to a task can optionally perform an action, such as * A notification sent to a task can optionally perform an action, such as
* update, overwrite or increment the task's notification value. In that way * update, overwrite or increment one of the task's notification values. In
* task notifications can be used to send data to a task, or be used as light * that way task notifications can be used to send data to a task, or be used as
* weight and fast binary or counting semaphores. * light weight and fast binary or counting semaphores.
* *
* A notification sent to a task will remain pending until it is cleared by the * A task can use xTaskNotifyWaitIndexed() to [optionally] block to wait for a
* task calling xTaskNotifyWait() or ulTaskNotifyTake(). If the task was * notification to be pending, or ulTaskNotifyTakeIndexed() to [optionally] block
* already in the Blocked state to wait for a notification when the notification * to wait for a notification value to have a non-zero value. The task does
* arrives then the task will automatically be removed from the Blocked state
* (unblocked) and the notification cleared.
*
* A task can use xTaskNotifyWait() to [optionally] block to wait for a
* notification to be pending, or ulTaskNotifyTake() to [optionally] block
* to wait for its notification value to have a non-zero value. The task does
* not consume any CPU time while it is in the Blocked state. * not consume any CPU time while it is in the Blocked state.
* *
* See http://www.FreeRTOS.org/RTOS-task-notifications.html for details. * A notification sent to a task will remain pending until it is cleared by the
* task calling xTaskNotifyWaitIndexed() or ulTaskNotifyTakeIndexed() (or their
* un-indexed equivalents). If the task was already in the Blocked state to
* wait for a notification when the notification arrives then the task will
* automatically be removed from the Blocked state (unblocked) and the
* notification cleared.
*
* **NOTE** Each notification within the array operates independently - a task
* can only block on one notification within the array at a time and will not be
* unblocked by a notification sent to any other array index.
*
* Backward compatibility information:
* Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
* all task notification API functions operated on that value. Replacing the
* single notification value with an array of notification values necessitated a
* new set of API functions that could address specific notifications within the
* array. xTaskNotifyFromISR() is the original API function, and remains
* backward compatible by always operating on the notification value at index 0
* within the array. Calling xTaskNotifyFromISR() is equivalent to calling
* xTaskNotifyIndexedFromISR() with the uxIndexToNotify parameter set to 0.
*
* @param uxIndexToNotify The index within the target task's array of
* notification values to which the notification is to be sent. uxIndexToNotify
* must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyFromISR()
* does not have this parameter and always sends notifications to index 0.
* *
* @param xTaskToNotify The handle of the task being notified. The handle to a * @param xTaskToNotify The handle of the task being notified. The handle to a
* task can be returned from the xTaskCreate() API function used to create the * task can be returned from the xTaskCreate() API function used to create the
@ -1947,24 +2022,56 @@ BaseType_t xTaskGenericNotify( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexTo
* @return Dependent on the value of eAction. See the description of the * @return Dependent on the value of eAction. See the description of the
* eAction parameter. * eAction parameter.
* *
* \defgroup xTaskNotifyFromISR xTaskNotifyFromISR * \defgroup xTaskNotifyIndexedFromISR xTaskNotifyIndexedFromISR
* \ingroup TaskNotifications * \ingroup TaskNotifications
*/ */
BaseType_t xTaskGenericNotifyFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue, BaseType_t *pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION; BaseType_t xTaskGenericNotifyFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue, BaseType_t *pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
#define xTaskNotifyFromISR( xTaskToNotify, ulValue, eAction, pxHigherPriorityTaskWoken ) xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), NULL, ( pxHigherPriorityTaskWoken ) ) #define xTaskNotifyFromISR( xTaskToNotify, ulValue, eAction, pxHigherPriorityTaskWoken ) xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), NULL, ( pxHigherPriorityTaskWoken ) )
#define xTaskNotifyAndQueryFromISR( xTaskToNotify, ulValue, eAction, pulPreviousNotificationValue, pxHigherPriorityTaskWoken ) xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), ( pulPreviousNotificationValue ), ( pxHigherPriorityTaskWoken ) )
#define xTaskNotifyIndexedFromISR( xTaskToNotify, uxIndexToNotify, ulValue, eAction, pxHigherPriorityTaskWoken ) xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( uxIndexToNotify ), ( ulValue ), ( eAction ), NULL, ( pxHigherPriorityTaskWoken ) ) #define xTaskNotifyIndexedFromISR( xTaskToNotify, uxIndexToNotify, ulValue, eAction, pxHigherPriorityTaskWoken ) xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( uxIndexToNotify ), ( ulValue ), ( eAction ), NULL, ( pxHigherPriorityTaskWoken ) )
#define xTaskNotifyAndQueryIndexedFromISR( xTaskToNotify, uxIndexToNotify, ulValue, eAction, pulPreviousNotificationValue, pxHigherPriorityTaskWoken ) xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( uxIndexToNotify ), ( ulValue ), ( eAction ), ( pulPreviousNotificationValue ), ( pxHigherPriorityTaskWoken ) )
/** /**
* task. h * task. h
* <PRE>BaseType_t xTaskNotifyAndQueryIndexedFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue, BaseType_t *pxHigherPriorityTaskWoken );</PRE>
* <PRE>BaseType_t xTaskNotifyAndQueryFromISR( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue, BaseType_t *pxHigherPriorityTaskWoken );</PRE>
*
* See http://www.FreeRTOS.org/RTOS-task-notifications.html for details.
*
* xTaskNotifyAndQueryIndexedFromISR() performs the same operation as
* xTaskNotifyIndexedFromISR() with the addition that it also returns the
* subject task's prior notification value (the notification value at the time
* the function is called rather than at the time the function returns) in the
* additional pulPreviousNotifyValue parameter.
*
* xTaskNotifyAndQueryFromISR() performs the same operation as
* xTaskNotifyFromISR() with the addition that it also returns the subject
* task's prior notification value (the notification value at the time the
* function is called rather than at the time the function returns) in the
* additional pulPreviousNotifyValue parameter.
*
* \defgroup xTaskNotifyAndQueryIndexedFromISR xTaskNotifyAndQueryIndexedFromISR
* \ingroup TaskNotifications
*/
#define xTaskNotifyAndQueryIndexedFromISR( xTaskToNotify, uxIndexToNotify, ulValue, eAction, pulPreviousNotificationValue, pxHigherPriorityTaskWoken ) xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( uxIndexToNotify ), ( ulValue ), ( eAction ), ( pulPreviousNotificationValue ), ( pxHigherPriorityTaskWoken ) )
#define xTaskNotifyAndQueryFromISR( xTaskToNotify, ulValue, eAction, pulPreviousNotificationValue, pxHigherPriorityTaskWoken ) xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), ( pulPreviousNotificationValue ), ( pxHigherPriorityTaskWoken ) )
/**
* task. h
* <PRE>BaseType_t xTaskNotifyWaitIndexed( UBaseType_t uxIndexToWaitOn, uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait );</pre>
* <PRE>BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait );</pre> * <PRE>BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait );</pre>
* *
* Waits for a direct to task notification to be pending at a given index within
* an array of direct to task notifications.
*
* See http://www.FreeRTOS.org/RTOS-task-notifications.html for details.
*
* configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this
* function to be available. * function to be available.
* *
* When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private * Each task has a private array of "notification values" (or 'notifications'),
* "notification value", which is a 32-bit unsigned integer (uint32_t). * each of which is a 32-bit unsigned integer (uint32_t). The constant
* configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
* array, and (for backward compatibility) defaults to 1 if left undefined.
* Prior to FreeRTOS V10.4.0 there was only one notification value per task.
* *
* Events can be sent to a task using an intermediary object. Examples of such * Events can be sent to a task using an intermediary object. Examples of such
* objects are queues, semaphores, mutexes and event groups. Task notifications * objects are queues, semaphores, mutexes and event groups. Task notifications
@ -1972,22 +2079,41 @@ BaseType_t xTaskGenericNotifyFromISR( TaskHandle_t xTaskToNotify, UBaseType_t ux
* an intermediary object. * an intermediary object.
* *
* A notification sent to a task can optionally perform an action, such as * A notification sent to a task can optionally perform an action, such as
* update, overwrite or increment the task's notification value. In that way * update, overwrite or increment one of the task's notification values. In
* task notifications can be used to send data to a task, or be used as light * that way task notifications can be used to send data to a task, or be used as
* weight and fast binary or counting semaphores. * light weight and fast binary or counting semaphores.
* *
* A notification sent to a task will remain pending until it is cleared by the * A notification sent to a task will remain pending until it is cleared by the
* task calling xTaskNotifyWait() or ulTaskNotifyTake(). If the task was * task calling xTaskNotifyWaitIndexed() or ulTaskNotifyTakeIndexed() (or their
* already in the Blocked state to wait for a notification when the notification * un-indexed equivalents). If the task was already in the Blocked state to
* arrives then the task will automatically be removed from the Blocked state * wait for a notification when the notification arrives then the task will
* (unblocked) and the notification cleared. * automatically be removed from the Blocked state (unblocked) and the
* notification cleared.
* *
* A task can use xTaskNotifyWait() to [optionally] block to wait for a * A task can use xTaskNotifyWaitIndexed() to [optionally] block to wait for a
* notification to be pending, or ulTaskNotifyTake() to [optionally] block * notification to be pending, or ulTaskNotifyTakeIndexed() to [optionally] block
* to wait for its notification value to have a non-zero value. The task does * to wait for a notification value to have a non-zero value. The task does
* not consume any CPU time while it is in the Blocked state. * not consume any CPU time while it is in the Blocked state.
* *
* See http://www.FreeRTOS.org/RTOS-task-notifications.html for details. * **NOTE** Each notification within the array operates independently - a task
* can only block on one notification within the array at a time and will not be
* unblocked by a notification sent to any other array index.
*
* Backward compatibility information:
* Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
* all task notification API functions operated on that value. Replacing the
* single notification value with an array of notification values necessitated a
* new set of API functions that could address specific notifications within the
* array. xTaskNotifyWait() is the original API function, and remains backward
* compatible by always operating on the notification value at index 0 in the
* array. Calling xTaskNotifyWait() is equivalent to calling
* xTaskNotifyWaitIndexed() with the uxIndexToWaitOn parameter set to 0.
*
* @param uxIndexToWaitOn The index within the calling task's array of
* notification values on which the calling task will wait for a notification to
* be received. uxIndexToWaitOn must be less than
* configTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyWait() does
* not have this parameter and always waits for notifications on index 0.
* *
* @param ulBitsToClearOnEntry Bits that are set in ulBitsToClearOnEntry value * @param ulBitsToClearOnEntry Bits that are set in ulBitsToClearOnEntry value
* will be cleared in the calling task's notification value before the task * will be cleared in the calling task's notification value before the task
@ -2026,22 +2152,31 @@ BaseType_t xTaskGenericNotifyFromISR( TaskHandle_t xTaskToNotify, UBaseType_t ux
* already pending when xTaskNotifyWait was called) then pdPASS is * already pending when xTaskNotifyWait was called) then pdPASS is
* returned. Otherwise pdFAIL is returned. * returned. Otherwise pdFAIL is returned.
* *
* \defgroup xTaskNotifyWait xTaskNotifyWait * \defgroup xTaskNotifyWaitIndexed xTaskNotifyWaitIndexed
* \ingroup TaskNotifications * \ingroup TaskNotifications
*/ */
BaseType_t xTaskGenericNotifyWait( UBaseType_t uxIndexToWait, uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; BaseType_t xTaskGenericNotifyWait( UBaseType_t uxIndexToWaitOn, uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
#define xTaskNotifyWait( ulBitsToClearOnEntry, ulBitsToClearOnExit, pulNotificationValue, xTicksToWait ) xTaskGenericNotifyWait( tskDEFAULT_INDEX_TO_NOTIFY, ( ulBitsToClearOnEntry ), ( ulBitsToClearOnExit ), ( pulNotificationValue ), ( xTicksToWait ) ) #define xTaskNotifyWait( ulBitsToClearOnEntry, ulBitsToClearOnExit, pulNotificationValue, xTicksToWait ) xTaskGenericNotifyWait( tskDEFAULT_INDEX_TO_NOTIFY, ( ulBitsToClearOnEntry ), ( ulBitsToClearOnExit ), ( pulNotificationValue ), ( xTicksToWait ) )
#define xTaskNotifyWaitIndexed( uxIndexToWait, ulBitsToClearOnEntry, ulBitsToClearOnExit, pulNotificationValue, xTicksToWait ) xTaskGenericNotifyWait( uxIndexToWait, ( ulBitsToClearOnEntry ), ( ulBitsToClearOnExit ), ( pulNotificationValue ), ( xTicksToWait ) ) #define xTaskNotifyWaitIndexed( uxIndexToWaitOn, ulBitsToClearOnEntry, ulBitsToClearOnExit, pulNotificationValue, xTicksToWait ) xTaskGenericNotifyWait( ( uxIndexToWaitOn ), ( ulBitsToClearOnEntry ), ( ulBitsToClearOnExit ), ( pulNotificationValue ), ( xTicksToWait ) )
/** /**
* task. h * task. h
* <PRE>BaseType_t xTaskNotifyGiveIndexed( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify );</PRE>
* <PRE>BaseType_t xTaskNotifyGive( TaskHandle_t xTaskToNotify );</PRE> * <PRE>BaseType_t xTaskNotifyGive( TaskHandle_t xTaskToNotify );</PRE>
* *
* configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this macro * Sends a direct to task notification to a particular index in the target
* to be available. * task's notification array in a manner similar to giving a counting semaphore.
* *
* When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private * See http://www.FreeRTOS.org/RTOS-task-notifications.html for more details.
* "notification value", which is a 32-bit unsigned integer (uint32_t). *
* configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these
* macros to be available.
*
* Each task has a private array of "notification values" (or 'notifications'),
* each of which is a 32-bit unsigned integer (uint32_t). The constant
* configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
* array, and (for backward compatibility) defaults to 1 if left undefined.
* Prior to FreeRTOS V10.4.0 there was only one notification value per task.
* *
* Events can be sent to a task using an intermediary object. Examples of such * Events can be sent to a task using an intermediary object. Examples of such
* objects are queues, semaphores, mutexes and event groups. Task notifications * objects are queues, semaphores, mutexes and event groups. Task notifications
@ -2049,32 +2184,49 @@ BaseType_t xTaskGenericNotifyWait( UBaseType_t uxIndexToWait, uint32_t ulBitsToC
* an intermediary object. * an intermediary object.
* *
* A notification sent to a task can optionally perform an action, such as * A notification sent to a task can optionally perform an action, such as
* update, overwrite or increment the task's notification value. In that way * update, overwrite or increment one of the task's notification values. In
* task notifications can be used to send data to a task, or be used as light * that way task notifications can be used to send data to a task, or be used as
* weight and fast binary or counting semaphores. * light weight and fast binary or counting semaphores.
* *
* xTaskNotifyGive() is a helper macro intended for use when task notifications * xTaskNotifyGiveIndexed() is a helper macro intended for use when task
* are used as light weight and faster binary or counting semaphore equivalents. * notifications are used as light weight and faster binary or counting
* Actual FreeRTOS semaphores are given using the xSemaphoreGive() API function, * semaphore equivalents. Actual FreeRTOS semaphores are given using the
* the equivalent action that instead uses a task notification is * xSemaphoreGive() API function, the equivalent action that instead uses a task
* xTaskNotifyGive(). * notification is xTaskNotifyGiveIndexed().
* *
* When task notifications are being used as a binary or counting semaphore * When task notifications are being used as a binary or counting semaphore
* equivalent then the task being notified should wait for the notification * equivalent then the task being notified should wait for the notification
* using the ulTaskNotificationTake() API function rather than the * using the ulTaskNotificationTakeIndexed() API function rather than the
* xTaskNotifyWait() API function. * xTaskNotifyWaitIndexed() API function.
* *
* See http://www.FreeRTOS.org/RTOS-task-notifications.html for more details. * **NOTE** Each notification within the array operates independently - a task
* can only block on one notification within the array at a time and will not be
* unblocked by a notification sent to any other array index.
*
* Backward compatibility information:
* Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
* all task notification API functions operated on that value. Replacing the
* single notification value with an array of notification values necessitated a
* new set of API functions that could address specific notifications within the
* array. xTaskNotifyGive() is the original API function, and remains backward
* compatible by always operating on the notification value at index 0 in the
* array. Calling xTaskNotifyGive() is equivalent to calling
* xTaskNotifyGiveIndexed() with the uxIndexToNotify parameter set to 0.
* *
* @param xTaskToNotify The handle of the task being notified. The handle to a * @param xTaskToNotify The handle of the task being notified. The handle to a
* task can be returned from the xTaskCreate() API function used to create the * task can be returned from the xTaskCreate() API function used to create the
* task, and the handle of the currently running task can be obtained by calling * task, and the handle of the currently running task can be obtained by calling
* xTaskGetCurrentTaskHandle(). * xTaskGetCurrentTaskHandle().
* *
* @param uxIndexToNotify The index within the target task's array of
* notification values to which the notification is to be sent. uxIndexToNotify
* must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyGive()
* does not have this parameter and always sends notifications to index 0.
*
* @return xTaskNotifyGive() is a macro that calls xTaskNotify() with the * @return xTaskNotifyGive() is a macro that calls xTaskNotify() with the
* eAction parameter set to eIncrement - so pdPASS is always returned. * eAction parameter set to eIncrement - so pdPASS is always returned.
* *
* \defgroup xTaskNotifyGive xTaskNotifyGive * \defgroup xTaskNotifyGiveIndexed xTaskNotifyGiveIndexed
* \ingroup TaskNotifications * \ingroup TaskNotifications
*/ */
#define xTaskNotifyGive( xTaskToNotify ) xTaskGenericNotify( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( 0 ), eIncrement, NULL ) #define xTaskNotifyGive( xTaskToNotify ) xTaskGenericNotify( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( 0 ), eIncrement, NULL )
@ -2082,16 +2234,22 @@ BaseType_t xTaskGenericNotifyWait( UBaseType_t uxIndexToWait, uint32_t ulBitsToC
/** /**
* task. h * task. h
* <PRE>void vTaskNotifyGiveIndexedFromISR( TaskHandle_t xTaskHandle, UBaseType_t uxIndexToNotify, BaseType_t *pxHigherPriorityTaskWoken );
* <PRE>void vTaskNotifyGiveFromISR( TaskHandle_t xTaskHandle, BaseType_t *pxHigherPriorityTaskWoken ); * <PRE>void vTaskNotifyGiveFromISR( TaskHandle_t xTaskHandle, BaseType_t *pxHigherPriorityTaskWoken );
* *
* A version of xTaskNotifyGiveIndexed() that can be called from an interrupt
* service routine (ISR).
*
* See http://www.FreeRTOS.org/RTOS-task-notifications.html for more details.
*
* configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this macro * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this macro
* to be available. * to be available.
* *
* When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private * Each task has a private array of "notification values" (or 'notifications'),
* "notification value", which is a 32-bit unsigned integer (uint32_t). * each of which is a 32-bit unsigned integer (uint32_t). The constant
* * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
* A version of xTaskNotifyGive() that can be called from an interrupt service * array, and (for backward compatibility) defaults to 1 if left undefined.
* routine (ISR). * Prior to FreeRTOS V10.4.0 there was only one notification value per task.
* *
* Events can be sent to a task using an intermediary object. Examples of such * Events can be sent to a task using an intermediary object. Examples of such
* objects are queues, semaphores, mutexes and event groups. Task notifications * objects are queues, semaphores, mutexes and event groups. Task notifications
@ -2099,28 +2257,46 @@ BaseType_t xTaskGenericNotifyWait( UBaseType_t uxIndexToWait, uint32_t ulBitsToC
* an intermediary object. * an intermediary object.
* *
* A notification sent to a task can optionally perform an action, such as * A notification sent to a task can optionally perform an action, such as
* update, overwrite or increment the task's notification value. In that way * update, overwrite or increment one of the task's notification values. In
* task notifications can be used to send data to a task, or be used as light * that way task notifications can be used to send data to a task, or be used as
* weight and fast binary or counting semaphores. * light weight and fast binary or counting semaphores.
* *
* vTaskNotifyGiveFromISR() is intended for use when task notifications are * vTaskNotifyGiveIndexedFromISR() is intended for use when task notifications
* used as light weight and faster binary or counting semaphore equivalents. * are used as light weight and faster binary or counting semaphore equivalents.
* Actual FreeRTOS semaphores are given from an ISR using the * Actual FreeRTOS semaphores are given from an ISR using the
* xSemaphoreGiveFromISR() API function, the equivalent action that instead uses * xSemaphoreGiveFromISR() API function, the equivalent action that instead uses
* a task notification is vTaskNotifyGiveFromISR(). * a task notification is vTaskNotifyGiveIndexedFromISR().
* *
* When task notifications are being used as a binary or counting semaphore * When task notifications are being used as a binary or counting semaphore
* equivalent then the task being notified should wait for the notification * equivalent then the task being notified should wait for the notification
* using the ulTaskNotificationTake() API function rather than the * using the ulTaskNotificationTakeIndexed() API function rather than the
* xTaskNotifyWait() API function. * xTaskNotifyWaitIndexed() API function.
* *
* See http://www.FreeRTOS.org/RTOS-task-notifications.html for more details. * **NOTE** Each notification within the array operates independently - a task
* can only block on one notification within the array at a time and will not be
* unblocked by a notification sent to any other array index.
*
* Backward compatibility information:
* Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
* all task notification API functions operated on that value. Replacing the
* single notification value with an array of notification values necessitated a
* new set of API functions that could address specific notifications within the
* array. xTaskNotifyFromISR() is the original API function, and remains
* backward compatible by always operating on the notification value at index 0
* within the array. Calling xTaskNotifyGiveFromISR() is equivalent to calling
* xTaskNotifyGiveIndexedFromISR() with the uxIndexToNotify parameter set to 0.
* *
* @param xTaskToNotify The handle of the task being notified. The handle to a * @param xTaskToNotify The handle of the task being notified. The handle to a
* task can be returned from the xTaskCreate() API function used to create the * task can be returned from the xTaskCreate() API function used to create the
* task, and the handle of the currently running task can be obtained by calling * task, and the handle of the currently running task can be obtained by calling
* xTaskGetCurrentTaskHandle(). * xTaskGetCurrentTaskHandle().
* *
* @param uxIndexToNotify The index within the target task's array of
* notification values to which the notification is to be sent. uxIndexToNotify
* must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES.
* xTaskNotifyGiveFromISR() does not have this parameter and always sends
* notifications to index 0.
*
* @param pxHigherPriorityTaskWoken vTaskNotifyGiveFromISR() will set * @param pxHigherPriorityTaskWoken vTaskNotifyGiveFromISR() will set
* *pxHigherPriorityTaskWoken to pdTRUE if sending the notification caused the * *pxHigherPriorityTaskWoken to pdTRUE if sending the notification caused the
* task to which the notification was sent to leave the Blocked state, and the * task to which the notification was sent to leave the Blocked state, and the
@ -2130,7 +2306,7 @@ BaseType_t xTaskGenericNotifyWait( UBaseType_t uxIndexToWait, uint32_t ulBitsToC
* requested from an ISR is dependent on the port - see the documentation page * requested from an ISR is dependent on the port - see the documentation page
* for the port in use. * for the port in use.
* *
* \defgroup xTaskNotifyWait xTaskNotifyWait * \defgroup vTaskNotifyGiveIndexedFromISR vTaskNotifyGiveIndexedFromISR
* \ingroup TaskNotifications * \ingroup TaskNotifications
*/ */
void vTaskGenericNotifyGiveFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, BaseType_t *pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION; void vTaskGenericNotifyGiveFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, BaseType_t *pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
@ -2139,13 +2315,22 @@ void vTaskGenericNotifyGiveFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIn
/** /**
* task. h * task. h
* <PRE>uint32_t ulTaskNotifyTakeIndexed( UBaseType_t uxIndexToWaitOn, BaseType_t xClearCountOnExit, TickType_t xTicksToWait );</pre>
* <PRE>uint32_t ulTaskNotifyTake( BaseType_t xClearCountOnExit, TickType_t xTicksToWait );</pre> * <PRE>uint32_t ulTaskNotifyTake( BaseType_t xClearCountOnExit, TickType_t xTicksToWait );</pre>
* *
* Waits for a direct to task notification on a particular index in the calling
* task's notification array in a manner similar to taking a counting semaphore.
*
* See http://www.FreeRTOS.org/RTOS-task-notifications.html for details.
*
* configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this
* function to be available. * function to be available.
* *
* When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private * Each task has a private array of "notification values" (or 'notifications'),
* "notification value", which is a 32-bit unsigned integer (uint32_t). * each of which is a 32-bit unsigned integer (uint32_t). The constant
* configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
* array, and (for backward compatibility) defaults to 1 if left undefined.
* Prior to FreeRTOS V10.4.0 there was only one notification value per task.
* *
* Events can be sent to a task using an intermediary object. Examples of such * Events can be sent to a task using an intermediary object. Examples of such
* objects are queues, semaphores, mutexes and event groups. Task notifications * objects are queues, semaphores, mutexes and event groups. Task notifications
@ -2153,35 +2338,54 @@ void vTaskGenericNotifyGiveFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIn
* an intermediary object. * an intermediary object.
* *
* A notification sent to a task can optionally perform an action, such as * A notification sent to a task can optionally perform an action, such as
* update, overwrite or increment the task's notification value. In that way * update, overwrite or increment one of the task's notification values. In
* task notifications can be used to send data to a task, or be used as light * that way task notifications can be used to send data to a task, or be used as
* weight and fast binary or counting semaphores. * light weight and fast binary or counting semaphores.
* *
* ulTaskNotifyTake() is intended for use when a task notification is used as a * ulTaskNotifyTakeIndexed() is intended for use when a task notification is
* faster and lighter weight binary or counting semaphore alternative. Actual * used as a faster and lighter weight binary or counting semaphore alternative.
* FreeRTOS semaphores are taken using the xSemaphoreTake() API function, the * Actual FreeRTOS semaphores are taken using the xSemaphoreTake() API function,
* equivalent action that instead uses a task notification is * the equivalent action that instead uses a task notification is
* ulTaskNotifyTake(). * ulTaskNotifyTakeIndexed().
* *
* When a task is using its notification value as a binary or counting semaphore * When a task is using its notification value as a binary or counting semaphore
* other tasks should send notifications to it using the xTaskNotifyGive() * other tasks should send notifications to it using the xTaskNotifyGiveIndexed()
* macro, or xTaskNotify() function with the eAction parameter set to * macro, or xTaskNotifyIndex() function with the eAction parameter set to
* eIncrement. * eIncrement.
* *
* ulTaskNotifyTake() can either clear the task's notification value to * ulTaskNotifyTakeIndexed() can either clear the task's notification value at
* zero on exit, in which case the notification value acts like a binary * the array index specified by the uxIndexToWaitOn parameter to zero on exit,
* semaphore, or decrement the task's notification value on exit, in which case * in which case the notification value acts like a binary semaphore, or
* the notification value acts like a counting semaphore. * decrement the notification value on exit, in which case the notification
* value acts like a counting semaphore.
* *
* A task can use ulTaskNotifyTake() to [optionally] block to wait for a * A task can use ulTaskNotifyTakeIndexed() to [optionally] block to wait for
* the task's notification value to be non-zero. The task does not consume any * the task's notification value to be non-zero. The task does not consume any
* CPU time while it is in the Blocked state. * CPU time while it is in the Blocked state.
* *
* Where as xTaskNotifyWait() will return when a notification is pending, * Where as xTaskNotifyWaitIndexed() will return when a notification is pending,
* ulTaskNotifyTake() will return when the task's notification value is * ulTaskNotifyTakeIndexed() will return when the task's notification value is
* not zero. * not zero.
* *
* See http://www.FreeRTOS.org/RTOS-task-notifications.html for details. * **NOTE** Each notification within the array operates independently - a task
* can only block on one notification within the array at a time and will not be
* unblocked by a notification sent to any other array index.
*
* Backward compatibility information:
* Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
* all task notification API functions operated on that value. Replacing the
* single notification value with an array of notification values necessitated a
* new set of API functions that could address specific notifications within the
* array. ulTaskNotifyTake() is the original API function, and remains backward
* compatible by always operating on the notification value at index 0 in the
* array. Calling ulTaskNotifyTake() is equivalent to calling
* ulTaskNotifyTakeIndexed() with the uxIndexToWaitOn parameter set to 0.
*
* @param uxIndexToWaitOn The index within the calling task's array of
* notification values on which the calling task will wait for a notification to
* be non-zero. uxIndexToWaitOn must be less than
* configTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyTake() does
* not have this parameter and always waits for notifications on index 0.
* *
* @param xClearCountOnExit if xClearCountOnExit is pdFALSE then the task's * @param xClearCountOnExit if xClearCountOnExit is pdFALSE then the task's
* notification value is decremented when the function exits. In this way the * notification value is decremented when the function exits. In this way the
@ -2201,25 +2405,65 @@ void vTaskGenericNotifyGiveFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIn
* @return The task's notification count before it is either cleared to zero or * @return The task's notification count before it is either cleared to zero or
* decremented (see the xClearCountOnExit parameter). * decremented (see the xClearCountOnExit parameter).
* *
* \defgroup ulTaskNotifyTake ulTaskNotifyTake * \defgroup ulTaskNotifyTakeIndexed ulTaskNotifyTakeIndexed
* \ingroup TaskNotifications * \ingroup TaskNotifications
*/ */
uint32_t ulTaskGenericNotifyTake( UBaseType_t uxIndexToWait, BaseType_t xClearCountOnExit, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; uint32_t ulTaskGenericNotifyTake( UBaseType_t uxIndexToWaitOn, BaseType_t xClearCountOnExit, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
#define ulTaskNotifyTake( xClearCountOnExit, xTicksToWait ) ulTaskGenericNotifyTake( ( tskDEFAULT_INDEX_TO_NOTIFY ), ( xClearCountOnExit ), ( xTicksToWait ) ) #define ulTaskNotifyTake( xClearCountOnExit, xTicksToWait ) ulTaskGenericNotifyTake( ( tskDEFAULT_INDEX_TO_NOTIFY ), ( xClearCountOnExit ), ( xTicksToWait ) )
#define ulTaskNotifyTakeIndexed( uxIndexToNotify, xClearCountOnExit, xTicksToWait ) ulTaskGenericNotifyTake( ( uxIndexToNotify ), ( xClearCountOnExit ), ( xTicksToWait ) ) #define ulTaskNotifyTakeIndexed( uxIndexToWaitOn, xClearCountOnExit, xTicksToWait ) ulTaskGenericNotifyTake( ( uxIndexToNotify ), ( xClearCountOnExit ), ( xTicksToWait ) )
/** /**
* task. h * task. h
* <PRE>BaseType_t xTaskNotifyStateClearIndexed( TaskHandle_t xTask, UBaseType_t uxIndexToCLear );</pre>
* <PRE>BaseType_t xTaskNotifyStateClear( TaskHandle_t xTask );</pre> * <PRE>BaseType_t xTaskNotifyStateClear( TaskHandle_t xTask );</pre>
* *
* If the notification state of the task referenced by the handle xTask is * See http://www.FreeRTOS.org/RTOS-task-notifications.html for details.
* eNotified, then set the task's notification state to eNotWaitingNotification. *
* The task's notification value is not altered. Set xTask to NULL to clear the * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these
* notification state of the calling task. * functions to be available.
*
* Each task has a private array of "notification values" (or 'notifications'),
* each of which is a 32-bit unsigned integer (uint32_t). The constant
* configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
* array, and (for backward compatibility) defaults to 1 if left undefined.
* Prior to FreeRTOS V10.4.0 there was only one notification value per task.
*
* If a notification is sent to an index within the array of notifications then
* the notification at that index is said to be 'pending' until it is read or
* explicitly cleared by the receiving task. xTaskNotifyStateClearIndexed()
* is the function that clears a pending notification without reading the
* notification value. The notification value at the same array index is not
* altered. Set xTask to NULL to clear the notification state of the calling
* task.
*
* Backward compatibility information:
* Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
* all task notification API functions operated on that value. Replacing the
* single notification value with an array of notification values necessitated a
* new set of API functions that could address specific notifications within the
* array. xTaskNotifyStateClear() is the original API function, and remains
* backward compatible by always operating on the notification value at index 0
* within the array. Calling xTaskNotifyStateClear() is equivalent to calling
* xTaskNotifyStateClearIndexed() with the uxIndexToNotify parameter set to 0.
*
* @param xTask The handle of the RTOS task that will have a notification state
* cleared. Set xTask to NULL to clear a notification state in the calling
* task. To obtain a task's handle create the task using xTaskCreate() and
* make use of the pxCreatedTask parameter, or create the task using
* xTaskCreateStatic() and store the returned value, or use the task's name in
* a call to xTaskGetHandle().
*
* @param uxIndexToClear The index within the target task's array of
* notification values to act upon. For example, setting uxIndexToClear to 1
* will clear the state of the notification at index 1 within the array.
* uxIndexToClear must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES.
* ulTaskNotifyStateClear() does not have this parameter and always acts on the
* notification at index 0.
* *
* @return pdTRUE if the task's notification state was set to * @return pdTRUE if the task's notification state was set to
* eNotWaitingNotification, otherwise pdFALSE. * eNotWaitingNotification, otherwise pdFALSE.
* \defgroup xTaskNotifyStateClear xTaskNotifyStateClear *
* \defgroup xTaskNotifyStateClearIndexed xTaskNotifyStateClearIndexed
* \ingroup TaskNotifications * \ingroup TaskNotifications
*/ */
BaseType_t xTaskGenericNotifyStateClear( TaskHandle_t xTask, UBaseType_t uxIndexToClear ) PRIVILEGED_FUNCTION; BaseType_t xTaskGenericNotifyStateClear( TaskHandle_t xTask, UBaseType_t uxIndexToClear ) PRIVILEGED_FUNCTION;
@ -2228,17 +2472,46 @@ BaseType_t xTaskGenericNotifyStateClear( TaskHandle_t xTask, UBaseType_t uxIndex
/** /**
* task. h * task. h
* <PRE>uint32_t ulTaskNotifyValueClearIndexed( TaskHandle_t xTask, UBaseType_t uxIndexToClear, uint32_t ulBitsToClear );</pre>
* <PRE>uint32_t ulTaskNotifyValueClear( TaskHandle_t xTask, uint32_t ulBitsToClear );</pre> * <PRE>uint32_t ulTaskNotifyValueClear( TaskHandle_t xTask, uint32_t ulBitsToClear );</pre>
* *
* Clears the bits specified by the ulBitsToClear bit mask in the notification * See http://www.FreeRTOS.org/RTOS-task-notifications.html for details.
* value of the task referenced by xTask.
* *
* @param xTask The handle of the RTOS task that will have bits in its notification * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these
* value cleared. Set xTask to NULL to clear bits in the notification value of the * functions to be available.
* calling task. To obtain a task's handle create the task using xTaskCreate() and *
* make use of the pxCreatedTask parameter, or create the task using * Each task has a private array of "notification values" (or 'notifications'),
* xTaskCreateStatic() and store the returned value, or use the task's name in a call * each of which is a 32-bit unsigned integer (uint32_t). The constant
* to xTaskGetHandle(). * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
* array, and (for backward compatibility) defaults to 1 if left undefined.
* Prior to FreeRTOS V10.4.0 there was only one notification value per task.
*
* ulTaskNotifyValueClearIndexed() clears the bits specified by the
* ulBitsToClear bit mask in the notification value at array index uxIndexToClear
* of the task referenced by xTask.
*
* Backward compatibility information:
* Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
* all task notification API functions operated on that value. Replacing the
* single notification value with an array of notification values necessitated a
* new set of API functions that could address specific notifications within the
* array. ulTaskNotifyValueClear() is the original API function, and remains
* backward compatible by always operating on the notification value at index 0
* within the array. Calling ulTaskNotifyValueClear() is equivalent to calling
* ulTaskNotifyValueClearIndexed() with the uxIndexToClear parameter set to 0.
*
* @param xTask The handle of the RTOS task that will have bits in one of its
* notification values cleared. Set xTask to NULL to clear bits in a
* notification value of the calling task. To obtain a task's handle create the
* task using xTaskCreate() and make use of the pxCreatedTask parameter, or
* create the task using xTaskCreateStatic() and store the returned value, or
* use the task's name in a call to xTaskGetHandle().
*
* @param uxIndexToClear The index within the target task's array of
* notification values in which to clear the bits. uxIndexToClear
* must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES.
* ulTaskNotifyValueClear() does not have this parameter and always clears bits
* in the notification value at index 0.
* *
* @param ulBitsToClear Bit mask of the bits to clear in the notification value of * @param ulBitsToClear Bit mask of the bits to clear in the notification value of
* xTask. Set a bit to 1 to clear the corresponding bits in the task's notification * xTask. Set a bit to 1 to clear the corresponding bits in the task's notification

20
tasks.c
View file

@ -308,8 +308,8 @@ typedef struct tskTaskControlBlock /* The old naming convention is used to pr
#endif #endif
#if( configUSE_TASK_NOTIFICATIONS == 1 ) #if( configUSE_TASK_NOTIFICATIONS == 1 )
volatile uint32_t ulNotifiedValue[ configNUMBER_OF_TASK_NOTIFICATIONS ]; volatile uint32_t ulNotifiedValue[ configTASK_NOTIFICATION_ARRAY_ENTRIES ];
volatile uint8_t ucNotifyState[ configNUMBER_OF_TASK_NOTIFICATIONS ]; volatile uint8_t ucNotifyState[ configTASK_NOTIFICATION_ARRAY_ENTRIES ];
#endif #endif
/* See the comments in FreeRTOS.h with the definition of /* See the comments in FreeRTOS.h with the definition of
@ -1428,7 +1428,7 @@ static void prvAddNewTaskToReadyList( TCB_t *pxNewTCB )
rather than waiting on an object. If not, is rather than waiting on an object. If not, is
suspended. */ suspended. */
eReturn = eSuspended; eReturn = eSuspended;
for( x = 0; x < configNUMBER_OF_TASK_NOTIFICATIONS; x++ ) for( x = 0; x < configTASK_NOTIFICATION_ARRAY_ENTRIES; x++ )
{ {
if( pxTCB->ucNotifyState[ x ] == taskWAITING_NOTIFICATION ) if( pxTCB->ucNotifyState[ x ] == taskWAITING_NOTIFICATION )
{ {
@ -1741,7 +1741,7 @@ static void prvAddNewTaskToReadyList( TCB_t *pxNewTCB )
{ {
BaseType_t x; BaseType_t x;
for( x = 0; x < configNUMBER_OF_TASK_NOTIFICATIONS; x++ ) for( x = 0; x < configTASK_NOTIFICATION_ARRAY_ENTRIES; x++ )
{ {
if( pxTCB->ucNotifyState[ x ] == taskWAITING_NOTIFICATION ) if( pxTCB->ucNotifyState[ x ] == taskWAITING_NOTIFICATION )
{ {
@ -4645,7 +4645,7 @@ TickType_t uxReturn;
{ {
uint32_t ulReturn; uint32_t ulReturn;
configASSERT( uxIndexToWait < configNUMBER_OF_TASK_NOTIFICATIONS ); configASSERT( uxIndexToWait < configTASK_NOTIFICATION_ARRAY_ENTRIES );
taskENTER_CRITICAL(); taskENTER_CRITICAL();
{ {
@ -4719,7 +4719,7 @@ TickType_t uxReturn;
{ {
BaseType_t xReturn; BaseType_t xReturn;
configASSERT( uxIndexToWait < configNUMBER_OF_TASK_NOTIFICATIONS ); configASSERT( uxIndexToWait < configTASK_NOTIFICATION_ARRAY_ENTRIES );
taskENTER_CRITICAL(); taskENTER_CRITICAL();
{ {
@ -4807,7 +4807,7 @@ TickType_t uxReturn;
BaseType_t xReturn = pdPASS; BaseType_t xReturn = pdPASS;
uint8_t ucOriginalNotifyState; uint8_t ucOriginalNotifyState;
configASSERT( uxIndexToNotify < configNUMBER_OF_TASK_NOTIFICATIONS ); configASSERT( uxIndexToNotify < configTASK_NOTIFICATION_ARRAY_ENTRIES );
configASSERT( xTaskToNotify ); configASSERT( xTaskToNotify );
pxTCB = xTaskToNotify; pxTCB = xTaskToNotify;
@ -4929,7 +4929,7 @@ TickType_t uxReturn;
UBaseType_t uxSavedInterruptStatus; UBaseType_t uxSavedInterruptStatus;
configASSERT( xTaskToNotify ); configASSERT( xTaskToNotify );
configASSERT( uxIndexToNotify < configNUMBER_OF_TASK_NOTIFICATIONS ); configASSERT( uxIndexToNotify < configTASK_NOTIFICATION_ARRAY_ENTRIES );
/* RTOS ports that support interrupt nesting have the concept of a /* RTOS ports that support interrupt nesting have the concept of a
maximum system call (or maximum API call) interrupt priority. maximum system call (or maximum API call) interrupt priority.
@ -5058,7 +5058,7 @@ TickType_t uxReturn;
UBaseType_t uxSavedInterruptStatus; UBaseType_t uxSavedInterruptStatus;
configASSERT( xTaskToNotify ); configASSERT( xTaskToNotify );
configASSERT( uxIndexToNotify < configNUMBER_OF_TASK_NOTIFICATIONS ); configASSERT( uxIndexToNotify < configTASK_NOTIFICATION_ARRAY_ENTRIES );
/* RTOS ports that support interrupt nesting have the concept of a /* RTOS ports that support interrupt nesting have the concept of a
maximum system call (or maximum API call) interrupt priority. maximum system call (or maximum API call) interrupt priority.
@ -5143,7 +5143,7 @@ TickType_t uxReturn;
TCB_t *pxTCB; TCB_t *pxTCB;
BaseType_t xReturn; BaseType_t xReturn;
configASSERT( uxIndexToClear < configNUMBER_OF_TASK_NOTIFICATIONS ); configASSERT( uxIndexToClear < configTASK_NOTIFICATION_ARRAY_ENTRIES );
/* If null is passed in here then it is the calling task that is having /* If null is passed in here then it is the calling task that is having
its notification state cleared. */ its notification state cleared. */