]> git.sur5r.net Git - freertos/blobdiff - Source/include/task.h
Remove unnecessary ';' characters from a couple of macro definitions in the IAR MSP43...
[freertos] / Source / include / task.h
index b3b31d063868e0cec6223aca26dd502e6bed2426..0c9f70fd1b4e4bfd761a6579b233fdd8412edae4 100644 (file)
@@ -1,41 +1,46 @@
 /*\r
-    FreeRTOS V6.0.0 - Copyright (C) 2009 Real Time Engineers Ltd.\r
+    FreeRTOS V6.1.0 - Copyright (C) 2010 Real Time Engineers Ltd.\r
+\r
+    ***************************************************************************\r
+    *                                                                         *\r
+    * If you are:                                                             *\r
+    *                                                                         *\r
+    *    + New to FreeRTOS,                                                   *\r
+    *    + Wanting to learn FreeRTOS or multitasking in general quickly       *\r
+    *    + Looking for basic training,                                        *\r
+    *    + Wanting to improve your FreeRTOS skills and productivity           *\r
+    *                                                                         *\r
+    * then take a look at the FreeRTOS books - available as PDF or paperback  *\r
+    *                                                                         *\r
+    *        "Using the FreeRTOS Real Time Kernel - a Practical Guide"        *\r
+    *                  http://www.FreeRTOS.org/Documentation                  *\r
+    *                                                                         *\r
+    * A pdf reference manual is also available.  Both are usually delivered   *\r
+    * to your inbox within 20 minutes to two hours when purchased between 8am *\r
+    * and 8pm GMT (although please allow up to 24 hours in case of            *\r
+    * exceptional circumstances).  Thank you for your support!                *\r
+    *                                                                         *\r
+    ***************************************************************************\r
 \r
     This file is part of the FreeRTOS distribution.\r
 \r
-    FreeRTOS is free software; you can redistribute it and/or modify it    under\r
+    FreeRTOS is free software; you can redistribute it and/or modify it under\r
     the terms of the GNU General Public License (version 2) as published by the\r
-    Free Software Foundation and modified by the FreeRTOS exception.\r
-    **NOTE** The exception to the GPL is included to allow you to distribute a\r
-    combined work that includes FreeRTOS without being obliged to provide the\r
+    Free Software Foundation AND MODIFIED BY the FreeRTOS exception.\r
+    ***NOTE*** The exception to the GPL is included to allow you to distribute\r
+    combined work that includes FreeRTOS without being obliged to provide the\r
     source code for proprietary components outside of the FreeRTOS kernel.\r
-    Alternative commercial license and support terms are also available upon\r
-    request.  See the licensing section of http://www.FreeRTOS.org for full\r
-    license details.\r
-\r
-    FreeRTOS is distributed in the hope that it will be useful,    but WITHOUT\r
+    FreeRTOS is distributed in the hope that it will be useful, but WITHOUT\r
     ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or\r
     FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for\r
-    more details.\r
-\r
-    You should have received a copy of the GNU General Public License along\r
-    with FreeRTOS; if not, write to the Free Software Foundation, Inc., 59\r
-    Temple Place, Suite 330, Boston, MA  02111-1307  USA.\r
-\r
-\r
-    ***************************************************************************\r
-    *                                                                         *\r
-    * The FreeRTOS eBook and reference manual are available to purchase for a *\r
-    * small fee. Help yourself get started quickly while also helping the     *\r
-    * FreeRTOS project! See http://www.FreeRTOS.org/Documentation for details *\r
-    *                                                                         *\r
-    ***************************************************************************\r
+    more details. You should have received a copy of the GNU General Public\r
+    License and the FreeRTOS license exception along with FreeRTOS; if not it\r
+    can be viewed here: http://www.freertos.org/a00114.html and also obtained\r
+    by writing to Richard Barry, contact details for whom are available on the\r
+    FreeRTOS WEB site.\r
 \r
     1 tab == 4 spaces!\r
 \r
-    Please ensure to read the configuration and relevant port sections of the\r
-    online documentation.\r
-\r
     http://www.FreeRTOS.org - Documentation, latest information, license and\r
     contact details.\r
 \r
@@ -48,7 +53,7 @@
 \r
 \r
 #ifndef INC_FREERTOS_H\r
-       #error "#include FreeRTOS.h" must appear in source files before "#include task.h"\r
+       #error "include FreeRTOS.h must appear in source files before include task.h"\r
 #endif\r
 \r
 \r
@@ -67,7 +72,7 @@ extern "C" {
  * MACROS AND DEFINITIONS\r
  *----------------------------------------------------------*/\r
 \r
-#define tskKERNEL_VERSION_NUMBER "V6.0.0"\r
+#define tskKERNEL_VERSION_NUMBER "V6.1.0"\r
 \r
 /**\r
  * task. h\r
@@ -201,10 +206,10 @@ typedef struct xTASK_PARAMTERS
                                                  );</pre>\r
  *\r
  * Create a new task and add it to the list of tasks that are ready to run.\r
- * \r
+ *\r
  * xTaskCreate() can only be used to create a task that has unrestricted\r
  * access to the entire microcontroller memory map.  Systems that include MPU\r
- * support can alternatively create an MPU constrained task using \r
+ * support can alternatively create an MPU constrained task using\r
  * xTaskCreateRestricted().\r
  *\r
  * @param pvTaskCode Pointer to the task entry function.  Tasks\r
@@ -269,7 +274,7 @@ typedef struct xTASK_PARAMTERS
 /**\r
  * task. h\r
  *<pre>\r
- portBASE_TYPE xTaskCreateRestricted( xTaskParameters *pxTaskDefinition, xTaskHandle pxCreatedTask );</pre>\r
+ portBASE_TYPE xTaskCreateRestricted( xTaskParameters *pxTaskDefinition, xTaskHandle *pxCreatedTask );</pre>\r
  *\r
  * xTaskCreateRestricted() should only be used in systems that include an MPU\r
  * implementation.\r
@@ -280,13 +285,9 @@ typedef struct xTASK_PARAMTERS
  *\r
  * @param pxTaskDefinition Pointer to a structure that contains a member\r
  * for each of the normal xTaskCreate() parameters (see the xTaskCreate() API\r
- * documentation) plus an optional stack buffer and the memory region \r
+ * documentation) plus an optional stack buffer and the memory region\r
  * definitions.\r
  *\r
- * @param pcName A descriptive name for the task.  This is mainly used to\r
- * facilitate debugging.  Max length defined by tskMAX_TASK_NAME_LEN - default\r
- * is 16.\r
- *\r
  * @param pxCreatedTask Used to pass back a handle by which the created task\r
  * can be referenced.\r
  *\r
@@ -347,7 +348,7 @@ xTaskHandle xHandle;
  * Memory regions are assigned to a restricted task when the task is created by\r
  * a call to xTaskCreateRestricted().  These regions can be redefined using\r
  * vTaskAllocateMPURegions().\r
- * \r
+ *\r
  * @param xTask The handle of the task being updated.\r
  *\r
  * @param xRegions A pointer to an xMemoryRegion structure that contains the\r
@@ -370,7 +371,7 @@ static const xMemoryRegion xAltRegions[ portNUM_CONFIGURABLE_REGIONS ] =
 void vATask( void *pvParameters )\r
 {\r
        // This task was created such that it has access to certain regions of\r
-       // memory as defined by the MPU configuration.  At some point it is \r
+       // memory as defined by the MPU configuration.  At some point it is\r
        // desired that these MPU regions are replaced with that defined in the\r
        // xAltRegions const struct above.  Use a call to vTaskAllocateMPURegions()\r
        // for this purpose.  NULL is used as the task handle to indicate that this\r
@@ -962,7 +963,7 @@ signed portBASE_TYPE xTaskIsTaskSuspended( xTaskHandle xTask ) PRIVILEGED_FUNCTI
 \r
 /**\r
  * task. h\r
- * <PRE>volatile portTickType xTaskGetTickCount( void );</PRE>\r
+ * <PRE>portTickType xTaskGetTickCount( void );</PRE>\r
  *\r
  * @return The count of ticks since vTaskStartScheduler was called.\r
  *\r
@@ -971,6 +972,22 @@ signed portBASE_TYPE xTaskIsTaskSuspended( xTaskHandle xTask ) PRIVILEGED_FUNCTI
  */\r
 portTickType xTaskGetTickCount( void ) PRIVILEGED_FUNCTION;\r
 \r
+/**\r
+ * task. h\r
+ * <PRE>portTickType xTaskGetTickCountFromISR( void );</PRE>\r
+ *\r
+ * @return The count of ticks since vTaskStartScheduler was called.\r
+ *\r
+ * This is a version of xTaskGetTickCount() that is safe to be called from an\r
+ * ISR - provided that portTickType is the natural word size of the\r
+ * microcontroller being used or interrupt nesting is either not supported or\r
+ * not being used.\r
+ *\r
+ * \page xTaskGetTickCount xTaskGetTickCount\r
+ * \ingroup TaskUtils\r
+ */\r
+portTickType xTaskGetTickCountFromISR( void ) PRIVILEGED_FUNCTION;\r
+\r
 /**\r
  * task. h\r
  * <PRE>unsigned short uxTaskGetNumberOfTasks( void );</PRE>\r
@@ -1085,9 +1102,9 @@ unsigned long ulTaskEndTrace( void ) PRIVILEGED_FUNCTION;
  * this function to be available.\r
  *\r
  * Returns the high water mark of the stack associated with xTask.  That is,\r
- * the minimum free stack space there has been (in bytes) since the task\r
- * started.  The smaller the returned number the closer the task has come\r
- * to overflowing its stack.\r
+ * the minimum free stack space there has been (in words, so on a 32 bit machine\r
+ * a value of 1 means 4 bytes) since the task started.  The smaller the returned \r
+ * number the closer the task has come to overflowing its stack.\r
  *\r
  * @param xTask Handle of the task associated with the stack to be checked.\r
  * Set xTask to NULL to check the stack of the calling task.\r
@@ -1097,23 +1114,33 @@ unsigned long ulTaskEndTrace( void ) PRIVILEGED_FUNCTION;
  */\r
 unsigned portBASE_TYPE uxTaskGetStackHighWaterMark( xTaskHandle xTask ) PRIVILEGED_FUNCTION;\r
 \r
-/**\r
- * task.h\r
- * <pre>void vTaskSetApplicationTaskTag( xTaskHandle xTask, pdTASK_HOOK_CODE pxHookFunction );</pre>\r
- *\r
- * Sets pxHookFunction to be the task hook function used by the task xTask.\r
- * Passing xTask as NULL has the effect of setting the calling tasks hook\r
- * function.\r
- */\r
-void vTaskSetApplicationTaskTag( xTaskHandle xTask, pdTASK_HOOK_CODE pxHookFunction ) PRIVILEGED_FUNCTION;\r
-\r
-/**\r
- * task.h\r
- * <pre>void xTaskGetApplicationTaskTag( xTaskHandle xTask );</pre>\r
- *\r
- * Returns the pxHookFunction value assigned to the task xTask.\r
- */\r
-pdTASK_HOOK_CODE xTaskGetApplicationTaskTag( xTaskHandle xTask ) PRIVILEGED_FUNCTION;\r
+/* When using trace macros it is sometimes necessary to include tasks.h before\r
+FreeRTOS.h.  When this is done pdTASK_HOOK_CODE will not yet have been defined,\r
+so the following two prototypes will cause a compilation error.  This can be\r
+fixed by simply guarding against the inclusion of these two prototypes unless\r
+they are explicitly required by the configUSE_APPLICATION_TASK_TAG configuration\r
+constant. */\r
+#ifdef configUSE_APPLICATION_TASK_TAG\r
+       #if configUSE_APPLICATION_TASK_TAG == 1\r
+               /**\r
+                * task.h\r
+                * <pre>void vTaskSetApplicationTaskTag( xTaskHandle xTask, pdTASK_HOOK_CODE pxHookFunction );</pre>\r
+                *\r
+                * Sets pxHookFunction to be the task hook function used by the task xTask.\r
+                * Passing xTask as NULL has the effect of setting the calling tasks hook\r
+                * function.\r
+                */\r
+               void vTaskSetApplicationTaskTag( xTaskHandle xTask, pdTASK_HOOK_CODE pxHookFunction ) PRIVILEGED_FUNCTION;\r
+\r
+               /**\r
+                * task.h\r
+                * <pre>void xTaskGetApplicationTaskTag( xTaskHandle xTask );</pre>\r
+                *\r
+                * Returns the pxHookFunction value assigned to the task xTask.\r
+                */\r
+               pdTASK_HOOK_CODE xTaskGetApplicationTaskTag( xTaskHandle xTask ) PRIVILEGED_FUNCTION;\r
+       #endif /* configUSE_APPLICATION_TASK_TAG ==1 */\r
+#endif /* ifdef configUSE_APPLICATION_TASK_TAG */\r
 \r
 /**\r
  * task.h\r
@@ -1249,7 +1276,7 @@ void vTaskPriorityDisinherit( xTaskHandle * const pxMutexHolder ) PRIVILEGED_FUN
 \r
 /*\r
  * Generic version of the task creation function which is in turn called by the\r
- * xTaskCreate() and xTaskCreateProtected() macros.\r
+ * xTaskCreate() and xTaskCreateRestricted() macros.\r
  */\r
 signed portBASE_TYPE xTaskGenericCreate( pdTASK_CODE pvTaskCode, const signed char * const pcName, unsigned short usStackDepth, void *pvParameters, unsigned portBASE_TYPE uxPriority, xTaskHandle *pxCreatedTask, portSTACK_TYPE *puxStackBuffer, const xMemoryRegion * const xRegions ) PRIVILEGED_FUNCTION;\r
 \r