X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=FreeRTOS%2FSource%2Finclude%2Ftask.h;h=672769a9090a56dec89edafd59afe5ca409ad7aa;hb=71ccce588869c5a7643d6bc1e64f4dc6bdae81f2;hp=f9af55730c2e59e6b045d20ae7883627de07023a;hpb=0d859af17f26a3be89530391d736793fc7e25a34;p=freertos diff --git a/FreeRTOS/Source/include/task.h b/FreeRTOS/Source/include/task.h index f9af55730..672769a90 100644 --- a/FreeRTOS/Source/include/task.h +++ b/FreeRTOS/Source/include/task.h @@ -1,60 +1,64 @@ /* - FreeRTOS V8.1.2 - Copyright (C) 2014 Real Time Engineers Ltd. + FreeRTOS V8.2.1 - Copyright (C) 2015 Real Time Engineers Ltd. All rights reserved VISIT http://www.FreeRTOS.org TO ENSURE YOU ARE USING THE LATEST VERSION. - *************************************************************************** - * * - * FreeRTOS provides completely free yet professionally developed, * - * robust, strictly quality controlled, supported, and cross * - * platform software that has become a de facto standard. * - * * - * Help yourself get started quickly and support the FreeRTOS * - * project by purchasing a FreeRTOS tutorial book, reference * - * manual, or both from: http://www.FreeRTOS.org/Documentation * - * * - * Thank you! * - * * - *************************************************************************** - This file is part of the FreeRTOS distribution. FreeRTOS is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License (version 2) as published by the Free Software Foundation >>!AND MODIFIED BY!<< the FreeRTOS exception. + *************************************************************************** >>! NOTE: The modification to the GPL is included to allow you to !<< >>! distribute a combined work that includes FreeRTOS without being !<< >>! obliged to provide the source code for proprietary components !<< >>! outside of the FreeRTOS kernel. !<< + *************************************************************************** FreeRTOS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS - FOR A PARTICULAR PURPOSE. Full license text is available from the following + FOR A PARTICULAR PURPOSE. Full license text is available on the following link: http://www.freertos.org/a00114.html - 1 tab == 4 spaces! - *************************************************************************** * * - * Having a problem? Start by reading the FAQ "My application does * - * not run, what could be wrong?" * + * FreeRTOS provides completely free yet professionally developed, * + * robust, strictly quality controlled, supported, and cross * + * platform software that is more than just the market leader, it * + * is the industry's de facto standard. * * * - * http://www.FreeRTOS.org/FAQHelp.html * + * Help yourself get started quickly while simultaneously helping * + * to support the FreeRTOS project by purchasing a FreeRTOS * + * tutorial book, reference manual, or both: * + * http://www.FreeRTOS.org/Documentation * * * *************************************************************************** - http://www.FreeRTOS.org - Documentation, books, training, latest versions, - license and Real Time Engineers Ltd. contact details. + http://www.FreeRTOS.org/FAQHelp.html - Having a problem? Start by reading + the FAQ page "My application does not run, what could be wrong?". Have you + defined configASSERT()? + + http://www.FreeRTOS.org/support - In return for receiving this top quality + embedded software for free we request you assist our global community by + participating in the support forum. + + http://www.FreeRTOS.org/training - Investing in training allows your team to + be as productive as possible as early as possible. Now you can receive + FreeRTOS training directly from Richard Barry, CEO of Real Time Engineers + Ltd, and the world's leading authority on the world's leading RTOS. http://www.FreeRTOS.org/plus - A selection of FreeRTOS ecosystem products, including FreeRTOS+Trace - an indispensable productivity tool, a DOS compatible FAT file system, and our tiny thread aware UDP/IP stack. - http://www.OpenRTOS.com - Real Time Engineers ltd license FreeRTOS to High - Integrity Systems to sell under the OpenRTOS brand. Low cost OpenRTOS - licenses offer ticketed support, indemnification and middleware. + http://www.FreeRTOS.org/labs - Where new FreeRTOS products go to incubate. + Come and try FreeRTOS+TCP, our new open source TCP/IP stack for FreeRTOS. + + http://www.OpenRTOS.com - Real Time Engineers ltd. license FreeRTOS to High + Integrity Systems ltd. to sell under the OpenRTOS brand. Low cost OpenRTOS + licenses offer ticketed support, indemnification and commercial middleware. http://www.SafeRTOS.com - High Integrity Systems also provide a safety engineered and independently SIL3 certified version for use in safety and @@ -81,10 +85,10 @@ extern "C" { * MACROS AND DEFINITIONS *----------------------------------------------------------*/ -#define tskKERNEL_VERSION_NUMBER "V8.1.2" +#define tskKERNEL_VERSION_NUMBER "V8.2.1" #define tskKERNEL_VERSION_MAJOR 8 -#define tskKERNEL_VERSION_MINOR 1 -#define tskKERNEL_VERSION_BUILD 2 +#define tskKERNEL_VERSION_MINOR 2 +#define tskKERNEL_VERSION_BUILD 1 /** * task. h @@ -117,7 +121,7 @@ typedef enum /* Actions that can be performed when vTaskNotify() is called. */ typedef enum { - eNoAction, /* Notify the task without updating its notify value. */ + eNoAction = 0, /* Notify the task without updating its notify value. */ eSetBits, /* Set bits in the task's notification value. */ eIncrement, /* Increment the task's notification value. */ eSetValueWithOverwrite, /* Set the task's notification value to a specific value even if the previous value has not yet been read by the task. */ @@ -210,6 +214,7 @@ typedef enum * \ingroup SchedulerControl */ #define taskENTER_CRITICAL() portENTER_CRITICAL() +#define taskENTER_CRITICAL_FROM_ISR( x ) portSET_INTERRUPT_MASK_FROM_ISR( x ) /** * task. h @@ -224,7 +229,7 @@ typedef enum * \ingroup SchedulerControl */ #define taskEXIT_CRITICAL() portEXIT_CRITICAL() - +#define taskEXIT_CRITICAL_FROM_ISR() portCLEAR_INTERRUPT_MASK_FROM_ISR() /** * task. h * @@ -1154,6 +1159,18 @@ constant. */ #endif /* configUSE_APPLICATION_TASK_TAG ==1 */ #endif /* ifdef configUSE_APPLICATION_TASK_TAG */ +#if( configNUM_THREAD_LOCAL_STORAGE_POINTERS > 0 ) + + /* Each task contains an array of pointers that is dimensioned by the + configNUM_THREAD_LOCAL_STORAGE_POINTERS setting in FreeRTOSConfig.h. The + kernel does not use the pointers itself, so the application writer can use + the pointers for any purpose they wish. The following two functions are + used to set and query a pointer respectively. */ + void vTaskSetThreadLocalStoragePointer( TaskHandle_t xTaskToSet, BaseType_t xIndex, void *pvValue ); + void *pvTaskGetThreadLocalStoragePointer( TaskHandle_t xTaskToQuery, BaseType_t xIndex ); + +#endif + /** * task.h * 
BaseType_t xTaskCallApplicationTaskHook( TaskHandle_t xTask, void *pvParameter );
@@ -1380,8 +1397,8 @@ void vTaskGetRunTimeStats( char *pcWriteBuffer ) PRIVILEGED_FUNCTION; /*lint !e9 * task. h * 
BaseType_t xTaskNotify( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction );
* - * configUSE_TASK_NOTIFICATIONS must be defined as 1 for this function to be - * available. + * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this + * function to be available. * * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private * "notification value", which is a 32-bit unsigned integer (uint32_t). @@ -1403,14 +1420,11 @@ void vTaskGetRunTimeStats( char *pcWriteBuffer ) PRIVILEGED_FUNCTION; /*lint !e9 * (unblocked) and the notification cleared. * * A task can use xTaskNotifyWait() to [optionally] block to wait for a - * notification to be pending, or xTaskNotifyTake() to [optionally] block + * 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. * - * See http://www.FreeRTOS.org/RTOS_task_notifications.html for details of when - * it is best to use a task notification to send an event to a task compared to - * when it is best to use an intermediary object (such as a queue, semaphore, - * mutex or event group) to send an event to a task. + * See http://www.FreeRTOS.org/RTOS-task-notifications.html for details. * * @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 @@ -1448,20 +1462,26 @@ void vTaskGetRunTimeStats( char *pcWriteBuffer ) PRIVILEGED_FUNCTION; /*lint !e9 * updated. ulValue is not used and xTaskNotify() always returns pdPASS in * this case. * + * pulPreviousNotificationValue - + * Can be used to pass out the subject task's notification value before any + * bits are modified by the notify function. + * * @return Dependent on the value of eAction. See the description of the * eAction parameter. * * \defgroup xTaskNotify xTaskNotify * \ingroup TaskNotifications */ -BaseType_t xTaskNotify( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction ); +BaseType_t xTaskGenericNotify( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue ); +#define xTaskNotify( xTaskToNotify, ulValue, eAction ) xTaskGenericNotify( ( xTaskToNotify ), ( ulValue ), ( eAction ), NULL ) +#define xTaskNotifyAndQuery( xTaskToNotify, ulValue, eAction, pulPreviousNotifyValue ) xTaskGenericNotify( ( xTaskToNotify ), ( ulValue ), ( eAction ), ( pulPreviousNotifyValue ) ) /** * task. h * 
BaseType_t xTaskNotifyFromISR( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, BaseType_t *pxHigherPriorityTaskWoken );
* - * configUSE_TASK_NOTIFICATIONS must be defined as 1 for this function to be - * available. + * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this + * function to be available. * * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private * "notification value", which is a 32-bit unsigned integer (uint32_t). @@ -1486,14 +1506,11 @@ BaseType_t xTaskNotify( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAct * (unblocked) and the notification cleared. * * A task can use xTaskNotifyWait() to [optionally] block to wait for a - * notification to be pending, or xTaskNotifyTake() to [optionally] block + * 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. * - * See http://www.FreeRTOS.org/RTOS_task_notifications.html for details of when - * it is best to use a task notification to send an event to a task compared to - * when it is best to use an intermediary object (such as a queue, semaphore, - * mutex or event group) to send an event to a task. + * See http://www.FreeRTOS.org/RTOS-task-notifications.html for details. * * @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 @@ -1550,10 +1567,10 @@ BaseType_t xTaskNotifyFromISR( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNo /** * task. h - * 
BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry, BaseType_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait );
+ * 
BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait );
* - * configUSE_TASK_NOTIFICATIONS must be defined as 1 for this function to be - * available. + * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this + * function to be available. * * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private * "notification value", which is a 32-bit unsigned integer (uint32_t). @@ -1575,14 +1592,11 @@ BaseType_t xTaskNotifyFromISR( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNo * (unblocked) and the notification cleared. * * A task can use xTaskNotifyWait() to [optionally] block to wait for a - * notification to be pending, or xTaskNotifyTake() to [optionally] block + * 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. * - * See http://www.FreeRTOS.org/RTOS_task_notifications.html for details of when - * it is best to use a task notification to send an event to a task compared to - * when it is best to use an intermediary object (such as a queue, semaphore, - * mutex or event group) to send an event to a task. + * See http://www.FreeRTOS.org/RTOS-task-notifications.html for details. * * @param ulBitsToClearOnEntry Bits that are set in ulBitsToClearOnEntry value * will be cleared in the calling task's notification value before the task @@ -1624,14 +1638,14 @@ BaseType_t xTaskNotifyFromISR( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNo * \defgroup xTaskNotifyWait xTaskNotifyWait * \ingroup TaskNotifications */ -BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry, BaseType_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait ); +BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait ); /** * task. h - * 
BaseType_t xTaskNotifyGive( TaskHandle_t xTaskHandle, BaseType_t *pxHigherPriorityTaskWoken );
+ * 
BaseType_t xTaskNotifyGive( TaskHandle_t xTaskToNotify );

  *
- * configUSE_TASK_NOTIFICATIONS must be defined as 1 for this macro to be
- * available.
+ * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this macro
+ * to be available.
  *
  * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private
  * "notification value", which is a 32-bit unsigned integer (uint32_t).
@@ -1657,7 +1671,7 @@ BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry, BaseType_t ulBitsToCl
  * using the ulTaskNotificationTake() API function rather than the
  * xTaskNotifyWait() API function.
  *
- * See http://www.FreeRTOS.org/RTOS_task_notifications.html for more details.
+ * See http://www.FreeRTOS.org/RTOS-task-notifications.html for more details.
  *
  * @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
@@ -1674,10 +1688,10 @@ BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry, BaseType_t ulBitsToCl
 
 /**
  * task. h
- * 
BaseType_t xTaskNotifyGiveFromISR( TaskHandle_t xTaskHandle, BaseType_t *pxHigherPriorityTaskWoken );
+ * 
void vTaskNotifyGiveFromISR( TaskHandle_t xTaskHandle, BaseType_t *pxHigherPriorityTaskWoken );
  *
- * configUSE_TASK_NOTIFICATIONS must be defined as 1 for this macro to be
- * available.
+ * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this macro
+ * to be available.
  *
  * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private
  * "notification value", which is a 32-bit unsigned integer (uint32_t).
@@ -1695,47 +1709,44 @@ BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry, BaseType_t ulBitsToCl
  * task notifications can be used to send data to a task, or be used as light
  * weight and fast binary or counting semaphores.
  *
- * xTaskNotifyGiveFromISR() is a helper macro intended for use when task
- * notifications are used as light weight and faster binary or counting
- * semaphore equivalents.  Actual FreeRTOS semaphores are given from an ISR
- * using the xSemaphoreGiveFromISR() API function, the equivalent action that
- * instead uses a task notification is xTaskNotifyGiveFromISR().
+ * vTaskNotifyGiveFromISR() is intended for use when task notifications are
+ * used as light weight and faster binary or counting semaphore equivalents.
+ * Actual FreeRTOS semaphores are given from an ISR using the
+ * xSemaphoreGiveFromISR() API function, the equivalent action that instead uses
+ * a task notification is vTaskNotifyGiveFromISR().
  *
  * When task notifications are being used as a binary or counting semaphore
  * equivalent then the task being notified should wait for the notification
  * using the ulTaskNotificationTake() API function rather than the
  * xTaskNotifyWait() API function.
  *
- * See http://www.FreeRTOS.org/RTOS_task_notifications.html for more details.
+ * See http://www.FreeRTOS.org/RTOS-task-notifications.html for more details.
  *
  * @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, and the handle of the currently running task can be obtained by calling
  * xTaskGetCurrentTaskHandle().
  *
- * @param pxHigherPriorityTaskWoken  xTaskNotifyGiveFromISR() will set
+ * @param pxHigherPriorityTaskWoken  vTaskNotifyGiveFromISR() will set
  * *pxHigherPriorityTaskWoken to pdTRUE if sending the notification caused the
  * task to which the notification was sent to leave the Blocked state, and the
  * unblocked task has a priority higher than the currently running task.  If
- * xTaskNotifyGiveFromISR() sets this value to pdTRUE then a context switch
+ * vTaskNotifyGiveFromISR() sets this value to pdTRUE then a context switch
  * should be requested before the interrupt is exited.  How a context switch is
  * requested from an ISR is dependent on the port - see the documentation page
  * for the port in use.
  *
- * @return xTaskNotifyGiveFromISR() is a macro that calls xTaskNotifyFromISR()
- * with the eAction parameter set to eIncrement - so pdPASS is always returned.
- *
  * \defgroup xTaskNotifyWait xTaskNotifyWait
  * \ingroup TaskNotifications
  */
-BaseType_t xTaskNotifyGiveFromISR( TaskHandle_t xTaskToNotify, BaseType_t *pxHigherPriorityTaskWoken );
+void vTaskNotifyGiveFromISR( TaskHandle_t xTaskToNotify, BaseType_t *pxHigherPriorityTaskWoken );
 
 /**
  * task. h
  * 
uint32_t ulTaskNotifyTake( BaseType_t xClearCountOnExit, TickType_t xTicksToWait );

  *
- * configUSE_TASK_NOTIFICATIONS must be defined as 1 for this function to be
- * available.
+ * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this
+ * function to be available.
  *
  * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private
  * "notification value", which is a 32-bit unsigned integer (uint32_t).
@@ -1754,30 +1765,27 @@ BaseType_t xTaskNotifyGiveFromISR( TaskHandle_t xTaskToNotify, BaseType_t *pxHig
  * faster and lighter weight binary or counting semaphore alternative.  Actual
  * FreeRTOS semaphores are taken using the xSemaphoreTake() API function, the
  * equivalent action that instead uses a task notification is
- * xTaskNotifyTake().
+ * ulTaskNotifyTake().
  *
  * When a task is using its notification value as a binary or counting semaphore
  * other tasks should send notifications to it using the xTaskNotifyGive()
  * macro, or xTaskNotify() function with the eAction parameter set to
  * eIncrement.
  *
- * xTaskNotifyTake() can either clear the task's notification value to
+ * ulTaskNotifyTake() can either clear the task's notification value to
  * zero on exit, in which case the notification value acts like a binary
  * semaphore, or decrement the task's notification value on exit, in which case
  * the notification value acts like a counting semaphore.
  *
- * A task can use xTaskNotifyTake() to [optionally] block to wait for a
- * the tasks notification value to be non-zero.  The task does not consume any
+ * A task can use ulTaskNotifyTake() to [optionally] block to wait for a
+ * the task's notification value to be non-zero.  The task does not consume any
  * CPU time while it is in the Blocked state.
  *
  * Where as xTaskNotifyWait() will return when a notification is pending,
- * xTaskNotifyTake() will return when the task's notification value is
+ * ulTaskNotifyTake() will return when the task's notification value is
  * not zero.
  *
- * See http://www.FreeRTOS.org/RTOS_task_notifications.html for details of when
- * it is best to use a task notification to send an event to a task compared to
- * when it is best to use an intermediary object (such as a queue, semaphore,
- * mutex or event group) to send an event to a task.
+ * See http://www.FreeRTOS.org/RTOS-task-notifications.html for details.
  *
  * @param xClearCountOnExit if xClearCountOnExit is pdFALSE then the task's
  * notification value is decremented when the function exits.  In this way the
@@ -1789,7 +1797,7 @@ BaseType_t xTaskNotifyGiveFromISR( TaskHandle_t xTaskToNotify, BaseType_t *pxHig
  * @param xTicksToWait The maximum amount of time that the task should wait in
  * the Blocked state for the task's notification value to be greater than zero,
  * should the count not already be greater than zero when
- * xTaskNotifyTake() was called.  The task will not consume any processing
+ * ulTaskNotifyTake() was called.  The task will not consume any processing
  * time while it is in the Blocked state.  This is specified in kernel ticks,
  * the macro pdMS_TO_TICSK( value_in_ms ) can be used to convert a time
  * specified in milliseconds to a time specified in ticks.