1 /*
2 * FreeRTOS Kernel <DEVELOPMENT BRANCH>
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
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 */
60
61 /* MPU region parameters passed in ulParameters
62 * of MemoryRegion_t struct. */
68
69 /* The direct to task notification feature used to have only a single notification
70 * per task. Now there is an array of notifications per task that is dimensioned by
71 * configTASK_NOTIFICATION_ARRAY_ENTRIES. For backward compatibility, any use of the
72 * original direct to task notification defaults to using the first index in the
73 * array. */
75
76 /**
77 * task. h
78 *
79 * Type by which tasks are referenced. For example, a call to xTaskCreate
80 * returns (via a pointer parameter) an TaskHandle_t variable that can then
81 * be used as a parameter to vTaskDelete to delete the task.
82 *
83 * \defgroup TaskHandle_t TaskHandle_t
84 * \ingroup Tasks
85 */
86 struct tskTaskControlBlock; /* The old naming convention is used to prevent breaking kernel aware debuggers. */
88
89 /*
90 * Defines the prototype to which the application task hook function must
91 * conform.
92 */
94
95 /* Task states returned by eTaskGetState. */
96 typedef enum
97 {
98
eRunning = 0, /* A task is querying the state of itself, so must be running. */
99
eReady, /* The task being queried is in a ready or pending ready list. */
100
eBlocked, /* The task being queried is in the Blocked state. */
101
eSuspended, /* The task being queried is in the Suspended state, or is in the Blocked state with an infinite time out. */
102
eDeleted, /* The task being queried has been deleted, but its TCB has not yet been freed. */
103
eInvalid /* Used as an 'invalid state' value. */
105
106 /* Actions that can be performed when vTaskNotify() is called. */
107 typedef enum
108 {
109
eNoAction = 0, /* Notify the task without updating its notify value. */
110
eSetBits, /* Set bits in the task's notification value. */
111
eIncrement, /* Increment the task's notification value. */
112
eSetValueWithOverwrite, /* Set the task's notification value to a specific value even if the previous value has not yet been read by the task. */
115
116 /*
117 * Used internally only.
118 */
120 {
124
125 /*
126 * Defines the memory ranges allocated to the task when an MPU is used.
127 */
129 {
134
135 /*
136 * Parameters required to create an MPU protected task.
137 */
139 {
141 const char *
pcName; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
149 #endif
151
152 /* Used with the uxTaskGetSystemState() function to return the state of each task
153 * in the system. */
155 {
156
TaskHandle_t xHandle; /* The handle of the task to which the rest of the information in the structure relates. */
157 const char *
pcTaskName; /* A pointer to the task's name. This value will be invalid if the task was deleted since the structure was populated! */ /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
161
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. */
162 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. */
164 #if ( (
portSTACK_GROWTH > 0 ) && ( configRECORD_STACK_HIGH_ADDRESS == 1 ) )
167 #endif
168 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. */
170
171 /* Possible return values for eTaskConfirmSleepModeStatus(). */
172 typedef enum
173 {
174
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. */
175
eStandardSleep, /* Enter a sleep mode that will not last any longer than the expected idle time. */
176 #if ( INCLUDE_vTaskSuspend == 1 )
177
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. */
178 #endif /* INCLUDE_vTaskSuspend */
180
181 /**
182 * Defines the priority used by the idle task. This must not be modified.
183 *
184 * \ingroup TaskUtils
185 */
187
188 /**
189 * task. h
190 *
191 * Macro for forcing a context switch.
192 *
193 * \defgroup taskYIELD taskYIELD
194 * \ingroup SchedulerControl
195 */
197
198 /**
199 * task. h
200 *
201 * Macro to mark the start of a critical code region. Preemptive context
202 * switches cannot occur when in a critical region.
203 *
204 * NOTE: This may alter the stack (depending on the portable implementation)
205 * so must be used with care!
206 *
207 * \defgroup taskENTER_CRITICAL taskENTER_CRITICAL
208 * \ingroup SchedulerControl
209 */
212
213 /**
214 * task. h
215 *
216 * Macro to mark the end of a critical code region. Preemptive context
217 * switches cannot occur when in a critical region.
218 *
219 * NOTE: This may alter the stack (depending on the portable implementation)
220 * so must be used with care!
221 *
222 * \defgroup taskEXIT_CRITICAL taskEXIT_CRITICAL
223 * \ingroup SchedulerControl
224 */
227
228 /**
229 * task. h
230 *
231 * Macro to disable all maskable interrupts.
232 *
233 * \defgroup taskDISABLE_INTERRUPTS taskDISABLE_INTERRUPTS
234 * \ingroup SchedulerControl
235 */
237
238 /**
239 * task. h
240 *
241 * Macro to enable microcontroller interrupts.
242 *
243 * \defgroup taskENABLE_INTERRUPTS taskENABLE_INTERRUPTS
244 * \ingroup SchedulerControl
245 */
247
248 /* Definitions returned by xTaskGetSchedulerState(). taskSCHEDULER_SUSPENDED is
249 * 0 to generate more optimal code when configASSERT() is defined as the constant
250 * is used in assert() statements. */
254
255
256 /*-----------------------------------------------------------
257 * TASK CREATION API
258 *----------------------------------------------------------*/
259
260 /**
261 * task. h
262 * @code{c}
263 * BaseType_t xTaskCreate(
264 * TaskFunction_t pxTaskCode,
265 * const char *pcName,
266 * configSTACK_DEPTH_TYPE usStackDepth,
267 * void *pvParameters,
268 * UBaseType_t uxPriority,
269 * TaskHandle_t *pxCreatedTask
270 * );
271 * @endcode
272 *
273 * Create a new task and add it to the list of tasks that are ready to run.
274 *
275 * Internally, within the FreeRTOS implementation, tasks use two blocks of
276 * memory. The first block is used to hold the task's data structures. The
277 * second block is used by the task as its stack. If a task is created using
278 * xTaskCreate() then both blocks of memory are automatically dynamically
279 * allocated inside the xTaskCreate() function. (see
280 * https://www.FreeRTOS.org/a00111.html). If a task is created using
281 * xTaskCreateStatic() then the application writer must provide the required
282 * memory. xTaskCreateStatic() therefore allows a task to be created without
283 * using any dynamic memory allocation.
284 *
285 * See xTaskCreateStatic() for a version that does not use any dynamic memory
286 * allocation.
287 *
288 * xTaskCreate() can only be used to create a task that has unrestricted
289 * access to the entire microcontroller memory map. Systems that include MPU
290 * support can alternatively create an MPU constrained task using
291 * xTaskCreateRestricted().
292 *
293 * @param pxTaskCode Pointer to the task entry function. Tasks
294 * must be implemented to never return (i.e. continuous loop).
295 *
296 * @param pcName A descriptive name for the task. This is mainly used to
297 * facilitate debugging. Max length defined by configMAX_TASK_NAME_LEN - default
298 * is 16.
299 *
300 * @param usStackDepth The size of the task stack specified as the number of
301 * variables the stack can hold - not the number of bytes. For example, if
302 * the stack is 16 bits wide and usStackDepth is defined as 100, 200 bytes
303 * will be allocated for stack storage.
304 *
305 * @param pvParameters Pointer that will be used as the parameter for the task
306 * being created.
307 *
308 * @param uxPriority The priority at which the task should run. Systems that
309 * include MPU support can optionally create tasks in a privileged (system)
310 * mode by setting bit portPRIVILEGE_BIT of the priority parameter. For
311 * example, to create a privileged task at priority 2 the uxPriority parameter
312 * should be set to ( 2 | portPRIVILEGE_BIT ).
313 *
314 * @param pxCreatedTask Used to pass back a handle by which the created task
315 * can be referenced.
316 *
317 * @return pdPASS if the task was successfully created and added to a ready
318 * list, otherwise an error code defined in the file projdefs.h
319 *
320 * Example usage:
321 * @code{c}
322 * // Task to be created.
323 * void vTaskCode( void * pvParameters )
324 * {
325 * for( ;; )
326 * {
327 * // Task code goes here.
328 * }
329 * }
330 *
331 * // Function that creates a task.
332 * void vOtherFunction( void )
333 * {
334 * static uint8_t ucParameterToPass;
335 * TaskHandle_t xHandle = NULL;
336 *
337 * // Create the task, storing the handle. Note that the passed parameter ucParameterToPass
338 * // must exist for the lifetime of the task, so in this case is declared static. If it was just an
339 * // an automatic stack variable it might no longer exist, or at least have been corrupted, by the time
340 * // the new task attempts to access it.
341 * xTaskCreate( vTaskCode, "NAME", STACK_SIZE, &ucParameterToPass, tskIDLE_PRIORITY, &xHandle );
342 * configASSERT( xHandle );
343 *
344 * // Use the handle to delete the task.
345 * if( xHandle != NULL )
346 * {
347 * vTaskDelete( xHandle );
348 * }
349 * }
350 * @endcode
351 * \defgroup xTaskCreate xTaskCreate
352 * \ingroup Tasks
353 */
354 #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
355
BaseType_t xTaskCreate( TaskFunction_t pxTaskCode,
356 const char * const
pcName, /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
360
TaskHandle_t * const pxCreatedTask ) PRIVILEGED_FUNCTION;
361 #endif
362
363 /**
364 * task. h
365 * @code{c}
366 * TaskHandle_t xTaskCreateStatic( TaskFunction_t pxTaskCode,
367 * const char *pcName,
368 * uint32_t ulStackDepth,
369 * void *pvParameters,
370 * UBaseType_t uxPriority,
371 * StackType_t *puxStackBuffer,
372 * StaticTask_t *pxTaskBuffer );
373 * @endcode
374 *
375 * Create a new task and add it to the list of tasks that are ready to run.
376 *
377 * Internally, within the FreeRTOS implementation, tasks use two blocks of
378 * memory. The first block is used to hold the task's data structures. The
379 * second block is used by the task as its stack. If a task is created using
380 * xTaskCreate() then both blocks of memory are automatically dynamically
381 * allocated inside the xTaskCreate() function. (see
382 * https://www.FreeRTOS.org/a00111.html). If a task is created using
383 * xTaskCreateStatic() then the application writer must provide the required
384 * memory. xTaskCreateStatic() therefore allows a task to be created without
385 * using any dynamic memory allocation.
386 *
387 * @param pxTaskCode Pointer to the task entry function. Tasks
388 * must be implemented to never return (i.e. continuous loop).
389 *
390 * @param pcName A descriptive name for the task. This is mainly used to
391 * facilitate debugging. The maximum length of the string is defined by
392 * configMAX_TASK_NAME_LEN in FreeRTOSConfig.h.
393 *
394 * @param ulStackDepth The size of the task stack specified as the number of
395 * variables the stack can hold - not the number of bytes. For example, if
396 * the stack is 32-bits wide and ulStackDepth is defined as 100 then 400 bytes
397 * will be allocated for stack storage.
398 *
399 * @param pvParameters Pointer that will be used as the parameter for the task
400 * being created.
401 *
402 * @param uxPriority The priority at which the task will run.
403 *
404 * @param puxStackBuffer Must point to a StackType_t array that has at least
405 * ulStackDepth indexes - the array will then be used as the task's stack,
406 * removing the need for the stack to be allocated dynamically.
407 *
408 * @param pxTaskBuffer Must point to a variable of type StaticTask_t, which will
409 * then be used to hold the task's data structures, removing the need for the
410 * memory to be allocated dynamically.
411 *
412 * @return If neither puxStackBuffer nor pxTaskBuffer are NULL, then the task
413 * will be created and a handle to the created task is returned. If either
414 * puxStackBuffer or pxTaskBuffer are NULL then the task will not be created and
415 * NULL is returned.
416 *
417 * Example usage:
418 * @code{c}
419 *
420 * // Dimensions of the buffer that the task being created will use as its stack.
421 * // NOTE: This is the number of words the stack will hold, not the number of
422 * // bytes. For example, if each stack item is 32-bits, and this is set to 100,
423 * // then 400 bytes (100 * 32-bits) will be allocated.
424 #define STACK_SIZE 200
425 *
426 * // Structure that will hold the TCB of the task being created.
427 * StaticTask_t xTaskBuffer;
428 *
429 * // Buffer that the task being created will use as its stack. Note this is
430 * // an array of StackType_t variables. The size of StackType_t is dependent on
431 * // the RTOS port.
432 * StackType_t xStack[ STACK_SIZE ];
433 *
434 * // Function that implements the task being created.
435 * void vTaskCode( void * pvParameters )
436 * {
437 * // The parameter value is expected to be 1 as 1 is passed in the
438 * // pvParameters value in the call to xTaskCreateStatic().
439 * configASSERT( ( uint32_t ) pvParameters == 1UL );
440 *
441 * for( ;; )
442 * {
443 * // Task code goes here.
444 * }
445 * }
446 *
447 * // Function that creates a task.
448 * void vOtherFunction( void )
449 * {
450 * TaskHandle_t xHandle = NULL;
451 *
452 * // Create the task without using any dynamic memory allocation.
453 * xHandle = xTaskCreateStatic(
454 * vTaskCode, // Function that implements the task.
455 * "NAME", // Text name for the task.
456 * STACK_SIZE, // Stack size in words, not bytes.
457 * ( void * ) 1, // Parameter passed into the task.
458 * tskIDLE_PRIORITY,// Priority at which the task is created.
459 * xStack, // Array to use as the task's stack.
460 * &xTaskBuffer ); // Variable to hold the task's data structure.
461 *
462 * // puxStackBuffer and pxTaskBuffer were not NULL, so the task will have
463 * // been created, and xHandle will be the task's handle. Use the handle
464 * // to suspend the task.
465 * vTaskSuspend( xHandle );
466 * }
467 * @endcode
468 * \defgroup xTaskCreateStatic xTaskCreateStatic
469 * \ingroup Tasks
470 */
471 #if ( configSUPPORT_STATIC_ALLOCATION == 1 )
472
TaskHandle_t xTaskCreateStatic( TaskFunction_t pxTaskCode,
473 const char * const
pcName, /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
474 const uint32_t ulStackDepth,
478 StaticTask_t * const
pxTaskBuffer ) PRIVILEGED_FUNCTION;
479 #endif /* configSUPPORT_STATIC_ALLOCATION */
480
481 /**
482 * task. h
483 * @code{c}
484 * BaseType_t xTaskCreateRestricted( TaskParameters_t *pxTaskDefinition, TaskHandle_t *pxCreatedTask );
485 * @endcode
486 *
487 * Only available when configSUPPORT_DYNAMIC_ALLOCATION is set to 1.
488 *
489 * xTaskCreateRestricted() should only be used in systems that include an MPU
490 * implementation.
491 *
492 * Create a new task and add it to the list of tasks that are ready to run.
493 * The function parameters define the memory regions and associated access
494 * permissions allocated to the task.
495 *
496 * See xTaskCreateRestrictedStatic() for a version that does not use any
497 * dynamic memory allocation.
498 *
499 * @param pxTaskDefinition Pointer to a structure that contains a member
500 * for each of the normal xTaskCreate() parameters (see the xTaskCreate() API
501 * documentation) plus an optional stack buffer and the memory region
502 * definitions.
503 *
504 * @param pxCreatedTask Used to pass back a handle by which the created task
505 * can be referenced.
506 *
507 * @return pdPASS if the task was successfully created and added to a ready
508 * list, otherwise an error code defined in the file projdefs.h
509 *
510 * Example usage:
511 * @code{c}
512 * // Create an TaskParameters_t structure that defines the task to be created.
513 * static const TaskParameters_t xCheckTaskParameters =
514 * {
515 * vATask, // pvTaskCode - the function that implements the task.
516 * "ATask", // pcName - just a text name for the task to assist debugging.
517 * 100, // usStackDepth - the stack size DEFINED IN WORDS.
518 * NULL, // pvParameters - passed into the task function as the function parameters.
519 * ( 1UL | portPRIVILEGE_BIT ),// uxPriority - task priority, set the portPRIVILEGE_BIT if the task should run in a privileged state.
520 * cStackBuffer,// puxStackBuffer - the buffer to be used as the task stack.
521 *
522 * // xRegions - Allocate up to three separate memory regions for access by
523 * // the task, with appropriate access permissions. Different processors have
524 * // different memory alignment requirements - refer to the FreeRTOS documentation
525 * // for full information.
526 * {
527 * // Base address Length Parameters
528 * { cReadWriteArray, 32, portMPU_REGION_READ_WRITE },
529 * { cReadOnlyArray, 32, portMPU_REGION_READ_ONLY },
530 * { cPrivilegedOnlyAccessArray, 128, portMPU_REGION_PRIVILEGED_READ_WRITE }
531 * }
532 * };
533 *
534 * int main( void )
535 * {
536 * TaskHandle_t xHandle;
537 *
538 * // Create a task from the const structure defined above. The task handle
539 * // is requested (the second parameter is not NULL) but in this case just for
540 * // demonstration purposes as its not actually used.
541 * xTaskCreateRestricted( &xRegTest1Parameters, &xHandle );
542 *
543 * // Start the scheduler.
544 * vTaskStartScheduler();
545 *
546 * // Will only get here if there was insufficient memory to create the idle
547 * // and/or timer task.
548 * for( ;; );
549 * }
550 * @endcode
551 * \defgroup xTaskCreateRestricted xTaskCreateRestricted
552 * \ingroup Tasks
553 */
557 #endif
558
559 /**
560 * task. h
561 * @code{c}
562 * BaseType_t xTaskCreateRestrictedStatic( TaskParameters_t *pxTaskDefinition, TaskHandle_t *pxCreatedTask );
563 * @endcode
564 *
565 * Only available when configSUPPORT_STATIC_ALLOCATION is set to 1.
566 *
567 * xTaskCreateRestrictedStatic() should only be used in systems that include an
568 * MPU implementation.
569 *
570 * Internally, within the FreeRTOS implementation, tasks use two blocks of
571 * memory. The first block is used to hold the task's data structures. The
572 * second block is used by the task as its stack. If a task is created using
573 * xTaskCreateRestricted() then the stack is provided by the application writer,
574 * and the memory used to hold the task's data structure is automatically
575 * dynamically allocated inside the xTaskCreateRestricted() function. If a task
576 * is created using xTaskCreateRestrictedStatic() then the application writer
577 * must provide the memory used to hold the task's data structures too.
578 * xTaskCreateRestrictedStatic() therefore allows a memory protected task to be
579 * created without using any dynamic memory allocation.
580 *
581 * @param pxTaskDefinition Pointer to a structure that contains a member
582 * for each of the normal xTaskCreate() parameters (see the xTaskCreate() API
583 * documentation) plus an optional stack buffer and the memory region
584 * definitions. If configSUPPORT_STATIC_ALLOCATION is set to 1 the structure
585 * contains an additional member, which is used to point to a variable of type
586 * StaticTask_t - which is then used to hold the task's data structure.
587 *
588 * @param pxCreatedTask Used to pass back a handle by which the created task
589 * can be referenced.
590 *
591 * @return pdPASS if the task was successfully created and added to a ready
592 * list, otherwise an error code defined in the file projdefs.h
593 *
594 * Example usage:
595 * @code{c}
596 * // Create an TaskParameters_t structure that defines the task to be created.
597 * // The StaticTask_t variable is only included in the structure when
598 * // configSUPPORT_STATIC_ALLOCATION is set to 1. The PRIVILEGED_DATA macro can
599 * // be used to force the variable into the RTOS kernel's privileged data area.
600 * static PRIVILEGED_DATA StaticTask_t xTaskBuffer;
601 * static const TaskParameters_t xCheckTaskParameters =
602 * {
603 * vATask, // pvTaskCode - the function that implements the task.
604 * "ATask", // pcName - just a text name for the task to assist debugging.
605 * 100, // usStackDepth - the stack size DEFINED IN WORDS.
606 * NULL, // pvParameters - passed into the task function as the function parameters.
607 * ( 1UL | portPRIVILEGE_BIT ),// uxPriority - task priority, set the portPRIVILEGE_BIT if the task should run in a privileged state.
608 * cStackBuffer,// puxStackBuffer - the buffer to be used as the task stack.
609 *
610 * // xRegions - Allocate up to three separate memory regions for access by
611 * // the task, with appropriate access permissions. Different processors have
612 * // different memory alignment requirements - refer to the FreeRTOS documentation
613 * // for full information.
614 * {
615 * // Base address Length Parameters
616 * { cReadWriteArray, 32, portMPU_REGION_READ_WRITE },
617 * { cReadOnlyArray, 32, portMPU_REGION_READ_ONLY },
618 * { cPrivilegedOnlyAccessArray, 128, portMPU_REGION_PRIVILEGED_READ_WRITE }
619 * }
620 *
621 * &xTaskBuffer; // Holds the task's data structure.
622 * };
623 *
624 * int main( void )
625 * {
626 * TaskHandle_t xHandle;
627 *
628 * // Create a task from the const structure defined above. The task handle
629 * // is requested (the second parameter is not NULL) but in this case just for
630 * // demonstration purposes as its not actually used.
631 * xTaskCreateRestricted( &xRegTest1Parameters, &xHandle );
632 *
633 * // Start the scheduler.
634 * vTaskStartScheduler();
635 *
636 * // Will only get here if there was insufficient memory to create the idle
637 * // and/or timer task.
638 * for( ;; );
639 * }
640 * @endcode
641 * \defgroup xTaskCreateRestrictedStatic xTaskCreateRestrictedStatic
642 * \ingroup Tasks
643 */
647 #endif
648
649 /**
650 * task. h
651 * @code{c}
652 * void vTaskAllocateMPURegions( TaskHandle_t xTask, const MemoryRegion_t * const pxRegions );
653 * @endcode
654 *
655 * Memory regions are assigned to a restricted task when the task is created by
656 * a call to xTaskCreateRestricted(). These regions can be redefined using
657 * vTaskAllocateMPURegions().
658 *
659 * @param xTask The handle of the task being updated.
660 *
661 * @param xRegions A pointer to a MemoryRegion_t structure that contains the
662 * new memory region definitions.
663 *
664 * Example usage:
665 * @code{c}
666 * // Define an array of MemoryRegion_t structures that configures an MPU region
667 * // allowing read/write access for 1024 bytes starting at the beginning of the
668 * // ucOneKByte array. The other two of the maximum 3 definable regions are
669 * // unused so set to zero.
670 * static const MemoryRegion_t xAltRegions[ portNUM_CONFIGURABLE_REGIONS ] =
671 * {
672 * // Base address Length Parameters
673 * { ucOneKByte, 1024, portMPU_REGION_READ_WRITE },
674 * { 0, 0, 0 },
675 * { 0, 0, 0 }
676 * };
677 *
678 * void vATask( void *pvParameters )
679 * {
680 * // This task was created such that it has access to certain regions of
681 * // memory as defined by the MPU configuration. At some point it is
682 * // desired that these MPU regions are replaced with that defined in the
683 * // xAltRegions const struct above. Use a call to vTaskAllocateMPURegions()
684 * // for this purpose. NULL is used as the task handle to indicate that this
685 * // function should modify the MPU regions of the calling task.
686 * vTaskAllocateMPURegions( NULL, xAltRegions );
687 *
688 * // Now the task can continue its function, but from this point on can only
689 * // access its stack and the ucOneKByte array (unless any other statically
690 * // defined or shared regions have been declared elsewhere).
691 * }
692 * @endcode
693 * \defgroup xTaskCreateRestricted xTaskCreateRestricted
694 * \ingroup Tasks
695 */
698
699 /**
700 * task. h
701 * @code{c}
702 * void vTaskDelete( TaskHandle_t xTaskToDelete );
703 * @endcode
704 *
705 * INCLUDE_vTaskDelete must be defined as 1 for this function to be available.
706 * See the configuration section for more information.
707 *
708 * Remove a task from the RTOS real time kernel's management. The task being
709 * deleted will be removed from all ready, blocked, suspended and event lists.
710 *
711 * NOTE: The idle task is responsible for freeing the kernel allocated
712 * memory from tasks that have been deleted. It is therefore important that
713 * the idle task is not starved of microcontroller processing time if your
714 * application makes any calls to vTaskDelete (). Memory allocated by the
715 * task code is not automatically freed, and should be freed before the task
716 * is deleted.
717 *
718 * See the demo application file death.c for sample code that utilises
719 * vTaskDelete ().
720 *
721 * @param xTaskToDelete The handle of the task to be deleted. Passing NULL will
722 * cause the calling task to be deleted.
723 *
724 * Example usage:
725 * @code{c}
726 * void vOtherFunction( void )
727 * {
728 * TaskHandle_t xHandle;
729 *
730 * // Create the task, storing the handle.
731 * xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
732 *
733 * // Use the handle to delete the task.
734 * vTaskDelete( xHandle );
735 * }
736 * @endcode
737 * \defgroup vTaskDelete vTaskDelete
738 * \ingroup Tasks
739 */
740 void vTaskDelete(
TaskHandle_t xTaskToDelete ) PRIVILEGED_FUNCTION;
741
742 /*-----------------------------------------------------------
743 * TASK CONTROL API
744 *----------------------------------------------------------*/
745
746 /**
747 * task. h
748 * @code{c}
749 * void vTaskDelay( const TickType_t xTicksToDelay );
750 * @endcode
751 *
752 * Delay a task for a given number of ticks. The actual time that the
753 * task remains blocked depends on the tick rate. The constant
754 * portTICK_PERIOD_MS can be used to calculate real time from the tick
755 * rate - with the resolution of one tick period.
756 *
757 * INCLUDE_vTaskDelay must be defined as 1 for this function to be available.
758 * See the configuration section for more information.
759 *
760 *
761 * vTaskDelay() specifies a time at which the task wishes to unblock relative to
762 * the time at which vTaskDelay() is called. For example, specifying a block
763 * period of 100 ticks will cause the task to unblock 100 ticks after
764 * vTaskDelay() is called. vTaskDelay() does not therefore provide a good method
765 * of controlling the frequency of a periodic task as the path taken through the
766 * code, as well as other task and interrupt activity, will affect the frequency
767 * at which vTaskDelay() gets called and therefore the time at which the task
768 * next executes. See xTaskDelayUntil() for an alternative API function designed
769 * to facilitate fixed frequency execution. It does this by specifying an
770 * absolute time (rather than a relative time) at which the calling task should
771 * unblock.
772 *
773 * @param xTicksToDelay The amount of time, in tick periods, that
774 * the calling task should block.
775 *
776 * Example usage:
777 *
778 * void vTaskFunction( void * pvParameters )
779 * {
780 * // Block for 500ms.
781 * const TickType_t xDelay = 500 / portTICK_PERIOD_MS;
782 *
783 * for( ;; )
784 * {
785 * // Simply toggle the LED every 500ms, blocking between each toggle.
786 * vToggleLED();
787 * vTaskDelay( xDelay );
788 * }
789 * }
790 *
791 * \defgroup vTaskDelay vTaskDelay
792 * \ingroup TaskCtrl
793 */
794 void vTaskDelay( const
TickType_t xTicksToDelay ) PRIVILEGED_FUNCTION;
795
796 /**
797 * task. h
798 * @code{c}
799 * BaseType_t xTaskDelayUntil( TickType_t *pxPreviousWakeTime, const TickType_t xTimeIncrement );
800 * @endcode
801 *
802 * INCLUDE_xTaskDelayUntil must be defined as 1 for this function to be available.
803 * See the configuration section for more information.
804 *
805 * Delay a task until a specified time. This function can be used by periodic
806 * tasks to ensure a constant execution frequency.
807 *
808 * This function differs from vTaskDelay () in one important aspect: vTaskDelay () will
809 * cause a task to block for the specified number of ticks from the time vTaskDelay () is
810 * called. It is therefore difficult to use vTaskDelay () by itself to generate a fixed
811 * execution frequency as the time between a task starting to execute and that task
812 * calling vTaskDelay () may not be fixed [the task may take a different path though the
813 * code between calls, or may get interrupted or preempted a different number of times
814 * each time it executes].
815 *
816 * Whereas vTaskDelay () specifies a wake time relative to the time at which the function
817 * is called, xTaskDelayUntil () specifies the absolute (exact) time at which it wishes to
818 * unblock.
819 *
820 * The macro pdMS_TO_TICKS() can be used to calculate the number of ticks from a
821 * time specified in milliseconds with a resolution of one tick period.
822 *
823 * @param pxPreviousWakeTime Pointer to a variable that holds the time at which the
824 * task was last unblocked. The variable must be initialised with the current time
825 * prior to its first use (see the example below). Following this the variable is
826 * automatically updated within xTaskDelayUntil ().
827 *
828 * @param xTimeIncrement The cycle time period. The task will be unblocked at
829 * time *pxPreviousWakeTime + xTimeIncrement. Calling xTaskDelayUntil with the
830 * same xTimeIncrement parameter value will cause the task to execute with
831 * a fixed interface period.
832 *
833 * @return Value which can be used to check whether the task was actually delayed.
834 * Will be pdTRUE if the task way delayed and pdFALSE otherwise. A task will not
835 * be delayed if the next expected wake time is in the past.
836 *
837 * Example usage:
838 * @code{c}
839 * // Perform an action every 10 ticks.
840 * void vTaskFunction( void * pvParameters )
841 * {
842 * TickType_t xLastWakeTime;
843 * const TickType_t xFrequency = 10;
844 * BaseType_t xWasDelayed;
845 *
846 * // Initialise the xLastWakeTime variable with the current time.
847 * xLastWakeTime = xTaskGetTickCount ();
848 * for( ;; )
849 * {
850 * // Wait for the next cycle.
851 * xWasDelayed = xTaskDelayUntil( &xLastWakeTime, xFrequency );
852 *
853 * // Perform action here. xWasDelayed value can be used to determine
854 * // whether a deadline was missed if the code here took too long.
855 * }
856 * }
857 * @endcode
858 * \defgroup xTaskDelayUntil xTaskDelayUntil
859 * \ingroup TaskCtrl
860 */
862 const
TickType_t xTimeIncrement ) PRIVILEGED_FUNCTION;
863
864 /*
865 * vTaskDelayUntil() is the older version of xTaskDelayUntil() and does not
866 * return a value.
867 */
869 { \
870 ( void ) xTaskDelayUntil( pxPreviousWakeTime, xTimeIncrement ); \
871 }
872
873
874 /**
875 * task. h
876 * @code{c}
877 * BaseType_t xTaskAbortDelay( TaskHandle_t xTask );
878 * @endcode
879 *
880 * INCLUDE_xTaskAbortDelay must be defined as 1 in FreeRTOSConfig.h for this
881 * function to be available.
882 *
883 * A task will enter the Blocked state when it is waiting for an event. The
884 * event it is waiting for can be a temporal event (waiting for a time), such
885 * as when vTaskDelay() is called, or an event on an object, such as when
886 * xQueueReceive() or ulTaskNotifyTake() is called. If the handle of a task
887 * that is in the Blocked state is used in a call to xTaskAbortDelay() then the
888 * task will leave the Blocked state, and return from whichever function call
889 * placed the task into the Blocked state.
890 *
891 * There is no 'FromISR' version of this function as an interrupt would need to
892 * know which object a task was blocked on in order to know which actions to
893 * take. For example, if the task was blocked on a queue the interrupt handler
894 * would then need to know if the queue was locked.
895 *
896 * @param xTask The handle of the task to remove from the Blocked state.
897 *
898 * @return If the task referenced by xTask was not in the Blocked state then
899 * pdFAIL is returned. Otherwise pdPASS is returned.
900 *
901 * \defgroup xTaskAbortDelay xTaskAbortDelay
902 * \ingroup TaskCtrl
903 */
905
906 /**
907 * task. h
908 * @code{c}
909 * UBaseType_t uxTaskPriorityGet( const TaskHandle_t xTask );
910 * @endcode
911 *
912 * INCLUDE_uxTaskPriorityGet must be defined as 1 for this function to be available.
913 * See the configuration section for more information.
914 *
915 * Obtain the priority of any task.
916 *
917 * @param xTask Handle of the task to be queried. Passing a NULL
918 * handle results in the priority of the calling task being returned.
919 *
920 * @return The priority of xTask.
921 *
922 * Example usage:
923 * @code{c}
924 * void vAFunction( void )
925 * {
926 * TaskHandle_t xHandle;
927 *
928 * // Create a task, storing the handle.
929 * xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
930 *
931 * // ...
932 *
933 * // Use the handle to obtain the priority of the created task.
934 * // It was created with tskIDLE_PRIORITY, but may have changed
935 * // it itself.
936 * if( uxTaskPriorityGet( xHandle ) != tskIDLE_PRIORITY )
937 * {
938 * // The task has changed it's priority.
939 * }
940 *
941 * // ...
942 *
943 * // Is our priority higher than the created task?
944 * if( uxTaskPriorityGet( xHandle ) < uxTaskPriorityGet( NULL ) )
945 * {
946 * // Our priority (obtained using NULL handle) is higher.
947 * }
948 * }
949 * @endcode
950 * \defgroup uxTaskPriorityGet uxTaskPriorityGet
951 * \ingroup TaskCtrl
952 */
954
955 /**
956 * task. h
957 * @code{c}
958 * UBaseType_t uxTaskPriorityGetFromISR( const TaskHandle_t xTask );
959 * @endcode
960 *
961 * A version of uxTaskPriorityGet() that can be used from an ISR.
962 */
964
965 /**
966 * task. h
967 * @code{c}
968 * eTaskState eTaskGetState( TaskHandle_t xTask );
969 * @endcode
970 *
971 * INCLUDE_eTaskGetState must be defined as 1 for this function to be available.
972 * See the configuration section for more information.
973 *
974 * Obtain the state of any task. States are encoded by the eTaskState
975 * enumerated type.
976 *
977 * @param xTask Handle of the task to be queried.
978 *
979 * @return The state of xTask at the time the function was called. Note the
980 * state of the task might change between the function being called, and the
981 * functions return value being tested by the calling task.
982 */
984
985 /**
986 * task. h
987 * @code{c}
988 * void vTaskGetInfo( TaskHandle_t xTask, TaskStatus_t *pxTaskStatus, BaseType_t xGetFreeStackSpace, eTaskState eState );
989 * @endcode
990 *
991 * configUSE_TRACE_FACILITY must be defined as 1 for this function to be
992 * available. See the configuration section for more information.
993 *
994 * Populates a TaskStatus_t structure with information about a task.
995 *
996 * @param xTask Handle of the task being queried. If xTask is NULL then
997 * information will be returned about the calling task.
998 *
999 * @param pxTaskStatus A pointer to the TaskStatus_t structure that will be
1000 * filled with information about the task referenced by the handle passed using
1001 * the xTask parameter.
1002 *
1003 * @param xGetFreeStackSpace The TaskStatus_t structure contains a member to report
1004 * the stack high water mark of the task being queried. Calculating the stack
1005 * high water mark takes a relatively long time, and can make the system
1006 * temporarily unresponsive - so the xGetFreeStackSpace parameter is provided to
1007 * allow the high water mark checking to be skipped. The high watermark value
1008 * will only be written to the TaskStatus_t structure if xGetFreeStackSpace is
1009 * not set to pdFALSE;
1010 *
1011 * @param eState The TaskStatus_t structure contains a member to report the
1012 * state of the task being queried. Obtaining the task state is not as fast as
1013 * a simple assignment - so the eState parameter is provided to allow the state
1014 * information to be omitted from the TaskStatus_t structure. To obtain state
1015 * information then set eState to eInvalid - otherwise the value passed in
1016 * eState will be reported as the task state in the TaskStatus_t structure.
1017 *
1018 * Example usage:
1019 * @code{c}
1020 * void vAFunction( void )
1021 * {
1022 * TaskHandle_t xHandle;
1023 * TaskStatus_t xTaskDetails;
1024 *
1025 * // Obtain the handle of a task from its name.
1026 * xHandle = xTaskGetHandle( "Task_Name" );
1027 *
1028 * // Check the handle is not NULL.
1029 * configASSERT( xHandle );
1030 *
1031 * // Use the handle to obtain further information about the task.
1032 * vTaskGetInfo( xHandle,
1033 * &xTaskDetails,
1034 * pdTRUE, // Include the high water mark in xTaskDetails.
1035 * eInvalid ); // Include the task state in xTaskDetails.
1036 * }
1037 * @endcode
1038 * \defgroup vTaskGetInfo vTaskGetInfo
1039 * \ingroup TaskCtrl
1040 */
1045
1046 /**
1047 * task. h
1048 * @code{c}
1049 * void vTaskPrioritySet( TaskHandle_t xTask, UBaseType_t uxNewPriority );
1050 * @endcode
1051 *
1052 * INCLUDE_vTaskPrioritySet must be defined as 1 for this function to be available.
1053 * See the configuration section for more information.
1054 *
1055 * Set the priority of any task.
1056 *
1057 * A context switch will occur before the function returns if the priority
1058 * being set is higher than the currently executing task.
1059 *
1060 * @param xTask Handle to the task for which the priority is being set.
1061 * Passing a NULL handle results in the priority of the calling task being set.
1062 *
1063 * @param uxNewPriority The priority to which the task will be set.
1064 *
1065 * Example usage:
1066 * @code{c}
1067 * void vAFunction( void )
1068 * {
1069 * TaskHandle_t xHandle;
1070 *
1071 * // Create a task, storing the handle.
1072 * xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
1073 *
1074 * // ...
1075 *
1076 * // Use the handle to raise the priority of the created task.
1077 * vTaskPrioritySet( xHandle, tskIDLE_PRIORITY + 1 );
1078 *
1079 * // ...
1080 *
1081 * // Use a NULL handle to raise our priority to the same value.
1082 * vTaskPrioritySet( NULL, tskIDLE_PRIORITY + 1 );
1083 * }
1084 * @endcode
1085 * \defgroup vTaskPrioritySet vTaskPrioritySet
1086 * \ingroup TaskCtrl
1087 */
1090
1091 /**
1092 * task. h
1093 * @code{c}
1094 * void vTaskSuspend( TaskHandle_t xTaskToSuspend );
1095 * @endcode
1096 *
1097 * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available.
1098 * See the configuration section for more information.
1099 *
1100 * Suspend any task. When suspended a task will never get any microcontroller
1101 * processing time, no matter what its priority.
1102 *
1103 * Calls to vTaskSuspend are not accumulative -
1104 * i.e. calling vTaskSuspend () twice on the same task still only requires one
1105 * call to vTaskResume () to ready the suspended task.
1106 *
1107 * @param xTaskToSuspend Handle to the task being suspended. Passing a NULL
1108 * handle will cause the calling task to be suspended.
1109 *
1110 * Example usage:
1111 * @code{c}
1112 * void vAFunction( void )
1113 * {
1114 * TaskHandle_t xHandle;
1115 *
1116 * // Create a task, storing the handle.
1117 * xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
1118 *
1119 * // ...
1120 *
1121 * // Use the handle to suspend the created task.
1122 * vTaskSuspend( xHandle );
1123 *
1124 * // ...
1125 *
1126 * // The created task will not run during this period, unless
1127 * // another task calls vTaskResume( xHandle ).
1128 *
1129 * //...
1130 *
1131 *
1132 * // Suspend ourselves.
1133 * vTaskSuspend( NULL );
1134 *
1135 * // We cannot get here unless another task calls vTaskResume
1136 * // with our handle as the parameter.
1137 * }
1138 * @endcode
1139 * \defgroup vTaskSuspend vTaskSuspend
1140 * \ingroup TaskCtrl
1141 */
1142 void vTaskSuspend(
TaskHandle_t xTaskToSuspend ) PRIVILEGED_FUNCTION;
1143
1144 /**
1145 * task. h
1146 * @code{c}
1147 * void vTaskResume( TaskHandle_t xTaskToResume );
1148 * @endcode
1149 *
1150 * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available.
1151 * See the configuration section for more information.
1152 *
1153 * Resumes a suspended task.
1154 *
1155 * A task that has been suspended by one or more calls to vTaskSuspend ()
1156 * will be made available for running again by a single call to
1157 * vTaskResume ().
1158 *
1159 * @param xTaskToResume Handle to the task being readied.
1160 *
1161 * Example usage:
1162 * @code{c}
1163 * void vAFunction( void )
1164 * {
1165 * TaskHandle_t xHandle;
1166 *
1167 * // Create a task, storing the handle.
1168 * xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
1169 *
1170 * // ...
1171 *
1172 * // Use the handle to suspend the created task.
1173 * vTaskSuspend( xHandle );
1174 *
1175 * // ...
1176 *
1177 * // The created task will not run during this period, unless
1178 * // another task calls vTaskResume( xHandle ).
1179 *
1180 * //...
1181 *
1182 *
1183 * // Resume the suspended task ourselves.
1184 * vTaskResume( xHandle );
1185 *
1186 * // The created task will once again get microcontroller processing
1187 * // time in accordance with its priority within the system.
1188 * }
1189 * @endcode
1190 * \defgroup vTaskResume vTaskResume
1191 * \ingroup TaskCtrl
1192 */
1193 void vTaskResume(
TaskHandle_t xTaskToResume ) PRIVILEGED_FUNCTION;
1194
1195 /**
1196 * task. h
1197 * @code{c}
1198 * void xTaskResumeFromISR( TaskHandle_t xTaskToResume );
1199 * @endcode
1200 *
1201 * INCLUDE_xTaskResumeFromISR must be defined as 1 for this function to be
1202 * available. See the configuration section for more information.
1203 *
1204 * An implementation of vTaskResume() that can be called from within an ISR.
1205 *
1206 * A task that has been suspended by one or more calls to vTaskSuspend ()
1207 * will be made available for running again by a single call to
1208 * xTaskResumeFromISR ().
1209 *
1210 * xTaskResumeFromISR() should not be used to synchronise a task with an
1211 * interrupt if there is a chance that the interrupt could arrive prior to the
1212 * task being suspended - as this can lead to interrupts being missed. Use of a
1213 * semaphore as a synchronisation mechanism would avoid this eventuality.
1214 *
1215 * @param xTaskToResume Handle to the task being readied.
1216 *
1217 * @return pdTRUE if resuming the task should result in a context switch,
1218 * otherwise pdFALSE. This is used by the ISR to determine if a context switch
1219 * may be required following the ISR.
1220 *
1221 * \defgroup vTaskResumeFromISR vTaskResumeFromISR
1222 * \ingroup TaskCtrl
1223 */
1225
1226 /*-----------------------------------------------------------
1227 * SCHEDULER CONTROL
1228 *----------------------------------------------------------*/
1229
1230 /**
1231 * task. h
1232 * @code{c}
1233 * void vTaskStartScheduler( void );
1234 * @endcode
1235 *
1236 * Starts the real time kernel tick processing. After calling the kernel
1237 * has control over which tasks are executed and when.
1238 *
1239 * See the demo application file main.c for an example of creating
1240 * tasks and starting the kernel.
1241 *
1242 * Example usage:
1243 * @code{c}
1244 * void vAFunction( void )
1245 * {
1246 * // Create at least one task before starting the kernel.
1247 * xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL );
1248 *
1249 * // Start the real time kernel with preemption.
1250 * vTaskStartScheduler ();
1251 *
1252 * // Will not get here unless a task calls vTaskEndScheduler ()
1253 * }
1254 * @endcode
1255 *
1256 * \defgroup vTaskStartScheduler vTaskStartScheduler
1257 * \ingroup SchedulerControl
1258 */
1259 void vTaskStartScheduler( void ) PRIVILEGED_FUNCTION;
1260
1261 /**
1262 * task. h
1263 * @code{c}
1264 * void vTaskEndScheduler( void );
1265 * @endcode
1266 *
1267 * NOTE: At the time of writing only the x86 real mode port, which runs on a PC
1268 * in place of DOS, implements this function.
1269 *
1270 * Stops the real time kernel tick. All created tasks will be automatically
1271 * deleted and multitasking (either preemptive or cooperative) will
1272 * stop. Execution then resumes from the point where vTaskStartScheduler ()
1273 * was called, as if vTaskStartScheduler () had just returned.
1274 *
1275 * See the demo application file main. c in the demo/PC directory for an
1276 * example that uses vTaskEndScheduler ().
1277 *
1278 * vTaskEndScheduler () requires an exit function to be defined within the
1279 * portable layer (see vPortEndScheduler () in port. c for the PC port). This
1280 * performs hardware specific operations such as stopping the kernel tick.
1281 *
1282 * vTaskEndScheduler () will cause all of the resources allocated by the
1283 * kernel to be freed - but will not free resources allocated by application
1284 * tasks.
1285 *
1286 * Example usage:
1287 * @code{c}
1288 * void vTaskCode( void * pvParameters )
1289 * {
1290 * for( ;; )
1291 * {
1292 * // Task code goes here.
1293 *
1294 * // At some point we want to end the real time kernel processing
1295 * // so call ...
1296 * vTaskEndScheduler ();
1297 * }
1298 * }
1299 *
1300 * void vAFunction( void )
1301 * {
1302 * // Create at least one task before starting the kernel.
1303 * xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL );
1304 *
1305 * // Start the real time kernel with preemption.
1306 * vTaskStartScheduler ();
1307 *
1308 * // Will only get here when the vTaskCode () task has called
1309 * // vTaskEndScheduler (). When we get here we are back to single task
1310 * // execution.
1311 * }
1312 * @endcode
1313 *
1314 * \defgroup vTaskEndScheduler vTaskEndScheduler
1315 * \ingroup SchedulerControl
1316 */
1317 void vTaskEndScheduler( void ) PRIVILEGED_FUNCTION;
1318
1319 /**
1320 * task. h
1321 * @code{c}
1322 * void vTaskSuspendAll( void );
1323 * @endcode
1324 *
1325 * Suspends the scheduler without disabling interrupts. Context switches will
1326 * not occur while the scheduler is suspended.
1327 *
1328 * After calling vTaskSuspendAll () the calling task will continue to execute
1329 * without risk of being swapped out until a call to xTaskResumeAll () has been
1330 * made.
1331 *
1332 * API functions that have the potential to cause a context switch (for example,
1333 * xTaskDelayUntil(), xQueueSend(), etc.) must not be called while the scheduler
1334 * is suspended.
1335 *
1336 * Example usage:
1337 * @code{c}
1338 * void vTask1( void * pvParameters )
1339 * {
1340 * for( ;; )
1341 * {
1342 * // Task code goes here.
1343 *
1344 * // ...
1345 *
1346 * // At some point the task wants to perform a long operation during
1347 * // which it does not want to get swapped out. It cannot use
1348 * // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the
1349 * // operation may cause interrupts to be missed - including the
1350 * // ticks.
1351 *
1352 * // Prevent the real time kernel swapping out the task.
1353 * vTaskSuspendAll ();
1354 *
1355 * // Perform the operation here. There is no need to use critical
1356 * // sections as we have all the microcontroller processing time.
1357 * // During this time interrupts will still operate and the kernel
1358 * // tick count will be maintained.
1359 *
1360 * // ...
1361 *
1362 * // The operation is complete. Restart the kernel.
1363 * xTaskResumeAll ();
1364 * }
1365 * }
1366 * @endcode
1367 * \defgroup vTaskSuspendAll vTaskSuspendAll
1368 * \ingroup SchedulerControl
1369 */
1371
1372 /**
1373 * task. h
1374 * @code{c}
1375 * BaseType_t xTaskResumeAll( void );
1376 * @endcode
1377 *
1378 * Resumes scheduler activity after it was suspended by a call to
1379 * vTaskSuspendAll().
1380 *
1381 * xTaskResumeAll() only resumes the scheduler. It does not unsuspend tasks
1382 * that were previously suspended by a call to vTaskSuspend().
1383 *
1384 * @return If resuming the scheduler caused a context switch then pdTRUE is
1385 * returned, otherwise pdFALSE is returned.
1386 *
1387 * Example usage:
1388 * @code{c}
1389 * void vTask1( void * pvParameters )
1390 * {
1391 * for( ;; )
1392 * {
1393 * // Task code goes here.
1394 *
1395 * // ...
1396 *
1397 * // At some point the task wants to perform a long operation during
1398 * // which it does not want to get swapped out. It cannot use
1399 * // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the
1400 * // operation may cause interrupts to be missed - including the
1401 * // ticks.
1402 *
1403 * // Prevent the real time kernel swapping out the task.
1404 * vTaskSuspendAll ();
1405 *
1406 * // Perform the operation here. There is no need to use critical
1407 * // sections as we have all the microcontroller processing time.
1408 * // During this time interrupts will still operate and the real
1409 * // time kernel tick count will be maintained.
1410 *
1411 * // ...
1412 *
1413 * // The operation is complete. Restart the kernel. We want to force
1414 * // a context switch - but there is no point if resuming the scheduler
1415 * // caused a context switch already.
1416 * if( !xTaskResumeAll () )
1417 * {
1418 * taskYIELD ();
1419 * }
1420 * }
1421 * }
1422 * @endcode
1423 * \defgroup xTaskResumeAll xTaskResumeAll
1424 * \ingroup SchedulerControl
1425 */
1427
1428 /*-----------------------------------------------------------
1429 * TASK UTILITIES
1430 *----------------------------------------------------------*/
1431
1432 /**
1433 * task. h
1434 * @code{c}
1435 * TickType_t xTaskGetTickCount( void );
1436 * @endcode
1437 *
1438 * @return The count of ticks since vTaskStartScheduler was called.
1439 *
1440 * \defgroup xTaskGetTickCount xTaskGetTickCount
1441 * \ingroup TaskUtils
1442 */
1443
TickType_t xTaskGetTickCount( void ) PRIVILEGED_FUNCTION;
1444
1445 /**
1446 * task. h
1447 * @code{c}
1448 * TickType_t xTaskGetTickCountFromISR( void );
1449 * @endcode
1450 *
1451 * @return The count of ticks since vTaskStartScheduler was called.
1452 *
1453 * This is a version of xTaskGetTickCount() that is safe to be called from an
1454 * ISR - provided that TickType_t is the natural word size of the
1455 * microcontroller being used or interrupt nesting is either not supported or
1456 * not being used.
1457 *
1458 * \defgroup xTaskGetTickCountFromISR xTaskGetTickCountFromISR
1459 * \ingroup TaskUtils
1460 */
1461
TickType_t xTaskGetTickCountFromISR( void ) PRIVILEGED_FUNCTION;
1462
1463 /**
1464 * task. h
1465 * @code{c}
1466 * uint16_t uxTaskGetNumberOfTasks( void );
1467 * @endcode
1468 *
1469 * @return The number of tasks that the real time kernel is currently managing.
1470 * This includes all ready, blocked and suspended tasks. A task that
1471 * has been deleted but not yet freed by the idle task will also be
1472 * included in the count.
1473 *
1474 * \defgroup uxTaskGetNumberOfTasks uxTaskGetNumberOfTasks
1475 * \ingroup TaskUtils
1476 */
1477
UBaseType_t uxTaskGetNumberOfTasks( void ) PRIVILEGED_FUNCTION;
1478
1479 /**
1480 * task. h
1481 * @code{c}
1482 * char *pcTaskGetName( TaskHandle_t xTaskToQuery );
1483 * @endcode
1484 *
1485 * @return The text (human readable) name of the task referenced by the handle
1486 * xTaskToQuery. A task can query its own name by either passing in its own
1487 * handle, or by setting xTaskToQuery to NULL.
1488 *
1489 * \defgroup pcTaskGetName pcTaskGetName
1490 * \ingroup TaskUtils
1491 */
1492 char * pcTaskGetName(
TaskHandle_t xTaskToQuery ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
1493
1494 /**
1495 * task. h
1496 * @code{c}
1497 * TaskHandle_t xTaskGetHandle( const char *pcNameToQuery );
1498 * @endcode
1499 *
1500 * NOTE: This function takes a relatively long time to complete and should be
1501 * used sparingly.
1502 *
1503 * @return The handle of the task that has the human readable name pcNameToQuery.
1504 * NULL is returned if no matching name is found. INCLUDE_xTaskGetHandle
1505 * must be set to 1 in FreeRTOSConfig.h for pcTaskGetHandle() to be available.
1506 *
1507 * \defgroup pcTaskGetHandle pcTaskGetHandle
1508 * \ingroup TaskUtils
1509 */
1510
TaskHandle_t xTaskGetHandle( const char * pcNameToQuery ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
1511
1512 /**
1513 * task.h
1514 * @code{c}
1515 * UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask );
1516 * @endcode
1517 *
1518 * INCLUDE_uxTaskGetStackHighWaterMark must be set to 1 in FreeRTOSConfig.h for
1519 * this function to be available.
1520 *
1521 * Returns the high water mark of the stack associated with xTask. That is,
1522 * the minimum free stack space there has been (in words, so on a 32 bit machine
1523 * a value of 1 means 4 bytes) since the task started. The smaller the returned
1524 * number the closer the task has come to overflowing its stack.
1525 *
1526 * uxTaskGetStackHighWaterMark() and uxTaskGetStackHighWaterMark2() are the
1527 * same except for their return type. Using configSTACK_DEPTH_TYPE allows the
1528 * user to determine the return type. It gets around the problem of the value
1529 * overflowing on 8-bit types without breaking backward compatibility for
1530 * applications that expect an 8-bit return type.
1531 *
1532 * @param xTask Handle of the task associated with the stack to be checked.
1533 * Set xTask to NULL to check the stack of the calling task.
1534 *
1535 * @return The smallest amount of free stack space there has been (in words, so
1536 * actual spaces on the stack rather than bytes) since the task referenced by
1537 * xTask was created.
1538 */
1540
1541 /**
1542 * task.h
1543 * @code{c}
1544 * configSTACK_DEPTH_TYPE uxTaskGetStackHighWaterMark2( TaskHandle_t xTask );
1545 * @endcode
1546 *
1547 * INCLUDE_uxTaskGetStackHighWaterMark2 must be set to 1 in FreeRTOSConfig.h for
1548 * this function to be available.
1549 *
1550 * Returns the high water mark of the stack associated with xTask. That is,
1551 * the minimum free stack space there has been (in words, so on a 32 bit machine
1552 * a value of 1 means 4 bytes) since the task started. The smaller the returned
1553 * number the closer the task has come to overflowing its stack.
1554 *
1555 * uxTaskGetStackHighWaterMark() and uxTaskGetStackHighWaterMark2() are the
1556 * same except for their return type. Using configSTACK_DEPTH_TYPE allows the
1557 * user to determine the return type. It gets around the problem of the value
1558 * overflowing on 8-bit types without breaking backward compatibility for
1559 * applications that expect an 8-bit return type.
1560 *
1561 * @param xTask Handle of the task associated with the stack to be checked.
1562 * Set xTask to NULL to check the stack of the calling task.
1563 *
1564 * @return The smallest amount of free stack space there has been (in words, so
1565 * actual spaces on the stack rather than bytes) since the task referenced by
1566 * xTask was created.
1567 */
1568 configSTACK_DEPTH_TYPE uxTaskGetStackHighWaterMark2(
TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
1569
1570 /* When using trace macros it is sometimes necessary to include task.h before
1571 * FreeRTOS.h. When this is done TaskHookFunction_t will not yet have been defined,
1572 * so the following two prototypes will cause a compilation error. This can be
1573 * fixed by simply guarding against the inclusion of these two prototypes unless
1574 * they are explicitly required by the configUSE_APPLICATION_TASK_TAG configuration
1575 * constant. */
1576 #ifdef configUSE_APPLICATION_TASK_TAG
1577 #if configUSE_APPLICATION_TASK_TAG == 1
1578
1579 /**
1580 * task.h
1581 * @code{c}
1582 * void vTaskSetApplicationTaskTag( TaskHandle_t xTask, TaskHookFunction_t pxHookFunction );
1583 * @endcode
1584 *
1585 * Sets pxHookFunction to be the task hook function used by the task xTask.
1586 * Passing xTask as NULL has the effect of setting the calling tasks hook
1587 * function.
1588 */
1591
1592 /**
1593 * task.h
1594 * @code{c}
1595 * void xTaskGetApplicationTaskTag( TaskHandle_t xTask );
1596 * @endcode
1597 *
1598 * Returns the pxHookFunction value assigned to the task xTask. Do not
1599 * call from an interrupt service routine - call
1600 * xTaskGetApplicationTaskTagFromISR() instead.
1601 */
1603
1604 /**
1605 * task.h
1606 * @code{c}
1607 * void xTaskGetApplicationTaskTagFromISR( TaskHandle_t xTask );
1608 * @endcode
1609 *
1610 * Returns the pxHookFunction value assigned to the task xTask. Can
1611 * be called from an interrupt service routine.
1612 */
1614 #endif /* configUSE_APPLICATION_TASK_TAG ==1 */
1615 #endif /* ifdef configUSE_APPLICATION_TASK_TAG */
1616
1617 #if ( configNUM_THREAD_LOCAL_STORAGE_POINTERS > 0 )
1618
1619 /* Each task contains an array of pointers that is dimensioned by the
1620 * configNUM_THREAD_LOCAL_STORAGE_POINTERS setting in FreeRTOSConfig.h. The
1621 * kernel does not use the pointers itself, so the application writer can use
1622 * the pointers for any purpose they wish. The following two functions are
1623 * used to set and query a pointer respectively. */
1624 void vTaskSetThreadLocalStoragePointer(
TaskHandle_t xTaskToSet,
1626 void * pvValue ) PRIVILEGED_FUNCTION;
1627 void * pvTaskGetThreadLocalStoragePointer(
TaskHandle_t xTaskToQuery,
1629
1630 #endif
1631
1632 #if ( configCHECK_FOR_STACK_OVERFLOW > 0 )
1633
1634 /**
1635 * task.h
1636 * @code{c}
1637 * void vApplicationStackOverflowHook( TaskHandle_t xTask char *pcTaskName);
1638 * @endcode
1639 *
1640 * The application stack overflow hook is called when a stack overflow is detected for a task.
1641 *
1642 * Details on stack overflow detection can be found here: https://www.FreeRTOS.org/Stacks-and-stack-overflow-checking.html
1643 *
1644 * @param xTask the task that just exceeded its stack boundaries.
1645 * @param pcTaskName A character string containing the name of the offending task.
1646 */
1647 void vApplicationStackOverflowHook(
TaskHandle_t xTask,
1649
1650 #endif
1651
1652 #if ( configUSE_TICK_HOOK > 0 )
1653
1654 /**
1655 * task.h
1656 * @code{c}
1657 * void vApplicationTickHook( void );
1658 * @endcode
1659 *
1660 * This hook function is called in the system tick handler after any OS work is completed.
1661 */
1662 void vApplicationTickHook( void ); /*lint !e526 Symbol not defined as it is an application callback. */
1663
1664 #endif
1665
1666 #if ( configSUPPORT_STATIC_ALLOCATION == 1 )
1667
1668 /**
1669 * task.h
1670 * @code{c}
1671 * void vApplicationGetIdleTaskMemory( StaticTask_t ** ppxIdleTaskTCBBuffer, StackType_t ** ppxIdleTaskStackBuffer, uint32_t *pulIdleTaskStackSize )
1672 * @endcode
1673 *
1674 * 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
1675 * configSUPPORT_STATIC_ALLOCATION is set. For more information see this URI: https://www.FreeRTOS.org/a00110.html#configSUPPORT_STATIC_ALLOCATION
1676 *
1677 * @param ppxIdleTaskTCBBuffer A handle to a statically allocated TCB buffer
1678 * @param ppxIdleTaskStackBuffer A handle to a statically allocated Stack buffer for the idle task
1679 * @param pulIdleTaskStackSize A pointer to the number of elements that will fit in the allocated stack buffer
1680 */
1681 void vApplicationGetIdleTaskMemory( StaticTask_t ** ppxIdleTaskTCBBuffer,
1683 uint32_t * pulIdleTaskStackSize ); /*lint !e526 Symbol not defined as it is an application callback. */
1684 #endif
1685
1686 /**
1687 * task.h
1688 * @code{c}
1689 * BaseType_t xTaskCallApplicationTaskHook( TaskHandle_t xTask, void *pvParameter );
1690 * @endcode
1691 *
1692 * Calls the hook function associated with xTask. Passing xTask as NULL has
1693 * the effect of calling the Running tasks (the calling task) hook function.
1694 *
1695 * pvParameter is passed to the hook function for the task to interpret as it
1696 * wants. The return value is the value returned by the task hook function
1697 * registered by the user.
1698 */
1700 void * pvParameter ) PRIVILEGED_FUNCTION;
1701
1702 /**
1703 * xTaskGetIdleTaskHandle() is only available if
1704 * INCLUDE_xTaskGetIdleTaskHandle is set to 1 in FreeRTOSConfig.h.
1705 *
1706 * Simply returns the handle of the idle task. It is not valid to call
1707 * xTaskGetIdleTaskHandle() before the scheduler has been started.
1708 */
1709
TaskHandle_t xTaskGetIdleTaskHandle( void ) PRIVILEGED_FUNCTION;
1710
1711 /**
1712 * configUSE_TRACE_FACILITY must be defined as 1 in FreeRTOSConfig.h for
1713 * uxTaskGetSystemState() to be available.
1714 *
1715 * uxTaskGetSystemState() populates an TaskStatus_t structure for each task in
1716 * the system. TaskStatus_t structures contain, among other things, members
1717 * for the task handle, task name, task priority, task state, and total amount
1718 * of run time consumed by the task. See the TaskStatus_t structure
1719 * definition in this file for the full member list.
1720 *
1721 * NOTE: This function is intended for debugging use only as its use results in
1722 * the scheduler remaining suspended for an extended period.
1723 *
1724 * @param pxTaskStatusArray A pointer to an array of TaskStatus_t structures.
1725 * The array must contain at least one TaskStatus_t structure for each task
1726 * that is under the control of the RTOS. The number of tasks under the control
1727 * of the RTOS can be determined using the uxTaskGetNumberOfTasks() API function.
1728 *
1729 * @param uxArraySize The size of the array pointed to by the pxTaskStatusArray
1730 * parameter. The size is specified as the number of indexes in the array, or
1731 * the number of TaskStatus_t structures contained in the array, not by the
1732 * number of bytes in the array.
1733 *
1734 * @param pulTotalRunTime If configGENERATE_RUN_TIME_STATS is set to 1 in
1735 * FreeRTOSConfig.h then *pulTotalRunTime is set by uxTaskGetSystemState() to the
1736 * total run time (as defined by the run time stats clock, see
1737 * https://www.FreeRTOS.org/rtos-run-time-stats.html) since the target booted.
1738 * pulTotalRunTime can be set to NULL to omit the total run time information.
1739 *
1740 * @return The number of TaskStatus_t structures that were populated by
1741 * uxTaskGetSystemState(). This should equal the number returned by the
1742 * uxTaskGetNumberOfTasks() API function, but will be zero if the value passed
1743 * in the uxArraySize parameter was too small.
1744 *
1745 * Example usage:
1746 * @code{c}
1747 * // This example demonstrates how a human readable table of run time stats
1748 * // information is generated from raw data provided by uxTaskGetSystemState().
1749 * // The human readable table is written to pcWriteBuffer
1750 * void vTaskGetRunTimeStats( char *pcWriteBuffer )
1751 * {
1752 * TaskStatus_t *pxTaskStatusArray;
1753 * volatile UBaseType_t uxArraySize, x;
1754 * configRUN_TIME_COUNTER_TYPE ulTotalRunTime, ulStatsAsPercentage;
1755 *
1756 * // Make sure the write buffer does not contain a string.
1757 * pcWriteBuffer = 0x00;
1758 *
1759 * // Take a snapshot of the number of tasks in case it changes while this
1760 * // function is executing.
1761 * uxArraySize = uxTaskGetNumberOfTasks();
1762 *
1763 * // Allocate a TaskStatus_t structure for each task. An array could be
1764 * // allocated statically at compile time.
1765 * pxTaskStatusArray = pvPortMalloc( uxArraySize * sizeof( TaskStatus_t ) );
1766 *
1767 * if( pxTaskStatusArray != NULL )
1768 * {
1769 * // Generate raw status information about each task.
1770 * uxArraySize = uxTaskGetSystemState( pxTaskStatusArray, uxArraySize, &ulTotalRunTime );
1771 *
1772 * // For percentage calculations.
1773 * ulTotalRunTime /= 100UL;
1774 *
1775 * // Avoid divide by zero errors.
1776 * if( ulTotalRunTime > 0 )
1777 * {
1778 * // For each populated position in the pxTaskStatusArray array,
1779 * // format the raw data as human readable ASCII data
1780 * for( x = 0; x < uxArraySize; x++ )
1781 * {
1782 * // What percentage of the total run time has the task used?
1783 * // This will always be rounded down to the nearest integer.
1784 * // ulTotalRunTimeDiv100 has already been divided by 100.
1785 * ulStatsAsPercentage = pxTaskStatusArray[ x ].ulRunTimeCounter / ulTotalRunTime;
1786 *
1787 * if( ulStatsAsPercentage > 0UL )
1788 * {
1789 * sprintf( pcWriteBuffer, "%s\t\t%lu\t\t%lu%%\r\n", pxTaskStatusArray[ x ].pcTaskName, pxTaskStatusArray[ x ].ulRunTimeCounter, ulStatsAsPercentage );
1790 * }
1791 * else
1792 * {
1793 * // If the percentage is zero here then the task has
1794 * // consumed less than 1% of the total run time.
1795 * sprintf( pcWriteBuffer, "%s\t\t%lu\t\t<1%%\r\n", pxTaskStatusArray[ x ].pcTaskName, pxTaskStatusArray[ x ].ulRunTimeCounter );
1796 * }
1797 *
1798 * pcWriteBuffer += strlen( ( char * ) pcWriteBuffer );
1799 * }
1800 * }
1801 *
1802 * // The array is no longer needed, free the memory it consumes.
1803 * vPortFree( pxTaskStatusArray );
1804 * }
1805 * }
1806 * @endcode
1807 */
1810 configRUN_TIME_COUNTER_TYPE * const pulTotalRunTime ) PRIVILEGED_FUNCTION;
1811
1812 /**
1813 * task. h
1814 * @code{c}
1815 * void vTaskList( char *pcWriteBuffer );
1816 * @endcode
1817 *
1818 * configUSE_TRACE_FACILITY and configUSE_STATS_FORMATTING_FUNCTIONS must
1819 * both be defined as 1 for this function to be available. See the
1820 * configuration section of the FreeRTOS.org website for more information.
1821 *
1822 * NOTE 1: This function will disable interrupts for its duration. It is
1823 * not intended for normal application runtime use but as a debug aid.
1824 *
1825 * Lists all the current tasks, along with their current state and stack
1826 * usage high water mark.
1827 *
1828 * Tasks are reported as blocked ('B'), ready ('R'), deleted ('D') or
1829 * suspended ('S').
1830 *
1831 * PLEASE NOTE:
1832 *
1833 * This function is provided for convenience only, and is used by many of the
1834 * demo applications. Do not consider it to be part of the scheduler.
1835 *
1836 * vTaskList() calls uxTaskGetSystemState(), then formats part of the
1837 * uxTaskGetSystemState() output into a human readable table that displays task:
1838 * names, states, priority, stack usage and task number.
1839 * Stack usage specified as the number of unused StackType_t words stack can hold
1840 * on top of stack - not the number of bytes.
1841 *
1842 * vTaskList() has a dependency on the sprintf() C library function that might
1843 * bloat the code size, use a lot of stack, and provide different results on
1844 * different platforms. An alternative, tiny, third party, and limited
1845 * functionality implementation of sprintf() is provided in many of the
1846 * FreeRTOS/Demo sub-directories in a file called printf-stdarg.c (note
1847 * printf-stdarg.c does not provide a full snprintf() implementation!).
1848 *
1849 * It is recommended that production systems call uxTaskGetSystemState()
1850 * directly to get access to raw stats data, rather than indirectly through a
1851 * call to vTaskList().
1852 *
1853 * @param pcWriteBuffer A buffer into which the above mentioned details
1854 * will be written, in ASCII form. This buffer is assumed to be large
1855 * enough to contain the generated report. Approximately 40 bytes per
1856 * task should be sufficient.
1857 *
1858 * \defgroup vTaskList vTaskList
1859 * \ingroup TaskUtils
1860 */
1861 void vTaskList( char * pcWriteBuffer ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
1862
1863 /**
1864 * task. h
1865 * @code{c}
1866 * void vTaskGetRunTimeStats( char *pcWriteBuffer );
1867 * @endcode
1868 *
1869 * configGENERATE_RUN_TIME_STATS and configUSE_STATS_FORMATTING_FUNCTIONS
1870 * must both be defined as 1 for this function to be available. The application
1871 * must also then provide definitions for
1872 * portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and portGET_RUN_TIME_COUNTER_VALUE()
1873 * to configure a peripheral timer/counter and return the timers current count
1874 * value respectively. The counter should be at least 10 times the frequency of
1875 * the tick count.
1876 *
1877 * NOTE 1: This function will disable interrupts for its duration. It is
1878 * not intended for normal application runtime use but as a debug aid.
1879 *
1880 * Setting configGENERATE_RUN_TIME_STATS to 1 will result in a total
1881 * accumulated execution time being stored for each task. The resolution
1882 * of the accumulated time value depends on the frequency of the timer
1883 * configured by the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() macro.
1884 * Calling vTaskGetRunTimeStats() writes the total execution time of each
1885 * task into a buffer, both as an absolute count value and as a percentage
1886 * of the total system execution time.
1887 *
1888 * NOTE 2:
1889 *
1890 * This function is provided for convenience only, and is used by many of the
1891 * demo applications. Do not consider it to be part of the scheduler.
1892 *
1893 * vTaskGetRunTimeStats() calls uxTaskGetSystemState(), then formats part of the
1894 * uxTaskGetSystemState() output into a human readable table that displays the
1895 * amount of time each task has spent in the Running state in both absolute and
1896 * percentage terms.
1897 *
1898 * vTaskGetRunTimeStats() has a dependency on the sprintf() C library function
1899 * that might bloat the code size, use a lot of stack, and provide different
1900 * results on different platforms. An alternative, tiny, third party, and
1901 * limited functionality implementation of sprintf() is provided in many of the
1902 * FreeRTOS/Demo sub-directories in a file called printf-stdarg.c (note
1903 * printf-stdarg.c does not provide a full snprintf() implementation!).
1904 *
1905 * It is recommended that production systems call uxTaskGetSystemState() directly
1906 * to get access to raw stats data, rather than indirectly through a call to
1907 * vTaskGetRunTimeStats().
1908 *
1909 * @param pcWriteBuffer A buffer into which the execution times will be
1910 * written, in ASCII form. This buffer is assumed to be large enough to
1911 * contain the generated report. Approximately 40 bytes per task should
1912 * be sufficient.
1913 *
1914 * \defgroup vTaskGetRunTimeStats vTaskGetRunTimeStats
1915 * \ingroup TaskUtils
1916 */
1917 void vTaskGetRunTimeStats( char * pcWriteBuffer ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
1918
1919 /**
1920 * task. h
1921 * @code{c}
1922 * configRUN_TIME_COUNTER_TYPE ulTaskGetIdleRunTimeCounter( void );
1923 * configRUN_TIME_COUNTER_TYPE ulTaskGetIdleRunTimePercent( void );
1924 * @endcode
1925 *
1926 * configGENERATE_RUN_TIME_STATS, configUSE_STATS_FORMATTING_FUNCTIONS and
1927 * INCLUDE_xTaskGetIdleTaskHandle must all be defined as 1 for these functions
1928 * to be available. The application must also then provide definitions for
1929 * portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and portGET_RUN_TIME_COUNTER_VALUE()
1930 * to configure a peripheral timer/counter and return the timers current count
1931 * value respectively. The counter should be at least 10 times the frequency of
1932 * the tick count.
1933 *
1934 * Setting configGENERATE_RUN_TIME_STATS to 1 will result in a total
1935 * accumulated execution time being stored for each task. The resolution
1936 * of the accumulated time value depends on the frequency of the timer
1937 * configured by the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() macro.
1938 * While uxTaskGetSystemState() and vTaskGetRunTimeStats() writes the total
1939 * execution time of each task into a buffer, ulTaskGetIdleRunTimeCounter()
1940 * returns the total execution time of just the idle task and
1941 * ulTaskGetIdleRunTimePercent() returns the percentage of the CPU time used by
1942 * just the idle task.
1943 *
1944 * Note the amount of idle time is only a good measure of the slack time in a
1945 * system if there are no other tasks executing at the idle priority, tickless
1946 * idle is not used, and configIDLE_SHOULD_YIELD is set to 0.
1947 *
1948 * @return The total run time of the idle task or the percentage of the total
1949 * run time consumed by the idle task. This is the amount of time the
1950 * idle task has actually been executing. The unit of time is dependent on the
1951 * frequency configured using the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and
1952 * portGET_RUN_TIME_COUNTER_VALUE() macros.
1953 *
1954 * \defgroup ulTaskGetIdleRunTimeCounter ulTaskGetIdleRunTimeCounter
1955 * \ingroup TaskUtils
1956 */
1957 configRUN_TIME_COUNTER_TYPE ulTaskGetIdleRunTimeCounter( void ) PRIVILEGED_FUNCTION;
1958 configRUN_TIME_COUNTER_TYPE ulTaskGetIdleRunTimePercent( void ) PRIVILEGED_FUNCTION;
1959
1960 /**
1961 * task. h
1962 * @code{c}
1963 * BaseType_t xTaskNotifyIndexed( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction );
1964 * BaseType_t xTaskNotify( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction );
1965 * @endcode
1966 *
1967 * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
1968 *
1969 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these
1970 * functions to be available.
1971 *
1972 * Sends a direct to task notification to a task, with an optional value and
1973 * action.
1974 *
1975 * Each task has a private array of "notification values" (or 'notifications'),
1976 * each of which is a 32-bit unsigned integer (uint32_t). The constant
1977 * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
1978 * array, and (for backward compatibility) defaults to 1 if left undefined.
1979 * Prior to FreeRTOS V10.4.0 there was only one notification value per task.
1980 *
1981 * Events can be sent to a task using an intermediary object. Examples of such
1982 * objects are queues, semaphores, mutexes and event groups. Task notifications
1983 * are a method of sending an event directly to a task without the need for such
1984 * an intermediary object.
1985 *
1986 * A notification sent to a task can optionally perform an action, such as
1987 * update, overwrite or increment one of the task's notification values. In
1988 * that way task notifications can be used to send data to a task, or be used as
1989 * light weight and fast binary or counting semaphores.
1990 *
1991 * A task can use xTaskNotifyWaitIndexed() or ulTaskNotifyTakeIndexed() to
1992 * [optionally] block to wait for a notification to be pending. The task does
1993 * not consume any CPU time while it is in the Blocked state.
1994 *
1995 * A notification sent to a task will remain pending until it is cleared by the
1996 * task calling xTaskNotifyWaitIndexed() or ulTaskNotifyTakeIndexed() (or their
1997 * un-indexed equivalents). If the task was already in the Blocked state to
1998 * wait for a notification when the notification arrives then the task will
1999 * automatically be removed from the Blocked state (unblocked) and the
2000 * notification cleared.
2001 *
2002 * **NOTE** Each notification within the array operates independently - a task
2003 * can only block on one notification within the array at a time and will not be
2004 * unblocked by a notification sent to any other array index.
2005 *
2006 * Backward compatibility information:
2007 * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
2008 * all task notification API functions operated on that value. Replacing the
2009 * single notification value with an array of notification values necessitated a
2010 * new set of API functions that could address specific notifications within the
2011 * array. xTaskNotify() is the original API function, and remains backward
2012 * compatible by always operating on the notification value at index 0 in the
2013 * array. Calling xTaskNotify() is equivalent to calling xTaskNotifyIndexed()
2014 * with the uxIndexToNotify parameter set to 0.
2015 *
2016 * @param xTaskToNotify The handle of the task being notified. The handle to a
2017 * task can be returned from the xTaskCreate() API function used to create the
2018 * task, and the handle of the currently running task can be obtained by calling
2019 * xTaskGetCurrentTaskHandle().
2020 *
2021 * @param uxIndexToNotify The index within the target task's array of
2022 * notification values to which the notification is to be sent. uxIndexToNotify
2023 * must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotify() does
2024 * not have this parameter and always sends notifications to index 0.
2025 *
2026 * @param ulValue Data that can be sent with the notification. How the data is
2027 * used depends on the value of the eAction parameter.
2028 *
2029 * @param eAction Specifies how the notification updates the task's notification
2030 * value, if at all. Valid values for eAction are as follows:
2031 *
2032 * eSetBits -
2033 * The target notification value is bitwise ORed with ulValue.
2034 * xTaskNotifyIndexed() always returns pdPASS in this case.
2035 *
2036 * eIncrement -
2037 * The target notification value is incremented. ulValue is not used and
2038 * xTaskNotifyIndexed() always returns pdPASS in this case.
2039 *
2040 * eSetValueWithOverwrite -
2041 * The target notification value is set to the value of ulValue, even if the
2042 * task being notified had not yet processed the previous notification at the
2043 * same array index (the task already had a notification pending at that index).
2044 * xTaskNotifyIndexed() always returns pdPASS in this case.
2045 *
2046 * eSetValueWithoutOverwrite -
2047 * If the task being notified did not already have a notification pending at the
2048 * same array index then the target notification value is set to ulValue and
2049 * xTaskNotifyIndexed() will return pdPASS. If the task being notified already
2050 * had a notification pending at the same array index then no action is
2051 * performed and pdFAIL is returned.
2052 *
2053 * eNoAction -
2054 * The task receives a notification at the specified array index without the
2055 * notification value at that index being updated. ulValue is not used and
2056 * xTaskNotifyIndexed() always returns pdPASS in this case.
2057 *
2058 * pulPreviousNotificationValue -
2059 * Can be used to pass out the subject task's notification value before any
2060 * bits are modified by the notify function.
2061 *
2062 * @return Dependent on the value of eAction. See the description of the
2063 * eAction parameter.
2064 *
2065 * \defgroup xTaskNotifyIndexed xTaskNotifyIndexed
2066 * \ingroup TaskNotifications
2067 */
2070 uint32_t ulValue,
2072 uint32_t * pulPreviousNotificationValue ) PRIVILEGED_FUNCTION;
2073 #define
xTaskNotify( xTaskToNotify, ulValue, eAction ) \
2076 xTaskGenericNotify( ( xTaskToNotify ), ( uxIndexToNotify ), ( ulValue ), ( eAction ), NULL )
2077
2078 /**
2079 * task. h
2080 * @code{c}
2081 * BaseType_t xTaskNotifyAndQueryIndexed( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotifyValue );
2082 * BaseType_t xTaskNotifyAndQuery( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotifyValue );
2083 * @endcode
2084 *
2085 * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
2086 *
2087 * xTaskNotifyAndQueryIndexed() performs the same operation as
2088 * xTaskNotifyIndexed() with the addition that it also returns the subject
2089 * task's prior notification value (the notification value at the time the
2090 * function is called rather than when the function returns) in the additional
2091 * pulPreviousNotifyValue parameter.
2092 *
2093 * xTaskNotifyAndQuery() performs the same operation as xTaskNotify() with the
2094 * addition that it also returns the subject task's prior notification value
2095 * (the notification value as it was at the time the function is called, rather
2096 * than when the function returns) in the additional pulPreviousNotifyValue
2097 * parameter.
2098 *
2099 * \defgroup xTaskNotifyAndQueryIndexed xTaskNotifyAndQueryIndexed
2100 * \ingroup TaskNotifications
2101 */
2103 xTaskGenericNotify( ( xTaskToNotify ), (
tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), ( pulPreviousNotifyValue ) )
2105 xTaskGenericNotify( ( xTaskToNotify ), ( uxIndexToNotify ), ( ulValue ), ( eAction ), ( pulPreviousNotifyValue ) )
2106
2107 /**
2108 * task. h
2109 * @code{c}
2110 * BaseType_t xTaskNotifyIndexedFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, BaseType_t *pxHigherPriorityTaskWoken );
2111 * BaseType_t xTaskNotifyFromISR( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, BaseType_t *pxHigherPriorityTaskWoken );
2112 * @endcode
2113 *
2114 * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
2115 *
2116 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these
2117 * functions to be available.
2118 *
2119 * A version of xTaskNotifyIndexed() that can be used from an interrupt service
2120 * routine (ISR).
2121 *
2122 * Each task has a private array of "notification values" (or 'notifications'),
2123 * each of which is a 32-bit unsigned integer (uint32_t). The constant
2124 * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
2125 * array, and (for backward compatibility) defaults to 1 if left undefined.
2126 * Prior to FreeRTOS V10.4.0 there was only one notification value per task.
2127 *
2128 * Events can be sent to a task using an intermediary object. Examples of such
2129 * objects are queues, semaphores, mutexes and event groups. Task notifications
2130 * are a method of sending an event directly to a task without the need for such
2131 * an intermediary object.
2132 *
2133 * A notification sent to a task can optionally perform an action, such as
2134 * update, overwrite or increment one of the task's notification values. In
2135 * that way task notifications can be used to send data to a task, or be used as
2136 * light weight and fast binary or counting semaphores.
2137 *
2138 * A task can use xTaskNotifyWaitIndexed() to [optionally] block to wait for a
2139 * notification to be pending, or ulTaskNotifyTakeIndexed() to [optionally] block
2140 * to wait for a notification value to have a non-zero value. The task does
2141 * not consume any CPU time while it is in the Blocked state.
2142 *
2143 * A notification sent to a task will remain pending until it is cleared by the
2144 * task calling xTaskNotifyWaitIndexed() or ulTaskNotifyTakeIndexed() (or their
2145 * un-indexed equivalents). If the task was already in the Blocked state to
2146 * wait for a notification when the notification arrives then the task will
2147 * automatically be removed from the Blocked state (unblocked) and the
2148 * notification cleared.
2149 *
2150 * **NOTE** Each notification within the array operates independently - a task
2151 * can only block on one notification within the array at a time and will not be
2152 * unblocked by a notification sent to any other array index.
2153 *
2154 * Backward compatibility information:
2155 * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
2156 * all task notification API functions operated on that value. Replacing the
2157 * single notification value with an array of notification values necessitated a
2158 * new set of API functions that could address specific notifications within the
2159 * array. xTaskNotifyFromISR() is the original API function, and remains
2160 * backward compatible by always operating on the notification value at index 0
2161 * within the array. Calling xTaskNotifyFromISR() is equivalent to calling
2162 * xTaskNotifyIndexedFromISR() with the uxIndexToNotify parameter set to 0.
2163 *
2164 * @param uxIndexToNotify The index within the target task's array of
2165 * notification values to which the notification is to be sent. uxIndexToNotify
2166 * must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyFromISR()
2167 * does not have this parameter and always sends notifications to index 0.
2168 *
2169 * @param xTaskToNotify The handle of the task being notified. The handle to a
2170 * task can be returned from the xTaskCreate() API function used to create the
2171 * task, and the handle of the currently running task can be obtained by calling
2172 * xTaskGetCurrentTaskHandle().
2173 *
2174 * @param ulValue Data that can be sent with the notification. How the data is
2175 * used depends on the value of the eAction parameter.
2176 *
2177 * @param eAction Specifies how the notification updates the task's notification
2178 * value, if at all. Valid values for eAction are as follows:
2179 *
2180 * eSetBits -
2181 * The task's notification value is bitwise ORed with ulValue. xTaskNotify()
2182 * always returns pdPASS in this case.
2183 *
2184 * eIncrement -
2185 * The task's notification value is incremented. ulValue is not used and
2186 * xTaskNotify() always returns pdPASS in this case.
2187 *
2188 * eSetValueWithOverwrite -
2189 * The task's notification value is set to the value of ulValue, even if the
2190 * task being notified had not yet processed the previous notification (the
2191 * task already had a notification pending). xTaskNotify() always returns
2192 * pdPASS in this case.
2193 *
2194 * eSetValueWithoutOverwrite -
2195 * If the task being notified did not already have a notification pending then
2196 * the task's notification value is set to ulValue and xTaskNotify() will
2197 * return pdPASS. If the task being notified already had a notification
2198 * pending then no action is performed and pdFAIL is returned.
2199 *
2200 * eNoAction -
2201 * The task receives a notification without its notification value being
2202 * updated. ulValue is not used and xTaskNotify() always returns pdPASS in
2203 * this case.
2204 *
2205 * @param pxHigherPriorityTaskWoken xTaskNotifyFromISR() will set
2206 * *pxHigherPriorityTaskWoken to pdTRUE if sending the notification caused the
2207 * task to which the notification was sent to leave the Blocked state, and the
2208 * unblocked task has a priority higher than the currently running task. If
2209 * xTaskNotifyFromISR() sets this value to pdTRUE then a context switch should
2210 * be requested before the interrupt is exited. How a context switch is
2211 * requested from an ISR is dependent on the port - see the documentation page
2212 * for the port in use.
2213 *
2214 * @return Dependent on the value of eAction. See the description of the
2215 * eAction parameter.
2216 *
2217 * \defgroup xTaskNotifyIndexedFromISR xTaskNotifyIndexedFromISR
2218 * \ingroup TaskNotifications
2219 */
2222 uint32_t ulValue,
2224 uint32_t * pulPreviousNotificationValue,
2225
BaseType_t * pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
2226 #define
xTaskNotifyFromISR( xTaskToNotify, ulValue, eAction, pxHigherPriorityTaskWoken ) \
2227 xTaskGenericNotifyFromISR( ( xTaskToNotify ), (
tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), NULL, ( pxHigherPriorityTaskWoken ) )
2229 xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( uxIndexToNotify ), ( ulValue ), ( eAction ), NULL, ( pxHigherPriorityTaskWoken ) )
2230
2231 /**
2232 * task. h
2233 * @code{c}
2234 * BaseType_t xTaskNotifyAndQueryIndexedFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue, BaseType_t *pxHigherPriorityTaskWoken );
2235 * BaseType_t xTaskNotifyAndQueryFromISR( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue, BaseType_t *pxHigherPriorityTaskWoken );
2236 * @endcode
2237 *
2238 * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
2239 *
2240 * xTaskNotifyAndQueryIndexedFromISR() performs the same operation as
2241 * xTaskNotifyIndexedFromISR() with the addition that it also returns the
2242 * subject task's prior notification value (the notification value at the time
2243 * the function is called rather than at the time the function returns) in the
2244 * additional pulPreviousNotifyValue parameter.
2245 *
2246 * xTaskNotifyAndQueryFromISR() performs the same operation as
2247 * xTaskNotifyFromISR() with the addition that it also returns the subject
2248 * task's prior notification value (the notification value at the time the
2249 * function is called rather than at the time the function returns) in the
2250 * additional pulPreviousNotifyValue parameter.
2251 *
2252 * \defgroup xTaskNotifyAndQueryIndexedFromISR xTaskNotifyAndQueryIndexedFromISR
2253 * \ingroup TaskNotifications
2254 */
2256 xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( uxIndexToNotify ), ( ulValue ), ( eAction ), ( pulPreviousNotificationValue ), ( pxHigherPriorityTaskWoken ) )
2257 #define
xTaskNotifyAndQueryFromISR( xTaskToNotify, ulValue, eAction, pulPreviousNotificationValue, pxHigherPriorityTaskWoken ) \
2258 xTaskGenericNotifyFromISR( ( xTaskToNotify ), (
tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), ( pulPreviousNotificationValue ), ( pxHigherPriorityTaskWoken ) )
2259
2260 /**
2261 * task. h
2262 * @code{c}
2263 * BaseType_t xTaskNotifyWaitIndexed( UBaseType_t uxIndexToWaitOn, uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait );
2264 *
2265 * BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait );
2266 * @endcode
2267 *
2268 * Waits for a direct to task notification to be pending at a given index within
2269 * an array of direct to task notifications.
2270 *
2271 * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
2272 *
2273 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this
2274 * function to be available.
2275 *
2276 * Each task has a private array of "notification values" (or 'notifications'),
2277 * each of which is a 32-bit unsigned integer (uint32_t). The constant
2278 * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
2279 * array, and (for backward compatibility) defaults to 1 if left undefined.
2280 * Prior to FreeRTOS V10.4.0 there was only one notification value per task.
2281 *
2282 * Events can be sent to a task using an intermediary object. Examples of such
2283 * objects are queues, semaphores, mutexes and event groups. Task notifications
2284 * are a method of sending an event directly to a task without the need for such
2285 * an intermediary object.
2286 *
2287 * A notification sent to a task can optionally perform an action, such as
2288 * update, overwrite or increment one of the task's notification values. In
2289 * that way task notifications can be used to send data to a task, or be used as
2290 * light weight and fast binary or counting semaphores.
2291 *
2292 * A notification sent to a task will remain pending until it is cleared by the
2293 * task calling xTaskNotifyWaitIndexed() or ulTaskNotifyTakeIndexed() (or their
2294 * un-indexed equivalents). If the task was already in the Blocked state to
2295 * wait for a notification when the notification arrives then the task will
2296 * automatically be removed from the Blocked state (unblocked) and the
2297 * notification cleared.
2298 *
2299 * A task can use xTaskNotifyWaitIndexed() to [optionally] block to wait for a
2300 * notification to be pending, or ulTaskNotifyTakeIndexed() to [optionally] block
2301 * to wait for a notification value to have a non-zero value. The task does
2302 * not consume any CPU time while it is in the Blocked state.
2303 *
2304 * **NOTE** Each notification within the array operates independently - a task
2305 * can only block on one notification within the array at a time and will not be
2306 * unblocked by a notification sent to any other array index.
2307 *
2308 * Backward compatibility information:
2309 * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
2310 * all task notification API functions operated on that value. Replacing the
2311 * single notification value with an array of notification values necessitated a
2312 * new set of API functions that could address specific notifications within the
2313 * array. xTaskNotifyWait() is the original API function, and remains backward
2314 * compatible by always operating on the notification value at index 0 in the
2315 * array. Calling xTaskNotifyWait() is equivalent to calling
2316 * xTaskNotifyWaitIndexed() with the uxIndexToWaitOn parameter set to 0.
2317 *
2318 * @param uxIndexToWaitOn The index within the calling task's array of
2319 * notification values on which the calling task will wait for a notification to
2320 * be received. uxIndexToWaitOn must be less than
2321 * configTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyWait() does
2322 * not have this parameter and always waits for notifications on index 0.
2323 *
2324 * @param ulBitsToClearOnEntry Bits that are set in ulBitsToClearOnEntry value
2325 * will be cleared in the calling task's notification value before the task
2326 * checks to see if any notifications are pending, and optionally blocks if no
2327 * notifications are pending. Setting ulBitsToClearOnEntry to ULONG_MAX (if
2328 * limits.h is included) or 0xffffffffUL (if limits.h is not included) will have
2329 * the effect of resetting the task's notification value to 0. Setting
2330 * ulBitsToClearOnEntry to 0 will leave the task's notification value unchanged.
2331 *
2332 * @param ulBitsToClearOnExit If a notification is pending or received before
2333 * the calling task exits the xTaskNotifyWait() function then the task's
2334 * notification value (see the xTaskNotify() API function) is passed out using
2335 * the pulNotificationValue parameter. Then any bits that are set in
2336 * ulBitsToClearOnExit will be cleared in the task's notification value (note
2337 * *pulNotificationValue is set before any bits are cleared). Setting
2338 * ulBitsToClearOnExit to ULONG_MAX (if limits.h is included) or 0xffffffffUL
2339 * (if limits.h is not included) will have the effect of resetting the task's
2340 * notification value to 0 before the function exits. Setting
2341 * ulBitsToClearOnExit to 0 will leave the task's notification value unchanged
2342 * when the function exits (in which case the value passed out in
2343 * pulNotificationValue will match the task's notification value).
2344 *
2345 * @param pulNotificationValue Used to pass the task's notification value out
2346 * of the function. Note the value passed out will not be effected by the
2347 * clearing of any bits caused by ulBitsToClearOnExit being non-zero.
2348 *
2349 * @param xTicksToWait The maximum amount of time that the task should wait in
2350 * the Blocked state for a notification to be received, should a notification
2351 * not already be pending when xTaskNotifyWait() was called. The task
2352 * will not consume any processing time while it is in the Blocked state. This
2353 * is specified in kernel ticks, the macro pdMS_TO_TICKS( value_in_ms ) can be
2354 * used to convert a time specified in milliseconds to a time specified in
2355 * ticks.
2356 *
2357 * @return If a notification was received (including notifications that were
2358 * already pending when xTaskNotifyWait was called) then pdPASS is
2359 * returned. Otherwise pdFAIL is returned.
2360 *
2361 * \defgroup xTaskNotifyWaitIndexed xTaskNotifyWaitIndexed
2362 * \ingroup TaskNotifications
2363 */
2365 uint32_t ulBitsToClearOnEntry,
2366 uint32_t ulBitsToClearOnExit,
2367 uint32_t * pulNotificationValue,
2368
TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
2369 #define
xTaskNotifyWait( ulBitsToClearOnEntry, ulBitsToClearOnExit, pulNotificationValue, xTicksToWait ) \
2370 xTaskGenericNotifyWait(
tskDEFAULT_INDEX_TO_NOTIFY, ( ulBitsToClearOnEntry ), ( ulBitsToClearOnExit ), ( pulNotificationValue ), ( xTicksToWait ) )
2371 #define
xTaskNotifyWaitIndexed( uxIndexToWaitOn, ulBitsToClearOnEntry, ulBitsToClearOnExit, pulNotificationValue, xTicksToWait ) \
2372 xTaskGenericNotifyWait( ( uxIndexToWaitOn ), ( ulBitsToClearOnEntry ), ( ulBitsToClearOnExit ), ( pulNotificationValue ), ( xTicksToWait ) )
2373
2374 /**
2375 * task. h
2376 * @code{c}
2377 * BaseType_t xTaskNotifyGiveIndexed( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify );
2378 * BaseType_t xTaskNotifyGive( TaskHandle_t xTaskToNotify );
2379 * @endcode
2380 *
2381 * Sends a direct to task notification to a particular index in the target
2382 * task's notification array in a manner similar to giving a counting semaphore.
2383 *
2384 * See https://www.FreeRTOS.org/RTOS-task-notifications.html for more details.
2385 *
2386 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these
2387 * macros to be available.
2388 *
2389 * Each task has a private array of "notification values" (or 'notifications'),
2390 * each of which is a 32-bit unsigned integer (uint32_t). The constant
2391 * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
2392 * array, and (for backward compatibility) defaults to 1 if left undefined.
2393 * Prior to FreeRTOS V10.4.0 there was only one notification value per task.
2394 *
2395 * Events can be sent to a task using an intermediary object. Examples of such
2396 * objects are queues, semaphores, mutexes and event groups. Task notifications
2397 * are a method of sending an event directly to a task without the need for such
2398 * an intermediary object.
2399 *
2400 * A notification sent to a task can optionally perform an action, such as
2401 * update, overwrite or increment one of the task's notification values. In
2402 * that way task notifications can be used to send data to a task, or be used as
2403 * light weight and fast binary or counting semaphores.
2404 *
2405 * xTaskNotifyGiveIndexed() is a helper macro intended for use when task
2406 * notifications are used as light weight and faster binary or counting
2407 * semaphore equivalents. Actual FreeRTOS semaphores are given using the
2408 * xSemaphoreGive() API function, the equivalent action that instead uses a task
2409 * notification is xTaskNotifyGiveIndexed().
2410 *
2411 * When task notifications are being used as a binary or counting semaphore
2412 * equivalent then the task being notified should wait for the notification
2413 * using the ulTaskNotifyTakeIndexed() API function rather than the
2414 * xTaskNotifyWaitIndexed() API function.
2415 *
2416 * **NOTE** Each notification within the array operates independently - a task
2417 * can only block on one notification within the array at a time and will not be
2418 * unblocked by a notification sent to any other array index.
2419 *
2420 * Backward compatibility information:
2421 * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
2422 * all task notification API functions operated on that value. Replacing the
2423 * single notification value with an array of notification values necessitated a
2424 * new set of API functions that could address specific notifications within the
2425 * array. xTaskNotifyGive() is the original API function, and remains backward
2426 * compatible by always operating on the notification value at index 0 in the
2427 * array. Calling xTaskNotifyGive() is equivalent to calling
2428 * xTaskNotifyGiveIndexed() with the uxIndexToNotify parameter set to 0.
2429 *
2430 * @param xTaskToNotify The handle of the task being notified. The handle to a
2431 * task can be returned from the xTaskCreate() API function used to create the
2432 * task, and the handle of the currently running task can be obtained by calling
2433 * xTaskGetCurrentTaskHandle().
2434 *
2435 * @param uxIndexToNotify The index within the target task's array of
2436 * notification values to which the notification is to be sent. uxIndexToNotify
2437 * must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyGive()
2438 * does not have this parameter and always sends notifications to index 0.
2439 *
2440 * @return xTaskNotifyGive() is a macro that calls xTaskNotify() with the
2441 * eAction parameter set to eIncrement - so pdPASS is always returned.
2442 *
2443 * \defgroup xTaskNotifyGiveIndexed xTaskNotifyGiveIndexed
2444 * \ingroup TaskNotifications
2445 */
2449 xTaskGenericNotify( ( xTaskToNotify ), ( uxIndexToNotify ), ( 0 ),
eIncrement, NULL )
2450
2451 /**
2452 * task. h
2453 * @code{c}
2454 * void vTaskNotifyGiveIndexedFromISR( TaskHandle_t xTaskHandle, UBaseType_t uxIndexToNotify, BaseType_t *pxHigherPriorityTaskWoken );
2455 * void vTaskNotifyGiveFromISR( TaskHandle_t xTaskHandle, BaseType_t *pxHigherPriorityTaskWoken );
2456 * @endcode
2457 *
2458 * A version of xTaskNotifyGiveIndexed() that can be called from an interrupt
2459 * service routine (ISR).
2460 *
2461 * See https://www.FreeRTOS.org/RTOS-task-notifications.html for more details.
2462 *
2463 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this macro
2464 * to be available.
2465 *
2466 * Each task has a private array of "notification values" (or 'notifications'),
2467 * each of which is a 32-bit unsigned integer (uint32_t). The constant
2468 * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
2469 * array, and (for backward compatibility) defaults to 1 if left undefined.
2470 * Prior to FreeRTOS V10.4.0 there was only one notification value per task.
2471 *
2472 * Events can be sent to a task using an intermediary object. Examples of such
2473 * objects are queues, semaphores, mutexes and event groups. Task notifications
2474 * are a method of sending an event directly to a task without the need for such
2475 * an intermediary object.
2476 *
2477 * A notification sent to a task can optionally perform an action, such as
2478 * update, overwrite or increment one of the task's notification values. In
2479 * that way task notifications can be used to send data to a task, or be used as
2480 * light weight and fast binary or counting semaphores.
2481 *
2482 * vTaskNotifyGiveIndexedFromISR() is intended for use when task notifications
2483 * are used as light weight and faster binary or counting semaphore equivalents.
2484 * Actual FreeRTOS semaphores are given from an ISR using the
2485 * xSemaphoreGiveFromISR() API function, the equivalent action that instead uses
2486 * a task notification is vTaskNotifyGiveIndexedFromISR().
2487 *
2488 * When task notifications are being used as a binary or counting semaphore
2489 * equivalent then the task being notified should wait for the notification
2490 * using the ulTaskNotifyTakeIndexed() API function rather than the
2491 * xTaskNotifyWaitIndexed() API function.
2492 *
2493 * **NOTE** Each notification within the array operates independently - a task
2494 * can only block on one notification within the array at a time and will not be
2495 * unblocked by a notification sent to any other array index.
2496 *
2497 * Backward compatibility information:
2498 * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
2499 * all task notification API functions operated on that value. Replacing the
2500 * single notification value with an array of notification values necessitated a
2501 * new set of API functions that could address specific notifications within the
2502 * array. xTaskNotifyFromISR() is the original API function, and remains
2503 * backward compatible by always operating on the notification value at index 0
2504 * within the array. Calling xTaskNotifyGiveFromISR() is equivalent to calling
2505 * xTaskNotifyGiveIndexedFromISR() with the uxIndexToNotify parameter set to 0.
2506 *
2507 * @param xTaskToNotify The handle of the task being notified. The handle to a
2508 * task can be returned from the xTaskCreate() API function used to create the
2509 * task, and the handle of the currently running task can be obtained by calling
2510 * xTaskGetCurrentTaskHandle().
2511 *
2512 * @param uxIndexToNotify The index within the target task's array of
2513 * notification values to which the notification is to be sent. uxIndexToNotify
2514 * must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES.
2515 * xTaskNotifyGiveFromISR() does not have this parameter and always sends
2516 * notifications to index 0.
2517 *
2518 * @param pxHigherPriorityTaskWoken vTaskNotifyGiveFromISR() will set
2519 * *pxHigherPriorityTaskWoken to pdTRUE if sending the notification caused the
2520 * task to which the notification was sent to leave the Blocked state, and the
2521 * unblocked task has a priority higher than the currently running task. If
2522 * vTaskNotifyGiveFromISR() sets this value to pdTRUE then a context switch
2523 * should be requested before the interrupt is exited. How a context switch is
2524 * requested from an ISR is dependent on the port - see the documentation page
2525 * for the port in use.
2526 *
2527 * \defgroup vTaskNotifyGiveIndexedFromISR vTaskNotifyGiveIndexedFromISR
2528 * \ingroup TaskNotifications
2529 */
2530 void vTaskGenericNotifyGiveFromISR(
TaskHandle_t xTaskToNotify,
2532
BaseType_t * pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
2536 vTaskGenericNotifyGiveFromISR( ( xTaskToNotify ), ( uxIndexToNotify ), ( pxHigherPriorityTaskWoken ) );
2537
2538 /**
2539 * task. h
2540 * @code{c}
2541 * uint32_t ulTaskNotifyTakeIndexed( UBaseType_t uxIndexToWaitOn, BaseType_t xClearCountOnExit, TickType_t xTicksToWait );
2542 *
2543 * uint32_t ulTaskNotifyTake( BaseType_t xClearCountOnExit, TickType_t xTicksToWait );
2544 * @endcode
2545 *
2546 * Waits for a direct to task notification on a particular index in the calling
2547 * task's notification array in a manner similar to taking a counting semaphore.
2548 *
2549 * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
2550 *
2551 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this
2552 * function to be available.
2553 *
2554 * Each task has a private array of "notification values" (or 'notifications'),
2555 * each of which is a 32-bit unsigned integer (uint32_t). The constant
2556 * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
2557 * array, and (for backward compatibility) defaults to 1 if left undefined.
2558 * Prior to FreeRTOS V10.4.0 there was only one notification value per task.
2559 *
2560 * Events can be sent to a task using an intermediary object. Examples of such
2561 * objects are queues, semaphores, mutexes and event groups. Task notifications
2562 * are a method of sending an event directly to a task without the need for such
2563 * an intermediary object.
2564 *
2565 * A notification sent to a task can optionally perform an action, such as
2566 * update, overwrite or increment one of the task's notification values. In
2567 * that way task notifications can be used to send data to a task, or be used as
2568 * light weight and fast binary or counting semaphores.
2569 *
2570 * ulTaskNotifyTakeIndexed() is intended for use when a task notification is
2571 * used as a faster and lighter weight binary or counting semaphore alternative.
2572 * Actual FreeRTOS semaphores are taken using the xSemaphoreTake() API function,
2573 * the equivalent action that instead uses a task notification is
2574 * ulTaskNotifyTakeIndexed().
2575 *
2576 * When a task is using its notification value as a binary or counting semaphore
2577 * other tasks should send notifications to it using the xTaskNotifyGiveIndexed()
2578 * macro, or xTaskNotifyIndex() function with the eAction parameter set to
2579 * eIncrement.
2580 *
2581 * ulTaskNotifyTakeIndexed() can either clear the task's notification value at
2582 * the array index specified by the uxIndexToWaitOn parameter to zero on exit,
2583 * in which case the notification value acts like a binary semaphore, or
2584 * decrement the notification value on exit, in which case the notification
2585 * value acts like a counting semaphore.
2586 *
2587 * A task can use ulTaskNotifyTakeIndexed() to [optionally] block to wait for
2588 * a notification. The task does not consume any CPU time while it is in the
2589 * Blocked state.
2590 *
2591 * Where as xTaskNotifyWaitIndexed() will return when a notification is pending,
2592 * ulTaskNotifyTakeIndexed() will return when the task's notification value is
2593 * not zero.
2594 *
2595 * **NOTE** Each notification within the array operates independently - a task
2596 * can only block on one notification within the array at a time and will not be
2597 * unblocked by a notification sent to any other array index.
2598 *
2599 * Backward compatibility information:
2600 * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
2601 * all task notification API functions operated on that value. Replacing the
2602 * single notification value with an array of notification values necessitated a
2603 * new set of API functions that could address specific notifications within the
2604 * array. ulTaskNotifyTake() is the original API function, and remains backward
2605 * compatible by always operating on the notification value at index 0 in the
2606 * array. Calling ulTaskNotifyTake() is equivalent to calling
2607 * ulTaskNotifyTakeIndexed() with the uxIndexToWaitOn parameter set to 0.
2608 *
2609 * @param uxIndexToWaitOn The index within the calling task's array of
2610 * notification values on which the calling task will wait for a notification to
2611 * be non-zero. uxIndexToWaitOn must be less than
2612 * configTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyTake() does
2613 * not have this parameter and always waits for notifications on index 0.
2614 *
2615 * @param xClearCountOnExit if xClearCountOnExit is pdFALSE then the task's
2616 * notification value is decremented when the function exits. In this way the
2617 * notification value acts like a counting semaphore. If xClearCountOnExit is
2618 * not pdFALSE then the task's notification value is cleared to zero when the
2619 * function exits. In this way the notification value acts like a binary
2620 * semaphore.
2621 *
2622 * @param xTicksToWait The maximum amount of time that the task should wait in
2623 * the Blocked state for the task's notification value to be greater than zero,
2624 * should the count not already be greater than zero when
2625 * ulTaskNotifyTake() was called. The task will not consume any processing
2626 * time while it is in the Blocked state. This is specified in kernel ticks,
2627 * the macro pdMS_TO_TICKS( value_in_ms ) can be used to convert a time
2628 * specified in milliseconds to a time specified in ticks.
2629 *
2630 * @return The task's notification count before it is either cleared to zero or
2631 * decremented (see the xClearCountOnExit parameter).
2632 *
2633 * \defgroup ulTaskNotifyTakeIndexed ulTaskNotifyTakeIndexed
2634 * \ingroup TaskNotifications
2635 */
2636 uint32_t ulTaskGenericNotifyTake(
UBaseType_t uxIndexToWaitOn,
2638
TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
2642 ulTaskGenericNotifyTake( ( uxIndexToWaitOn ), ( xClearCountOnExit ), ( xTicksToWait ) )
2643
2644 /**
2645 * task. h
2646 * @code{c}
2647 * BaseType_t xTaskNotifyStateClearIndexed( TaskHandle_t xTask, UBaseType_t uxIndexToCLear );
2648 *
2649 * BaseType_t xTaskNotifyStateClear( TaskHandle_t xTask );
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 * Each task has a private array of "notification values" (or 'notifications'),
2658 * each of which is a 32-bit unsigned integer (uint32_t). The constant
2659 * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
2660 * array, and (for backward compatibility) defaults to 1 if left undefined.
2661 * Prior to FreeRTOS V10.4.0 there was only one notification value per task.
2662 *
2663 * If a notification is sent to an index within the array of notifications then
2664 * the notification at that index is said to be 'pending' until it is read or
2665 * explicitly cleared by the receiving task. xTaskNotifyStateClearIndexed()
2666 * is the function that clears a pending notification without reading the
2667 * notification value. The notification value at the same array index is not
2668 * altered. Set xTask to NULL to clear the notification state of the calling
2669 * task.
2670 *
2671 * Backward compatibility information:
2672 * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
2673 * all task notification API functions operated on that value. Replacing the
2674 * single notification value with an array of notification values necessitated a
2675 * new set of API functions that could address specific notifications within the
2676 * array. xTaskNotifyStateClear() is the original API function, and remains
2677 * backward compatible by always operating on the notification value at index 0
2678 * within the array. Calling xTaskNotifyStateClear() is equivalent to calling
2679 * xTaskNotifyStateClearIndexed() with the uxIndexToNotify parameter set to 0.
2680 *
2681 * @param xTask The handle of the RTOS task that will have a notification state
2682 * cleared. Set xTask to NULL to clear a notification state in the calling
2683 * task. To obtain a task's handle create the task using xTaskCreate() and
2684 * make use of the pxCreatedTask parameter, or create the task using
2685 * xTaskCreateStatic() and store the returned value, or use the task's name in
2686 * a call to xTaskGetHandle().
2687 *
2688 * @param uxIndexToClear The index within the target task's array of
2689 * notification values to act upon. For example, setting uxIndexToClear to 1
2690 * will clear the state of the notification at index 1 within the array.
2691 * uxIndexToClear must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES.
2692 * ulTaskNotifyStateClear() does not have this parameter and always acts on the
2693 * notification at index 0.
2694 *
2695 * @return pdTRUE if the task's notification state was set to
2696 * eNotWaitingNotification, otherwise pdFALSE.
2697 *
2698 * \defgroup xTaskNotifyStateClearIndexed xTaskNotifyStateClearIndexed
2699 * \ingroup TaskNotifications
2700 */
2706 xTaskGenericNotifyStateClear( ( xTask ), ( uxIndexToClear ) )
2707
2708 /**
2709 * task. h
2710 * @code{c}
2711 * uint32_t ulTaskNotifyValueClearIndexed( TaskHandle_t xTask, UBaseType_t uxIndexToClear, uint32_t ulBitsToClear );
2712 *
2713 * uint32_t ulTaskNotifyValueClear( TaskHandle_t xTask, uint32_t ulBitsToClear );
2714 * @endcode
2715 *
2716 * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
2717 *
2718 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these
2719 * functions to be available.
2720 *
2721 * Each task has a private array of "notification values" (or 'notifications'),
2722 * each of which is a 32-bit unsigned integer (uint32_t). The constant
2723 * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
2724 * array, and (for backward compatibility) defaults to 1 if left undefined.
2725 * Prior to FreeRTOS V10.4.0 there was only one notification value per task.
2726 *
2727 * ulTaskNotifyValueClearIndexed() clears the bits specified by the
2728 * ulBitsToClear bit mask in the notification value at array index uxIndexToClear
2729 * of the task referenced by xTask.
2730 *
2731 * Backward compatibility information:
2732 * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
2733 * all task notification API functions operated on that value. Replacing the
2734 * single notification value with an array of notification values necessitated a
2735 * new set of API functions that could address specific notifications within the
2736 * array. ulTaskNotifyValueClear() is the original API function, and remains
2737 * backward compatible by always operating on the notification value at index 0
2738 * within the array. Calling ulTaskNotifyValueClear() is equivalent to calling
2739 * ulTaskNotifyValueClearIndexed() with the uxIndexToClear parameter set to 0.
2740 *
2741 * @param xTask The handle of the RTOS task that will have bits in one of its
2742 * notification values cleared. Set xTask to NULL to clear bits in a
2743 * notification value of the calling task. To obtain a task's handle create the
2744 * task using xTaskCreate() and make use of the pxCreatedTask parameter, or
2745 * create the task using xTaskCreateStatic() and store the returned value, or
2746 * use the task's name in a call to xTaskGetHandle().
2747 *
2748 * @param uxIndexToClear The index within the target task's array of
2749 * notification values in which to clear the bits. uxIndexToClear
2750 * must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES.
2751 * ulTaskNotifyValueClear() does not have this parameter and always clears bits
2752 * in the notification value at index 0.
2753 *
2754 * @param ulBitsToClear Bit mask of the bits to clear in the notification value of
2755 * xTask. Set a bit to 1 to clear the corresponding bits in the task's notification
2756 * value. Set ulBitsToClear to 0xffffffff (UINT_MAX on 32-bit architectures) to clear
2757 * the notification value to 0. Set ulBitsToClear to 0 to query the task's
2758 * notification value without clearing any bits.
2759 *
2760 *
2761 * @return The value of the target task's notification value before the bits
2762 * specified by ulBitsToClear were cleared.
2763 * \defgroup ulTaskNotifyValueClear ulTaskNotifyValueClear
2764 * \ingroup TaskNotifications
2765 */
2766 uint32_t ulTaskGenericNotifyValueClear(
TaskHandle_t xTask,
2768 uint32_t ulBitsToClear ) PRIVILEGED_FUNCTION;
2772 ulTaskGenericNotifyValueClear( ( xTask ), ( uxIndexToClear ), ( ulBitsToClear ) )
2773
2774 /**
2775 * task.h
2776 * @code{c}
2777 * void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut );
2778 * @endcode
2779 *
2780 * Capture the current time for future use with xTaskCheckForTimeOut().
2781 *
2782 * @param pxTimeOut Pointer to a timeout object into which the current time
2783 * is to be captured. The captured time includes the tick count and the number
2784 * of times the tick count has overflowed since the system first booted.
2785 * \defgroup vTaskSetTimeOutState vTaskSetTimeOutState
2786 * \ingroup TaskCtrl
2787 */
2788 void vTaskSetTimeOutState(
TimeOut_t * const pxTimeOut ) PRIVILEGED_FUNCTION;
2789
2790 /**
2791 * task.h
2792 * @code{c}
2793 * BaseType_t xTaskCheckForTimeOut( TimeOut_t * const pxTimeOut, TickType_t * const pxTicksToWait );
2794 * @endcode
2795 *
2796 * Determines if pxTicksToWait ticks has passed since a time was captured
2797 * using a call to vTaskSetTimeOutState(). The captured time includes the tick
2798 * count and the number of times the tick count has overflowed.
2799 *
2800 * @param pxTimeOut The time status as captured previously using
2801 * vTaskSetTimeOutState. If the timeout has not yet occurred, it is updated
2802 * to reflect the current time status.
2803 * @param pxTicksToWait The number of ticks to check for timeout i.e. if
2804 * pxTicksToWait ticks have passed since pxTimeOut was last updated (either by
2805 * vTaskSetTimeOutState() or xTaskCheckForTimeOut()), the timeout has occurred.
2806 * If the timeout has not occurred, pxTicksToWait is updated to reflect the
2807 * number of remaining ticks.
2808 *
2809 * @return If timeout has occurred, pdTRUE is returned. Otherwise pdFALSE is
2810 * returned and pxTicksToWait is updated to reflect the number of remaining
2811 * ticks.
2812 *
2813 * @see https://www.FreeRTOS.org/xTaskCheckForTimeOut.html
2814 *
2815 * Example Usage:
2816 * @code{c}
2817 * // Driver library function used to receive uxWantedBytes from an Rx buffer
2818 * // that is filled by a UART interrupt. If there are not enough bytes in the
2819 * // Rx buffer then the task enters the Blocked state until it is notified that
2820 * // more data has been placed into the buffer. If there is still not enough
2821 * // data then the task re-enters the Blocked state, and xTaskCheckForTimeOut()
2822 * // is used to re-calculate the Block time to ensure the total amount of time
2823 * // spent in the Blocked state does not exceed MAX_TIME_TO_WAIT. This
2824 * // continues until either the buffer contains at least uxWantedBytes bytes,
2825 * // or the total amount of time spent in the Blocked state reaches
2826 * // MAX_TIME_TO_WAIT - at which point the task reads however many bytes are
2827 * // available up to a maximum of uxWantedBytes.
2828 *
2829 * size_t xUART_Receive( uint8_t *pucBuffer, size_t uxWantedBytes )
2830 * {
2831 * size_t uxReceived = 0;
2832 * TickType_t xTicksToWait = MAX_TIME_TO_WAIT;
2833 * TimeOut_t xTimeOut;
2834 *
2835 * // Initialize xTimeOut. This records the time at which this function
2836 * // was entered.
2837 * vTaskSetTimeOutState( &xTimeOut );
2838 *
2839 * // Loop until the buffer contains the wanted number of bytes, or a
2840 * // timeout occurs.
2841 * while( UART_bytes_in_rx_buffer( pxUARTInstance ) < uxWantedBytes )
2842 * {
2843 * // The buffer didn't contain enough data so this task is going to
2844 * // enter the Blocked state. Adjusting xTicksToWait to account for
2845 * // any time that has been spent in the Blocked state within this
2846 * // function so far to ensure the total amount of time spent in the
2847 * // Blocked state does not exceed MAX_TIME_TO_WAIT.
2848 * if( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait ) != pdFALSE )
2849 * {
2850 * //Timed out before the wanted number of bytes were available,
2851 * // exit the loop.
2852 * break;
2853 * }
2854 *
2855 * // Wait for a maximum of xTicksToWait ticks to be notified that the
2856 * // receive interrupt has placed more data into the buffer.
2857 * ulTaskNotifyTake( pdTRUE, xTicksToWait );
2858 * }
2859 *
2860 * // Attempt to read uxWantedBytes from the receive buffer into pucBuffer.
2861 * // The actual number of bytes read (which might be less than
2862 * // uxWantedBytes) is returned.
2863 * uxReceived = UART_read_from_receive_buffer( pxUARTInstance,
2864 * pucBuffer,
2865 * uxWantedBytes );
2866 *
2867 * return uxReceived;
2868 * }
2869 * @endcode
2870 * \defgroup xTaskCheckForTimeOut xTaskCheckForTimeOut
2871 * \ingroup TaskCtrl
2872 */
2874
TickType_t * const pxTicksToWait ) PRIVILEGED_FUNCTION;
2875
2876 /**
2877 * task.h
2878 * @code{c}
2879 * BaseType_t xTaskCatchUpTicks( TickType_t xTicksToCatchUp );
2880 * @endcode
2881 *
2882 * This function corrects the tick count value after the application code has held
2883 * interrupts disabled for an extended period resulting in tick interrupts having
2884 * been missed.
2885 *
2886 * This function is similar to vTaskStepTick(), however, unlike
2887 * vTaskStepTick(), xTaskCatchUpTicks() may move the tick count forward past a
2888 * time at which a task should be removed from the blocked state. That means
2889 * tasks may have to be removed from the blocked state as the tick count is
2890 * moved.
2891 *
2892 * @param xTicksToCatchUp The number of tick interrupts that have been missed due to
2893 * interrupts being disabled. Its value is not computed automatically, so must be
2894 * computed by the application writer.
2895 *
2896 * @return pdTRUE if moving the tick count forward resulted in a task leaving the
2897 * blocked state and a context switch being performed. Otherwise pdFALSE.
2898 *
2899 * \defgroup xTaskCatchUpTicks xTaskCatchUpTicks
2900 * \ingroup TaskCtrl
2901 */
2903
2904
2905 /*-----------------------------------------------------------
2906 * SCHEDULER INTERNALS AVAILABLE FOR PORTING PURPOSES
2907 *----------------------------------------------------------*/
2908
2909 /*
2910 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS ONLY
2911 * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS
2912 * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
2913 *
2914 * Called from the real time kernel tick (either preemptive or cooperative),
2915 * this increments the tick count and checks if any tasks that are blocked
2916 * for a finite period required removing from a blocked list and placing on
2917 * a ready list. If a non-zero value is returned then a context switch is
2918 * required because either:
2919 * + A task was removed from a blocked list because its timeout had expired,
2920 * or
2921 * + Time slicing is in use and there is a task of equal priority to the
2922 * currently running task.
2923 */
2924
BaseType_t xTaskIncrementTick( void ) PRIVILEGED_FUNCTION;
2925
2926 /*
2927 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN
2928 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
2929 *
2930 * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED.
2931 *
2932 * Removes the calling task from the ready list and places it both
2933 * on the list of tasks waiting for a particular event, and the
2934 * list of delayed tasks. The task will be removed from both lists
2935 * and replaced on the ready list should either the event occur (and
2936 * there be no higher priority tasks waiting on the same event) or
2937 * the delay period expires.
2938 *
2939 * The 'unordered' version replaces the event list item value with the
2940 * xItemValue value, and inserts the list item at the end of the list.
2941 *
2942 * The 'ordered' version uses the existing event list item value (which is the
2943 * owning task's priority) to insert the list item into the event list in task
2944 * priority order.
2945 *
2946 * @param pxEventList The list containing tasks that are blocked waiting
2947 * for the event to occur.
2948 *
2949 * @param xItemValue The item value to use for the event list item when the
2950 * event list is not ordered by task priority.
2951 *
2952 * @param xTicksToWait The maximum amount of time that the task should wait
2953 * for the event to occur. This is specified in kernel ticks, the constant
2954 * portTICK_PERIOD_MS can be used to convert kernel ticks into a real time
2955 * period.
2956 */
2957 void vTaskPlaceOnEventList( List_t * const pxEventList,
2958 const
TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
2959 void vTaskPlaceOnUnorderedEventList( List_t * pxEventList,
2961 const
TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
2962
2963 /*
2964 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN
2965 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
2966 *
2967 * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED.
2968 *
2969 * This function performs nearly the same function as vTaskPlaceOnEventList().
2970 * The difference being that this function does not permit tasks to block
2971 * indefinitely, whereas vTaskPlaceOnEventList() does.
2972 *
2973 */
2974 void vTaskPlaceOnEventListRestricted( List_t * const pxEventList,
2976 const
BaseType_t xWaitIndefinitely ) PRIVILEGED_FUNCTION;
2977
2978 /*
2979 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN
2980 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
2981 *
2982 * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED.
2983 *
2984 * Removes a task from both the specified event list and the list of blocked
2985 * tasks, and places it on a ready queue.
2986 *
2987 * xTaskRemoveFromEventList()/vTaskRemoveFromUnorderedEventList() will be called
2988 * if either an event occurs to unblock a task, or the block timeout period
2989 * expires.
2990 *
2991 * xTaskRemoveFromEventList() is used when the event list is in task priority
2992 * order. It removes the list item from the head of the event list as that will
2993 * have the highest priority owning task of all the tasks on the event list.
2994 * vTaskRemoveFromUnorderedEventList() is used when the event list is not
2995 * ordered and the event list items hold something other than the owning tasks
2996 * priority. In this case the event list item value is updated to the value
2997 * passed in the xItemValue parameter.
2998 *
2999 * @return pdTRUE if the task being removed has a higher priority than the task
3000 * making the call, otherwise pdFALSE.
3001 */
3002
BaseType_t xTaskRemoveFromEventList( const List_t * const pxEventList ) PRIVILEGED_FUNCTION;
3003 void vTaskRemoveFromUnorderedEventList( ListItem_t * pxEventListItem,
3004 const
TickType_t xItemValue ) PRIVILEGED_FUNCTION;
3005
3006 /*
3007 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS ONLY
3008 * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS
3009 * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
3010 *
3011 * Sets the pointer to the current TCB to the TCB of the highest priority task
3012 * that is ready to run.
3013 */
3014 portDONT_DISCARD void vTaskSwitchContext( void ) PRIVILEGED_FUNCTION;
3015
3016 /*
3017 * THESE FUNCTIONS MUST NOT BE USED FROM APPLICATION CODE. THEY ARE USED BY
3018 * THE EVENT BITS MODULE.
3019 */
3020
TickType_t uxTaskResetEventItemValue( void ) PRIVILEGED_FUNCTION;
3021
3022 /*
3023 * Return the handle of the calling task.
3024 */
3025
TaskHandle_t xTaskGetCurrentTaskHandle( void ) PRIVILEGED_FUNCTION;
3026
3027 /*
3028 * Shortcut used by the queue implementation to prevent unnecessary call to
3029 * taskYIELD();
3030 */
3031 void vTaskMissedYield( void ) PRIVILEGED_FUNCTION;
3032
3033 /*
3034 * Returns the scheduler state as taskSCHEDULER_RUNNING,
3035 * taskSCHEDULER_NOT_STARTED or taskSCHEDULER_SUSPENDED.
3036 */
3037
BaseType_t xTaskGetSchedulerState( void ) PRIVILEGED_FUNCTION;
3038
3039 /*
3040 * Raises the priority of the mutex holder to that of the calling task should
3041 * the mutex holder have a priority less than the calling task.
3042 */
3044
3045 /*
3046 * Set the priority of a task back to its proper priority in the case that it
3047 * inherited a higher priority while it was holding a semaphore.
3048 */
3050
3051 /*
3052 * If a higher priority task attempting to obtain a mutex caused a lower
3053 * priority task to inherit the higher priority task's priority - but the higher
3054 * priority task then timed out without obtaining the mutex, then the lower
3055 * priority task will disinherit the priority again - but only down as far as
3056 * the highest priority task that is still waiting for the mutex (if there were
3057 * more than one task waiting for the mutex).
3058 */
3059 void vTaskPriorityDisinheritAfterTimeout(
TaskHandle_t const pxMutexHolder,
3060
UBaseType_t uxHighestPriorityWaitingTask ) PRIVILEGED_FUNCTION;
3061
3062 /*
3063 * Get the uxTaskNumber assigned to the task referenced by the xTask parameter.
3064 */
3066
3067 /*
3068 * Set the uxTaskNumber of the task referenced by the xTask parameter to
3069 * uxHandle.
3070 */
3073
3074 /*
3075 * Only available when configUSE_TICKLESS_IDLE is set to 1.
3076 * If tickless mode is being used, or a low power mode is implemented, then
3077 * the tick interrupt will not execute during idle periods. When this is the
3078 * case, the tick count value maintained by the scheduler needs to be kept up
3079 * to date with the actual execution time by being skipped forward by a time
3080 * equal to the idle period.
3081 */
3082 void vTaskStepTick(
TickType_t xTicksToJump ) PRIVILEGED_FUNCTION;
3083
3084 /*
3085 * Only available when configUSE_TICKLESS_IDLE is set to 1.
3086 * Provided for use within portSUPPRESS_TICKS_AND_SLEEP() to allow the port
3087 * specific sleep function to determine if it is ok to proceed with the sleep,
3088 * and if it is ok to proceed, if it is ok to sleep indefinitely.
3089 *
3090 * This function is necessary because portSUPPRESS_TICKS_AND_SLEEP() is only
3091 * called with the scheduler suspended, not from within a critical section. It
3092 * is therefore possible for an interrupt to request a context switch between
3093 * portSUPPRESS_TICKS_AND_SLEEP() and the low power mode actually being
3094 * entered. eTaskConfirmSleepModeStatus() should be called from a short
3095 * critical section between the timer being stopped and the sleep mode being
3096 * entered to ensure it is ok to proceed into the sleep mode.
3097 */
3099
3100 /*
3101 * For internal use only. Increment the mutex held count when a mutex is
3102 * taken and return the handle of the task that has taken the mutex.
3103 */
3104
TaskHandle_t pvTaskIncrementMutexHeldCount( void ) PRIVILEGED_FUNCTION;
3105
3106 /*
3107 * For internal use only. Same as vTaskSetTimeOutState(), but without a critical
3108 * section.
3109 */
3110 void vTaskInternalSetTimeOutState(
TimeOut_t * const pxTimeOut ) PRIVILEGED_FUNCTION;
3111
3112
3113 /* *INDENT-OFF* */
3114 #ifdef __cplusplus
3115 }
3116 #endif
3117 /* *INDENT-ON* */
3118 #endif /* INC_TASK_H */