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

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