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

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