git.sur5r.net Git - freertos/blob - Source/include/task.h

   1 /*\r
   2         FreeRTOS.org V5.1.2 - Copyright (C) 2003-2009 Richard Barry.\r
   3 \r
   4         This file is part of the FreeRTOS.org distribution.\r
   5 \r
   6         FreeRTOS.org is free software; you can redistribute it and/or modify\r
   7         it under the terms of the GNU General Public License as published by\r
   8         the Free Software Foundation; either version 2 of the License, or\r
   9         (at your option) any later version.\r
  10 \r
  11         FreeRTOS.org is distributed in the hope that it will be useful,\r
  12         but WITHOUT ANY WARRANTY; without even the implied warranty of\r
  13         MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\r
  14         GNU General Public License for more details.\r
  15 \r
  16         You should have received a copy of the GNU General Public License\r
  17         along with FreeRTOS.org; if not, write to the Free Software\r
  18         Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA\r
  19 \r
  20         A special exception to the GPL can be applied should you wish to distribute\r
  21         a combined work that includes FreeRTOS.org, without being obliged to provide\r
  22         the source code for any proprietary components.  See the licensing section\r
  23         of http://www.FreeRTOS.org for full details of how and when the exception\r
  24         can be applied.\r
  25 \r
  26     ***************************************************************************\r
  27     ***************************************************************************\r
  28     *                                                                         *\r
  29     * Get the FreeRTOS eBook!  See http://www.FreeRTOS.org/Documentation      *\r
  30         *                                                                         *\r
  31         * This is a concise, step by step, 'hands on' guide that describes both   *\r
  32         * general multitasking concepts and FreeRTOS specifics. It presents and   *\r
  33         * explains numerous examples that are written using the FreeRTOS API.     *\r
  34         * Full source code for all the examples is provided in an accompanying    *\r
  35         * .zip file.                                                              *\r
  36     *                                                                         *\r
  37     ***************************************************************************\r
  38     ***************************************************************************\r
  39 \r
  40         Please ensure to read the configuration and relevant port sections of the\r
  41         online documentation.\r
  42 \r
  43         http://www.FreeRTOS.org - Documentation, latest information, license and \r
  44         contact details.\r
  45 \r
  46         http://www.SafeRTOS.com - A version that is certified for use in safety \r
  47         critical systems.\r
  48 \r
  49         http://www.OpenRTOS.com - Commercial support, development, porting, \r
  50         licensing and training services.\r
  51 */\r
  52 \r
  53 \r
  54 #ifndef INC_FREERTOS_H\r
  55         #error "#include FreeRTOS.h" must appear in source files before "#include task.h"\r
  56 #endif\r
  57 \r
  58 \r
  59 \r
  60 #ifndef TASK_H\r
  61 #define TASK_H\r
  62 \r
  63 #include "portable.h"\r
  64 #include "list.h"\r
  65 \r
  66 #ifdef __cplusplus\r
  67 extern "C" {\r
  68 #endif\r
  69 /*-----------------------------------------------------------\r
  70  * MACROS AND DEFINITIONS\r
  71  *----------------------------------------------------------*/\r
  72 \r
  73 #define tskKERNEL_VERSION_NUMBER "V5.1.0"\r
  74 \r
  75 /**\r
  76  * task. h\r
  77  *\r
  78  * Type by which tasks are referenced.  For example, a call to xTaskCreate\r
  79  * returns (via a pointer parameter) an xTaskHandle variable that can then\r
  80  * be used as a parameter to vTaskDelete to delete the task.\r
  81  *\r
  82  * \page xTaskHandle xTaskHandle\r
  83  * \ingroup Tasks\r
  84  */\r
  85 typedef void * xTaskHandle;\r
  86 \r
  87 /*\r
  88  * Used internally only.\r
  89  */\r
  90 typedef struct xTIME_OUT\r
  91 {\r
  92     portBASE_TYPE xOverflowCount;\r
  93     portTickType  xTimeOnEntering;\r
  94 } xTimeOutType;\r
  95 \r
  96 /*\r
  97  * Defines the priority used by the idle task.  This must not be modified.\r
  98  *\r
  99  * \ingroup TaskUtils\r
 100  */\r
 101 #define tskIDLE_PRIORITY                        ( ( unsigned portBASE_TYPE ) 0 )\r
 102 \r
 103 /**\r
 104  * task. h\r
 105  *\r
 106  * Macro for forcing a context switch.\r
 107  *\r
 108  * \page taskYIELD taskYIELD\r
 109  * \ingroup SchedulerControl\r
 110  */\r
 111 #define taskYIELD()                                     portYIELD()\r
 112 \r
 113 /**\r
 114  * task. h\r
 115  *\r
 116  * Macro to mark the start of a critical code region.  Preemptive context\r
 117  * switches cannot occur when in a critical region.\r
 118  *\r
 119  * NOTE: This may alter the stack (depending on the portable implementation)\r
 120  * so must be used with care!\r
 121  *\r
 122  * \page taskENTER_CRITICAL taskENTER_CRITICAL\r
 123  * \ingroup SchedulerControl\r
 124  */\r
 125 #define taskENTER_CRITICAL()            portENTER_CRITICAL()\r
 126 \r
 127 /**\r
 128  * task. h\r
 129  *\r
 130  * Macro to mark the end of a critical code region.  Preemptive context\r
 131  * switches cannot occur when in a critical region.\r
 132  *\r
 133  * NOTE: This may alter the stack (depending on the portable implementation)\r
 134  * so must be used with care!\r
 135  *\r
 136  * \page taskEXIT_CRITICAL taskEXIT_CRITICAL\r
 137  * \ingroup SchedulerControl\r
 138  */\r
 139 #define taskEXIT_CRITICAL()                     portEXIT_CRITICAL()\r
 140 \r
 141 /**\r
 142  * task. h\r
 143  *\r
 144  * Macro to disable all maskable interrupts.\r
 145  *\r
 146  * \page taskDISABLE_INTERRUPTS taskDISABLE_INTERRUPTS\r
 147  * \ingroup SchedulerControl\r
 148  */\r
 149 #define taskDISABLE_INTERRUPTS()        portDISABLE_INTERRUPTS()\r
 150 \r
 151 /**\r
 152  * task. h\r
 153  *\r
 154  * Macro to enable microcontroller interrupts.\r
 155  *\r
 156  * \page taskENABLE_INTERRUPTS taskENABLE_INTERRUPTS\r
 157  * \ingroup SchedulerControl\r
 158  */\r
 159 #define taskENABLE_INTERRUPTS()         portENABLE_INTERRUPTS()\r
 160 \r
 161 /* Definitions returned by xTaskGetSchedulerState(). */\r
 162 #define taskSCHEDULER_NOT_STARTED       0\r
 163 #define taskSCHEDULER_RUNNING           1\r
 164 #define taskSCHEDULER_SUSPENDED         2\r
 165 \r
 166 /*-----------------------------------------------------------\r
 167  * TASK CREATION API\r
 168  *----------------------------------------------------------*/\r
 169 \r
 170 /**\r
 171  * task. h\r
 172  *<pre>\r
 173  portBASE_TYPE xTaskCreate(\r
 174                               pdTASK_CODE pvTaskCode,\r
 175                               const portCHAR * const pcName,\r
 176                               unsigned portSHORT usStackDepth,\r
 177                               void *pvParameters,\r
 178                               unsigned portBASE_TYPE uxPriority,\r
 179                               xTaskHandle *pvCreatedTask\r
 180                           );</pre>\r
 181  *\r
 182  * Create a new task and add it to the list of tasks that are ready to run.\r
 183  *\r
 184  * @param pvTaskCode Pointer to the task entry function.  Tasks\r
 185  * must be implemented to never return (i.e. continuous loop).\r
 186  *\r
 187  * @param pcName A descriptive name for the task.  This is mainly used to\r
 188  * facilitate debugging.  Max length defined by tskMAX_TASK_NAME_LEN - default\r
 189  * is 16.\r
 190  *\r
 191  * @param usStackDepth The size of the task stack specified as the number of\r
 192  * variables the stack can hold - not the number of bytes.  For example, if\r
 193  * the stack is 16 bits wide and usStackDepth is defined as 100, 200 bytes\r
 194  * will be allocated for stack storage.\r
 195  *\r
 196  * @param pvParameters Pointer that will be used as the parameter for the task\r
 197  * being created.\r
 198  *\r
 199  * @param uxPriority The priority at which the task should run.\r
 200  *\r
 201  * @param pvCreatedTask Used to pass back a handle by which the created task\r
 202  * can be referenced.\r
 203  *\r
 204  * @return pdPASS if the task was successfully created and added to a ready\r
 205  * list, otherwise an error code defined in the file errors. h\r
 206  *\r
 207  * Example usage:\r
 208    <pre>\r
 209  // Task to be created.\r
 210  void vTaskCode( void * pvParameters )\r
 211  {\r
 212      for( ;; )\r
 213      {\r
 214          // Task code goes here.\r
 215      }\r
 216  }\r
 217 \r
 218  // Function that creates a task.\r
 219  void vOtherFunction( void )\r
 220  {\r
 221  static unsigned char ucParameterToPass;\r
 222  xTaskHandle xHandle;\r
 223                 \r
 224      // Create the task, storing the handle.  Note that the passed parameter ucParameterToPass\r
 225      // must exist for the lifetime of the task, so in this case is declared static.  If it was just an\r
 226      // an automatic stack variable it might no longer exist, or at least have been corrupted, by the time\r
 227      // the new time attempts to access it.\r
 228      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, &ucParameterToPass, tskIDLE_PRIORITY, &xHandle );\r
 229                 \r
 230      // Use the handle to delete the task.\r
 231      vTaskDelete( xHandle );\r
 232  }\r
 233    </pre>\r
 234  * \defgroup xTaskCreate xTaskCreate\r
 235  * \ingroup Tasks\r
 236  */\r
 237 signed portBASE_TYPE xTaskCreate( pdTASK_CODE pvTaskCode, const signed portCHAR * const pcName, unsigned portSHORT usStackDepth, void *pvParameters, unsigned portBASE_TYPE uxPriority, xTaskHandle *pvCreatedTask );\r
 238 \r
 239 /**\r
 240  * task. h\r
 241  * <pre>void vTaskDelete( xTaskHandle pxTask );</pre>\r
 242  *\r
 243  * INCLUDE_vTaskDelete must be defined as 1 for this function to be available.\r
 244  * See the configuration section for more information.\r
 245  *\r
 246  * Remove a task from the RTOS real time kernels management.  The task being\r
 247  * deleted will be removed from all ready, blocked, suspended and event lists.\r
 248  *\r
 249  * NOTE:  The idle task is responsible for freeing the kernel allocated\r
 250  * memory from tasks that have been deleted.  It is therefore important that\r
 251  * the idle task is not starved of microcontroller processing time if your\r
 252  * application makes any calls to vTaskDelete ().  Memory allocated by the\r
 253  * task code is not automatically freed, and should be freed before the task\r
 254  * is deleted.\r
 255  *\r
 256  * See the demo application file death.c for sample code that utilises\r
 257  * vTaskDelete ().\r
 258  *\r
 259  * @param pxTask The handle of the task to be deleted.  Passing NULL will\r
 260  * cause the calling task to be deleted.\r
 261  *\r
 262  * Example usage:\r
 263    <pre>\r
 264  void vOtherFunction( void )\r
 265  {\r
 266  xTaskHandle xHandle;\r
 267                 \r
 268      // Create the task, storing the handle.\r
 269      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );\r
 270                 \r
 271      // Use the handle to delete the task.\r
 272      vTaskDelete( xHandle );\r
 273  }\r
 274    </pre>\r
 275  * \defgroup vTaskDelete vTaskDelete\r
 276  * \ingroup Tasks\r
 277  */\r
 278 void vTaskDelete( xTaskHandle pxTask );\r
 279 \r
 280 \r
 281 /*-----------------------------------------------------------\r
 282  * TASK CONTROL API\r
 283  *----------------------------------------------------------*/\r
 284 \r
 285 /**\r
 286  * task. h\r
 287  * <pre>void vTaskDelay( portTickType xTicksToDelay );</pre>\r
 288  *\r
 289  * Delay a task for a given number of ticks.  The actual time that the\r
 290  * task remains blocked depends on the tick rate.  The constant\r
 291  * portTICK_RATE_MS can be used to calculate real time from the tick\r
 292  * rate - with the resolution of one tick period.\r
 293  *\r
 294  * INCLUDE_vTaskDelay must be defined as 1 for this function to be available.\r
 295  * See the configuration section for more information.\r
 296  *\r
 297  *\r
 298  * vTaskDelay() specifies a time at which the task wishes to unblock relative to\r
 299  * the time at which vTaskDelay() is called.  For example, specifying a block \r
 300  * period of 100 ticks will cause the task to unblock 100 ticks after \r
 301  * vTaskDelay() is called.  vTaskDelay() does not therefore provide a good method\r
 302  * of controlling the frequency of a cyclical task as the path taken through the \r
 303  * code, as well as other task and interrupt activity, will effect the frequency \r
 304  * at which vTaskDelay() gets called and therefore the time at which the task \r
 305  * next executes.  See vTaskDelayUntil() for an alternative API function designed \r
 306  * to facilitate fixed frequency execution.  It does this by specifying an \r
 307  * absolute time (rather than a relative time) at which the calling task should \r
 308  * unblock.\r
 309  *\r
 310  * @param xTicksToDelay The amount of time, in tick periods, that\r
 311  * the calling task should block.\r
 312  *\r
 313  * Example usage:\r
 314 \r
 315  void vTaskFunction( void * pvParameters )\r
 316  {\r
 317  void vTaskFunction( void * pvParameters )\r
 318  {\r
 319  // Block for 500ms.\r
 320  const portTickType xDelay = 500 / portTICK_RATE_MS;\r
 321 \r
 322      for( ;; )\r
 323      {\r
 324          // Simply toggle the LED every 500ms, blocking between each toggle.\r
 325          vToggleLED();\r
 326          vTaskDelay( xDelay );\r
 327      }\r
 328  }\r
 329 \r
 330  * \defgroup vTaskDelay vTaskDelay\r
 331  * \ingroup TaskCtrl\r
 332  */\r
 333 void vTaskDelay( portTickType xTicksToDelay );\r
 334 \r
 335 /**\r
 336  * task. h\r
 337  * <pre>void vTaskDelayUntil( portTickType *pxPreviousWakeTime, portTickType xTimeIncrement );</pre>\r
 338  *\r
 339  * INCLUDE_vTaskDelayUntil must be defined as 1 for this function to be available.\r
 340  * See the configuration section for more information.\r
 341  *\r
 342  * Delay a task until a specified time.  This function can be used by cyclical\r
 343  * tasks to ensure a constant execution frequency.\r
 344  *\r
 345  * This function differs from vTaskDelay () in one important aspect:  vTaskDelay () will\r
 346  * cause a task to block for the specified number of ticks from the time vTaskDelay () is\r
 347  * called.  It is therefore difficult to use vTaskDelay () by itself to generate a fixed\r
 348  * execution frequency as the time between a task starting to execute and that task\r
 349  * calling vTaskDelay () may not be fixed [the task may take a different path though the\r
 350  * code between calls, or may get interrupted or preempted a different number of times\r
 351  * each time it executes].\r
 352  *\r
 353  * Whereas vTaskDelay () specifies a wake time relative to the time at which the function\r
 354  * is called, vTaskDelayUntil () specifies the absolute (exact) time at which it wishes to\r
 355  * unblock.\r
 356  *\r
 357  * The constant portTICK_RATE_MS can be used to calculate real time from the tick\r
 358  * rate - with the resolution of one tick period.\r
 359  *\r
 360  * @param pxPreviousWakeTime Pointer to a variable that holds the time at which the\r
 361  * task was last unblocked.  The variable must be initialised with the current time\r
 362  * prior to its first use (see the example below).  Following this the variable is\r
 363  * automatically updated within vTaskDelayUntil ().\r
 364  *\r
 365  * @param xTimeIncrement The cycle time period.  The task will be unblocked at\r
 366  * time *pxPreviousWakeTime + xTimeIncrement.  Calling vTaskDelayUntil with the\r
 367  * same xTimeIncrement parameter value will cause the task to execute with\r
 368  * a fixed interface period.\r
 369  *\r
 370  * Example usage:\r
 371    <pre>\r
 372  // Perform an action every 10 ticks.\r
 373  void vTaskFunction( void * pvParameters )\r
 374  {\r
 375  portTickType xLastWakeTime;\r
 376  const portTickType xFrequency = 10;\r
 377 \r
 378      // Initialise the xLastWakeTime variable with the current time.\r
 379      xLastWakeTime = xTaskGetTickCount ();\r
 380      for( ;; )\r
 381      {\r
 382          // Wait for the next cycle.\r
 383          vTaskDelayUntil( &xLastWakeTime, xFrequency );\r
 384 \r
 385          // Perform action here.\r
 386      }\r
 387  }\r
 388    </pre>\r
 389  * \defgroup vTaskDelayUntil vTaskDelayUntil\r
 390  * \ingroup TaskCtrl\r
 391  */\r
 392 void vTaskDelayUntil( portTickType * const pxPreviousWakeTime, portTickType xTimeIncrement );\r
 393 \r
 394 /**\r
 395  * task. h\r
 396  * <pre>unsigned portBASE_TYPE uxTaskPriorityGet( xTaskHandle pxTask );</pre>\r
 397  *\r
 398  * INCLUDE_xTaskPriorityGet must be defined as 1 for this function to be available.\r
 399  * See the configuration section for more information.\r
 400  *\r
 401  * Obtain the priority of any task.\r
 402  *\r
 403  * @param pxTask Handle of the task to be queried.  Passing a NULL\r
 404  * handle results in the priority of the calling task being returned.\r
 405  *\r
 406  * @return The priority of pxTask.\r
 407  *\r
 408  * Example usage:\r
 409    <pre>\r
 410  void vAFunction( void )\r
 411  {\r
 412  xTaskHandle xHandle;\r
 413                 \r
 414      // Create a task, storing the handle.\r
 415      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );\r
 416                 \r
 417      // ...\r
 418 \r
 419      // Use the handle to obtain the priority of the created task.\r
 420      // It was created with tskIDLE_PRIORITY, but may have changed\r
 421      // it itself.\r
 422      if( uxTaskPriorityGet( xHandle ) != tskIDLE_PRIORITY )\r
 423      {\r
 424          // The task has changed it's priority.\r
 425      }\r
 426 \r
 427      // ...\r
 428 \r
 429      // Is our priority higher than the created task?\r
 430      if( uxTaskPriorityGet( xHandle ) < uxTaskPriorityGet( NULL ) )\r
 431      {\r
 432          // Our priority (obtained using NULL handle) is higher.\r
 433      }\r
 434  }\r
 435    </pre>\r
 436  * \defgroup uxTaskPriorityGet uxTaskPriorityGet\r
 437  * \ingroup TaskCtrl\r
 438  */\r
 439 unsigned portBASE_TYPE uxTaskPriorityGet( xTaskHandle pxTask );\r
 440 \r
 441 /**\r
 442  * task. h\r
 443  * <pre>void vTaskPrioritySet( xTaskHandle pxTask, unsigned portBASE_TYPE uxNewPriority );</pre>\r
 444  *\r
 445  * INCLUDE_vTaskPrioritySet must be defined as 1 for this function to be available.\r
 446  * See the configuration section for more information.\r
 447  *\r
 448  * Set the priority of any task.\r
 449  *\r
 450  * A context switch will occur before the function returns if the priority\r
 451  * being set is higher than the currently executing task.\r
 452  *\r
 453  * @param pxTask Handle to the task for which the priority is being set.\r
 454  * Passing a NULL handle results in the priority of the calling task being set.\r
 455  *\r
 456  * @param uxNewPriority The priority to which the task will be set.\r
 457  *\r
 458  * Example usage:\r
 459    <pre>\r
 460  void vAFunction( void )\r
 461  {\r
 462  xTaskHandle xHandle;\r
 463                 \r
 464      // Create a task, storing the handle.\r
 465      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );\r
 466 \r
 467      // ...\r
 468 \r
 469      // Use the handle to raise the priority of the created task.\r
 470      vTaskPrioritySet( xHandle, tskIDLE_PRIORITY + 1 );\r
 471 \r
 472      // ...\r
 473 \r
 474      // Use a NULL handle to raise our priority to the same value.\r
 475      vTaskPrioritySet( NULL, tskIDLE_PRIORITY + 1 );\r
 476  }\r
 477    </pre>\r
 478  * \defgroup vTaskPrioritySet vTaskPrioritySet\r
 479  * \ingroup TaskCtrl\r
 480  */\r
 481 void vTaskPrioritySet( xTaskHandle pxTask, unsigned portBASE_TYPE uxNewPriority );\r
 482 \r
 483 /**\r
 484  * task. h\r
 485  * <pre>void vTaskSuspend( xTaskHandle pxTaskToSuspend );</pre>\r
 486  *\r
 487  * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available.\r
 488  * See the configuration section for more information.\r
 489  *\r
 490  * Suspend any task.  When suspended a task will never get any microcontroller\r
 491  * processing time, no matter what its priority.\r
 492  *\r
 493  * Calls to vTaskSuspend are not accumulative -\r
 494  * i.e. calling vTaskSuspend () twice on the same task still only requires one\r
 495  * call to vTaskResume () to ready the suspended task.\r
 496  *\r
 497  * @param pxTaskToSuspend Handle to the task being suspended.  Passing a NULL\r
 498  * handle will cause the calling task to be suspended.\r
 499  *\r
 500  * Example usage:\r
 501    <pre>\r
 502  void vAFunction( void )\r
 503  {\r
 504  xTaskHandle xHandle;\r
 505                 \r
 506      // Create a task, storing the handle.\r
 507      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );\r
 508                 \r
 509      // ...\r
 510 \r
 511      // Use the handle to suspend the created task.\r
 512      vTaskSuspend( xHandle );\r
 513 \r
 514      // ...\r
 515                 \r
 516      // The created task will not run during this period, unless\r
 517      // another task calls vTaskResume( xHandle ).\r
 518                 \r
 519      //...\r
 520                 \r
 521 \r
 522      // Suspend ourselves.\r
 523      vTaskSuspend( NULL );\r
 524 \r
 525      // We cannot get here unless another task calls vTaskResume\r
 526      // with our handle as the parameter.\r
 527  }\r
 528    </pre>\r
 529  * \defgroup vTaskSuspend vTaskSuspend\r
 530  * \ingroup TaskCtrl\r
 531  */\r
 532 void vTaskSuspend( xTaskHandle pxTaskToSuspend );\r
 533 \r
 534 /**\r
 535  * task. h\r
 536  * <pre>void vTaskResume( xTaskHandle pxTaskToResume );</pre>\r
 537  *\r
 538  * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available.\r
 539  * See the configuration section for more information.\r
 540  *\r
 541  * Resumes a suspended task.\r
 542  *\r
 543  * A task that has been suspended by one of more calls to vTaskSuspend ()\r
 544  * will be made available for running again by a single call to\r
 545  * vTaskResume ().\r
 546  *\r
 547  * @param pxTaskToResume Handle to the task being readied.\r
 548  *\r
 549  * Example usage:\r
 550    <pre>\r
 551  void vAFunction( void )\r
 552  {\r
 553  xTaskHandle xHandle;\r
 554                 \r
 555      // Create a task, storing the handle.\r
 556      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );\r
 557                 \r
 558      // ...\r
 559 \r
 560      // Use the handle to suspend the created task.\r
 561      vTaskSuspend( xHandle );\r
 562 \r
 563      // ...\r
 564         \r
 565      // The created task will not run during this period, unless\r
 566      // another task calls vTaskResume( xHandle ).\r
 567                 \r
 568      //...\r
 569                 \r
 570 \r
 571      // Resume the suspended task ourselves.\r
 572      vTaskResume( xHandle );\r
 573 \r
 574      // The created task will once again get microcontroller processing\r
 575      // time in accordance with it priority within the system.\r
 576  }\r
 577    </pre>\r
 578  * \defgroup vTaskResume vTaskResume\r
 579  * \ingroup TaskCtrl\r
 580  */\r
 581 void vTaskResume( xTaskHandle pxTaskToResume );\r
 582 \r
 583 /**\r
 584  * task. h\r
 585  * <pre>void xTaskResumeFromISR( xTaskHandle pxTaskToResume );</pre>\r
 586  *\r
 587  * INCLUDE_xTaskResumeFromISR must be defined as 1 for this function to be \r
 588  * available.  See the configuration section for more information.\r
 589  *\r
 590  * An implementation of vTaskResume() that can be called from within an ISR.\r
 591  *\r
 592  * A task that has been suspended by one of more calls to vTaskSuspend ()\r
 593  * will be made available for running again by a single call to\r
 594  * xTaskResumeFromISR ().\r
 595  *\r
 596  * @param pxTaskToResume Handle to the task being readied.\r
 597  *\r
 598  * \defgroup vTaskResumeFromISR vTaskResumeFromISR\r
 599  * \ingroup TaskCtrl\r
 600  */\r
 601 portBASE_TYPE xTaskResumeFromISR( xTaskHandle pxTaskToResume );\r
 602 \r
 603 /*-----------------------------------------------------------\r
 604  * SCHEDULER CONTROL\r
 605  *----------------------------------------------------------*/\r
 606 \r
 607 /**\r
 608  * task. h\r
 609  * <pre>void vTaskStartScheduler( void );</pre>\r
 610  *\r
 611  * Starts the real time kernel tick processing.  After calling the kernel\r
 612  * has control over which tasks are executed and when.  This function\r
 613  * does not return until an executing task calls vTaskEndScheduler ().\r
 614  *\r
 615  * At least one task should be created via a call to xTaskCreate ()\r
 616  * before calling vTaskStartScheduler ().  The idle task is created\r
 617  * automatically when the first application task is created.\r
 618  *\r
 619  * See the demo application file main.c for an example of creating\r
 620  * tasks and starting the kernel.\r
 621  *\r
 622  * Example usage:\r
 623    <pre>\r
 624  void vAFunction( void )\r
 625  {\r
 626      // Create at least one task before starting the kernel.\r
 627      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL );\r
 628 \r
 629      // Start the real time kernel with preemption.\r
 630      vTaskStartScheduler ();\r
 631 \r
 632      // Will not get here unless a task calls vTaskEndScheduler ()\r
 633  }\r
 634    </pre>\r
 635  *\r
 636  * \defgroup vTaskStartScheduler vTaskStartScheduler\r
 637  * \ingroup SchedulerControl\r
 638  */\r
 639 void vTaskStartScheduler( void );\r
 640 \r
 641 /**\r
 642  * task. h\r
 643  * <pre>void vTaskEndScheduler( void );</pre>\r
 644  *\r
 645  * Stops the real time kernel tick.  All created tasks will be automatically\r
 646  * deleted and multitasking (either preemptive or cooperative) will\r
 647  * stop.  Execution then resumes from the point where vTaskStartScheduler ()\r
 648  * was called, as if vTaskStartScheduler () had just returned.\r
 649  *\r
 650  * See the demo application file main. c in the demo/PC directory for an\r
 651  * example that uses vTaskEndScheduler ().\r
 652  *\r
 653  * vTaskEndScheduler () requires an exit function to be defined within the\r
 654  * portable layer (see vPortEndScheduler () in port. c for the PC port).  This\r
 655  * performs hardware specific operations such as stopping the kernel tick.\r
 656  *\r
 657  * vTaskEndScheduler () will cause all of the resources allocated by the\r
 658  * kernel to be freed - but will not free resources allocated by application\r
 659  * tasks.\r
 660  *\r
 661  * Example usage:\r
 662    <pre>\r
 663  void vTaskCode( void * pvParameters )\r
 664  {\r
 665      for( ;; )\r
 666      {\r
 667          // Task code goes here.\r
 668 \r
 669          // At some point we want to end the real time kernel processing\r
 670          // so call ...\r
 671          vTaskEndScheduler ();\r
 672      }\r
 673  }\r
 674 \r
 675  void vAFunction( void )\r
 676  {\r
 677      // Create at least one task before starting the kernel.\r
 678      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL );\r
 679 \r
 680      // Start the real time kernel with preemption.\r
 681      vTaskStartScheduler ();\r
 682 \r
 683      // Will only get here when the vTaskCode () task has called\r
 684      // vTaskEndScheduler ().  When we get here we are back to single task\r
 685      // execution.\r
 686  }\r
 687    </pre>\r
 688  *\r
 689  * \defgroup vTaskEndScheduler vTaskEndScheduler\r
 690  * \ingroup SchedulerControl\r
 691  */\r
 692 void vTaskEndScheduler( void );\r
 693 \r
 694 /**\r
 695  * task. h\r
 696  * <pre>void vTaskSuspendAll( void );</pre>\r
 697  *\r
 698  * Suspends all real time kernel activity while keeping interrupts (including the\r
 699  * kernel tick) enabled.\r
 700  *\r
 701  * After calling vTaskSuspendAll () the calling task will continue to execute\r
 702  * without risk of being swapped out until a call to xTaskResumeAll () has been\r
 703  * made.\r
 704  *\r
 705  * API functions that have the potential to cause a context switch (for example, \r
 706  * vTaskDelayUntil(), xQueueSend(), etc.) must not be called while the scheduler \r
 707  * is suspended.\r
 708  *\r
 709  * Example usage:\r
 710    <pre>\r
 711  void vTask1( void * pvParameters )\r
 712  {\r
 713      for( ;; )\r
 714      {\r
 715          // Task code goes here.\r
 716 \r
 717          // ...\r
 718 \r
 719          // At some point the task wants to perform a long operation during\r
 720          // which it does not want to get swapped out.  It cannot use\r
 721          // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the\r
 722          // operation may cause interrupts to be missed - including the\r
 723          // ticks.\r
 724 \r
 725          // Prevent the real time kernel swapping out the task.\r
 726          vTaskSuspendAll ();\r
 727 \r
 728          // Perform the operation here.  There is no need to use critical\r
 729          // sections as we have all the microcontroller processing time.\r
 730          // During this time interrupts will still operate and the kernel\r
 731          // tick count will be maintained.\r
 732 \r
 733          // ...\r
 734 \r
 735          // The operation is complete.  Restart the kernel.\r
 736          xTaskResumeAll ();\r
 737      }\r
 738  }\r
 739    </pre>\r
 740  * \defgroup vTaskSuspendAll vTaskSuspendAll\r
 741  * \ingroup SchedulerControl\r
 742  */\r
 743 void vTaskSuspendAll( void );\r
 744 \r
 745 /**\r
 746  * task. h\r
 747  * <pre>portCHAR xTaskResumeAll( void );</pre>\r
 748  *\r
 749  * Resumes real time kernel activity following a call to vTaskSuspendAll ().\r
 750  * After a call to vTaskSuspendAll () the kernel will take control of which\r
 751  * task is executing at any time.\r
 752  *\r
 753  * @return If resuming the scheduler caused a context switch then pdTRUE is\r
 754  *         returned, otherwise pdFALSE is returned.\r
 755  *\r
 756  * Example usage:\r
 757    <pre>\r
 758  void vTask1( void * pvParameters )\r
 759  {\r
 760      for( ;; )\r
 761      {\r
 762          // Task code goes here.\r
 763 \r
 764          // ...\r
 765 \r
 766          // At some point the task wants to perform a long operation during\r
 767          // which it does not want to get swapped out.  It cannot use\r
 768          // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the\r
 769          // operation may cause interrupts to be missed - including the\r
 770          // ticks.\r
 771 \r
 772          // Prevent the real time kernel swapping out the task.\r
 773          vTaskSuspendAll ();\r
 774 \r
 775          // Perform the operation here.  There is no need to use critical\r
 776          // sections as we have all the microcontroller processing time.\r
 777          // During this time interrupts will still operate and the real\r
 778          // time kernel tick count will be maintained.\r
 779 \r
 780          // ...\r
 781 \r
 782          // The operation is complete.  Restart the kernel.  We want to force\r
 783          // a context switch - but there is no point if resuming the scheduler\r
 784          // caused a context switch already.\r
 785          if( !xTaskResumeAll () )\r
 786          {\r
 787               taskYIELD ();\r
 788          }\r
 789      }\r
 790  }\r
 791    </pre>\r
 792  * \defgroup xTaskResumeAll xTaskResumeAll\r
 793  * \ingroup SchedulerControl\r
 794  */\r
 795 signed portBASE_TYPE xTaskResumeAll( void );\r
 796 \r
 797 /**\r
 798  * task. h\r
 799  * <pre>signed portBASE_TYPE xTaskIsTaskSuspended( xTaskHandle xTask );</pre>\r
 800  *\r
 801  * Utility task that simply returns pdTRUE if the task referenced by xTask is\r
 802  * currently in the Suspended state, or pdFALSE if the task referenced by xTask\r
 803  * is in any other state.\r
 804  *\r
 805  */\r
 806 signed portBASE_TYPE xTaskIsTaskSuspended( xTaskHandle xTask );\r
 807 \r
 808 /*-----------------------------------------------------------\r
 809  * TASK UTILITIES\r
 810  *----------------------------------------------------------*/\r
 811 \r
 812 /**\r
 813  * task. h\r
 814  * <PRE>volatile portTickType xTaskGetTickCount( void );</PRE>\r
 815  *\r
 816  * @return The count of ticks since vTaskStartScheduler was called.\r
 817  *\r
 818  * \page xTaskGetTickCount xTaskGetTickCount\r
 819  * \ingroup TaskUtils\r
 820  */\r
 821 portTickType xTaskGetTickCount( void );\r
 822 \r
 823 /**\r
 824  * task. h\r
 825  * <PRE>unsigned portSHORT uxTaskGetNumberOfTasks( void );</PRE>\r
 826  *\r
 827  * @return The number of tasks that the real time kernel is currently managing.\r
 828  * This includes all ready, blocked and suspended tasks.  A task that\r
 829  * has been deleted but not yet freed by the idle task will also be\r
 830  * included in the count.\r
 831  *\r
 832  * \page uxTaskGetNumberOfTasks uxTaskGetNumberOfTasks\r
 833  * \ingroup TaskUtils\r
 834  */\r
 835 unsigned portBASE_TYPE uxTaskGetNumberOfTasks( void );\r
 836 \r
 837 /**\r
 838  * task. h\r
 839  * <PRE>void vTaskList( portCHAR *pcWriteBuffer );</PRE>\r
 840  *\r
 841  * configUSE_TRACE_FACILITY, INCLUDE_vTaskDelete and INCLUDE_vTaskSuspend\r
 842  * must all be defined as 1 for this function to be available.\r
 843  * See the configuration section for more information.\r
 844  *\r
 845  * NOTE: This function will disable interrupts for its duration.  It is\r
 846  * not intended for normal application runtime use but as a debug aid.\r
 847  *\r
 848  * Lists all the current tasks, along with their current state and stack\r
 849  * usage high water mark.\r
 850  *\r
 851  * Tasks are reported as blocked ('B'), ready ('R'), deleted ('D') or\r
 852  * suspended ('S').\r
 853  *\r
 854  * @param pcWriteBuffer A buffer into which the above mentioned details\r
 855  * will be written, in ascii form.  This buffer is assumed to be large\r
 856  * enough to contain the generated report.  Approximately 40 bytes per\r
 857  * task should be sufficient.\r
 858  *\r
 859  * \page vTaskList vTaskList\r
 860  * \ingroup TaskUtils\r
 861  */\r
 862 void vTaskList( signed portCHAR *pcWriteBuffer );\r
 863 \r
 864 /**\r
 865  * task. h\r
 866  * <PRE>void vTaskStartTrace( portCHAR * pcBuffer, unsigned portBASE_TYPE uxBufferSize );</PRE>\r
 867  *\r
 868  * Starts a real time kernel activity trace.  The trace logs the identity of\r
 869  * which task is running when.\r
 870  *\r
 871  * The trace file is stored in binary format.  A separate DOS utility called\r
 872  * convtrce.exe is used to convert this into a tab delimited text file which\r
 873  * can be viewed and plotted in a spread sheet.\r
 874  *\r
 875  * @param pcBuffer The buffer into which the trace will be written.\r
 876  *\r
 877  * @param ulBufferSize The size of pcBuffer in bytes.  The trace will continue\r
 878  * until either the buffer in full, or ulTaskEndTrace () is called.\r
 879  *\r
 880  * \page vTaskStartTrace vTaskStartTrace\r
 881  * \ingroup TaskUtils\r
 882  */\r
 883 void vTaskStartTrace( signed portCHAR * pcBuffer, unsigned portLONG ulBufferSize );\r
 884 \r
 885 /**\r
 886  * task. h\r
 887  * <PRE>unsigned portLONG ulTaskEndTrace( void );</PRE>\r
 888  *\r
 889  * Stops a kernel activity trace.  See vTaskStartTrace ().\r
 890  *\r
 891  * @return The number of bytes that have been written into the trace buffer.\r
 892  *\r
 893  * \page usTaskEndTrace usTaskEndTrace\r
 894  * \ingroup TaskUtils\r
 895  */\r
 896 unsigned portLONG ulTaskEndTrace( void );\r
 897 \r
 898 /**\r
 899  * task.h\r
 900  * <PRE>unsigned portBASE_TYPE uxTaskGetStackHighWaterMark( xTaskHandle xTask );</PRE>\r
 901  *\r
 902  * INCLUDE_uxTaskGetStackHighWaterMark must be set to 1 in FreeRTOSConfig.h for\r
 903  * this function to be available.\r
 904  *\r
 905  * Returns the high water mark of the stack associated with xTask.  That is,\r
 906  * the minimum free stack space there has been (in bytes) since the task\r
 907  * started.  The smaller the returned number the closer the task has come\r
 908  * to overflowing its stack.\r
 909  *\r
 910  * @param xTask Handle of the task associated with the stack to be checked.\r
 911  * Set xTask to NULL to check the stack of the calling task.\r
 912  *\r
 913  * @return The smallest amount of free stack space there has been (in bytes)\r
 914  * since the task referenced by xTask was created.\r
 915  */\r
 916 unsigned portBASE_TYPE uxTaskGetStackHighWaterMark( xTaskHandle xTask );\r
 917 \r
 918 /**\r
 919  * task.h\r
 920  * <pre>void vTaskSetApplicationTaskTag( xTaskHandle xTask, pdTASK_HOOK_CODE pxHookFunction );</pre>\r
 921  *\r
 922  * Sets pxHookFunction to be the task hook function used by the task xTask.\r
 923  * Passing xTask as NULL has the effect of setting the calling tasks hook\r
 924  * function.\r
 925  */\r
 926 void vTaskSetApplicationTaskTag( xTaskHandle xTask, pdTASK_HOOK_CODE pxHookFunction );\r
 927 \r
 928 /**\r
 929  * task.h\r
 930  * <pre>portBASE_TYPE xTaskCallApplicationTaskHook( xTaskHandle xTask, pdTASK_HOOK_CODE pxHookFunction );</pre>\r
 931  *\r
 932  * Calls the hook function associated with xTask.  Passing xTask as NULL has\r
 933  * the effect of calling the Running tasks (the calling task) hook function.\r
 934  *\r
 935  * pvParameter is passed to the hook function for the task to interpret as it\r
 936  * wants.\r
 937  */\r
 938 portBASE_TYPE xTaskCallApplicationTaskHook( xTaskHandle xTask, void *pvParameter );\r
 939 \r
 940 \r
 941 /*-----------------------------------------------------------\r
 942  * SCHEDULER INTERNALS AVAILABLE FOR PORTING PURPOSES\r
 943  *----------------------------------------------------------*/\r
 944 \r
 945 /*\r
 946  * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS ONLY\r
 947  * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS\r
 948  * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.\r
 949  *\r
 950  * Called from the real time kernel tick (either preemptive or cooperative),\r
 951  * this increments the tick count and checks if any tasks that are blocked\r
 952  * for a finite period required removing from a blocked list and placing on\r
 953  * a ready list.\r
 954  */\r
 955 void vTaskIncrementTick( void );\r
 956 \r
 957 /*\r
 958  * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS AN\r
 959  * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.\r
 960  *\r
 961  * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED.\r
 962  *\r
 963  * Removes the calling task from the ready list and places it both\r
 964  * on the list of tasks waiting for a particular event, and the\r
 965  * list of delayed tasks.  The task will be removed from both lists\r
 966  * and replaced on the ready list should either the event occur (and\r
 967  * there be no higher priority tasks waiting on the same event) or\r
 968  * the delay period expires.\r
 969  *\r
 970  * @param pxEventList The list containing tasks that are blocked waiting\r
 971  * for the event to occur.\r
 972  *\r
 973  * @param xTicksToWait The maximum amount of time that the task should wait\r
 974  * for the event to occur.  This is specified in kernel ticks,the constant\r
 975  * portTICK_RATE_MS can be used to convert kernel ticks into a real time\r
 976  * period.\r
 977  */\r
 978 void vTaskPlaceOnEventList( const xList * const pxEventList, portTickType xTicksToWait );\r
 979 \r
 980 /*\r
 981  * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS AN\r
 982  * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.\r
 983  *\r
 984  * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED.\r
 985  *\r
 986  * Removes a task from both the specified event list and the list of blocked\r
 987  * tasks, and places it on a ready queue.\r
 988  *\r
 989  * xTaskRemoveFromEventList () will be called if either an event occurs to\r
 990  * unblock a task, or the block timeout period expires.\r
 991  *\r
 992  * @return pdTRUE if the task being removed has a higher priority than the task\r
 993  * making the call, otherwise pdFALSE.\r
 994  */\r
 995 signed portBASE_TYPE xTaskRemoveFromEventList( const xList * const pxEventList );\r
 996 \r
 997 /*\r
 998  * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS AN\r
 999  * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.\r
1000  *\r
1001  * INCLUDE_vTaskCleanUpResources and INCLUDE_vTaskSuspend must be defined as 1\r
1002  * for this function to be available.\r
1003  * See the configuration section for more information.\r
1004  *\r
1005  * Empties the ready and delayed queues of task control blocks, freeing the\r
1006  * memory allocated for the task control block and task stacks as it goes.\r
1007  */\r
1008 void vTaskCleanUpResources( void );\r
1009 \r
1010 /*\r
1011  * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS ONLY\r
1012  * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS\r
1013  * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.\r
1014  *\r
1015  * Sets the pointer to the current TCB to the TCB of the highest priority task\r
1016  * that is ready to run.\r
1017  */\r
1018 void vTaskSwitchContext( void );\r
1019 \r
1020 /*\r
1021  * Return the handle of the calling task.\r
1022  */\r
1023 xTaskHandle xTaskGetCurrentTaskHandle( void );\r
1024 \r
1025 /*\r
1026  * Capture the current time status for future reference.\r
1027  */\r
1028 void vTaskSetTimeOutState( xTimeOutType * const pxTimeOut );\r
1029 \r
1030 /*\r
1031  * Compare the time status now with that previously captured to see if the\r
1032  * timeout has expired.\r
1033  */\r
1034 portBASE_TYPE xTaskCheckForTimeOut( xTimeOutType * const pxTimeOut, portTickType * const pxTicksToWait );\r
1035 \r
1036 /*\r
1037  * Shortcut used by the queue implementation to prevent unnecessary call to\r
1038  * taskYIELD();\r
1039  */\r
1040 void vTaskMissedYield( void );\r
1041 \r
1042 /*\r
1043  * Returns the scheduler state as taskSCHEDULER_RUNNING,\r
1044  * taskSCHEDULER_NOT_STARTED or taskSCHEDULER_SUSPENDED.\r
1045  */\r
1046 portBASE_TYPE xTaskGetSchedulerState( void );\r
1047 \r
1048 /*\r
1049  * Raises the priority of the mutex holder to that of the calling task should\r
1050  * the mutex holder have a priority less than the calling task.\r
1051  */\r
1052 void vTaskPriorityInherit( xTaskHandle * const pxMutexHolder );\r
1053 \r
1054 /*\r
1055  * Set the priority of a task back to its proper priority in the case that it\r
1056  * inherited a higher priority while it was holding a semaphore.\r
1057  */\r
1058 void vTaskPriorityDisinherit( xTaskHandle * const pxMutexHolder );\r
1059 \r
1060 #ifdef __cplusplus\r
1061 }\r
1062 #endif\r
1063 #endif /* TASK_H */\r
1064 \r
1065 \r
1066 \r