forked from FreeRTOS/FreeRTOS-Kernel
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathtask.h
3759 lines (3603 loc) · 160 KB
/
task.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/*
* FreeRTOS Kernel <DEVELOPMENT BRANCH>
* Copyright (C) 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
*
* SPDX-License-Identifier: MIT
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of
* this software and associated documentation files (the "Software"), to deal in
* the Software without restriction, including without limitation the rights to
* use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
* the Software, and to permit persons to whom the Software is furnished to do so,
* subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
* FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
* COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
* IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*
* https://www.FreeRTOS.org
* https://github.com/FreeRTOS
*
*/
#ifndef INC_TASK_H
#define INC_TASK_H
#ifndef INC_FREERTOS_H
#error "include FreeRTOS.h must appear in source files before include task.h"
#endif
#include "list.h"
/* *INDENT-OFF* */
#ifdef __cplusplus
extern "C" {
#endif
/* *INDENT-ON* */
/*-----------------------------------------------------------
* MACROS AND DEFINITIONS
*----------------------------------------------------------*/
/*
* If tskKERNEL_VERSION_NUMBER ends with + it represents the version in development
* after the numbered release.
*
* The tskKERNEL_VERSION_MAJOR, tskKERNEL_VERSION_MINOR, tskKERNEL_VERSION_BUILD
* values will reflect the last released version number.
*/
#define tskKERNEL_VERSION_NUMBER "V10.4.4+"
#define tskKERNEL_VERSION_MAJOR 10
#define tskKERNEL_VERSION_MINOR 4
#define tskKERNEL_VERSION_BUILD 4
/* MPU region parameters passed in ulParameters
* of MemoryRegion_t struct. */
#define tskMPU_REGION_READ_ONLY ( 1UL << 0UL )
#define tskMPU_REGION_READ_WRITE ( 1UL << 1UL )
#define tskMPU_REGION_EXECUTE_NEVER ( 1UL << 2UL )
#define tskMPU_REGION_NORMAL_MEMORY ( 1UL << 3UL )
#define tskMPU_REGION_DEVICE_MEMORY ( 1UL << 4UL )
/* MPU region permissions stored in MPU settings to
* authorize access requests. */
#define tskMPU_READ_PERMISSION ( 1UL << 0UL )
#define tskMPU_WRITE_PERMISSION ( 1UL << 1UL )
/* The direct to task notification feature used to have only a single notification
* per task. Now there is an array of notifications per task that is dimensioned by
* configTASK_NOTIFICATION_ARRAY_ENTRIES. For backward compatibility, any use of the
* original direct to task notification defaults to using the first index in the
* array. */
#define tskDEFAULT_INDEX_TO_NOTIFY ( 0 )
/**
* task. h
*
* Type by which tasks are referenced. For example, a call to xTaskCreate
* returns (via a pointer parameter) an TaskHandle_t variable that can then
* be used as a parameter to vTaskDelete to delete the task.
*
* \defgroup TaskHandle_t TaskHandle_t
* \ingroup Tasks
*/
struct tskTaskControlBlock; /* The old naming convention is used to prevent breaking kernel aware debuggers. */
typedef struct tskTaskControlBlock * TaskHandle_t;
typedef const struct tskTaskControlBlock * ConstTaskHandle_t;
/*
* Defines the prototype to which the application task hook function must
* conform.
*/
typedef BaseType_t (* TaskHookFunction_t)( void * arg );
/* Task states returned by eTaskGetState. */
typedef enum
{
eRunning = 0, /* A task is querying the state of itself, so must be running. */
eReady, /* The task being queried is in a ready or pending ready list. */
eBlocked, /* The task being queried is in the Blocked state. */
eSuspended, /* The task being queried is in the Suspended state, or is in the Blocked state with an infinite time out. */
eDeleted, /* The task being queried has been deleted, but its TCB has not yet been freed. */
eInvalid /* Used as an 'invalid state' value. */
} eTaskState;
/* Actions that can be performed when vTaskNotify() is called. */
typedef enum
{
eNoAction = 0, /* Notify the task without updating its notify value. */
eSetBits, /* Set bits in the task's notification value. */
eIncrement, /* Increment the task's notification value. */
eSetValueWithOverwrite, /* Set the task's notification value to a specific value even if the previous value has not yet been read by the task. */
eSetValueWithoutOverwrite /* Set the task's notification value if the previous value has been read by the task. */
} eNotifyAction;
/*
* Used internally only.
*/
typedef struct xTIME_OUT
{
BaseType_t xOverflowCount;
TickType_t xTimeOnEntering;
} TimeOut_t;
/*
* Defines the memory ranges allocated to the task when an MPU is used.
*/
typedef struct xMEMORY_REGION
{
void * pvBaseAddress;
uint32_t ulLengthInBytes;
uint32_t ulParameters;
} MemoryRegion_t;
/*
* Parameters required to create an MPU protected task.
*/
typedef struct xTASK_PARAMETERS
{
TaskFunction_t pvTaskCode;
const char * pcName;
configSTACK_DEPTH_TYPE usStackDepth;
void * pvParameters;
UBaseType_t uxPriority;
StackType_t * puxStackBuffer;
MemoryRegion_t xRegions[ portNUM_CONFIGURABLE_REGIONS ];
#if ( ( portUSING_MPU_WRAPPERS == 1 ) && ( configSUPPORT_STATIC_ALLOCATION == 1 ) )
StaticTask_t * const pxTaskBuffer;
#endif
} TaskParameters_t;
/* Used with the uxTaskGetSystemState() function to return the state of each task
* in the system. */
typedef struct xTASK_STATUS
{
TaskHandle_t xHandle; /* The handle of the task to which the rest of the information in the structure relates. */
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! */
UBaseType_t xTaskNumber; /* A number unique to the task. */
eTaskState eCurrentState; /* The state in which the task existed when the structure was populated. */
UBaseType_t uxCurrentPriority; /* The priority at which the task was running (may be inherited) when the structure was populated. */
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. */
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. */
StackType_t * pxStackBase; /* Points to the lowest address of the task's stack area. */
#if ( ( portSTACK_GROWTH > 0 ) || ( configRECORD_STACK_HIGH_ADDRESS == 1 ) )
StackType_t * pxTopOfStack; /* Points to the top address of the task's stack area. */
StackType_t * pxEndOfStack; /* Points to the end address of the task's stack area. */
#endif
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. */
#if ( ( configUSE_CORE_AFFINITY == 1 ) && ( configNUMBER_OF_CORES > 1 ) )
UBaseType_t uxCoreAffinityMask; /* The core affinity mask for the task */
#endif
} TaskStatus_t;
/* Possible return values for eTaskConfirmSleepModeStatus(). */
typedef enum
{
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. */
eStandardSleep, /* Enter a sleep mode that will not last any longer than the expected idle time. */
#if ( INCLUDE_vTaskSuspend == 1 )
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. */
#endif /* INCLUDE_vTaskSuspend */
} eSleepModeStatus;
/**
* Defines the priority used by the idle task. This must not be modified.
*
* \ingroup TaskUtils
*/
#define tskIDLE_PRIORITY ( ( UBaseType_t ) 0U )
/**
* Defines affinity to all available cores.
*
* \ingroup TaskUtils
*/
#define tskNO_AFFINITY ( ( UBaseType_t ) -1 )
/**
* task. h
*
* Macro for forcing a context switch.
*
* \defgroup taskYIELD taskYIELD
* \ingroup SchedulerControl
*/
#define taskYIELD() portYIELD()
/**
* task. h
*
* Macro to mark the start of a critical code region. Preemptive context
* switches cannot occur when in a critical region.
*
* NOTE: This may alter the stack (depending on the portable implementation)
* so must be used with care!
*
* \defgroup taskENTER_CRITICAL taskENTER_CRITICAL
* \ingroup SchedulerControl
*/
#define taskENTER_CRITICAL() portENTER_CRITICAL()
#if ( configNUMBER_OF_CORES == 1 )
#define taskENTER_CRITICAL_FROM_ISR() portSET_INTERRUPT_MASK_FROM_ISR()
#else
#define taskENTER_CRITICAL_FROM_ISR() portENTER_CRITICAL_FROM_ISR()
#endif
/**
* task. h
*
* Macro to mark the end of a critical code region. Preemptive context
* switches cannot occur when in a critical region.
*
* NOTE: This may alter the stack (depending on the portable implementation)
* so must be used with care!
*
* \defgroup taskEXIT_CRITICAL taskEXIT_CRITICAL
* \ingroup SchedulerControl
*/
#define taskEXIT_CRITICAL() portEXIT_CRITICAL()
#if ( configNUMBER_OF_CORES == 1 )
#define taskEXIT_CRITICAL_FROM_ISR( x ) portCLEAR_INTERRUPT_MASK_FROM_ISR( x )
#else
#define taskEXIT_CRITICAL_FROM_ISR( x ) portEXIT_CRITICAL_FROM_ISR( x )
#endif
/**
* task. h
*
* Macro to disable all maskable interrupts.
*
* \defgroup taskDISABLE_INTERRUPTS taskDISABLE_INTERRUPTS
* \ingroup SchedulerControl
*/
#define taskDISABLE_INTERRUPTS() portDISABLE_INTERRUPTS()
/**
* task. h
*
* Macro to enable microcontroller interrupts.
*
* \defgroup taskENABLE_INTERRUPTS taskENABLE_INTERRUPTS
* \ingroup SchedulerControl
*/
#define taskENABLE_INTERRUPTS() portENABLE_INTERRUPTS()
/* Definitions returned by xTaskGetSchedulerState(). taskSCHEDULER_SUSPENDED is
* 0 to generate more optimal code when configASSERT() is defined as the constant
* is used in assert() statements. */
#define taskSCHEDULER_SUSPENDED ( ( BaseType_t ) 0 )
#define taskSCHEDULER_NOT_STARTED ( ( BaseType_t ) 1 )
#define taskSCHEDULER_RUNNING ( ( BaseType_t ) 2 )
/* Checks if core ID is valid. */
#define taskVALID_CORE_ID( xCoreID ) ( ( ( ( ( BaseType_t ) 0 <= ( xCoreID ) ) && ( ( xCoreID ) < ( BaseType_t ) configNUMBER_OF_CORES ) ) ) ? ( pdTRUE ) : ( pdFALSE ) )
/*-----------------------------------------------------------
* TASK CREATION API
*----------------------------------------------------------*/
/**
* task. h
* @code{c}
* BaseType_t xTaskCreate(
* TaskFunction_t pxTaskCode,
* const char * const pcName,
* const configSTACK_DEPTH_TYPE uxStackDepth,
* void *pvParameters,
* UBaseType_t uxPriority,
* TaskHandle_t *pxCreatedTask
* );
* @endcode
*
* Create a new task and add it to the list of tasks that are ready to run.
*
* Internally, within the FreeRTOS implementation, tasks use two blocks of
* memory. The first block is used to hold the task's data structures. The
* second block is used by the task as its stack. If a task is created using
* xTaskCreate() then both blocks of memory are automatically dynamically
* allocated inside the xTaskCreate() function. (see
* https://www.FreeRTOS.org/a00111.html). If a task is created using
* xTaskCreateStatic() then the application writer must provide the required
* memory. xTaskCreateStatic() therefore allows a task to be created without
* using any dynamic memory allocation.
*
* See xTaskCreateStatic() for a version that does not use any dynamic memory
* allocation.
*
* xTaskCreate() can only be used to create a task that has unrestricted
* access to the entire microcontroller memory map. Systems that include MPU
* support can alternatively create an MPU constrained task using
* xTaskCreateRestricted().
*
* @param pxTaskCode Pointer to the task entry function. Tasks
* must be implemented to never return (i.e. continuous loop).
*
* @param pcName A descriptive name for the task. This is mainly used to
* facilitate debugging. Max length defined by configMAX_TASK_NAME_LEN - default
* is 16.
*
* @param uxStackDepth The size of the task stack specified as the number of
* variables the stack can hold - not the number of bytes. For example, if
* the stack is 16 bits wide and uxStackDepth is defined as 100, 200 bytes
* will be allocated for stack storage.
*
* @param pvParameters Pointer that will be used as the parameter for the task
* being created.
*
* @param uxPriority The priority at which the task should run. Systems that
* include MPU support can optionally create tasks in a privileged (system)
* mode by setting bit portPRIVILEGE_BIT of the priority parameter. For
* example, to create a privileged task at priority 2 the uxPriority parameter
* should be set to ( 2 | portPRIVILEGE_BIT ).
*
* @param pxCreatedTask Used to pass back a handle by which the created task
* can be referenced.
*
* @return pdPASS if the task was successfully created and added to a ready
* list, otherwise an error code defined in the file projdefs.h
*
* Example usage:
* @code{c}
* // Task to be created.
* void vTaskCode( void * pvParameters )
* {
* for( ;; )
* {
* // Task code goes here.
* }
* }
*
* // Function that creates a task.
* void vOtherFunction( void )
* {
* static uint8_t ucParameterToPass;
* TaskHandle_t xHandle = NULL;
*
* // Create the task, storing the handle. Note that the passed parameter ucParameterToPass
* // must exist for the lifetime of the task, so in this case is declared static. If it was just an
* // an automatic stack variable it might no longer exist, or at least have been corrupted, by the time
* // the new task attempts to access it.
* xTaskCreate( vTaskCode, "NAME", STACK_SIZE, &ucParameterToPass, tskIDLE_PRIORITY, &xHandle );
* configASSERT( xHandle );
*
* // Use the handle to delete the task.
* if( xHandle != NULL )
* {
* vTaskDelete( xHandle );
* }
* }
* @endcode
* \defgroup xTaskCreate xTaskCreate
* \ingroup Tasks
*/
#if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
BaseType_t xTaskCreate( TaskFunction_t pxTaskCode,
const char * const pcName,
const configSTACK_DEPTH_TYPE uxStackDepth,
void * const pvParameters,
UBaseType_t uxPriority,
TaskHandle_t * const pxCreatedTask ) PRIVILEGED_FUNCTION;
#endif
#if ( ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) && ( configNUMBER_OF_CORES > 1 ) && ( configUSE_CORE_AFFINITY == 1 ) )
BaseType_t xTaskCreateAffinitySet( TaskFunction_t pxTaskCode,
const char * const pcName,
const configSTACK_DEPTH_TYPE uxStackDepth,
void * const pvParameters,
UBaseType_t uxPriority,
UBaseType_t uxCoreAffinityMask,
TaskHandle_t * const pxCreatedTask ) PRIVILEGED_FUNCTION;
#endif
/**
* task. h
* @code{c}
* TaskHandle_t xTaskCreateStatic( TaskFunction_t pxTaskCode,
* const char * const pcName,
* const configSTACK_DEPTH_TYPE uxStackDepth,
* void *pvParameters,
* UBaseType_t uxPriority,
* StackType_t *puxStackBuffer,
* StaticTask_t *pxTaskBuffer );
* @endcode
*
* Create a new task and add it to the list of tasks that are ready to run.
*
* Internally, within the FreeRTOS implementation, tasks use two blocks of
* memory. The first block is used to hold the task's data structures. The
* second block is used by the task as its stack. If a task is created using
* xTaskCreate() then both blocks of memory are automatically dynamically
* allocated inside the xTaskCreate() function. (see
* https://www.FreeRTOS.org/a00111.html). If a task is created using
* xTaskCreateStatic() then the application writer must provide the required
* memory. xTaskCreateStatic() therefore allows a task to be created without
* using any dynamic memory allocation.
*
* @param pxTaskCode Pointer to the task entry function. Tasks
* must be implemented to never return (i.e. continuous loop).
*
* @param pcName A descriptive name for the task. This is mainly used to
* facilitate debugging. The maximum length of the string is defined by
* configMAX_TASK_NAME_LEN in FreeRTOSConfig.h.
*
* @param uxStackDepth The size of the task stack specified as the number of
* variables the stack can hold - not the number of bytes. For example, if
* the stack is 32-bits wide and uxStackDepth is defined as 100 then 400 bytes
* will be allocated for stack storage.
*
* @param pvParameters Pointer that will be used as the parameter for the task
* being created.
*
* @param uxPriority The priority at which the task will run.
*
* @param puxStackBuffer Must point to a StackType_t array that has at least
* uxStackDepth indexes - the array will then be used as the task's stack,
* removing the need for the stack to be allocated dynamically.
*
* @param pxTaskBuffer Must point to a variable of type StaticTask_t, which will
* then be used to hold the task's data structures, removing the need for the
* memory to be allocated dynamically.
*
* @return If neither puxStackBuffer nor pxTaskBuffer are NULL, then the task
* will be created and a handle to the created task is returned. If either
* puxStackBuffer or pxTaskBuffer are NULL then the task will not be created and
* NULL is returned.
*
* Example usage:
* @code{c}
*
* // Dimensions of the buffer that the task being created will use as its stack.
* // NOTE: This is the number of words the stack will hold, not the number of
* // bytes. For example, if each stack item is 32-bits, and this is set to 100,
* // then 400 bytes (100 * 32-bits) will be allocated.
#define STACK_SIZE 200
*
* // Structure that will hold the TCB of the task being created.
* StaticTask_t xTaskBuffer;
*
* // Buffer that the task being created will use as its stack. Note this is
* // an array of StackType_t variables. The size of StackType_t is dependent on
* // the RTOS port.
* StackType_t xStack[ STACK_SIZE ];
*
* // Function that implements the task being created.
* void vTaskCode( void * pvParameters )
* {
* // The parameter value is expected to be 1 as 1 is passed in the
* // pvParameters value in the call to xTaskCreateStatic().
* configASSERT( ( uint32_t ) pvParameters == 1UL );
*
* for( ;; )
* {
* // Task code goes here.
* }
* }
*
* // Function that creates a task.
* void vOtherFunction( void )
* {
* TaskHandle_t xHandle = NULL;
*
* // Create the task without using any dynamic memory allocation.
* xHandle = xTaskCreateStatic(
* vTaskCode, // Function that implements the task.
* "NAME", // Text name for the task.
* STACK_SIZE, // Stack size in words, not bytes.
* ( void * ) 1, // Parameter passed into the task.
* tskIDLE_PRIORITY,// Priority at which the task is created.
* xStack, // Array to use as the task's stack.
* &xTaskBuffer ); // Variable to hold the task's data structure.
*
* // puxStackBuffer and pxTaskBuffer were not NULL, so the task will have
* // been created, and xHandle will be the task's handle. Use the handle
* // to suspend the task.
* vTaskSuspend( xHandle );
* }
* @endcode
* \defgroup xTaskCreateStatic xTaskCreateStatic
* \ingroup Tasks
*/
#if ( configSUPPORT_STATIC_ALLOCATION == 1 )
TaskHandle_t xTaskCreateStatic( TaskFunction_t pxTaskCode,
const char * const pcName,
const configSTACK_DEPTH_TYPE uxStackDepth,
void * const pvParameters,
UBaseType_t uxPriority,
StackType_t * const puxStackBuffer,
StaticTask_t * const pxTaskBuffer ) PRIVILEGED_FUNCTION;
#endif /* configSUPPORT_STATIC_ALLOCATION */
#if ( ( configSUPPORT_STATIC_ALLOCATION == 1 ) && ( configNUMBER_OF_CORES > 1 ) && ( configUSE_CORE_AFFINITY == 1 ) )
TaskHandle_t xTaskCreateStaticAffinitySet( TaskFunction_t pxTaskCode,
const char * const pcName,
const configSTACK_DEPTH_TYPE uxStackDepth,
void * const pvParameters,
UBaseType_t uxPriority,
StackType_t * const puxStackBuffer,
StaticTask_t * const pxTaskBuffer,
UBaseType_t uxCoreAffinityMask ) PRIVILEGED_FUNCTION;
#endif
/**
* task. h
* @code{c}
* BaseType_t xTaskCreateRestricted( TaskParameters_t *pxTaskDefinition, TaskHandle_t *pxCreatedTask );
* @endcode
*
* Only available when configSUPPORT_DYNAMIC_ALLOCATION is set to 1.
*
* xTaskCreateRestricted() should only be used in systems that include an MPU
* implementation.
*
* Create a new task and add it to the list of tasks that are ready to run.
* The function parameters define the memory regions and associated access
* permissions allocated to the task.
*
* See xTaskCreateRestrictedStatic() for a version that does not use any
* dynamic memory allocation.
*
* @param pxTaskDefinition Pointer to a structure that contains a member
* for each of the normal xTaskCreate() parameters (see the xTaskCreate() API
* documentation) plus an optional stack buffer and the memory region
* definitions.
*
* @param pxCreatedTask Used to pass back a handle by which the created task
* can be referenced.
*
* @return pdPASS if the task was successfully created and added to a ready
* list, otherwise an error code defined in the file projdefs.h
*
* Example usage:
* @code{c}
* // Create an TaskParameters_t structure that defines the task to be created.
* static const TaskParameters_t xCheckTaskParameters =
* {
* vATask, // pvTaskCode - the function that implements the task.
* "ATask", // pcName - just a text name for the task to assist debugging.
* 100, // uxStackDepth - the stack size DEFINED IN WORDS.
* NULL, // pvParameters - passed into the task function as the function parameters.
* ( 1UL | portPRIVILEGE_BIT ),// uxPriority - task priority, set the portPRIVILEGE_BIT if the task should run in a privileged state.
* cStackBuffer,// puxStackBuffer - the buffer to be used as the task stack.
*
* // xRegions - Allocate up to three separate memory regions for access by
* // the task, with appropriate access permissions. Different processors have
* // different memory alignment requirements - refer to the FreeRTOS documentation
* // for full information.
* {
* // Base address Length Parameters
* { cReadWriteArray, 32, portMPU_REGION_READ_WRITE },
* { cReadOnlyArray, 32, portMPU_REGION_READ_ONLY },
* { cPrivilegedOnlyAccessArray, 128, portMPU_REGION_PRIVILEGED_READ_WRITE }
* }
* };
*
* int main( void )
* {
* TaskHandle_t xHandle;
*
* // Create a task from the const structure defined above. The task handle
* // is requested (the second parameter is not NULL) but in this case just for
* // demonstration purposes as its not actually used.
* xTaskCreateRestricted( &xRegTest1Parameters, &xHandle );
*
* // Start the scheduler.
* vTaskStartScheduler();
*
* // Will only get here if there was insufficient memory to create the idle
* // and/or timer task.
* for( ;; );
* }
* @endcode
* \defgroup xTaskCreateRestricted xTaskCreateRestricted
* \ingroup Tasks
*/
#if ( portUSING_MPU_WRAPPERS == 1 )
BaseType_t xTaskCreateRestricted( const TaskParameters_t * const pxTaskDefinition,
TaskHandle_t * pxCreatedTask ) PRIVILEGED_FUNCTION;
#endif
#if ( ( portUSING_MPU_WRAPPERS == 1 ) && ( configNUMBER_OF_CORES > 1 ) && ( configUSE_CORE_AFFINITY == 1 ) )
BaseType_t xTaskCreateRestrictedAffinitySet( const TaskParameters_t * const pxTaskDefinition,
UBaseType_t uxCoreAffinityMask,
TaskHandle_t * pxCreatedTask ) PRIVILEGED_FUNCTION;
#endif
/**
* task. h
* @code{c}
* BaseType_t xTaskCreateRestrictedStatic( TaskParameters_t *pxTaskDefinition, TaskHandle_t *pxCreatedTask );
* @endcode
*
* Only available when configSUPPORT_STATIC_ALLOCATION is set to 1.
*
* xTaskCreateRestrictedStatic() should only be used in systems that include an
* MPU implementation.
*
* Internally, within the FreeRTOS implementation, tasks use two blocks of
* memory. The first block is used to hold the task's data structures. The
* second block is used by the task as its stack. If a task is created using
* xTaskCreateRestricted() then the stack is provided by the application writer,
* and the memory used to hold the task's data structure is automatically
* dynamically allocated inside the xTaskCreateRestricted() function. If a task
* is created using xTaskCreateRestrictedStatic() then the application writer
* must provide the memory used to hold the task's data structures too.
* xTaskCreateRestrictedStatic() therefore allows a memory protected task to be
* created without using any dynamic memory allocation.
*
* @param pxTaskDefinition Pointer to a structure that contains a member
* for each of the normal xTaskCreate() parameters (see the xTaskCreate() API
* documentation) plus an optional stack buffer and the memory region
* definitions. If configSUPPORT_STATIC_ALLOCATION is set to 1 the structure
* contains an additional member, which is used to point to a variable of type
* StaticTask_t - which is then used to hold the task's data structure.
*
* @param pxCreatedTask Used to pass back a handle by which the created task
* can be referenced.
*
* @return pdPASS if the task was successfully created and added to a ready
* list, otherwise an error code defined in the file projdefs.h
*
* Example usage:
* @code{c}
* // Create an TaskParameters_t structure that defines the task to be created.
* // The StaticTask_t variable is only included in the structure when
* // configSUPPORT_STATIC_ALLOCATION is set to 1. The PRIVILEGED_DATA macro can
* // be used to force the variable into the RTOS kernel's privileged data area.
* static PRIVILEGED_DATA StaticTask_t xTaskBuffer;
* static const TaskParameters_t xCheckTaskParameters =
* {
* vATask, // pvTaskCode - the function that implements the task.
* "ATask", // pcName - just a text name for the task to assist debugging.
* 100, // uxStackDepth - the stack size DEFINED IN WORDS.
* NULL, // pvParameters - passed into the task function as the function parameters.
* ( 1UL | portPRIVILEGE_BIT ),// uxPriority - task priority, set the portPRIVILEGE_BIT if the task should run in a privileged state.
* cStackBuffer,// puxStackBuffer - the buffer to be used as the task stack.
*
* // xRegions - Allocate up to three separate memory regions for access by
* // the task, with appropriate access permissions. Different processors have
* // different memory alignment requirements - refer to the FreeRTOS documentation
* // for full information.
* {
* // Base address Length Parameters
* { cReadWriteArray, 32, portMPU_REGION_READ_WRITE },
* { cReadOnlyArray, 32, portMPU_REGION_READ_ONLY },
* { cPrivilegedOnlyAccessArray, 128, portMPU_REGION_PRIVILEGED_READ_WRITE }
* }
*
* &xTaskBuffer; // Holds the task's data structure.
* };
*
* int main( void )
* {
* TaskHandle_t xHandle;
*
* // Create a task from the const structure defined above. The task handle
* // is requested (the second parameter is not NULL) but in this case just for
* // demonstration purposes as its not actually used.
* xTaskCreateRestrictedStatic( &xRegTest1Parameters, &xHandle );
*
* // Start the scheduler.
* vTaskStartScheduler();
*
* // Will only get here if there was insufficient memory to create the idle
* // and/or timer task.
* for( ;; );
* }
* @endcode
* \defgroup xTaskCreateRestrictedStatic xTaskCreateRestrictedStatic
* \ingroup Tasks
*/
#if ( ( portUSING_MPU_WRAPPERS == 1 ) && ( configSUPPORT_STATIC_ALLOCATION == 1 ) )
BaseType_t xTaskCreateRestrictedStatic( const TaskParameters_t * const pxTaskDefinition,
TaskHandle_t * pxCreatedTask ) PRIVILEGED_FUNCTION;
#endif
#if ( ( portUSING_MPU_WRAPPERS == 1 ) && ( configSUPPORT_STATIC_ALLOCATION == 1 ) && ( configNUMBER_OF_CORES > 1 ) && ( configUSE_CORE_AFFINITY == 1 ) )
BaseType_t xTaskCreateRestrictedStaticAffinitySet( const TaskParameters_t * const pxTaskDefinition,
UBaseType_t uxCoreAffinityMask,
TaskHandle_t * pxCreatedTask ) PRIVILEGED_FUNCTION;
#endif
/**
* task. h
* @code{c}
* void vTaskAllocateMPURegions( TaskHandle_t xTask, const MemoryRegion_t * const pxRegions );
* @endcode
*
* Memory regions are assigned to a restricted task when the task is created by
* a call to xTaskCreateRestricted(). These regions can be redefined using
* vTaskAllocateMPURegions().
*
* @param xTaskToModify The handle of the task being updated.
*
* @param[in] pxRegions A pointer to a MemoryRegion_t structure that contains the
* new memory region definitions.
*
* Example usage:
* @code{c}
* // Define an array of MemoryRegion_t structures that configures an MPU region
* // allowing read/write access for 1024 bytes starting at the beginning of the
* // ucOneKByte array. The other two of the maximum 3 definable regions are
* // unused so set to zero.
* static const MemoryRegion_t xAltRegions[ portNUM_CONFIGURABLE_REGIONS ] =
* {
* // Base address Length Parameters
* { ucOneKByte, 1024, portMPU_REGION_READ_WRITE },
* { 0, 0, 0 },
* { 0, 0, 0 }
* };
*
* void vATask( void *pvParameters )
* {
* // This task was created such that it has access to certain regions of
* // memory as defined by the MPU configuration. At some point it is
* // desired that these MPU regions are replaced with that defined in the
* // xAltRegions const struct above. Use a call to vTaskAllocateMPURegions()
* // for this purpose. NULL is used as the task handle to indicate that this
* // function should modify the MPU regions of the calling task.
* vTaskAllocateMPURegions( NULL, xAltRegions );
*
* // Now the task can continue its function, but from this point on can only
* // access its stack and the ucOneKByte array (unless any other statically
* // defined or shared regions have been declared elsewhere).
* }
* @endcode
* \defgroup vTaskAllocateMPURegions vTaskAllocateMPURegions
* \ingroup Tasks
*/
#if ( portUSING_MPU_WRAPPERS == 1 )
void vTaskAllocateMPURegions( TaskHandle_t xTaskToModify,
const MemoryRegion_t * const pxRegions ) PRIVILEGED_FUNCTION;
#endif
/**
* task. h
* @code{c}
* void vTaskDelete( TaskHandle_t xTaskToDelete );
* @endcode
*
* INCLUDE_vTaskDelete must be defined as 1 for this function to be available.
* See the configuration section for more information.
*
* Remove a task from the RTOS real time kernel's management. The task being
* deleted will be removed from all ready, blocked, suspended and event lists.
*
* NOTE: The idle task is responsible for freeing the kernel allocated
* memory from tasks that have been deleted. It is therefore important that
* the idle task is not starved of microcontroller processing time if your
* application makes any calls to vTaskDelete (). Memory allocated by the
* task code is not automatically freed, and should be freed before the task
* is deleted.
*
* See the demo application file death.c for sample code that utilises
* vTaskDelete ().
*
* @param xTaskToDelete The handle of the task to be deleted. Passing NULL will
* cause the calling task to be deleted.
*
* Example usage:
* @code{c}
* void vOtherFunction( void )
* {
* TaskHandle_t xHandle;
*
* // Create the task, storing the handle.
* xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
*
* // Use the handle to delete the task.
* vTaskDelete( xHandle );
* }
* @endcode
* \defgroup vTaskDelete vTaskDelete
* \ingroup Tasks
*/
void vTaskDelete( TaskHandle_t xTaskToDelete ) PRIVILEGED_FUNCTION;
/*-----------------------------------------------------------
* TASK CONTROL API
*----------------------------------------------------------*/
/**
* task. h
* @code{c}
* void vTaskDelay( const TickType_t xTicksToDelay );
* @endcode
*
* Delay a task for a given number of ticks. The actual time that the
* task remains blocked depends on the tick rate. The constant
* portTICK_PERIOD_MS can be used to calculate real time from the tick
* rate - with the resolution of one tick period.
*
* INCLUDE_vTaskDelay must be defined as 1 for this function to be available.
* See the configuration section for more information.
*
*
* vTaskDelay() specifies a time at which the task wishes to unblock relative to
* the time at which vTaskDelay() is called. For example, specifying a block
* period of 100 ticks will cause the task to unblock 100 ticks after
* vTaskDelay() is called. vTaskDelay() does not therefore provide a good method
* of controlling the frequency of a periodic task as the path taken through the
* code, as well as other task and interrupt activity, will affect the frequency
* at which vTaskDelay() gets called and therefore the time at which the task
* next executes. See xTaskDelayUntil() for an alternative API function designed
* to facilitate fixed frequency execution. It does this by specifying an
* absolute time (rather than a relative time) at which the calling task should
* unblock.
*
* @param xTicksToDelay The amount of time, in tick periods, that
* the calling task should block.
*
* Example usage:
*
* void vTaskFunction( void * pvParameters )
* {
* // Block for 500ms.
* const TickType_t xDelay = 500 / portTICK_PERIOD_MS;
*
* for( ;; )
* {
* // Simply toggle the LED every 500ms, blocking between each toggle.
* vToggleLED();
* vTaskDelay( xDelay );
* }
* }
*
* \defgroup vTaskDelay vTaskDelay
* \ingroup TaskCtrl
*/
void vTaskDelay( const TickType_t xTicksToDelay ) PRIVILEGED_FUNCTION;
/**
* task. h
* @code{c}
* BaseType_t xTaskDelayUntil( TickType_t *pxPreviousWakeTime, const TickType_t xTimeIncrement );
* @endcode
*
* INCLUDE_xTaskDelayUntil must be defined as 1 for this function to be available.
* See the configuration section for more information.
*
* Delay a task until a specified time. This function can be used by periodic
* tasks to ensure a constant execution frequency.
*
* This function differs from vTaskDelay () in one important aspect: vTaskDelay () will
* cause a task to block for the specified number of ticks from the time vTaskDelay () is
* called. It is therefore difficult to use vTaskDelay () by itself to generate a fixed
* execution frequency as the time between a task starting to execute and that task
* calling vTaskDelay () may not be fixed [the task may take a different path though the
* code between calls, or may get interrupted or preempted a different number of times
* each time it executes].
*
* Whereas vTaskDelay () specifies a wake time relative to the time at which the function
* is called, xTaskDelayUntil () specifies the absolute (exact) time at which it wishes to
* unblock.
*
* The macro pdMS_TO_TICKS() can be used to calculate the number of ticks from a
* time specified in milliseconds with a resolution of one tick period.
*
* @param pxPreviousWakeTime Pointer to a variable that holds the time at which the
* task was last unblocked. The variable must be initialised with the current time
* prior to its first use (see the example below). Following this the variable is
* automatically updated within xTaskDelayUntil ().
*
* @param xTimeIncrement The cycle time period. The task will be unblocked at
* time *pxPreviousWakeTime + xTimeIncrement. Calling xTaskDelayUntil with the
* same xTimeIncrement parameter value will cause the task to execute with
* a fixed interface period.
*
* @return Value which can be used to check whether the task was actually delayed.
* Will be pdTRUE if the task way delayed and pdFALSE otherwise. A task will not
* be delayed if the next expected wake time is in the past.
*
* Example usage:
* @code{c}
* // Perform an action every 10 ticks.
* void vTaskFunction( void * pvParameters )
* {
* TickType_t xLastWakeTime;
* const TickType_t xFrequency = 10;
* BaseType_t xWasDelayed;
*
* // Initialise the xLastWakeTime variable with the current time.
* xLastWakeTime = xTaskGetTickCount ();
* for( ;; )
* {
* // Wait for the next cycle.
* xWasDelayed = xTaskDelayUntil( &xLastWakeTime, xFrequency );
*
* // Perform action here. xWasDelayed value can be used to determine
* // whether a deadline was missed if the code here took too long.
* }
* }
* @endcode
* \defgroup xTaskDelayUntil xTaskDelayUntil
* \ingroup TaskCtrl
*/
BaseType_t xTaskDelayUntil( TickType_t * const pxPreviousWakeTime,
const TickType_t xTimeIncrement ) PRIVILEGED_FUNCTION;
/*
* vTaskDelayUntil() is the older version of xTaskDelayUntil() and does not
* return a value.
*/
#define vTaskDelayUntil( pxPreviousWakeTime, xTimeIncrement ) \
do { \
( void ) xTaskDelayUntil( ( pxPreviousWakeTime ), ( xTimeIncrement ) ); \
} while( 0 )
/**
* task. h
* @code{c}
* BaseType_t xTaskAbortDelay( TaskHandle_t xTask );
* @endcode
*
* INCLUDE_xTaskAbortDelay must be defined as 1 in FreeRTOSConfig.h for this
* function to be available.
*
* A task will enter the Blocked state when it is waiting for an event. The
* event it is waiting for can be a temporal event (waiting for a time), such
* as when vTaskDelay() is called, or an event on an object, such as when
* xQueueReceive() or ulTaskNotifyTake() is called. If the handle of a task
* that is in the Blocked state is used in a call to xTaskAbortDelay() then the
* task will leave the Blocked state, and return from whichever function call
* placed the task into the Blocked state.
*
* There is no 'FromISR' version of this function as an interrupt would need to
* know which object a task was blocked on in order to know which actions to
* take. For example, if the task was blocked on a queue the interrupt handler
* would then need to know if the queue was locked.
*
* @param xTask The handle of the task to remove from the Blocked state.
*
* @return If the task referenced by xTask was not in the Blocked state then
* pdFAIL is returned. Otherwise pdPASS is returned.
*
* \defgroup xTaskAbortDelay xTaskAbortDelay
* \ingroup TaskCtrl
*/
#if ( INCLUDE_xTaskAbortDelay == 1 )
BaseType_t xTaskAbortDelay( TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
#endif
/**
* task. h
* @code{c}
* UBaseType_t uxTaskPriorityGet( const TaskHandle_t xTask );
* @endcode
*
* INCLUDE_uxTaskPriorityGet must be defined as 1 for this function to be available.
* See the configuration section for more information.
*
* Obtain the priority of any task.
*
* @param xTask Handle of the task to be queried. Passing a NULL
* handle results in the priority of the calling task being returned.
*
* @return The priority of xTask.
*
* Example usage:
* @code{c}
* void vAFunction( void )
* {
* TaskHandle_t xHandle;
*
* // Create a task, storing the handle.
* xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
*
* // ...
*
* // Use the handle to obtain the priority of the created task.
* // It was created with tskIDLE_PRIORITY, but may have changed
* // it itself.
* if( uxTaskPriorityGet( xHandle ) != tskIDLE_PRIORITY )
* {