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

   1 /*\r
   2         FreeRTOS.org V5.0.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!  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.0"\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  * @param xTicksToDelay The amount of time, in tick periods, that\r
 291  * the calling task should block.\r
 292  *\r
 293  * Example usage:\r
 294    <pre>\r
 295  // Wait 10 ticks before performing an action.\r
 296  // NOTE:\r
 297  // This is for demonstration only and would be better achieved\r
 298  // using vTaskDelayUntil ().\r
 299  void vTaskFunction( void * pvParameters )\r
 300  {\r
 301  portTickType xDelay, xNextTime;\r
 302 \r
 303      // Calc the time at which we want to perform the action\r
 304      // next.\r
 305      xNextTime = xTaskGetTickCount () + ( portTickType ) 10;\r
 306 \r
 307      for( ;; )\r
 308      {\r
 309          xDelay = xNextTime - xTaskGetTickCount ();\r
 310          xNextTime += ( portTickType ) 10;\r
 311 \r
 312          // Guard against overflow\r
 313          if( xDelay <= ( portTickType ) 10 )\r
 314          {\r
 315              vTaskDelay( xDelay );\r
 316          }\r
 317 \r
 318          // Perform action here.\r
 319      }\r
 320  }\r
 321    </pre>\r
 322  * \defgroup vTaskDelay vTaskDelay\r
 323  * \ingroup TaskCtrl\r
 324  */\r
 325 void vTaskDelay( portTickType xTicksToDelay );\r
 326 \r
 327 /**\r
 328  * task. h\r
 329  * <pre>void vTaskDelayUntil( portTickType *pxPreviousWakeTime, portTickType xTimeIncrement );</pre>\r
 330  *\r
 331  * INCLUDE_vTaskDelayUntil must be defined as 1 for this function to be available.\r
 332  * See the configuration section for more information.\r
 333  *\r
 334  * Delay a task until a specified time.  This function can be used by cyclical\r
 335  * tasks to ensure a constant execution frequency.\r
 336  *\r
 337  * This function differs from vTaskDelay () in one important aspect:  vTaskDelay () will\r
 338  * cause a task to block for the specified number of ticks from the time vTaskDelay () is\r
 339  * called.  It is therefore difficult to use vTaskDelay () by itself to generate a fixed\r
 340  * execution frequency as the time between a task starting to execute and that task\r
 341  * calling vTaskDelay () may not be fixed [the task may take a different path though the\r
 342  * code between calls, or may get interrupted or preempted a different number of times\r
 343  * each time it executes].\r
 344  *\r
 345  * Whereas vTaskDelay () specifies a wake time relative to the time at which the function\r
 346  * is called, vTaskDelayUntil () specifies the absolute (exact) time at which it wishes to\r
 347  * unblock.\r
 348  *\r
 349  * The constant portTICK_RATE_MS can be used to calculate real time from the tick\r
 350  * rate - with the resolution of one tick period.\r
 351  *\r
 352  * @param pxPreviousWakeTime Pointer to a variable that holds the time at which the\r
 353  * task was last unblocked.  The variable must be initialised with the current time\r
 354  * prior to its first use (see the example below).  Following this the variable is\r
 355  * automatically updated within vTaskDelayUntil ().\r
 356  *\r
 357  * @param xTimeIncrement The cycle time period.  The task will be unblocked at\r
 358  * time *pxPreviousWakeTime + xTimeIncrement.  Calling vTaskDelayUntil with the\r
 359  * same xTimeIncrement parameter value will cause the task to execute with\r
 360  * a fixed interface period.\r
 361  *\r
 362  * Example usage:\r
 363    <pre>\r
 364  // Perform an action every 10 ticks.\r
 365  void vTaskFunction( void * pvParameters )\r
 366  {\r
 367  portTickType xLastWakeTime;\r
 368  const portTickType xFrequency = 10;\r
 369 \r
 370      // Initialise the xLastWakeTime variable with the current time.\r
 371      xLastWakeTime = xTaskGetTickCount ();\r
 372      for( ;; )\r
 373      {\r
 374          // Wait for the next cycle.\r
 375          vTaskDelayUntil( &xLastWakeTime, xFrequency );\r
 376 \r
 377          // Perform action here.\r
 378      }\r
 379  }\r
 380    </pre>\r
 381  * \defgroup vTaskDelayUntil vTaskDelayUntil\r
 382  * \ingroup TaskCtrl\r
 383  */\r
 384 void vTaskDelayUntil( portTickType * const pxPreviousWakeTime, portTickType xTimeIncrement );\r
 385 \r
 386 /**\r
 387  * task. h\r
 388  * <pre>unsigned portBASE_TYPE uxTaskPriorityGet( xTaskHandle pxTask );</pre>\r
 389  *\r
 390  * INCLUDE_xTaskPriorityGet must be defined as 1 for this function to be available.\r
 391  * See the configuration section for more information.\r
 392  *\r
 393  * Obtain the priority of any task.\r
 394  *\r
 395  * @param pxTask Handle of the task to be queried.  Passing a NULL\r
 396  * handle results in the priority of the calling task being returned.\r
 397  *\r
 398  * @return The priority of pxTask.\r
 399  *\r
 400  * Example usage:\r
 401    <pre>\r
 402  void vAFunction( void )\r
 403  {\r
 404  xTaskHandle xHandle;\r
 405                 \r
 406      // Create a task, storing the handle.\r
 407      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );\r
 408                 \r
 409      // ...\r
 410 \r
 411      // Use the handle to obtain the priority of the created task.\r
 412      // It was created with tskIDLE_PRIORITY, but may have changed\r
 413      // it itself.\r
 414      if( uxTaskPriorityGet( xHandle ) != tskIDLE_PRIORITY )\r
 415      {\r
 416          // The task has changed it's priority.\r
 417      }\r
 418 \r
 419      // ...\r
 420 \r
 421      // Is our priority higher than the created task?\r
 422      if( uxTaskPriorityGet( xHandle ) < uxTaskPriorityGet( NULL ) )\r
 423      {\r
 424          // Our priority (obtained using NULL handle) is higher.\r
 425      }\r
 426  }\r
 427    </pre>\r
 428  * \defgroup uxTaskPriorityGet uxTaskPriorityGet\r
 429  * \ingroup TaskCtrl\r
 430  */\r
 431 unsigned portBASE_TYPE uxTaskPriorityGet( xTaskHandle pxTask );\r
 432 \r
 433 /**\r
 434  * task. h\r
 435  * <pre>void vTaskPrioritySet( xTaskHandle pxTask, unsigned portBASE_TYPE uxNewPriority );</pre>\r
 436  *\r
 437  * INCLUDE_vTaskPrioritySet must be defined as 1 for this function to be available.\r
 438  * See the configuration section for more information.\r
 439  *\r
 440  * Set the priority of any task.\r
 441  *\r
 442  * A context switch will occur before the function returns if the priority\r
 443  * being set is higher than the currently executing task.\r
 444  *\r
 445  * @param pxTask Handle to the task for which the priority is being set.\r
 446  * Passing a NULL handle results in the priority of the calling task being set.\r
 447  *\r
 448  * @param uxNewPriority The priority to which the task will be set.\r
 449  *\r
 450  * Example usage:\r
 451    <pre>\r
 452  void vAFunction( void )\r
 453  {\r
 454  xTaskHandle xHandle;\r
 455                 \r
 456      // Create a task, storing the handle.\r
 457      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );\r
 458 \r
 459      // ...\r
 460 \r
 461      // Use the handle to raise the priority of the created task.\r
 462      vTaskPrioritySet( xHandle, tskIDLE_PRIORITY + 1 );\r
 463 \r
 464      // ...\r
 465 \r
 466      // Use a NULL handle to raise our priority to the same value.\r
 467      vTaskPrioritySet( NULL, tskIDLE_PRIORITY + 1 );\r
 468  }\r
 469    </pre>\r
 470  * \defgroup vTaskPrioritySet vTaskPrioritySet\r
 471  * \ingroup TaskCtrl\r
 472  */\r
 473 void vTaskPrioritySet( xTaskHandle pxTask, unsigned portBASE_TYPE uxNewPriority );\r
 474 \r
 475 /**\r
 476  * task. h\r
 477  * <pre>void vTaskSuspend( xTaskHandle pxTaskToSuspend );</pre>\r
 478  *\r
 479  * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available.\r
 480  * See the configuration section for more information.\r
 481  *\r
 482  * Suspend any task.  When suspended a task will never get any microcontroller\r
 483  * processing time, no matter what its priority.\r
 484  *\r
 485  * Calls to vTaskSuspend are not accumulative -\r
 486  * i.e. calling vTaskSuspend () twice on the same task still only requires one\r
 487  * call to vTaskResume () to ready the suspended task.\r
 488  *\r
 489  * @param pxTaskToSuspend Handle to the task being suspended.  Passing a NULL\r
 490  * handle will cause the calling task to be suspended.\r
 491  *\r
 492  * Example usage:\r
 493    <pre>\r
 494  void vAFunction( void )\r
 495  {\r
 496  xTaskHandle xHandle;\r
 497                 \r
 498      // Create a task, storing the handle.\r
 499      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );\r
 500                 \r
 501      // ...\r
 502 \r
 503      // Use the handle to suspend the created task.\r
 504      vTaskSuspend( xHandle );\r
 505 \r
 506      // ...\r
 507                 \r
 508      // The created task will not run during this period, unless\r
 509      // another task calls vTaskResume( xHandle ).\r
 510                 \r
 511      //...\r
 512                 \r
 513 \r
 514      // Suspend ourselves.\r
 515      vTaskSuspend( NULL );\r
 516 \r
 517      // We cannot get here unless another task calls vTaskResume\r
 518      // with our handle as the parameter.\r
 519  }\r
 520    </pre>\r
 521  * \defgroup vTaskSuspend vTaskSuspend\r
 522  * \ingroup TaskCtrl\r
 523  */\r
 524 void vTaskSuspend( xTaskHandle pxTaskToSuspend );\r
 525 \r
 526 /**\r
 527  * task. h\r
 528  * <pre>void vTaskResume( xTaskHandle pxTaskToResume );</pre>\r
 529  *\r
 530  * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available.\r
 531  * See the configuration section for more information.\r
 532  *\r
 533  * Resumes a suspended task.\r
 534  *\r
 535  * A task that has been suspended by one of more calls to vTaskSuspend ()\r
 536  * will be made available for running again by a single call to\r
 537  * vTaskResume ().\r
 538  *\r
 539  * @param pxTaskToResume Handle to the task being readied.\r
 540  *\r
 541  * Example usage:\r
 542    <pre>\r
 543  void vAFunction( void )\r
 544  {\r
 545  xTaskHandle xHandle;\r
 546                 \r
 547      // Create a task, storing the handle.\r
 548      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );\r
 549                 \r
 550      // ...\r
 551 \r
 552      // Use the handle to suspend the created task.\r
 553      vTaskSuspend( xHandle );\r
 554 \r
 555      // ...\r
 556         \r
 557      // The created task will not run during this period, unless\r
 558      // another task calls vTaskResume( xHandle ).\r
 559                 \r
 560      //...\r
 561                 \r
 562 \r
 563      // Resume the suspended task ourselves.\r
 564      vTaskResume( xHandle );\r
 565 \r
 566      // The created task will once again get microcontroller processing\r
 567      // time in accordance with it priority within the system.\r
 568  }\r
 569    </pre>\r
 570  * \defgroup vTaskResume vTaskResume\r
 571  * \ingroup TaskCtrl\r
 572  */\r
 573 void vTaskResume( xTaskHandle pxTaskToResume );\r
 574 \r
 575 /**\r
 576  * task. h\r
 577  * <pre>void xTaskResumeFromISR( xTaskHandle pxTaskToResume );</pre>\r
 578  *\r
 579  * INCLUDE_xTaskResumeFromISR must be defined as 1 for this function to be \r
 580  * available.  See the configuration section for more information.\r
 581  *\r
 582  * An implementation of vTaskResume() that can be called from within an ISR.\r
 583  *\r
 584  * A task that has been suspended by one of more calls to vTaskSuspend ()\r
 585  * will be made available for running again by a single call to\r
 586  * xTaskResumeFromISR ().\r
 587  *\r
 588  * @param pxTaskToResume Handle to the task being readied.\r
 589  *\r
 590  * \defgroup vTaskResumeFromISR vTaskResumeFromISR\r
 591  * \ingroup TaskCtrl\r
 592  */\r
 593 portBASE_TYPE xTaskResumeFromISR( xTaskHandle pxTaskToResume );\r
 594 \r
 595 /*-----------------------------------------------------------\r
 596  * SCHEDULER CONTROL\r
 597  *----------------------------------------------------------*/\r
 598 \r
 599 /**\r
 600  * task. h\r
 601  * <pre>void vTaskStartScheduler( void );</pre>\r
 602  *\r
 603  * Starts the real time kernel tick processing.  After calling the kernel\r
 604  * has control over which tasks are executed and when.  This function\r
 605  * does not return until an executing task calls vTaskEndScheduler ().\r
 606  *\r
 607  * At least one task should be created via a call to xTaskCreate ()\r
 608  * before calling vTaskStartScheduler ().  The idle task is created\r
 609  * automatically when the first application task is created.\r
 610  *\r
 611  * See the demo application file main.c for an example of creating\r
 612  * tasks and starting the kernel.\r
 613  *\r
 614  * Example usage:\r
 615    <pre>\r
 616  void vAFunction( void )\r
 617  {\r
 618      // Create at least one task before starting the kernel.\r
 619      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL );\r
 620 \r
 621      // Start the real time kernel with preemption.\r
 622      vTaskStartScheduler ();\r
 623 \r
 624      // Will not get here unless a task calls vTaskEndScheduler ()\r
 625  }\r
 626    </pre>\r
 627  *\r
 628  * \defgroup vTaskStartScheduler vTaskStartScheduler\r
 629  * \ingroup SchedulerControl\r
 630  */\r
 631 void vTaskStartScheduler( void );\r
 632 \r
 633 /**\r
 634  * task. h\r
 635  * <pre>void vTaskEndScheduler( void );</pre>\r
 636  *\r
 637  * Stops the real time kernel tick.  All created tasks will be automatically\r
 638  * deleted and multitasking (either preemptive or cooperative) will\r
 639  * stop.  Execution then resumes from the point where vTaskStartScheduler ()\r
 640  * was called, as if vTaskStartScheduler () had just returned.\r
 641  *\r
 642  * See the demo application file main. c in the demo/PC directory for an\r
 643  * example that uses vTaskEndScheduler ().\r
 644  *\r
 645  * vTaskEndScheduler () requires an exit function to be defined within the\r
 646  * portable layer (see vPortEndScheduler () in port. c for the PC port).  This\r
 647  * performs hardware specific operations such as stopping the kernel tick.\r
 648  *\r
 649  * vTaskEndScheduler () will cause all of the resources allocated by the\r
 650  * kernel to be freed - but will not free resources allocated by application\r
 651  * tasks.\r
 652  *\r
 653  * Example usage:\r
 654    <pre>\r
 655  void vTaskCode( void * pvParameters )\r
 656  {\r
 657      for( ;; )\r
 658      {\r
 659          // Task code goes here.\r
 660 \r
 661          // At some point we want to end the real time kernel processing\r
 662          // so call ...\r
 663          vTaskEndScheduler ();\r
 664      }\r
 665  }\r
 666 \r
 667  void vAFunction( void )\r
 668  {\r
 669      // Create at least one task before starting the kernel.\r
 670      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL );\r
 671 \r
 672      // Start the real time kernel with preemption.\r
 673      vTaskStartScheduler ();\r
 674 \r
 675      // Will only get here when the vTaskCode () task has called\r
 676      // vTaskEndScheduler ().  When we get here we are back to single task\r
 677      // execution.\r
 678  }\r
 679    </pre>\r
 680  *\r
 681  * \defgroup vTaskEndScheduler vTaskEndScheduler\r
 682  * \ingroup SchedulerControl\r
 683  */\r
 684 void vTaskEndScheduler( void );\r
 685 \r
 686 /**\r
 687  * task. h\r
 688  * <pre>void vTaskSuspendAll( void );</pre>\r
 689  *\r
 690  * Suspends all real time kernel activity while keeping interrupts (including the\r
 691  * kernel tick) enabled.\r
 692  *\r
 693  * After calling vTaskSuspendAll () the calling task will continue to execute\r
 694  * without risk of being swapped out until a call to xTaskResumeAll () has been\r
 695  * made.\r
 696  *\r
 697  * Example usage:\r
 698    <pre>\r
 699  void vTask1( void * pvParameters )\r
 700  {\r
 701      for( ;; )\r
 702      {\r
 703          // Task code goes here.\r
 704 \r
 705          // ...\r
 706 \r
 707          // At some point the task wants to perform a long operation during\r
 708          // which it does not want to get swapped out.  It cannot use\r
 709          // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the\r
 710          // operation may cause interrupts to be missed - including the\r
 711          // ticks.\r
 712 \r
 713          // Prevent the real time kernel swapping out the task.\r
 714          vTaskSuspendAll ();\r
 715 \r
 716          // Perform the operation here.  There is no need to use critical\r
 717          // sections as we have all the microcontroller processing time.\r
 718          // During this time interrupts will still operate and the kernel\r
 719          // tick count will be maintained.\r
 720 \r
 721          // ...\r
 722 \r
 723          // The operation is complete.  Restart the kernel.\r
 724          xTaskResumeAll ();\r
 725      }\r
 726  }\r
 727    </pre>\r
 728  * \defgroup vTaskSuspendAll vTaskSuspendAll\r
 729  * \ingroup SchedulerControl\r
 730  */\r
 731 void vTaskSuspendAll( void );\r
 732 \r
 733 /**\r
 734  * task. h\r
 735  * <pre>portCHAR xTaskResumeAll( void );</pre>\r
 736  *\r
 737  * Resumes real time kernel activity following a call to vTaskSuspendAll ().\r
 738  * After a call to vTaskSuspendAll () the kernel will take control of which\r
 739  * task is executing at any time.\r
 740  *\r
 741  * @return If resuming the scheduler caused a context switch then pdTRUE is\r
 742  *         returned, otherwise pdFALSE is returned.\r
 743  *\r
 744  * Example usage:\r
 745    <pre>\r
 746  void vTask1( void * pvParameters )\r
 747  {\r
 748      for( ;; )\r
 749      {\r
 750          // Task code goes here.\r
 751 \r
 752          // ...\r
 753 \r
 754          // At some point the task wants to perform a long operation during\r
 755          // which it does not want to get swapped out.  It cannot use\r
 756          // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the\r
 757          // operation may cause interrupts to be missed - including the\r
 758          // ticks.\r
 759 \r
 760          // Prevent the real time kernel swapping out the task.\r
 761          vTaskSuspendAll ();\r
 762 \r
 763          // Perform the operation here.  There is no need to use critical\r
 764          // sections as we have all the microcontroller processing time.\r
 765          // During this time interrupts will still operate and the real\r
 766          // time kernel tick count will be maintained.\r
 767 \r
 768          // ...\r
 769 \r
 770          // The operation is complete.  Restart the kernel.  We want to force\r
 771          // a context switch - but there is no point if resuming the scheduler\r
 772          // caused a context switch already.\r
 773          if( !xTaskResumeAll () )\r
 774          {\r
 775               taskYIELD ();\r
 776          }\r
 777      }\r
 778  }\r
 779    </pre>\r
 780  * \defgroup xTaskResumeAll xTaskResumeAll\r
 781  * \ingroup SchedulerControl\r
 782  */\r
 783 signed portBASE_TYPE xTaskResumeAll( void );\r
 784 \r
 785 \r
 786 /*-----------------------------------------------------------\r
 787  * TASK UTILITIES\r
 788  *----------------------------------------------------------*/\r
 789 \r
 790 /**\r
 791  * task. h\r
 792  * <PRE>volatile portTickType xTaskGetTickCount( void );</PRE>\r
 793  *\r
 794  * @return The count of ticks since vTaskStartScheduler was called.\r
 795  *\r
 796  * \page xTaskGetTickCount xTaskGetTickCount\r
 797  * \ingroup TaskUtils\r
 798  */\r
 799 portTickType xTaskGetTickCount( void );\r
 800 \r
 801 /**\r
 802  * task. h\r
 803  * <PRE>unsigned portSHORT uxTaskGetNumberOfTasks( void );</PRE>\r
 804  *\r
 805  * @return The number of tasks that the real time kernel is currently managing.\r
 806  * This includes all ready, blocked and suspended tasks.  A task that\r
 807  * has been deleted but not yet freed by the idle task will also be\r
 808  * included in the count.\r
 809  *\r
 810  * \page uxTaskGetNumberOfTasks uxTaskGetNumberOfTasks\r
 811  * \ingroup TaskUtils\r
 812  */\r
 813 unsigned portBASE_TYPE uxTaskGetNumberOfTasks( void );\r
 814 \r
 815 /**\r
 816  * task. h\r
 817  * <PRE>void vTaskList( portCHAR *pcWriteBuffer );</PRE>\r
 818  *\r
 819  * configUSE_TRACE_FACILITY, INCLUDE_vTaskDelete and INCLUDE_vTaskSuspend\r
 820  * must all be defined as 1 for this function to be available.\r
 821  * See the configuration section for more information.\r
 822  *\r
 823  * NOTE: This function will disable interrupts for its duration.  It is\r
 824  * not intended for normal application runtime use but as a debug aid.\r
 825  *\r
 826  * Lists all the current tasks, along with their current state and stack\r
 827  * usage high water mark.\r
 828  *\r
 829  * Tasks are reported as blocked ('B'), ready ('R'), deleted ('D') or\r
 830  * suspended ('S').\r
 831  *\r
 832  * @param pcWriteBuffer A buffer into which the above mentioned details\r
 833  * will be written, in ascii form.  This buffer is assumed to be large\r
 834  * enough to contain the generated report.  Approximately 40 bytes per\r
 835  * task should be sufficient.\r
 836  *\r
 837  * \page vTaskList vTaskList\r
 838  * \ingroup TaskUtils\r
 839  */\r
 840 void vTaskList( signed portCHAR *pcWriteBuffer );\r
 841 \r
 842 /**\r
 843  * task. h\r
 844  * <PRE>void vTaskStartTrace( portCHAR * pcBuffer, unsigned portBASE_TYPE uxBufferSize );</PRE>\r
 845  *\r
 846  * Starts a real time kernel activity trace.  The trace logs the identity of\r
 847  * which task is running when.\r
 848  *\r
 849  * The trace file is stored in binary format.  A separate DOS utility called\r
 850  * convtrce.exe is used to convert this into a tab delimited text file which\r
 851  * can be viewed and plotted in a spread sheet.\r
 852  *\r
 853  * @param pcBuffer The buffer into which the trace will be written.\r
 854  *\r
 855  * @param ulBufferSize The size of pcBuffer in bytes.  The trace will continue\r
 856  * until either the buffer in full, or ulTaskEndTrace () is called.\r
 857  *\r
 858  * \page vTaskStartTrace vTaskStartTrace\r
 859  * \ingroup TaskUtils\r
 860  */\r
 861 void vTaskStartTrace( signed portCHAR * pcBuffer, unsigned portLONG ulBufferSize );\r
 862 \r
 863 /**\r
 864  * task. h\r
 865  * <PRE>unsigned portLONG ulTaskEndTrace( void );</PRE>\r
 866  *\r
 867  * Stops a kernel activity trace.  See vTaskStartTrace ().\r
 868  *\r
 869  * @return The number of bytes that have been written into the trace buffer.\r
 870  *\r
 871  * \page usTaskEndTrace usTaskEndTrace\r
 872  * \ingroup TaskUtils\r
 873  */\r
 874 unsigned portLONG ulTaskEndTrace( void );\r
 875 \r
 876 /**\r
 877  * task.h\r
 878  * <PRE>unsigned portBASE_TYPE uxTaskGetStackHighWaterMark( xTaskHandle xTask );</PRE>\r
 879  *\r
 880  * INCLUDE_uxTaskGetStackHighWaterMark must be set to 1 in FreeRTOSConfig.h for\r
 881  * this function to be available.\r
 882  *\r
 883  * Returns the high water mark of the stack associated with xTask.  That is,\r
 884  * the minimum free stack space there has been (in bytes) since the task\r
 885  * started.  The smaller the returned number the closer the task has come\r
 886  * to overflowing its stack.\r
 887  *\r
 888  * @param xTask Handle of the task associated with the stack to be checked.\r
 889  * Set xTask to NULL to check the stack of the calling task.\r
 890  *\r
 891  * @return The smallest amount of free stack space there has been (in bytes)\r
 892  * since the task referenced by xTask was created.\r
 893  */\r
 894 unsigned portBASE_TYPE uxTaskGetStackHighWaterMark( xTaskHandle xTask );\r
 895 \r
 896 /**\r
 897  * task.h\r
 898  * <pre>void vTaskSetApplicationTaskTag( xTaskHandle xTask, pdTASK_HOOK_CODE pxHookFunction );</pre>\r
 899  *\r
 900  * Sets pxHookFunction to be the task hook function used by the task xTask.\r
 901  * Passing xTask as NULL has the effect of setting the calling tasks hook\r
 902  * function.\r
 903  */\r
 904 void vTaskSetApplicationTaskTag( xTaskHandle xTask, pdTASK_HOOK_CODE pxHookFunction );\r
 905 \r
 906 /**\r
 907  * task.h\r
 908  * <pre>portBASE_TYPE xTaskCallApplicationTaskHook( xTaskHandle xTask, pdTASK_HOOK_CODE pxHookFunction );</pre>\r
 909  *\r
 910  * Calls the hook function associated with xTask.  Passing xTask as NULL has\r
 911  * the effect of calling the Running tasks (the calling task) hook function.\r
 912  *\r
 913  * pvParameter is passed to the hook function for the task to interpret as it\r
 914  * wants.\r
 915  */\r
 916 portBASE_TYPE xTaskCallApplicationTaskHook( xTaskHandle xTask, void *pvParameter );\r
 917 \r
 918 \r
 919 /*-----------------------------------------------------------\r
 920  * SCHEDULER INTERNALS AVAILABLE FOR PORTING PURPOSES\r
 921  *----------------------------------------------------------*/\r
 922 \r
 923 /*\r
 924  * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS ONLY\r
 925  * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS\r
 926  * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.\r
 927  *\r
 928  * Called from the real time kernel tick (either preemptive or cooperative),\r
 929  * this increments the tick count and checks if any tasks that are blocked\r
 930  * for a finite period required removing from a blocked list and placing on\r
 931  * a ready list.\r
 932  */\r
 933 inline void vTaskIncrementTick( void );\r
 934 \r
 935 /*\r
 936  * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS AN\r
 937  * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.\r
 938  *\r
 939  * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED.\r
 940  *\r
 941  * Removes the calling task from the ready list and places it both\r
 942  * on the list of tasks waiting for a particular event, and the\r
 943  * list of delayed tasks.  The task will be removed from both lists\r
 944  * and replaced on the ready list should either the event occur (and\r
 945  * there be no higher priority tasks waiting on the same event) or\r
 946  * the delay period expires.\r
 947  *\r
 948  * @param pxEventList The list containing tasks that are blocked waiting\r
 949  * for the event to occur.\r
 950  *\r
 951  * @param xTicksToWait The maximum amount of time that the task should wait\r
 952  * for the event to occur.  This is specified in kernel ticks,the constant\r
 953  * portTICK_RATE_MS can be used to convert kernel ticks into a real time\r
 954  * period.\r
 955  */\r
 956 void vTaskPlaceOnEventList( const xList * const pxEventList, portTickType xTicksToWait );\r
 957 \r
 958 /*\r
 959  * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS AN\r
 960  * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.\r
 961  *\r
 962  * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED.\r
 963  *\r
 964  * Removes a task from both the specified event list and the list of blocked\r
 965  * tasks, and places it on a ready queue.\r
 966  *\r
 967  * xTaskRemoveFromEventList () will be called if either an event occurs to\r
 968  * unblock a task, or the block timeout period expires.\r
 969  *\r
 970  * @return pdTRUE if the task being removed has a higher priority than the task\r
 971  * making the call, otherwise pdFALSE.\r
 972  */\r
 973 signed portBASE_TYPE xTaskRemoveFromEventList( const xList * const pxEventList );\r
 974 \r
 975 /*\r
 976  * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS AN\r
 977  * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.\r
 978  *\r
 979  * INCLUDE_vTaskCleanUpResources and INCLUDE_vTaskSuspend must be defined as 1\r
 980  * for this function to be available.\r
 981  * See the configuration section for more information.\r
 982  *\r
 983  * Empties the ready and delayed queues of task control blocks, freeing the\r
 984  * memory allocated for the task control block and task stacks as it goes.\r
 985  */\r
 986 void vTaskCleanUpResources( void );\r
 987 \r
 988 /*\r
 989  * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS ONLY\r
 990  * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS\r
 991  * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.\r
 992  *\r
 993  * Sets the pointer to the current TCB to the TCB of the highest priority task\r
 994  * that is ready to run.\r
 995  */\r
 996 inline void vTaskSwitchContext( void );\r
 997 \r
 998 /*\r
 999  * Return the handle of the calling task.\r
1000  */\r
1001 xTaskHandle xTaskGetCurrentTaskHandle( void );\r
1002 \r
1003 /*\r
1004  * Capture the current time status for future reference.\r
1005  */\r
1006 void vTaskSetTimeOutState( xTimeOutType * const pxTimeOut );\r
1007 \r
1008 /*\r
1009  * Compare the time status now with that previously captured to see if the\r
1010  * timeout has expired.\r
1011  */\r
1012 portBASE_TYPE xTaskCheckForTimeOut( xTimeOutType * const pxTimeOut, portTickType * const pxTicksToWait );\r
1013 \r
1014 /*\r
1015  * Shortcut used by the queue implementation to prevent unnecessary call to\r
1016  * taskYIELD();\r
1017  */\r
1018 void vTaskMissedYield( void );\r
1019 \r
1020 /*\r
1021  * Returns the scheduler state as taskSCHEDULER_RUNNING,\r
1022  * taskSCHEDULER_NOT_STARTED or taskSCHEDULER_SUSPENDED.\r
1023  */\r
1024 portBASE_TYPE xTaskGetSchedulerState( void );\r
1025 \r
1026 /*\r
1027  * Raises the priority of the mutex holder to that of the calling task should\r
1028  * the mutex holder have a priority less than the calling task.\r
1029  */\r
1030 void vTaskPriorityInherit( xTaskHandle * const pxMutexHolder );\r
1031 \r
1032 /*\r
1033  * Set the priority of a task back to its proper priority in the case that it\r
1034  * inherited a higher priority while it was holding a semaphore.\r
1035  */\r
1036 void vTaskPriorityDisinherit( xTaskHandle * const pxMutexHolder );\r
1037 \r
1038 #ifdef __cplusplus\r
1039 }\r
1040 #endif\r
1041 #endif /* TASK_H */\r
1042 \r
1043 \r
1044 \r