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