FreeRTOS Real Time Operating System, Modified from Kenji Arai's initial port. See freertos.org for full documentation.

Fork of FreeRTOS_on_mbed_v1 by Kenji Arai

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers task.h Source File

task.h

00001 /*
00002     FreeRTOS V6.0.3 - Copyright (C) 2010 Real Time Engineers Ltd.
00003 
00004     ***************************************************************************
00005     *                                                                         *
00006     * If you are:                                                             *
00007     *                                                                         *
00008     *    + New to FreeRTOS,                                                   *
00009     *    + Wanting to learn FreeRTOS or multitasking in general quickly       *
00010     *    + Looking for basic training,                                        *
00011     *    + Wanting to improve your FreeRTOS skills and productivity           *
00012     *                                                                         *
00013     * then take a look at the FreeRTOS eBook                                  *
00014     *                                                                         *
00015     *        "Using the FreeRTOS Real Time Kernel - a Practical Guide"        *
00016     *                  http://www.FreeRTOS.org/Documentation                  *
00017     *                                                                         *
00018     * A pdf reference manual is also available.  Both are usually delivered   *
00019     * to your inbox within 20 minutes to two hours when purchased between 8am *
00020     * and 8pm GMT (although please allow up to 24 hours in case of            *
00021     * exceptional circumstances).  Thank you for your support!                *
00022     *                                                                         *
00023     ***************************************************************************
00024 
00025     This file is part of the FreeRTOS distribution.
00026 
00027     FreeRTOS is free software; you can redistribute it and/or modify it under
00028     the terms of the GNU General Public License (version 2) as published by the
00029     Free Software Foundation AND MODIFIED BY the FreeRTOS exception.
00030     ***NOTE*** The exception to the GPL is included to allow you to distribute
00031     a combined work that includes FreeRTOS without being obliged to provide the
00032     source code for proprietary components outside of the FreeRTOS kernel.
00033     FreeRTOS is distributed in the hope that it will be useful, but WITHOUT
00034     ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
00035     FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
00036     more details. You should have received a copy of the GNU General Public 
00037     License and the FreeRTOS license exception along with FreeRTOS; if not it 
00038     can be viewed here: http://www.freertos.org/a00114.html and also obtained 
00039     by writing to Richard Barry, contact details for whom are available on the
00040     FreeRTOS WEB site.
00041 
00042     1 tab == 4 spaces!
00043 
00044     http://www.FreeRTOS.org - Documentation, latest information, license and
00045     contact details.
00046 
00047     http://www.SafeRTOS.com - A version that is certified for use in safety
00048     critical systems.
00049 
00050     http://www.OpenRTOS.com - Commercial support, development, porting,
00051     licensing and training services.
00052 */
00053 
00054 
00055 #ifndef INC_FREERTOS_H
00056     #error "#include FreeRTOS.h" must appear in source files before "#include task.h"
00057 #endif
00058 
00059 
00060 
00061 #ifndef TASK_H
00062 #define TASK_H
00063 
00064 #include "portable.h"
00065 #include "list.h"
00066 
00067 #ifdef __cplusplus
00068 extern "C" {
00069 #endif
00070 
00071 /*-----------------------------------------------------------
00072  * MACROS AND DEFINITIONS
00073  *----------------------------------------------------------*/
00074 
00075 #define tskKERNEL_VERSION_NUMBER "V6.0.3"
00076 
00077 /**
00078  * task. h
00079  *
00080  * Type by which tasks are referenced.  For example, a call to xTaskCreate
00081  * returns (via a pointer parameter) an xTaskHandle variable that can then
00082  * be used as a parameter to vTaskDelete to delete the task.
00083  *
00084  * \page xTaskHandle xTaskHandle
00085  * \ingroup Tasks
00086  */
00087 typedef void * xTaskHandle;
00088 
00089 /*
00090  * Used internally only.
00091  */
00092 typedef struct xTIME_OUT
00093 {
00094     portBASE_TYPE xOverflowCount;
00095     portTickType  xTimeOnEntering;
00096 } xTimeOutType;
00097 
00098 /*
00099  * Defines the memory ranges allocated to the task when an MPU is used.
00100  */
00101 typedef struct xMEMORY_REGION
00102 {
00103     void *pvBaseAddress;
00104     unsigned long ulLengthInBytes;
00105     unsigned long ulParameters;
00106 } xMemoryRegion;
00107 
00108 #if 0
00109 //  modified by K.Arai Oct. 28th, 2010
00110 //  due to compile error!
00111 /*
00112  * Parameters required to create an MPU protected task.
00113  */
00114 typedef struct xTASK_PARAMTERS
00115 {
00116     pdTASK_CODE pvTaskCode;
00117     const signed char * const pcName;
00118     unsigned short usStackDepth;
00119     void *pvParameters;
00120     unsigned portBASE_TYPE uxPriority;
00121     portSTACK_TYPE *puxStackBuffer;
00122     xMemoryRegion xRegions[ portNUM_CONFIGURABLE_REGIONS ];
00123 } xTaskParameters;
00124 #endif
00125 
00126 /*
00127  * Defines the priority used by the idle task.  This must not be modified.
00128  *
00129  * \ingroup TaskUtils
00130  */
00131 #define tskIDLE_PRIORITY            ( ( unsigned portBASE_TYPE ) 0 )
00132 
00133 /**
00134  * task. h
00135  *
00136  * Macro for forcing a context switch.
00137  *
00138  * \page taskYIELD taskYIELD
00139  * \ingroup SchedulerControl
00140  */
00141 #define taskYIELD()                    portYIELD()
00142 
00143 /**
00144  * task. h
00145  *
00146  * Macro to mark the start of a critical code region.  Preemptive context
00147  * switches cannot occur when in a critical region.
00148  *
00149  * NOTE: This may alter the stack (depending on the portable implementation)
00150  * so must be used with care!
00151  *
00152  * \page taskENTER_CRITICAL taskENTER_CRITICAL
00153  * \ingroup SchedulerControl
00154  */
00155 #define taskENTER_CRITICAL()        portENTER_CRITICAL()
00156 
00157 /**
00158  * task. h
00159  *
00160  * Macro to mark the end of a critical code region.  Preemptive context
00161  * switches cannot occur when in a critical region.
00162  *
00163  * NOTE: This may alter the stack (depending on the portable implementation)
00164  * so must be used with care!
00165  *
00166  * \page taskEXIT_CRITICAL taskEXIT_CRITICAL
00167  * \ingroup SchedulerControl
00168  */
00169 #define taskEXIT_CRITICAL()            portEXIT_CRITICAL()
00170 
00171 /**
00172  * task. h
00173  *
00174  * Macro to disable all maskable interrupts.
00175  *
00176  * \page taskDISABLE_INTERRUPTS taskDISABLE_INTERRUPTS
00177  * \ingroup SchedulerControl
00178  */
00179 #define taskDISABLE_INTERRUPTS()    portDISABLE_INTERRUPTS()
00180 
00181 /**
00182  * task. h
00183  *
00184  * Macro to enable microcontroller interrupts.
00185  *
00186  * \page taskENABLE_INTERRUPTS taskENABLE_INTERRUPTS
00187  * \ingroup SchedulerControl
00188  */
00189 #define taskENABLE_INTERRUPTS()        portENABLE_INTERRUPTS()
00190 
00191 /* Definitions returned by xTaskGetSchedulerState(). */
00192 #define taskSCHEDULER_NOT_STARTED    0
00193 #define taskSCHEDULER_RUNNING        1
00194 #define taskSCHEDULER_SUSPENDED        2
00195 
00196 /*-----------------------------------------------------------
00197  * TASK CREATION API
00198  *----------------------------------------------------------*/
00199 
00200 /**
00201  * task. h
00202  *<pre>
00203  portBASE_TYPE xTaskCreate(
00204                               pdTASK_CODE pvTaskCode,
00205                               const char * const pcName,
00206                               unsigned short usStackDepth,
00207                               void *pvParameters,
00208                               unsigned portBASE_TYPE uxPriority,
00209                               xTaskHandle *pvCreatedTask
00210                           );</pre>
00211  *
00212  * Create a new task and add it to the list of tasks that are ready to run.
00213  * 
00214  * xTaskCreate() can only be used to create a task that has unrestricted
00215  * access to the entire microcontroller memory map.  Systems that include MPU
00216  * support can alternatively create an MPU constrained task using 
00217  * xTaskCreateRestricted().
00218  *
00219  * @param pvTaskCode Pointer to the task entry function.  Tasks
00220  * must be implemented to never return (i.e. continuous loop).
00221  *
00222  * @param pcName A descriptive name for the task.  This is mainly used to
00223  * facilitate debugging.  Max length defined by tskMAX_TASK_NAME_LEN - default
00224  * is 16.
00225  *
00226  * @param usStackDepth The size of the task stack specified as the number of
00227  * variables the stack can hold - not the number of bytes.  For example, if
00228  * the stack is 16 bits wide and usStackDepth is defined as 100, 200 bytes
00229  * will be allocated for stack storage.
00230  *
00231  * @param pvParameters Pointer that will be used as the parameter for the task
00232  * being created.
00233  *
00234  * @param uxPriority The priority at which the task should run.  Systems that
00235  * include MPU support can optionally create tasks in a privileged (system)
00236  * mode by setting bit portPRIVILEGE_BIT of the priority parameter.  For
00237  * example, to create a privileged task at priority 2 the uxPriority parameter
00238  * should be set to ( 2 | portPRIVILEGE_BIT ).
00239  *
00240  * @param pvCreatedTask Used to pass back a handle by which the created task
00241  * can be referenced.
00242  *
00243  * @return pdPASS if the task was successfully created and added to a ready
00244  * list, otherwise an error code defined in the file errors. h
00245  *
00246  * Example usage:
00247    <pre>
00248  // Task to be created.
00249  void vTaskCode( void * pvParameters )
00250  {
00251      for( ;; )
00252      {
00253          // Task code goes here.
00254      }
00255  }
00256 
00257  // Function that creates a task.
00258  void vOtherFunction( void )
00259  {
00260  static unsigned char ucParameterToPass;
00261  xTaskHandle xHandle;
00262 
00263      // Create the task, storing the handle.  Note that the passed parameter ucParameterToPass
00264      // must exist for the lifetime of the task, so in this case is declared static.  If it was just an
00265      // an automatic stack variable it might no longer exist, or at least have been corrupted, by the time
00266      // the new task attempts to access it.
00267      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, &ucParameterToPass, tskIDLE_PRIORITY, &xHandle );
00268 
00269      // Use the handle to delete the task.
00270      vTaskDelete( xHandle );
00271  }
00272    </pre>
00273  * \defgroup xTaskCreate xTaskCreate
00274  * \ingroup Tasks
00275  */
00276 #define xTaskCreate( pvTaskCode, pcName, usStackDepth, pvParameters, uxPriority, pxCreatedTask ) xTaskGenericCreate( ( pvTaskCode ), ( pcName ), ( usStackDepth ), ( pvParameters ), ( uxPriority ), ( pxCreatedTask ), ( NULL ), ( NULL ) )
00277 
00278 /**
00279  * task. h
00280  *<pre>
00281  portBASE_TYPE xTaskCreateRestricted( xTaskParameters *pxTaskDefinition, xTaskHandle *pxCreatedTask );</pre>
00282  *
00283  * xTaskCreateRestricted() should only be used in systems that include an MPU
00284  * implementation.
00285  *
00286  * Create a new task and add it to the list of tasks that are ready to run.
00287  * The function parameters define the memory regions and associated access
00288  * permissions allocated to the task.
00289  *
00290  * @param pxTaskDefinition Pointer to a structure that contains a member
00291  * for each of the normal xTaskCreate() parameters (see the xTaskCreate() API
00292  * documentation) plus an optional stack buffer and the memory region 
00293  * definitions.
00294  *
00295  * @param pxCreatedTask Used to pass back a handle by which the created task
00296  * can be referenced.
00297  *
00298  * @return pdPASS if the task was successfully created and added to a ready
00299  * list, otherwise an error code defined in the file errors. h
00300  *
00301  * Example usage:
00302    <pre>
00303 // Create an xTaskParameters structure that defines the task to be created.
00304 static const xTaskParameters xCheckTaskParameters =
00305 {
00306     vATask,        // pvTaskCode - the function that implements the task.
00307     "ATask",    // pcName - just a text name for the task to assist debugging.
00308     100,        // usStackDepth    - the stack size DEFINED IN WORDS.
00309     NULL,        // pvParameters - passed into the task function as the function parameters.
00310     ( 1UL | portPRIVILEGE_BIT ),// uxPriority - task priority, set the portPRIVILEGE_BIT if the task should run in a privileged state.
00311     cStackBuffer,// puxStackBuffer - the buffer to be used as the task stack.
00312 
00313     // xRegions - Allocate up to three separate memory regions for access by
00314     // the task, with appropriate access permissions.  Different processors have
00315     // different memory alignment requirements - refer to the FreeRTOS documentation
00316     // for full information.
00317     {                                            
00318         // Base address                    Length    Parameters
00319         { cReadWriteArray,                32,        portMPU_REGION_READ_WRITE },
00320         { cReadOnlyArray,                32,        portMPU_REGION_READ_ONLY },
00321         { cPrivilegedOnlyAccessArray,    128,    portMPU_REGION_PRIVILEGED_READ_WRITE }
00322     }
00323 };
00324 
00325 int main( void )
00326 {
00327 xTaskHandle xHandle;
00328 
00329     // Create a task from the const structure defined above.  The task handle
00330     // is requested (the second parameter is not NULL) but in this case just for
00331     // demonstration purposes as its not actually used.
00332     xTaskCreateRestricted( &xRegTest1Parameters, &xHandle );
00333 
00334     // Start the scheduler.
00335     vTaskStartScheduler();
00336 
00337     // Will only get here if there was insufficient memory to create the idle
00338     // task.
00339     for( ;; );
00340 }
00341    </pre>
00342  * \defgroup xTaskCreateRestricted xTaskCreateRestricted
00343  * \ingroup Tasks
00344  */
00345 #define xTaskCreateRestricted( x, pxCreatedTask ) xTaskGenericCreate( ((x)->pvTaskCode), ((x)->pcName), ((x)->usStackDepth), ((x)->pvParameters), ((x)->uxPriority), (pxCreatedTask), ((x)->puxStackBuffer), ((x)->xRegions) )
00346 
00347 /**
00348  * task. h
00349  *<pre>
00350  void vTaskAllocateMPURegions( xTaskHandle xTask, const xMemoryRegion * const pxRegions );</pre>
00351  *
00352  * Memory regions are assigned to a restricted task when the task is created by
00353  * a call to xTaskCreateRestricted().  These regions can be redefined using
00354  * vTaskAllocateMPURegions().
00355  * 
00356  * @param xTask The handle of the task being updated.
00357  *
00358  * @param xRegions A pointer to an xMemoryRegion structure that contains the
00359  * new memory region definitions.
00360  *
00361  * Example usage:
00362    <pre>
00363 // Define an array of xMemoryRegion structures that configures an MPU region
00364 // allowing read/write access for 1024 bytes starting at the beginning of the
00365 // ucOneKByte array.  The other two of the maximum 3 definable regions are
00366 // unused so set to zero.
00367 static const xMemoryRegion xAltRegions[ portNUM_CONFIGURABLE_REGIONS ] =
00368 {                                            
00369     // Base address        Length        Parameters
00370     { ucOneKByte,        1024,        portMPU_REGION_READ_WRITE },
00371     { 0,                0,            0 },
00372     { 0,                0,            0 }
00373 };
00374 
00375 void vATask( void *pvParameters )
00376 {
00377     // This task was created such that it has access to certain regions of
00378     // memory as defined by the MPU configuration.  At some point it is 
00379     // desired that these MPU regions are replaced with that defined in the
00380     // xAltRegions const struct above.  Use a call to vTaskAllocateMPURegions()
00381     // for this purpose.  NULL is used as the task handle to indicate that this
00382     // function should modify the MPU regions of the calling task.
00383     vTaskAllocateMPURegions( NULL, xAltRegions );
00384     
00385     // Now the task can continue its function, but from this point on can only
00386     // access its stack and the ucOneKByte array (unless any other statically
00387     // defined or shared regions have been declared elsewhere).
00388 }
00389    </pre>
00390  * \defgroup xTaskCreateRestricted xTaskCreateRestricted
00391  * \ingroup Tasks
00392  */
00393 void vTaskAllocateMPURegions( xTaskHandle xTask, const xMemoryRegion * const pxRegions ) PRIVILEGED_FUNCTION;
00394 
00395 /**
00396  * task. h
00397  * <pre>void vTaskDelete( xTaskHandle pxTask );</pre>
00398  *
00399  * INCLUDE_vTaskDelete must be defined as 1 for this function to be available.
00400  * See the configuration section for more information.
00401  *
00402  * Remove a task from the RTOS real time kernels management.  The task being
00403  * deleted will be removed from all ready, blocked, suspended and event lists.
00404  *
00405  * NOTE:  The idle task is responsible for freeing the kernel allocated
00406  * memory from tasks that have been deleted.  It is therefore important that
00407  * the idle task is not starved of microcontroller processing time if your
00408  * application makes any calls to vTaskDelete ().  Memory allocated by the
00409  * task code is not automatically freed, and should be freed before the task
00410  * is deleted.
00411  *
00412  * See the demo application file death.c for sample code that utilises
00413  * vTaskDelete ().
00414  *
00415  * @param pxTask The handle of the task to be deleted.  Passing NULL will
00416  * cause the calling task to be deleted.
00417  *
00418  * Example usage:
00419    <pre>
00420  void vOtherFunction( void )
00421  {
00422  xTaskHandle xHandle;
00423 
00424      // Create the task, storing the handle.
00425      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
00426 
00427      // Use the handle to delete the task.
00428      vTaskDelete( xHandle );
00429  }
00430    </pre>
00431  * \defgroup vTaskDelete vTaskDelete
00432  * \ingroup Tasks
00433  */
00434 void vTaskDelete( xTaskHandle pxTask ) PRIVILEGED_FUNCTION;
00435 
00436 
00437 /*-----------------------------------------------------------
00438  * TASK CONTROL API
00439  *----------------------------------------------------------*/
00440 
00441 /**
00442  * task. h
00443  * <pre>void vTaskDelay( portTickType xTicksToDelay );</pre>
00444  *
00445  * Delay a task for a given number of ticks.  The actual time that the
00446  * task remains blocked depends on the tick rate.  The constant
00447  * portTICK_RATE_MS can be used to calculate real time from the tick
00448  * rate - with the resolution of one tick period.
00449  *
00450  * INCLUDE_vTaskDelay must be defined as 1 for this function to be available.
00451  * See the configuration section for more information.
00452  *
00453  *
00454  * vTaskDelay() specifies a time at which the task wishes to unblock relative to
00455  * the time at which vTaskDelay() is called.  For example, specifying a block
00456  * period of 100 ticks will cause the task to unblock 100 ticks after
00457  * vTaskDelay() is called.  vTaskDelay() does not therefore provide a good method
00458  * of controlling the frequency of a cyclical task as the path taken through the
00459  * code, as well as other task and interrupt activity, will effect the frequency
00460  * at which vTaskDelay() gets called and therefore the time at which the task
00461  * next executes.  See vTaskDelayUntil() for an alternative API function designed
00462  * to facilitate fixed frequency execution.  It does this by specifying an
00463  * absolute time (rather than a relative time) at which the calling task should
00464  * unblock.
00465  *
00466  * @param xTicksToDelay The amount of time, in tick periods, that
00467  * the calling task should block.
00468  *
00469  * Example usage:
00470 
00471  void vTaskFunction( void * pvParameters )
00472  {
00473  void vTaskFunction( void * pvParameters )
00474  {
00475  // Block for 500ms.
00476  const portTickType xDelay = 500 / portTICK_RATE_MS;
00477 
00478      for( ;; )
00479      {
00480          // Simply toggle the LED every 500ms, blocking between each toggle.
00481          vToggleLED();
00482          vTaskDelay( xDelay );
00483      }
00484  }
00485 
00486  * \defgroup vTaskDelay vTaskDelay
00487  * \ingroup TaskCtrl
00488  */
00489 void vTaskDelay( portTickType xTicksToDelay ) PRIVILEGED_FUNCTION;
00490 
00491 /**
00492  * task. h
00493  * <pre>void vTaskDelayUntil( portTickType *pxPreviousWakeTime, portTickType xTimeIncrement );</pre>
00494  *
00495  * INCLUDE_vTaskDelayUntil must be defined as 1 for this function to be available.
00496  * See the configuration section for more information.
00497  *
00498  * Delay a task until a specified time.  This function can be used by cyclical
00499  * tasks to ensure a constant execution frequency.
00500  *
00501  * This function differs from vTaskDelay () in one important aspect:  vTaskDelay () will
00502  * cause a task to block for the specified number of ticks from the time vTaskDelay () is
00503  * called.  It is therefore difficult to use vTaskDelay () by itself to generate a fixed
00504  * execution frequency as the time between a task starting to execute and that task
00505  * calling vTaskDelay () may not be fixed [the task may take a different path though the
00506  * code between calls, or may get interrupted or preempted a different number of times
00507  * each time it executes].
00508  *
00509  * Whereas vTaskDelay () specifies a wake time relative to the time at which the function
00510  * is called, vTaskDelayUntil () specifies the absolute (exact) time at which it wishes to
00511  * unblock.
00512  *
00513  * The constant portTICK_RATE_MS can be used to calculate real time from the tick
00514  * rate - with the resolution of one tick period.
00515  *
00516  * @param pxPreviousWakeTime Pointer to a variable that holds the time at which the
00517  * task was last unblocked.  The variable must be initialised with the current time
00518  * prior to its first use (see the example below).  Following this the variable is
00519  * automatically updated within vTaskDelayUntil ().
00520  *
00521  * @param xTimeIncrement The cycle time period.  The task will be unblocked at
00522  * time *pxPreviousWakeTime + xTimeIncrement.  Calling vTaskDelayUntil with the
00523  * same xTimeIncrement parameter value will cause the task to execute with
00524  * a fixed interface period.
00525  *
00526  * Example usage:
00527    <pre>
00528  // Perform an action every 10 ticks.
00529  void vTaskFunction( void * pvParameters )
00530  {
00531  portTickType xLastWakeTime;
00532  const portTickType xFrequency = 10;
00533 
00534      // Initialise the xLastWakeTime variable with the current time.
00535      xLastWakeTime = xTaskGetTickCount ();
00536      for( ;; )
00537      {
00538          // Wait for the next cycle.
00539          vTaskDelayUntil( &xLastWakeTime, xFrequency );
00540 
00541          // Perform action here.
00542      }
00543  }
00544    </pre>
00545  * \defgroup vTaskDelayUntil vTaskDelayUntil
00546  * \ingroup TaskCtrl
00547  */
00548 void vTaskDelayUntil( portTickType * const pxPreviousWakeTime, portTickType xTimeIncrement ) PRIVILEGED_FUNCTION;
00549 
00550 /**
00551  * task. h
00552  * <pre>unsigned portBASE_TYPE uxTaskPriorityGet( xTaskHandle pxTask );</pre>
00553  *
00554  * INCLUDE_xTaskPriorityGet must be defined as 1 for this function to be available.
00555  * See the configuration section for more information.
00556  *
00557  * Obtain the priority of any task.
00558  *
00559  * @param pxTask Handle of the task to be queried.  Passing a NULL
00560  * handle results in the priority of the calling task being returned.
00561  *
00562  * @return The priority of pxTask.
00563  *
00564  * Example usage:
00565    <pre>
00566  void vAFunction( void )
00567  {
00568  xTaskHandle xHandle;
00569 
00570      // Create a task, storing the handle.
00571      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
00572 
00573      // ...
00574 
00575      // Use the handle to obtain the priority of the created task.
00576      // It was created with tskIDLE_PRIORITY, but may have changed
00577      // it itself.
00578      if( uxTaskPriorityGet( xHandle ) != tskIDLE_PRIORITY )
00579      {
00580          // The task has changed it's priority.
00581      }
00582 
00583      // ...
00584 
00585      // Is our priority higher than the created task?
00586      if( uxTaskPriorityGet( xHandle ) < uxTaskPriorityGet( NULL ) )
00587      {
00588          // Our priority (obtained using NULL handle) is higher.
00589      }
00590  }
00591    </pre>
00592  * \defgroup uxTaskPriorityGet uxTaskPriorityGet
00593  * \ingroup TaskCtrl
00594  */
00595 unsigned portBASE_TYPE uxTaskPriorityGet( xTaskHandle pxTask ) PRIVILEGED_FUNCTION;
00596 
00597 /**
00598  * task. h
00599  * <pre>void vTaskPrioritySet( xTaskHandle pxTask, unsigned portBASE_TYPE uxNewPriority );</pre>
00600  *
00601  * INCLUDE_vTaskPrioritySet must be defined as 1 for this function to be available.
00602  * See the configuration section for more information.
00603  *
00604  * Set the priority of any task.
00605  *
00606  * A context switch will occur before the function returns if the priority
00607  * being set is higher than the currently executing task.
00608  *
00609  * @param pxTask Handle to the task for which the priority is being set.
00610  * Passing a NULL handle results in the priority of the calling task being set.
00611  *
00612  * @param uxNewPriority The priority to which the task will be set.
00613  *
00614  * Example usage:
00615    <pre>
00616  void vAFunction( void )
00617  {
00618  xTaskHandle xHandle;
00619 
00620      // Create a task, storing the handle.
00621      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
00622 
00623      // ...
00624 
00625      // Use the handle to raise the priority of the created task.
00626      vTaskPrioritySet( xHandle, tskIDLE_PRIORITY + 1 );
00627 
00628      // ...
00629 
00630      // Use a NULL handle to raise our priority to the same value.
00631      vTaskPrioritySet( NULL, tskIDLE_PRIORITY + 1 );
00632  }
00633    </pre>
00634  * \defgroup vTaskPrioritySet vTaskPrioritySet
00635  * \ingroup TaskCtrl
00636  */
00637 void vTaskPrioritySet( xTaskHandle pxTask, unsigned portBASE_TYPE uxNewPriority ) PRIVILEGED_FUNCTION;
00638 
00639 /**
00640  * task. h
00641  * <pre>void vTaskSuspend( xTaskHandle pxTaskToSuspend );</pre>
00642  *
00643  * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available.
00644  * See the configuration section for more information.
00645  *
00646  * Suspend any task.  When suspended a task will never get any microcontroller
00647  * processing time, no matter what its priority.
00648  *
00649  * Calls to vTaskSuspend are not accumulative -
00650  * i.e. calling vTaskSuspend () twice on the same task still only requires one
00651  * call to vTaskResume () to ready the suspended task.
00652  *
00653  * @param pxTaskToSuspend Handle to the task being suspended.  Passing a NULL
00654  * handle will cause the calling task to be suspended.
00655  *
00656  * Example usage:
00657    <pre>
00658  void vAFunction( void )
00659  {
00660  xTaskHandle xHandle;
00661 
00662      // Create a task, storing the handle.
00663      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
00664 
00665      // ...
00666 
00667      // Use the handle to suspend the created task.
00668      vTaskSuspend( xHandle );
00669 
00670      // ...
00671 
00672      // The created task will not run during this period, unless
00673      // another task calls vTaskResume( xHandle ).
00674 
00675      //...
00676 
00677 
00678      // Suspend ourselves.
00679      vTaskSuspend( NULL );
00680 
00681      // We cannot get here unless another task calls vTaskResume
00682      // with our handle as the parameter.
00683  }
00684    </pre>
00685  * \defgroup vTaskSuspend vTaskSuspend
00686  * \ingroup TaskCtrl
00687  */
00688 void vTaskSuspend( xTaskHandle pxTaskToSuspend ) PRIVILEGED_FUNCTION;
00689 
00690 /**
00691  * task. h
00692  * <pre>void vTaskResume( xTaskHandle pxTaskToResume );</pre>
00693  *
00694  * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available.
00695  * See the configuration section for more information.
00696  *
00697  * Resumes a suspended task.
00698  *
00699  * A task that has been suspended by one of more calls to vTaskSuspend ()
00700  * will be made available for running again by a single call to
00701  * vTaskResume ().
00702  *
00703  * @param pxTaskToResume Handle to the task being readied.
00704  *
00705  * Example usage:
00706    <pre>
00707  void vAFunction( void )
00708  {
00709  xTaskHandle xHandle;
00710 
00711      // Create a task, storing the handle.
00712      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
00713 
00714      // ...
00715 
00716      // Use the handle to suspend the created task.
00717      vTaskSuspend( xHandle );
00718 
00719      // ...
00720 
00721      // The created task will not run during this period, unless
00722      // another task calls vTaskResume( xHandle ).
00723 
00724      //...
00725 
00726 
00727      // Resume the suspended task ourselves.
00728      vTaskResume( xHandle );
00729 
00730      // The created task will once again get microcontroller processing
00731      // time in accordance with it priority within the system.
00732  }
00733    </pre>
00734  * \defgroup vTaskResume vTaskResume
00735  * \ingroup TaskCtrl
00736  */
00737 void vTaskResume( xTaskHandle pxTaskToResume ) PRIVILEGED_FUNCTION;
00738 
00739 /**
00740  * task. h
00741  * <pre>void xTaskResumeFromISR( xTaskHandle pxTaskToResume );</pre>
00742  *
00743  * INCLUDE_xTaskResumeFromISR must be defined as 1 for this function to be
00744  * available.  See the configuration section for more information.
00745  *
00746  * An implementation of vTaskResume() that can be called from within an ISR.
00747  *
00748  * A task that has been suspended by one of more calls to vTaskSuspend ()
00749  * will be made available for running again by a single call to
00750  * xTaskResumeFromISR ().
00751  *
00752  * @param pxTaskToResume Handle to the task being readied.
00753  *
00754  * \defgroup vTaskResumeFromISR vTaskResumeFromISR
00755  * \ingroup TaskCtrl
00756  */
00757 portBASE_TYPE xTaskResumeFromISR( xTaskHandle pxTaskToResume ) PRIVILEGED_FUNCTION;
00758 
00759 /*-----------------------------------------------------------
00760  * SCHEDULER CONTROL
00761  *----------------------------------------------------------*/
00762 
00763 /**
00764  * task. h
00765  * <pre>void vTaskStartScheduler( void );</pre>
00766  *
00767  * Starts the real time kernel tick processing.  After calling the kernel
00768  * has control over which tasks are executed and when.  This function
00769  * does not return until an executing task calls vTaskEndScheduler ().
00770  *
00771  * At least one task should be created via a call to xTaskCreate ()
00772  * before calling vTaskStartScheduler ().  The idle task is created
00773  * automatically when the first application task is created.
00774  *
00775  * See the demo application file main.c for an example of creating
00776  * tasks and starting the kernel.
00777  *
00778  * Example usage:
00779    <pre>
00780  void vAFunction( void )
00781  {
00782      // Create at least one task before starting the kernel.
00783      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL );
00784 
00785      // Start the real time kernel with preemption.
00786      vTaskStartScheduler ();
00787 
00788      // Will not get here unless a task calls vTaskEndScheduler ()
00789  }
00790    </pre>
00791  *
00792  * \defgroup vTaskStartScheduler vTaskStartScheduler
00793  * \ingroup SchedulerControl
00794  */
00795 void vTaskStartScheduler( void ) PRIVILEGED_FUNCTION;
00796 
00797 /**
00798  * task. h
00799  * <pre>void vTaskEndScheduler( void );</pre>
00800  *
00801  * Stops the real time kernel tick.  All created tasks will be automatically
00802  * deleted and multitasking (either preemptive or cooperative) will
00803  * stop.  Execution then resumes from the point where vTaskStartScheduler ()
00804  * was called, as if vTaskStartScheduler () had just returned.
00805  *
00806  * See the demo application file main. c in the demo/PC directory for an
00807  * example that uses vTaskEndScheduler ().
00808  *
00809  * vTaskEndScheduler () requires an exit function to be defined within the
00810  * portable layer (see vPortEndScheduler () in port. c for the PC port).  This
00811  * performs hardware specific operations such as stopping the kernel tick.
00812  *
00813  * vTaskEndScheduler () will cause all of the resources allocated by the
00814  * kernel to be freed - but will not free resources allocated by application
00815  * tasks.
00816  *
00817  * Example usage:
00818    <pre>
00819  void vTaskCode( void * pvParameters )
00820  {
00821      for( ;; )
00822      {
00823          // Task code goes here.
00824 
00825          // At some point we want to end the real time kernel processing
00826          // so call ...
00827          vTaskEndScheduler ();
00828      }
00829  }
00830 
00831  void vAFunction( void )
00832  {
00833      // Create at least one task before starting the kernel.
00834      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL );
00835 
00836      // Start the real time kernel with preemption.
00837      vTaskStartScheduler ();
00838 
00839      // Will only get here when the vTaskCode () task has called
00840      // vTaskEndScheduler ().  When we get here we are back to single task
00841      // execution.
00842  }
00843    </pre>
00844  *
00845  * \defgroup vTaskEndScheduler vTaskEndScheduler
00846  * \ingroup SchedulerControl
00847  */
00848 void vTaskEndScheduler( void ) PRIVILEGED_FUNCTION;
00849 
00850 /**
00851  * task. h
00852  * <pre>void vTaskSuspendAll( void );</pre>
00853  *
00854  * Suspends all real time kernel activity while keeping interrupts (including the
00855  * kernel tick) enabled.
00856  *
00857  * After calling vTaskSuspendAll () the calling task will continue to execute
00858  * without risk of being swapped out until a call to xTaskResumeAll () has been
00859  * made.
00860  *
00861  * API functions that have the potential to cause a context switch (for example,
00862  * vTaskDelayUntil(), xQueueSend(), etc.) must not be called while the scheduler
00863  * is suspended.
00864  *
00865  * Example usage:
00866    <pre>
00867  void vTask1( void * pvParameters )
00868  {
00869      for( ;; )
00870      {
00871          // Task code goes here.
00872 
00873          // ...
00874 
00875          // At some point the task wants to perform a long operation during
00876          // which it does not want to get swapped out.  It cannot use
00877          // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the
00878          // operation may cause interrupts to be missed - including the
00879          // ticks.
00880 
00881          // Prevent the real time kernel swapping out the task.
00882          vTaskSuspendAll ();
00883 
00884          // Perform the operation here.  There is no need to use critical
00885          // sections as we have all the microcontroller processing time.
00886          // During this time interrupts will still operate and the kernel
00887          // tick count will be maintained.
00888 
00889          // ...
00890 
00891          // The operation is complete.  Restart the kernel.
00892          xTaskResumeAll ();
00893      }
00894  }
00895    </pre>
00896  * \defgroup vTaskSuspendAll vTaskSuspendAll
00897  * \ingroup SchedulerControl
00898  */
00899 void vTaskSuspendAll( void ) PRIVILEGED_FUNCTION;
00900 
00901 /**
00902  * task. h
00903  * <pre>char xTaskResumeAll( void );</pre>
00904  *
00905  * Resumes real time kernel activity following a call to vTaskSuspendAll ().
00906  * After a call to vTaskSuspendAll () the kernel will take control of which
00907  * task is executing at any time.
00908  *
00909  * @return If resuming the scheduler caused a context switch then pdTRUE is
00910  *          returned, otherwise pdFALSE is returned.
00911  *
00912  * Example usage:
00913    <pre>
00914  void vTask1( void * pvParameters )
00915  {
00916      for( ;; )
00917      {
00918          // Task code goes here.
00919 
00920          // ...
00921 
00922          // At some point the task wants to perform a long operation during
00923          // which it does not want to get swapped out.  It cannot use
00924          // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the
00925          // operation may cause interrupts to be missed - including the
00926          // ticks.
00927 
00928          // Prevent the real time kernel swapping out the task.
00929          vTaskSuspendAll ();
00930 
00931          // Perform the operation here.  There is no need to use critical
00932          // sections as we have all the microcontroller processing time.
00933          // During this time interrupts will still operate and the real
00934          // time kernel tick count will be maintained.
00935 
00936          // ...
00937 
00938          // The operation is complete.  Restart the kernel.  We want to force
00939          // a context switch - but there is no point if resuming the scheduler
00940          // caused a context switch already.
00941          if( !xTaskResumeAll () )
00942          {
00943               taskYIELD ();
00944          }
00945      }
00946  }
00947    </pre>
00948  * \defgroup xTaskResumeAll xTaskResumeAll
00949  * \ingroup SchedulerControl
00950  */
00951 signed portBASE_TYPE xTaskResumeAll( void ) PRIVILEGED_FUNCTION;
00952 
00953 /**
00954  * task. h
00955  * <pre>signed portBASE_TYPE xTaskIsTaskSuspended( xTaskHandle xTask );</pre>
00956  *
00957  * Utility task that simply returns pdTRUE if the task referenced by xTask is
00958  * currently in the Suspended state, or pdFALSE if the task referenced by xTask
00959  * is in any other state.
00960  *
00961  */
00962 signed portBASE_TYPE xTaskIsTaskSuspended( xTaskHandle xTask ) PRIVILEGED_FUNCTION;
00963 
00964 /*-----------------------------------------------------------
00965  * TASK UTILITIES
00966  *----------------------------------------------------------*/
00967 
00968 /**
00969  * task. h
00970  * <PRE>volatile portTickType xTaskGetTickCount( void );</PRE>
00971  *
00972  * @return The count of ticks since vTaskStartScheduler was called.
00973  *
00974  * \page xTaskGetTickCount xTaskGetTickCount
00975  * \ingroup TaskUtils
00976  */
00977 portTickType xTaskGetTickCount( void ) PRIVILEGED_FUNCTION;
00978 
00979 /**
00980  * task. h
00981  * <PRE>unsigned short uxTaskGetNumberOfTasks( void );</PRE>
00982  *
00983  * @return The number of tasks that the real time kernel is currently managing.
00984  * This includes all ready, blocked and suspended tasks.  A task that
00985  * has been deleted but not yet freed by the idle task will also be
00986  * included in the count.
00987  *
00988  * \page uxTaskGetNumberOfTasks uxTaskGetNumberOfTasks
00989  * \ingroup TaskUtils
00990  */
00991 unsigned portBASE_TYPE uxTaskGetNumberOfTasks( void ) PRIVILEGED_FUNCTION;
00992 
00993 /**
00994  * task. h
00995  * <PRE>void vTaskList( char *pcWriteBuffer );</PRE>
00996  *
00997  * configUSE_TRACE_FACILITY must be defined as 1 for this function to be
00998  * available.  See the configuration section for more information.
00999  *
01000  * NOTE: This function will disable interrupts for its duration.  It is
01001  * not intended for normal application runtime use but as a debug aid.
01002  *
01003  * Lists all the current tasks, along with their current state and stack
01004  * usage high water mark.
01005  *
01006  * Tasks are reported as blocked ('B'), ready ('R'), deleted ('D') or
01007  * suspended ('S').
01008  *
01009  * @param pcWriteBuffer A buffer into which the above mentioned details
01010  * will be written, in ascii form.  This buffer is assumed to be large
01011  * enough to contain the generated report.  Approximately 40 bytes per
01012  * task should be sufficient.
01013  *
01014  * \page vTaskList vTaskList
01015  * \ingroup TaskUtils
01016  */
01017 void vTaskList( signed char *pcWriteBuffer ) PRIVILEGED_FUNCTION;
01018 
01019 /**
01020  * task. h
01021  * <PRE>void vTaskGetRunTimeStats( char *pcWriteBuffer );</PRE>
01022  *
01023  * configGENERATE_RUN_TIME_STATS must be defined as 1 for this function
01024  * to be available.  The application must also then provide definitions
01025  * for portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and
01026  * portGET_RUN_TIME_COUNTER_VALUE to configure a peripheral timer/counter
01027  * and return the timers current count value respectively.  The counter
01028  * should be at least 10 times the frequency of the tick count.
01029  *
01030  * NOTE: This function will disable interrupts for its duration.  It is
01031  * not intended for normal application runtime use but as a debug aid.
01032  *
01033  * Setting configGENERATE_RUN_TIME_STATS to 1 will result in a total
01034  * accumulated execution time being stored for each task.  The resolution
01035  * of the accumulated time value depends on the frequency of the timer
01036  * configured by the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() macro.
01037  * Calling vTaskGetRunTimeStats() writes the total execution time of each
01038  * task into a buffer, both as an absolute count value and as a percentage
01039  * of the total system execution time.
01040  *
01041  * @param pcWriteBuffer A buffer into which the execution times will be
01042  * written, in ascii form.  This buffer is assumed to be large enough to
01043  * contain the generated report.  Approximately 40 bytes per task should
01044  * be sufficient.
01045  *
01046  * \page vTaskGetRunTimeStats vTaskGetRunTimeStats
01047  * \ingroup TaskUtils
01048  */
01049 void vTaskGetRunTimeStats( signed char *pcWriteBuffer ) PRIVILEGED_FUNCTION;
01050 
01051 /**
01052  * task. h
01053  * <PRE>void vTaskStartTrace( char * pcBuffer, unsigned portBASE_TYPE uxBufferSize );</PRE>
01054  *
01055  * Starts a real time kernel activity trace.  The trace logs the identity of
01056  * which task is running when.
01057  *
01058  * The trace file is stored in binary format.  A separate DOS utility called
01059  * convtrce.exe is used to convert this into a tab delimited text file which
01060  * can be viewed and plotted in a spread sheet.
01061  *
01062  * @param pcBuffer The buffer into which the trace will be written.
01063  *
01064  * @param ulBufferSize The size of pcBuffer in bytes.  The trace will continue
01065  * until either the buffer in full, or ulTaskEndTrace () is called.
01066  *
01067  * \page vTaskStartTrace vTaskStartTrace
01068  * \ingroup TaskUtils
01069  */
01070 void vTaskStartTrace( signed char * pcBuffer, unsigned long ulBufferSize ) PRIVILEGED_FUNCTION;
01071 
01072 /**
01073  * task. h
01074  * <PRE>unsigned long ulTaskEndTrace( void );</PRE>
01075  *
01076  * Stops a kernel activity trace.  See vTaskStartTrace ().
01077  *
01078  * @return The number of bytes that have been written into the trace buffer.
01079  *
01080  * \page usTaskEndTrace usTaskEndTrace
01081  * \ingroup TaskUtils
01082  */
01083 unsigned long ulTaskEndTrace( void ) PRIVILEGED_FUNCTION;
01084 
01085 /**
01086  * task.h
01087  * <PRE>unsigned portBASE_TYPE uxTaskGetStackHighWaterMark( xTaskHandle xTask );</PRE>
01088  *
01089  * INCLUDE_uxTaskGetStackHighWaterMark must be set to 1 in FreeRTOSConfig.h for
01090  * this function to be available.
01091  *
01092  * Returns the high water mark of the stack associated with xTask.  That is,
01093  * the minimum free stack space there has been (in bytes) since the task
01094  * started.  The smaller the returned number the closer the task has come
01095  * to overflowing its stack.
01096  *
01097  * @param xTask Handle of the task associated with the stack to be checked.
01098  * Set xTask to NULL to check the stack of the calling task.
01099  *
01100  * @return The smallest amount of free stack space there has been (in bytes)
01101  * since the task referenced by xTask was created.
01102  */
01103 unsigned portBASE_TYPE uxTaskGetStackHighWaterMark( xTaskHandle xTask ) PRIVILEGED_FUNCTION;
01104 
01105 /**
01106  * task.h
01107  * <pre>void vTaskSetApplicationTaskTag( xTaskHandle xTask, pdTASK_HOOK_CODE pxHookFunction );</pre>
01108  *
01109  * Sets pxHookFunction to be the task hook function used by the task xTask.
01110  * Passing xTask as NULL has the effect of setting the calling tasks hook
01111  * function.
01112  */
01113 void vTaskSetApplicationTaskTag( xTaskHandle xTask, pdTASK_HOOK_CODE pxHookFunction ) PRIVILEGED_FUNCTION;
01114 
01115 /**
01116  * task.h
01117  * <pre>void xTaskGetApplicationTaskTag( xTaskHandle xTask );</pre>
01118  *
01119  * Returns the pxHookFunction value assigned to the task xTask.
01120  */
01121 pdTASK_HOOK_CODE xTaskGetApplicationTaskTag( xTaskHandle xTask ) PRIVILEGED_FUNCTION;
01122 
01123 /**
01124  * task.h
01125  * <pre>portBASE_TYPE xTaskCallApplicationTaskHook( xTaskHandle xTask, pdTASK_HOOK_CODE pxHookFunction );</pre>
01126  *
01127  * Calls the hook function associated with xTask.  Passing xTask as NULL has
01128  * the effect of calling the Running tasks (the calling task) hook function.
01129  *
01130  * pvParameter is passed to the hook function for the task to interpret as it
01131  * wants.
01132  */
01133 portBASE_TYPE xTaskCallApplicationTaskHook( xTaskHandle xTask, void *pvParameter ) PRIVILEGED_FUNCTION;
01134 
01135 
01136 /*-----------------------------------------------------------
01137  * SCHEDULER INTERNALS AVAILABLE FOR PORTING PURPOSES
01138  *----------------------------------------------------------*/
01139 
01140 /*
01141  * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS ONLY
01142  * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS
01143  * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
01144  *
01145  * Called from the real time kernel tick (either preemptive or cooperative),
01146  * this increments the tick count and checks if any tasks that are blocked
01147  * for a finite period required removing from a blocked list and placing on
01148  * a ready list.
01149  */
01150 void vTaskIncrementTick( void ) PRIVILEGED_FUNCTION;
01151 
01152 /*
01153  * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS AN
01154  * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
01155  *
01156  * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED.
01157  *
01158  * Removes the calling task from the ready list and places it both
01159  * on the list of tasks waiting for a particular event, and the
01160  * list of delayed tasks.  The task will be removed from both lists
01161  * and replaced on the ready list should either the event occur (and
01162  * there be no higher priority tasks waiting on the same event) or
01163  * the delay period expires.
01164  *
01165  * @param pxEventList The list containing tasks that are blocked waiting
01166  * for the event to occur.
01167  *
01168  * @param xTicksToWait The maximum amount of time that the task should wait
01169  * for the event to occur.  This is specified in kernel ticks,the constant
01170  * portTICK_RATE_MS can be used to convert kernel ticks into a real time
01171  * period.
01172  */
01173 void vTaskPlaceOnEventList( const xList * const pxEventList, portTickType xTicksToWait ) PRIVILEGED_FUNCTION;
01174 
01175 /*
01176  * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS AN
01177  * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
01178  *
01179  * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED.
01180  *
01181  * Removes a task from both the specified event list and the list of blocked
01182  * tasks, and places it on a ready queue.
01183  *
01184  * xTaskRemoveFromEventList () will be called if either an event occurs to
01185  * unblock a task, or the block timeout period expires.
01186  *
01187  * @return pdTRUE if the task being removed has a higher priority than the task
01188  * making the call, otherwise pdFALSE.
01189  */
01190 signed portBASE_TYPE xTaskRemoveFromEventList( const xList * const pxEventList ) PRIVILEGED_FUNCTION;
01191 
01192 /*
01193  * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS AN
01194  * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
01195  *
01196  * INCLUDE_vTaskCleanUpResources and INCLUDE_vTaskSuspend must be defined as 1
01197  * for this function to be available.
01198  * See the configuration section for more information.
01199  *
01200  * Empties the ready and delayed queues of task control blocks, freeing the
01201  * memory allocated for the task control block and task stacks as it goes.
01202  */
01203 void vTaskCleanUpResources( void ) PRIVILEGED_FUNCTION;
01204 
01205 /*
01206  * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS ONLY
01207  * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS
01208  * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
01209  *
01210  * Sets the pointer to the current TCB to the TCB of the highest priority task
01211  * that is ready to run.
01212  */
01213 void vTaskSwitchContext( void ) PRIVILEGED_FUNCTION;
01214 
01215 /*
01216  * Return the handle of the calling task.
01217  */
01218 xTaskHandle xTaskGetCurrentTaskHandle( void ) PRIVILEGED_FUNCTION;
01219 
01220 /*
01221  * Capture the current time status for future reference.
01222  */
01223 void vTaskSetTimeOutState( xTimeOutType * const pxTimeOut ) PRIVILEGED_FUNCTION;
01224 
01225 /*
01226  * Compare the time status now with that previously captured to see if the
01227  * timeout has expired.
01228  */
01229 portBASE_TYPE xTaskCheckForTimeOut( xTimeOutType * const pxTimeOut, portTickType * const pxTicksToWait ) PRIVILEGED_FUNCTION;
01230 
01231 /*
01232  * Shortcut used by the queue implementation to prevent unnecessary call to
01233  * taskYIELD();
01234  */
01235 void vTaskMissedYield( void ) PRIVILEGED_FUNCTION;
01236 
01237 /*
01238  * Returns the scheduler state as taskSCHEDULER_RUNNING,
01239  * taskSCHEDULER_NOT_STARTED or taskSCHEDULER_SUSPENDED.
01240  */
01241 portBASE_TYPE xTaskGetSchedulerState( void ) PRIVILEGED_FUNCTION;
01242 
01243 /*
01244  * Raises the priority of the mutex holder to that of the calling task should
01245  * the mutex holder have a priority less than the calling task.
01246  */
01247 void vTaskPriorityInherit( xTaskHandle * const pxMutexHolder ) PRIVILEGED_FUNCTION;
01248 
01249 /*
01250  * Set the priority of a task back to its proper priority in the case that it
01251  * inherited a higher priority while it was holding a semaphore.
01252  */
01253 void vTaskPriorityDisinherit( xTaskHandle * const pxMutexHolder ) PRIVILEGED_FUNCTION;
01254 
01255 /*
01256  * Generic version of the task creation function which is in turn called by the
01257  * xTaskCreate() and xTaskCreateRestricted() macros.
01258  */
01259 signed portBASE_TYPE xTaskGenericCreate( pdTASK_CODE pvTaskCode, const signed char * const pcName, unsigned short usStackDepth, void *pvParameters, unsigned portBASE_TYPE uxPriority, xTaskHandle *pxCreatedTask, portSTACK_TYPE *puxStackBuffer, const xMemoryRegion * const xRegions ) PRIVILEGED_FUNCTION;
01260 
01261 /*----------------------------------------------------------------------------------------------------------*/
01262 /* The time between cycles of the 'check' functionality (defined within the tick hook. */
01263 #define mainCHECK_DELAY                        ( ( portTickType ) 5000 / portTICK_RATE_MS )
01264 
01265 void vApplicationTickHook( void );
01266 void vApplicationStackOverflowHook( xTaskHandle *pxTask, signed char *pcTaskName );
01267 
01268 
01269 #ifdef __cplusplus
01270 }
01271 #endif
01272 #endif /* TASK_H */
01273 
01274 
01275