Port of TI's CC3100 Websock camera demo. Using FreeRTOS, mbedTLS, also parts of Arducam for cams ov5642 and 0v2640. Can also use MT9D111. Work in progress. Be warned some parts maybe a bit flacky. This is for Seeed Arch max only, for an M3, see the demo for CM3 using the 0v5642 aducam mini.

Dependencies:   mbed

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers task.h Source File

task.h

00001 /*
00002     FreeRTOS V8.2.1 - Copyright (C) 2015 Real Time Engineers Ltd.
00003     All rights reserved
00004 
00005     VISIT http://www.FreeRTOS.org TO ENSURE YOU ARE USING THE LATEST VERSION.
00006 
00007     This file is part of the FreeRTOS distribution.
00008 
00009     FreeRTOS is free software; you can redistribute it and/or modify it under
00010     the terms of the GNU General Public License (version 2) as published by the
00011     Free Software Foundation >>!AND MODIFIED BY!<< the FreeRTOS exception.
00012 
00013     ***************************************************************************
00014     >>!   NOTE: The modification to the GPL is included to allow you to     !<<
00015     >>!   distribute a combined work that includes FreeRTOS without being   !<<
00016     >>!   obliged to provide the source code for proprietary components     !<<
00017     >>!   outside of the FreeRTOS kernel.                                   !<<
00018     ***************************************************************************
00019 
00020     FreeRTOS is distributed in the hope that it will be useful, but WITHOUT ANY
00021     WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
00022     FOR A PARTICULAR PURPOSE.  Full license text is available on the following
00023     link: http://www.freertos.org/a00114.html
00024 
00025     ***************************************************************************
00026      *                                                                       *
00027      *    FreeRTOS provides completely free yet professionally developed,    *
00028      *    robust, strictly quality controlled, supported, and cross          *
00029      *    platform software that is more than just the market leader, it     *
00030      *    is the industry's de facto standard.                               *
00031      *                                                                       *
00032      *    Help yourself get started quickly while simultaneously helping     *
00033      *    to support the FreeRTOS project by purchasing a FreeRTOS           *
00034      *    tutorial book, reference manual, or both:                          *
00035      *    http://www.FreeRTOS.org/Documentation                              *
00036      *                                                                       *
00037     ***************************************************************************
00038 
00039     http://www.FreeRTOS.org/FAQHelp.html - Having a problem?  Start by reading
00040     the FAQ page "My application does not run, what could be wrong?".  Have you
00041     defined configASSERT()?
00042 
00043     http://www.FreeRTOS.org/support - In return for receiving this top quality
00044     embedded software for free we request you assist our global community by
00045     participating in the support forum.
00046 
00047     http://www.FreeRTOS.org/training - Investing in training allows your team to
00048     be as productive as possible as early as possible.  Now you can receive
00049     FreeRTOS training directly from Richard Barry, CEO of Real Time Engineers
00050     Ltd, and the world's leading authority on the world's leading RTOS.
00051 
00052     http://www.FreeRTOS.org/plus - A selection of FreeRTOS ecosystem products,
00053     including FreeRTOS+Trace - an indispensable productivity tool, a DOS
00054     compatible FAT file system, and our tiny thread aware UDP/IP stack.
00055 
00056     http://www.FreeRTOS.org/labs - Where new FreeRTOS products go to incubate.
00057     Come and try FreeRTOS+TCP, our new open source TCP/IP stack for FreeRTOS.
00058 
00059     http://www.OpenRTOS.com - Real Time Engineers ltd. license FreeRTOS to High
00060     Integrity Systems ltd. to sell under the OpenRTOS brand.  Low cost OpenRTOS
00061     licenses offer ticketed support, indemnification and commercial middleware.
00062 
00063     http://www.SafeRTOS.com - High Integrity Systems also provide a safety
00064     engineered and independently SIL3 certified version for use in safety and
00065     mission critical applications that require provable dependability.
00066 
00067     1 tab == 4 spaces!
00068 */
00069 
00070 
00071 #ifndef INC_TASK_H
00072 #define INC_TASK_H
00073 
00074 #ifndef INC_FREERTOS_H
00075     #error "include FreeRTOS.h must appear in source files before include task.h"
00076 #endif
00077 
00078 #include "list.h"
00079 
00080 #ifdef __cplusplus
00081 extern "C" {
00082 #endif
00083 
00084 /*-----------------------------------------------------------
00085  * MACROS AND DEFINITIONS
00086  *----------------------------------------------------------*/
00087 
00088 #define tskKERNEL_VERSION_NUMBER "V8.2.1"
00089 #define tskKERNEL_VERSION_MAJOR 8
00090 #define tskKERNEL_VERSION_MINOR 2
00091 #define tskKERNEL_VERSION_BUILD 1
00092 
00093 /**
00094  * task. h
00095  *
00096  * Type by which tasks are referenced.  For example, a call to xTaskCreate
00097  * returns (via a pointer parameter) an TaskHandle_t variable that can then
00098  * be used as a parameter to vTaskDelete to delete the task.
00099  *
00100  * \defgroup TaskHandle_t TaskHandle_t
00101  * \ingroup Tasks
00102  */
00103 typedef void * TaskHandle_t;
00104 
00105 /*
00106  * Defines the prototype to which the application task hook function must
00107  * conform.
00108  */
00109 typedef BaseType_t (*TaskHookFunction_t)( void * );
00110 
00111 /* Task states returned by eTaskGetState. */
00112 typedef enum
00113 {
00114     eRunning = 0,   /* A task is querying the state of itself, so must be running. */
00115     eReady,         /* The task being queried is in a read or pending ready list. */
00116     eBlocked,       /* The task being queried is in the Blocked state. */
00117     eSuspended,     /* The task being queried is in the Suspended state, or is in the Blocked state with an infinite time out. */
00118     eDeleted        /* The task being queried has been deleted, but its TCB has not yet been freed. */
00119 } eTaskState;
00120 
00121 /* Actions that can be performed when vTaskNotify() is called. */
00122 typedef enum
00123 {
00124     eNoAction = 0,              /* Notify the task without updating its notify value. */
00125     eSetBits,                   /* Set bits in the task's notification value. */
00126     eIncrement,                 /* Increment the task's notification value. */
00127     eSetValueWithOverwrite,     /* Set the task's notification value to a specific value even if the previous value has not yet been read by the task. */
00128     eSetValueWithoutOverwrite   /* Set the task's notification value if the previous value has been read by the task. */
00129 } eNotifyAction;
00130 
00131 /*
00132  * Used internally only.
00133  */
00134 typedef struct xTIME_OUT
00135 {
00136     BaseType_t xOverflowCount;
00137     TickType_t xTimeOnEntering;
00138 } TimeOut_t;
00139 
00140 /*
00141  * Defines the memory ranges allocated to the task when an MPU is used.
00142  */
00143 typedef struct xMEMORY_REGION
00144 {
00145     void *pvBaseAddress;
00146     uint32_t ulLengthInBytes;
00147     uint32_t ulParameters;
00148 } MemoryRegion_t;
00149 
00150 /*
00151  * Parameters required to create an MPU protected task.
00152  */
00153 typedef struct xTASK_PARAMETERS
00154 {
00155     TaskFunction_t pvTaskCode;
00156     const char * const pcName;  /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
00157     uint16_t usStackDepth;
00158     void *pvParameters;
00159     UBaseType_t uxPriority;
00160     StackType_t *puxStackBuffer;
00161     MemoryRegion_t xRegions[ portNUM_CONFIGURABLE_REGIONS ];
00162 } TaskParameters_t;
00163 
00164 /* Used with the uxTaskGetSystemState() function to return the state of each task
00165 in the system. */
00166 typedef struct xTASK_STATUS
00167 {
00168     TaskHandle_t xHandle;           /* The handle of the task to which the rest of the information in the structure relates. */
00169     const char *pcTaskName;         /* A pointer to the task's name.  This value will be invalid if the task was deleted since the structure was populated! */ /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
00170     UBaseType_t xTaskNumber;        /* A number unique to the task. */
00171     eTaskState eCurrentState;       /* The state in which the task existed when the structure was populated. */
00172     UBaseType_t uxCurrentPriority;  /* The priority at which the task was running (may be inherited) when the structure was populated. */
00173     UBaseType_t uxBasePriority;     /* The priority to which the task will return if the task's current priority has been inherited to avoid unbounded priority inversion when obtaining a mutex.  Only valid if configUSE_MUTEXES is defined as 1 in FreeRTOSConfig.h. */
00174     uint32_t ulRunTimeCounter;      /* The total run time allocated to the task so far, as defined by the run time stats clock.  See http://www.freertos.org/rtos-run-time-stats.html.  Only valid when configGENERATE_RUN_TIME_STATS is defined as 1 in FreeRTOSConfig.h. */
00175     uint16_t usStackHighWaterMark;  /* The minimum amount of stack space that has remained for the task since the task was created.  The closer this value is to zero the closer the task has come to overflowing its stack. */
00176 } TaskStatus_t;
00177 
00178 /* Possible return values for eTaskConfirmSleepModeStatus(). */
00179 typedef enum
00180 {
00181     eAbortSleep = 0,        /* A task has been made ready or a context switch pended since portSUPPORESS_TICKS_AND_SLEEP() was called - abort entering a sleep mode. */
00182     eStandardSleep,         /* Enter a sleep mode that will not last any longer than the expected idle time. */
00183     eNoTasksWaitingTimeout  /* No tasks are waiting for a timeout so it is safe to enter a sleep mode that can only be exited by an external interrupt. */
00184 } eSleepModeStatus;
00185 
00186 
00187 /**
00188  * Defines the priority used by the idle task.  This must not be modified.
00189  *
00190  * \ingroup TaskUtils
00191  */
00192 #define tskIDLE_PRIORITY            ( ( UBaseType_t ) 0U )
00193 
00194 /**
00195  * task. h
00196  *
00197  * Macro for forcing a context switch.
00198  *
00199  * \defgroup taskYIELD taskYIELD
00200  * \ingroup SchedulerControl
00201  */
00202 #define taskYIELD()                 portYIELD()
00203 
00204 /**
00205  * task. h
00206  *
00207  * Macro to mark the start of a critical code region.  Preemptive context
00208  * switches cannot occur when in a critical region.
00209  *
00210  * NOTE: This may alter the stack (depending on the portable implementation)
00211  * so must be used with care!
00212  *
00213  * \defgroup taskENTER_CRITICAL taskENTER_CRITICAL
00214  * \ingroup SchedulerControl
00215  */
00216 #define taskENTER_CRITICAL()        portENTER_CRITICAL()
00217 #define taskENTER_CRITICAL_FROM_ISR( x ) portSET_INTERRUPT_MASK_FROM_ISR( x )
00218 
00219 /**
00220  * task. h
00221  *
00222  * Macro to mark the end of a critical code region.  Preemptive context
00223  * switches cannot occur when in a critical region.
00224  *
00225  * NOTE: This may alter the stack (depending on the portable implementation)
00226  * so must be used with care!
00227  *
00228  * \defgroup taskEXIT_CRITICAL taskEXIT_CRITICAL
00229  * \ingroup SchedulerControl
00230  */
00231 #define taskEXIT_CRITICAL()         portEXIT_CRITICAL()
00232 #define taskEXIT_CRITICAL_FROM_ISR() portCLEAR_INTERRUPT_MASK_FROM_ISR()
00233 /**
00234  * task. h
00235  *
00236  * Macro to disable all maskable interrupts.
00237  *
00238  * \defgroup taskDISABLE_INTERRUPTS taskDISABLE_INTERRUPTS
00239  * \ingroup SchedulerControl
00240  */
00241 #define taskDISABLE_INTERRUPTS()    portDISABLE_INTERRUPTS()
00242 
00243 /**
00244  * task. h
00245  *
00246  * Macro to enable microcontroller interrupts.
00247  *
00248  * \defgroup taskENABLE_INTERRUPTS taskENABLE_INTERRUPTS
00249  * \ingroup SchedulerControl
00250  */
00251 #define taskENABLE_INTERRUPTS()     portENABLE_INTERRUPTS()
00252 
00253 /* Definitions returned by xTaskGetSchedulerState().  taskSCHEDULER_SUSPENDED is
00254 0 to generate more optimal code when configASSERT() is defined as the constant
00255 is used in assert() statements. */
00256 #define taskSCHEDULER_SUSPENDED     ( ( BaseType_t ) 0 )
00257 #define taskSCHEDULER_NOT_STARTED   ( ( BaseType_t ) 1 )
00258 #define taskSCHEDULER_RUNNING       ( ( BaseType_t ) 2 )
00259 
00260 
00261 /*-----------------------------------------------------------
00262  * TASK CREATION API
00263  *----------------------------------------------------------*/
00264 
00265 /**
00266  * task. h
00267  *<pre>
00268  BaseType_t xTaskCreate(
00269                               TaskFunction_t pvTaskCode,
00270                               const char * const pcName,
00271                               uint16_t usStackDepth,
00272                               void *pvParameters,
00273                               UBaseType_t uxPriority,
00274                               TaskHandle_t *pvCreatedTask
00275                           );</pre>
00276  *
00277  * Create a new task and add it to the list of tasks that are ready to run.
00278  *
00279  * xTaskCreate() can only be used to create a task that has unrestricted
00280  * access to the entire microcontroller memory map.  Systems that include MPU
00281  * support can alternatively create an MPU constrained task using
00282  * xTaskCreateRestricted().
00283  *
00284  * @param pvTaskCode Pointer to the task entry function.  Tasks
00285  * must be implemented to never return (i.e. continuous loop).
00286  *
00287  * @param pcName A descriptive name for the task.  This is mainly used to
00288  * facilitate debugging.  Max length defined by configMAX_TASK_NAME_LEN - default
00289  * is 16.
00290  *
00291  * @param usStackDepth The size of the task stack specified as the number of
00292  * variables the stack can hold - not the number of bytes.  For example, if
00293  * the stack is 16 bits wide and usStackDepth is defined as 100, 200 bytes
00294  * will be allocated for stack storage.
00295  *
00296  * @param pvParameters Pointer that will be used as the parameter for the task
00297  * being created.
00298  *
00299  * @param uxPriority The priority at which the task should run.  Systems that
00300  * include MPU support can optionally create tasks in a privileged (system)
00301  * mode by setting bit portPRIVILEGE_BIT of the priority parameter.  For
00302  * example, to create a privileged task at priority 2 the uxPriority parameter
00303  * should be set to ( 2 | portPRIVILEGE_BIT ).
00304  *
00305  * @param pvCreatedTask Used to pass back a handle by which the created task
00306  * can be referenced.
00307  *
00308  * @return pdPASS if the task was successfully created and added to a ready
00309  * list, otherwise an error code defined in the file projdefs.h
00310  *
00311  * Example usage:
00312    <pre>
00313  // Task to be created.
00314  void vTaskCode( void * pvParameters )
00315  {
00316      for( ;; )
00317      {
00318          // Task code goes here.
00319      }
00320  }
00321 
00322  // Function that creates a task.
00323  void vOtherFunction( void )
00324  {
00325  static uint8_t ucParameterToPass;
00326  TaskHandle_t xHandle = NULL;
00327 
00328      // Create the task, storing the handle.  Note that the passed parameter ucParameterToPass
00329      // must exist for the lifetime of the task, so in this case is declared static.  If it was just an
00330      // an automatic stack variable it might no longer exist, or at least have been corrupted, by the time
00331      // the new task attempts to access it.
00332      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, &ucParameterToPass, tskIDLE_PRIORITY, &xHandle );
00333      configASSERT( xHandle );
00334 
00335      // Use the handle to delete the task.
00336      if( xHandle != NULL )
00337      {
00338          vTaskDelete( xHandle );
00339      }
00340  }
00341    </pre>
00342  * \defgroup xTaskCreate xTaskCreate
00343  * \ingroup Tasks
00344  */
00345 #define xTaskCreate( pvTaskCode, pcName, usStackDepth, pvParameters, uxPriority, pxCreatedTask ) xTaskGenericCreate( ( pvTaskCode ), ( pcName ), ( usStackDepth ), ( pvParameters ), ( uxPriority ), ( pxCreatedTask ), ( NULL ), ( NULL ) )
00346 
00347 /**
00348  * task. h
00349  *<pre>
00350  BaseType_t xTaskCreateRestricted( TaskParameters_t *pxTaskDefinition, TaskHandle_t *pxCreatedTask );</pre>
00351  *
00352  * xTaskCreateRestricted() should only be used in systems that include an MPU
00353  * implementation.
00354  *
00355  * Create a new task and add it to the list of tasks that are ready to run.
00356  * The function parameters define the memory regions and associated access
00357  * permissions allocated to the task.
00358  *
00359  * @param pxTaskDefinition Pointer to a structure that contains a member
00360  * for each of the normal xTaskCreate() parameters (see the xTaskCreate() API
00361  * documentation) plus an optional stack buffer and the memory region
00362  * definitions.
00363  *
00364  * @param pxCreatedTask Used to pass back a handle by which the created task
00365  * can be referenced.
00366  *
00367  * @return pdPASS if the task was successfully created and added to a ready
00368  * list, otherwise an error code defined in the file projdefs.h
00369  *
00370  * Example usage:
00371    <pre>
00372 // Create an TaskParameters_t structure that defines the task to be created.
00373 static const TaskParameters_t xCheckTaskParameters =
00374 {
00375     vATask,     // pvTaskCode - the function that implements the task.
00376     "ATask",    // pcName - just a text name for the task to assist debugging.
00377     100,        // usStackDepth - the stack size DEFINED IN WORDS.
00378     NULL,       // pvParameters - passed into the task function as the function parameters.
00379     ( 1UL | portPRIVILEGE_BIT ),// uxPriority - task priority, set the portPRIVILEGE_BIT if the task should run in a privileged state.
00380     cStackBuffer,// puxStackBuffer - the buffer to be used as the task stack.
00381 
00382     // xRegions - Allocate up to three separate memory regions for access by
00383     // the task, with appropriate access permissions.  Different processors have
00384     // different memory alignment requirements - refer to the FreeRTOS documentation
00385     // for full information.
00386     {
00387         // Base address                 Length  Parameters
00388         { cReadWriteArray,              32,     portMPU_REGION_READ_WRITE },
00389         { cReadOnlyArray,               32,     portMPU_REGION_READ_ONLY },
00390         { cPrivilegedOnlyAccessArray,   128,    portMPU_REGION_PRIVILEGED_READ_WRITE }
00391     }
00392 };
00393 
00394 int main( void )
00395 {
00396 TaskHandle_t xHandle;
00397 
00398     // Create a task from the const structure defined above.  The task handle
00399     // is requested (the second parameter is not NULL) but in this case just for
00400     // demonstration purposes as its not actually used.
00401     xTaskCreateRestricted( &xRegTest1Parameters, &xHandle );
00402 
00403     // Start the scheduler.
00404     vTaskStartScheduler();
00405 
00406     // Will only get here if there was insufficient memory to create the idle
00407     // and/or timer task.
00408     for( ;; );
00409 }
00410    </pre>
00411  * \defgroup xTaskCreateRestricted xTaskCreateRestricted
00412  * \ingroup Tasks
00413  */
00414 #define xTaskCreateRestricted( x, pxCreatedTask ) xTaskGenericCreate( ((x)->pvTaskCode), ((x)->pcName), ((x)->usStackDepth), ((x)->pvParameters), ((x)->uxPriority), (pxCreatedTask), ((x)->puxStackBuffer), ((x)->xRegions) )
00415 
00416 /**
00417  * task. h
00418  *<pre>
00419  void vTaskAllocateMPURegions( TaskHandle_t xTask, const MemoryRegion_t * const pxRegions );</pre>
00420  *
00421  * Memory regions are assigned to a restricted task when the task is created by
00422  * a call to xTaskCreateRestricted().  These regions can be redefined using
00423  * vTaskAllocateMPURegions().
00424  *
00425  * @param xTask The handle of the task being updated.
00426  *
00427  * @param xRegions A pointer to an MemoryRegion_t structure that contains the
00428  * new memory region definitions.
00429  *
00430  * Example usage:
00431    <pre>
00432 // Define an array of MemoryRegion_t structures that configures an MPU region
00433 // allowing read/write access for 1024 bytes starting at the beginning of the
00434 // ucOneKByte array.  The other two of the maximum 3 definable regions are
00435 // unused so set to zero.
00436 static const MemoryRegion_t xAltRegions[ portNUM_CONFIGURABLE_REGIONS ] =
00437 {
00438     // Base address     Length      Parameters
00439     { ucOneKByte,       1024,       portMPU_REGION_READ_WRITE },
00440     { 0,                0,          0 },
00441     { 0,                0,          0 }
00442 };
00443 
00444 void vATask( void *pvParameters )
00445 {
00446     // This task was created such that it has access to certain regions of
00447     // memory as defined by the MPU configuration.  At some point it is
00448     // desired that these MPU regions are replaced with that defined in the
00449     // xAltRegions const struct above.  Use a call to vTaskAllocateMPURegions()
00450     // for this purpose.  NULL is used as the task handle to indicate that this
00451     // function should modify the MPU regions of the calling task.
00452     vTaskAllocateMPURegions( NULL, xAltRegions );
00453 
00454     // Now the task can continue its function, but from this point on can only
00455     // access its stack and the ucOneKByte array (unless any other statically
00456     // defined or shared regions have been declared elsewhere).
00457 }
00458    </pre>
00459  * \defgroup xTaskCreateRestricted xTaskCreateRestricted
00460  * \ingroup Tasks
00461  */
00462 void vTaskAllocateMPURegions( TaskHandle_t xTask, const MemoryRegion_t * const pxRegions ) PRIVILEGED_FUNCTION;
00463 
00464 /**
00465  * task. h
00466  * <pre>void vTaskDelete( TaskHandle_t xTask );</pre>
00467  *
00468  * INCLUDE_vTaskDelete must be defined as 1 for this function to be available.
00469  * See the configuration section for more information.
00470  *
00471  * Remove a task from the RTOS real time kernel's management.  The task being
00472  * deleted will be removed from all ready, blocked, suspended and event lists.
00473  *
00474  * NOTE:  The idle task is responsible for freeing the kernel allocated
00475  * memory from tasks that have been deleted.  It is therefore important that
00476  * the idle task is not starved of microcontroller processing time if your
00477  * application makes any calls to vTaskDelete ().  Memory allocated by the
00478  * task code is not automatically freed, and should be freed before the task
00479  * is deleted.
00480  *
00481  * See the demo application file death.c for sample code that utilises
00482  * vTaskDelete ().
00483  *
00484  * @param xTask The handle of the task to be deleted.  Passing NULL will
00485  * cause the calling task to be deleted.
00486  *
00487  * Example usage:
00488    <pre>
00489  void vOtherFunction( void )
00490  {
00491  TaskHandle_t xHandle;
00492 
00493      // Create the task, storing the handle.
00494      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
00495 
00496      // Use the handle to delete the task.
00497      vTaskDelete( xHandle );
00498  }
00499    </pre>
00500  * \defgroup vTaskDelete vTaskDelete
00501  * \ingroup Tasks
00502  */
00503 void vTaskDelete( TaskHandle_t xTaskToDelete ) PRIVILEGED_FUNCTION;
00504 
00505 /*-----------------------------------------------------------
00506  * TASK CONTROL API
00507  *----------------------------------------------------------*/
00508 
00509 /**
00510  * task. h
00511  * <pre>void vTaskDelay( const TickType_t xTicksToDelay );</pre>
00512  *
00513  * Delay a task for a given number of ticks.  The actual time that the
00514  * task remains blocked depends on the tick rate.  The constant
00515  * portTICK_PERIOD_MS can be used to calculate real time from the tick
00516  * rate - with the resolution of one tick period.
00517  *
00518  * INCLUDE_vTaskDelay must be defined as 1 for this function to be available.
00519  * See the configuration section for more information.
00520  *
00521  *
00522  * vTaskDelay() specifies a time at which the task wishes to unblock relative to
00523  * the time at which vTaskDelay() is called.  For example, specifying a block
00524  * period of 100 ticks will cause the task to unblock 100 ticks after
00525  * vTaskDelay() is called.  vTaskDelay() does not therefore provide a good method
00526  * of controlling the frequency of a periodic task as the path taken through the
00527  * code, as well as other task and interrupt activity, will effect the frequency
00528  * at which vTaskDelay() gets called and therefore the time at which the task
00529  * next executes.  See vTaskDelayUntil() for an alternative API function designed
00530  * to facilitate fixed frequency execution.  It does this by specifying an
00531  * absolute time (rather than a relative time) at which the calling task should
00532  * unblock.
00533  *
00534  * @param xTicksToDelay The amount of time, in tick periods, that
00535  * the calling task should block.
00536  *
00537  * Example usage:
00538 
00539  void vTaskFunction( void * pvParameters )
00540  {
00541  // Block for 500ms.
00542  const TickType_t xDelay = 500 / portTICK_PERIOD_MS;
00543 
00544      for( ;; )
00545      {
00546          // Simply toggle the LED every 500ms, blocking between each toggle.
00547          vToggleLED();
00548          vTaskDelay( xDelay );
00549      }
00550  }
00551 
00552  * \defgroup vTaskDelay vTaskDelay
00553  * \ingroup TaskCtrl
00554  */
00555 void vTaskDelay( const TickType_t xTicksToDelay ) PRIVILEGED_FUNCTION;
00556 
00557 /**
00558  * task. h
00559  * <pre>void vTaskDelayUntil( TickType_t *pxPreviousWakeTime, const TickType_t xTimeIncrement );</pre>
00560  *
00561  * INCLUDE_vTaskDelayUntil must be defined as 1 for this function to be available.
00562  * See the configuration section for more information.
00563  *
00564  * Delay a task until a specified time.  This function can be used by periodic
00565  * tasks to ensure a constant execution frequency.
00566  *
00567  * This function differs from vTaskDelay () in one important aspect:  vTaskDelay () will
00568  * cause a task to block for the specified number of ticks from the time vTaskDelay () is
00569  * called.  It is therefore difficult to use vTaskDelay () by itself to generate a fixed
00570  * execution frequency as the time between a task starting to execute and that task
00571  * calling vTaskDelay () may not be fixed [the task may take a different path though the
00572  * code between calls, or may get interrupted or preempted a different number of times
00573  * each time it executes].
00574  *
00575  * Whereas vTaskDelay () specifies a wake time relative to the time at which the function
00576  * is called, vTaskDelayUntil () specifies the absolute (exact) time at which it wishes to
00577  * unblock.
00578  *
00579  * The constant portTICK_PERIOD_MS can be used to calculate real time from the tick
00580  * rate - with the resolution of one tick period.
00581  *
00582  * @param pxPreviousWakeTime Pointer to a variable that holds the time at which the
00583  * task was last unblocked.  The variable must be initialised with the current time
00584  * prior to its first use (see the example below).  Following this the variable is
00585  * automatically updated within vTaskDelayUntil ().
00586  *
00587  * @param xTimeIncrement The cycle time period.  The task will be unblocked at
00588  * time *pxPreviousWakeTime + xTimeIncrement.  Calling vTaskDelayUntil with the
00589  * same xTimeIncrement parameter value will cause the task to execute with
00590  * a fixed interface period.
00591  *
00592  * Example usage:
00593    <pre>
00594  // Perform an action every 10 ticks.
00595  void vTaskFunction( void * pvParameters )
00596  {
00597  TickType_t xLastWakeTime;
00598  const TickType_t xFrequency = 10;
00599 
00600      // Initialise the xLastWakeTime variable with the current time.
00601      xLastWakeTime = xTaskGetTickCount ();
00602      for( ;; )
00603      {
00604          // Wait for the next cycle.
00605          vTaskDelayUntil( &xLastWakeTime, xFrequency );
00606 
00607          // Perform action here.
00608      }
00609  }
00610    </pre>
00611  * \defgroup vTaskDelayUntil vTaskDelayUntil
00612  * \ingroup TaskCtrl
00613  */
00614 void vTaskDelayUntil( TickType_t * const pxPreviousWakeTime, const TickType_t xTimeIncrement ) PRIVILEGED_FUNCTION;
00615 
00616 /**
00617  * task. h
00618  * <pre>UBaseType_t uxTaskPriorityGet( TaskHandle_t xTask );</pre>
00619  *
00620  * INCLUDE_uxTaskPriorityGet must be defined as 1 for this function to be available.
00621  * See the configuration section for more information.
00622  *
00623  * Obtain the priority of any task.
00624  *
00625  * @param xTask Handle of the task to be queried.  Passing a NULL
00626  * handle results in the priority of the calling task being returned.
00627  *
00628  * @return The priority of xTask.
00629  *
00630  * Example usage:
00631    <pre>
00632  void vAFunction( void )
00633  {
00634  TaskHandle_t xHandle;
00635 
00636      // Create a task, storing the handle.
00637      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
00638 
00639      // ...
00640 
00641      // Use the handle to obtain the priority of the created task.
00642      // It was created with tskIDLE_PRIORITY, but may have changed
00643      // it itself.
00644      if( uxTaskPriorityGet( xHandle ) != tskIDLE_PRIORITY )
00645      {
00646          // The task has changed it's priority.
00647      }
00648 
00649      // ...
00650 
00651      // Is our priority higher than the created task?
00652      if( uxTaskPriorityGet( xHandle ) < uxTaskPriorityGet( NULL ) )
00653      {
00654          // Our priority (obtained using NULL handle) is higher.
00655      }
00656  }
00657    </pre>
00658  * \defgroup uxTaskPriorityGet uxTaskPriorityGet
00659  * \ingroup TaskCtrl
00660  */
00661 UBaseType_t uxTaskPriorityGet( TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
00662 
00663 /**
00664  * task. h
00665  * <pre>UBaseType_t uxTaskPriorityGetFromISR( TaskHandle_t xTask );</pre>
00666  *
00667  * A version of uxTaskPriorityGet() that can be used from an ISR.
00668  */
00669 UBaseType_t uxTaskPriorityGetFromISR( TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
00670 
00671 /**
00672  * task. h
00673  * <pre>eTaskState eTaskGetState( TaskHandle_t xTask );</pre>
00674  *
00675  * INCLUDE_eTaskGetState must be defined as 1 for this function to be available.
00676  * See the configuration section for more information.
00677  *
00678  * Obtain the state of any task.  States are encoded by the eTaskState
00679  * enumerated type.
00680  *
00681  * @param xTask Handle of the task to be queried.
00682  *
00683  * @return The state of xTask at the time the function was called.  Note the
00684  * state of the task might change between the function being called, and the
00685  * functions return value being tested by the calling task.
00686  */
00687 eTaskState eTaskGetState( TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
00688 
00689 /**
00690  * task. h
00691  * <pre>void vTaskPrioritySet( TaskHandle_t xTask, UBaseType_t uxNewPriority );</pre>
00692  *
00693  * INCLUDE_vTaskPrioritySet must be defined as 1 for this function to be available.
00694  * See the configuration section for more information.
00695  *
00696  * Set the priority of any task.
00697  *
00698  * A context switch will occur before the function returns if the priority
00699  * being set is higher than the currently executing task.
00700  *
00701  * @param xTask Handle to the task for which the priority is being set.
00702  * Passing a NULL handle results in the priority of the calling task being set.
00703  *
00704  * @param uxNewPriority The priority to which the task will be set.
00705  *
00706  * Example usage:
00707    <pre>
00708  void vAFunction( void )
00709  {
00710  TaskHandle_t xHandle;
00711 
00712      // Create a task, storing the handle.
00713      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
00714 
00715      // ...
00716 
00717      // Use the handle to raise the priority of the created task.
00718      vTaskPrioritySet( xHandle, tskIDLE_PRIORITY + 1 );
00719 
00720      // ...
00721 
00722      // Use a NULL handle to raise our priority to the same value.
00723      vTaskPrioritySet( NULL, tskIDLE_PRIORITY + 1 );
00724  }
00725    </pre>
00726  * \defgroup vTaskPrioritySet vTaskPrioritySet
00727  * \ingroup TaskCtrl
00728  */
00729 void vTaskPrioritySet( TaskHandle_t xTask, UBaseType_t uxNewPriority ) PRIVILEGED_FUNCTION;
00730 
00731 /**
00732  * task. h
00733  * <pre>void vTaskSuspend( TaskHandle_t xTaskToSuspend );</pre>
00734  *
00735  * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available.
00736  * See the configuration section for more information.
00737  *
00738  * Suspend any task.  When suspended a task will never get any microcontroller
00739  * processing time, no matter what its priority.
00740  *
00741  * Calls to vTaskSuspend are not accumulative -
00742  * i.e. calling vTaskSuspend () twice on the same task still only requires one
00743  * call to vTaskResume () to ready the suspended task.
00744  *
00745  * @param xTaskToSuspend Handle to the task being suspended.  Passing a NULL
00746  * handle will cause the calling task to be suspended.
00747  *
00748  * Example usage:
00749    <pre>
00750  void vAFunction( void )
00751  {
00752  TaskHandle_t xHandle;
00753 
00754      // Create a task, storing the handle.
00755      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
00756 
00757      // ...
00758 
00759      // Use the handle to suspend the created task.
00760      vTaskSuspend( xHandle );
00761 
00762      // ...
00763 
00764      // The created task will not run during this period, unless
00765      // another task calls vTaskResume( xHandle ).
00766 
00767      //...
00768 
00769 
00770      // Suspend ourselves.
00771      vTaskSuspend( NULL );
00772 
00773      // We cannot get here unless another task calls vTaskResume
00774      // with our handle as the parameter.
00775  }
00776    </pre>
00777  * \defgroup vTaskSuspend vTaskSuspend
00778  * \ingroup TaskCtrl
00779  */
00780 void vTaskSuspend( TaskHandle_t xTaskToSuspend ) PRIVILEGED_FUNCTION;
00781 
00782 /**
00783  * task. h
00784  * <pre>void vTaskResume( TaskHandle_t xTaskToResume );</pre>
00785  *
00786  * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available.
00787  * See the configuration section for more information.
00788  *
00789  * Resumes a suspended task.
00790  *
00791  * A task that has been suspended by one or more calls to vTaskSuspend ()
00792  * will be made available for running again by a single call to
00793  * vTaskResume ().
00794  *
00795  * @param xTaskToResume Handle to the task being readied.
00796  *
00797  * Example usage:
00798    <pre>
00799  void vAFunction( void )
00800  {
00801  TaskHandle_t xHandle;
00802 
00803      // Create a task, storing the handle.
00804      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
00805 
00806      // ...
00807 
00808      // Use the handle to suspend the created task.
00809      vTaskSuspend( xHandle );
00810 
00811      // ...
00812 
00813      // The created task will not run during this period, unless
00814      // another task calls vTaskResume( xHandle ).
00815 
00816      //...
00817 
00818 
00819      // Resume the suspended task ourselves.
00820      vTaskResume( xHandle );
00821 
00822      // The created task will once again get microcontroller processing
00823      // time in accordance with its priority within the system.
00824  }
00825    </pre>
00826  * \defgroup vTaskResume vTaskResume
00827  * \ingroup TaskCtrl
00828  */
00829 void vTaskResume( TaskHandle_t xTaskToResume ) PRIVILEGED_FUNCTION;
00830 
00831 /**
00832  * task. h
00833  * <pre>void xTaskResumeFromISR( TaskHandle_t xTaskToResume );</pre>
00834  *
00835  * INCLUDE_xTaskResumeFromISR must be defined as 1 for this function to be
00836  * available.  See the configuration section for more information.
00837  *
00838  * An implementation of vTaskResume() that can be called from within an ISR.
00839  *
00840  * A task that has been suspended by one or more calls to vTaskSuspend ()
00841  * will be made available for running again by a single call to
00842  * xTaskResumeFromISR ().
00843  *
00844  * xTaskResumeFromISR() should not be used to synchronise a task with an
00845  * interrupt if there is a chance that the interrupt could arrive prior to the
00846  * task being suspended - as this can lead to interrupts being missed. Use of a
00847  * semaphore as a synchronisation mechanism would avoid this eventuality.
00848  *
00849  * @param xTaskToResume Handle to the task being readied.
00850  *
00851  * @return pdTRUE if resuming the task should result in a context switch,
00852  * otherwise pdFALSE. This is used by the ISR to determine if a context switch
00853  * may be required following the ISR.
00854  *
00855  * \defgroup vTaskResumeFromISR vTaskResumeFromISR
00856  * \ingroup TaskCtrl
00857  */
00858 BaseType_t xTaskResumeFromISR( TaskHandle_t xTaskToResume ) PRIVILEGED_FUNCTION;
00859 
00860 /*-----------------------------------------------------------
00861  * SCHEDULER CONTROL
00862  *----------------------------------------------------------*/
00863 
00864 /**
00865  * task. h
00866  * <pre>void vTaskStartScheduler( void );</pre>
00867  *
00868  * Starts the real time kernel tick processing.  After calling the kernel
00869  * has control over which tasks are executed and when.
00870  *
00871  * See the demo application file main.c for an example of creating
00872  * tasks and starting the kernel.
00873  *
00874  * Example usage:
00875    <pre>
00876  void vAFunction( void )
00877  {
00878      // Create at least one task before starting the kernel.
00879      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL );
00880 
00881      // Start the real time kernel with preemption.
00882      vTaskStartScheduler ();
00883 
00884      // Will not get here unless a task calls vTaskEndScheduler ()
00885  }
00886    </pre>
00887  *
00888  * \defgroup vTaskStartScheduler vTaskStartScheduler
00889  * \ingroup SchedulerControl
00890  */
00891 void vTaskStartScheduler( void ) PRIVILEGED_FUNCTION;
00892 
00893 /**
00894  * task. h
00895  * <pre>void vTaskEndScheduler( void );</pre>
00896  *
00897  * NOTE:  At the time of writing only the x86 real mode port, which runs on a PC
00898  * in place of DOS, implements this function.
00899  *
00900  * Stops the real time kernel tick.  All created tasks will be automatically
00901  * deleted and multitasking (either preemptive or cooperative) will
00902  * stop.  Execution then resumes from the point where vTaskStartScheduler ()
00903  * was called, as if vTaskStartScheduler () had just returned.
00904  *
00905  * See the demo application file main. c in the demo/PC directory for an
00906  * example that uses vTaskEndScheduler ().
00907  *
00908  * vTaskEndScheduler () requires an exit function to be defined within the
00909  * portable layer (see vPortEndScheduler () in port. c for the PC port).  This
00910  * performs hardware specific operations such as stopping the kernel tick.
00911  *
00912  * vTaskEndScheduler () will cause all of the resources allocated by the
00913  * kernel to be freed - but will not free resources allocated by application
00914  * tasks.
00915  *
00916  * Example usage:
00917    <pre>
00918  void vTaskCode( void * pvParameters )
00919  {
00920      for( ;; )
00921      {
00922          // Task code goes here.
00923 
00924          // At some point we want to end the real time kernel processing
00925          // so call ...
00926          vTaskEndScheduler ();
00927      }
00928  }
00929 
00930  void vAFunction( void )
00931  {
00932      // Create at least one task before starting the kernel.
00933      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL );
00934 
00935      // Start the real time kernel with preemption.
00936      vTaskStartScheduler ();
00937 
00938      // Will only get here when the vTaskCode () task has called
00939      // vTaskEndScheduler ().  When we get here we are back to single task
00940      // execution.
00941  }
00942    </pre>
00943  *
00944  * \defgroup vTaskEndScheduler vTaskEndScheduler
00945  * \ingroup SchedulerControl
00946  */
00947 void vTaskEndScheduler( void ) PRIVILEGED_FUNCTION;
00948 
00949 /**
00950  * task. h
00951  * <pre>void vTaskSuspendAll( void );</pre>
00952  *
00953  * Suspends the scheduler without disabling interrupts.  Context switches will
00954  * not occur while the scheduler is suspended.
00955  *
00956  * After calling vTaskSuspendAll () the calling task will continue to execute
00957  * without risk of being swapped out until a call to xTaskResumeAll () has been
00958  * made.
00959  *
00960  * API functions that have the potential to cause a context switch (for example,
00961  * vTaskDelayUntil(), xQueueSend(), etc.) must not be called while the scheduler
00962  * is suspended.
00963  *
00964  * Example usage:
00965    <pre>
00966  void vTask1( void * pvParameters )
00967  {
00968      for( ;; )
00969      {
00970          // Task code goes here.
00971 
00972          // ...
00973 
00974          // At some point the task wants to perform a long operation during
00975          // which it does not want to get swapped out.  It cannot use
00976          // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the
00977          // operation may cause interrupts to be missed - including the
00978          // ticks.
00979 
00980          // Prevent the real time kernel swapping out the task.
00981          vTaskSuspendAll ();
00982 
00983          // Perform the operation here.  There is no need to use critical
00984          // sections as we have all the microcontroller processing time.
00985          // During this time interrupts will still operate and the kernel
00986          // tick count will be maintained.
00987 
00988          // ...
00989 
00990          // The operation is complete.  Restart the kernel.
00991          xTaskResumeAll ();
00992      }
00993  }
00994    </pre>
00995  * \defgroup vTaskSuspendAll vTaskSuspendAll
00996  * \ingroup SchedulerControl
00997  */
00998 void vTaskSuspendAll( void ) PRIVILEGED_FUNCTION;
00999 
01000 /**
01001  * task. h
01002  * <pre>BaseType_t xTaskResumeAll( void );</pre>
01003  *
01004  * Resumes scheduler activity after it was suspended by a call to
01005  * vTaskSuspendAll().
01006  *
01007  * xTaskResumeAll() only resumes the scheduler.  It does not unsuspend tasks
01008  * that were previously suspended by a call to vTaskSuspend().
01009  *
01010  * @return If resuming the scheduler caused a context switch then pdTRUE is
01011  *        returned, otherwise pdFALSE is returned.
01012  *
01013  * Example usage:
01014    <pre>
01015  void vTask1( void * pvParameters )
01016  {
01017      for( ;; )
01018      {
01019          // Task code goes here.
01020 
01021          // ...
01022 
01023          // At some point the task wants to perform a long operation during
01024          // which it does not want to get swapped out.  It cannot use
01025          // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the
01026          // operation may cause interrupts to be missed - including the
01027          // ticks.
01028 
01029          // Prevent the real time kernel swapping out the task.
01030          vTaskSuspendAll ();
01031 
01032          // Perform the operation here.  There is no need to use critical
01033          // sections as we have all the microcontroller processing time.
01034          // During this time interrupts will still operate and the real
01035          // time kernel tick count will be maintained.
01036 
01037          // ...
01038 
01039          // The operation is complete.  Restart the kernel.  We want to force
01040          // a context switch - but there is no point if resuming the scheduler
01041          // caused a context switch already.
01042          if( !xTaskResumeAll () )
01043          {
01044               taskYIELD ();
01045          }
01046      }
01047  }
01048    </pre>
01049  * \defgroup xTaskResumeAll xTaskResumeAll
01050  * \ingroup SchedulerControl
01051  */
01052 BaseType_t xTaskResumeAll( void ) PRIVILEGED_FUNCTION;
01053 
01054 /*-----------------------------------------------------------
01055  * TASK UTILITIES
01056  *----------------------------------------------------------*/
01057 
01058 /**
01059  * task. h
01060  * <PRE>TickType_t xTaskGetTickCount( void );</PRE>
01061  *
01062  * @return The count of ticks since vTaskStartScheduler was called.
01063  *
01064  * \defgroup xTaskGetTickCount xTaskGetTickCount
01065  * \ingroup TaskUtils
01066  */
01067 TickType_t xTaskGetTickCount( void ) PRIVILEGED_FUNCTION;
01068 
01069 /**
01070  * task. h
01071  * <PRE>TickType_t xTaskGetTickCountFromISR( void );</PRE>
01072  *
01073  * @return The count of ticks since vTaskStartScheduler was called.
01074  *
01075  * This is a version of xTaskGetTickCount() that is safe to be called from an
01076  * ISR - provided that TickType_t is the natural word size of the
01077  * microcontroller being used or interrupt nesting is either not supported or
01078  * not being used.
01079  *
01080  * \defgroup xTaskGetTickCountFromISR xTaskGetTickCountFromISR
01081  * \ingroup TaskUtils
01082  */
01083 TickType_t xTaskGetTickCountFromISR( void ) PRIVILEGED_FUNCTION;
01084 
01085 /**
01086  * task. h
01087  * <PRE>uint16_t uxTaskGetNumberOfTasks( void );</PRE>
01088  *
01089  * @return The number of tasks that the real time kernel is currently managing.
01090  * This includes all ready, blocked and suspended tasks.  A task that
01091  * has been deleted but not yet freed by the idle task will also be
01092  * included in the count.
01093  *
01094  * \defgroup uxTaskGetNumberOfTasks uxTaskGetNumberOfTasks
01095  * \ingroup TaskUtils
01096  */
01097 UBaseType_t uxTaskGetNumberOfTasks( void ) PRIVILEGED_FUNCTION;
01098 
01099 /**
01100  * task. h
01101  * <PRE>char *pcTaskGetTaskName( TaskHandle_t xTaskToQuery );</PRE>
01102  *
01103  * @return The text (human readable) name of the task referenced by the handle
01104  * xTaskToQuery.  A task can query its own name by either passing in its own
01105  * handle, or by setting xTaskToQuery to NULL.  INCLUDE_pcTaskGetTaskName must be
01106  * set to 1 in FreeRTOSConfig.h for pcTaskGetTaskName() to be available.
01107  *
01108  * \defgroup pcTaskGetTaskName pcTaskGetTaskName
01109  * \ingroup TaskUtils
01110  */
01111 char *pcTaskGetTaskName( TaskHandle_t xTaskToQuery ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
01112 
01113 /**
01114  * task.h
01115  * <PRE>UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask );</PRE>
01116  *
01117  * INCLUDE_uxTaskGetStackHighWaterMark must be set to 1 in FreeRTOSConfig.h for
01118  * this function to be available.
01119  *
01120  * Returns the high water mark of the stack associated with xTask.  That is,
01121  * the minimum free stack space there has been (in words, so on a 32 bit machine
01122  * a value of 1 means 4 bytes) since the task started.  The smaller the returned
01123  * number the closer the task has come to overflowing its stack.
01124  *
01125  * @param xTask Handle of the task associated with the stack to be checked.
01126  * Set xTask to NULL to check the stack of the calling task.
01127  *
01128  * @return The smallest amount of free stack space there has been (in words, so
01129  * actual spaces on the stack rather than bytes) since the task referenced by
01130  * xTask was created.
01131  */
01132 UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
01133 
01134 /* When using trace macros it is sometimes necessary to include task.h before
01135 FreeRTOS.h.  When this is done TaskHookFunction_t will not yet have been defined,
01136 so the following two prototypes will cause a compilation error.  This can be
01137 fixed by simply guarding against the inclusion of these two prototypes unless
01138 they are explicitly required by the configUSE_APPLICATION_TASK_TAG configuration
01139 constant. */
01140 #ifdef configUSE_APPLICATION_TASK_TAG
01141     #if configUSE_APPLICATION_TASK_TAG == 1
01142         /**
01143          * task.h
01144          * <pre>void vTaskSetApplicationTaskTag( TaskHandle_t xTask, TaskHookFunction_t pxHookFunction );</pre>
01145          *
01146          * Sets pxHookFunction to be the task hook function used by the task xTask.
01147          * Passing xTask as NULL has the effect of setting the calling tasks hook
01148          * function.
01149          */
01150         void vTaskSetApplicationTaskTag( TaskHandle_t xTask, TaskHookFunction_t pxHookFunction ) PRIVILEGED_FUNCTION;
01151 
01152         /**
01153          * task.h
01154          * <pre>void xTaskGetApplicationTaskTag( TaskHandle_t xTask );</pre>
01155          *
01156          * Returns the pxHookFunction value assigned to the task xTask.
01157          */
01158         TaskHookFunction_t xTaskGetApplicationTaskTag( TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
01159     #endif /* configUSE_APPLICATION_TASK_TAG ==1 */
01160 #endif /* ifdef configUSE_APPLICATION_TASK_TAG */
01161 
01162 #if( configNUM_THREAD_LOCAL_STORAGE_POINTERS > 0 )
01163 
01164     /* Each task contains an array of pointers that is dimensioned by the
01165     configNUM_THREAD_LOCAL_STORAGE_POINTERS setting in FreeRTOSConfig.h.  The
01166     kernel does not use the pointers itself, so the application writer can use
01167     the pointers for any purpose they wish.  The following two functions are
01168     used to set and query a pointer respectively. */
01169     void vTaskSetThreadLocalStoragePointer( TaskHandle_t xTaskToSet, BaseType_t xIndex, void *pvValue );
01170     void *pvTaskGetThreadLocalStoragePointer( TaskHandle_t xTaskToQuery, BaseType_t xIndex );
01171 
01172 #endif
01173 
01174 /**
01175  * task.h
01176  * <pre>BaseType_t xTaskCallApplicationTaskHook( TaskHandle_t xTask, void *pvParameter );</pre>
01177  *
01178  * Calls the hook function associated with xTask.  Passing xTask as NULL has
01179  * the effect of calling the Running tasks (the calling task) hook function.
01180  *
01181  * pvParameter is passed to the hook function for the task to interpret as it
01182  * wants.  The return value is the value returned by the task hook function
01183  * registered by the user.
01184  */
01185 BaseType_t xTaskCallApplicationTaskHook( TaskHandle_t xTask, void *pvParameter ) PRIVILEGED_FUNCTION;
01186 
01187 /**
01188  * xTaskGetIdleTaskHandle() is only available if
01189  * INCLUDE_xTaskGetIdleTaskHandle is set to 1 in FreeRTOSConfig.h.
01190  *
01191  * Simply returns the handle of the idle task.  It is not valid to call
01192  * xTaskGetIdleTaskHandle() before the scheduler has been started.
01193  */
01194 TaskHandle_t xTaskGetIdleTaskHandle( void );
01195 
01196 /**
01197  * configUSE_TRACE_FACILITY must be defined as 1 in FreeRTOSConfig.h for
01198  * uxTaskGetSystemState() to be available.
01199  *
01200  * uxTaskGetSystemState() populates an TaskStatus_t structure for each task in
01201  * the system.  TaskStatus_t structures contain, among other things, members
01202  * for the task handle, task name, task priority, task state, and total amount
01203  * of run time consumed by the task.  See the TaskStatus_t structure
01204  * definition in this file for the full member list.
01205  *
01206  * NOTE:  This function is intended for debugging use only as its use results in
01207  * the scheduler remaining suspended for an extended period.
01208  *
01209  * @param pxTaskStatusArray A pointer to an array of TaskStatus_t structures.
01210  * The array must contain at least one TaskStatus_t structure for each task
01211  * that is under the control of the RTOS.  The number of tasks under the control
01212  * of the RTOS can be determined using the uxTaskGetNumberOfTasks() API function.
01213  *
01214  * @param uxArraySize The size of the array pointed to by the pxTaskStatusArray
01215  * parameter.  The size is specified as the number of indexes in the array, or
01216  * the number of TaskStatus_t structures contained in the array, not by the
01217  * number of bytes in the array.
01218  *
01219  * @param pulTotalRunTime If configGENERATE_RUN_TIME_STATS is set to 1 in
01220  * FreeRTOSConfig.h then *pulTotalRunTime is set by uxTaskGetSystemState() to the
01221  * total run time (as defined by the run time stats clock, see
01222  * http://www.freertos.org/rtos-run-time-stats.html) since the target booted.
01223  * pulTotalRunTime can be set to NULL to omit the total run time information.
01224  *
01225  * @return The number of TaskStatus_t structures that were populated by
01226  * uxTaskGetSystemState().  This should equal the number returned by the
01227  * uxTaskGetNumberOfTasks() API function, but will be zero if the value passed
01228  * in the uxArraySize parameter was too small.
01229  *
01230  * Example usage:
01231    <pre>
01232     // This example demonstrates how a human readable table of run time stats
01233     // information is generated from raw data provided by uxTaskGetSystemState().
01234     // The human readable table is written to pcWriteBuffer
01235     void vTaskGetRunTimeStats( char *pcWriteBuffer )
01236     {
01237     TaskStatus_t *pxTaskStatusArray;
01238     volatile UBaseType_t uxArraySize, x;
01239     uint32_t ulTotalRunTime, ulStatsAsPercentage;
01240 
01241         // Make sure the write buffer does not contain a string.
01242         *pcWriteBuffer = 0x00;
01243 
01244         // Take a snapshot of the number of tasks in case it changes while this
01245         // function is executing.
01246         uxArraySize = uxTaskGetNumberOfTasks();
01247 
01248         // Allocate a TaskStatus_t structure for each task.  An array could be
01249         // allocated statically at compile time.
01250         pxTaskStatusArray = pvPortMalloc( uxArraySize * sizeof( TaskStatus_t ) );
01251 
01252         if( pxTaskStatusArray != NULL )
01253         {
01254             // Generate raw status information about each task.
01255             uxArraySize = uxTaskGetSystemState( pxTaskStatusArray, uxArraySize, &ulTotalRunTime );
01256 
01257             // For percentage calculations.
01258             ulTotalRunTime /= 100UL;
01259 
01260             // Avoid divide by zero errors.
01261             if( ulTotalRunTime > 0 )
01262             {
01263                 // For each populated position in the pxTaskStatusArray array,
01264                 // format the raw data as human readable ASCII data
01265                 for( x = 0; x < uxArraySize; x++ )
01266                 {
01267                     // What percentage of the total run time has the task used?
01268                     // This will always be rounded down to the nearest integer.
01269                     // ulTotalRunTimeDiv100 has already been divided by 100.
01270                     ulStatsAsPercentage = pxTaskStatusArray[ x ].ulRunTimeCounter / ulTotalRunTime;
01271 
01272                     if( ulStatsAsPercentage > 0UL )
01273                     {
01274                         sprintf( pcWriteBuffer, "%s\t\t%lu\t\t%lu%%\r\n", pxTaskStatusArray[ x ].pcTaskName, pxTaskStatusArray[ x ].ulRunTimeCounter, ulStatsAsPercentage );
01275                     }
01276                     else
01277                     {
01278                         // If the percentage is zero here then the task has
01279                         // consumed less than 1% of the total run time.
01280                         sprintf( pcWriteBuffer, "%s\t\t%lu\t\t<1%%\r\n", pxTaskStatusArray[ x ].pcTaskName, pxTaskStatusArray[ x ].ulRunTimeCounter );
01281                     }
01282 
01283                     pcWriteBuffer += strlen( ( char * ) pcWriteBuffer );
01284                 }
01285             }
01286 
01287             // The array is no longer needed, free the memory it consumes.
01288             vPortFree( pxTaskStatusArray );
01289         }
01290     }
01291     </pre>
01292  */
01293 UBaseType_t uxTaskGetSystemState( TaskStatus_t * const pxTaskStatusArray, const UBaseType_t uxArraySize, uint32_t * const pulTotalRunTime );
01294 
01295 /**
01296  * task. h
01297  * <PRE>void vTaskList( char *pcWriteBuffer );</PRE>
01298  *
01299  * configUSE_TRACE_FACILITY and configUSE_STATS_FORMATTING_FUNCTIONS must
01300  * both be defined as 1 for this function to be available.  See the
01301  * configuration section of the FreeRTOS.org website for more information.
01302  *
01303  * NOTE 1: This function will disable interrupts for its duration.  It is
01304  * not intended for normal application runtime use but as a debug aid.
01305  *
01306  * Lists all the current tasks, along with their current state and stack
01307  * usage high water mark.
01308  *
01309  * Tasks are reported as blocked ('B'), ready ('R'), deleted ('D') or
01310  * suspended ('S').
01311  *
01312  * PLEASE NOTE:
01313  *
01314  * This function is provided for convenience only, and is used by many of the
01315  * demo applications.  Do not consider it to be part of the scheduler.
01316  *
01317  * vTaskList() calls uxTaskGetSystemState(), then formats part of the
01318  * uxTaskGetSystemState() output into a human readable table that displays task
01319  * names, states and stack usage.
01320  *
01321  * vTaskList() has a dependency on the sprintf() C library function that might
01322  * bloat the code size, use a lot of stack, and provide different results on
01323  * different platforms.  An alternative, tiny, third party, and limited
01324  * functionality implementation of sprintf() is provided in many of the
01325  * FreeRTOS/Demo sub-directories in a file called printf-stdarg.c (note
01326  * printf-stdarg.c does not provide a full snprintf() implementation!).
01327  *
01328  * It is recommended that production systems call uxTaskGetSystemState()
01329  * directly to get access to raw stats data, rather than indirectly through a
01330  * call to vTaskList().
01331  *
01332  * @param pcWriteBuffer A buffer into which the above mentioned details
01333  * will be written, in ASCII form.  This buffer is assumed to be large
01334  * enough to contain the generated report.  Approximately 40 bytes per
01335  * task should be sufficient.
01336  *
01337  * \defgroup vTaskList vTaskList
01338  * \ingroup TaskUtils
01339  */
01340 void vTaskList( char * pcWriteBuffer ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
01341 
01342 /**
01343  * task. h
01344  * <PRE>void vTaskGetRunTimeStats( char *pcWriteBuffer );</PRE>
01345  *
01346  * configGENERATE_RUN_TIME_STATS and configUSE_STATS_FORMATTING_FUNCTIONS
01347  * must both be defined as 1 for this function to be available.  The application
01348  * must also then provide definitions for
01349  * portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and portGET_RUN_TIME_COUNTER_VALUE()
01350  * to configure a peripheral timer/counter and return the timers current count
01351  * value respectively.  The counter should be at least 10 times the frequency of
01352  * the tick count.
01353  *
01354  * NOTE 1: This function will disable interrupts for its duration.  It is
01355  * not intended for normal application runtime use but as a debug aid.
01356  *
01357  * Setting configGENERATE_RUN_TIME_STATS to 1 will result in a total
01358  * accumulated execution time being stored for each task.  The resolution
01359  * of the accumulated time value depends on the frequency of the timer
01360  * configured by the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() macro.
01361  * Calling vTaskGetRunTimeStats() writes the total execution time of each
01362  * task into a buffer, both as an absolute count value and as a percentage
01363  * of the total system execution time.
01364  *
01365  * NOTE 2:
01366  *
01367  * This function is provided for convenience only, and is used by many of the
01368  * demo applications.  Do not consider it to be part of the scheduler.
01369  *
01370  * vTaskGetRunTimeStats() calls uxTaskGetSystemState(), then formats part of the
01371  * uxTaskGetSystemState() output into a human readable table that displays the
01372  * amount of time each task has spent in the Running state in both absolute and
01373  * percentage terms.
01374  *
01375  * vTaskGetRunTimeStats() has a dependency on the sprintf() C library function
01376  * that might bloat the code size, use a lot of stack, and provide different
01377  * results on different platforms.  An alternative, tiny, third party, and
01378  * limited functionality implementation of sprintf() is provided in many of the
01379  * FreeRTOS/Demo sub-directories in a file called printf-stdarg.c (note
01380  * printf-stdarg.c does not provide a full snprintf() implementation!).
01381  *
01382  * It is recommended that production systems call uxTaskGetSystemState() directly
01383  * to get access to raw stats data, rather than indirectly through a call to
01384  * vTaskGetRunTimeStats().
01385  *
01386  * @param pcWriteBuffer A buffer into which the execution times will be
01387  * written, in ASCII form.  This buffer is assumed to be large enough to
01388  * contain the generated report.  Approximately 40 bytes per task should
01389  * be sufficient.
01390  *
01391  * \defgroup vTaskGetRunTimeStats vTaskGetRunTimeStats
01392  * \ingroup TaskUtils
01393  */
01394 void vTaskGetRunTimeStats( char *pcWriteBuffer ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
01395 
01396 /**
01397  * task. h
01398  * <PRE>BaseType_t xTaskNotify( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction );</PRE>
01399  *
01400  * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this
01401  * function to be available.
01402  *
01403  * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private
01404  * "notification value", which is a 32-bit unsigned integer (uint32_t).
01405  *
01406  * Events can be sent to a task using an intermediary object.  Examples of such
01407  * objects are queues, semaphores, mutexes and event groups.  Task notifications
01408  * are a method of sending an event directly to a task without the need for such
01409  * an intermediary object.
01410  *
01411  * A notification sent to a task can optionally perform an action, such as
01412  * update, overwrite or increment the task's notification value.  In that way
01413  * task notifications can be used to send data to a task, or be used as light
01414  * weight and fast binary or counting semaphores.
01415  *
01416  * A notification sent to a task will remain pending until it is cleared by the
01417  * task calling xTaskNotifyWait() or ulTaskNotifyTake().  If the task was
01418  * already in the Blocked state to wait for a notification when the notification
01419  * arrives then the task will automatically be removed from the Blocked state
01420  * (unblocked) and the notification cleared.
01421  *
01422  * A task can use xTaskNotifyWait() to [optionally] block to wait for a
01423  * notification to be pending, or ulTaskNotifyTake() to [optionally] block
01424  * to wait for its notification value to have a non-zero value.  The task does
01425  * not consume any CPU time while it is in the Blocked state.
01426  *
01427  * See http://www.FreeRTOS.org/RTOS-task-notifications.html for details.
01428  *
01429  * @param xTaskToNotify The handle of the task being notified.  The handle to a
01430  * task can be returned from the xTaskCreate() API function used to create the
01431  * task, and the handle of the currently running task can be obtained by calling
01432  * xTaskGetCurrentTaskHandle().
01433  *
01434  * @param ulValue Data that can be sent with the notification.  How the data is
01435  * used depends on the value of the eAction parameter.
01436  *
01437  * @param eAction Specifies how the notification updates the task's notification
01438  * value, if at all.  Valid values for eAction are as follows:
01439  *
01440  *  eSetBits -
01441  *  The task's notification value is bitwise ORed with ulValue.  xTaskNofify()
01442  *  always returns pdPASS in this case.
01443  *
01444  *  eIncrement -
01445  *  The task's notification value is incremented.  ulValue is not used and
01446  *  xTaskNotify() always returns pdPASS in this case.
01447  *
01448  *  eSetValueWithOverwrite -
01449  *  The task's notification value is set to the value of ulValue, even if the
01450  *  task being notified had not yet processed the previous notification (the
01451  *  task already had a notification pending).  xTaskNotify() always returns
01452  *  pdPASS in this case.
01453  *
01454  *  eSetValueWithoutOverwrite -
01455  *  If the task being notified did not already have a notification pending then
01456  *  the task's notification value is set to ulValue and xTaskNotify() will
01457  *  return pdPASS.  If the task being notified already had a notification
01458  *  pending then no action is performed and pdFAIL is returned.
01459  *
01460  *  eNoAction -
01461  *  The task receives a notification without its notification value being
01462  *  updated.  ulValue is not used and xTaskNotify() always returns pdPASS in
01463  *  this case.
01464  *
01465  *  pulPreviousNotificationValue -
01466  *  Can be used to pass out the subject task's notification value before any
01467  *  bits are modified by the notify function.
01468  *
01469  * @return Dependent on the value of eAction.  See the description of the
01470  * eAction parameter.
01471  *
01472  * \defgroup xTaskNotify xTaskNotify
01473  * \ingroup TaskNotifications
01474  */
01475 BaseType_t xTaskGenericNotify( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue );
01476 #define xTaskNotify( xTaskToNotify, ulValue, eAction ) xTaskGenericNotify( ( xTaskToNotify ), ( ulValue ), ( eAction ), NULL )
01477 #define xTaskNotifyAndQuery( xTaskToNotify, ulValue, eAction, pulPreviousNotifyValue ) xTaskGenericNotify( ( xTaskToNotify ), ( ulValue ), ( eAction ), ( pulPreviousNotifyValue ) )
01478 
01479 /**
01480  * task. h
01481  * <PRE>BaseType_t xTaskNotifyFromISR( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, BaseType_t *pxHigherPriorityTaskWoken );</PRE>
01482  *
01483  * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this
01484  * function to be available.
01485  *
01486  * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private
01487  * "notification value", which is a 32-bit unsigned integer (uint32_t).
01488  *
01489  * A version of xTaskNotify() that can be used from an interrupt service routine
01490  * (ISR).
01491  *
01492  * Events can be sent to a task using an intermediary object.  Examples of such
01493  * objects are queues, semaphores, mutexes and event groups.  Task notifications
01494  * are a method of sending an event directly to a task without the need for such
01495  * an intermediary object.
01496  *
01497  * A notification sent to a task can optionally perform an action, such as
01498  * update, overwrite or increment the task's notification value.  In that way
01499  * task notifications can be used to send data to a task, or be used as light
01500  * weight and fast binary or counting semaphores.
01501  *
01502  * A notification sent to a task will remain pending until it is cleared by the
01503  * task calling xTaskNotifyWait() or ulTaskNotifyTake().  If the task was
01504  * already in the Blocked state to wait for a notification when the notification
01505  * arrives then the task will automatically be removed from the Blocked state
01506  * (unblocked) and the notification cleared.
01507  *
01508  * A task can use xTaskNotifyWait() to [optionally] block to wait for a
01509  * notification to be pending, or ulTaskNotifyTake() to [optionally] block
01510  * to wait for its notification value to have a non-zero value.  The task does
01511  * not consume any CPU time while it is in the Blocked state.
01512  *
01513  * See http://www.FreeRTOS.org/RTOS-task-notifications.html for details.
01514  *
01515  * @param xTaskToNotify The handle of the task being notified.  The handle to a
01516  * task can be returned from the xTaskCreate() API function used to create the
01517  * task, and the handle of the currently running task can be obtained by calling
01518  * xTaskGetCurrentTaskHandle().
01519  *
01520  * @param ulValue Data that can be sent with the notification.  How the data is
01521  * used depends on the value of the eAction parameter.
01522  *
01523  * @param eAction Specifies how the notification updates the task's notification
01524  * value, if at all.  Valid values for eAction are as follows:
01525  *
01526  *  eSetBits -
01527  *  The task's notification value is bitwise ORed with ulValue.  xTaskNofify()
01528  *  always returns pdPASS in this case.
01529  *
01530  *  eIncrement -
01531  *  The task's notification value is incremented.  ulValue is not used and
01532  *  xTaskNotify() always returns pdPASS in this case.
01533  *
01534  *  eSetValueWithOverwrite -
01535  *  The task's notification value is set to the value of ulValue, even if the
01536  *  task being notified had not yet processed the previous notification (the
01537  *  task already had a notification pending).  xTaskNotify() always returns
01538  *  pdPASS in this case.
01539  *
01540  *  eSetValueWithoutOverwrite -
01541  *  If the task being notified did not already have a notification pending then
01542  *  the task's notification value is set to ulValue and xTaskNotify() will
01543  *  return pdPASS.  If the task being notified already had a notification
01544  *  pending then no action is performed and pdFAIL is returned.
01545  *
01546  *  eNoAction -
01547  *  The task receives a notification without its notification value being
01548  *  updated.  ulValue is not used and xTaskNotify() always returns pdPASS in
01549  *  this case.
01550  *
01551  * @param pxHigherPriorityTaskWoken  xTaskNotifyFromISR() will set
01552  * *pxHigherPriorityTaskWoken to pdTRUE if sending the notification caused the
01553  * task to which the notification was sent to leave the Blocked state, and the
01554  * unblocked task has a priority higher than the currently running task.  If
01555  * xTaskNotifyFromISR() sets this value to pdTRUE then a context switch should
01556  * be requested before the interrupt is exited.  How a context switch is
01557  * requested from an ISR is dependent on the port - see the documentation page
01558  * for the port in use.
01559  *
01560  * @return Dependent on the value of eAction.  See the description of the
01561  * eAction parameter.
01562  *
01563  * \defgroup xTaskNotify xTaskNotify
01564  * \ingroup TaskNotifications
01565  */
01566 BaseType_t xTaskNotifyFromISR( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, BaseType_t *pxHigherPriorityTaskWoken );
01567 
01568 /**
01569  * task. h
01570  * <PRE>BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait );</pre>
01571  *
01572  * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this
01573  * function to be available.
01574  *
01575  * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private
01576  * "notification value", which is a 32-bit unsigned integer (uint32_t).
01577  *
01578  * Events can be sent to a task using an intermediary object.  Examples of such
01579  * objects are queues, semaphores, mutexes and event groups.  Task notifications
01580  * are a method of sending an event directly to a task without the need for such
01581  * an intermediary object.
01582  *
01583  * A notification sent to a task can optionally perform an action, such as
01584  * update, overwrite or increment the task's notification value.  In that way
01585  * task notifications can be used to send data to a task, or be used as light
01586  * weight and fast binary or counting semaphores.
01587  *
01588  * A notification sent to a task will remain pending until it is cleared by the
01589  * task calling xTaskNotifyWait() or ulTaskNotifyTake().  If the task was
01590  * already in the Blocked state to wait for a notification when the notification
01591  * arrives then the task will automatically be removed from the Blocked state
01592  * (unblocked) and the notification cleared.
01593  *
01594  * A task can use xTaskNotifyWait() to [optionally] block to wait for a
01595  * notification to be pending, or ulTaskNotifyTake() to [optionally] block
01596  * to wait for its notification value to have a non-zero value.  The task does
01597  * not consume any CPU time while it is in the Blocked state.
01598  *
01599  * See http://www.FreeRTOS.org/RTOS-task-notifications.html for details.
01600  *
01601  * @param ulBitsToClearOnEntry Bits that are set in ulBitsToClearOnEntry value
01602  * will be cleared in the calling task's notification value before the task
01603  * checks to see if any notifications are pending, and optionally blocks if no
01604  * notifications are pending.  Setting ulBitsToClearOnEntry to ULONG_MAX (if
01605  * limits.h is included) or 0xffffffffUL (if limits.h is not included) will have
01606  * the effect of resetting the task's notification value to 0.  Setting
01607  * ulBitsToClearOnEntry to 0 will leave the task's notification value unchanged.
01608  *
01609  * @param ulBitsToClearOnExit If a notification is pending or received before
01610  * the calling task exits the xTaskNotifyWait() function then the task's
01611  * notification value (see the xTaskNotify() API function) is passed out using
01612  * the pulNotificationValue parameter.  Then any bits that are set in
01613  * ulBitsToClearOnExit will be cleared in the task's notification value (note
01614  * *pulNotificationValue is set before any bits are cleared).  Setting
01615  * ulBitsToClearOnExit to ULONG_MAX (if limits.h is included) or 0xffffffffUL
01616  * (if limits.h is not included) will have the effect of resetting the task's
01617  * notification value to 0 before the function exits.  Setting
01618  * ulBitsToClearOnExit to 0 will leave the task's notification value unchanged
01619  * when the function exits (in which case the value passed out in
01620  * pulNotificationValue will match the task's notification value).
01621  *
01622  * @param pulNotificationValue Used to pass the task's notification value out
01623  * of the function.  Note the value passed out will not be effected by the
01624  * clearing of any bits caused by ulBitsToClearOnExit being non-zero.
01625  *
01626  * @param xTicksToWait The maximum amount of time that the task should wait in
01627  * the Blocked state for a notification to be received, should a notification
01628  * not already be pending when xTaskNotifyWait() was called.  The task
01629  * will not consume any processing time while it is in the Blocked state.  This
01630  * is specified in kernel ticks, the macro pdMS_TO_TICSK( value_in_ms ) can be
01631  * used to convert a time specified in milliseconds to a time specified in
01632  * ticks.
01633  *
01634  * @return If a notification was received (including notifications that were
01635  * already pending when xTaskNotifyWait was called) then pdPASS is
01636  * returned.  Otherwise pdFAIL is returned.
01637  *
01638  * \defgroup xTaskNotifyWait xTaskNotifyWait
01639  * \ingroup TaskNotifications
01640  */
01641 BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait );
01642 
01643 /**
01644  * task. h
01645  * <PRE>BaseType_t xTaskNotifyGive( TaskHandle_t xTaskToNotify );</PRE>
01646  *
01647  * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this macro
01648  * to be available.
01649  *
01650  * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private
01651  * "notification value", which is a 32-bit unsigned integer (uint32_t).
01652  *
01653  * Events can be sent to a task using an intermediary object.  Examples of such
01654  * objects are queues, semaphores, mutexes and event groups.  Task notifications
01655  * are a method of sending an event directly to a task without the need for such
01656  * an intermediary object.
01657  *
01658  * A notification sent to a task can optionally perform an action, such as
01659  * update, overwrite or increment the task's notification value.  In that way
01660  * task notifications can be used to send data to a task, or be used as light
01661  * weight and fast binary or counting semaphores.
01662  *
01663  * xTaskNotifyGive() is a helper macro intended for use when task notifications
01664  * are used as light weight and faster binary or counting semaphore equivalents.
01665  * Actual FreeRTOS semaphores are given using the xSemaphoreGive() API function,
01666  * the equivalent action that instead uses a task notification is
01667  * xTaskNotifyGive().
01668  *
01669  * When task notifications are being used as a binary or counting semaphore
01670  * equivalent then the task being notified should wait for the notification
01671  * using the ulTaskNotificationTake() API function rather than the
01672  * xTaskNotifyWait() API function.
01673  *
01674  * See http://www.FreeRTOS.org/RTOS-task-notifications.html for more details.
01675  *
01676  * @param xTaskToNotify The handle of the task being notified.  The handle to a
01677  * task can be returned from the xTaskCreate() API function used to create the
01678  * task, and the handle of the currently running task can be obtained by calling
01679  * xTaskGetCurrentTaskHandle().
01680  *
01681  * @return xTaskNotifyGive() is a macro that calls xTaskNotify() with the
01682  * eAction parameter set to eIncrement - so pdPASS is always returned.
01683  *
01684  * \defgroup xTaskNotifyGive xTaskNotifyGive
01685  * \ingroup TaskNotifications
01686  */
01687 #define xTaskNotifyGive( xTaskToNotify ) xTaskNotify( ( xTaskToNotify ), 0, eIncrement );
01688 
01689 /**
01690  * task. h
01691  * <PRE>void vTaskNotifyGiveFromISR( TaskHandle_t xTaskHandle, BaseType_t *pxHigherPriorityTaskWoken );
01692  *
01693  * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this macro
01694  * to be available.
01695  *
01696  * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private
01697  * "notification value", which is a 32-bit unsigned integer (uint32_t).
01698  *
01699  * A version of xTaskNotifyGive() that can be called from an interrupt service
01700  * routine (ISR).
01701  *
01702  * Events can be sent to a task using an intermediary object.  Examples of such
01703  * objects are queues, semaphores, mutexes and event groups.  Task notifications
01704  * are a method of sending an event directly to a task without the need for such
01705  * an intermediary object.
01706  *
01707  * A notification sent to a task can optionally perform an action, such as
01708  * update, overwrite or increment the task's notification value.  In that way
01709  * task notifications can be used to send data to a task, or be used as light
01710  * weight and fast binary or counting semaphores.
01711  *
01712  * vTaskNotifyGiveFromISR() is intended for use when task notifications are
01713  * used as light weight and faster binary or counting semaphore equivalents.
01714  * Actual FreeRTOS semaphores are given from an ISR using the
01715  * xSemaphoreGiveFromISR() API function, the equivalent action that instead uses
01716  * a task notification is vTaskNotifyGiveFromISR().
01717  *
01718  * When task notifications are being used as a binary or counting semaphore
01719  * equivalent then the task being notified should wait for the notification
01720  * using the ulTaskNotificationTake() API function rather than the
01721  * xTaskNotifyWait() API function.
01722  *
01723  * See http://www.FreeRTOS.org/RTOS-task-notifications.html for more details.
01724  *
01725  * @param xTaskToNotify The handle of the task being notified.  The handle to a
01726  * task can be returned from the xTaskCreate() API function used to create the
01727  * task, and the handle of the currently running task can be obtained by calling
01728  * xTaskGetCurrentTaskHandle().
01729  *
01730  * @param pxHigherPriorityTaskWoken  vTaskNotifyGiveFromISR() will set
01731  * *pxHigherPriorityTaskWoken to pdTRUE if sending the notification caused the
01732  * task to which the notification was sent to leave the Blocked state, and the
01733  * unblocked task has a priority higher than the currently running task.  If
01734  * vTaskNotifyGiveFromISR() sets this value to pdTRUE then a context switch
01735  * should be requested before the interrupt is exited.  How a context switch is
01736  * requested from an ISR is dependent on the port - see the documentation page
01737  * for the port in use.
01738  *
01739  * \defgroup xTaskNotifyWait xTaskNotifyWait
01740  * \ingroup TaskNotifications
01741  */
01742 void vTaskNotifyGiveFromISR( TaskHandle_t xTaskToNotify, BaseType_t *pxHigherPriorityTaskWoken );
01743 
01744 /**
01745  * task. h
01746  * <PRE>uint32_t ulTaskNotifyTake( BaseType_t xClearCountOnExit, TickType_t xTicksToWait );</pre>
01747  *
01748  * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this
01749  * function to be available.
01750  *
01751  * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private
01752  * "notification value", which is a 32-bit unsigned integer (uint32_t).
01753  *
01754  * Events can be sent to a task using an intermediary object.  Examples of such
01755  * objects are queues, semaphores, mutexes and event groups.  Task notifications
01756  * are a method of sending an event directly to a task without the need for such
01757  * an intermediary object.
01758  *
01759  * A notification sent to a task can optionally perform an action, such as
01760  * update, overwrite or increment the task's notification value.  In that way
01761  * task notifications can be used to send data to a task, or be used as light
01762  * weight and fast binary or counting semaphores.
01763  *
01764  * ulTaskNotifyTake() is intended for use when a task notification is used as a
01765  * faster and lighter weight binary or counting semaphore alternative.  Actual
01766  * FreeRTOS semaphores are taken using the xSemaphoreTake() API function, the
01767  * equivalent action that instead uses a task notification is
01768  * ulTaskNotifyTake().
01769  *
01770  * When a task is using its notification value as a binary or counting semaphore
01771  * other tasks should send notifications to it using the xTaskNotifyGive()
01772  * macro, or xTaskNotify() function with the eAction parameter set to
01773  * eIncrement.
01774  *
01775  * ulTaskNotifyTake() can either clear the task's notification value to
01776  * zero on exit, in which case the notification value acts like a binary
01777  * semaphore, or decrement the task's notification value on exit, in which case
01778  * the notification value acts like a counting semaphore.
01779  *
01780  * A task can use ulTaskNotifyTake() to [optionally] block to wait for a
01781  * the task's notification value to be non-zero.  The task does not consume any
01782  * CPU time while it is in the Blocked state.
01783  *
01784  * Where as xTaskNotifyWait() will return when a notification is pending,
01785  * ulTaskNotifyTake() will return when the task's notification value is
01786  * not zero.
01787  *
01788  * See http://www.FreeRTOS.org/RTOS-task-notifications.html for details.
01789  *
01790  * @param xClearCountOnExit if xClearCountOnExit is pdFALSE then the task's
01791  * notification value is decremented when the function exits.  In this way the
01792  * notification value acts like a counting semaphore.  If xClearCountOnExit is
01793  * not pdFALSE then the task's notification value is cleared to zero when the
01794  * function exits.  In this way the notification value acts like a binary
01795  * semaphore.
01796  *
01797  * @param xTicksToWait The maximum amount of time that the task should wait in
01798  * the Blocked state for the task's notification value to be greater than zero,
01799  * should the count not already be greater than zero when
01800  * ulTaskNotifyTake() was called.  The task will not consume any processing
01801  * time while it is in the Blocked state.  This is specified in kernel ticks,
01802  * the macro pdMS_TO_TICSK( value_in_ms ) can be used to convert a time
01803  * specified in milliseconds to a time specified in ticks.
01804  *
01805  * @return The task's notification count before it is either cleared to zero or
01806  * decremented (see the xClearCountOnExit parameter).
01807  *
01808  * \defgroup ulTaskNotifyTake ulTaskNotifyTake
01809  * \ingroup TaskNotifications
01810  */
01811 uint32_t ulTaskNotifyTake( BaseType_t xClearCountOnExit, TickType_t xTicksToWait );
01812 
01813 /*-----------------------------------------------------------
01814  * SCHEDULER INTERNALS AVAILABLE FOR PORTING PURPOSES
01815  *----------------------------------------------------------*/
01816 
01817 /*
01818  * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS ONLY
01819  * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS
01820  * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
01821  *
01822  * Called from the real time kernel tick (either preemptive or cooperative),
01823  * this increments the tick count and checks if any tasks that are blocked
01824  * for a finite period required removing from a blocked list and placing on
01825  * a ready list.  If a non-zero value is returned then a context switch is
01826  * required because either:
01827  *   + A task was removed from a blocked list because its timeout had expired,
01828  *     or
01829  *   + Time slicing is in use and there is a task of equal priority to the
01830  *     currently running task.
01831  */
01832 BaseType_t xTaskIncrementTick( void ) PRIVILEGED_FUNCTION;
01833 
01834 /*
01835  * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS AN
01836  * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
01837  *
01838  * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED.
01839  *
01840  * Removes the calling task from the ready list and places it both
01841  * on the list of tasks waiting for a particular event, and the
01842  * list of delayed tasks.  The task will be removed from both lists
01843  * and replaced on the ready list should either the event occur (and
01844  * there be no higher priority tasks waiting on the same event) or
01845  * the delay period expires.
01846  *
01847  * The 'unordered' version replaces the event list item value with the
01848  * xItemValue value, and inserts the list item at the end of the list.
01849  *
01850  * The 'ordered' version uses the existing event list item value (which is the
01851  * owning tasks priority) to insert the list item into the event list is task
01852  * priority order.
01853  *
01854  * @param pxEventList The list containing tasks that are blocked waiting
01855  * for the event to occur.
01856  *
01857  * @param xItemValue The item value to use for the event list item when the
01858  * event list is not ordered by task priority.
01859  *
01860  * @param xTicksToWait The maximum amount of time that the task should wait
01861  * for the event to occur.  This is specified in kernel ticks,the constant
01862  * portTICK_PERIOD_MS can be used to convert kernel ticks into a real time
01863  * period.
01864  */
01865 void vTaskPlaceOnEventList( List_t * const pxEventList, const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
01866 void vTaskPlaceOnUnorderedEventList( List_t * pxEventList, const TickType_t xItemValue, const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
01867 
01868 /*
01869  * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS AN
01870  * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
01871  *
01872  * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED.
01873  *
01874  * This function performs nearly the same function as vTaskPlaceOnEventList().
01875  * The difference being that this function does not permit tasks to block
01876  * indefinitely, whereas vTaskPlaceOnEventList() does.
01877  *
01878  */
01879 void vTaskPlaceOnEventListRestricted( List_t * const pxEventList, const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
01880 
01881 /*
01882  * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS AN
01883  * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
01884  *
01885  * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED.
01886  *
01887  * Removes a task from both the specified event list and the list of blocked
01888  * tasks, and places it on a ready queue.
01889  *
01890  * xTaskRemoveFromEventList()/xTaskRemoveFromUnorderedEventList() will be called
01891  * if either an event occurs to unblock a task, or the block timeout period
01892  * expires.
01893  *
01894  * xTaskRemoveFromEventList() is used when the event list is in task priority
01895  * order.  It removes the list item from the head of the event list as that will
01896  * have the highest priority owning task of all the tasks on the event list.
01897  * xTaskRemoveFromUnorderedEventList() is used when the event list is not
01898  * ordered and the event list items hold something other than the owning tasks
01899  * priority.  In this case the event list item value is updated to the value
01900  * passed in the xItemValue parameter.
01901  *
01902  * @return pdTRUE if the task being removed has a higher priority than the task
01903  * making the call, otherwise pdFALSE.
01904  */
01905 BaseType_t xTaskRemoveFromEventList( const List_t * const pxEventList ) PRIVILEGED_FUNCTION;
01906 BaseType_t xTaskRemoveFromUnorderedEventList( ListItem_t * pxEventListItem, const TickType_t xItemValue ) PRIVILEGED_FUNCTION;
01907 
01908 /*
01909  * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS ONLY
01910  * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS
01911  * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
01912  *
01913  * Sets the pointer to the current TCB to the TCB of the highest priority task
01914  * that is ready to run.
01915  */
01916 void vTaskSwitchContext( void ) PRIVILEGED_FUNCTION;
01917 
01918 /*
01919  * THESE FUNCTIONS MUST NOT BE USED FROM APPLICATION CODE.  THEY ARE USED BY
01920  * THE EVENT BITS MODULE.
01921  */
01922 TickType_t uxTaskResetEventItemValue( void ) PRIVILEGED_FUNCTION;
01923 
01924 /*
01925  * Return the handle of the calling task.
01926  */
01927 TaskHandle_t xTaskGetCurrentTaskHandle( void ) PRIVILEGED_FUNCTION;
01928 
01929 /*
01930  * Capture the current time status for future reference.
01931  */
01932 void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut ) PRIVILEGED_FUNCTION;
01933 
01934 /*
01935  * Compare the time status now with that previously captured to see if the
01936  * timeout has expired.
01937  */
01938 BaseType_t xTaskCheckForTimeOut( TimeOut_t * const pxTimeOut, TickType_t * const pxTicksToWait ) PRIVILEGED_FUNCTION;
01939 
01940 /*
01941  * Shortcut used by the queue implementation to prevent unnecessary call to
01942  * taskYIELD();
01943  */
01944 void vTaskMissedYield( void ) PRIVILEGED_FUNCTION;
01945 
01946 /*
01947  * Returns the scheduler state as taskSCHEDULER_RUNNING,
01948  * taskSCHEDULER_NOT_STARTED or taskSCHEDULER_SUSPENDED.
01949  */
01950 BaseType_t xTaskGetSchedulerState( void ) PRIVILEGED_FUNCTION;
01951 
01952 /*
01953  * Raises the priority of the mutex holder to that of the calling task should
01954  * the mutex holder have a priority less than the calling task.
01955  */
01956 void vTaskPriorityInherit( TaskHandle_t const pxMutexHolder ) PRIVILEGED_FUNCTION;
01957 
01958 /*
01959  * Set the priority of a task back to its proper priority in the case that it
01960  * inherited a higher priority while it was holding a semaphore.
01961  */
01962 BaseType_t xTaskPriorityDisinherit( TaskHandle_t const pxMutexHolder ) PRIVILEGED_FUNCTION;
01963 
01964 /*
01965  * Generic version of the task creation function which is in turn called by the
01966  * xTaskCreate() and xTaskCreateRestricted() macros.
01967  */
01968 BaseType_t xTaskGenericCreate( TaskFunction_t pxTaskCode, const char * const pcName, const uint16_t usStackDepth, void * const pvParameters, UBaseType_t uxPriority, TaskHandle_t * const pxCreatedTask, StackType_t * const puxStackBuffer, const MemoryRegion_t * const xRegions ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
01969 
01970 /*
01971  * Get the uxTCBNumber assigned to the task referenced by the xTask parameter.
01972  */
01973 UBaseType_t uxTaskGetTaskNumber( TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
01974 
01975 /*
01976  * Set the uxTaskNumber of the task referenced by the xTask parameter to
01977  * uxHandle.
01978  */
01979 void vTaskSetTaskNumber( TaskHandle_t xTask, const UBaseType_t uxHandle ) PRIVILEGED_FUNCTION;
01980 
01981 /*
01982  * Only available when configUSE_TICKLESS_IDLE is set to 1.
01983  * If tickless mode is being used, or a low power mode is implemented, then
01984  * the tick interrupt will not execute during idle periods.  When this is the
01985  * case, the tick count value maintained by the scheduler needs to be kept up
01986  * to date with the actual execution time by being skipped forward by a time
01987  * equal to the idle period.
01988  */
01989 void vTaskStepTick( const TickType_t xTicksToJump ) PRIVILEGED_FUNCTION;
01990 
01991 /*
01992  * Only avilable when configUSE_TICKLESS_IDLE is set to 1.
01993  * Provided for use within portSUPPRESS_TICKS_AND_SLEEP() to allow the port
01994  * specific sleep function to determine if it is ok to proceed with the sleep,
01995  * and if it is ok to proceed, if it is ok to sleep indefinitely.
01996  *
01997  * This function is necessary because portSUPPRESS_TICKS_AND_SLEEP() is only
01998  * called with the scheduler suspended, not from within a critical section.  It
01999  * is therefore possible for an interrupt to request a context switch between
02000  * portSUPPRESS_TICKS_AND_SLEEP() and the low power mode actually being
02001  * entered.  eTaskConfirmSleepModeStatus() should be called from a short
02002  * critical section between the timer being stopped and the sleep mode being
02003  * entered to ensure it is ok to proceed into the sleep mode.
02004  */
02005 eSleepModeStatus eTaskConfirmSleepModeStatus( void ) PRIVILEGED_FUNCTION;
02006 
02007 /*
02008  * For internal use only.  Increment the mutex held count when a mutex is
02009  * taken and return the handle of the task that has taken the mutex.
02010  */
02011 void *pvTaskIncrementMutexHeldCount( void );
02012 
02013 #ifdef __cplusplus
02014 }
02015 #endif
02016 #endif /* INC_TASK_H */
02017 
02018 
02019 
02020