git.gag.com Git - fw/openalt/blob - FreeRTOS/include/task.h

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