1 /*
2  * FreeRTOS Kernel V11.1.0
3  * Copyright (C) 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
4  *
5  * SPDX-License-Identifier: MIT
6  *
7  * Permission is hereby granted, free of charge, to any person obtaining a copy of
8  * this software and associated documentation files (the "Software"), to deal in
9  * the Software without restriction, including without limitation the rights to
10  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
11  * the Software, and to permit persons to whom the Software is furnished to do so,
12  * subject to the following conditions:
13  *
14  * The above copyright notice and this permission notice shall be included in all
15  * copies or substantial portions of the Software.
16  *
17  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
19  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
20  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
21  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
22  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
23  *
24  * https://www.FreeRTOS.org
25  * https://github.com/FreeRTOS
26  *
27  */
28 
29 
30 #ifndef INC_TASK_H
31 #define INC_TASK_H
32 
33 #ifndef INC_FREERTOS_H
34     #error "include FreeRTOS.h must appear in source files before include task.h"
35 #endif
36 
37 #include "list.h"
38 
39 /* *INDENT-OFF* */
40 #ifdef __cplusplus
41     extern "C" {
42 #endif
43 /* *INDENT-ON* */
44 
45 /*-----------------------------------------------------------
46 * MACROS AND DEFINITIONS
47 *----------------------------------------------------------*/
48 
49 /*
50  * If tskKERNEL_VERSION_NUMBER ends with + it represents the version in development
51  * after the numbered release.
52  *
53  * The tskKERNEL_VERSION_MAJOR, tskKERNEL_VERSION_MINOR, tskKERNEL_VERSION_BUILD
54  * values will reflect the last released version number.
55  */
56 #define tskKERNEL_VERSION_NUMBER       "V11.1.0"
57 #define tskKERNEL_VERSION_MAJOR        11
58 #define tskKERNEL_VERSION_MINOR        1
59 #define tskKERNEL_VERSION_BUILD        0
60 
61 /* MPU region parameters passed in ulParameters
62  * of MemoryRegion_t struct. */
63 #define tskMPU_REGION_READ_ONLY        ( 1U << 0U )
64 #define tskMPU_REGION_READ_WRITE       ( 1U << 1U )
65 #define tskMPU_REGION_EXECUTE_NEVER    ( 1U << 2U )
66 #define tskMPU_REGION_NORMAL_MEMORY    ( 1U << 3U )
67 #define tskMPU_REGION_DEVICE_MEMORY    ( 1U << 4U )
68 
69 /* MPU region permissions stored in MPU settings to
70  * authorize access requests. */
71 #define tskMPU_READ_PERMISSION         ( 1U << 0U )
72 #define tskMPU_WRITE_PERMISSION        ( 1U << 1U )
73 
74 /* The direct to task notification feature used to have only a single notification
75  * per task.  Now there is an array of notifications per task that is dimensioned by
76  * configTASK_NOTIFICATION_ARRAY_ENTRIES.  For backward compatibility, any use of the
77  * original direct to task notification defaults to using the first index in the
78  * array. */
79 #define tskDEFAULT_INDEX_TO_NOTIFY     ( 0 )
80 
81 /**
82  * task. h
83  *
84  * Type by which tasks are referenced.  For example, a call to xTaskCreate
85  * returns (via a pointer parameter) an TaskHandle_t variable that can then
86  * be used as a parameter to vTaskDelete to delete the task.
87  *
88  * \defgroup TaskHandle_t TaskHandle_t
89  * \ingroup Tasks
90  */
91 struct tskTaskControlBlock; /* The old naming convention is used to prevent breaking kernel aware debuggers. */
92 typedef struct tskTaskControlBlock         * TaskHandle_t;
93 typedef const struct tskTaskControlBlock   * ConstTaskHandle_t;
94 
95 /*
96  * Defines the prototype to which the application task hook function must
97  * conform.
98  */
99 typedef BaseType_t (* TaskHookFunction_t)( void * arg );
100 
101 /* Task states returned by eTaskGetState. */
102 typedef enum
103 {
104     eRunning = 0, /* A task is querying the state of itself, so must be running. */
105     eReady,       /* The task being queried is in a ready or pending ready list. */
106     eBlocked,     /* The task being queried is in the Blocked state. */
107     eSuspended,   /* The task being queried is in the Suspended state, or is in the Blocked state with an infinite time out. */
108     eDeleted,     /* The task being queried has been deleted, but its TCB has not yet been freed. */
109     eInvalid      /* Used as an 'invalid state' value. */
110 } eTaskState;
111 
112 /* Actions that can be performed when vTaskNotify() is called. */
113 typedef enum
114 {
115     eNoAction = 0,            /* Notify the task without updating its notify value. */
116     eSetBits,                 /* Set bits in the task's notification value. */
117     eIncrement,               /* Increment the task's notification value. */
118     eSetValueWithOverwrite,   /* Set the task's notification value to a specific value even if the previous value has not yet been read by the task. */
119     eSetValueWithoutOverwrite /* Set the task's notification value if the previous value has been read by the task. */
120 } eNotifyAction;
121 
122 /*
123  * Used internally only.
124  */
125 typedef struct xTIME_OUT
126 {
127     BaseType_t xOverflowCount;
128     TickType_t xTimeOnEntering;
129 } TimeOut_t;
130 
131 /*
132  * Defines the memory ranges allocated to the task when an MPU is used.
133  */
134 typedef struct xMEMORY_REGION
135 {
136     void * pvBaseAddress;
137     uint32_t ulLengthInBytes;
138     uint32_t ulParameters;
139 } MemoryRegion_t;
140 
141 /*
142  * Parameters required to create an MPU protected task.
143  */
144 typedef struct xTASK_PARAMETERS
145 {
146     TaskFunction_t pvTaskCode;
147     const char * pcName;
148     configSTACK_DEPTH_TYPE usStackDepth;
149     void * pvParameters;
150     UBaseType_t uxPriority;
151     StackType_t * puxStackBuffer;
152     MemoryRegion_t xRegions[ portNUM_CONFIGURABLE_REGIONS ];
153     #if ( ( portUSING_MPU_WRAPPERS == 1 ) && ( configSUPPORT_STATIC_ALLOCATION == 1 ) )
154         StaticTask_t * const pxTaskBuffer;
155     #endif
156 } TaskParameters_t;
157 
158 /* Used with the uxTaskGetSystemState() function to return the state of each task
159  * in the system. */
160 typedef struct xTASK_STATUS
161 {
162     TaskHandle_t xHandle;                         /* The handle of the task to which the rest of the information in the structure relates. */
163     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! */
164     UBaseType_t xTaskNumber;                      /* A number unique to the task. */
165     eTaskState eCurrentState;                     /* The state in which the task existed when the structure was populated. */
166     UBaseType_t uxCurrentPriority;                /* The priority at which the task was running (may be inherited) when the structure was populated. */
167     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. */
168     configRUN_TIME_COUNTER_TYPE ulRunTimeCounter; /* The total run time allocated to the task so far, as defined by the run time stats clock.  See https://www.FreeRTOS.org/rtos-run-time-stats.html.  Only valid when configGENERATE_RUN_TIME_STATS is defined as 1 in FreeRTOSConfig.h. */
169     StackType_t * pxStackBase;                    /* Points to the lowest address of the task's stack area. */
170     #if ( ( portSTACK_GROWTH > 0 ) || ( configRECORD_STACK_HIGH_ADDRESS == 1 ) )
171         StackType_t * pxTopOfStack;               /* Points to the top address of the task's stack area. */
172         StackType_t * pxEndOfStack;               /* Points to the end address of the task's stack area. */
173     #endif
174     configSTACK_DEPTH_TYPE 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. */
175     #if ( ( configUSE_CORE_AFFINITY == 1 ) && ( configNUMBER_OF_CORES > 1 ) )
176         UBaseType_t uxCoreAffinityMask;           /* The core affinity mask for the task */
177     #endif
178 } TaskStatus_t;
179 
180 /* Possible return values for eTaskConfirmSleepModeStatus(). */
181 typedef enum
182 {
183     eAbortSleep = 0, /* A task has been made ready or a context switch pended since portSUPPRESS_TICKS_AND_SLEEP() was called - abort entering a sleep mode. */
184     eStandardSleep   /* Enter a sleep mode that will not last any longer than the expected idle time. */
185     #if ( INCLUDE_vTaskSuspend == 1 )
186         ,
187         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. */
188     #endif /* INCLUDE_vTaskSuspend */
189 } eSleepModeStatus;
190 
191 /**
192  * Defines the priority used by the idle task.  This must not be modified.
193  *
194  * \ingroup TaskUtils
195  */
196 #define tskIDLE_PRIORITY    ( ( UBaseType_t ) 0U )
197 
198 /**
199  * Defines affinity to all available cores.
200  *
201  * \ingroup TaskUtils
202  */
203 #define tskNO_AFFINITY      ( ( UBaseType_t ) -1 )
204 
205 /**
206  * task. h
207  *
208  * Macro for forcing a context switch.
209  *
210  * \defgroup taskYIELD taskYIELD
211  * \ingroup SchedulerControl
212  */
213 #define taskYIELD()                          portYIELD()
214 
215 /**
216  * task. h
217  *
218  * Macro to mark the start of a critical code region.  Preemptive context
219  * switches cannot occur when in a critical region.
220  *
221  * NOTE: This may alter the stack (depending on the portable implementation)
222  * so must be used with care!
223  *
224  * \defgroup taskENTER_CRITICAL taskENTER_CRITICAL
225  * \ingroup SchedulerControl
226  */
227 #define taskENTER_CRITICAL()                 portENTER_CRITICAL()
228 #if ( configNUMBER_OF_CORES == 1 )
229     #define taskENTER_CRITICAL_FROM_ISR()    portSET_INTERRUPT_MASK_FROM_ISR()
230 #else
231     #define taskENTER_CRITICAL_FROM_ISR()    portENTER_CRITICAL_FROM_ISR()
232 #endif
233 
234 /**
235  * task. h
236  *
237  * Macro to mark the end of a critical code region.  Preemptive context
238  * switches cannot occur when in a critical region.
239  *
240  * NOTE: This may alter the stack (depending on the portable implementation)
241  * so must be used with care!
242  *
243  * \defgroup taskEXIT_CRITICAL taskEXIT_CRITICAL
244  * \ingroup SchedulerControl
245  */
246 #define taskEXIT_CRITICAL()                    portEXIT_CRITICAL()
247 #if ( configNUMBER_OF_CORES == 1 )
248     #define taskEXIT_CRITICAL_FROM_ISR( x )    portCLEAR_INTERRUPT_MASK_FROM_ISR( x )
249 #else
250     #define taskEXIT_CRITICAL_FROM_ISR( x )    portEXIT_CRITICAL_FROM_ISR( x )
251 #endif
252 
253 /**
254  * task. h
255  *
256  * Macro to disable all maskable interrupts.
257  *
258  * \defgroup taskDISABLE_INTERRUPTS taskDISABLE_INTERRUPTS
259  * \ingroup SchedulerControl
260  */
261 #define taskDISABLE_INTERRUPTS()    portDISABLE_INTERRUPTS()
262 
263 /**
264  * task. h
265  *
266  * Macro to enable microcontroller interrupts.
267  *
268  * \defgroup taskENABLE_INTERRUPTS taskENABLE_INTERRUPTS
269  * \ingroup SchedulerControl
270  */
271 #define taskENABLE_INTERRUPTS()     portENABLE_INTERRUPTS()
272 
273 /* Definitions returned by xTaskGetSchedulerState().  taskSCHEDULER_SUSPENDED is
274  * 0 to generate more optimal code when configASSERT() is defined as the constant
275  * is used in assert() statements. */
276 #define taskSCHEDULER_SUSPENDED      ( ( BaseType_t ) 0 )
277 #define taskSCHEDULER_NOT_STARTED    ( ( BaseType_t ) 1 )
278 #define taskSCHEDULER_RUNNING        ( ( BaseType_t ) 2 )
279 
280 /* Checks if core ID is valid. */
281 #define taskVALID_CORE_ID( xCoreID )    ( ( ( ( ( BaseType_t ) 0 <= ( xCoreID ) ) && ( ( xCoreID ) < ( BaseType_t ) configNUMBER_OF_CORES ) ) ) ? ( pdTRUE ) : ( pdFALSE ) )
282 
283 /*-----------------------------------------------------------
284 * TASK CREATION API
285 *----------------------------------------------------------*/
286 
287 /**
288  * task. h
289  * @code{c}
290  * BaseType_t xTaskCreate(
291  *                            TaskFunction_t pxTaskCode,
292  *                            const char * const pcName,
293  *                            const configSTACK_DEPTH_TYPE uxStackDepth,
294  *                            void *pvParameters,
295  *                            UBaseType_t uxPriority,
296  *                            TaskHandle_t *pxCreatedTask
297  *                        );
298  * @endcode
299  *
300  * Create a new task and add it to the list of tasks that are ready to run.
301  *
302  * Internally, within the FreeRTOS implementation, tasks use two blocks of
303  * memory.  The first block is used to hold the task's data structures.  The
304  * second block is used by the task as its stack.  If a task is created using
305  * xTaskCreate() then both blocks of memory are automatically dynamically
306  * allocated inside the xTaskCreate() function.  (see
307  * https://www.FreeRTOS.org/a00111.html).  If a task is created using
308  * xTaskCreateStatic() then the application writer must provide the required
309  * memory.  xTaskCreateStatic() therefore allows a task to be created without
310  * using any dynamic memory allocation.
311  *
312  * See xTaskCreateStatic() for a version that does not use any dynamic memory
313  * allocation.
314  *
315  * xTaskCreate() can only be used to create a task that has unrestricted
316  * access to the entire microcontroller memory map.  Systems that include MPU
317  * support can alternatively create an MPU constrained task using
318  * xTaskCreateRestricted().
319  *
320  * @param pxTaskCode Pointer to the task entry function.  Tasks
321  * must be implemented to never return (i.e. continuous loop).
322  *
323  * @param pcName A descriptive name for the task.  This is mainly used to
324  * facilitate debugging.  Max length defined by configMAX_TASK_NAME_LEN - default
325  * is 16.
326  *
327  * @param uxStackDepth The size of the task stack specified as the number of
328  * variables the stack can hold - not the number of bytes.  For example, if
329  * the stack is 16 bits wide and uxStackDepth is defined as 100, 200 bytes
330  * will be allocated for stack storage.
331  *
332  * @param pvParameters Pointer that will be used as the parameter for the task
333  * being created.
334  *
335  * @param uxPriority The priority at which the task should run.  Systems that
336  * include MPU support can optionally create tasks in a privileged (system)
337  * mode by setting bit portPRIVILEGE_BIT of the priority parameter.  For
338  * example, to create a privileged task at priority 2 the uxPriority parameter
339  * should be set to ( 2 | portPRIVILEGE_BIT ).
340  *
341  * @param pxCreatedTask Used to pass back a handle by which the created task
342  * can be referenced.
343  *
344  * @return pdPASS if the task was successfully created and added to a ready
345  * list, otherwise an error code defined in the file projdefs.h
346  *
347  * Example usage:
348  * @code{c}
349  * // Task to be created.
350  * void vTaskCode( void * pvParameters )
351  * {
352  *   for( ;; )
353  *   {
354  *       // Task code goes here.
355  *   }
356  * }
357  *
358  * // Function that creates a task.
359  * void vOtherFunction( void )
360  * {
361  * static uint8_t ucParameterToPass;
362  * TaskHandle_t xHandle = NULL;
363  *
364  *   // Create the task, storing the handle.  Note that the passed parameter ucParameterToPass
365  *   // must exist for the lifetime of the task, so in this case is declared static.  If it was just an
366  *   // an automatic stack variable it might no longer exist, or at least have been corrupted, by the time
367  *   // the new task attempts to access it.
368  *   xTaskCreate( vTaskCode, "NAME", STACK_SIZE, &ucParameterToPass, tskIDLE_PRIORITY, &xHandle );
369  *   configASSERT( xHandle );
370  *
371  *   // Use the handle to delete the task.
372  *   if( xHandle != NULL )
373  *   {
374  *      vTaskDelete( xHandle );
375  *   }
376  * }
377  * @endcode
378  * \defgroup xTaskCreate xTaskCreate
379  * \ingroup Tasks
380  */
381 #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
382     BaseType_t xTaskCreate( TaskFunction_t pxTaskCode,
383                             const char * const pcName,
384                             const configSTACK_DEPTH_TYPE uxStackDepth,
385                             void * const pvParameters,
386                             UBaseType_t uxPriority,
387                             TaskHandle_t * const pxCreatedTask ) PRIVILEGED_FUNCTION;
388 #endif
389 
390 #if ( ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) && ( configNUMBER_OF_CORES > 1 ) && ( configUSE_CORE_AFFINITY == 1 ) )
391     BaseType_t xTaskCreateAffinitySet( TaskFunction_t pxTaskCode,
392                                        const char * const pcName,
393                                        const configSTACK_DEPTH_TYPE uxStackDepth,
394                                        void * const pvParameters,
395                                        UBaseType_t uxPriority,
396                                        UBaseType_t uxCoreAffinityMask,
397                                        TaskHandle_t * const pxCreatedTask ) PRIVILEGED_FUNCTION;
398 #endif
399 
400 /**
401  * task. h
402  * @code{c}
403  * TaskHandle_t xTaskCreateStatic( TaskFunction_t pxTaskCode,
404  *                               const char * const pcName,
405  *                               const configSTACK_DEPTH_TYPE uxStackDepth,
406  *                               void *pvParameters,
407  *                               UBaseType_t uxPriority,
408  *                               StackType_t *puxStackBuffer,
409  *                               StaticTask_t *pxTaskBuffer );
410  * @endcode
411  *
412  * Create a new task and add it to the list of tasks that are ready to run.
413  *
414  * Internally, within the FreeRTOS implementation, tasks use two blocks of
415  * memory.  The first block is used to hold the task's data structures.  The
416  * second block is used by the task as its stack.  If a task is created using
417  * xTaskCreate() then both blocks of memory are automatically dynamically
418  * allocated inside the xTaskCreate() function.  (see
419  * https://www.FreeRTOS.org/a00111.html).  If a task is created using
420  * xTaskCreateStatic() then the application writer must provide the required
421  * memory.  xTaskCreateStatic() therefore allows a task to be created without
422  * using any dynamic memory allocation.
423  *
424  * @param pxTaskCode Pointer to the task entry function.  Tasks
425  * must be implemented to never return (i.e. continuous loop).
426  *
427  * @param pcName A descriptive name for the task.  This is mainly used to
428  * facilitate debugging.  The maximum length of the string is defined by
429  * configMAX_TASK_NAME_LEN in FreeRTOSConfig.h.
430  *
431  * @param uxStackDepth The size of the task stack specified as the number of
432  * variables the stack can hold - not the number of bytes.  For example, if
433  * the stack is 32-bits wide and uxStackDepth is defined as 100 then 400 bytes
434  * will be allocated for stack storage.
435  *
436  * @param pvParameters Pointer that will be used as the parameter for the task
437  * being created.
438  *
439  * @param uxPriority The priority at which the task will run.
440  *
441  * @param puxStackBuffer Must point to a StackType_t array that has at least
442  * uxStackDepth indexes - the array will then be used as the task's stack,
443  * removing the need for the stack to be allocated dynamically.
444  *
445  * @param pxTaskBuffer Must point to a variable of type StaticTask_t, which will
446  * then be used to hold the task's data structures, removing the need for the
447  * memory to be allocated dynamically.
448  *
449  * @return If neither puxStackBuffer nor pxTaskBuffer are NULL, then the task
450  * will be created and a handle to the created task is returned.  If either
451  * puxStackBuffer or pxTaskBuffer are NULL then the task will not be created and
452  * NULL is returned.
453  *
454  * Example usage:
455  * @code{c}
456  *
457  *  // Dimensions of the buffer that the task being created will use as its stack.
458  *  // NOTE:  This is the number of words the stack will hold, not the number of
459  *  // bytes.  For example, if each stack item is 32-bits, and this is set to 100,
460  *  // then 400 bytes (100 * 32-bits) will be allocated.
461  #define STACK_SIZE 200
462  *
463  *  // Structure that will hold the TCB of the task being created.
464  *  StaticTask_t xTaskBuffer;
465  *
466  *  // Buffer that the task being created will use as its stack.  Note this is
467  *  // an array of StackType_t variables.  The size of StackType_t is dependent on
468  *  // the RTOS port.
469  *  StackType_t xStack[ STACK_SIZE ];
470  *
471  *  // Function that implements the task being created.
472  *  void vTaskCode( void * pvParameters )
473  *  {
474  *      // The parameter value is expected to be 1 as 1 is passed in the
475  *      // pvParameters value in the call to xTaskCreateStatic().
476  *      configASSERT( ( uint32_t ) pvParameters == 1U );
477  *
478  *      for( ;; )
479  *      {
480  *          // Task code goes here.
481  *      }
482  *  }
483  *
484  *  // Function that creates a task.
485  *  void vOtherFunction( void )
486  *  {
487  *      TaskHandle_t xHandle = NULL;
488  *
489  *      // Create the task without using any dynamic memory allocation.
490  *      xHandle = xTaskCreateStatic(
491  *                    vTaskCode,       // Function that implements the task.
492  *                    "NAME",          // Text name for the task.
493  *                    STACK_SIZE,      // Stack size in words, not bytes.
494  *                    ( void * ) 1,    // Parameter passed into the task.
495  *                    tskIDLE_PRIORITY,// Priority at which the task is created.
496  *                    xStack,          // Array to use as the task's stack.
497  *                    &xTaskBuffer );  // Variable to hold the task's data structure.
498  *
499  *      // puxStackBuffer and pxTaskBuffer were not NULL, so the task will have
500  *      // been created, and xHandle will be the task's handle.  Use the handle
501  *      // to suspend the task.
502  *      vTaskSuspend( xHandle );
503  *  }
504  * @endcode
505  * \defgroup xTaskCreateStatic xTaskCreateStatic
506  * \ingroup Tasks
507  */
508 #if ( configSUPPORT_STATIC_ALLOCATION == 1 )
509     TaskHandle_t xTaskCreateStatic( TaskFunction_t pxTaskCode,
510                                     const char * const pcName,
511                                     const configSTACK_DEPTH_TYPE uxStackDepth,
512                                     void * const pvParameters,
513                                     UBaseType_t uxPriority,
514                                     StackType_t * const puxStackBuffer,
515                                     StaticTask_t * const pxTaskBuffer ) PRIVILEGED_FUNCTION;
516 #endif /* configSUPPORT_STATIC_ALLOCATION */
517 
518 #if ( ( configSUPPORT_STATIC_ALLOCATION == 1 ) && ( configNUMBER_OF_CORES > 1 ) && ( configUSE_CORE_AFFINITY == 1 ) )
519     TaskHandle_t xTaskCreateStaticAffinitySet( TaskFunction_t pxTaskCode,
520                                                const char * const pcName,
521                                                const configSTACK_DEPTH_TYPE uxStackDepth,
522                                                void * const pvParameters,
523                                                UBaseType_t uxPriority,
524                                                StackType_t * const puxStackBuffer,
525                                                StaticTask_t * const pxTaskBuffer,
526                                                UBaseType_t uxCoreAffinityMask ) PRIVILEGED_FUNCTION;
527 #endif
528 
529 /**
530  * task. h
531  * @code{c}
532  * BaseType_t xTaskCreateRestricted( TaskParameters_t *pxTaskDefinition, TaskHandle_t *pxCreatedTask );
533  * @endcode
534  *
535  * Only available when configSUPPORT_DYNAMIC_ALLOCATION is set to 1.
536  *
537  * xTaskCreateRestricted() should only be used in systems that include an MPU
538  * implementation.
539  *
540  * Create a new task and add it to the list of tasks that are ready to run.
541  * The function parameters define the memory regions and associated access
542  * permissions allocated to the task.
543  *
544  * See xTaskCreateRestrictedStatic() for a version that does not use any
545  * dynamic memory allocation.
546  *
547  * @param pxTaskDefinition Pointer to a structure that contains a member
548  * for each of the normal xTaskCreate() parameters (see the xTaskCreate() API
549  * documentation) plus an optional stack buffer and the memory region
550  * definitions.
551  *
552  * @param pxCreatedTask Used to pass back a handle by which the created task
553  * can be referenced.
554  *
555  * @return pdPASS if the task was successfully created and added to a ready
556  * list, otherwise an error code defined in the file projdefs.h
557  *
558  * Example usage:
559  * @code{c}
560  * // Create an TaskParameters_t structure that defines the task to be created.
561  * static const TaskParameters_t xCheckTaskParameters =
562  * {
563  *  vATask,     // pvTaskCode - the function that implements the task.
564  *  "ATask",    // pcName - just a text name for the task to assist debugging.
565  *  100,        // uxStackDepth - the stack size DEFINED IN WORDS.
566  *  NULL,       // pvParameters - passed into the task function as the function parameters.
567  *  ( 1U | portPRIVILEGE_BIT ),// uxPriority - task priority, set the portPRIVILEGE_BIT if the task should run in a privileged state.
568  *  cStackBuffer,// puxStackBuffer - the buffer to be used as the task stack.
569  *
570  *  // xRegions - Allocate up to three separate memory regions for access by
571  *  // the task, with appropriate access permissions.  Different processors have
572  *  // different memory alignment requirements - refer to the FreeRTOS documentation
573  *  // for full information.
574  *  {
575  *      // Base address                 Length  Parameters
576  *      { cReadWriteArray,              32,     portMPU_REGION_READ_WRITE },
577  *      { cReadOnlyArray,               32,     portMPU_REGION_READ_ONLY },
578  *      { cPrivilegedOnlyAccessArray,   128,    portMPU_REGION_PRIVILEGED_READ_WRITE }
579  *  }
580  * };
581  *
582  * int main( void )
583  * {
584  * TaskHandle_t xHandle;
585  *
586  *  // Create a task from the const structure defined above.  The task handle
587  *  // is requested (the second parameter is not NULL) but in this case just for
588  *  // demonstration purposes as its not actually used.
589  *  xTaskCreateRestricted( &xRegTest1Parameters, &xHandle );
590  *
591  *  // Start the scheduler.
592  *  vTaskStartScheduler();
593  *
594  *  // Will only get here if there was insufficient memory to create the idle
595  *  // and/or timer task.
596  *  for( ;; );
597  * }
598  * @endcode
599  * \defgroup xTaskCreateRestricted xTaskCreateRestricted
600  * \ingroup Tasks
601  */
602 #if ( portUSING_MPU_WRAPPERS == 1 )
603     BaseType_t xTaskCreateRestricted( const TaskParameters_t * const pxTaskDefinition,
604                                       TaskHandle_t * pxCreatedTask ) PRIVILEGED_FUNCTION;
605 #endif
606 
607 #if ( ( portUSING_MPU_WRAPPERS == 1 ) && ( configNUMBER_OF_CORES > 1 ) && ( configUSE_CORE_AFFINITY == 1 ) )
608     BaseType_t xTaskCreateRestrictedAffinitySet( const TaskParameters_t * const pxTaskDefinition,
609                                                  UBaseType_t uxCoreAffinityMask,
610                                                  TaskHandle_t * pxCreatedTask ) PRIVILEGED_FUNCTION;
611 #endif
612 
613 /**
614  * task. h
615  * @code{c}
616  * BaseType_t xTaskCreateRestrictedStatic( TaskParameters_t *pxTaskDefinition, TaskHandle_t *pxCreatedTask );
617  * @endcode
618  *
619  * Only available when configSUPPORT_STATIC_ALLOCATION is set to 1.
620  *
621  * xTaskCreateRestrictedStatic() should only be used in systems that include an
622  * MPU implementation.
623  *
624  * Internally, within the FreeRTOS implementation, tasks use two blocks of
625  * memory.  The first block is used to hold the task's data structures.  The
626  * second block is used by the task as its stack.  If a task is created using
627  * xTaskCreateRestricted() then the stack is provided by the application writer,
628  * and the memory used to hold the task's data structure is automatically
629  * dynamically allocated inside the xTaskCreateRestricted() function.  If a task
630  * is created using xTaskCreateRestrictedStatic() then the application writer
631  * must provide the memory used to hold the task's data structures too.
632  * xTaskCreateRestrictedStatic() therefore allows a memory protected task to be
633  * created without using any dynamic memory allocation.
634  *
635  * @param pxTaskDefinition Pointer to a structure that contains a member
636  * for each of the normal xTaskCreate() parameters (see the xTaskCreate() API
637  * documentation) plus an optional stack buffer and the memory region
638  * definitions.  If configSUPPORT_STATIC_ALLOCATION is set to 1 the structure
639  * contains an additional member, which is used to point to a variable of type
640  * StaticTask_t - which is then used to hold the task's data structure.
641  *
642  * @param pxCreatedTask Used to pass back a handle by which the created task
643  * can be referenced.
644  *
645  * @return pdPASS if the task was successfully created and added to a ready
646  * list, otherwise an error code defined in the file projdefs.h
647  *
648  * Example usage:
649  * @code{c}
650  * // Create an TaskParameters_t structure that defines the task to be created.
651  * // The StaticTask_t variable is only included in the structure when
652  * // configSUPPORT_STATIC_ALLOCATION is set to 1.  The PRIVILEGED_DATA macro can
653  * // be used to force the variable into the RTOS kernel's privileged data area.
654  * static PRIVILEGED_DATA StaticTask_t xTaskBuffer;
655  * static const TaskParameters_t xCheckTaskParameters =
656  * {
657  *  vATask,     // pvTaskCode - the function that implements the task.
658  *  "ATask",    // pcName - just a text name for the task to assist debugging.
659  *  100,        // uxStackDepth - the stack size DEFINED IN WORDS.
660  *  NULL,       // pvParameters - passed into the task function as the function parameters.
661  *  ( 1U | portPRIVILEGE_BIT ),// uxPriority - task priority, set the portPRIVILEGE_BIT if the task should run in a privileged state.
662  *  cStackBuffer,// puxStackBuffer - the buffer to be used as the task stack.
663  *
664  *  // xRegions - Allocate up to three separate memory regions for access by
665  *  // the task, with appropriate access permissions.  Different processors have
666  *  // different memory alignment requirements - refer to the FreeRTOS documentation
667  *  // for full information.
668  *  {
669  *      // Base address                 Length  Parameters
670  *      { cReadWriteArray,              32,     portMPU_REGION_READ_WRITE },
671  *      { cReadOnlyArray,               32,     portMPU_REGION_READ_ONLY },
672  *      { cPrivilegedOnlyAccessArray,   128,    portMPU_REGION_PRIVILEGED_READ_WRITE }
673  *  }
674  *
675  *  &xTaskBuffer; // Holds the task's data structure.
676  * };
677  *
678  * int main( void )
679  * {
680  * TaskHandle_t xHandle;
681  *
682  *  // Create a task from the const structure defined above.  The task handle
683  *  // is requested (the second parameter is not NULL) but in this case just for
684  *  // demonstration purposes as its not actually used.
685  *  xTaskCreateRestrictedStatic( &xRegTest1Parameters, &xHandle );
686  *
687  *  // Start the scheduler.
688  *  vTaskStartScheduler();
689  *
690  *  // Will only get here if there was insufficient memory to create the idle
691  *  // and/or timer task.
692  *  for( ;; );
693  * }
694  * @endcode
695  * \defgroup xTaskCreateRestrictedStatic xTaskCreateRestrictedStatic
696  * \ingroup Tasks
697  */
698 #if ( ( portUSING_MPU_WRAPPERS == 1 ) && ( configSUPPORT_STATIC_ALLOCATION == 1 ) )
699     BaseType_t xTaskCreateRestrictedStatic( const TaskParameters_t * const pxTaskDefinition,
700                                             TaskHandle_t * pxCreatedTask ) PRIVILEGED_FUNCTION;
701 #endif
702 
703 #if ( ( portUSING_MPU_WRAPPERS == 1 ) && ( configSUPPORT_STATIC_ALLOCATION == 1 ) && ( configNUMBER_OF_CORES > 1 ) && ( configUSE_CORE_AFFINITY == 1 ) )
704     BaseType_t xTaskCreateRestrictedStaticAffinitySet( const TaskParameters_t * const pxTaskDefinition,
705                                                        UBaseType_t uxCoreAffinityMask,
706                                                        TaskHandle_t * pxCreatedTask ) PRIVILEGED_FUNCTION;
707 #endif
708 
709 /**
710  * task. h
711  * @code{c}
712  * void vTaskAllocateMPURegions( TaskHandle_t xTask, const MemoryRegion_t * const pxRegions );
713  * @endcode
714  *
715  * Memory regions are assigned to a restricted task when the task is created by
716  * a call to xTaskCreateRestricted().  These regions can be redefined using
717  * vTaskAllocateMPURegions().
718  *
719  * @param xTaskToModify The handle of the task being updated.
720  *
721  * @param[in] pxRegions A pointer to a MemoryRegion_t structure that contains the
722  * new memory region definitions.
723  *
724  * Example usage:
725  * @code{c}
726  * // Define an array of MemoryRegion_t structures that configures an MPU region
727  * // allowing read/write access for 1024 bytes starting at the beginning of the
728  * // ucOneKByte array.  The other two of the maximum 3 definable regions are
729  * // unused so set to zero.
730  * static const MemoryRegion_t xAltRegions[ portNUM_CONFIGURABLE_REGIONS ] =
731  * {
732  *  // Base address     Length      Parameters
733  *  { ucOneKByte,       1024,       portMPU_REGION_READ_WRITE },
734  *  { 0,                0,          0 },
735  *  { 0,                0,          0 }
736  * };
737  *
738  * void vATask( void *pvParameters )
739  * {
740  *  // This task was created such that it has access to certain regions of
741  *  // memory as defined by the MPU configuration.  At some point it is
742  *  // desired that these MPU regions are replaced with that defined in the
743  *  // xAltRegions const struct above.  Use a call to vTaskAllocateMPURegions()
744  *  // for this purpose.  NULL is used as the task handle to indicate that this
745  *  // function should modify the MPU regions of the calling task.
746  *  vTaskAllocateMPURegions( NULL, xAltRegions );
747  *
748  *  // Now the task can continue its function, but from this point on can only
749  *  // access its stack and the ucOneKByte array (unless any other statically
750  *  // defined or shared regions have been declared elsewhere).
751  * }
752  * @endcode
753  * \defgroup vTaskAllocateMPURegions vTaskAllocateMPURegions
754  * \ingroup Tasks
755  */
756 #if ( portUSING_MPU_WRAPPERS == 1 )
757     void vTaskAllocateMPURegions( TaskHandle_t xTaskToModify,
758                                   const MemoryRegion_t * const pxRegions ) PRIVILEGED_FUNCTION;
759 #endif
760 
761 /**
762  * task. h
763  * @code{c}
764  * void vTaskDelete( TaskHandle_t xTaskToDelete );
765  * @endcode
766  *
767  * INCLUDE_vTaskDelete must be defined as 1 for this function to be available.
768  * See the configuration section for more information.
769  *
770  * Remove a task from the RTOS real time kernel's management.  The task being
771  * deleted will be removed from all ready, blocked, suspended and event lists.
772  *
773  * NOTE:  The idle task is responsible for freeing the kernel allocated
774  * memory from tasks that have been deleted.  It is therefore important that
775  * the idle task is not starved of microcontroller processing time if your
776  * application makes any calls to vTaskDelete ().  Memory allocated by the
777  * task code is not automatically freed, and should be freed before the task
778  * is deleted.
779  *
780  * See the demo application file death.c for sample code that utilises
781  * vTaskDelete ().
782  *
783  * @param xTaskToDelete The handle of the task to be deleted.  Passing NULL will
784  * cause the calling task to be deleted.
785  *
786  * Example usage:
787  * @code{c}
788  * void vOtherFunction( void )
789  * {
790  * TaskHandle_t xHandle;
791  *
792  *   // Create the task, storing the handle.
793  *   xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
794  *
795  *   // Use the handle to delete the task.
796  *   vTaskDelete( xHandle );
797  * }
798  * @endcode
799  * \defgroup vTaskDelete vTaskDelete
800  * \ingroup Tasks
801  */
802 void vTaskDelete( TaskHandle_t xTaskToDelete ) PRIVILEGED_FUNCTION;
803 
804 /*-----------------------------------------------------------
805 * TASK CONTROL API
806 *----------------------------------------------------------*/
807 
808 /**
809  * task. h
810  * @code{c}
811  * void vTaskDelay( const TickType_t xTicksToDelay );
812  * @endcode
813  *
814  * Delay a task for a given number of ticks.  The actual time that the
815  * task remains blocked depends on the tick rate.  The constant
816  * portTICK_PERIOD_MS can be used to calculate real time from the tick
817  * rate - with the resolution of one tick period.
818  *
819  * INCLUDE_vTaskDelay must be defined as 1 for this function to be available.
820  * See the configuration section for more information.
821  *
822  *
823  * vTaskDelay() specifies a time at which the task wishes to unblock relative to
824  * the time at which vTaskDelay() is called.  For example, specifying a block
825  * period of 100 ticks will cause the task to unblock 100 ticks after
826  * vTaskDelay() is called.  vTaskDelay() does not therefore provide a good method
827  * of controlling the frequency of a periodic task as the path taken through the
828  * code, as well as other task and interrupt activity, will affect the frequency
829  * at which vTaskDelay() gets called and therefore the time at which the task
830  * next executes.  See xTaskDelayUntil() for an alternative API function designed
831  * to facilitate fixed frequency execution.  It does this by specifying an
832  * absolute time (rather than a relative time) at which the calling task should
833  * unblock.
834  *
835  * @param xTicksToDelay The amount of time, in tick periods, that
836  * the calling task should block.
837  *
838  * Example usage:
839  *
840  * void vTaskFunction( void * pvParameters )
841  * {
842  * // Block for 500ms.
843  * const TickType_t xDelay = 500 / portTICK_PERIOD_MS;
844  *
845  *   for( ;; )
846  *   {
847  *       // Simply toggle the LED every 500ms, blocking between each toggle.
848  *       vToggleLED();
849  *       vTaskDelay( xDelay );
850  *   }
851  * }
852  *
853  * \defgroup vTaskDelay vTaskDelay
854  * \ingroup TaskCtrl
855  */
856 void vTaskDelay( const TickType_t xTicksToDelay ) PRIVILEGED_FUNCTION;
857 
858 /**
859  * task. h
860  * @code{c}
861  * BaseType_t xTaskDelayUntil( TickType_t *pxPreviousWakeTime, const TickType_t xTimeIncrement );
862  * @endcode
863  *
864  * INCLUDE_xTaskDelayUntil must be defined as 1 for this function to be available.
865  * See the configuration section for more information.
866  *
867  * Delay a task until a specified time.  This function can be used by periodic
868  * tasks to ensure a constant execution frequency.
869  *
870  * This function differs from vTaskDelay () in one important aspect:  vTaskDelay () will
871  * cause a task to block for the specified number of ticks from the time vTaskDelay () is
872  * called.  It is therefore difficult to use vTaskDelay () by itself to generate a fixed
873  * execution frequency as the time between a task starting to execute and that task
874  * calling vTaskDelay () may not be fixed [the task may take a different path though the
875  * code between calls, or may get interrupted or preempted a different number of times
876  * each time it executes].
877  *
878  * Whereas vTaskDelay () specifies a wake time relative to the time at which the function
879  * is called, xTaskDelayUntil () specifies the absolute (exact) time at which it wishes to
880  * unblock.
881  *
882  * The macro pdMS_TO_TICKS() can be used to calculate the number of ticks from a
883  * time specified in milliseconds with a resolution of one tick period.
884  *
885  * @param pxPreviousWakeTime Pointer to a variable that holds the time at which the
886  * task was last unblocked.  The variable must be initialised with the current time
887  * prior to its first use (see the example below).  Following this the variable is
888  * automatically updated within xTaskDelayUntil ().
889  *
890  * @param xTimeIncrement The cycle time period.  The task will be unblocked at
891  * time *pxPreviousWakeTime + xTimeIncrement.  Calling xTaskDelayUntil with the
892  * same xTimeIncrement parameter value will cause the task to execute with
893  * a fixed interface period.
894  *
895  * @return Value which can be used to check whether the task was actually delayed.
896  * Will be pdTRUE if the task way delayed and pdFALSE otherwise.  A task will not
897  * be delayed if the next expected wake time is in the past.
898  *
899  * Example usage:
900  * @code{c}
901  * // Perform an action every 10 ticks.
902  * void vTaskFunction( void * pvParameters )
903  * {
904  * TickType_t xLastWakeTime;
905  * const TickType_t xFrequency = 10;
906  * BaseType_t xWasDelayed;
907  *
908  *     // Initialise the xLastWakeTime variable with the current time.
909  *     xLastWakeTime = xTaskGetTickCount ();
910  *     for( ;; )
911  *     {
912  *         // Wait for the next cycle.
913  *         xWasDelayed = xTaskDelayUntil( &xLastWakeTime, xFrequency );
914  *
915  *         // Perform action here. xWasDelayed value can be used to determine
916  *         // whether a deadline was missed if the code here took too long.
917  *     }
918  * }
919  * @endcode
920  * \defgroup xTaskDelayUntil xTaskDelayUntil
921  * \ingroup TaskCtrl
922  */
923 BaseType_t xTaskDelayUntil( TickType_t * const pxPreviousWakeTime,
924                             const TickType_t xTimeIncrement ) PRIVILEGED_FUNCTION;
925 
926 /*
927  * vTaskDelayUntil() is the older version of xTaskDelayUntil() and does not
928  * return a value.
929  */
930 #define vTaskDelayUntil( pxPreviousWakeTime, xTimeIncrement )                   \
931     do {                                                                        \
932         ( void ) xTaskDelayUntil( ( pxPreviousWakeTime ), ( xTimeIncrement ) ); \
933     } while( 0 )
934 
935 
936 /**
937  * task. h
938  * @code{c}
939  * BaseType_t xTaskAbortDelay( TaskHandle_t xTask );
940  * @endcode
941  *
942  * INCLUDE_xTaskAbortDelay must be defined as 1 in FreeRTOSConfig.h for this
943  * function to be available.
944  *
945  * A task will enter the Blocked state when it is waiting for an event.  The
946  * event it is waiting for can be a temporal event (waiting for a time), such
947  * as when vTaskDelay() is called, or an event on an object, such as when
948  * xQueueReceive() or ulTaskNotifyTake() is called.  If the handle of a task
949  * that is in the Blocked state is used in a call to xTaskAbortDelay() then the
950  * task will leave the Blocked state, and return from whichever function call
951  * placed the task into the Blocked state.
952  *
953  * There is no 'FromISR' version of this function as an interrupt would need to
954  * know which object a task was blocked on in order to know which actions to
955  * take.  For example, if the task was blocked on a queue the interrupt handler
956  * would then need to know if the queue was locked.
957  *
958  * @param xTask The handle of the task to remove from the Blocked state.
959  *
960  * @return If the task referenced by xTask was not in the Blocked state then
961  * pdFAIL is returned.  Otherwise pdPASS is returned.
962  *
963  * \defgroup xTaskAbortDelay xTaskAbortDelay
964  * \ingroup TaskCtrl
965  */
966 #if ( INCLUDE_xTaskAbortDelay == 1 )
967     BaseType_t xTaskAbortDelay( TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
968 #endif
969 
970 /**
971  * task. h
972  * @code{c}
973  * UBaseType_t uxTaskPriorityGet( const TaskHandle_t xTask );
974  * @endcode
975  *
976  * INCLUDE_uxTaskPriorityGet must be defined as 1 for this function to be available.
977  * See the configuration section for more information.
978  *
979  * Obtain the priority of any task.
980  *
981  * @param xTask Handle of the task to be queried.  Passing a NULL
982  * handle results in the priority of the calling task being returned.
983  *
984  * @return The priority of xTask.
985  *
986  * Example usage:
987  * @code{c}
988  * void vAFunction( void )
989  * {
990  * TaskHandle_t xHandle;
991  *
992  *   // Create a task, storing the handle.
993  *   xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
994  *
995  *   // ...
996  *
997  *   // Use the handle to obtain the priority of the created task.
998  *   // It was created with tskIDLE_PRIORITY, but may have changed
999  *   // it itself.
1000  *   if( uxTaskPriorityGet( xHandle ) != tskIDLE_PRIORITY )
1001  *   {
1002  *       // The task has changed it's priority.
1003  *   }
1004  *
1005  *   // ...
1006  *
1007  *   // Is our priority higher than the created task?
1008  *   if( uxTaskPriorityGet( xHandle ) < uxTaskPriorityGet( NULL ) )
1009  *   {
1010  *       // Our priority (obtained using NULL handle) is higher.
1011  *   }
1012  * }
1013  * @endcode
1014  * \defgroup uxTaskPriorityGet uxTaskPriorityGet
1015  * \ingroup TaskCtrl
1016  */
1017 UBaseType_t uxTaskPriorityGet( const TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
1018 
1019 /**
1020  * task. h
1021  * @code{c}
1022  * UBaseType_t uxTaskPriorityGetFromISR( const TaskHandle_t xTask );
1023  * @endcode
1024  *
1025  * A version of uxTaskPriorityGet() that can be used from an ISR.
1026  */
1027 UBaseType_t uxTaskPriorityGetFromISR( const TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
1028 
1029 /**
1030  * task. h
1031  * @code{c}
1032  * UBaseType_t uxTaskBasePriorityGet( const TaskHandle_t xTask );
1033  * @endcode
1034  *
1035  * INCLUDE_uxTaskPriorityGet and configUSE_MUTEXES must be defined as 1 for this
1036  * function to be available. See the configuration section for more information.
1037  *
1038  * Obtain the base priority of any task.
1039  *
1040  * @param xTask Handle of the task to be queried.  Passing a NULL
1041  * handle results in the base priority of the calling task being returned.
1042  *
1043  * @return The base priority of xTask.
1044  *
1045  * \defgroup uxTaskPriorityGet uxTaskBasePriorityGet
1046  * \ingroup TaskCtrl
1047  */
1048 UBaseType_t uxTaskBasePriorityGet( const TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
1049 
1050 /**
1051  * task. h
1052  * @code{c}
1053  * UBaseType_t uxTaskBasePriorityGetFromISR( const TaskHandle_t xTask );
1054  * @endcode
1055  *
1056  * A version of uxTaskBasePriorityGet() that can be used from an ISR.
1057  */
1058 UBaseType_t uxTaskBasePriorityGetFromISR( const TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
1059 
1060 /**
1061  * task. h
1062  * @code{c}
1063  * eTaskState eTaskGetState( TaskHandle_t xTask );
1064  * @endcode
1065  *
1066  * INCLUDE_eTaskGetState must be defined as 1 for this function to be available.
1067  * See the configuration section for more information.
1068  *
1069  * Obtain the state of any task.  States are encoded by the eTaskState
1070  * enumerated type.
1071  *
1072  * @param xTask Handle of the task to be queried.
1073  *
1074  * @return The state of xTask at the time the function was called.  Note the
1075  * state of the task might change between the function being called, and the
1076  * functions return value being tested by the calling task.
1077  */
1078 #if ( ( INCLUDE_eTaskGetState == 1 ) || ( configUSE_TRACE_FACILITY == 1 ) || ( INCLUDE_xTaskAbortDelay == 1 ) )
1079     eTaskState eTaskGetState( TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
1080 #endif
1081 
1082 /**
1083  * task. h
1084  * @code{c}
1085  * void vTaskGetInfo( TaskHandle_t xTask, TaskStatus_t *pxTaskStatus, BaseType_t xGetFreeStackSpace, eTaskState eState );
1086  * @endcode
1087  *
1088  * configUSE_TRACE_FACILITY must be defined as 1 for this function to be
1089  * available.  See the configuration section for more information.
1090  *
1091  * Populates a TaskStatus_t structure with information about a task.
1092  *
1093  * @param xTask Handle of the task being queried.  If xTask is NULL then
1094  * information will be returned about the calling task.
1095  *
1096  * @param pxTaskStatus A pointer to the TaskStatus_t structure that will be
1097  * filled with information about the task referenced by the handle passed using
1098  * the xTask parameter.
1099  *
1100  * @param xGetFreeStackSpace The TaskStatus_t structure contains a member to report
1101  * the stack high water mark of the task being queried.  Calculating the stack
1102  * high water mark takes a relatively long time, and can make the system
1103  * temporarily unresponsive - so the xGetFreeStackSpace parameter is provided to
1104  * allow the high water mark checking to be skipped.  The high watermark value
1105  * will only be written to the TaskStatus_t structure if xGetFreeStackSpace is
1106  * not set to pdFALSE;
1107  *
1108  * @param eState The TaskStatus_t structure contains a member to report the
1109  * state of the task being queried.  Obtaining the task state is not as fast as
1110  * a simple assignment - so the eState parameter is provided to allow the state
1111  * information to be omitted from the TaskStatus_t structure.  To obtain state
1112  * information then set eState to eInvalid - otherwise the value passed in
1113  * eState will be reported as the task state in the TaskStatus_t structure.
1114  *
1115  * Example usage:
1116  * @code{c}
1117  * void vAFunction( void )
1118  * {
1119  * TaskHandle_t xHandle;
1120  * TaskStatus_t xTaskDetails;
1121  *
1122  *  // Obtain the handle of a task from its name.
1123  *  xHandle = xTaskGetHandle( "Task_Name" );
1124  *
1125  *  // Check the handle is not NULL.
1126  *  configASSERT( xHandle );
1127  *
1128  *  // Use the handle to obtain further information about the task.
1129  *  vTaskGetInfo( xHandle,
1130  *                &xTaskDetails,
1131  *                pdTRUE, // Include the high water mark in xTaskDetails.
1132  *                eInvalid ); // Include the task state in xTaskDetails.
1133  * }
1134  * @endcode
1135  * \defgroup vTaskGetInfo vTaskGetInfo
1136  * \ingroup TaskCtrl
1137  */
1138 #if ( configUSE_TRACE_FACILITY == 1 )
1139     void vTaskGetInfo( TaskHandle_t xTask,
1140                        TaskStatus_t * pxTaskStatus,
1141                        BaseType_t xGetFreeStackSpace,
1142                        eTaskState eState ) PRIVILEGED_FUNCTION;
1143 #endif
1144 
1145 /**
1146  * task. h
1147  * @code{c}
1148  * void vTaskPrioritySet( TaskHandle_t xTask, UBaseType_t uxNewPriority );
1149  * @endcode
1150  *
1151  * INCLUDE_vTaskPrioritySet must be defined as 1 for this function to be available.
1152  * See the configuration section for more information.
1153  *
1154  * Set the priority of any task.
1155  *
1156  * A context switch will occur before the function returns if the priority
1157  * being set is higher than the currently executing task.
1158  *
1159  * @param xTask Handle to the task for which the priority is being set.
1160  * Passing a NULL handle results in the priority of the calling task being set.
1161  *
1162  * @param uxNewPriority The priority to which the task will be set.
1163  *
1164  * Example usage:
1165  * @code{c}
1166  * void vAFunction( void )
1167  * {
1168  * TaskHandle_t xHandle;
1169  *
1170  *   // Create a task, storing the handle.
1171  *   xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
1172  *
1173  *   // ...
1174  *
1175  *   // Use the handle to raise the priority of the created task.
1176  *   vTaskPrioritySet( xHandle, tskIDLE_PRIORITY + 1 );
1177  *
1178  *   // ...
1179  *
1180  *   // Use a NULL handle to raise our priority to the same value.
1181  *   vTaskPrioritySet( NULL, tskIDLE_PRIORITY + 1 );
1182  * }
1183  * @endcode
1184  * \defgroup vTaskPrioritySet vTaskPrioritySet
1185  * \ingroup TaskCtrl
1186  */
1187 void vTaskPrioritySet( TaskHandle_t xTask,
1188                        UBaseType_t uxNewPriority ) PRIVILEGED_FUNCTION;
1189 
1190 /**
1191  * task. h
1192  * @code{c}
1193  * void vTaskSuspend( TaskHandle_t xTaskToSuspend );
1194  * @endcode
1195  *
1196  * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available.
1197  * See the configuration section for more information.
1198  *
1199  * Suspend any task.  When suspended a task will never get any microcontroller
1200  * processing time, no matter what its priority.
1201  *
1202  * Calls to vTaskSuspend are not accumulative -
1203  * i.e. calling vTaskSuspend () twice on the same task still only requires one
1204  * call to vTaskResume () to ready the suspended task.
1205  *
1206  * @param xTaskToSuspend Handle to the task being suspended.  Passing a NULL
1207  * handle will cause the calling task to be suspended.
1208  *
1209  * Example usage:
1210  * @code{c}
1211  * void vAFunction( void )
1212  * {
1213  * TaskHandle_t xHandle;
1214  *
1215  *   // Create a task, storing the handle.
1216  *   xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
1217  *
1218  *   // ...
1219  *
1220  *   // Use the handle to suspend the created task.
1221  *   vTaskSuspend( xHandle );
1222  *
1223  *   // ...
1224  *
1225  *   // The created task will not run during this period, unless
1226  *   // another task calls vTaskResume( xHandle ).
1227  *
1228  *   //...
1229  *
1230  *
1231  *   // Suspend ourselves.
1232  *   vTaskSuspend( NULL );
1233  *
1234  *   // We cannot get here unless another task calls vTaskResume
1235  *   // with our handle as the parameter.
1236  * }
1237  * @endcode
1238  * \defgroup vTaskSuspend vTaskSuspend
1239  * \ingroup TaskCtrl
1240  */
1241 void vTaskSuspend( TaskHandle_t xTaskToSuspend ) PRIVILEGED_FUNCTION;
1242 
1243 /**
1244  * task. h
1245  * @code{c}
1246  * void vTaskResume( TaskHandle_t xTaskToResume );
1247  * @endcode
1248  *
1249  * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available.
1250  * See the configuration section for more information.
1251  *
1252  * Resumes a suspended task.
1253  *
1254  * A task that has been suspended by one or more calls to vTaskSuspend ()
1255  * will be made available for running again by a single call to
1256  * vTaskResume ().
1257  *
1258  * @param xTaskToResume Handle to the task being readied.
1259  *
1260  * Example usage:
1261  * @code{c}
1262  * void vAFunction( void )
1263  * {
1264  * TaskHandle_t xHandle;
1265  *
1266  *   // Create a task, storing the handle.
1267  *   xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
1268  *
1269  *   // ...
1270  *
1271  *   // Use the handle to suspend the created task.
1272  *   vTaskSuspend( xHandle );
1273  *
1274  *   // ...
1275  *
1276  *   // The created task will not run during this period, unless
1277  *   // another task calls vTaskResume( xHandle ).
1278  *
1279  *   //...
1280  *
1281  *
1282  *   // Resume the suspended task ourselves.
1283  *   vTaskResume( xHandle );
1284  *
1285  *   // The created task will once again get microcontroller processing
1286  *   // time in accordance with its priority within the system.
1287  * }
1288  * @endcode
1289  * \defgroup vTaskResume vTaskResume
1290  * \ingroup TaskCtrl
1291  */
1292 void vTaskResume( TaskHandle_t xTaskToResume ) PRIVILEGED_FUNCTION;
1293 
1294 /**
1295  * task. h
1296  * @code{c}
1297  * void xTaskResumeFromISR( TaskHandle_t xTaskToResume );
1298  * @endcode
1299  *
1300  * INCLUDE_xTaskResumeFromISR must be defined as 1 for this function to be
1301  * available.  See the configuration section for more information.
1302  *
1303  * An implementation of vTaskResume() that can be called from within an ISR.
1304  *
1305  * A task that has been suspended by one or more calls to vTaskSuspend ()
1306  * will be made available for running again by a single call to
1307  * xTaskResumeFromISR ().
1308  *
1309  * xTaskResumeFromISR() should not be used to synchronise a task with an
1310  * interrupt if there is a chance that the interrupt could arrive prior to the
1311  * task being suspended - as this can lead to interrupts being missed. Use of a
1312  * semaphore as a synchronisation mechanism would avoid this eventuality.
1313  *
1314  * @param xTaskToResume Handle to the task being readied.
1315  *
1316  * @return pdTRUE if resuming the task should result in a context switch,
1317  * otherwise pdFALSE. This is used by the ISR to determine if a context switch
1318  * may be required following the ISR.
1319  *
1320  * \defgroup vTaskResumeFromISR vTaskResumeFromISR
1321  * \ingroup TaskCtrl
1322  */
1323 BaseType_t xTaskResumeFromISR( TaskHandle_t xTaskToResume ) PRIVILEGED_FUNCTION;
1324 
1325 #if ( configUSE_CORE_AFFINITY == 1 )
1326 
1327 /**
1328  * @brief Sets the core affinity mask for a task.
1329  *
1330  * It sets the cores on which a task can run. configUSE_CORE_AFFINITY must
1331  * be defined as 1 for this function to be available.
1332  *
1333  * @param xTask The handle of the task to set the core affinity mask for.
1334  * Passing NULL will set the core affinity mask for the calling task.
1335  *
1336  * @param uxCoreAffinityMask A bitwise value that indicates the cores on
1337  * which the task can run. Cores are numbered from 0 to configNUMBER_OF_CORES - 1.
1338  * For example, to ensure that a task can run on core 0 and core 1, set
1339  * uxCoreAffinityMask to 0x03.
1340  *
1341  * Example usage:
1342  *
1343  * // The function that creates task.
1344  * void vAFunction( void )
1345  * {
1346  * TaskHandle_t xHandle;
1347  * UBaseType_t uxCoreAffinityMask;
1348  *
1349  *      // Create a task, storing the handle.
1350  *      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &( xHandle ) );
1351  *
1352  *      // Define the core affinity mask such that this task can only run
1353  *      // on core 0 and core 2.
1354  *      uxCoreAffinityMask = ( ( 1 << 0 ) | ( 1 << 2 ) );
1355  *
1356  *      //Set the core affinity mask for the task.
1357  *      vTaskCoreAffinitySet( xHandle, uxCoreAffinityMask );
1358  * }
1359  */
1360     void vTaskCoreAffinitySet( const TaskHandle_t xTask,
1361                                UBaseType_t uxCoreAffinityMask );
1362 #endif
1363 
1364 #if ( ( configNUMBER_OF_CORES > 1 ) && ( configUSE_CORE_AFFINITY == 1 ) )
1365 
1366 /**
1367  * @brief Gets the core affinity mask for a task.
1368  *
1369  * configUSE_CORE_AFFINITY must be defined as 1 for this function to be
1370  * available.
1371  *
1372  * @param xTask The handle of the task to get the core affinity mask for.
1373  * Passing NULL will get the core affinity mask for the calling task.
1374  *
1375  * @return The core affinity mask which is a bitwise value that indicates
1376  * the cores on which a task can run. Cores are numbered from 0 to
1377  * configNUMBER_OF_CORES - 1. For example, if a task can run on core 0 and core 1,
1378  * the core affinity mask is 0x03.
1379  *
1380  * Example usage:
1381  *
1382  * // Task handle of the networking task - it is populated elsewhere.
1383  * TaskHandle_t xNetworkingTaskHandle;
1384  *
1385  * void vAFunction( void )
1386  * {
1387  * TaskHandle_t xHandle;
1388  * UBaseType_t uxNetworkingCoreAffinityMask;
1389  *
1390  *     // Create a task, storing the handle.
1391  *     xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &( xHandle ) );
1392  *
1393  *     //Get the core affinity mask for the networking task.
1394  *     uxNetworkingCoreAffinityMask = vTaskCoreAffinityGet( xNetworkingTaskHandle );
1395  *
1396  *     // Here is a hypothetical scenario, just for the example. Assume that we
1397  *     // have 2 cores - Core 0 and core 1. We want to pin the application task to
1398  *     // the core different than the networking task to ensure that the
1399  *     // application task does not interfere with networking.
1400  *     if( ( uxNetworkingCoreAffinityMask & ( 1 << 0 ) ) != 0 )
1401  *     {
1402  *         // The networking task can run on core 0, pin our task to core 1.
1403  *         vTaskCoreAffinitySet( xHandle, ( 1 << 1 ) );
1404  *     }
1405  *     else
1406  *     {
1407  *         // Otherwise, pin our task to core 0.
1408  *         vTaskCoreAffinitySet( xHandle, ( 1 << 0 ) );
1409  *     }
1410  * }
1411  */
1412     UBaseType_t vTaskCoreAffinityGet( ConstTaskHandle_t xTask );
1413 #endif
1414 
1415 #if ( configUSE_TASK_PREEMPTION_DISABLE == 1 )
1416 
1417 /**
1418  * @brief Disables preemption for a task.
1419  *
1420  * @param xTask The handle of the task to disable preemption. Passing NULL
1421  * disables preemption for the calling task.
1422  *
1423  * Example usage:
1424  *
1425  * void vTaskCode( void *pvParameters )
1426  * {
1427  *     // Silence warnings about unused parameters.
1428  *     ( void ) pvParameters;
1429  *
1430  *     for( ;; )
1431  *     {
1432  *         // ... Perform some function here.
1433  *
1434  *         // Disable preemption for this task.
1435  *         vTaskPreemptionDisable( NULL );
1436  *
1437  *         // The task will not be preempted when it is executing in this portion ...
1438  *
1439  *         // ... until the preemption is enabled again.
1440  *         vTaskPreemptionEnable( NULL );
1441  *
1442  *         // The task can be preempted when it is executing in this portion.
1443  *     }
1444  * }
1445  */
1446     void vTaskPreemptionDisable( const TaskHandle_t xTask );
1447 #endif
1448 
1449 #if ( configUSE_TASK_PREEMPTION_DISABLE == 1 )
1450 
1451 /**
1452  * @brief Enables preemption for a task.
1453  *
1454  * @param xTask The handle of the task to enable preemption. Passing NULL
1455  * enables preemption for the calling task.
1456  *
1457  * Example usage:
1458  *
1459  * void vTaskCode( void *pvParameters )
1460  * {
1461  *     // Silence warnings about unused parameters.
1462  *     ( void ) pvParameters;
1463  *
1464  *     for( ;; )
1465  *     {
1466  *         // ... Perform some function here.
1467  *
1468  *         // Disable preemption for this task.
1469  *         vTaskPreemptionDisable( NULL );
1470  *
1471  *         // The task will not be preempted when it is executing in this portion ...
1472  *
1473  *         // ... until the preemption is enabled again.
1474  *         vTaskPreemptionEnable( NULL );
1475  *
1476  *         // The task can be preempted when it is executing in this portion.
1477  *     }
1478  * }
1479  */
1480     void vTaskPreemptionEnable( const TaskHandle_t xTask );
1481 #endif
1482 
1483 /*-----------------------------------------------------------
1484 * SCHEDULER CONTROL
1485 *----------------------------------------------------------*/
1486 
1487 /**
1488  * task. h
1489  * @code{c}
1490  * void vTaskStartScheduler( void );
1491  * @endcode
1492  *
1493  * Starts the real time kernel tick processing.  After calling the kernel
1494  * has control over which tasks are executed and when.
1495  *
1496  * See the demo application file main.c for an example of creating
1497  * tasks and starting the kernel.
1498  *
1499  * Example usage:
1500  * @code{c}
1501  * void vAFunction( void )
1502  * {
1503  *   // Create at least one task before starting the kernel.
1504  *   xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL );
1505  *
1506  *   // Start the real time kernel with preemption.
1507  *   vTaskStartScheduler ();
1508  *
1509  *   // Will not get here unless a task calls vTaskEndScheduler ()
1510  * }
1511  * @endcode
1512  *
1513  * \defgroup vTaskStartScheduler vTaskStartScheduler
1514  * \ingroup SchedulerControl
1515  */
1516 void vTaskStartScheduler( void ) PRIVILEGED_FUNCTION;
1517 
1518 /**
1519  * task. h
1520  * @code{c}
1521  * void vTaskEndScheduler( void );
1522  * @endcode
1523  *
1524  * NOTE:  At the time of writing only the x86 real mode port, which runs on a PC
1525  * in place of DOS, implements this function.
1526  *
1527  * Stops the real time kernel tick.  All created tasks will be automatically
1528  * deleted and multitasking (either preemptive or cooperative) will
1529  * stop.  Execution then resumes from the point where vTaskStartScheduler ()
1530  * was called, as if vTaskStartScheduler () had just returned.
1531  *
1532  * See the demo application file main. c in the demo/PC directory for an
1533  * example that uses vTaskEndScheduler ().
1534  *
1535  * vTaskEndScheduler () requires an exit function to be defined within the
1536  * portable layer (see vPortEndScheduler () in port. c for the PC port).  This
1537  * performs hardware specific operations such as stopping the kernel tick.
1538  *
1539  * vTaskEndScheduler () will cause all of the resources allocated by the
1540  * kernel to be freed - but will not free resources allocated by application
1541  * tasks.
1542  *
1543  * Example usage:
1544  * @code{c}
1545  * void vTaskCode( void * pvParameters )
1546  * {
1547  *   for( ;; )
1548  *   {
1549  *       // Task code goes here.
1550  *
1551  *       // At some point we want to end the real time kernel processing
1552  *       // so call ...
1553  *       vTaskEndScheduler ();
1554  *   }
1555  * }
1556  *
1557  * void vAFunction( void )
1558  * {
1559  *   // Create at least one task before starting the kernel.
1560  *   xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL );
1561  *
1562  *   // Start the real time kernel with preemption.
1563  *   vTaskStartScheduler ();
1564  *
1565  *   // Will only get here when the vTaskCode () task has called
1566  *   // vTaskEndScheduler ().  When we get here we are back to single task
1567  *   // execution.
1568  * }
1569  * @endcode
1570  *
1571  * \defgroup vTaskEndScheduler vTaskEndScheduler
1572  * \ingroup SchedulerControl
1573  */
1574 void vTaskEndScheduler( void ) PRIVILEGED_FUNCTION;
1575 
1576 /**
1577  * task. h
1578  * @code{c}
1579  * void vTaskSuspendAll( void );
1580  * @endcode
1581  *
1582  * Suspends the scheduler without disabling interrupts.  Context switches will
1583  * not occur while the scheduler is suspended.
1584  *
1585  * After calling vTaskSuspendAll () the calling task will continue to execute
1586  * without risk of being swapped out until a call to xTaskResumeAll () has been
1587  * made.
1588  *
1589  * API functions that have the potential to cause a context switch (for example,
1590  * xTaskDelayUntil(), xQueueSend(), etc.) must not be called while the scheduler
1591  * is suspended.
1592  *
1593  * Example usage:
1594  * @code{c}
1595  * void vTask1( void * pvParameters )
1596  * {
1597  *   for( ;; )
1598  *   {
1599  *       // Task code goes here.
1600  *
1601  *       // ...
1602  *
1603  *       // At some point the task wants to perform a long operation during
1604  *       // which it does not want to get swapped out.  It cannot use
1605  *       // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the
1606  *       // operation may cause interrupts to be missed - including the
1607  *       // ticks.
1608  *
1609  *       // Prevent the real time kernel swapping out the task.
1610  *       vTaskSuspendAll ();
1611  *
1612  *       // Perform the operation here.  There is no need to use critical
1613  *       // sections as we have all the microcontroller processing time.
1614  *       // During this time interrupts will still operate and the kernel
1615  *       // tick count will be maintained.
1616  *
1617  *       // ...
1618  *
1619  *       // The operation is complete.  Restart the kernel.
1620  *       xTaskResumeAll ();
1621  *   }
1622  * }
1623  * @endcode
1624  * \defgroup vTaskSuspendAll vTaskSuspendAll
1625  * \ingroup SchedulerControl
1626  */
1627 void vTaskSuspendAll( void ) PRIVILEGED_FUNCTION;
1628 
1629 /**
1630  * task. h
1631  * @code{c}
1632  * BaseType_t xTaskResumeAll( void );
1633  * @endcode
1634  *
1635  * Resumes scheduler activity after it was suspended by a call to
1636  * vTaskSuspendAll().
1637  *
1638  * xTaskResumeAll() only resumes the scheduler.  It does not unsuspend tasks
1639  * that were previously suspended by a call to vTaskSuspend().
1640  *
1641  * @return If resuming the scheduler caused a context switch then pdTRUE is
1642  *         returned, otherwise pdFALSE is returned.
1643  *
1644  * Example usage:
1645  * @code{c}
1646  * void vTask1( void * pvParameters )
1647  * {
1648  *   for( ;; )
1649  *   {
1650  *       // Task code goes here.
1651  *
1652  *       // ...
1653  *
1654  *       // At some point the task wants to perform a long operation during
1655  *       // which it does not want to get swapped out.  It cannot use
1656  *       // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the
1657  *       // operation may cause interrupts to be missed - including the
1658  *       // ticks.
1659  *
1660  *       // Prevent the real time kernel swapping out the task.
1661  *       vTaskSuspendAll ();
1662  *
1663  *       // Perform the operation here.  There is no need to use critical
1664  *       // sections as we have all the microcontroller processing time.
1665  *       // During this time interrupts will still operate and the real
1666  *       // time kernel tick count will be maintained.
1667  *
1668  *       // ...
1669  *
1670  *       // The operation is complete.  Restart the kernel.  We want to force
1671  *       // a context switch - but there is no point if resuming the scheduler
1672  *       // caused a context switch already.
1673  *       if( !xTaskResumeAll () )
1674  *       {
1675  *            taskYIELD ();
1676  *       }
1677  *   }
1678  * }
1679  * @endcode
1680  * \defgroup xTaskResumeAll xTaskResumeAll
1681  * \ingroup SchedulerControl
1682  */
1683 BaseType_t xTaskResumeAll( void ) PRIVILEGED_FUNCTION;
1684 
1685 /*-----------------------------------------------------------
1686 * TASK UTILITIES
1687 *----------------------------------------------------------*/
1688 
1689 /**
1690  * task. h
1691  * @code{c}
1692  * TickType_t xTaskGetTickCount( void );
1693  * @endcode
1694  *
1695  * @return The count of ticks since vTaskStartScheduler was called.
1696  *
1697  * \defgroup xTaskGetTickCount xTaskGetTickCount
1698  * \ingroup TaskUtils
1699  */
1700 TickType_t xTaskGetTickCount( void ) PRIVILEGED_FUNCTION;
1701 
1702 /**
1703  * task. h
1704  * @code{c}
1705  * TickType_t xTaskGetTickCountFromISR( void );
1706  * @endcode
1707  *
1708  * @return The count of ticks since vTaskStartScheduler was called.
1709  *
1710  * This is a version of xTaskGetTickCount() that is safe to be called from an
1711  * ISR - provided that TickType_t is the natural word size of the
1712  * microcontroller being used or interrupt nesting is either not supported or
1713  * not being used.
1714  *
1715  * \defgroup xTaskGetTickCountFromISR xTaskGetTickCountFromISR
1716  * \ingroup TaskUtils
1717  */
1718 TickType_t xTaskGetTickCountFromISR( void ) PRIVILEGED_FUNCTION;
1719 
1720 /**
1721  * task. h
1722  * @code{c}
1723  * uint16_t uxTaskGetNumberOfTasks( void );
1724  * @endcode
1725  *
1726  * @return The number of tasks that the real time kernel is currently managing.
1727  * This includes all ready, blocked and suspended tasks.  A task that
1728  * has been deleted but not yet freed by the idle task will also be
1729  * included in the count.
1730  *
1731  * \defgroup uxTaskGetNumberOfTasks uxTaskGetNumberOfTasks
1732  * \ingroup TaskUtils
1733  */
1734 UBaseType_t uxTaskGetNumberOfTasks( void ) PRIVILEGED_FUNCTION;
1735 
1736 /**
1737  * task. h
1738  * @code{c}
1739  * char *pcTaskGetName( TaskHandle_t xTaskToQuery );
1740  * @endcode
1741  *
1742  * @return The text (human readable) name of the task referenced by the handle
1743  * xTaskToQuery.  A task can query its own name by either passing in its own
1744  * handle, or by setting xTaskToQuery to NULL.
1745  *
1746  * \defgroup pcTaskGetName pcTaskGetName
1747  * \ingroup TaskUtils
1748  */
1749 char * pcTaskGetName( TaskHandle_t xTaskToQuery ) PRIVILEGED_FUNCTION;
1750 
1751 /**
1752  * task. h
1753  * @code{c}
1754  * TaskHandle_t xTaskGetHandle( const char *pcNameToQuery );
1755  * @endcode
1756  *
1757  * NOTE:  This function takes a relatively long time to complete and should be
1758  * used sparingly.
1759  *
1760  * @return The handle of the task that has the human readable name pcNameToQuery.
1761  * NULL is returned if no matching name is found.  INCLUDE_xTaskGetHandle
1762  * must be set to 1 in FreeRTOSConfig.h for pcTaskGetHandle() to be available.
1763  *
1764  * \defgroup pcTaskGetHandle pcTaskGetHandle
1765  * \ingroup TaskUtils
1766  */
1767 #if ( INCLUDE_xTaskGetHandle == 1 )
1768     TaskHandle_t xTaskGetHandle( const char * pcNameToQuery ) PRIVILEGED_FUNCTION;
1769 #endif
1770 
1771 /**
1772  * task. h
1773  * @code{c}
1774  * BaseType_t xTaskGetStaticBuffers( TaskHandle_t xTask,
1775  *                                   StackType_t ** ppuxStackBuffer,
1776  *                                   StaticTask_t ** ppxTaskBuffer );
1777  * @endcode
1778  *
1779  * Retrieve pointers to a statically created task's data structure
1780  * buffer and stack buffer. These are the same buffers that are supplied
1781  * at the time of creation.
1782  *
1783  * @param xTask The task for which to retrieve the buffers.
1784  *
1785  * @param ppuxStackBuffer Used to return a pointer to the task's stack buffer.
1786  *
1787  * @param ppxTaskBuffer Used to return a pointer to the task's data structure
1788  * buffer.
1789  *
1790  * @return pdTRUE if buffers were retrieved, pdFALSE otherwise.
1791  *
1792  * \defgroup xTaskGetStaticBuffers xTaskGetStaticBuffers
1793  * \ingroup TaskUtils
1794  */
1795 #if ( configSUPPORT_STATIC_ALLOCATION == 1 )
1796     BaseType_t xTaskGetStaticBuffers( TaskHandle_t xTask,
1797                                       StackType_t ** ppuxStackBuffer,
1798                                       StaticTask_t ** ppxTaskBuffer ) PRIVILEGED_FUNCTION;
1799 #endif /* configSUPPORT_STATIC_ALLOCATION */
1800 
1801 /**
1802  * task.h
1803  * @code{c}
1804  * UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask );
1805  * @endcode
1806  *
1807  * INCLUDE_uxTaskGetStackHighWaterMark must be set to 1 in FreeRTOSConfig.h for
1808  * this function to be available.
1809  *
1810  * Returns the high water mark of the stack associated with xTask.  That is,
1811  * the minimum free stack space there has been (in words, so on a 32 bit machine
1812  * a value of 1 means 4 bytes) since the task started.  The smaller the returned
1813  * number the closer the task has come to overflowing its stack.
1814  *
1815  * uxTaskGetStackHighWaterMark() and uxTaskGetStackHighWaterMark2() are the
1816  * same except for their return type.  Using configSTACK_DEPTH_TYPE allows the
1817  * user to determine the return type.  It gets around the problem of the value
1818  * overflowing on 8-bit types without breaking backward compatibility for
1819  * applications that expect an 8-bit return type.
1820  *
1821  * @param xTask Handle of the task associated with the stack to be checked.
1822  * Set xTask to NULL to check the stack of the calling task.
1823  *
1824  * @return The smallest amount of free stack space there has been (in words, so
1825  * actual spaces on the stack rather than bytes) since the task referenced by
1826  * xTask was created.
1827  */
1828 #if ( INCLUDE_uxTaskGetStackHighWaterMark == 1 )
1829     UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
1830 #endif
1831 
1832 /**
1833  * task.h
1834  * @code{c}
1835  * configSTACK_DEPTH_TYPE uxTaskGetStackHighWaterMark2( TaskHandle_t xTask );
1836  * @endcode
1837  *
1838  * INCLUDE_uxTaskGetStackHighWaterMark2 must be set to 1 in FreeRTOSConfig.h for
1839  * this function to be available.
1840  *
1841  * Returns the high water mark of the stack associated with xTask.  That is,
1842  * the minimum free stack space there has been (in words, so on a 32 bit machine
1843  * a value of 1 means 4 bytes) since the task started.  The smaller the returned
1844  * number the closer the task has come to overflowing its stack.
1845  *
1846  * uxTaskGetStackHighWaterMark() and uxTaskGetStackHighWaterMark2() are the
1847  * same except for their return type.  Using configSTACK_DEPTH_TYPE allows the
1848  * user to determine the return type.  It gets around the problem of the value
1849  * overflowing on 8-bit types without breaking backward compatibility for
1850  * applications that expect an 8-bit return type.
1851  *
1852  * @param xTask Handle of the task associated with the stack to be checked.
1853  * Set xTask to NULL to check the stack of the calling task.
1854  *
1855  * @return The smallest amount of free stack space there has been (in words, so
1856  * actual spaces on the stack rather than bytes) since the task referenced by
1857  * xTask was created.
1858  */
1859 #if ( INCLUDE_uxTaskGetStackHighWaterMark2 == 1 )
1860     configSTACK_DEPTH_TYPE uxTaskGetStackHighWaterMark2( TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
1861 #endif
1862 
1863 /* When using trace macros it is sometimes necessary to include task.h before
1864  * FreeRTOS.h.  When this is done TaskHookFunction_t will not yet have been defined,
1865  * so the following two prototypes will cause a compilation error.  This can be
1866  * fixed by simply guarding against the inclusion of these two prototypes unless
1867  * they are explicitly required by the configUSE_APPLICATION_TASK_TAG configuration
1868  * constant. */
1869 #ifdef configUSE_APPLICATION_TASK_TAG
1870     #if configUSE_APPLICATION_TASK_TAG == 1
1871 
1872 /**
1873  * task.h
1874  * @code{c}
1875  * void vTaskSetApplicationTaskTag( TaskHandle_t xTask, TaskHookFunction_t pxHookFunction );
1876  * @endcode
1877  *
1878  * Sets pxHookFunction to be the task hook function used by the task xTask.
1879  * Passing xTask as NULL has the effect of setting the calling tasks hook
1880  * function.
1881  */
1882         void vTaskSetApplicationTaskTag( TaskHandle_t xTask,
1883                                          TaskHookFunction_t pxHookFunction ) PRIVILEGED_FUNCTION;
1884 
1885 /**
1886  * task.h
1887  * @code{c}
1888  * void xTaskGetApplicationTaskTag( TaskHandle_t xTask );
1889  * @endcode
1890  *
1891  * Returns the pxHookFunction value assigned to the task xTask.  Do not
1892  * call from an interrupt service routine - call
1893  * xTaskGetApplicationTaskTagFromISR() instead.
1894  */
1895         TaskHookFunction_t xTaskGetApplicationTaskTag( TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
1896 
1897 /**
1898  * task.h
1899  * @code{c}
1900  * void xTaskGetApplicationTaskTagFromISR( TaskHandle_t xTask );
1901  * @endcode
1902  *
1903  * Returns the pxHookFunction value assigned to the task xTask.  Can
1904  * be called from an interrupt service routine.
1905  */
1906         TaskHookFunction_t xTaskGetApplicationTaskTagFromISR( TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
1907     #endif /* configUSE_APPLICATION_TASK_TAG ==1 */
1908 #endif /* ifdef configUSE_APPLICATION_TASK_TAG */
1909 
1910 #if ( configNUM_THREAD_LOCAL_STORAGE_POINTERS > 0 )
1911 
1912 /* Each task contains an array of pointers that is dimensioned by the
1913  * configNUM_THREAD_LOCAL_STORAGE_POINTERS setting in FreeRTOSConfig.h.  The
1914  * kernel does not use the pointers itself, so the application writer can use
1915  * the pointers for any purpose they wish.  The following two functions are
1916  * used to set and query a pointer respectively. */
1917     void vTaskSetThreadLocalStoragePointer( TaskHandle_t xTaskToSet,
1918                                             BaseType_t xIndex,
1919                                             void * pvValue ) PRIVILEGED_FUNCTION;
1920     void * pvTaskGetThreadLocalStoragePointer( TaskHandle_t xTaskToQuery,
1921                                                BaseType_t xIndex ) PRIVILEGED_FUNCTION;
1922 
1923 #endif
1924 
1925 #if ( configCHECK_FOR_STACK_OVERFLOW > 0 )
1926 
1927 /**
1928  * task.h
1929  * @code{c}
1930  * void vApplicationStackOverflowHook( TaskHandle_t xTask, char *pcTaskName);
1931  * @endcode
1932  *
1933  * The application stack overflow hook is called when a stack overflow is detected for a task.
1934  *
1935  * Details on stack overflow detection can be found here: https://www.FreeRTOS.org/Stacks-and-stack-overflow-checking.html
1936  *
1937  * @param xTask the task that just exceeded its stack boundaries.
1938  * @param pcTaskName A character string containing the name of the offending task.
1939  */
1940     /* MISRA Ref 8.6.1 [External linkage] */
1941     /* More details at: https://github.com/FreeRTOS/FreeRTOS-Kernel/blob/main/MISRA.md#rule-86 */
1942     /* coverity[misra_c_2012_rule_8_6_violation] */
1943     void vApplicationStackOverflowHook( TaskHandle_t xTask,
1944                                         char * pcTaskName );
1945 
1946 #endif
1947 
1948 #if ( configUSE_IDLE_HOOK == 1 )
1949 
1950 /**
1951  * task.h
1952  * @code{c}
1953  * void vApplicationIdleHook( void );
1954  * @endcode
1955  *
1956  * The application idle hook is called by the idle task.
1957  * This allows the application designer to add background functionality without
1958  * the overhead of a separate task.
1959  * NOTE: vApplicationIdleHook() MUST NOT, UNDER ANY CIRCUMSTANCES, CALL A FUNCTION THAT MIGHT BLOCK.
1960  */
1961     /* MISRA Ref 8.6.1 [External linkage] */
1962     /* More details at: https://github.com/FreeRTOS/FreeRTOS-Kernel/blob/main/MISRA.md#rule-86 */
1963     /* coverity[misra_c_2012_rule_8_6_violation] */
1964     void vApplicationIdleHook( void );
1965 
1966 #endif
1967 
1968 
1969 #if  ( configUSE_TICK_HOOK != 0 )
1970 
1971 /**
1972  *  task.h
1973  * @code{c}
1974  * void vApplicationTickHook( void );
1975  * @endcode
1976  *
1977  * This hook function is called in the system tick handler after any OS work is completed.
1978  */
1979     /* MISRA Ref 8.6.1 [External linkage] */
1980     /* More details at: https://github.com/FreeRTOS/FreeRTOS-Kernel/blob/main/MISRA.md#rule-86 */
1981     /* coverity[misra_c_2012_rule_8_6_violation] */
1982     void vApplicationTickHook( void );
1983 
1984 #endif
1985 
1986 #if ( configSUPPORT_STATIC_ALLOCATION == 1 )
1987 
1988 /**
1989  * task.h
1990  * @code{c}
1991  * void vApplicationGetIdleTaskMemory( StaticTask_t ** ppxIdleTaskTCBBuffer, StackType_t ** ppxIdleTaskStackBuffer, configSTACK_DEPTH_TYPE * puxIdleTaskStackSize )
1992  * @endcode
1993  *
1994  * This function is used to provide a statically allocated block of memory to FreeRTOS to hold the Idle Task TCB.  This function is required when
1995  * configSUPPORT_STATIC_ALLOCATION is set.  For more information see this URI: https://www.FreeRTOS.org/a00110.html#configSUPPORT_STATIC_ALLOCATION
1996  *
1997  * @param ppxIdleTaskTCBBuffer A handle to a statically allocated TCB buffer
1998  * @param ppxIdleTaskStackBuffer A handle to a statically allocated Stack buffer for the idle task
1999  * @param puxIdleTaskStackSize A pointer to the number of elements that will fit in the allocated stack buffer
2000  */
2001     void vApplicationGetIdleTaskMemory( StaticTask_t ** ppxIdleTaskTCBBuffer,
2002                                         StackType_t ** ppxIdleTaskStackBuffer,
2003                                         configSTACK_DEPTH_TYPE * puxIdleTaskStackSize );
2004 
2005 /**
2006  * task.h
2007  * @code{c}
2008  * void vApplicationGetPassiveIdleTaskMemory( StaticTask_t ** ppxIdleTaskTCBBuffer, StackType_t ** ppxIdleTaskStackBuffer, configSTACK_DEPTH_TYPE * puxIdleTaskStackSize, BaseType_t xCoreID )
2009  * @endcode
2010  *
2011  * This function is used to provide a statically allocated block of memory to FreeRTOS to hold the Idle Tasks TCB.  This function is required when
2012  * configSUPPORT_STATIC_ALLOCATION is set.  For more information see this URI: https://www.FreeRTOS.org/a00110.html#configSUPPORT_STATIC_ALLOCATION
2013  *
2014  * In the FreeRTOS SMP, there are a total of configNUMBER_OF_CORES idle tasks:
2015  *  1. 1 Active idle task which does all the housekeeping.
2016  *  2. ( configNUMBER_OF_CORES - 1 ) Passive idle tasks which do nothing.
2017  * These idle tasks are created to ensure that each core has an idle task to run when
2018  * no other task is available to run.
2019  *
2020  * The function vApplicationGetPassiveIdleTaskMemory is called with passive idle
2021  * task index 0, 1 ... ( configNUMBER_OF_CORES - 2 ) to get memory for passive idle
2022  * tasks.
2023  *
2024  * @param ppxIdleTaskTCBBuffer A handle to a statically allocated TCB buffer
2025  * @param ppxIdleTaskStackBuffer A handle to a statically allocated Stack buffer for the idle task
2026  * @param puxIdleTaskStackSize A pointer to the number of elements that will fit in the allocated stack buffer
2027  * @param xPassiveIdleTaskIndex The passive idle task index of the idle task buffer
2028  */
2029     #if ( configNUMBER_OF_CORES > 1 )
2030         void vApplicationGetPassiveIdleTaskMemory( StaticTask_t ** ppxIdleTaskTCBBuffer,
2031                                                    StackType_t ** ppxIdleTaskStackBuffer,
2032                                                    configSTACK_DEPTH_TYPE * puxIdleTaskStackSize,
2033                                                    BaseType_t xPassiveIdleTaskIndex );
2034     #endif /* #if ( configNUMBER_OF_CORES > 1 ) */
2035 #endif /* if ( configSUPPORT_STATIC_ALLOCATION == 1 ) */
2036 
2037 /**
2038  * task.h
2039  * @code{c}
2040  * BaseType_t xTaskCallApplicationTaskHook( TaskHandle_t xTask, void *pvParameter );
2041  * @endcode
2042  *
2043  * Calls the hook function associated with xTask.  Passing xTask as NULL has
2044  * the effect of calling the Running tasks (the calling task) hook function.
2045  *
2046  * pvParameter is passed to the hook function for the task to interpret as it
2047  * wants.  The return value is the value returned by the task hook function
2048  * registered by the user.
2049  */
2050 #if ( configUSE_APPLICATION_TASK_TAG == 1 )
2051     BaseType_t xTaskCallApplicationTaskHook( TaskHandle_t xTask,
2052                                              void * pvParameter ) PRIVILEGED_FUNCTION;
2053 #endif
2054 
2055 /**
2056  * xTaskGetIdleTaskHandle() is only available if
2057  * INCLUDE_xTaskGetIdleTaskHandle is set to 1 in FreeRTOSConfig.h.
2058  *
2059  * In single-core FreeRTOS, this function simply returns the handle of the idle
2060  * task. It is not valid to call xTaskGetIdleTaskHandle() before the scheduler
2061  * has been started.
2062  *
2063  * In the FreeRTOS SMP, there are a total of configNUMBER_OF_CORES idle tasks:
2064  *  1. 1 Active idle task which does all the housekeeping.
2065  *  2. ( configNUMBER_OF_CORES - 1 ) Passive idle tasks which do nothing.
2066  * These idle tasks are created to ensure that each core has an idle task to run when
2067  * no other task is available to run. Call xTaskGetIdleTaskHandle() or
2068  * xTaskGetIdleTaskHandleForCore() with xCoreID set to 0  to get the Active
2069  * idle task handle. Call xTaskGetIdleTaskHandleForCore() with xCoreID set to
2070  * 1,2 ... ( configNUMBER_OF_CORES - 1 ) to get the Passive idle task handles.
2071  */
2072 #if ( INCLUDE_xTaskGetIdleTaskHandle == 1 )
2073     #if ( configNUMBER_OF_CORES == 1 )
2074         TaskHandle_t xTaskGetIdleTaskHandle( void ) PRIVILEGED_FUNCTION;
2075     #endif /* #if ( configNUMBER_OF_CORES == 1 ) */
2076 
2077     TaskHandle_t xTaskGetIdleTaskHandleForCore( BaseType_t xCoreID ) PRIVILEGED_FUNCTION;
2078 #endif /* #if ( INCLUDE_xTaskGetIdleTaskHandle == 1 ) */
2079 
2080 /**
2081  * configUSE_TRACE_FACILITY must be defined as 1 in FreeRTOSConfig.h for
2082  * uxTaskGetSystemState() to be available.
2083  *
2084  * uxTaskGetSystemState() populates an TaskStatus_t structure for each task in
2085  * the system.  TaskStatus_t structures contain, among other things, members
2086  * for the task handle, task name, task priority, task state, and total amount
2087  * of run time consumed by the task.  See the TaskStatus_t structure
2088  * definition in this file for the full member list.
2089  *
2090  * NOTE:  This function is intended for debugging use only as its use results in
2091  * the scheduler remaining suspended for an extended period.
2092  *
2093  * @param pxTaskStatusArray A pointer to an array of TaskStatus_t structures.
2094  * The array must contain at least one TaskStatus_t structure for each task
2095  * that is under the control of the RTOS.  The number of tasks under the control
2096  * of the RTOS can be determined using the uxTaskGetNumberOfTasks() API function.
2097  *
2098  * @param uxArraySize The size of the array pointed to by the pxTaskStatusArray
2099  * parameter.  The size is specified as the number of indexes in the array, or
2100  * the number of TaskStatus_t structures contained in the array, not by the
2101  * number of bytes in the array.
2102  *
2103  * @param pulTotalRunTime If configGENERATE_RUN_TIME_STATS is set to 1 in
2104  * FreeRTOSConfig.h then *pulTotalRunTime is set by uxTaskGetSystemState() to the
2105  * total run time (as defined by the run time stats clock, see
2106  * https://www.FreeRTOS.org/rtos-run-time-stats.html) since the target booted.
2107  * pulTotalRunTime can be set to NULL to omit the total run time information.
2108  *
2109  * @return The number of TaskStatus_t structures that were populated by
2110  * uxTaskGetSystemState().  This should equal the number returned by the
2111  * uxTaskGetNumberOfTasks() API function, but will be zero if the value passed
2112  * in the uxArraySize parameter was too small.
2113  *
2114  * Example usage:
2115  * @code{c}
2116  *  // This example demonstrates how a human readable table of run time stats
2117  *  // information is generated from raw data provided by uxTaskGetSystemState().
2118  *  // The human readable table is written to pcWriteBuffer
2119  *  void vTaskGetRunTimeStats( char *pcWriteBuffer )
2120  *  {
2121  *  TaskStatus_t *pxTaskStatusArray;
2122  *  volatile UBaseType_t uxArraySize, x;
2123  *  configRUN_TIME_COUNTER_TYPE ulTotalRunTime, ulStatsAsPercentage;
2124  *
2125  *      // Make sure the write buffer does not contain a string.
2126  * pcWriteBuffer = 0x00;
2127  *
2128  *      // Take a snapshot of the number of tasks in case it changes while this
2129  *      // function is executing.
2130  *      uxArraySize = uxTaskGetNumberOfTasks();
2131  *
2132  *      // Allocate a TaskStatus_t structure for each task.  An array could be
2133  *      // allocated statically at compile time.
2134  *      pxTaskStatusArray = pvPortMalloc( uxArraySize * sizeof( TaskStatus_t ) );
2135  *
2136  *      if( pxTaskStatusArray != NULL )
2137  *      {
2138  *          // Generate raw status information about each task.
2139  *          uxArraySize = uxTaskGetSystemState( pxTaskStatusArray, uxArraySize, &ulTotalRunTime );
2140  *
2141  *          // For percentage calculations.
2142  *          ulTotalRunTime /= 100U;
2143  *
2144  *          // Avoid divide by zero errors.
2145  *          if( ulTotalRunTime > 0 )
2146  *          {
2147  *              // For each populated position in the pxTaskStatusArray array,
2148  *              // format the raw data as human readable ASCII data
2149  *              for( x = 0; x < uxArraySize; x++ )
2150  *              {
2151  *                  // What percentage of the total run time has the task used?
2152  *                  // This will always be rounded down to the nearest integer.
2153  *                  // ulTotalRunTimeDiv100 has already been divided by 100.
2154  *                  ulStatsAsPercentage = pxTaskStatusArray[ x ].ulRunTimeCounter / ulTotalRunTime;
2155  *
2156  *                  if( ulStatsAsPercentage > 0U )
2157  *                  {
2158  *                      sprintf( pcWriteBuffer, "%s\t\t%lu\t\t%lu%%\r\n", pxTaskStatusArray[ x ].pcTaskName, pxTaskStatusArray[ x ].ulRunTimeCounter, ulStatsAsPercentage );
2159  *                  }
2160  *                  else
2161  *                  {
2162  *                      // If the percentage is zero here then the task has
2163  *                      // consumed less than 1% of the total run time.
2164  *                      sprintf( pcWriteBuffer, "%s\t\t%lu\t\t<1%%\r\n", pxTaskStatusArray[ x ].pcTaskName, pxTaskStatusArray[ x ].ulRunTimeCounter );
2165  *                  }
2166  *
2167  *                  pcWriteBuffer += strlen( ( char * ) pcWriteBuffer );
2168  *              }
2169  *          }
2170  *
2171  *          // The array is no longer needed, free the memory it consumes.
2172  *          vPortFree( pxTaskStatusArray );
2173  *      }
2174  *  }
2175  *  @endcode
2176  */
2177 #if ( configUSE_TRACE_FACILITY == 1 )
2178     UBaseType_t uxTaskGetSystemState( TaskStatus_t * const pxTaskStatusArray,
2179                                       const UBaseType_t uxArraySize,
2180                                       configRUN_TIME_COUNTER_TYPE * const pulTotalRunTime ) PRIVILEGED_FUNCTION;
2181 #endif
2182 
2183 /**
2184  * task. h
2185  * @code{c}
2186  * void vTaskListTasks( char *pcWriteBuffer, size_t uxBufferLength );
2187  * @endcode
2188  *
2189  * configUSE_TRACE_FACILITY and configUSE_STATS_FORMATTING_FUNCTIONS must
2190  * both be defined as 1 for this function to be available.  See the
2191  * configuration section of the FreeRTOS.org website for more information.
2192  *
2193  * NOTE 1: This function will disable interrupts for its duration.  It is
2194  * not intended for normal application runtime use but as a debug aid.
2195  *
2196  * Lists all the current tasks, along with their current state and stack
2197  * usage high water mark.
2198  *
2199  * Tasks are reported as blocked ('B'), ready ('R'), deleted ('D') or
2200  * suspended ('S').
2201  *
2202  * PLEASE NOTE:
2203  *
2204  * This function is provided for convenience only, and is used by many of the
2205  * demo applications.  Do not consider it to be part of the scheduler.
2206  *
2207  * vTaskListTasks() calls uxTaskGetSystemState(), then formats part of the
2208  * uxTaskGetSystemState() output into a human readable table that displays task:
2209  * names, states, priority, stack usage and task number.
2210  * Stack usage specified as the number of unused StackType_t words stack can hold
2211  * on top of stack - not the number of bytes.
2212  *
2213  * vTaskListTasks() has a dependency on the snprintf() C library function that might
2214  * bloat the code size, use a lot of stack, and provide different results on
2215  * different platforms.  An alternative, tiny, third party, and limited
2216  * functionality implementation of snprintf() is provided in many of the
2217  * FreeRTOS/Demo sub-directories in a file called printf-stdarg.c (note
2218  * printf-stdarg.c does not provide a full snprintf() implementation!).
2219  *
2220  * It is recommended that production systems call uxTaskGetSystemState()
2221  * directly to get access to raw stats data, rather than indirectly through a
2222  * call to vTaskListTasks().
2223  *
2224  * @param pcWriteBuffer A buffer into which the above mentioned details
2225  * will be written, in ASCII form.  This buffer is assumed to be large
2226  * enough to contain the generated report.  Approximately 40 bytes per
2227  * task should be sufficient.
2228  *
2229  * @param uxBufferLength Length of the pcWriteBuffer.
2230  *
2231  * \defgroup vTaskListTasks vTaskListTasks
2232  * \ingroup TaskUtils
2233  */
2234 #if ( ( configUSE_TRACE_FACILITY == 1 ) && ( configUSE_STATS_FORMATTING_FUNCTIONS > 0 ) )
2235     void vTaskListTasks( char * pcWriteBuffer,
2236                          size_t uxBufferLength ) PRIVILEGED_FUNCTION;
2237 #endif
2238 
2239 /**
2240  * task. h
2241  * @code{c}
2242  * void vTaskList( char *pcWriteBuffer );
2243  * @endcode
2244  *
2245  * configUSE_TRACE_FACILITY and configUSE_STATS_FORMATTING_FUNCTIONS must
2246  * both be defined as 1 for this function to be available.  See the
2247  * configuration section of the FreeRTOS.org website for more information.
2248  *
2249  * WARN: This function assumes that the pcWriteBuffer is of length
2250  * configSTATS_BUFFER_MAX_LENGTH. This function is there only for
2251  * backward compatibility. New applications are recommended to
2252  * use vTaskListTasks and supply the length of the pcWriteBuffer explicitly.
2253  *
2254  * NOTE 1: This function will disable interrupts for its duration.  It is
2255  * not intended for normal application runtime use but as a debug aid.
2256  *
2257  * Lists all the current tasks, along with their current state and stack
2258  * usage high water mark.
2259  *
2260  * Tasks are reported as blocked ('B'), ready ('R'), deleted ('D') or
2261  * suspended ('S').
2262  *
2263  * PLEASE NOTE:
2264  *
2265  * This function is provided for convenience only, and is used by many of the
2266  * demo applications.  Do not consider it to be part of the scheduler.
2267  *
2268  * vTaskList() calls uxTaskGetSystemState(), then formats part of the
2269  * uxTaskGetSystemState() output into a human readable table that displays task:
2270  * names, states, priority, stack usage and task number.
2271  * Stack usage specified as the number of unused StackType_t words stack can hold
2272  * on top of stack - not the number of bytes.
2273  *
2274  * vTaskList() has a dependency on the snprintf() C library function that might
2275  * bloat the code size, use a lot of stack, and provide different results on
2276  * different platforms.  An alternative, tiny, third party, and limited
2277  * functionality implementation of snprintf() is provided in many of the
2278  * FreeRTOS/Demo sub-directories in a file called printf-stdarg.c (note
2279  * printf-stdarg.c does not provide a full snprintf() implementation!).
2280  *
2281  * It is recommended that production systems call uxTaskGetSystemState()
2282  * directly to get access to raw stats data, rather than indirectly through a
2283  * call to vTaskList().
2284  *
2285  * @param pcWriteBuffer A buffer into which the above mentioned details
2286  * will be written, in ASCII form.  This buffer is assumed to be large
2287  * enough to contain the generated report.  Approximately 40 bytes per
2288  * task should be sufficient.
2289  *
2290  * \defgroup vTaskList vTaskList
2291  * \ingroup TaskUtils
2292  */
2293 #define vTaskList( pcWriteBuffer )    vTaskListTasks( ( pcWriteBuffer ), configSTATS_BUFFER_MAX_LENGTH )
2294 
2295 /**
2296  * task. h
2297  * @code{c}
2298  * void vTaskGetRunTimeStatistics( char *pcWriteBuffer, size_t uxBufferLength );
2299  * @endcode
2300  *
2301  * configGENERATE_RUN_TIME_STATS and configUSE_STATS_FORMATTING_FUNCTIONS
2302  * must both be defined as 1 for this function to be available.  The application
2303  * must also then provide definitions for
2304  * portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and portGET_RUN_TIME_COUNTER_VALUE()
2305  * to configure a peripheral timer/counter and return the timers current count
2306  * value respectively.  The counter should be at least 10 times the frequency of
2307  * the tick count.
2308  *
2309  * NOTE 1: This function will disable interrupts for its duration.  It is
2310  * not intended for normal application runtime use but as a debug aid.
2311  *
2312  * Setting configGENERATE_RUN_TIME_STATS to 1 will result in a total
2313  * accumulated execution time being stored for each task.  The resolution
2314  * of the accumulated time value depends on the frequency of the timer
2315  * configured by the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() macro.
2316  * Calling vTaskGetRunTimeStatistics() writes the total execution time of each
2317  * task into a buffer, both as an absolute count value and as a percentage
2318  * of the total system execution time.
2319  *
2320  * NOTE 2:
2321  *
2322  * This function is provided for convenience only, and is used by many of the
2323  * demo applications.  Do not consider it to be part of the scheduler.
2324  *
2325  * vTaskGetRunTimeStatistics() calls uxTaskGetSystemState(), then formats part of
2326  * the uxTaskGetSystemState() output into a human readable table that displays the
2327  * amount of time each task has spent in the Running state in both absolute and
2328  * percentage terms.
2329  *
2330  * vTaskGetRunTimeStatistics() has a dependency on the snprintf() C library function
2331  * that might bloat the code size, use a lot of stack, and provide different
2332  * results on different platforms.  An alternative, tiny, third party, and
2333  * limited functionality implementation of snprintf() is provided in many of the
2334  * FreeRTOS/Demo sub-directories in a file called printf-stdarg.c (note
2335  * printf-stdarg.c does not provide a full snprintf() implementation!).
2336  *
2337  * It is recommended that production systems call uxTaskGetSystemState() directly
2338  * to get access to raw stats data, rather than indirectly through a call to
2339  * vTaskGetRunTimeStatistics().
2340  *
2341  * @param pcWriteBuffer A buffer into which the execution times will be
2342  * written, in ASCII form.  This buffer is assumed to be large enough to
2343  * contain the generated report.  Approximately 40 bytes per task should
2344  * be sufficient.
2345  *
2346  * @param uxBufferLength Length of the pcWriteBuffer.
2347  *
2348  * \defgroup vTaskGetRunTimeStatistics vTaskGetRunTimeStatistics
2349  * \ingroup TaskUtils
2350  */
2351 #if ( ( configGENERATE_RUN_TIME_STATS == 1 ) && ( configUSE_STATS_FORMATTING_FUNCTIONS > 0 ) && ( configUSE_TRACE_FACILITY == 1 ) )
2352     void vTaskGetRunTimeStatistics( char * pcWriteBuffer,
2353                                     size_t uxBufferLength ) PRIVILEGED_FUNCTION;
2354 #endif
2355 
2356 /**
2357  * task. h
2358  * @code{c}
2359  * void vTaskGetRunTimeStats( char *pcWriteBuffer );
2360  * @endcode
2361  *
2362  * configGENERATE_RUN_TIME_STATS and configUSE_STATS_FORMATTING_FUNCTIONS
2363  * must both be defined as 1 for this function to be available.  The application
2364  * must also then provide definitions for
2365  * portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and portGET_RUN_TIME_COUNTER_VALUE()
2366  * to configure a peripheral timer/counter and return the timers current count
2367  * value respectively.  The counter should be at least 10 times the frequency of
2368  * the tick count.
2369  *
2370  * WARN: This function assumes that the pcWriteBuffer is of length
2371  * configSTATS_BUFFER_MAX_LENGTH. This function is there only for
2372  * backward compatiblity. New applications are recommended to use
2373  * vTaskGetRunTimeStatistics and supply the length of the pcWriteBuffer
2374  * explicitly.
2375  *
2376  * NOTE 1: This function will disable interrupts for its duration.  It is
2377  * not intended for normal application runtime use but as a debug aid.
2378  *
2379  * Setting configGENERATE_RUN_TIME_STATS to 1 will result in a total
2380  * accumulated execution time being stored for each task.  The resolution
2381  * of the accumulated time value depends on the frequency of the timer
2382  * configured by the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() macro.
2383  * Calling vTaskGetRunTimeStats() writes the total execution time of each
2384  * task into a buffer, both as an absolute count value and as a percentage
2385  * of the total system execution time.
2386  *
2387  * NOTE 2:
2388  *
2389  * This function is provided for convenience only, and is used by many of the
2390  * demo applications.  Do not consider it to be part of the scheduler.
2391  *
2392  * vTaskGetRunTimeStats() calls uxTaskGetSystemState(), then formats part of the
2393  * uxTaskGetSystemState() output into a human readable table that displays the
2394  * amount of time each task has spent in the Running state in both absolute and
2395  * percentage terms.
2396  *
2397  * vTaskGetRunTimeStats() has a dependency on the snprintf() C library function
2398  * that might bloat the code size, use a lot of stack, and provide different
2399  * results on different platforms.  An alternative, tiny, third party, and
2400  * limited functionality implementation of snprintf() is provided in many of the
2401  * FreeRTOS/Demo sub-directories in a file called printf-stdarg.c (note
2402  * printf-stdarg.c does not provide a full snprintf() implementation!).
2403  *
2404  * It is recommended that production systems call uxTaskGetSystemState() directly
2405  * to get access to raw stats data, rather than indirectly through a call to
2406  * vTaskGetRunTimeStats().
2407  *
2408  * @param pcWriteBuffer A buffer into which the execution times will be
2409  * written, in ASCII form.  This buffer is assumed to be large enough to
2410  * contain the generated report.  Approximately 40 bytes per task should
2411  * be sufficient.
2412  *
2413  * \defgroup vTaskGetRunTimeStats vTaskGetRunTimeStats
2414  * \ingroup TaskUtils
2415  */
2416 #define vTaskGetRunTimeStats( pcWriteBuffer )    vTaskGetRunTimeStatistics( ( pcWriteBuffer ), configSTATS_BUFFER_MAX_LENGTH )
2417 
2418 /**
2419  * task. h
2420  * @code{c}
2421  * configRUN_TIME_COUNTER_TYPE ulTaskGetRunTimeCounter( const TaskHandle_t xTask );
2422  * configRUN_TIME_COUNTER_TYPE ulTaskGetRunTimePercent( const TaskHandle_t xTask );
2423  * @endcode
2424  *
2425  * configGENERATE_RUN_TIME_STATS must be defined as 1 for these functions to be
2426  * available.  The application must also then provide definitions for
2427  * portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and
2428  * portGET_RUN_TIME_COUNTER_VALUE() to configure a peripheral timer/counter and
2429  * return the timers current count value respectively.  The counter should be
2430  * at least 10 times the frequency of the tick count.
2431  *
2432  * Setting configGENERATE_RUN_TIME_STATS to 1 will result in a total
2433  * accumulated execution time being stored for each task.  The resolution
2434  * of the accumulated time value depends on the frequency of the timer
2435  * configured by the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() macro.
2436  * While uxTaskGetSystemState() and vTaskGetRunTimeStats() writes the total
2437  * execution time of each task into a buffer, ulTaskGetRunTimeCounter()
2438  * returns the total execution time of just one task and
2439  * ulTaskGetRunTimePercent() returns the percentage of the CPU time used by
2440  * just one task.
2441  *
2442  * @return The total run time of the given task or the percentage of the total
2443  * run time consumed by the given task.  This is the amount of time the task
2444  * has actually been executing.  The unit of time is dependent on the frequency
2445  * configured using the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and
2446  * portGET_RUN_TIME_COUNTER_VALUE() macros.
2447  *
2448  * \defgroup ulTaskGetRunTimeCounter ulTaskGetRunTimeCounter
2449  * \ingroup TaskUtils
2450  */
2451 #if ( configGENERATE_RUN_TIME_STATS == 1 )
2452     configRUN_TIME_COUNTER_TYPE ulTaskGetRunTimeCounter( const TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
2453     configRUN_TIME_COUNTER_TYPE ulTaskGetRunTimePercent( const TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
2454 #endif
2455 
2456 /**
2457  * task. h
2458  * @code{c}
2459  * configRUN_TIME_COUNTER_TYPE ulTaskGetIdleRunTimeCounter( void );
2460  * configRUN_TIME_COUNTER_TYPE ulTaskGetIdleRunTimePercent( void );
2461  * @endcode
2462  *
2463  * configGENERATE_RUN_TIME_STATS must be defined as 1 for these functions to be
2464  * available.  The application must also then provide definitions for
2465  * portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and
2466  * portGET_RUN_TIME_COUNTER_VALUE() to configure a peripheral timer/counter and
2467  * return the timers current count value respectively.  The counter should be
2468  * at least 10 times the frequency of the tick count.
2469  *
2470  * Setting configGENERATE_RUN_TIME_STATS to 1 will result in a total
2471  * accumulated execution time being stored for each task.  The resolution
2472  * of the accumulated time value depends on the frequency of the timer
2473  * configured by the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() macro.
2474  * While uxTaskGetSystemState() and vTaskGetRunTimeStats() writes the total
2475  * execution time of each task into a buffer, ulTaskGetIdleRunTimeCounter()
2476  * returns the total execution time of just the idle task and
2477  * ulTaskGetIdleRunTimePercent() returns the percentage of the CPU time used by
2478  * just the idle task.
2479  *
2480  * Note the amount of idle time is only a good measure of the slack time in a
2481  * system if there are no other tasks executing at the idle priority, tickless
2482  * idle is not used, and configIDLE_SHOULD_YIELD is set to 0.
2483  *
2484  * @return The total run time of the idle task or the percentage of the total
2485  * run time consumed by the idle task.  This is the amount of time the
2486  * idle task has actually been executing.  The unit of time is dependent on the
2487  * frequency configured using the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and
2488  * portGET_RUN_TIME_COUNTER_VALUE() macros.
2489  *
2490  * \defgroup ulTaskGetIdleRunTimeCounter ulTaskGetIdleRunTimeCounter
2491  * \ingroup TaskUtils
2492  */
2493 #if ( ( configGENERATE_RUN_TIME_STATS == 1 ) && ( INCLUDE_xTaskGetIdleTaskHandle == 1 ) )
2494     configRUN_TIME_COUNTER_TYPE ulTaskGetIdleRunTimeCounter( void ) PRIVILEGED_FUNCTION;
2495     configRUN_TIME_COUNTER_TYPE ulTaskGetIdleRunTimePercent( void ) PRIVILEGED_FUNCTION;
2496 #endif
2497 
2498 /**
2499  * task. h
2500  * @code{c}
2501  * BaseType_t xTaskNotifyIndexed( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction );
2502  * BaseType_t xTaskNotify( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction );
2503  * @endcode
2504  *
2505  * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
2506  *
2507  * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these
2508  * functions to be available.
2509  *
2510  * Sends a direct to task notification to a task, with an optional value and
2511  * action.
2512  *
2513  * Each task has a private array of "notification values" (or 'notifications'),
2514  * each of which is a 32-bit unsigned integer (uint32_t).  The constant
2515  * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
2516  * array, and (for backward compatibility) defaults to 1 if left undefined.
2517  * Prior to FreeRTOS V10.4.0 there was only one notification value per task.
2518  *
2519  * Events can be sent to a task using an intermediary object.  Examples of such
2520  * objects are queues, semaphores, mutexes and event groups.  Task notifications
2521  * are a method of sending an event directly to a task without the need for such
2522  * an intermediary object.
2523  *
2524  * A notification sent to a task can optionally perform an action, such as
2525  * update, overwrite or increment one of the task's notification values.  In
2526  * that way task notifications can be used to send data to a task, or be used as
2527  * light weight and fast binary or counting semaphores.
2528  *
2529  * A task can use xTaskNotifyWaitIndexed() or ulTaskNotifyTakeIndexed() to
2530  * [optionally] block to wait for a notification to be pending.  The task does
2531  * not consume any CPU time while it is in the Blocked state.
2532  *
2533  * A notification sent to a task will remain pending until it is cleared by the
2534  * task calling xTaskNotifyWaitIndexed() or ulTaskNotifyTakeIndexed() (or their
2535  * un-indexed equivalents).  If the task was already in the Blocked state to
2536  * wait for a notification when the notification arrives then the task will
2537  * automatically be removed from the Blocked state (unblocked) and the
2538  * notification cleared.
2539  *
2540  * **NOTE** Each notification within the array operates independently - a task
2541  * can only block on one notification within the array at a time and will not be
2542  * unblocked by a notification sent to any other array index.
2543  *
2544  * Backward compatibility information:
2545  * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
2546  * all task notification API functions operated on that value. Replacing the
2547  * single notification value with an array of notification values necessitated a
2548  * new set of API functions that could address specific notifications within the
2549  * array.  xTaskNotify() is the original API function, and remains backward
2550  * compatible by always operating on the notification value at index 0 in the
2551  * array. Calling xTaskNotify() is equivalent to calling xTaskNotifyIndexed()
2552  * with the uxIndexToNotify parameter set to 0.
2553  *
2554  * @param xTaskToNotify The handle of the task being notified.  The handle to a
2555  * task can be returned from the xTaskCreate() API function used to create the
2556  * task, and the handle of the currently running task can be obtained by calling
2557  * xTaskGetCurrentTaskHandle().
2558  *
2559  * @param uxIndexToNotify The index within the target task's array of
2560  * notification values to which the notification is to be sent.  uxIndexToNotify
2561  * must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES.  xTaskNotify() does
2562  * not have this parameter and always sends notifications to index 0.
2563  *
2564  * @param ulValue Data that can be sent with the notification.  How the data is
2565  * used depends on the value of the eAction parameter.
2566  *
2567  * @param eAction Specifies how the notification updates the task's notification
2568  * value, if at all.  Valid values for eAction are as follows:
2569  *
2570  * eSetBits -
2571  * The target notification value is bitwise ORed with ulValue.
2572  * xTaskNotifyIndexed() always returns pdPASS in this case.
2573  *
2574  * eIncrement -
2575  * The target notification value is incremented.  ulValue is not used and
2576  * xTaskNotifyIndexed() always returns pdPASS in this case.
2577  *
2578  * eSetValueWithOverwrite -
2579  * The target notification value is set to the value of ulValue, even if the
2580  * task being notified had not yet processed the previous notification at the
2581  * same array index (the task already had a notification pending at that index).
2582  * xTaskNotifyIndexed() always returns pdPASS in this case.
2583  *
2584  * eSetValueWithoutOverwrite -
2585  * If the task being notified did not already have a notification pending at the
2586  * same array index then the target notification value is set to ulValue and
2587  * xTaskNotifyIndexed() will return pdPASS.  If the task being notified already
2588  * had a notification pending at the same array index then no action is
2589  * performed and pdFAIL is returned.
2590  *
2591  * eNoAction -
2592  * The task receives a notification at the specified array index without the
2593  * notification value at that index being updated.  ulValue is not used and
2594  * xTaskNotifyIndexed() always returns pdPASS in this case.
2595  *
2596  * pulPreviousNotificationValue -
2597  * Can be used to pass out the subject task's notification value before any
2598  * bits are modified by the notify function.
2599  *
2600  * @return Dependent on the value of eAction.  See the description of the
2601  * eAction parameter.
2602  *
2603  * \defgroup xTaskNotifyIndexed xTaskNotifyIndexed
2604  * \ingroup TaskNotifications
2605  */
2606 BaseType_t xTaskGenericNotify( TaskHandle_t xTaskToNotify,
2607                                UBaseType_t uxIndexToNotify,
2608                                uint32_t ulValue,
2609                                eNotifyAction eAction,
2610                                uint32_t * pulPreviousNotificationValue ) PRIVILEGED_FUNCTION;
2611 #define xTaskNotify( xTaskToNotify, ulValue, eAction ) \
2612     xTaskGenericNotify( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), NULL )
2613 #define xTaskNotifyIndexed( xTaskToNotify, uxIndexToNotify, ulValue, eAction ) \
2614     xTaskGenericNotify( ( xTaskToNotify ), ( uxIndexToNotify ), ( ulValue ), ( eAction ), NULL )
2615 
2616 /**
2617  * task. h
2618  * @code{c}
2619  * BaseType_t xTaskNotifyAndQueryIndexed( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotifyValue );
2620  * BaseType_t xTaskNotifyAndQuery( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotifyValue );
2621  * @endcode
2622  *
2623  * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
2624  *
2625  * xTaskNotifyAndQueryIndexed() performs the same operation as
2626  * xTaskNotifyIndexed() with the addition that it also returns the subject
2627  * task's prior notification value (the notification value at the time the
2628  * function is called rather than when the function returns) in the additional
2629  * pulPreviousNotifyValue parameter.
2630  *
2631  * xTaskNotifyAndQuery() performs the same operation as xTaskNotify() with the
2632  * addition that it also returns the subject task's prior notification value
2633  * (the notification value as it was at the time the function is called, rather
2634  * than when the function returns) in the additional pulPreviousNotifyValue
2635  * parameter.
2636  *
2637  * \defgroup xTaskNotifyAndQueryIndexed xTaskNotifyAndQueryIndexed
2638  * \ingroup TaskNotifications
2639  */
2640 #define xTaskNotifyAndQuery( xTaskToNotify, ulValue, eAction, pulPreviousNotifyValue ) \
2641     xTaskGenericNotify( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), ( pulPreviousNotifyValue ) )
2642 #define xTaskNotifyAndQueryIndexed( xTaskToNotify, uxIndexToNotify, ulValue, eAction, pulPreviousNotifyValue ) \
2643     xTaskGenericNotify( ( xTaskToNotify ), ( uxIndexToNotify ), ( ulValue ), ( eAction ), ( pulPreviousNotifyValue ) )
2644 
2645 /**
2646  * task. h
2647  * @code{c}
2648  * BaseType_t xTaskNotifyIndexedFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, BaseType_t *pxHigherPriorityTaskWoken );
2649  * BaseType_t xTaskNotifyFromISR( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, BaseType_t *pxHigherPriorityTaskWoken );
2650  * @endcode
2651  *
2652  * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
2653  *
2654  * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these
2655  * functions to be available.
2656  *
2657  * A version of xTaskNotifyIndexed() that can be used from an interrupt service
2658  * routine (ISR).
2659  *
2660  * Each task has a private array of "notification values" (or 'notifications'),
2661  * each of which is a 32-bit unsigned integer (uint32_t).  The constant
2662  * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
2663  * array, and (for backward compatibility) defaults to 1 if left undefined.
2664  * Prior to FreeRTOS V10.4.0 there was only one notification value per task.
2665  *
2666  * Events can be sent to a task using an intermediary object.  Examples of such
2667  * objects are queues, semaphores, mutexes and event groups.  Task notifications
2668  * are a method of sending an event directly to a task without the need for such
2669  * an intermediary object.
2670  *
2671  * A notification sent to a task can optionally perform an action, such as
2672  * update, overwrite or increment one of the task's notification values.  In
2673  * that way task notifications can be used to send data to a task, or be used as
2674  * light weight and fast binary or counting semaphores.
2675  *
2676  * A task can use xTaskNotifyWaitIndexed() to [optionally] block to wait for a
2677  * notification to be pending, or ulTaskNotifyTakeIndexed() to [optionally] block
2678  * to wait for a notification value to have a non-zero value.  The task does
2679  * not consume any CPU time while it is in the Blocked state.
2680  *
2681  * A notification sent to a task will remain pending until it is cleared by the
2682  * task calling xTaskNotifyWaitIndexed() or ulTaskNotifyTakeIndexed() (or their
2683  * un-indexed equivalents).  If the task was already in the Blocked state to
2684  * wait for a notification when the notification arrives then the task will
2685  * automatically be removed from the Blocked state (unblocked) and the
2686  * notification cleared.
2687  *
2688  * **NOTE** Each notification within the array operates independently - a task
2689  * can only block on one notification within the array at a time and will not be
2690  * unblocked by a notification sent to any other array index.
2691  *
2692  * Backward compatibility information:
2693  * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
2694  * all task notification API functions operated on that value. Replacing the
2695  * single notification value with an array of notification values necessitated a
2696  * new set of API functions that could address specific notifications within the
2697  * array.  xTaskNotifyFromISR() is the original API function, and remains
2698  * backward compatible by always operating on the notification value at index 0
2699  * within the array. Calling xTaskNotifyFromISR() is equivalent to calling
2700  * xTaskNotifyIndexedFromISR() with the uxIndexToNotify parameter set to 0.
2701  *
2702  * @param uxIndexToNotify The index within the target task's array of
2703  * notification values to which the notification is to be sent.  uxIndexToNotify
2704  * must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES.  xTaskNotifyFromISR()
2705  * does not have this parameter and always sends notifications to index 0.
2706  *
2707  * @param xTaskToNotify The handle of the task being notified.  The handle to a
2708  * task can be returned from the xTaskCreate() API function used to create the
2709  * task, and the handle of the currently running task can be obtained by calling
2710  * xTaskGetCurrentTaskHandle().
2711  *
2712  * @param ulValue Data that can be sent with the notification.  How the data is
2713  * used depends on the value of the eAction parameter.
2714  *
2715  * @param eAction Specifies how the notification updates the task's notification
2716  * value, if at all.  Valid values for eAction are as follows:
2717  *
2718  * eSetBits -
2719  * The task's notification value is bitwise ORed with ulValue.  xTaskNotify()
2720  * always returns pdPASS in this case.
2721  *
2722  * eIncrement -
2723  * The task's notification value is incremented.  ulValue is not used and
2724  * xTaskNotify() always returns pdPASS in this case.
2725  *
2726  * eSetValueWithOverwrite -
2727  * The task's notification value is set to the value of ulValue, even if the
2728  * task being notified had not yet processed the previous notification (the
2729  * task already had a notification pending).  xTaskNotify() always returns
2730  * pdPASS in this case.
2731  *
2732  * eSetValueWithoutOverwrite -
2733  * If the task being notified did not already have a notification pending then
2734  * the task's notification value is set to ulValue and xTaskNotify() will
2735  * return pdPASS.  If the task being notified already had a notification
2736  * pending then no action is performed and pdFAIL is returned.
2737  *
2738  * eNoAction -
2739  * The task receives a notification without its notification value being
2740  * updated.  ulValue is not used and xTaskNotify() always returns pdPASS in
2741  * this case.
2742  *
2743  * @param pxHigherPriorityTaskWoken  xTaskNotifyFromISR() will set
2744  * *pxHigherPriorityTaskWoken to pdTRUE if sending the notification caused the
2745  * task to which the notification was sent to leave the Blocked state, and the
2746  * unblocked task has a priority higher than the currently running task.  If
2747  * xTaskNotifyFromISR() sets this value to pdTRUE then a context switch should
2748  * be requested before the interrupt is exited.  How a context switch is
2749  * requested from an ISR is dependent on the port - see the documentation page
2750  * for the port in use.
2751  *
2752  * @return Dependent on the value of eAction.  See the description of the
2753  * eAction parameter.
2754  *
2755  * \defgroup xTaskNotifyIndexedFromISR xTaskNotifyIndexedFromISR
2756  * \ingroup TaskNotifications
2757  */
2758 BaseType_t xTaskGenericNotifyFromISR( TaskHandle_t xTaskToNotify,
2759                                       UBaseType_t uxIndexToNotify,
2760                                       uint32_t ulValue,
2761                                       eNotifyAction eAction,
2762                                       uint32_t * pulPreviousNotificationValue,
2763                                       BaseType_t * pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
2764 #define xTaskNotifyFromISR( xTaskToNotify, ulValue, eAction, pxHigherPriorityTaskWoken ) \
2765     xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), NULL, ( pxHigherPriorityTaskWoken ) )
2766 #define xTaskNotifyIndexedFromISR( xTaskToNotify, uxIndexToNotify, ulValue, eAction, pxHigherPriorityTaskWoken ) \
2767     xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( uxIndexToNotify ), ( ulValue ), ( eAction ), NULL, ( pxHigherPriorityTaskWoken ) )
2768 
2769 /**
2770  * task. h
2771  * @code{c}
2772  * BaseType_t xTaskNotifyAndQueryIndexedFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue, BaseType_t *pxHigherPriorityTaskWoken );
2773  * BaseType_t xTaskNotifyAndQueryFromISR( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue, BaseType_t *pxHigherPriorityTaskWoken );
2774  * @endcode
2775  *
2776  * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
2777  *
2778  * xTaskNotifyAndQueryIndexedFromISR() performs the same operation as
2779  * xTaskNotifyIndexedFromISR() with the addition that it also returns the
2780  * subject task's prior notification value (the notification value at the time
2781  * the function is called rather than at the time the function returns) in the
2782  * additional pulPreviousNotifyValue parameter.
2783  *
2784  * xTaskNotifyAndQueryFromISR() performs the same operation as
2785  * xTaskNotifyFromISR() with the addition that it also returns the subject
2786  * task's prior notification value (the notification value at the time the
2787  * function is called rather than at the time the function returns) in the
2788  * additional pulPreviousNotifyValue parameter.
2789  *
2790  * \defgroup xTaskNotifyAndQueryIndexedFromISR xTaskNotifyAndQueryIndexedFromISR
2791  * \ingroup TaskNotifications
2792  */
2793 #define xTaskNotifyAndQueryIndexedFromISR( xTaskToNotify, uxIndexToNotify, ulValue, eAction, pulPreviousNotificationValue, pxHigherPriorityTaskWoken ) \
2794     xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( uxIndexToNotify ), ( ulValue ), ( eAction ), ( pulPreviousNotificationValue ), ( pxHigherPriorityTaskWoken ) )
2795 #define xTaskNotifyAndQueryFromISR( xTaskToNotify, ulValue, eAction, pulPreviousNotificationValue, pxHigherPriorityTaskWoken ) \
2796     xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), ( pulPreviousNotificationValue ), ( pxHigherPriorityTaskWoken ) )
2797 
2798 /**
2799  * task. h
2800  * @code{c}
2801  * BaseType_t xTaskNotifyWaitIndexed( UBaseType_t uxIndexToWaitOn, uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait );
2802  *
2803  * BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait );
2804  * @endcode
2805  *
2806  * Waits for a direct to task notification to be pending at a given index within
2807  * an array of direct to task notifications.
2808  *
2809  * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
2810  *
2811  * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this
2812  * function to be available.
2813  *
2814  * Each task has a private array of "notification values" (or 'notifications'),
2815  * each of which is a 32-bit unsigned integer (uint32_t).  The constant
2816  * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
2817  * array, and (for backward compatibility) defaults to 1 if left undefined.
2818  * Prior to FreeRTOS V10.4.0 there was only one notification value per task.
2819  *
2820  * Events can be sent to a task using an intermediary object.  Examples of such
2821  * objects are queues, semaphores, mutexes and event groups.  Task notifications
2822  * are a method of sending an event directly to a task without the need for such
2823  * an intermediary object.
2824  *
2825  * A notification sent to a task can optionally perform an action, such as
2826  * update, overwrite or increment one of the task's notification values.  In
2827  * that way task notifications can be used to send data to a task, or be used as
2828  * light weight and fast binary or counting semaphores.
2829  *
2830  * A notification sent to a task will remain pending until it is cleared by the
2831  * task calling xTaskNotifyWaitIndexed() or ulTaskNotifyTakeIndexed() (or their
2832  * un-indexed equivalents).  If the task was already in the Blocked state to
2833  * wait for a notification when the notification arrives then the task will
2834  * automatically be removed from the Blocked state (unblocked) and the
2835  * notification cleared.
2836  *
2837  * A task can use xTaskNotifyWaitIndexed() to [optionally] block to wait for a
2838  * notification to be pending, or ulTaskNotifyTakeIndexed() to [optionally] block
2839  * to wait for a notification value to have a non-zero value.  The task does
2840  * not consume any CPU time while it is in the Blocked state.
2841  *
2842  * **NOTE** Each notification within the array operates independently - a task
2843  * can only block on one notification within the array at a time and will not be
2844  * unblocked by a notification sent to any other array index.
2845  *
2846  * Backward compatibility information:
2847  * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
2848  * all task notification API functions operated on that value. Replacing the
2849  * single notification value with an array of notification values necessitated a
2850  * new set of API functions that could address specific notifications within the
2851  * array.  xTaskNotifyWait() is the original API function, and remains backward
2852  * compatible by always operating on the notification value at index 0 in the
2853  * array. Calling xTaskNotifyWait() is equivalent to calling
2854  * xTaskNotifyWaitIndexed() with the uxIndexToWaitOn parameter set to 0.
2855  *
2856  * @param uxIndexToWaitOn The index within the calling task's array of
2857  * notification values on which the calling task will wait for a notification to
2858  * be received.  uxIndexToWaitOn must be less than
2859  * configTASK_NOTIFICATION_ARRAY_ENTRIES.  xTaskNotifyWait() does
2860  * not have this parameter and always waits for notifications on index 0.
2861  *
2862  * @param ulBitsToClearOnEntry Bits that are set in ulBitsToClearOnEntry value
2863  * will be cleared in the calling task's notification value before the task
2864  * checks to see if any notifications are pending, and optionally blocks if no
2865  * notifications are pending.  Setting ulBitsToClearOnEntry to ULONG_MAX (if
2866  * limits.h is included) or 0xffffffffU (if limits.h is not included) will have
2867  * the effect of resetting the task's notification value to 0.  Setting
2868  * ulBitsToClearOnEntry to 0 will leave the task's notification value unchanged.
2869  *
2870  * @param ulBitsToClearOnExit If a notification is pending or received before
2871  * the calling task exits the xTaskNotifyWait() function then the task's
2872  * notification value (see the xTaskNotify() API function) is passed out using
2873  * the pulNotificationValue parameter.  Then any bits that are set in
2874  * ulBitsToClearOnExit will be cleared in the task's notification value (note
2875  * *pulNotificationValue is set before any bits are cleared).  Setting
2876  * ulBitsToClearOnExit to ULONG_MAX (if limits.h is included) or 0xffffffffUL
2877  * (if limits.h is not included) will have the effect of resetting the task's
2878  * notification value to 0 before the function exits.  Setting
2879  * ulBitsToClearOnExit to 0 will leave the task's notification value unchanged
2880  * when the function exits (in which case the value passed out in
2881  * pulNotificationValue will match the task's notification value).
2882  *
2883  * @param pulNotificationValue Used to pass the task's notification value out
2884  * of the function.  Note the value passed out will not be effected by the
2885  * clearing of any bits caused by ulBitsToClearOnExit being non-zero.
2886  *
2887  * @param xTicksToWait The maximum amount of time that the task should wait in
2888  * the Blocked state for a notification to be received, should a notification
2889  * not already be pending when xTaskNotifyWait() was called.  The task
2890  * will not consume any processing time while it is in the Blocked state.  This
2891  * is specified in kernel ticks, the macro pdMS_TO_TICKS( value_in_ms ) can be
2892  * used to convert a time specified in milliseconds to a time specified in
2893  * ticks.
2894  *
2895  * @return If a notification was received (including notifications that were
2896  * already pending when xTaskNotifyWait was called) then pdPASS is
2897  * returned.  Otherwise pdFAIL is returned.
2898  *
2899  * \defgroup xTaskNotifyWaitIndexed xTaskNotifyWaitIndexed
2900  * \ingroup TaskNotifications
2901  */
2902 BaseType_t xTaskGenericNotifyWait( UBaseType_t uxIndexToWaitOn,
2903                                    uint32_t ulBitsToClearOnEntry,
2904                                    uint32_t ulBitsToClearOnExit,
2905                                    uint32_t * pulNotificationValue,
2906                                    TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
2907 #define xTaskNotifyWait( ulBitsToClearOnEntry, ulBitsToClearOnExit, pulNotificationValue, xTicksToWait ) \
2908     xTaskGenericNotifyWait( tskDEFAULT_INDEX_TO_NOTIFY, ( ulBitsToClearOnEntry ), ( ulBitsToClearOnExit ), ( pulNotificationValue ), ( xTicksToWait ) )
2909 #define xTaskNotifyWaitIndexed( uxIndexToWaitOn, ulBitsToClearOnEntry, ulBitsToClearOnExit, pulNotificationValue, xTicksToWait ) \
2910     xTaskGenericNotifyWait( ( uxIndexToWaitOn ), ( ulBitsToClearOnEntry ), ( ulBitsToClearOnExit ), ( pulNotificationValue ), ( xTicksToWait ) )
2911 
2912 /**
2913  * task. h
2914  * @code{c}
2915  * BaseType_t xTaskNotifyGiveIndexed( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify );
2916  * BaseType_t xTaskNotifyGive( TaskHandle_t xTaskToNotify );
2917  * @endcode
2918  *
2919  * Sends a direct to task notification to a particular index in the target
2920  * task's notification array in a manner similar to giving a counting semaphore.
2921  *
2922  * See https://www.FreeRTOS.org/RTOS-task-notifications.html for more details.
2923  *
2924  * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these
2925  * macros to be available.
2926  *
2927  * Each task has a private array of "notification values" (or 'notifications'),
2928  * each of which is a 32-bit unsigned integer (uint32_t).  The constant
2929  * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
2930  * array, and (for backward compatibility) defaults to 1 if left undefined.
2931  * Prior to FreeRTOS V10.4.0 there was only one notification value per task.
2932  *
2933  * Events can be sent to a task using an intermediary object.  Examples of such
2934  * objects are queues, semaphores, mutexes and event groups.  Task notifications
2935  * are a method of sending an event directly to a task without the need for such
2936  * an intermediary object.
2937  *
2938  * A notification sent to a task can optionally perform an action, such as
2939  * update, overwrite or increment one of the task's notification values.  In
2940  * that way task notifications can be used to send data to a task, or be used as
2941  * light weight and fast binary or counting semaphores.
2942  *
2943  * xTaskNotifyGiveIndexed() is a helper macro intended for use when task
2944  * notifications are used as light weight and faster binary or counting
2945  * semaphore equivalents.  Actual FreeRTOS semaphores are given using the
2946  * xSemaphoreGive() API function, the equivalent action that instead uses a task
2947  * notification is xTaskNotifyGiveIndexed().
2948  *
2949  * When task notifications are being used as a binary or counting semaphore
2950  * equivalent then the task being notified should wait for the notification
2951  * using the ulTaskNotifyTakeIndexed() API function rather than the
2952  * xTaskNotifyWaitIndexed() API function.
2953  *
2954  * **NOTE** Each notification within the array operates independently - a task
2955  * can only block on one notification within the array at a time and will not be
2956  * unblocked by a notification sent to any other array index.
2957  *
2958  * Backward compatibility information:
2959  * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
2960  * all task notification API functions operated on that value. Replacing the
2961  * single notification value with an array of notification values necessitated a
2962  * new set of API functions that could address specific notifications within the
2963  * array.  xTaskNotifyGive() is the original API function, and remains backward
2964  * compatible by always operating on the notification value at index 0 in the
2965  * array. Calling xTaskNotifyGive() is equivalent to calling
2966  * xTaskNotifyGiveIndexed() with the uxIndexToNotify parameter set to 0.
2967  *
2968  * @param xTaskToNotify The handle of the task being notified.  The handle to a
2969  * task can be returned from the xTaskCreate() API function used to create the
2970  * task, and the handle of the currently running task can be obtained by calling
2971  * xTaskGetCurrentTaskHandle().
2972  *
2973  * @param uxIndexToNotify The index within the target task's array of
2974  * notification values to which the notification is to be sent.  uxIndexToNotify
2975  * must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES.  xTaskNotifyGive()
2976  * does not have this parameter and always sends notifications to index 0.
2977  *
2978  * @return xTaskNotifyGive() is a macro that calls xTaskNotify() with the
2979  * eAction parameter set to eIncrement - so pdPASS is always returned.
2980  *
2981  * \defgroup xTaskNotifyGiveIndexed xTaskNotifyGiveIndexed
2982  * \ingroup TaskNotifications
2983  */
2984 #define xTaskNotifyGive( xTaskToNotify ) \
2985     xTaskGenericNotify( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( 0 ), eIncrement, NULL )
2986 #define xTaskNotifyGiveIndexed( xTaskToNotify, uxIndexToNotify ) \
2987     xTaskGenericNotify( ( xTaskToNotify ), ( uxIndexToNotify ), ( 0 ), eIncrement, NULL )
2988 
2989 /**
2990  * task. h
2991  * @code{c}
2992  * void vTaskNotifyGiveIndexedFromISR( TaskHandle_t xTaskHandle, UBaseType_t uxIndexToNotify, BaseType_t *pxHigherPriorityTaskWoken );
2993  * void vTaskNotifyGiveFromISR( TaskHandle_t xTaskHandle, BaseType_t *pxHigherPriorityTaskWoken );
2994  * @endcode
2995  *
2996  * A version of xTaskNotifyGiveIndexed() that can be called from an interrupt
2997  * service routine (ISR).
2998  *
2999  * See https://www.FreeRTOS.org/RTOS-task-notifications.html for more details.
3000  *
3001  * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this macro
3002  * to be available.
3003  *
3004  * Each task has a private array of "notification values" (or 'notifications'),
3005  * each of which is a 32-bit unsigned integer (uint32_t).  The constant
3006  * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
3007  * array, and (for backward compatibility) defaults to 1 if left undefined.
3008  * Prior to FreeRTOS V10.4.0 there was only one notification value per task.
3009  *
3010  * Events can be sent to a task using an intermediary object.  Examples of such
3011  * objects are queues, semaphores, mutexes and event groups.  Task notifications
3012  * are a method of sending an event directly to a task without the need for such
3013  * an intermediary object.
3014  *
3015  * A notification sent to a task can optionally perform an action, such as
3016  * update, overwrite or increment one of the task's notification values.  In
3017  * that way task notifications can be used to send data to a task, or be used as
3018  * light weight and fast binary or counting semaphores.
3019  *
3020  * vTaskNotifyGiveIndexedFromISR() is intended for use when task notifications
3021  * are used as light weight and faster binary or counting semaphore equivalents.
3022  * Actual FreeRTOS semaphores are given from an ISR using the
3023  * xSemaphoreGiveFromISR() API function, the equivalent action that instead uses
3024  * a task notification is vTaskNotifyGiveIndexedFromISR().
3025  *
3026  * When task notifications are being used as a binary or counting semaphore
3027  * equivalent then the task being notified should wait for the notification
3028  * using the ulTaskNotifyTakeIndexed() API function rather than the
3029  * xTaskNotifyWaitIndexed() API function.
3030  *
3031  * **NOTE** Each notification within the array operates independently - a task
3032  * can only block on one notification within the array at a time and will not be
3033  * unblocked by a notification sent to any other array index.
3034  *
3035  * Backward compatibility information:
3036  * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
3037  * all task notification API functions operated on that value. Replacing the
3038  * single notification value with an array of notification values necessitated a
3039  * new set of API functions that could address specific notifications within the
3040  * array.  xTaskNotifyFromISR() is the original API function, and remains
3041  * backward compatible by always operating on the notification value at index 0
3042  * within the array. Calling xTaskNotifyGiveFromISR() is equivalent to calling
3043  * xTaskNotifyGiveIndexedFromISR() with the uxIndexToNotify parameter set to 0.
3044  *
3045  * @param xTaskToNotify The handle of the task being notified.  The handle to a
3046  * task can be returned from the xTaskCreate() API function used to create the
3047  * task, and the handle of the currently running task can be obtained by calling
3048  * xTaskGetCurrentTaskHandle().
3049  *
3050  * @param uxIndexToNotify The index within the target task's array of
3051  * notification values to which the notification is to be sent.  uxIndexToNotify
3052  * must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES.
3053  * xTaskNotifyGiveFromISR() does not have this parameter and always sends
3054  * notifications to index 0.
3055  *
3056  * @param pxHigherPriorityTaskWoken  vTaskNotifyGiveFromISR() will set
3057  * *pxHigherPriorityTaskWoken to pdTRUE if sending the notification caused the
3058  * task to which the notification was sent to leave the Blocked state, and the
3059  * unblocked task has a priority higher than the currently running task.  If
3060  * vTaskNotifyGiveFromISR() sets this value to pdTRUE then a context switch
3061  * should be requested before the interrupt is exited.  How a context switch is
3062  * requested from an ISR is dependent on the port - see the documentation page
3063  * for the port in use.
3064  *
3065  * \defgroup vTaskNotifyGiveIndexedFromISR vTaskNotifyGiveIndexedFromISR
3066  * \ingroup TaskNotifications
3067  */
3068 void vTaskGenericNotifyGiveFromISR( TaskHandle_t xTaskToNotify,
3069                                     UBaseType_t uxIndexToNotify,
3070                                     BaseType_t * pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
3071 #define vTaskNotifyGiveFromISR( xTaskToNotify, pxHigherPriorityTaskWoken ) \
3072     vTaskGenericNotifyGiveFromISR( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( pxHigherPriorityTaskWoken ) )
3073 #define vTaskNotifyGiveIndexedFromISR( xTaskToNotify, uxIndexToNotify, pxHigherPriorityTaskWoken ) \
3074     vTaskGenericNotifyGiveFromISR( ( xTaskToNotify ), ( uxIndexToNotify ), ( pxHigherPriorityTaskWoken ) )
3075 
3076 /**
3077  * task. h
3078  * @code{c}
3079  * uint32_t ulTaskNotifyTakeIndexed( UBaseType_t uxIndexToWaitOn, BaseType_t xClearCountOnExit, TickType_t xTicksToWait );
3080  *
3081  * uint32_t ulTaskNotifyTake( BaseType_t xClearCountOnExit, TickType_t xTicksToWait );
3082  * @endcode
3083  *
3084  * Waits for a direct to task notification on a particular index in the calling
3085  * task's notification array in a manner similar to taking a counting semaphore.
3086  *
3087  * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
3088  *
3089  * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this
3090  * function to be available.
3091  *
3092  * Each task has a private array of "notification values" (or 'notifications'),
3093  * each of which is a 32-bit unsigned integer (uint32_t).  The constant
3094  * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
3095  * array, and (for backward compatibility) defaults to 1 if left undefined.
3096  * Prior to FreeRTOS V10.4.0 there was only one notification value per task.
3097  *
3098  * Events can be sent to a task using an intermediary object.  Examples of such
3099  * objects are queues, semaphores, mutexes and event groups.  Task notifications
3100  * are a method of sending an event directly to a task without the need for such
3101  * an intermediary object.
3102  *
3103  * A notification sent to a task can optionally perform an action, such as
3104  * update, overwrite or increment one of the task's notification values.  In
3105  * that way task notifications can be used to send data to a task, or be used as
3106  * light weight and fast binary or counting semaphores.
3107  *
3108  * ulTaskNotifyTakeIndexed() is intended for use when a task notification is
3109  * used as a faster and lighter weight binary or counting semaphore alternative.
3110  * Actual FreeRTOS semaphores are taken using the xSemaphoreTake() API function,
3111  * the equivalent action that instead uses a task notification is
3112  * ulTaskNotifyTakeIndexed().
3113  *
3114  * When a task is using its notification value as a binary or counting semaphore
3115  * other tasks should send notifications to it using the xTaskNotifyGiveIndexed()
3116  * macro, or xTaskNotifyIndex() function with the eAction parameter set to
3117  * eIncrement.
3118  *
3119  * ulTaskNotifyTakeIndexed() can either clear the task's notification value at
3120  * the array index specified by the uxIndexToWaitOn parameter to zero on exit,
3121  * in which case the notification value acts like a binary semaphore, or
3122  * decrement the notification value on exit, in which case the notification
3123  * value acts like a counting semaphore.
3124  *
3125  * A task can use ulTaskNotifyTakeIndexed() to [optionally] block to wait for
3126  * a notification.  The task does not consume any CPU time while it is in the
3127  * Blocked state.
3128  *
3129  * Where as xTaskNotifyWaitIndexed() will return when a notification is pending,
3130  * ulTaskNotifyTakeIndexed() will return when the task's notification value is
3131  * not zero.
3132  *
3133  * **NOTE** Each notification within the array operates independently - a task
3134  * can only block on one notification within the array at a time and will not be
3135  * unblocked by a notification sent to any other array index.
3136  *
3137  * Backward compatibility information:
3138  * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
3139  * all task notification API functions operated on that value. Replacing the
3140  * single notification value with an array of notification values necessitated a
3141  * new set of API functions that could address specific notifications within the
3142  * array.  ulTaskNotifyTake() is the original API function, and remains backward
3143  * compatible by always operating on the notification value at index 0 in the
3144  * array. Calling ulTaskNotifyTake() is equivalent to calling
3145  * ulTaskNotifyTakeIndexed() with the uxIndexToWaitOn parameter set to 0.
3146  *
3147  * @param uxIndexToWaitOn The index within the calling task's array of
3148  * notification values on which the calling task will wait for a notification to
3149  * be non-zero.  uxIndexToWaitOn must be less than
3150  * configTASK_NOTIFICATION_ARRAY_ENTRIES.  xTaskNotifyTake() does
3151  * not have this parameter and always waits for notifications on index 0.
3152  *
3153  * @param xClearCountOnExit if xClearCountOnExit is pdFALSE then the task's
3154  * notification value is decremented when the function exits.  In this way the
3155  * notification value acts like a counting semaphore.  If xClearCountOnExit is
3156  * not pdFALSE then the task's notification value is cleared to zero when the
3157  * function exits.  In this way the notification value acts like a binary
3158  * semaphore.
3159  *
3160  * @param xTicksToWait The maximum amount of time that the task should wait in
3161  * the Blocked state for the task's notification value to be greater than zero,
3162  * should the count not already be greater than zero when
3163  * ulTaskNotifyTake() was called.  The task will not consume any processing
3164  * time while it is in the Blocked state.  This is specified in kernel ticks,
3165  * the macro pdMS_TO_TICKS( value_in_ms ) can be used to convert a time
3166  * specified in milliseconds to a time specified in ticks.
3167  *
3168  * @return The task's notification count before it is either cleared to zero or
3169  * decremented (see the xClearCountOnExit parameter).
3170  *
3171  * \defgroup ulTaskNotifyTakeIndexed ulTaskNotifyTakeIndexed
3172  * \ingroup TaskNotifications
3173  */
3174 uint32_t ulTaskGenericNotifyTake( UBaseType_t uxIndexToWaitOn,
3175                                   BaseType_t xClearCountOnExit,
3176                                   TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
3177 #define ulTaskNotifyTake( xClearCountOnExit, xTicksToWait ) \
3178     ulTaskGenericNotifyTake( ( tskDEFAULT_INDEX_TO_NOTIFY ), ( xClearCountOnExit ), ( xTicksToWait ) )
3179 #define ulTaskNotifyTakeIndexed( uxIndexToWaitOn, xClearCountOnExit, xTicksToWait ) \
3180     ulTaskGenericNotifyTake( ( uxIndexToWaitOn ), ( xClearCountOnExit ), ( xTicksToWait ) )
3181 
3182 /**
3183  * task. h
3184  * @code{c}
3185  * BaseType_t xTaskNotifyStateClearIndexed( TaskHandle_t xTask, UBaseType_t uxIndexToCLear );
3186  *
3187  * BaseType_t xTaskNotifyStateClear( TaskHandle_t xTask );
3188  * @endcode
3189  *
3190  * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
3191  *
3192  * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these
3193  * functions to be available.
3194  *
3195  * Each task has a private array of "notification values" (or 'notifications'),
3196  * each of which is a 32-bit unsigned integer (uint32_t).  The constant
3197  * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
3198  * array, and (for backward compatibility) defaults to 1 if left undefined.
3199  * Prior to FreeRTOS V10.4.0 there was only one notification value per task.
3200  *
3201  * If a notification is sent to an index within the array of notifications then
3202  * the notification at that index is said to be 'pending' until it is read or
3203  * explicitly cleared by the receiving task.  xTaskNotifyStateClearIndexed()
3204  * is the function that clears a pending notification without reading the
3205  * notification value.  The notification value at the same array index is not
3206  * altered.  Set xTask to NULL to clear the notification state of the calling
3207  * task.
3208  *
3209  * Backward compatibility information:
3210  * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
3211  * all task notification API functions operated on that value. Replacing the
3212  * single notification value with an array of notification values necessitated a
3213  * new set of API functions that could address specific notifications within the
3214  * array.  xTaskNotifyStateClear() is the original API function, and remains
3215  * backward compatible by always operating on the notification value at index 0
3216  * within the array. Calling xTaskNotifyStateClear() is equivalent to calling
3217  * xTaskNotifyStateClearIndexed() with the uxIndexToNotify parameter set to 0.
3218  *
3219  * @param xTask The handle of the RTOS task that will have a notification state
3220  * cleared.  Set xTask to NULL to clear a notification state in the calling
3221  * task.  To obtain a task's handle create the task using xTaskCreate() and
3222  * make use of the pxCreatedTask parameter, or create the task using
3223  * xTaskCreateStatic() and store the returned value, or use the task's name in
3224  * a call to xTaskGetHandle().
3225  *
3226  * @param uxIndexToClear The index within the target task's array of
3227  * notification values to act upon.  For example, setting uxIndexToClear to 1
3228  * will clear the state of the notification at index 1 within the array.
3229  * uxIndexToClear must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES.
3230  * ulTaskNotifyStateClear() does not have this parameter and always acts on the
3231  * notification at index 0.
3232  *
3233  * @return pdTRUE if the task's notification state was set to
3234  * eNotWaitingNotification, otherwise pdFALSE.
3235  *
3236  * \defgroup xTaskNotifyStateClearIndexed xTaskNotifyStateClearIndexed
3237  * \ingroup TaskNotifications
3238  */
3239 BaseType_t xTaskGenericNotifyStateClear( TaskHandle_t xTask,
3240                                          UBaseType_t uxIndexToClear ) PRIVILEGED_FUNCTION;
3241 #define xTaskNotifyStateClear( xTask ) \
3242     xTaskGenericNotifyStateClear( ( xTask ), ( tskDEFAULT_INDEX_TO_NOTIFY ) )
3243 #define xTaskNotifyStateClearIndexed( xTask, uxIndexToClear ) \
3244     xTaskGenericNotifyStateClear( ( xTask ), ( uxIndexToClear ) )
3245 
3246 /**
3247  * task. h
3248  * @code{c}
3249  * uint32_t ulTaskNotifyValueClearIndexed( TaskHandle_t xTask, UBaseType_t uxIndexToClear, uint32_t ulBitsToClear );
3250  *
3251  * uint32_t ulTaskNotifyValueClear( TaskHandle_t xTask, uint32_t ulBitsToClear );
3252  * @endcode
3253  *
3254  * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
3255  *
3256  * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these
3257  * functions to be available.
3258  *
3259  * Each task has a private array of "notification values" (or 'notifications'),
3260  * each of which is a 32-bit unsigned integer (uint32_t).  The constant
3261  * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
3262  * array, and (for backward compatibility) defaults to 1 if left undefined.
3263  * Prior to FreeRTOS V10.4.0 there was only one notification value per task.
3264  *
3265  * ulTaskNotifyValueClearIndexed() clears the bits specified by the
3266  * ulBitsToClear bit mask in the notification value at array index uxIndexToClear
3267  * of the task referenced by xTask.
3268  *
3269  * Backward compatibility information:
3270  * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
3271  * all task notification API functions operated on that value. Replacing the
3272  * single notification value with an array of notification values necessitated a
3273  * new set of API functions that could address specific notifications within the
3274  * array.  ulTaskNotifyValueClear() is the original API function, and remains
3275  * backward compatible by always operating on the notification value at index 0
3276  * within the array. Calling ulTaskNotifyValueClear() is equivalent to calling
3277  * ulTaskNotifyValueClearIndexed() with the uxIndexToClear parameter set to 0.
3278  *
3279  * @param xTask The handle of the RTOS task that will have bits in one of its
3280  * notification values cleared. Set xTask to NULL to clear bits in a
3281  * notification value of the calling task.  To obtain a task's handle create the
3282  * task using xTaskCreate() and make use of the pxCreatedTask parameter, or
3283  * create the task using xTaskCreateStatic() and store the returned value, or
3284  * use the task's name in a call to xTaskGetHandle().
3285  *
3286  * @param uxIndexToClear The index within the target task's array of
3287  * notification values in which to clear the bits.  uxIndexToClear
3288  * must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES.
3289  * ulTaskNotifyValueClear() does not have this parameter and always clears bits
3290  * in the notification value at index 0.
3291  *
3292  * @param ulBitsToClear Bit mask of the bits to clear in the notification value of
3293  * xTask. Set a bit to 1 to clear the corresponding bits in the task's notification
3294  * value. Set ulBitsToClear to 0xffffffff (UINT_MAX on 32-bit architectures) to clear
3295  * the notification value to 0.  Set ulBitsToClear to 0 to query the task's
3296  * notification value without clearing any bits.
3297  *
3298  *
3299  * @return The value of the target task's notification value before the bits
3300  * specified by ulBitsToClear were cleared.
3301  * \defgroup ulTaskNotifyValueClear ulTaskNotifyValueClear
3302  * \ingroup TaskNotifications
3303  */
3304 uint32_t ulTaskGenericNotifyValueClear( TaskHandle_t xTask,
3305                                         UBaseType_t uxIndexToClear,
3306                                         uint32_t ulBitsToClear ) PRIVILEGED_FUNCTION;
3307 #define ulTaskNotifyValueClear( xTask, ulBitsToClear ) \
3308     ulTaskGenericNotifyValueClear( ( xTask ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulBitsToClear ) )
3309 #define ulTaskNotifyValueClearIndexed( xTask, uxIndexToClear, ulBitsToClear ) \
3310     ulTaskGenericNotifyValueClear( ( xTask ), ( uxIndexToClear ), ( ulBitsToClear ) )
3311 
3312 /**
3313  * task.h
3314  * @code{c}
3315  * void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut );
3316  * @endcode
3317  *
3318  * Capture the current time for future use with xTaskCheckForTimeOut().
3319  *
3320  * @param pxTimeOut Pointer to a timeout object into which the current time
3321  * is to be captured.  The captured time includes the tick count and the number
3322  * of times the tick count has overflowed since the system first booted.
3323  * \defgroup vTaskSetTimeOutState vTaskSetTimeOutState
3324  * \ingroup TaskCtrl
3325  */
3326 void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut ) PRIVILEGED_FUNCTION;
3327 
3328 /**
3329  * task.h
3330  * @code{c}
3331  * BaseType_t xTaskCheckForTimeOut( TimeOut_t * const pxTimeOut, TickType_t * const pxTicksToWait );
3332  * @endcode
3333  *
3334  * Determines if pxTicksToWait ticks has passed since a time was captured
3335  * using a call to vTaskSetTimeOutState().  The captured time includes the tick
3336  * count and the number of times the tick count has overflowed.
3337  *
3338  * @param pxTimeOut The time status as captured previously using
3339  * vTaskSetTimeOutState. If the timeout has not yet occurred, it is updated
3340  * to reflect the current time status.
3341  * @param pxTicksToWait The number of ticks to check for timeout i.e. if
3342  * pxTicksToWait ticks have passed since pxTimeOut was last updated (either by
3343  * vTaskSetTimeOutState() or xTaskCheckForTimeOut()), the timeout has occurred.
3344  * If the timeout has not occurred, pxTicksToWait is updated to reflect the
3345  * number of remaining ticks.
3346  *
3347  * @return If timeout has occurred, pdTRUE is returned. Otherwise pdFALSE is
3348  * returned and pxTicksToWait is updated to reflect the number of remaining
3349  * ticks.
3350  *
3351  * @see https://www.FreeRTOS.org/xTaskCheckForTimeOut.html
3352  *
3353  * Example Usage:
3354  * @code{c}
3355  *  // Driver library function used to receive uxWantedBytes from an Rx buffer
3356  *  // that is filled by a UART interrupt. If there are not enough bytes in the
3357  *  // Rx buffer then the task enters the Blocked state until it is notified that
3358  *  // more data has been placed into the buffer. If there is still not enough
3359  *  // data then the task re-enters the Blocked state, and xTaskCheckForTimeOut()
3360  *  // is used to re-calculate the Block time to ensure the total amount of time
3361  *  // spent in the Blocked state does not exceed MAX_TIME_TO_WAIT. This
3362  *  // continues until either the buffer contains at least uxWantedBytes bytes,
3363  *  // or the total amount of time spent in the Blocked state reaches
3364  *  // MAX_TIME_TO_WAIT - at which point the task reads however many bytes are
3365  *  // available up to a maximum of uxWantedBytes.
3366  *
3367  *  size_t xUART_Receive( uint8_t *pucBuffer, size_t uxWantedBytes )
3368  *  {
3369  *  size_t uxReceived = 0;
3370  *  TickType_t xTicksToWait = MAX_TIME_TO_WAIT;
3371  *  TimeOut_t xTimeOut;
3372  *
3373  *      // Initialize xTimeOut.  This records the time at which this function
3374  *      // was entered.
3375  *      vTaskSetTimeOutState( &xTimeOut );
3376  *
3377  *      // Loop until the buffer contains the wanted number of bytes, or a
3378  *      // timeout occurs.
3379  *      while( UART_bytes_in_rx_buffer( pxUARTInstance ) < uxWantedBytes )
3380  *      {
3381  *          // The buffer didn't contain enough data so this task is going to
3382  *          // enter the Blocked state. Adjusting xTicksToWait to account for
3383  *          // any time that has been spent in the Blocked state within this
3384  *          // function so far to ensure the total amount of time spent in the
3385  *          // Blocked state does not exceed MAX_TIME_TO_WAIT.
3386  *          if( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait ) != pdFALSE )
3387  *          {
3388  *              //Timed out before the wanted number of bytes were available,
3389  *              // exit the loop.
3390  *              break;
3391  *          }
3392  *
3393  *          // Wait for a maximum of xTicksToWait ticks to be notified that the
3394  *          // receive interrupt has placed more data into the buffer.
3395  *          ulTaskNotifyTake( pdTRUE, xTicksToWait );
3396  *      }
3397  *
3398  *      // Attempt to read uxWantedBytes from the receive buffer into pucBuffer.
3399  *      // The actual number of bytes read (which might be less than
3400  *      // uxWantedBytes) is returned.
3401  *      uxReceived = UART_read_from_receive_buffer( pxUARTInstance,
3402  *                                                  pucBuffer,
3403  *                                                  uxWantedBytes );
3404  *
3405  *      return uxReceived;
3406  *  }
3407  * @endcode
3408  * \defgroup xTaskCheckForTimeOut xTaskCheckForTimeOut
3409  * \ingroup TaskCtrl
3410  */
3411 BaseType_t xTaskCheckForTimeOut( TimeOut_t * const pxTimeOut,
3412                                  TickType_t * const pxTicksToWait ) PRIVILEGED_FUNCTION;
3413 
3414 /**
3415  * task.h
3416  * @code{c}
3417  * BaseType_t xTaskCatchUpTicks( TickType_t xTicksToCatchUp );
3418  * @endcode
3419  *
3420  * This function corrects the tick count value after the application code has held
3421  * interrupts disabled for an extended period resulting in tick interrupts having
3422  * been missed.
3423  *
3424  * This function is similar to vTaskStepTick(), however, unlike
3425  * vTaskStepTick(), xTaskCatchUpTicks() may move the tick count forward past a
3426  * time at which a task should be removed from the blocked state.  That means
3427  * tasks may have to be removed from the blocked state as the tick count is
3428  * moved.
3429  *
3430  * @param xTicksToCatchUp The number of tick interrupts that have been missed due to
3431  * interrupts being disabled.  Its value is not computed automatically, so must be
3432  * computed by the application writer.
3433  *
3434  * @return pdTRUE if moving the tick count forward resulted in a task leaving the
3435  * blocked state and a context switch being performed.  Otherwise pdFALSE.
3436  *
3437  * \defgroup xTaskCatchUpTicks xTaskCatchUpTicks
3438  * \ingroup TaskCtrl
3439  */
3440 BaseType_t xTaskCatchUpTicks( TickType_t xTicksToCatchUp ) PRIVILEGED_FUNCTION;
3441 
3442 /**
3443  * task.h
3444  * @code{c}
3445  * void vTaskResetState( void );
3446  * @endcode
3447  *
3448  * This function resets the internal state of the task. It must be called by the
3449  * application before restarting the scheduler.
3450  *
3451  * \defgroup vTaskResetState vTaskResetState
3452  * \ingroup SchedulerControl
3453  */
3454 void vTaskResetState( void ) PRIVILEGED_FUNCTION;
3455 
3456 
3457 /*-----------------------------------------------------------
3458 * SCHEDULER INTERNALS AVAILABLE FOR PORTING PURPOSES
3459 *----------------------------------------------------------*/
3460 
3461 #if ( configNUMBER_OF_CORES == 1 )
3462     #define taskYIELD_WITHIN_API()    portYIELD_WITHIN_API()
3463 #else /* #if ( configNUMBER_OF_CORES == 1 ) */
3464     #define taskYIELD_WITHIN_API()    vTaskYieldWithinAPI()
3465 #endif /* #if ( configNUMBER_OF_CORES == 1 ) */
3466 
3467 /*
3468  * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS ONLY
3469  * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS
3470  * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
3471  *
3472  * Called from the real time kernel tick (either preemptive or cooperative),
3473  * this increments the tick count and checks if any tasks that are blocked
3474  * for a finite period required removing from a blocked list and placing on
3475  * a ready list.  If a non-zero value is returned then a context switch is
3476  * required because either:
3477  *   + A task was removed from a blocked list because its timeout had expired,
3478  *     or
3479  *   + Time slicing is in use and there is a task of equal priority to the
3480  *     currently running task.
3481  */
3482 BaseType_t xTaskIncrementTick( void ) PRIVILEGED_FUNCTION;
3483 
3484 /*
3485  * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS AN
3486  * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
3487  *
3488  * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED.
3489  *
3490  * Removes the calling task from the ready list and places it both
3491  * on the list of tasks waiting for a particular event, and the
3492  * list of delayed tasks.  The task will be removed from both lists
3493  * and replaced on the ready list should either the event occur (and
3494  * there be no higher priority tasks waiting on the same event) or
3495  * the delay period expires.
3496  *
3497  * The 'unordered' version replaces the event list item value with the
3498  * xItemValue value, and inserts the list item at the end of the list.
3499  *
3500  * The 'ordered' version uses the existing event list item value (which is the
3501  * owning task's priority) to insert the list item into the event list in task
3502  * priority order.
3503  *
3504  * @param pxEventList The list containing tasks that are blocked waiting
3505  * for the event to occur.
3506  *
3507  * @param xItemValue The item value to use for the event list item when the
3508  * event list is not ordered by task priority.
3509  *
3510  * @param xTicksToWait The maximum amount of time that the task should wait
3511  * for the event to occur.  This is specified in kernel ticks, the constant
3512  * portTICK_PERIOD_MS can be used to convert kernel ticks into a real time
3513  * period.
3514  */
3515 void vTaskPlaceOnEventList( List_t * const pxEventList,
3516                             const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
3517 void vTaskPlaceOnUnorderedEventList( List_t * pxEventList,
3518                                      const TickType_t xItemValue,
3519                                      const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
3520 
3521 /*
3522  * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS AN
3523  * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
3524  *
3525  * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED.
3526  *
3527  * This function performs nearly the same function as vTaskPlaceOnEventList().
3528  * The difference being that this function does not permit tasks to block
3529  * indefinitely, whereas vTaskPlaceOnEventList() does.
3530  *
3531  */
3532 void vTaskPlaceOnEventListRestricted( List_t * const pxEventList,
3533                                       TickType_t xTicksToWait,
3534                                       const BaseType_t xWaitIndefinitely ) PRIVILEGED_FUNCTION;
3535 
3536 /*
3537  * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS AN
3538  * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
3539  *
3540  * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED.
3541  *
3542  * Removes a task from both the specified event list and the list of blocked
3543  * tasks, and places it on a ready queue.
3544  *
3545  * xTaskRemoveFromEventList()/vTaskRemoveFromUnorderedEventList() will be called
3546  * if either an event occurs to unblock a task, or the block timeout period
3547  * expires.
3548  *
3549  * xTaskRemoveFromEventList() is used when the event list is in task priority
3550  * order.  It removes the list item from the head of the event list as that will
3551  * have the highest priority owning task of all the tasks on the event list.
3552  * vTaskRemoveFromUnorderedEventList() is used when the event list is not
3553  * ordered and the event list items hold something other than the owning tasks
3554  * priority.  In this case the event list item value is updated to the value
3555  * passed in the xItemValue parameter.
3556  *
3557  * @return pdTRUE if the task being removed has a higher priority than the task
3558  * making the call, otherwise pdFALSE.
3559  */
3560 BaseType_t xTaskRemoveFromEventList( const List_t * const pxEventList ) PRIVILEGED_FUNCTION;
3561 void vTaskRemoveFromUnorderedEventList( ListItem_t * pxEventListItem,
3562                                         const TickType_t xItemValue ) PRIVILEGED_FUNCTION;
3563 
3564 /*
3565  * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS ONLY
3566  * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS
3567  * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
3568  *
3569  * Sets the pointer to the current TCB to the TCB of the highest priority task
3570  * that is ready to run.
3571  */
3572 #if ( configNUMBER_OF_CORES == 1 )
3573     portDONT_DISCARD void vTaskSwitchContext( void ) PRIVILEGED_FUNCTION;
3574 #else
3575     portDONT_DISCARD void vTaskSwitchContext( BaseType_t xCoreID ) PRIVILEGED_FUNCTION;
3576 #endif
3577 
3578 /*
3579  * THESE FUNCTIONS MUST NOT BE USED FROM APPLICATION CODE.  THEY ARE USED BY
3580  * THE EVENT BITS MODULE.
3581  */
3582 TickType_t uxTaskResetEventItemValue( void ) PRIVILEGED_FUNCTION;
3583 
3584 /*
3585  * Return the handle of the calling task.
3586  */
3587 TaskHandle_t xTaskGetCurrentTaskHandle( void ) PRIVILEGED_FUNCTION;
3588 
3589 /*
3590  * Return the handle of the task running on specified core.
3591  */
3592 TaskHandle_t xTaskGetCurrentTaskHandleForCore( BaseType_t xCoreID ) PRIVILEGED_FUNCTION;
3593 
3594 /*
3595  * Shortcut used by the queue implementation to prevent unnecessary call to
3596  * taskYIELD();
3597  */
3598 void vTaskMissedYield( void ) PRIVILEGED_FUNCTION;
3599 
3600 /*
3601  * Returns the scheduler state as taskSCHEDULER_RUNNING,
3602  * taskSCHEDULER_NOT_STARTED or taskSCHEDULER_SUSPENDED.
3603  */
3604 BaseType_t xTaskGetSchedulerState( void ) PRIVILEGED_FUNCTION;
3605 
3606 /*
3607  * Raises the priority of the mutex holder to that of the calling task should
3608  * the mutex holder have a priority less than the calling task.
3609  */
3610 BaseType_t xTaskPriorityInherit( TaskHandle_t const pxMutexHolder ) PRIVILEGED_FUNCTION;
3611 
3612 /*
3613  * Set the priority of a task back to its proper priority in the case that it
3614  * inherited a higher priority while it was holding a semaphore.
3615  */
3616 BaseType_t xTaskPriorityDisinherit( TaskHandle_t const pxMutexHolder ) PRIVILEGED_FUNCTION;
3617 
3618 /*
3619  * If a higher priority task attempting to obtain a mutex caused a lower
3620  * priority task to inherit the higher priority task's priority - but the higher
3621  * priority task then timed out without obtaining the mutex, then the lower
3622  * priority task will disinherit the priority again - but only down as far as
3623  * the highest priority task that is still waiting for the mutex (if there were
3624  * more than one task waiting for the mutex).
3625  */
3626 void vTaskPriorityDisinheritAfterTimeout( TaskHandle_t const pxMutexHolder,
3627                                           UBaseType_t uxHighestPriorityWaitingTask ) PRIVILEGED_FUNCTION;
3628 
3629 /*
3630  * Get the uxTaskNumber assigned to the task referenced by the xTask parameter.
3631  */
3632 #if ( configUSE_TRACE_FACILITY == 1 )
3633     UBaseType_t uxTaskGetTaskNumber( TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
3634 #endif
3635 
3636 /*
3637  * Set the uxTaskNumber of the task referenced by the xTask parameter to
3638  * uxHandle.
3639  */
3640 #if ( configUSE_TRACE_FACILITY == 1 )
3641     void vTaskSetTaskNumber( TaskHandle_t xTask,
3642                              const UBaseType_t uxHandle ) PRIVILEGED_FUNCTION;
3643 #endif
3644 
3645 /*
3646  * Only available when configUSE_TICKLESS_IDLE is set to 1.
3647  * If tickless mode is being used, or a low power mode is implemented, then
3648  * the tick interrupt will not execute during idle periods.  When this is the
3649  * case, the tick count value maintained by the scheduler needs to be kept up
3650  * to date with the actual execution time by being skipped forward by a time
3651  * equal to the idle period.
3652  */
3653 #if ( configUSE_TICKLESS_IDLE != 0 )
3654     void vTaskStepTick( TickType_t xTicksToJump ) PRIVILEGED_FUNCTION;
3655 #endif
3656 
3657 /*
3658  * Only available when configUSE_TICKLESS_IDLE is set to 1.
3659  * Provided for use within portSUPPRESS_TICKS_AND_SLEEP() to allow the port
3660  * specific sleep function to determine if it is ok to proceed with the sleep,
3661  * and if it is ok to proceed, if it is ok to sleep indefinitely.
3662  *
3663  * This function is necessary because portSUPPRESS_TICKS_AND_SLEEP() is only
3664  * called with the scheduler suspended, not from within a critical section.  It
3665  * is therefore possible for an interrupt to request a context switch between
3666  * portSUPPRESS_TICKS_AND_SLEEP() and the low power mode actually being
3667  * entered.  eTaskConfirmSleepModeStatus() should be called from a short
3668  * critical section between the timer being stopped and the sleep mode being
3669  * entered to ensure it is ok to proceed into the sleep mode.
3670  */
3671 #if ( configUSE_TICKLESS_IDLE != 0 )
3672     eSleepModeStatus eTaskConfirmSleepModeStatus( void ) PRIVILEGED_FUNCTION;
3673 #endif
3674 
3675 /*
3676  * For internal use only.  Increment the mutex held count when a mutex is
3677  * taken and return the handle of the task that has taken the mutex.
3678  */
3679 TaskHandle_t pvTaskIncrementMutexHeldCount( void ) PRIVILEGED_FUNCTION;
3680 
3681 /*
3682  * For internal use only.  Same as vTaskSetTimeOutState(), but without a critical
3683  * section.
3684  */
3685 void vTaskInternalSetTimeOutState( TimeOut_t * const pxTimeOut ) PRIVILEGED_FUNCTION;
3686 
3687 /*
3688  * For internal use only. Same as portYIELD_WITHIN_API() in single core FreeRTOS.
3689  * For SMP this is not defined by the port.
3690  */
3691 #if ( configNUMBER_OF_CORES > 1 )
3692     void vTaskYieldWithinAPI( void );
3693 #endif
3694 
3695 /*
3696  * This function is only intended for use when implementing a port of the scheduler
3697  * and is only available when portCRITICAL_NESTING_IN_TCB is set to 1 or configNUMBER_OF_CORES
3698  * is greater than 1. This function can be used in the implementation of portENTER_CRITICAL
3699  * if port wants to maintain critical nesting count in TCB in single core FreeRTOS.
3700  * It should be used in the implementation of portENTER_CRITICAL if port is running a
3701  * multiple core FreeRTOS.
3702  */
3703 #if ( ( portCRITICAL_NESTING_IN_TCB == 1 ) || ( configNUMBER_OF_CORES > 1 ) )
3704     void vTaskEnterCritical( void );
3705 #endif
3706 
3707 /*
3708  * This function is only intended for use when implementing a port of the scheduler
3709  * and is only available when portCRITICAL_NESTING_IN_TCB is set to 1 or configNUMBER_OF_CORES
3710  * is greater than 1. This function can be used in the implementation of portEXIT_CRITICAL
3711  * if port wants to maintain critical nesting count in TCB in single core FreeRTOS.
3712  * It should be used in the implementation of portEXIT_CRITICAL if port is running a
3713  * multiple core FreeRTOS.
3714  */
3715 #if ( ( portCRITICAL_NESTING_IN_TCB == 1 ) || ( configNUMBER_OF_CORES > 1 ) )
3716     void vTaskExitCritical( void );
3717 #endif
3718 
3719 /*
3720  * This function is only intended for use when implementing a port of the scheduler
3721  * and is only available when configNUMBER_OF_CORES is greater than 1. This function
3722  * should be used in the implementation of portENTER_CRITICAL_FROM_ISR if port is
3723  * running a multiple core FreeRTOS.
3724  */
3725 #if ( configNUMBER_OF_CORES > 1 )
3726     UBaseType_t vTaskEnterCriticalFromISR( void );
3727 #endif
3728 
3729 /*
3730  * This function is only intended for use when implementing a port of the scheduler
3731  * and is only available when configNUMBER_OF_CORES is greater than 1. This function
3732  * should be used in the implementation of portEXIT_CRITICAL_FROM_ISR if port is
3733  * running a multiple core FreeRTOS.
3734  */
3735 #if ( configNUMBER_OF_CORES > 1 )
3736     void vTaskExitCriticalFromISR( UBaseType_t uxSavedInterruptStatus );
3737 #endif
3738 
3739 #if ( portUSING_MPU_WRAPPERS == 1 )
3740 
3741 /*
3742  * For internal use only.  Get MPU settings associated with a task.
3743  */
3744     xMPU_SETTINGS * xTaskGetMPUSettings( TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
3745 
3746 #endif /* portUSING_MPU_WRAPPERS */
3747 
3748 
3749 #if ( ( portUSING_MPU_WRAPPERS == 1 ) && ( configUSE_MPU_WRAPPERS_V1 == 0 ) && ( configENABLE_ACCESS_CONTROL_LIST == 1 ) )
3750 
3751 /*
3752  * For internal use only.  Grant/Revoke a task's access to a kernel object.
3753  */
3754     void vGrantAccessToKernelObject( TaskHandle_t xExternalTaskHandle,
3755                                      int32_t lExternalKernelObjectHandle ) PRIVILEGED_FUNCTION;
3756     void vRevokeAccessToKernelObject( TaskHandle_t xExternalTaskHandle,
3757                                       int32_t lExternalKernelObjectHandle ) PRIVILEGED_FUNCTION;
3758 
3759 /*
3760  * For internal use only.  Grant/Revoke a task's access to a kernel object.
3761  */
3762     void vPortGrantAccessToKernelObject( TaskHandle_t xInternalTaskHandle,
3763                                          int32_t lInternalIndexOfKernelObject ) PRIVILEGED_FUNCTION;
3764     void vPortRevokeAccessToKernelObject( TaskHandle_t xInternalTaskHandle,
3765                                           int32_t lInternalIndexOfKernelObject ) PRIVILEGED_FUNCTION;
3766 
3767 #endif /* #if ( ( portUSING_MPU_WRAPPERS == 1 ) && ( configUSE_MPU_WRAPPERS_V1 == 0 ) && ( configENABLE_ACCESS_CONTROL_LIST == 1 ) ) */
3768 
3769 /* *INDENT-OFF* */
3770 #ifdef __cplusplus
3771     }
3772 #endif
3773 /* *INDENT-ON* */
3774 #endif /* INC_TASK_H */
3775