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

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