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

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