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

Feature/multiple direct to task notifications (#63)

Browse source 
Description
Before this change each task had a single direct to task notification value and state as described here: https://www.FreeRTOS.org/RTOS-task-notifications.html. After this change each task has an array of task notifications, so more than one task notification value and state per task. The new FreeRTOSConfig.h compile time constant configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the array.

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.

Task notifications were introduced as a light weight method for peripheral drivers to pass data and events to tasks without the need for an intermediary object such as a semaphore - for example, to unblock a task from an ISR when the operation of a peripheral completed. That use case only requires a single notification value. Their popularity and resultant expanded use cases have since made the single value a limitation - especially as FreeRTOS stream and message buffers themselves use the notification mechanism. This change resolves that limitation. Stream and message buffers still use the task notification at array index 0, but now application writers can avoid any conflict that might have with their own use of task notifications by using notifications at array indexes other than 0.

The pre-existing task notification API functions work in a backward compatible way by always using the task notification at array index 0. For each such function there is now an equivalent that is postfixed "Indexed" and takes an additional parameter to specify which index within the array it should operate upon. For example, xTaskNotify() is the original that only operates on array index 0. xTaskNotifyIndexed() is the new function that can operate on any array index.

Test Steps
The update is tested using the Win32 demo (PR to be created in the FreeRTOS/FreeRTOS github repo), which has been updated to build and run a new test file FreeRTOS/Demo/Common/Minimal/TaskNotifyArray.c. The tests in that file are in addition to, not a replacement for those in FreeRTOS/Demo/Common/Minimal/TaskNotify.c.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.
This commit is contained in:
RichardBarry 2020-05-27 12:28:48 -07:00 • committed by GitHub
parent e4e4fb01a1
commit f2081af030
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 546 additions and 215 deletions
Download patch file Download diff file Expand all files Collapse all files

158
tasks.c
View file

@ -65,7 +65,7 @@ functions but without including stdio.h here. */
#endif
/* Values that can be assigned to the ucNotifyState member of the TCB. */
#define taskNOT_WAITING_NOTIFICATION ( ( uint8_t ) 0 )
#define taskNOT_WAITING_NOTIFICATION ( ( uint8_t ) 0 ) /* Must be zero as it is the initialised value. */
#define taskWAITING_NOTIFICATION ( ( uint8_t ) 1 )
#define taskNOTIFICATION_RECEIVED ( ( uint8_t ) 2 )
@ -308,8 +308,8 @@ typedef struct tskTaskControlBlock /* The old naming convention is used to pr
#endif
#if( configUSE_TASK_NOTIFICATIONS == 1 )
volatile uint32_t ulNotifiedValue;
volatile uint8_t ucNotifyState;
volatile uint32_t ulNotifiedValue[ configTASK_NOTIFICATION_ARRAY_ENTRIES ];
volatile uint8_t ucNotifyState[ configTASK_NOTIFICATION_ARRAY_ENTRIES ];
#endif
/* See the comments in FreeRTOS.h with the definition of
@ -980,17 +980,14 @@ UBaseType_t x;
#if( configNUM_THREAD_LOCAL_STORAGE_POINTERS != 0 )
{
for( x = 0; x < ( UBaseType_t ) configNUM_THREAD_LOCAL_STORAGE_POINTERS; x++ )
{
pxNewTCB->pvThreadLocalStoragePointers[ x ] = NULL;
}
memset( ( void * ) &( pxNewTCB->pvThreadLocalStoragePointers[ 0 ] ), 0x00, sizeof( pxNewTCB->pvThreadLocalStoragePointers ) );
}
#endif
#if ( configUSE_TASK_NOTIFICATIONS == 1 )
{
pxNewTCB->ulNotifiedValue = 0;
pxNewTCB->ucNotifyState = taskNOT_WAITING_NOTIFICATION;
memset( ( void * ) &( pxNewTCB->ulNotifiedValue[ 0 ] ), 0x00, sizeof( pxNewTCB->ulNotifiedValue ) );
memset( ( void * ) &( pxNewTCB->ucNotifyState[ 0 ] ), 0x00, sizeof( pxNewTCB->ucNotifyState ) );
}
#endif
@ -1423,17 +1420,21 @@ static void prvAddNewTaskToReadyList( TCB_t *pxNewTCB )
{
#if( configUSE_TASK_NOTIFICATIONS == 1 )
{
BaseType_t x;
/* The task does not appear on the event list item of
and of the RTOS objects, but could still be in the
blocked state if it is waiting on its notification
rather than waiting on an object. */
if( pxTCB->ucNotifyState == taskWAITING_NOTIFICATION )
rather than waiting on an object. If not, is
suspended. */
eReturn = eSuspended;
for( x = 0; x < configTASK_NOTIFICATION_ARRAY_ENTRIES; x++ )
{
eReturn = eBlocked;
}
else
{
eReturn = eSuspended;
if( pxTCB->ucNotifyState[ x ] == taskWAITING_NOTIFICATION )
{
eReturn = eBlocked;
break;
}
}
}
#else
@ -1738,11 +1739,16 @@ static void prvAddNewTaskToReadyList( TCB_t *pxNewTCB )
#if( configUSE_TASK_NOTIFICATIONS == 1 )
{
if( pxTCB->ucNotifyState == taskWAITING_NOTIFICATION )
BaseType_t x;
for( x = 0; x < configTASK_NOTIFICATION_ARRAY_ENTRIES; x++ )
{
/* The task was blocked to wait for a notification, but is
now suspended, so no notification was received. */
pxTCB->ucNotifyState = taskNOT_WAITING_NOTIFICATION;
if( pxTCB->ucNotifyState[ x ] == taskWAITING_NOTIFICATION )
{
/* The task was blocked to wait for a notification, but is
now suspended, so no notification was received. */
pxTCB->ucNotifyState[ x ] = taskNOT_WAITING_NOTIFICATION;
}
}
}
#endif
@ -4635,17 +4641,19 @@ TickType_t uxReturn;
#if( configUSE_TASK_NOTIFICATIONS == 1 )
uint32_t ulTaskNotifyTake( BaseType_t xClearCountOnExit, TickType_t xTicksToWait )
uint32_t ulTaskGenericNotifyTake( UBaseType_t uxIndexToWait, BaseType_t xClearCountOnExit, TickType_t xTicksToWait )
{
uint32_t ulReturn;
configASSERT( uxIndexToWait < configTASK_NOTIFICATION_ARRAY_ENTRIES );
taskENTER_CRITICAL();
{
/* Only block if the notification count is not already non-zero. */
if( pxCurrentTCB->ulNotifiedValue == 0UL )
if( pxCurrentTCB->ulNotifiedValue[ uxIndexToWait ] == 0UL )
{
/* Mark this task as waiting for a notification. */
pxCurrentTCB->ucNotifyState = taskWAITING_NOTIFICATION;
pxCurrentTCB->ucNotifyState[ uxIndexToWait ] = taskWAITING_NOTIFICATION;
if( xTicksToWait > ( TickType_t ) 0 )
{
@ -4672,18 +4680,18 @@ TickType_t uxReturn;
taskENTER_CRITICAL();
{
traceTASK_NOTIFY_TAKE();
ulReturn = pxCurrentTCB->ulNotifiedValue;
traceTASK_NOTIFY_TAKE( uxIndexToWait );
ulReturn = pxCurrentTCB->ulNotifiedValue[ uxIndexToWait ];
if( ulReturn != 0UL )
{
if( xClearCountOnExit != pdFALSE )
{
pxCurrentTCB->ulNotifiedValue = 0UL;
pxCurrentTCB->ulNotifiedValue[ uxIndexToWait ] = 0UL;
}
else
{
pxCurrentTCB->ulNotifiedValue = ulReturn - ( uint32_t ) 1;
pxCurrentTCB->ulNotifiedValue[ uxIndexToWait ] = ulReturn - ( uint32_t ) 1;
}
}
else
@ -4691,7 +4699,7 @@ TickType_t uxReturn;
mtCOVERAGE_TEST_MARKER();
}
pxCurrentTCB->ucNotifyState = taskNOT_WAITING_NOTIFICATION;
pxCurrentTCB->ucNotifyState[ uxIndexToWait ] = taskNOT_WAITING_NOTIFICATION;
}
taskEXIT_CRITICAL();
@ -4703,22 +4711,28 @@ TickType_t uxReturn;
#if( configUSE_TASK_NOTIFICATIONS == 1 )
BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait )
BaseType_t xTaskGenericNotifyWait( UBaseType_t uxIndexToWait,
uint32_t ulBitsToClearOnEntry,
uint32_t ulBitsToClearOnExit,
uint32_t *pulNotificationValue,
TickType_t xTicksToWait )
{
BaseType_t xReturn;
configASSERT( uxIndexToWait < configTASK_NOTIFICATION_ARRAY_ENTRIES );
taskENTER_CRITICAL();
{
/* Only block if a notification is not already pending. */
if( pxCurrentTCB->ucNotifyState != taskNOTIFICATION_RECEIVED )
if( pxCurrentTCB->ucNotifyState[ uxIndexToWait ] != taskNOTIFICATION_RECEIVED )
{
/* Clear bits in the task's notification value as bits may get
set by the notifying task or interrupt. This can be used to
clear the value to zero. */
pxCurrentTCB->ulNotifiedValue &= ~ulBitsToClearOnEntry;
pxCurrentTCB->ulNotifiedValue[ uxIndexToWait ] &= ~ulBitsToClearOnEntry;
/* Mark this task as waiting for a notification. */
pxCurrentTCB->ucNotifyState = taskWAITING_NOTIFICATION;
pxCurrentTCB->ucNotifyState[ uxIndexToWait ] = taskWAITING_NOTIFICATION;
if( xTicksToWait > ( TickType_t ) 0 )
{
@ -4745,20 +4759,20 @@ TickType_t uxReturn;
taskENTER_CRITICAL();
{
traceTASK_NOTIFY_WAIT();
traceTASK_NOTIFY_WAIT( uxIndexToWait );
if( pulNotificationValue != NULL )
{
/* Output the current notification value, which may or may not
have changed. */
*pulNotificationValue = pxCurrentTCB->ulNotifiedValue;
*pulNotificationValue = pxCurrentTCB->ulNotifiedValue[ uxIndexToWait ];
}
/* If ucNotifyValue is set then either the task never entered the
blocked state (because a notification was already pending) or the
task unblocked because of a notification. Otherwise the task
unblocked because of a timeout. */
if( pxCurrentTCB->ucNotifyState != taskNOTIFICATION_RECEIVED )
if( pxCurrentTCB->ucNotifyState[ uxIndexToWait ] != taskNOTIFICATION_RECEIVED )
{
/* A notification was not received. */
xReturn = pdFALSE;
@ -4767,11 +4781,11 @@ TickType_t uxReturn;
{
/* A notification was already pending or a notification was
received while the task was waiting. */
pxCurrentTCB->ulNotifiedValue &= ~ulBitsToClearOnExit;
pxCurrentTCB->ulNotifiedValue[ uxIndexToWait ] &= ~ulBitsToClearOnExit;
xReturn = pdTRUE;
}
pxCurrentTCB->ucNotifyState = taskNOT_WAITING_NOTIFICATION;
pxCurrentTCB->ucNotifyState[ uxIndexToWait ] = taskNOT_WAITING_NOTIFICATION;
}
taskEXIT_CRITICAL();
@ -4783,12 +4797,17 @@ TickType_t uxReturn;
#if( configUSE_TASK_NOTIFICATIONS == 1 )
BaseType_t xTaskGenericNotify( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue )
BaseType_t xTaskGenericNotify( TaskHandle_t xTaskToNotify,
UBaseType_t uxIndexToNotify,
uint32_t ulValue,
eNotifyAction eAction,
uint32_t *pulPreviousNotificationValue )
{
TCB_t * pxTCB;
BaseType_t xReturn = pdPASS;
uint8_t ucOriginalNotifyState;
configASSERT( uxIndexToNotify < configTASK_NOTIFICATION_ARRAY_ENTRIES );
configASSERT( xTaskToNotify );
pxTCB = xTaskToNotify;
@ -4796,31 +4815,31 @@ TickType_t uxReturn;
{
if( pulPreviousNotificationValue != NULL )
{
*pulPreviousNotificationValue = pxTCB->ulNotifiedValue;
*pulPreviousNotificationValue = pxTCB->ulNotifiedValue[ uxIndexToNotify ];
}
ucOriginalNotifyState = pxTCB->ucNotifyState;
ucOriginalNotifyState = pxTCB->ucNotifyState[ uxIndexToNotify ];
pxTCB->ucNotifyState = taskNOTIFICATION_RECEIVED;
pxTCB->ucNotifyState[ uxIndexToNotify ] = taskNOTIFICATION_RECEIVED;
switch( eAction )
{
case eSetBits :
pxTCB->ulNotifiedValue |= ulValue;
pxTCB->ulNotifiedValue[ uxIndexToNotify ] |= ulValue;
break;
case eIncrement :
( pxTCB->ulNotifiedValue )++;
( pxTCB->ulNotifiedValue[ uxIndexToNotify ] )++;
break;
case eSetValueWithOverwrite :
pxTCB->ulNotifiedValue = ulValue;
pxTCB->ulNotifiedValue[ uxIndexToNotify ] = ulValue;
break;
case eSetValueWithoutOverwrite :
if( ucOriginalNotifyState != taskNOTIFICATION_RECEIVED )
{
pxTCB->ulNotifiedValue = ulValue;
pxTCB->ulNotifiedValue[ uxIndexToNotify ] = ulValue;
}
else
{
@ -4838,7 +4857,7 @@ TickType_t uxReturn;
/* Should not get here if all enums are handled.
Artificially force an assert by testing a value the
compiler can't assume is const. */
configASSERT( pxTCB->ulNotifiedValue == ~0UL );
configASSERT( pxTCB->ulNotifiedValue[ uxIndexToNotify ] == ~0UL );
break;
}
@ -4897,7 +4916,12 @@ TickType_t uxReturn;
#if( configUSE_TASK_NOTIFICATIONS == 1 )
BaseType_t xTaskGenericNotifyFromISR( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue, BaseType_t *pxHigherPriorityTaskWoken )
BaseType_t xTaskGenericNotifyFromISR( TaskHandle_t xTaskToNotify,
UBaseType_t uxIndexToNotify,
uint32_t ulValue,
eNotifyAction eAction,
uint32_t *pulPreviousNotificationValue,
BaseType_t *pxHigherPriorityTaskWoken )
{
TCB_t * pxTCB;
uint8_t ucOriginalNotifyState;
@ -4905,6 +4929,7 @@ TickType_t uxReturn;
UBaseType_t uxSavedInterruptStatus;
configASSERT( xTaskToNotify );
configASSERT( uxIndexToNotify < configTASK_NOTIFICATION_ARRAY_ENTRIES );
/* RTOS ports that support interrupt nesting have the concept of a
maximum system call (or maximum API call) interrupt priority.
@ -4930,30 +4955,30 @@ TickType_t uxReturn;
{
if( pulPreviousNotificationValue != NULL )
{
*pulPreviousNotificationValue = pxTCB->ulNotifiedValue;
*pulPreviousNotificationValue = pxTCB->ulNotifiedValue[ uxIndexToNotify ];
}
ucOriginalNotifyState = pxTCB->ucNotifyState;
pxTCB->ucNotifyState = taskNOTIFICATION_RECEIVED;
ucOriginalNotifyState = pxTCB->ucNotifyState[ uxIndexToNotify ];
pxTCB->ucNotifyState[ uxIndexToNotify ] = taskNOTIFICATION_RECEIVED;
switch( eAction )
{
case eSetBits :
pxTCB->ulNotifiedValue |= ulValue;
pxTCB->ulNotifiedValue[ uxIndexToNotify ] |= ulValue;
break;
case eIncrement :
( pxTCB->ulNotifiedValue )++;
( pxTCB->ulNotifiedValue[ uxIndexToNotify ] )++;
break;
case eSetValueWithOverwrite :
pxTCB->ulNotifiedValue = ulValue;
pxTCB->ulNotifiedValue[ uxIndexToNotify ] = ulValue;
break;
case eSetValueWithoutOverwrite :
if( ucOriginalNotifyState != taskNOTIFICATION_RECEIVED )
{
pxTCB->ulNotifiedValue = ulValue;
pxTCB->ulNotifiedValue[ uxIndexToNotify ] = ulValue;
}
else
{
@ -4971,7 +4996,7 @@ TickType_t uxReturn;
/* Should not get here if all enums are handled.
Artificially force an assert by testing a value the
compiler can't assume is const. */
configASSERT( pxTCB->ulNotifiedValue == ~0UL );
configASSERT( pxTCB->ulNotifiedValue[ uxIndexToNotify ] == ~0UL );
break;
}
@ -5026,13 +5051,14 @@ TickType_t uxReturn;
#if( configUSE_TASK_NOTIFICATIONS == 1 )
void vTaskNotifyGiveFromISR( TaskHandle_t xTaskToNotify, BaseType_t *pxHigherPriorityTaskWoken )
void vTaskGenericNotifyGiveFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, BaseType_t *pxHigherPriorityTaskWoken )
{
TCB_t * pxTCB;
uint8_t ucOriginalNotifyState;
UBaseType_t uxSavedInterruptStatus;
configASSERT( xTaskToNotify );
configASSERT( uxIndexToNotify < configTASK_NOTIFICATION_ARRAY_ENTRIES );
/* RTOS ports that support interrupt nesting have the concept of a
maximum system call (or maximum API call) interrupt priority.
@ -5056,12 +5082,12 @@ TickType_t uxReturn;
uxSavedInterruptStatus = portSET_INTERRUPT_MASK_FROM_ISR();
{
ucOriginalNotifyState = pxTCB->ucNotifyState;
pxTCB->ucNotifyState = taskNOTIFICATION_RECEIVED;
ucOriginalNotifyState = pxTCB->ucNotifyState[ uxIndexToNotify ];
pxTCB->ucNotifyState[ uxIndexToNotify ] = taskNOTIFICATION_RECEIVED;
/* 'Giving' is equivalent to incrementing a count in a counting
semaphore. */
( pxTCB->ulNotifiedValue )++;
( pxTCB->ulNotifiedValue[ uxIndexToNotify ] )++;
traceTASK_NOTIFY_GIVE_FROM_ISR();
@ -5112,20 +5138,22 @@ TickType_t uxReturn;
#if( configUSE_TASK_NOTIFICATIONS == 1 )
BaseType_t xTaskNotifyStateClear( TaskHandle_t xTask )
BaseType_t xTaskGenericNotifyStateClear( TaskHandle_t xTask, UBaseType_t uxIndexToClear )
{
TCB_t *pxTCB;
BaseType_t xReturn;
configASSERT( uxIndexToClear < configTASK_NOTIFICATION_ARRAY_ENTRIES );
/* If null is passed in here then it is the calling task that is having
its notification state cleared. */
pxTCB = prvGetTCBFromHandle( xTask );
taskENTER_CRITICAL();
{
if( pxTCB->ucNotifyState == taskNOTIFICATION_RECEIVED )
if( pxTCB->ucNotifyState[ uxIndexToClear ] == taskNOTIFICATION_RECEIVED )
{
pxTCB->ucNotifyState = taskNOT_WAITING_NOTIFICATION;
pxTCB->ucNotifyState[ uxIndexToClear ] = taskNOT_WAITING_NOTIFICATION;
xReturn = pdPASS;
}
else
@ -5143,7 +5171,7 @@ TickType_t uxReturn;
#if( configUSE_TASK_NOTIFICATIONS == 1 )
uint32_t ulTaskNotifyValueClear( TaskHandle_t xTask, uint32_t ulBitsToClear )
uint32_t ulTaskGenericNotifyValueClear( TaskHandle_t xTask, UBaseType_t uxIndexToClear, uint32_t ulBitsToClear )
{
TCB_t *pxTCB;
uint32_t ulReturn;
@ -5156,8 +5184,8 @@ TickType_t uxReturn;
{
/* Return the notification as it was before the bits were cleared,
then clear the bit mask. */
ulReturn = pxCurrentTCB->ulNotifiedValue;
pxTCB->ulNotifiedValue &= ~ulBitsToClear;
ulReturn = pxCurrentTCB->ulNotifiedValue[ uxIndexToClear ];
pxTCB->ulNotifiedValue[ uxIndexToClear ] &= ~ulBitsToClear;
}
taskEXIT_CRITICAL();