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

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