OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [freertos-6.1.1/] [Source/] [include/] [task.h] - Blame information for rev 609

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 572 jeremybenn
/*
2
    FreeRTOS V6.1.1 - Copyright (C) 2011 Real Time Engineers Ltd.
3
 
4
    ***************************************************************************
5
    *                                                                         *
6
    * If you are:                                                             *
7
    *                                                                         *
8
    *    + New to FreeRTOS,                                                   *
9
    *    + Wanting to learn FreeRTOS or multitasking in general quickly       *
10
    *    + Looking for basic training,                                        *
11
    *    + Wanting to improve your FreeRTOS skills and productivity           *
12
    *                                                                         *
13
    * then take a look at the FreeRTOS books - available as PDF or paperback  *
14
    *                                                                         *
15
    *        "Using the FreeRTOS Real Time Kernel - a Practical Guide"        *
16
    *                  http://www.FreeRTOS.org/Documentation                  *
17
    *                                                                         *
18
    * A pdf reference manual is also available.  Both are usually delivered   *
19
    * to your inbox within 20 minutes to two hours when purchased between 8am *
20
    * and 8pm GMT (although please allow up to 24 hours in case of            *
21
    * exceptional circumstances).  Thank you for your support!                *
22
    *                                                                         *
23
    ***************************************************************************
24
 
25
    This file is part of the FreeRTOS distribution.
26
 
27
    FreeRTOS is free software; you can redistribute it and/or modify it under
28
    the terms of the GNU General Public License (version 2) as published by the
29
    Free Software Foundation AND MODIFIED BY the FreeRTOS exception.
30
    ***NOTE*** The exception to the GPL is included to allow you to distribute
31
    a combined work that includes FreeRTOS without being obliged to provide the
32
    source code for proprietary components outside of the FreeRTOS kernel.
33
    FreeRTOS is distributed in the hope that it will be useful, but WITHOUT
34
    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
35
    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
36
    more details. You should have received a copy of the GNU General Public
37
    License and the FreeRTOS license exception along with FreeRTOS; if not it
38
    can be viewed here: http://www.freertos.org/a00114.html and also obtained
39
    by writing to Richard Barry, contact details for whom are available on the
40
    FreeRTOS WEB site.
41
 
42
    1 tab == 4 spaces!
43
 
44
    http://www.FreeRTOS.org - Documentation, latest information, license and
45
    contact details.
46
 
47
    http://www.SafeRTOS.com - A version that is certified for use in safety
48
    critical systems.
49
 
50
    http://www.OpenRTOS.com - Commercial support, development, porting,
51
    licensing and training services.
52
*/
53
 
54
 
55
#ifndef INC_FREERTOS_H
56
        #error "include FreeRTOS.h must appear in source files before include task.h"
57
#endif
58
 
59
 
60
 
61
#ifndef TASK_H
62
#define TASK_H
63
 
64
#include "portable.h"
65
#include "list.h"
66
 
67
#ifdef __cplusplus
68
extern "C" {
69
#endif
70
 
71
/*-----------------------------------------------------------
72
 * MACROS AND DEFINITIONS
73
 *----------------------------------------------------------*/
74
 
75
#define tskKERNEL_VERSION_NUMBER "V6.1.1"
76
 
77
/**
78
 * task. h
79
 *
80
 * Type by which tasks are referenced.  For example, a call to xTaskCreate
81
 * returns (via a pointer parameter) an xTaskHandle variable that can then
82
 * be used as a parameter to vTaskDelete to delete the task.
83
 *
84
 * \page xTaskHandle xTaskHandle
85
 * \ingroup Tasks
86
 */
87
typedef void * xTaskHandle;
88
 
89
/*
90
 * Used internally only.
91
 */
92
typedef struct xTIME_OUT
93
{
94
        portBASE_TYPE xOverflowCount;
95
        portTickType  xTimeOnEntering;
96
} xTimeOutType;
97
 
98
/*
99
 * Defines the memory ranges allocated to the task when an MPU is used.
100
 */
101
typedef struct xMEMORY_REGION
102
{
103
        void *pvBaseAddress;
104
        unsigned long ulLengthInBytes;
105
        unsigned long ulParameters;
106
} xMemoryRegion;
107
 
108
/*
109
 * Parameters required to create an MPU protected task.
110
 */
111
typedef struct xTASK_PARAMTERS
112
{
113
        pdTASK_CODE pvTaskCode;
114
        const signed char * const pcName;
115
        unsigned short usStackDepth;
116
        void *pvParameters;
117
        unsigned portBASE_TYPE uxPriority;
118
        portSTACK_TYPE *puxStackBuffer;
119
        xMemoryRegion xRegions[ portNUM_CONFIGURABLE_REGIONS ];
120
} xTaskParameters;
121
 
122
/*
123
 * Defines the priority used by the idle task.  This must not be modified.
124
 *
125
 * \ingroup TaskUtils
126
 */
127
#define tskIDLE_PRIORITY                        ( ( unsigned portBASE_TYPE ) 0 )
128
 
129
/**
130
 * task. h
131
 *
132
 * Macro for forcing a context switch.
133
 *
134
 * \page taskYIELD taskYIELD
135
 * \ingroup SchedulerControl
136
 */
137
#define taskYIELD()                                     portYIELD()
138
 
139
/**
140
 * task. h
141
 *
142
 * Macro to mark the start of a critical code region.  Preemptive context
143
 * switches cannot occur when in a critical region.
144
 *
145
 * NOTE: This may alter the stack (depending on the portable implementation)
146
 * so must be used with care!
147
 *
148
 * \page taskENTER_CRITICAL taskENTER_CRITICAL
149
 * \ingroup SchedulerControl
150
 */
151
#define taskENTER_CRITICAL()            portENTER_CRITICAL()
152
 
153
/**
154
 * task. h
155
 *
156
 * Macro to mark the end of a critical code region.  Preemptive context
157
 * switches cannot occur when in a critical region.
158
 *
159
 * NOTE: This may alter the stack (depending on the portable implementation)
160
 * so must be used with care!
161
 *
162
 * \page taskEXIT_CRITICAL taskEXIT_CRITICAL
163
 * \ingroup SchedulerControl
164
 */
165
#define taskEXIT_CRITICAL()                     portEXIT_CRITICAL()
166
 
167
/**
168
 * task. h
169
 *
170
 * Macro to disable all maskable interrupts.
171
 *
172
 * \page taskDISABLE_INTERRUPTS taskDISABLE_INTERRUPTS
173
 * \ingroup SchedulerControl
174
 */
175
#define taskDISABLE_INTERRUPTS()        portDISABLE_INTERRUPTS()
176
 
177
/**
178
 * task. h
179
 *
180
 * Macro to enable microcontroller interrupts.
181
 *
182
 * \page taskENABLE_INTERRUPTS taskENABLE_INTERRUPTS
183
 * \ingroup SchedulerControl
184
 */
185
#define taskENABLE_INTERRUPTS()         portENABLE_INTERRUPTS()
186
 
187
/* Definitions returned by xTaskGetSchedulerState(). */
188
#define taskSCHEDULER_NOT_STARTED       0
189
#define taskSCHEDULER_RUNNING           1
190
#define taskSCHEDULER_SUSPENDED         2
191
 
192
/*-----------------------------------------------------------
193
 * TASK CREATION API
194
 *----------------------------------------------------------*/
195
 
196
/**
197
 * task. h
198
 *<pre>
199
 portBASE_TYPE xTaskCreate(
200
                                                          pdTASK_CODE pvTaskCode,
201
                                                          const char * const pcName,
202
                                                          unsigned short usStackDepth,
203
                                                          void *pvParameters,
204
                                                          unsigned portBASE_TYPE uxPriority,
205
                                                          xTaskHandle *pvCreatedTask
206
                                                  );</pre>
207
 *
208
 * Create a new task and add it to the list of tasks that are ready to run.
209
 *
210
 * xTaskCreate() can only be used to create a task that has unrestricted
211
 * access to the entire microcontroller memory map.  Systems that include MPU
212
 * support can alternatively create an MPU constrained task using
213
 * xTaskCreateRestricted().
214
 *
215
 * @param pvTaskCode Pointer to the task entry function.  Tasks
216
 * must be implemented to never return (i.e. continuous loop).
217
 *
218
 * @param pcName A descriptive name for the task.  This is mainly used to
219
 * facilitate debugging.  Max length defined by tskMAX_TASK_NAME_LEN - default
220
 * is 16.
221
 *
222
 * @param usStackDepth The size of the task stack specified as the number of
223
 * variables the stack can hold - not the number of bytes.  For example, if
224
 * the stack is 16 bits wide and usStackDepth is defined as 100, 200 bytes
225
 * will be allocated for stack storage.
226
 *
227
 * @param pvParameters Pointer that will be used as the parameter for the task
228
 * being created.
229
 *
230
 * @param uxPriority The priority at which the task should run.  Systems that
231
 * include MPU support can optionally create tasks in a privileged (system)
232
 * mode by setting bit portPRIVILEGE_BIT of the priority parameter.  For
233
 * example, to create a privileged task at priority 2 the uxPriority parameter
234
 * should be set to ( 2 | portPRIVILEGE_BIT ).
235
 *
236
 * @param pvCreatedTask Used to pass back a handle by which the created task
237
 * can be referenced.
238
 *
239
 * @return pdPASS if the task was successfully created and added to a ready
240
 * list, otherwise an error code defined in the file errors. h
241
 *
242
 * Example usage:
243
   <pre>
244
 // Task to be created.
245
 void vTaskCode( void * pvParameters )
246
 {
247
         for( ;; )
248
         {
249
                 // Task code goes here.
250
         }
251
 }
252
 
253
 // Function that creates a task.
254
 void vOtherFunction( void )
255
 {
256
 static unsigned char ucParameterToPass;
257
 xTaskHandle xHandle;
258
 
259
         // Create the task, storing the handle.  Note that the passed parameter ucParameterToPass
260
         // must exist for the lifetime of the task, so in this case is declared static.  If it was just an
261
         // an automatic stack variable it might no longer exist, or at least have been corrupted, by the time
262
         // the new task attempts to access it.
263
         xTaskCreate( vTaskCode, "NAME", STACK_SIZE, &ucParameterToPass, tskIDLE_PRIORITY, &xHandle );
264
 
265
         // Use the handle to delete the task.
266
         vTaskDelete( xHandle );
267
 }
268
   </pre>
269
 * \defgroup xTaskCreate xTaskCreate
270
 * \ingroup Tasks
271
 */
272
#define xTaskCreate( pvTaskCode, pcName, usStackDepth, pvParameters, uxPriority, pxCreatedTask ) xTaskGenericCreate( ( pvTaskCode ), ( pcName ), ( usStackDepth ), ( pvParameters ), ( uxPriority ), ( pxCreatedTask ), ( NULL ), ( NULL ) )
273
 
274
/**
275
 * task. h
276
 *<pre>
277
 portBASE_TYPE xTaskCreateRestricted( xTaskParameters *pxTaskDefinition, xTaskHandle *pxCreatedTask );</pre>
278
 *
279
 * xTaskCreateRestricted() should only be used in systems that include an MPU
280
 * implementation.
281
 *
282
 * Create a new task and add it to the list of tasks that are ready to run.
283
 * The function parameters define the memory regions and associated access
284
 * permissions allocated to the task.
285
 *
286
 * @param pxTaskDefinition Pointer to a structure that contains a member
287
 * for each of the normal xTaskCreate() parameters (see the xTaskCreate() API
288
 * documentation) plus an optional stack buffer and the memory region
289
 * definitions.
290
 *
291
 * @param pxCreatedTask Used to pass back a handle by which the created task
292
 * can be referenced.
293
 *
294
 * @return pdPASS if the task was successfully created and added to a ready
295
 * list, otherwise an error code defined in the file errors. h
296
 *
297
 * Example usage:
298
   <pre>
299
// Create an xTaskParameters structure that defines the task to be created.
300
static const xTaskParameters xCheckTaskParameters =
301
{
302
        vATask,         // pvTaskCode - the function that implements the task.
303
        "ATask",        // pcName - just a text name for the task to assist debugging.
304
        100,            // usStackDepth - the stack size DEFINED IN WORDS.
305
        NULL,           // pvParameters - passed into the task function as the function parameters.
306
        ( 1UL | portPRIVILEGE_BIT ),// uxPriority - task priority, set the portPRIVILEGE_BIT if the task should run in a privileged state.
307
        cStackBuffer,// puxStackBuffer - the buffer to be used as the task stack.
308
 
309
        // xRegions - Allocate up to three separate memory regions for access by
310
        // the task, with appropriate access permissions.  Different processors have
311
        // different memory alignment requirements - refer to the FreeRTOS documentation
312
        // for full information.
313
        {
314
                // Base address                                 Length  Parameters
315
        { cReadWriteArray,                              32,             portMPU_REGION_READ_WRITE },
316
        { cReadOnlyArray,                               32,             portMPU_REGION_READ_ONLY },
317
        { cPrivilegedOnlyAccessArray,   128,    portMPU_REGION_PRIVILEGED_READ_WRITE }
318
        }
319
};
320
 
321
int main( void )
322
{
323
xTaskHandle xHandle;
324
 
325
        // Create a task from the const structure defined above.  The task handle
326
        // is requested (the second parameter is not NULL) but in this case just for
327
        // demonstration purposes as its not actually used.
328
        xTaskCreateRestricted( &xRegTest1Parameters, &xHandle );
329
 
330
        // Start the scheduler.
331
        vTaskStartScheduler();
332
 
333
        // Will only get here if there was insufficient memory to create the idle
334
        // task.
335
        for( ;; );
336
}
337
   </pre>
338
 * \defgroup xTaskCreateRestricted xTaskCreateRestricted
339
 * \ingroup Tasks
340
 */
341
#define xTaskCreateRestricted( x, pxCreatedTask ) xTaskGenericCreate( ((x)->pvTaskCode), ((x)->pcName), ((x)->usStackDepth), ((x)->pvParameters), ((x)->uxPriority), (pxCreatedTask), ((x)->puxStackBuffer), ((x)->xRegions) )
342
 
343
/**
344
 * task. h
345
 *<pre>
346
 void vTaskAllocateMPURegions( xTaskHandle xTask, const xMemoryRegion * const pxRegions );</pre>
347
 *
348
 * Memory regions are assigned to a restricted task when the task is created by
349
 * a call to xTaskCreateRestricted().  These regions can be redefined using
350
 * vTaskAllocateMPURegions().
351
 *
352
 * @param xTask The handle of the task being updated.
353
 *
354
 * @param xRegions A pointer to an xMemoryRegion structure that contains the
355
 * new memory region definitions.
356
 *
357
 * Example usage:
358
   <pre>
359
// Define an array of xMemoryRegion structures that configures an MPU region
360
// allowing read/write access for 1024 bytes starting at the beginning of the
361
// ucOneKByte array.  The other two of the maximum 3 definable regions are
362
// unused so set to zero.
363
static const xMemoryRegion xAltRegions[ portNUM_CONFIGURABLE_REGIONS ] =
364
{
365
        // Base address         Length          Parameters
366
        { ucOneKByte,           1024,           portMPU_REGION_READ_WRITE },
367
        { 0,                            0,                      0 },
368
        { 0,                            0,                      0 }
369
};
370
 
371
void vATask( void *pvParameters )
372
{
373
        // This task was created such that it has access to certain regions of
374
        // memory as defined by the MPU configuration.  At some point it is
375
        // desired that these MPU regions are replaced with that defined in the
376
        // xAltRegions const struct above.  Use a call to vTaskAllocateMPURegions()
377
        // for this purpose.  NULL is used as the task handle to indicate that this
378
        // function should modify the MPU regions of the calling task.
379
        vTaskAllocateMPURegions( NULL, xAltRegions );
380
 
381
        // Now the task can continue its function, but from this point on can only
382
        // access its stack and the ucOneKByte array (unless any other statically
383
        // defined or shared regions have been declared elsewhere).
384
}
385
   </pre>
386
 * \defgroup xTaskCreateRestricted xTaskCreateRestricted
387
 * \ingroup Tasks
388
 */
389
void vTaskAllocateMPURegions( xTaskHandle xTask, const xMemoryRegion * const pxRegions ) PRIVILEGED_FUNCTION;
390
 
391
/**
392
 * task. h
393
 * <pre>void vTaskDelete( xTaskHandle pxTask );</pre>
394
 *
395
 * INCLUDE_vTaskDelete must be defined as 1 for this function to be available.
396
 * See the configuration section for more information.
397
 *
398
 * Remove a task from the RTOS real time kernels management.  The task being
399
 * deleted will be removed from all ready, blocked, suspended and event lists.
400
 *
401
 * NOTE:  The idle task is responsible for freeing the kernel allocated
402
 * memory from tasks that have been deleted.  It is therefore important that
403
 * the idle task is not starved of microcontroller processing time if your
404
 * application makes any calls to vTaskDelete ().  Memory allocated by the
405
 * task code is not automatically freed, and should be freed before the task
406
 * is deleted.
407
 *
408
 * See the demo application file death.c for sample code that utilises
409
 * vTaskDelete ().
410
 *
411
 * @param pxTask The handle of the task to be deleted.  Passing NULL will
412
 * cause the calling task to be deleted.
413
 *
414
 * Example usage:
415
   <pre>
416
 void vOtherFunction( void )
417
 {
418
 xTaskHandle xHandle;
419
 
420
         // Create the task, storing the handle.
421
         xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
422
 
423
         // Use the handle to delete the task.
424
         vTaskDelete( xHandle );
425
 }
426
   </pre>
427
 * \defgroup vTaskDelete vTaskDelete
428
 * \ingroup Tasks
429
 */
430
void vTaskDelete( xTaskHandle pxTask ) PRIVILEGED_FUNCTION;
431
 
432
 
433
/*-----------------------------------------------------------
434
 * TASK CONTROL API
435
 *----------------------------------------------------------*/
436
 
437
/**
438
 * task. h
439
 * <pre>void vTaskDelay( portTickType xTicksToDelay );</pre>
440
 *
441
 * Delay a task for a given number of ticks.  The actual time that the
442
 * task remains blocked depends on the tick rate.  The constant
443
 * portTICK_RATE_MS can be used to calculate real time from the tick
444
 * rate - with the resolution of one tick period.
445
 *
446
 * INCLUDE_vTaskDelay must be defined as 1 for this function to be available.
447
 * See the configuration section for more information.
448
 *
449
 *
450
 * vTaskDelay() specifies a time at which the task wishes to unblock relative to
451
 * the time at which vTaskDelay() is called.  For example, specifying a block
452
 * period of 100 ticks will cause the task to unblock 100 ticks after
453
 * vTaskDelay() is called.  vTaskDelay() does not therefore provide a good method
454
 * of controlling the frequency of a cyclical task as the path taken through the
455
 * code, as well as other task and interrupt activity, will effect the frequency
456
 * at which vTaskDelay() gets called and therefore the time at which the task
457
 * next executes.  See vTaskDelayUntil() for an alternative API function designed
458
 * to facilitate fixed frequency execution.  It does this by specifying an
459
 * absolute time (rather than a relative time) at which the calling task should
460
 * unblock.
461
 *
462
 * @param xTicksToDelay The amount of time, in tick periods, that
463
 * the calling task should block.
464
 *
465
 * Example usage:
466
 
467
 void vTaskFunction( void * pvParameters )
468
 {
469
 void vTaskFunction( void * pvParameters )
470
 {
471
 // Block for 500ms.
472
 const portTickType xDelay = 500 / portTICK_RATE_MS;
473
 
474
         for( ;; )
475
         {
476
                 // Simply toggle the LED every 500ms, blocking between each toggle.
477
                 vToggleLED();
478
                 vTaskDelay( xDelay );
479
         }
480
 }
481
 
482
 * \defgroup vTaskDelay vTaskDelay
483
 * \ingroup TaskCtrl
484
 */
485
void vTaskDelay( portTickType xTicksToDelay ) PRIVILEGED_FUNCTION;
486
 
487
/**
488
 * task. h
489
 * <pre>void vTaskDelayUntil( portTickType *pxPreviousWakeTime, portTickType xTimeIncrement );</pre>
490
 *
491
 * INCLUDE_vTaskDelayUntil must be defined as 1 for this function to be available.
492
 * See the configuration section for more information.
493
 *
494
 * Delay a task until a specified time.  This function can be used by cyclical
495
 * tasks to ensure a constant execution frequency.
496
 *
497
 * This function differs from vTaskDelay () in one important aspect:  vTaskDelay () will
498
 * cause a task to block for the specified number of ticks from the time vTaskDelay () is
499
 * called.  It is therefore difficult to use vTaskDelay () by itself to generate a fixed
500
 * execution frequency as the time between a task starting to execute and that task
501
 * calling vTaskDelay () may not be fixed [the task may take a different path though the
502
 * code between calls, or may get interrupted or preempted a different number of times
503
 * each time it executes].
504
 *
505
 * Whereas vTaskDelay () specifies a wake time relative to the time at which the function
506
 * is called, vTaskDelayUntil () specifies the absolute (exact) time at which it wishes to
507
 * unblock.
508
 *
509
 * The constant portTICK_RATE_MS can be used to calculate real time from the tick
510
 * rate - with the resolution of one tick period.
511
 *
512
 * @param pxPreviousWakeTime Pointer to a variable that holds the time at which the
513
 * task was last unblocked.  The variable must be initialised with the current time
514
 * prior to its first use (see the example below).  Following this the variable is
515
 * automatically updated within vTaskDelayUntil ().
516
 *
517
 * @param xTimeIncrement The cycle time period.  The task will be unblocked at
518
 * time *pxPreviousWakeTime + xTimeIncrement.  Calling vTaskDelayUntil with the
519
 * same xTimeIncrement parameter value will cause the task to execute with
520
 * a fixed interface period.
521
 *
522
 * Example usage:
523
   <pre>
524
 // Perform an action every 10 ticks.
525
 void vTaskFunction( void * pvParameters )
526
 {
527
 portTickType xLastWakeTime;
528
 const portTickType xFrequency = 10;
529
 
530
         // Initialise the xLastWakeTime variable with the current time.
531
         xLastWakeTime = xTaskGetTickCount ();
532
         for( ;; )
533
         {
534
                 // Wait for the next cycle.
535
                 vTaskDelayUntil( &xLastWakeTime, xFrequency );
536
 
537
                 // Perform action here.
538
         }
539
 }
540
   </pre>
541
 * \defgroup vTaskDelayUntil vTaskDelayUntil
542
 * \ingroup TaskCtrl
543
 */
544
void vTaskDelayUntil( portTickType * const pxPreviousWakeTime, portTickType xTimeIncrement ) PRIVILEGED_FUNCTION;
545
 
546
/**
547
 * task. h
548
 * <pre>unsigned portBASE_TYPE uxTaskPriorityGet( xTaskHandle pxTask );</pre>
549
 *
550
 * INCLUDE_xTaskPriorityGet must be defined as 1 for this function to be available.
551
 * See the configuration section for more information.
552
 *
553
 * Obtain the priority of any task.
554
 *
555
 * @param pxTask Handle of the task to be queried.  Passing a NULL
556
 * handle results in the priority of the calling task being returned.
557
 *
558
 * @return The priority of pxTask.
559
 *
560
 * Example usage:
561
   <pre>
562
 void vAFunction( void )
563
 {
564
 xTaskHandle xHandle;
565
 
566
         // Create a task, storing the handle.
567
         xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
568
 
569
         // ...
570
 
571
         // Use the handle to obtain the priority of the created task.
572
         // It was created with tskIDLE_PRIORITY, but may have changed
573
         // it itself.
574
         if( uxTaskPriorityGet( xHandle ) != tskIDLE_PRIORITY )
575
         {
576
                 // The task has changed it's priority.
577
         }
578
 
579
         // ...
580
 
581
         // Is our priority higher than the created task?
582
         if( uxTaskPriorityGet( xHandle ) < uxTaskPriorityGet( NULL ) )
583
         {
584
                 // Our priority (obtained using NULL handle) is higher.
585
         }
586
 }
587
   </pre>
588
 * \defgroup uxTaskPriorityGet uxTaskPriorityGet
589
 * \ingroup TaskCtrl
590
 */
591
unsigned portBASE_TYPE uxTaskPriorityGet( xTaskHandle pxTask ) PRIVILEGED_FUNCTION;
592
 
593
/**
594
 * task. h
595
 * <pre>void vTaskPrioritySet( xTaskHandle pxTask, unsigned portBASE_TYPE uxNewPriority );</pre>
596
 *
597
 * INCLUDE_vTaskPrioritySet must be defined as 1 for this function to be available.
598
 * See the configuration section for more information.
599
 *
600
 * Set the priority of any task.
601
 *
602
 * A context switch will occur before the function returns if the priority
603
 * being set is higher than the currently executing task.
604
 *
605
 * @param pxTask Handle to the task for which the priority is being set.
606
 * Passing a NULL handle results in the priority of the calling task being set.
607
 *
608
 * @param uxNewPriority The priority to which the task will be set.
609
 *
610
 * Example usage:
611
   <pre>
612
 void vAFunction( void )
613
 {
614
 xTaskHandle xHandle;
615
 
616
         // Create a task, storing the handle.
617
         xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
618
 
619
         // ...
620
 
621
         // Use the handle to raise the priority of the created task.
622
         vTaskPrioritySet( xHandle, tskIDLE_PRIORITY + 1 );
623
 
624
         // ...
625
 
626
         // Use a NULL handle to raise our priority to the same value.
627
         vTaskPrioritySet( NULL, tskIDLE_PRIORITY + 1 );
628
 }
629
   </pre>
630
 * \defgroup vTaskPrioritySet vTaskPrioritySet
631
 * \ingroup TaskCtrl
632
 */
633
void vTaskPrioritySet( xTaskHandle pxTask, unsigned portBASE_TYPE uxNewPriority ) PRIVILEGED_FUNCTION;
634
 
635
/**
636
 * task. h
637
 * <pre>void vTaskSuspend( xTaskHandle pxTaskToSuspend );</pre>
638
 *
639
 * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available.
640
 * See the configuration section for more information.
641
 *
642
 * Suspend any task.  When suspended a task will never get any microcontroller
643
 * processing time, no matter what its priority.
644
 *
645
 * Calls to vTaskSuspend are not accumulative -
646
 * i.e. calling vTaskSuspend () twice on the same task still only requires one
647
 * call to vTaskResume () to ready the suspended task.
648
 *
649
 * @param pxTaskToSuspend Handle to the task being suspended.  Passing a NULL
650
 * handle will cause the calling task to be suspended.
651
 *
652
 * Example usage:
653
   <pre>
654
 void vAFunction( void )
655
 {
656
 xTaskHandle xHandle;
657
 
658
         // Create a task, storing the handle.
659
         xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
660
 
661
         // ...
662
 
663
         // Use the handle to suspend the created task.
664
         vTaskSuspend( xHandle );
665
 
666
         // ...
667
 
668
         // The created task will not run during this period, unless
669
         // another task calls vTaskResume( xHandle ).
670
 
671
         //...
672
 
673
 
674
         // Suspend ourselves.
675
         vTaskSuspend( NULL );
676
 
677
         // We cannot get here unless another task calls vTaskResume
678
         // with our handle as the parameter.
679
 }
680
   </pre>
681
 * \defgroup vTaskSuspend vTaskSuspend
682
 * \ingroup TaskCtrl
683
 */
684
void vTaskSuspend( xTaskHandle pxTaskToSuspend ) PRIVILEGED_FUNCTION;
685
 
686
/**
687
 * task. h
688
 * <pre>void vTaskResume( xTaskHandle pxTaskToResume );</pre>
689
 *
690
 * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available.
691
 * See the configuration section for more information.
692
 *
693
 * Resumes a suspended task.
694
 *
695
 * A task that has been suspended by one of more calls to vTaskSuspend ()
696
 * will be made available for running again by a single call to
697
 * vTaskResume ().
698
 *
699
 * @param pxTaskToResume Handle to the task being readied.
700
 *
701
 * Example usage:
702
   <pre>
703
 void vAFunction( void )
704
 {
705
 xTaskHandle xHandle;
706
 
707
         // Create a task, storing the handle.
708
         xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
709
 
710
         // ...
711
 
712
         // Use the handle to suspend the created task.
713
         vTaskSuspend( xHandle );
714
 
715
         // ...
716
 
717
         // The created task will not run during this period, unless
718
         // another task calls vTaskResume( xHandle ).
719
 
720
         //...
721
 
722
 
723
         // Resume the suspended task ourselves.
724
         vTaskResume( xHandle );
725
 
726
         // The created task will once again get microcontroller processing
727
         // time in accordance with it priority within the system.
728
 }
729
   </pre>
730
 * \defgroup vTaskResume vTaskResume
731
 * \ingroup TaskCtrl
732
 */
733
void vTaskResume( xTaskHandle pxTaskToResume ) PRIVILEGED_FUNCTION;
734
 
735
/**
736
 * task. h
737
 * <pre>void xTaskResumeFromISR( xTaskHandle pxTaskToResume );</pre>
738
 *
739
 * INCLUDE_xTaskResumeFromISR must be defined as 1 for this function to be
740
 * available.  See the configuration section for more information.
741
 *
742
 * An implementation of vTaskResume() that can be called from within an ISR.
743
 *
744
 * A task that has been suspended by one of more calls to vTaskSuspend ()
745
 * will be made available for running again by a single call to
746
 * xTaskResumeFromISR ().
747
 *
748
 * @param pxTaskToResume Handle to the task being readied.
749
 *
750
 * \defgroup vTaskResumeFromISR vTaskResumeFromISR
751
 * \ingroup TaskCtrl
752
 */
753
portBASE_TYPE xTaskResumeFromISR( xTaskHandle pxTaskToResume ) PRIVILEGED_FUNCTION;
754
 
755
/*-----------------------------------------------------------
756
 * SCHEDULER CONTROL
757
 *----------------------------------------------------------*/
758
 
759
/**
760
 * task. h
761
 * <pre>void vTaskStartScheduler( void );</pre>
762
 *
763
 * Starts the real time kernel tick processing.  After calling the kernel
764
 * has control over which tasks are executed and when.  This function
765
 * does not return until an executing task calls vTaskEndScheduler ().
766
 *
767
 * At least one task should be created via a call to xTaskCreate ()
768
 * before calling vTaskStartScheduler ().  The idle task is created
769
 * automatically when the first application task is created.
770
 *
771
 * See the demo application file main.c for an example of creating
772
 * tasks and starting the kernel.
773
 *
774
 * Example usage:
775
   <pre>
776
 void vAFunction( void )
777
 {
778
         // Create at least one task before starting the kernel.
779
         xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL );
780
 
781
         // Start the real time kernel with preemption.
782
         vTaskStartScheduler ();
783
 
784
         // Will not get here unless a task calls vTaskEndScheduler ()
785
 }
786
   </pre>
787
 *
788
 * \defgroup vTaskStartScheduler vTaskStartScheduler
789
 * \ingroup SchedulerControl
790
 */
791
void vTaskStartScheduler( void ) PRIVILEGED_FUNCTION;
792
 
793
/**
794
 * task. h
795
 * <pre>void vTaskEndScheduler( void );</pre>
796
 *
797
 * Stops the real time kernel tick.  All created tasks will be automatically
798
 * deleted and multitasking (either preemptive or cooperative) will
799
 * stop.  Execution then resumes from the point where vTaskStartScheduler ()
800
 * was called, as if vTaskStartScheduler () had just returned.
801
 *
802
 * See the demo application file main. c in the demo/PC directory for an
803
 * example that uses vTaskEndScheduler ().
804
 *
805
 * vTaskEndScheduler () requires an exit function to be defined within the
806
 * portable layer (see vPortEndScheduler () in port. c for the PC port).  This
807
 * performs hardware specific operations such as stopping the kernel tick.
808
 *
809
 * vTaskEndScheduler () will cause all of the resources allocated by the
810
 * kernel to be freed - but will not free resources allocated by application
811
 * tasks.
812
 *
813
 * Example usage:
814
   <pre>
815
 void vTaskCode( void * pvParameters )
816
 {
817
         for( ;; )
818
         {
819
                 // Task code goes here.
820
 
821
                 // At some point we want to end the real time kernel processing
822
                 // so call ...
823
                 vTaskEndScheduler ();
824
         }
825
 }
826
 
827
 void vAFunction( void )
828
 {
829
         // Create at least one task before starting the kernel.
830
         xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL );
831
 
832
         // Start the real time kernel with preemption.
833
         vTaskStartScheduler ();
834
 
835
         // Will only get here when the vTaskCode () task has called
836
         // vTaskEndScheduler ().  When we get here we are back to single task
837
         // execution.
838
 }
839
   </pre>
840
 *
841
 * \defgroup vTaskEndScheduler vTaskEndScheduler
842
 * \ingroup SchedulerControl
843
 */
844
void vTaskEndScheduler( void ) PRIVILEGED_FUNCTION;
845
 
846
/**
847
 * task. h
848
 * <pre>void vTaskSuspendAll( void );</pre>
849
 *
850
 * Suspends all real time kernel activity while keeping interrupts (including the
851
 * kernel tick) enabled.
852
 *
853
 * After calling vTaskSuspendAll () the calling task will continue to execute
854
 * without risk of being swapped out until a call to xTaskResumeAll () has been
855
 * made.
856
 *
857
 * API functions that have the potential to cause a context switch (for example,
858
 * vTaskDelayUntil(), xQueueSend(), etc.) must not be called while the scheduler
859
 * is suspended.
860
 *
861
 * Example usage:
862
   <pre>
863
 void vTask1( void * pvParameters )
864
 {
865
         for( ;; )
866
         {
867
                 // Task code goes here.
868
 
869
                 // ...
870
 
871
                 // At some point the task wants to perform a long operation during
872
                 // which it does not want to get swapped out.  It cannot use
873
                 // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the
874
                 // operation may cause interrupts to be missed - including the
875
                 // ticks.
876
 
877
                 // Prevent the real time kernel swapping out the task.
878
                 vTaskSuspendAll ();
879
 
880
                 // Perform the operation here.  There is no need to use critical
881
                 // sections as we have all the microcontroller processing time.
882
                 // During this time interrupts will still operate and the kernel
883
                 // tick count will be maintained.
884
 
885
                 // ...
886
 
887
                 // The operation is complete.  Restart the kernel.
888
                 xTaskResumeAll ();
889
         }
890
 }
891
   </pre>
892
 * \defgroup vTaskSuspendAll vTaskSuspendAll
893
 * \ingroup SchedulerControl
894
 */
895
void vTaskSuspendAll( void ) PRIVILEGED_FUNCTION;
896
 
897
/**
898
 * task. h
899
 * <pre>char xTaskResumeAll( void );</pre>
900
 *
901
 * Resumes real time kernel activity following a call to vTaskSuspendAll ().
902
 * After a call to vTaskSuspendAll () the kernel will take control of which
903
 * task is executing at any time.
904
 *
905
 * @return If resuming the scheduler caused a context switch then pdTRUE is
906
 *                returned, otherwise pdFALSE is returned.
907
 *
908
 * Example usage:
909
   <pre>
910
 void vTask1( void * pvParameters )
911
 {
912
         for( ;; )
913
         {
914
                 // Task code goes here.
915
 
916
                 // ...
917
 
918
                 // At some point the task wants to perform a long operation during
919
                 // which it does not want to get swapped out.  It cannot use
920
                 // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the
921
                 // operation may cause interrupts to be missed - including the
922
                 // ticks.
923
 
924
                 // Prevent the real time kernel swapping out the task.
925
                 vTaskSuspendAll ();
926
 
927
                 // Perform the operation here.  There is no need to use critical
928
                 // sections as we have all the microcontroller processing time.
929
                 // During this time interrupts will still operate and the real
930
                 // time kernel tick count will be maintained.
931
 
932
                 // ...
933
 
934
                 // The operation is complete.  Restart the kernel.  We want to force
935
                 // a context switch - but there is no point if resuming the scheduler
936
                 // caused a context switch already.
937
                 if( !xTaskResumeAll () )
938
                 {
939
                          taskYIELD ();
940
                 }
941
         }
942
 }
943
   </pre>
944
 * \defgroup xTaskResumeAll xTaskResumeAll
945
 * \ingroup SchedulerControl
946
 */
947
signed portBASE_TYPE xTaskResumeAll( void ) PRIVILEGED_FUNCTION;
948
 
949
/**
950
 * task. h
951
 * <pre>signed portBASE_TYPE xTaskIsTaskSuspended( xTaskHandle xTask );</pre>
952
 *
953
 * Utility task that simply returns pdTRUE if the task referenced by xTask is
954
 * currently in the Suspended state, or pdFALSE if the task referenced by xTask
955
 * is in any other state.
956
 *
957
 */
958
signed portBASE_TYPE xTaskIsTaskSuspended( xTaskHandle xTask ) PRIVILEGED_FUNCTION;
959
 
960
/*-----------------------------------------------------------
961
 * TASK UTILITIES
962
 *----------------------------------------------------------*/
963
 
964
/**
965
 * task. h
966
 * <PRE>portTickType xTaskGetTickCount( void );</PRE>
967
 *
968
 * @return The count of ticks since vTaskStartScheduler was called.
969
 *
970
 * \page xTaskGetTickCount xTaskGetTickCount
971
 * \ingroup TaskUtils
972
 */
973
portTickType xTaskGetTickCount( void ) PRIVILEGED_FUNCTION;
974
 
975
/**
976
 * task. h
977
 * <PRE>portTickType xTaskGetTickCountFromISR( void );</PRE>
978
 *
979
 * @return The count of ticks since vTaskStartScheduler was called.
980
 *
981
 * This is a version of xTaskGetTickCount() that is safe to be called from an
982
 * ISR - provided that portTickType is the natural word size of the
983
 * microcontroller being used or interrupt nesting is either not supported or
984
 * not being used.
985
 *
986
 * \page xTaskGetTickCount xTaskGetTickCount
987
 * \ingroup TaskUtils
988
 */
989
portTickType xTaskGetTickCountFromISR( void ) PRIVILEGED_FUNCTION;
990
 
991
/**
992
 * task. h
993
 * <PRE>unsigned short uxTaskGetNumberOfTasks( void );</PRE>
994
 *
995
 * @return The number of tasks that the real time kernel is currently managing.
996
 * This includes all ready, blocked and suspended tasks.  A task that
997
 * has been deleted but not yet freed by the idle task will also be
998
 * included in the count.
999
 *
1000
 * \page uxTaskGetNumberOfTasks uxTaskGetNumberOfTasks
1001
 * \ingroup TaskUtils
1002
 */
1003
unsigned portBASE_TYPE uxTaskGetNumberOfTasks( void ) PRIVILEGED_FUNCTION;
1004
 
1005
/**
1006
 * task. h
1007
 * <PRE>void vTaskList( char *pcWriteBuffer );</PRE>
1008
 *
1009
 * configUSE_TRACE_FACILITY must be defined as 1 for this function to be
1010
 * available.  See the configuration section for more information.
1011
 *
1012
 * NOTE: This function will disable interrupts for its duration.  It is
1013
 * not intended for normal application runtime use but as a debug aid.
1014
 *
1015
 * Lists all the current tasks, along with their current state and stack
1016
 * usage high water mark.
1017
 *
1018
 * Tasks are reported as blocked ('B'), ready ('R'), deleted ('D') or
1019
 * suspended ('S').
1020
 *
1021
 * @param pcWriteBuffer A buffer into which the above mentioned details
1022
 * will be written, in ascii form.  This buffer is assumed to be large
1023
 * enough to contain the generated report.  Approximately 40 bytes per
1024
 * task should be sufficient.
1025
 *
1026
 * \page vTaskList vTaskList
1027
 * \ingroup TaskUtils
1028
 */
1029
void vTaskList( signed char *pcWriteBuffer ) PRIVILEGED_FUNCTION;
1030
 
1031
/**
1032
 * task. h
1033
 * <PRE>void vTaskGetRunTimeStats( char *pcWriteBuffer );</PRE>
1034
 *
1035
 * configGENERATE_RUN_TIME_STATS must be defined as 1 for this function
1036
 * to be available.  The application must also then provide definitions
1037
 * for portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and
1038
 * portGET_RUN_TIME_COUNTER_VALUE to configure a peripheral timer/counter
1039
 * and return the timers current count value respectively.  The counter
1040
 * should be at least 10 times the frequency of the tick count.
1041
 *
1042
 * NOTE: This function will disable interrupts for its duration.  It is
1043
 * not intended for normal application runtime use but as a debug aid.
1044
 *
1045
 * Setting configGENERATE_RUN_TIME_STATS to 1 will result in a total
1046
 * accumulated execution time being stored for each task.  The resolution
1047
 * of the accumulated time value depends on the frequency of the timer
1048
 * configured by the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() macro.
1049
 * Calling vTaskGetRunTimeStats() writes the total execution time of each
1050
 * task into a buffer, both as an absolute count value and as a percentage
1051
 * of the total system execution time.
1052
 *
1053
 * @param pcWriteBuffer A buffer into which the execution times will be
1054
 * written, in ascii form.  This buffer is assumed to be large enough to
1055
 * contain the generated report.  Approximately 40 bytes per task should
1056
 * be sufficient.
1057
 *
1058
 * \page vTaskGetRunTimeStats vTaskGetRunTimeStats
1059
 * \ingroup TaskUtils
1060
 */
1061
void vTaskGetRunTimeStats( signed char *pcWriteBuffer ) PRIVILEGED_FUNCTION;
1062
 
1063
/**
1064
 * task. h
1065
 * <PRE>void vTaskStartTrace( char * pcBuffer, unsigned portBASE_TYPE uxBufferSize );</PRE>
1066
 *
1067
 * Starts a real time kernel activity trace.  The trace logs the identity of
1068
 * which task is running when.
1069
 *
1070
 * The trace file is stored in binary format.  A separate DOS utility called
1071
 * convtrce.exe is used to convert this into a tab delimited text file which
1072
 * can be viewed and plotted in a spread sheet.
1073
 *
1074
 * @param pcBuffer The buffer into which the trace will be written.
1075
 *
1076
 * @param ulBufferSize The size of pcBuffer in bytes.  The trace will continue
1077
 * until either the buffer in full, or ulTaskEndTrace () is called.
1078
 *
1079
 * \page vTaskStartTrace vTaskStartTrace
1080
 * \ingroup TaskUtils
1081
 */
1082
void vTaskStartTrace( signed char * pcBuffer, unsigned long ulBufferSize ) PRIVILEGED_FUNCTION;
1083
 
1084
/**
1085
 * task. h
1086
 * <PRE>unsigned long ulTaskEndTrace( void );</PRE>
1087
 *
1088
 * Stops a kernel activity trace.  See vTaskStartTrace ().
1089
 *
1090
 * @return The number of bytes that have been written into the trace buffer.
1091
 *
1092
 * \page usTaskEndTrace usTaskEndTrace
1093
 * \ingroup TaskUtils
1094
 */
1095
unsigned long ulTaskEndTrace( void ) PRIVILEGED_FUNCTION;
1096
 
1097
/**
1098
 * task.h
1099
 * <PRE>unsigned portBASE_TYPE uxTaskGetStackHighWaterMark( xTaskHandle xTask );</PRE>
1100
 *
1101
 * INCLUDE_uxTaskGetStackHighWaterMark must be set to 1 in FreeRTOSConfig.h for
1102
 * this function to be available.
1103
 *
1104
 * Returns the high water mark of the stack associated with xTask.  That is,
1105
 * the minimum free stack space there has been (in words, so on a 32 bit machine
1106
 * a value of 1 means 4 bytes) since the task started.  The smaller the returned
1107
 * number the closer the task has come to overflowing its stack.
1108
 *
1109
 * @param xTask Handle of the task associated with the stack to be checked.
1110
 * Set xTask to NULL to check the stack of the calling task.
1111
 *
1112
 * @return The smallest amount of free stack space there has been (in bytes)
1113
 * since the task referenced by xTask was created.
1114
 */
1115
unsigned portBASE_TYPE uxTaskGetStackHighWaterMark( xTaskHandle xTask ) PRIVILEGED_FUNCTION;
1116
 
1117
/* When using trace macros it is sometimes necessary to include tasks.h before
1118
FreeRTOS.h.  When this is done pdTASK_HOOK_CODE will not yet have been defined,
1119
so the following two prototypes will cause a compilation error.  This can be
1120
fixed by simply guarding against the inclusion of these two prototypes unless
1121
they are explicitly required by the configUSE_APPLICATION_TASK_TAG configuration
1122
constant. */
1123
#ifdef configUSE_APPLICATION_TASK_TAG
1124
        #if configUSE_APPLICATION_TASK_TAG == 1
1125
                /**
1126
                 * task.h
1127
                 * <pre>void vTaskSetApplicationTaskTag( xTaskHandle xTask, pdTASK_HOOK_CODE pxHookFunction );</pre>
1128
                 *
1129
                 * Sets pxHookFunction to be the task hook function used by the task xTask.
1130
                 * Passing xTask as NULL has the effect of setting the calling tasks hook
1131
                 * function.
1132
                 */
1133
                void vTaskSetApplicationTaskTag( xTaskHandle xTask, pdTASK_HOOK_CODE pxHookFunction ) PRIVILEGED_FUNCTION;
1134
 
1135
                /**
1136
                 * task.h
1137
                 * <pre>void xTaskGetApplicationTaskTag( xTaskHandle xTask );</pre>
1138
                 *
1139
                 * Returns the pxHookFunction value assigned to the task xTask.
1140
                 */
1141
                pdTASK_HOOK_CODE xTaskGetApplicationTaskTag( xTaskHandle xTask ) PRIVILEGED_FUNCTION;
1142
        #endif /* configUSE_APPLICATION_TASK_TAG ==1 */
1143
#endif /* ifdef configUSE_APPLICATION_TASK_TAG */
1144
 
1145
/**
1146
 * task.h
1147
 * <pre>portBASE_TYPE xTaskCallApplicationTaskHook( xTaskHandle xTask, pdTASK_HOOK_CODE pxHookFunction );</pre>
1148
 *
1149
 * Calls the hook function associated with xTask.  Passing xTask as NULL has
1150
 * the effect of calling the Running tasks (the calling task) hook function.
1151
 *
1152
 * pvParameter is passed to the hook function for the task to interpret as it
1153
 * wants.
1154
 */
1155
portBASE_TYPE xTaskCallApplicationTaskHook( xTaskHandle xTask, void *pvParameter ) PRIVILEGED_FUNCTION;
1156
 
1157
 
1158
/*-----------------------------------------------------------
1159
 * SCHEDULER INTERNALS AVAILABLE FOR PORTING PURPOSES
1160
 *----------------------------------------------------------*/
1161
 
1162
/*
1163
 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS ONLY
1164
 * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS
1165
 * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
1166
 *
1167
 * Called from the real time kernel tick (either preemptive or cooperative),
1168
 * this increments the tick count and checks if any tasks that are blocked
1169
 * for a finite period required removing from a blocked list and placing on
1170
 * a ready list.
1171
 */
1172
void vTaskIncrementTick( void ) PRIVILEGED_FUNCTION;
1173
 
1174
/*
1175
 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS AN
1176
 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
1177
 *
1178
 * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED.
1179
 *
1180
 * Removes the calling task from the ready list and places it both
1181
 * on the list of tasks waiting for a particular event, and the
1182
 * list of delayed tasks.  The task will be removed from both lists
1183
 * and replaced on the ready list should either the event occur (and
1184
 * there be no higher priority tasks waiting on the same event) or
1185
 * the delay period expires.
1186
 *
1187
 * @param pxEventList The list containing tasks that are blocked waiting
1188
 * for the event to occur.
1189
 *
1190
 * @param xTicksToWait The maximum amount of time that the task should wait
1191
 * for the event to occur.  This is specified in kernel ticks,the constant
1192
 * portTICK_RATE_MS can be used to convert kernel ticks into a real time
1193
 * period.
1194
 */
1195
void vTaskPlaceOnEventList( const xList * const pxEventList, portTickType xTicksToWait ) PRIVILEGED_FUNCTION;
1196
 
1197
/*
1198
 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS AN
1199
 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
1200
 *
1201
 * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED.
1202
 *
1203
 * Removes a task from both the specified event list and the list of blocked
1204
 * tasks, and places it on a ready queue.
1205
 *
1206
 * xTaskRemoveFromEventList () will be called if either an event occurs to
1207
 * unblock a task, or the block timeout period expires.
1208
 *
1209
 * @return pdTRUE if the task being removed has a higher priority than the task
1210
 * making the call, otherwise pdFALSE.
1211
 */
1212
signed portBASE_TYPE xTaskRemoveFromEventList( const xList * const pxEventList ) PRIVILEGED_FUNCTION;
1213
 
1214
/*
1215
 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS AN
1216
 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
1217
 *
1218
 * INCLUDE_vTaskCleanUpResources and INCLUDE_vTaskSuspend must be defined as 1
1219
 * for this function to be available.
1220
 * See the configuration section for more information.
1221
 *
1222
 * Empties the ready and delayed queues of task control blocks, freeing the
1223
 * memory allocated for the task control block and task stacks as it goes.
1224
 */
1225
void vTaskCleanUpResources( void ) PRIVILEGED_FUNCTION;
1226
 
1227
/*
1228
 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE.  IT IS ONLY
1229
 * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS
1230
 * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
1231
 *
1232
 * Sets the pointer to the current TCB to the TCB of the highest priority task
1233
 * that is ready to run.
1234
 */
1235
void vTaskSwitchContext( void ) PRIVILEGED_FUNCTION;
1236
 
1237
/*
1238
 * Return the handle of the calling task.
1239
 */
1240
xTaskHandle xTaskGetCurrentTaskHandle( void ) PRIVILEGED_FUNCTION;
1241
 
1242
/*
1243
 * Capture the current time status for future reference.
1244
 */
1245
void vTaskSetTimeOutState( xTimeOutType * const pxTimeOut ) PRIVILEGED_FUNCTION;
1246
 
1247
/*
1248
 * Compare the time status now with that previously captured to see if the
1249
 * timeout has expired.
1250
 */
1251
portBASE_TYPE xTaskCheckForTimeOut( xTimeOutType * const pxTimeOut, portTickType * const pxTicksToWait ) PRIVILEGED_FUNCTION;
1252
 
1253
/*
1254
 * Shortcut used by the queue implementation to prevent unnecessary call to
1255
 * taskYIELD();
1256
 */
1257
void vTaskMissedYield( void ) PRIVILEGED_FUNCTION;
1258
 
1259
/*
1260
 * Returns the scheduler state as taskSCHEDULER_RUNNING,
1261
 * taskSCHEDULER_NOT_STARTED or taskSCHEDULER_SUSPENDED.
1262
 */
1263
portBASE_TYPE xTaskGetSchedulerState( void ) PRIVILEGED_FUNCTION;
1264
 
1265
/*
1266
 * Raises the priority of the mutex holder to that of the calling task should
1267
 * the mutex holder have a priority less than the calling task.
1268
 */
1269
void vTaskPriorityInherit( xTaskHandle * const pxMutexHolder ) PRIVILEGED_FUNCTION;
1270
 
1271
/*
1272
 * Set the priority of a task back to its proper priority in the case that it
1273
 * inherited a higher priority while it was holding a semaphore.
1274
 */
1275
void vTaskPriorityDisinherit( xTaskHandle * const pxMutexHolder ) PRIVILEGED_FUNCTION;
1276
 
1277
/*
1278
 * Generic version of the task creation function which is in turn called by the
1279
 * xTaskCreate() and xTaskCreateRestricted() macros.
1280
 */
1281
signed portBASE_TYPE xTaskGenericCreate( pdTASK_CODE pvTaskCode, const signed char * const pcName, unsigned short usStackDepth, void *pvParameters, unsigned portBASE_TYPE uxPriority, xTaskHandle *pxCreatedTask, portSTACK_TYPE *puxStackBuffer, const xMemoryRegion * const xRegions ) PRIVILEGED_FUNCTION;
1282
 
1283
#ifdef __cplusplus
1284
}
1285
#endif
1286
#endif /* TASK_H */
1287
 
1288
 
1289
 

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.