2 FreeRTOS.org V5.2.0 - Copyright (C) 2003-2009 Richard Barry.
\r
4 This file is part of the FreeRTOS.org distribution.
\r
6 FreeRTOS.org is free software; you can redistribute it and/or modify it
\r
7 under the terms of the GNU General Public License (version 2) as published
\r
8 by the Free Software Foundation and modified by the FreeRTOS exception.
\r
10 FreeRTOS.org is distributed in the hope that it will be useful, but WITHOUT
\r
11 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
\r
12 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
\r
15 You should have received a copy of the GNU General Public License along
\r
16 with FreeRTOS.org; if not, write to the Free Software Foundation, Inc., 59
\r
17 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
\r
19 A special exception to the GPL is included to allow you to distribute a
\r
20 combined work that includes FreeRTOS.org without being obliged to provide
\r
21 the source code for any proprietary components. See the licensing section
\r
22 of http://www.FreeRTOS.org for full details.
\r
25 ***************************************************************************
\r
27 * Get the FreeRTOS eBook! See http://www.FreeRTOS.org/Documentation *
\r
29 * This is a concise, step by step, 'hands on' guide that describes both *
\r
30 * general multitasking concepts and FreeRTOS specifics. It presents and *
\r
31 * explains numerous examples that are written using the FreeRTOS API. *
\r
32 * Full source code for all the examples is provided in an accompanying *
\r
35 ***************************************************************************
\r
39 Please ensure to read the configuration and relevant port sections of the
\r
40 online documentation.
\r
42 http://www.FreeRTOS.org - Documentation, latest information, license and
\r
45 http://www.SafeRTOS.com - A version that is certified for use in safety
\r
48 http://www.OpenRTOS.com - Commercial support, development, porting,
\r
49 licensing and training services.
\r
53 #ifndef INC_FREERTOS_H
\r
54 #error "#include FreeRTOS.h" must appear in source files before "#include task.h"
\r
62 #include "portable.h"
\r
68 /*-----------------------------------------------------------
\r
69 * MACROS AND DEFINITIONS
\r
70 *----------------------------------------------------------*/
\r
72 #define tskKERNEL_VERSION_NUMBER "V5.2.0"
\r
77 * Type by which tasks are referenced. For example, a call to xTaskCreate
\r
78 * returns (via a pointer parameter) an xTaskHandle variable that can then
\r
79 * be used as a parameter to vTaskDelete to delete the task.
\r
81 * \page xTaskHandle xTaskHandle
\r
84 typedef void * xTaskHandle;
\r
87 * Used internally only.
\r
89 typedef struct xTIME_OUT
\r
91 portBASE_TYPE xOverflowCount;
\r
92 portTickType xTimeOnEntering;
\r
96 * Defines the priority used by the idle task. This must not be modified.
\r
98 * \ingroup TaskUtils
\r
100 #define tskIDLE_PRIORITY ( ( unsigned portBASE_TYPE ) 0 )
\r
105 * Macro for forcing a context switch.
\r
107 * \page taskYIELD taskYIELD
\r
108 * \ingroup SchedulerControl
\r
110 #define taskYIELD() portYIELD()
\r
115 * Macro to mark the start of a critical code region. Preemptive context
\r
116 * switches cannot occur when in a critical region.
\r
118 * NOTE: This may alter the stack (depending on the portable implementation)
\r
119 * so must be used with care!
\r
121 * \page taskENTER_CRITICAL taskENTER_CRITICAL
\r
122 * \ingroup SchedulerControl
\r
124 #define taskENTER_CRITICAL() portENTER_CRITICAL()
\r
129 * Macro to mark the end of a critical code region. Preemptive context
\r
130 * switches cannot occur when in a critical region.
\r
132 * NOTE: This may alter the stack (depending on the portable implementation)
\r
133 * so must be used with care!
\r
135 * \page taskEXIT_CRITICAL taskEXIT_CRITICAL
\r
136 * \ingroup SchedulerControl
\r
138 #define taskEXIT_CRITICAL() portEXIT_CRITICAL()
\r
143 * Macro to disable all maskable interrupts.
\r
145 * \page taskDISABLE_INTERRUPTS taskDISABLE_INTERRUPTS
\r
146 * \ingroup SchedulerControl
\r
148 #define taskDISABLE_INTERRUPTS() portDISABLE_INTERRUPTS()
\r
153 * Macro to enable microcontroller interrupts.
\r
155 * \page taskENABLE_INTERRUPTS taskENABLE_INTERRUPTS
\r
156 * \ingroup SchedulerControl
\r
158 #define taskENABLE_INTERRUPTS() portENABLE_INTERRUPTS()
\r
160 /* Definitions returned by xTaskGetSchedulerState(). */
\r
161 #define taskSCHEDULER_NOT_STARTED 0
\r
162 #define taskSCHEDULER_RUNNING 1
\r
163 #define taskSCHEDULER_SUSPENDED 2
\r
165 /*-----------------------------------------------------------
\r
166 * TASK CREATION API
\r
167 *----------------------------------------------------------*/
\r
172 portBASE_TYPE xTaskCreate(
\r
173 pdTASK_CODE pvTaskCode,
\r
174 const portCHAR * const pcName,
\r
175 unsigned portSHORT usStackDepth,
\r
176 void *pvParameters,
\r
177 unsigned portBASE_TYPE uxPriority,
\r
178 xTaskHandle *pvCreatedTask
\r
181 * Create a new task and add it to the list of tasks that are ready to run.
\r
183 * @param pvTaskCode Pointer to the task entry function. Tasks
\r
184 * must be implemented to never return (i.e. continuous loop).
\r
186 * @param pcName A descriptive name for the task. This is mainly used to
\r
187 * facilitate debugging. Max length defined by tskMAX_TASK_NAME_LEN - default
\r
190 * @param usStackDepth The size of the task stack specified as the number of
\r
191 * variables the stack can hold - not the number of bytes. For example, if
\r
192 * the stack is 16 bits wide and usStackDepth is defined as 100, 200 bytes
\r
193 * will be allocated for stack storage.
\r
195 * @param pvParameters Pointer that will be used as the parameter for the task
\r
198 * @param uxPriority The priority at which the task should run.
\r
200 * @param pvCreatedTask Used to pass back a handle by which the created task
\r
201 * can be referenced.
\r
203 * @return pdPASS if the task was successfully created and added to a ready
\r
204 * list, otherwise an error code defined in the file errors. h
\r
208 // Task to be created.
\r
209 void vTaskCode( void * pvParameters )
\r
213 // Task code goes here.
\r
217 // Function that creates a task.
\r
218 void vOtherFunction( void )
\r
220 static unsigned char ucParameterToPass;
\r
221 xTaskHandle xHandle;
\r
223 // Create the task, storing the handle. Note that the passed parameter ucParameterToPass
\r
224 // must exist for the lifetime of the task, so in this case is declared static. If it was just an
\r
225 // an automatic stack variable it might no longer exist, or at least have been corrupted, by the time
\r
226 // the new time attempts to access it.
\r
227 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, &ucParameterToPass, tskIDLE_PRIORITY, &xHandle );
\r
229 // Use the handle to delete the task.
\r
230 vTaskDelete( xHandle );
\r
233 * \defgroup xTaskCreate xTaskCreate
\r
236 signed portBASE_TYPE xTaskCreate( pdTASK_CODE pvTaskCode, const signed portCHAR * const pcName, unsigned portSHORT usStackDepth, void *pvParameters, unsigned portBASE_TYPE uxPriority, xTaskHandle *pvCreatedTask );
\r
240 * <pre>void vTaskDelete( xTaskHandle pxTask );</pre>
\r
242 * INCLUDE_vTaskDelete must be defined as 1 for this function to be available.
\r
243 * See the configuration section for more information.
\r
245 * Remove a task from the RTOS real time kernels management. The task being
\r
246 * deleted will be removed from all ready, blocked, suspended and event lists.
\r
248 * NOTE: The idle task is responsible for freeing the kernel allocated
\r
249 * memory from tasks that have been deleted. It is therefore important that
\r
250 * the idle task is not starved of microcontroller processing time if your
\r
251 * application makes any calls to vTaskDelete (). Memory allocated by the
\r
252 * task code is not automatically freed, and should be freed before the task
\r
255 * See the demo application file death.c for sample code that utilises
\r
258 * @param pxTask The handle of the task to be deleted. Passing NULL will
\r
259 * cause the calling task to be deleted.
\r
263 void vOtherFunction( void )
\r
265 xTaskHandle xHandle;
\r
267 // Create the task, storing the handle.
\r
268 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
\r
270 // Use the handle to delete the task.
\r
271 vTaskDelete( xHandle );
\r
274 * \defgroup vTaskDelete vTaskDelete
\r
277 void vTaskDelete( xTaskHandle pxTask );
\r
280 /*-----------------------------------------------------------
\r
282 *----------------------------------------------------------*/
\r
286 * <pre>void vTaskDelay( portTickType xTicksToDelay );</pre>
\r
288 * Delay a task for a given number of ticks. The actual time that the
\r
289 * task remains blocked depends on the tick rate. The constant
\r
290 * portTICK_RATE_MS can be used to calculate real time from the tick
\r
291 * rate - with the resolution of one tick period.
\r
293 * INCLUDE_vTaskDelay must be defined as 1 for this function to be available.
\r
294 * See the configuration section for more information.
\r
297 * vTaskDelay() specifies a time at which the task wishes to unblock relative to
\r
298 * the time at which vTaskDelay() is called. For example, specifying a block
\r
299 * period of 100 ticks will cause the task to unblock 100 ticks after
\r
300 * vTaskDelay() is called. vTaskDelay() does not therefore provide a good method
\r
301 * of controlling the frequency of a cyclical task as the path taken through the
\r
302 * code, as well as other task and interrupt activity, will effect the frequency
\r
303 * at which vTaskDelay() gets called and therefore the time at which the task
\r
304 * next executes. See vTaskDelayUntil() for an alternative API function designed
\r
305 * to facilitate fixed frequency execution. It does this by specifying an
\r
306 * absolute time (rather than a relative time) at which the calling task should
\r
309 * @param xTicksToDelay The amount of time, in tick periods, that
\r
310 * the calling task should block.
\r
314 void vTaskFunction( void * pvParameters )
\r
316 void vTaskFunction( void * pvParameters )
\r
318 // Block for 500ms.
\r
319 const portTickType xDelay = 500 / portTICK_RATE_MS;
\r
323 // Simply toggle the LED every 500ms, blocking between each toggle.
\r
325 vTaskDelay( xDelay );
\r
329 * \defgroup vTaskDelay vTaskDelay
\r
330 * \ingroup TaskCtrl
\r
332 void vTaskDelay( portTickType xTicksToDelay );
\r
336 * <pre>void vTaskDelayUntil( portTickType *pxPreviousWakeTime, portTickType xTimeIncrement );</pre>
\r
338 * INCLUDE_vTaskDelayUntil must be defined as 1 for this function to be available.
\r
339 * See the configuration section for more information.
\r
341 * Delay a task until a specified time. This function can be used by cyclical
\r
342 * tasks to ensure a constant execution frequency.
\r
344 * This function differs from vTaskDelay () in one important aspect: vTaskDelay () will
\r
345 * cause a task to block for the specified number of ticks from the time vTaskDelay () is
\r
346 * called. It is therefore difficult to use vTaskDelay () by itself to generate a fixed
\r
347 * execution frequency as the time between a task starting to execute and that task
\r
348 * calling vTaskDelay () may not be fixed [the task may take a different path though the
\r
349 * code between calls, or may get interrupted or preempted a different number of times
\r
350 * each time it executes].
\r
352 * Whereas vTaskDelay () specifies a wake time relative to the time at which the function
\r
353 * is called, vTaskDelayUntil () specifies the absolute (exact) time at which it wishes to
\r
356 * The constant portTICK_RATE_MS can be used to calculate real time from the tick
\r
357 * rate - with the resolution of one tick period.
\r
359 * @param pxPreviousWakeTime Pointer to a variable that holds the time at which the
\r
360 * task was last unblocked. The variable must be initialised with the current time
\r
361 * prior to its first use (see the example below). Following this the variable is
\r
362 * automatically updated within vTaskDelayUntil ().
\r
364 * @param xTimeIncrement The cycle time period. The task will be unblocked at
\r
365 * time *pxPreviousWakeTime + xTimeIncrement. Calling vTaskDelayUntil with the
\r
366 * same xTimeIncrement parameter value will cause the task to execute with
\r
367 * a fixed interface period.
\r
371 // Perform an action every 10 ticks.
\r
372 void vTaskFunction( void * pvParameters )
\r
374 portTickType xLastWakeTime;
\r
375 const portTickType xFrequency = 10;
\r
377 // Initialise the xLastWakeTime variable with the current time.
\r
378 xLastWakeTime = xTaskGetTickCount ();
\r
381 // Wait for the next cycle.
\r
382 vTaskDelayUntil( &xLastWakeTime, xFrequency );
\r
384 // Perform action here.
\r
388 * \defgroup vTaskDelayUntil vTaskDelayUntil
\r
389 * \ingroup TaskCtrl
\r
391 void vTaskDelayUntil( portTickType * const pxPreviousWakeTime, portTickType xTimeIncrement );
\r
395 * <pre>unsigned portBASE_TYPE uxTaskPriorityGet( xTaskHandle pxTask );</pre>
\r
397 * INCLUDE_xTaskPriorityGet must be defined as 1 for this function to be available.
\r
398 * See the configuration section for more information.
\r
400 * Obtain the priority of any task.
\r
402 * @param pxTask Handle of the task to be queried. Passing a NULL
\r
403 * handle results in the priority of the calling task being returned.
\r
405 * @return The priority of pxTask.
\r
409 void vAFunction( void )
\r
411 xTaskHandle xHandle;
\r
413 // Create a task, storing the handle.
\r
414 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
\r
418 // Use the handle to obtain the priority of the created task.
\r
419 // It was created with tskIDLE_PRIORITY, but may have changed
\r
421 if( uxTaskPriorityGet( xHandle ) != tskIDLE_PRIORITY )
\r
423 // The task has changed it's priority.
\r
428 // Is our priority higher than the created task?
\r
429 if( uxTaskPriorityGet( xHandle ) < uxTaskPriorityGet( NULL ) )
\r
431 // Our priority (obtained using NULL handle) is higher.
\r
435 * \defgroup uxTaskPriorityGet uxTaskPriorityGet
\r
436 * \ingroup TaskCtrl
\r
438 unsigned portBASE_TYPE uxTaskPriorityGet( xTaskHandle pxTask );
\r
442 * <pre>void vTaskPrioritySet( xTaskHandle pxTask, unsigned portBASE_TYPE uxNewPriority );</pre>
\r
444 * INCLUDE_vTaskPrioritySet must be defined as 1 for this function to be available.
\r
445 * See the configuration section for more information.
\r
447 * Set the priority of any task.
\r
449 * A context switch will occur before the function returns if the priority
\r
450 * being set is higher than the currently executing task.
\r
452 * @param pxTask Handle to the task for which the priority is being set.
\r
453 * Passing a NULL handle results in the priority of the calling task being set.
\r
455 * @param uxNewPriority The priority to which the task will be set.
\r
459 void vAFunction( void )
\r
461 xTaskHandle xHandle;
\r
463 // Create a task, storing the handle.
\r
464 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
\r
468 // Use the handle to raise the priority of the created task.
\r
469 vTaskPrioritySet( xHandle, tskIDLE_PRIORITY + 1 );
\r
473 // Use a NULL handle to raise our priority to the same value.
\r
474 vTaskPrioritySet( NULL, tskIDLE_PRIORITY + 1 );
\r
477 * \defgroup vTaskPrioritySet vTaskPrioritySet
\r
478 * \ingroup TaskCtrl
\r
480 void vTaskPrioritySet( xTaskHandle pxTask, unsigned portBASE_TYPE uxNewPriority );
\r
484 * <pre>void vTaskSuspend( xTaskHandle pxTaskToSuspend );</pre>
\r
486 * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available.
\r
487 * See the configuration section for more information.
\r
489 * Suspend any task. When suspended a task will never get any microcontroller
\r
490 * processing time, no matter what its priority.
\r
492 * Calls to vTaskSuspend are not accumulative -
\r
493 * i.e. calling vTaskSuspend () twice on the same task still only requires one
\r
494 * call to vTaskResume () to ready the suspended task.
\r
496 * @param pxTaskToSuspend Handle to the task being suspended. Passing a NULL
\r
497 * handle will cause the calling task to be suspended.
\r
501 void vAFunction( void )
\r
503 xTaskHandle xHandle;
\r
505 // Create a task, storing the handle.
\r
506 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
\r
510 // Use the handle to suspend the created task.
\r
511 vTaskSuspend( xHandle );
\r
515 // The created task will not run during this period, unless
\r
516 // another task calls vTaskResume( xHandle ).
\r
521 // Suspend ourselves.
\r
522 vTaskSuspend( NULL );
\r
524 // We cannot get here unless another task calls vTaskResume
\r
525 // with our handle as the parameter.
\r
528 * \defgroup vTaskSuspend vTaskSuspend
\r
529 * \ingroup TaskCtrl
\r
531 void vTaskSuspend( xTaskHandle pxTaskToSuspend );
\r
535 * <pre>void vTaskResume( xTaskHandle pxTaskToResume );</pre>
\r
537 * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available.
\r
538 * See the configuration section for more information.
\r
540 * Resumes a suspended task.
\r
542 * A task that has been suspended by one of more calls to vTaskSuspend ()
\r
543 * will be made available for running again by a single call to
\r
546 * @param pxTaskToResume Handle to the task being readied.
\r
550 void vAFunction( void )
\r
552 xTaskHandle xHandle;
\r
554 // Create a task, storing the handle.
\r
555 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
\r
559 // Use the handle to suspend the created task.
\r
560 vTaskSuspend( xHandle );
\r
564 // The created task will not run during this period, unless
\r
565 // another task calls vTaskResume( xHandle ).
\r
570 // Resume the suspended task ourselves.
\r
571 vTaskResume( xHandle );
\r
573 // The created task will once again get microcontroller processing
\r
574 // time in accordance with it priority within the system.
\r
577 * \defgroup vTaskResume vTaskResume
\r
578 * \ingroup TaskCtrl
\r
580 void vTaskResume( xTaskHandle pxTaskToResume );
\r
584 * <pre>void xTaskResumeFromISR( xTaskHandle pxTaskToResume );</pre>
\r
586 * INCLUDE_xTaskResumeFromISR must be defined as 1 for this function to be
\r
587 * available. See the configuration section for more information.
\r
589 * An implementation of vTaskResume() that can be called from within an ISR.
\r
591 * A task that has been suspended by one of more calls to vTaskSuspend ()
\r
592 * will be made available for running again by a single call to
\r
593 * xTaskResumeFromISR ().
\r
595 * @param pxTaskToResume Handle to the task being readied.
\r
597 * \defgroup vTaskResumeFromISR vTaskResumeFromISR
\r
598 * \ingroup TaskCtrl
\r
600 portBASE_TYPE xTaskResumeFromISR( xTaskHandle pxTaskToResume );
\r
602 /*-----------------------------------------------------------
\r
603 * SCHEDULER CONTROL
\r
604 *----------------------------------------------------------*/
\r
608 * <pre>void vTaskStartScheduler( void );</pre>
\r
610 * Starts the real time kernel tick processing. After calling the kernel
\r
611 * has control over which tasks are executed and when. This function
\r
612 * does not return until an executing task calls vTaskEndScheduler ().
\r
614 * At least one task should be created via a call to xTaskCreate ()
\r
615 * before calling vTaskStartScheduler (). The idle task is created
\r
616 * automatically when the first application task is created.
\r
618 * See the demo application file main.c for an example of creating
\r
619 * tasks and starting the kernel.
\r
623 void vAFunction( void )
\r
625 // Create at least one task before starting the kernel.
\r
626 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL );
\r
628 // Start the real time kernel with preemption.
\r
629 vTaskStartScheduler ();
\r
631 // Will not get here unless a task calls vTaskEndScheduler ()
\r
635 * \defgroup vTaskStartScheduler vTaskStartScheduler
\r
636 * \ingroup SchedulerControl
\r
638 void vTaskStartScheduler( void );
\r
642 * <pre>void vTaskEndScheduler( void );</pre>
\r
644 * Stops the real time kernel tick. All created tasks will be automatically
\r
645 * deleted and multitasking (either preemptive or cooperative) will
\r
646 * stop. Execution then resumes from the point where vTaskStartScheduler ()
\r
647 * was called, as if vTaskStartScheduler () had just returned.
\r
649 * See the demo application file main. c in the demo/PC directory for an
\r
650 * example that uses vTaskEndScheduler ().
\r
652 * vTaskEndScheduler () requires an exit function to be defined within the
\r
653 * portable layer (see vPortEndScheduler () in port. c for the PC port). This
\r
654 * performs hardware specific operations such as stopping the kernel tick.
\r
656 * vTaskEndScheduler () will cause all of the resources allocated by the
\r
657 * kernel to be freed - but will not free resources allocated by application
\r
662 void vTaskCode( void * pvParameters )
\r
666 // Task code goes here.
\r
668 // At some point we want to end the real time kernel processing
\r
670 vTaskEndScheduler ();
\r
674 void vAFunction( void )
\r
676 // Create at least one task before starting the kernel.
\r
677 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL );
\r
679 // Start the real time kernel with preemption.
\r
680 vTaskStartScheduler ();
\r
682 // Will only get here when the vTaskCode () task has called
\r
683 // vTaskEndScheduler (). When we get here we are back to single task
\r
688 * \defgroup vTaskEndScheduler vTaskEndScheduler
\r
689 * \ingroup SchedulerControl
\r
691 void vTaskEndScheduler( void );
\r
695 * <pre>void vTaskSuspendAll( void );</pre>
\r
697 * Suspends all real time kernel activity while keeping interrupts (including the
\r
698 * kernel tick) enabled.
\r
700 * After calling vTaskSuspendAll () the calling task will continue to execute
\r
701 * without risk of being swapped out until a call to xTaskResumeAll () has been
\r
704 * API functions that have the potential to cause a context switch (for example,
\r
705 * vTaskDelayUntil(), xQueueSend(), etc.) must not be called while the scheduler
\r
710 void vTask1( void * pvParameters )
\r
714 // Task code goes here.
\r
718 // At some point the task wants to perform a long operation during
\r
719 // which it does not want to get swapped out. It cannot use
\r
720 // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the
\r
721 // operation may cause interrupts to be missed - including the
\r
724 // Prevent the real time kernel swapping out the task.
\r
725 vTaskSuspendAll ();
\r
727 // Perform the operation here. There is no need to use critical
\r
728 // sections as we have all the microcontroller processing time.
\r
729 // During this time interrupts will still operate and the kernel
\r
730 // tick count will be maintained.
\r
734 // The operation is complete. Restart the kernel.
\r
739 * \defgroup vTaskSuspendAll vTaskSuspendAll
\r
740 * \ingroup SchedulerControl
\r
742 void vTaskSuspendAll( void );
\r
746 * <pre>portCHAR xTaskResumeAll( void );</pre>
\r
748 * Resumes real time kernel activity following a call to vTaskSuspendAll ().
\r
749 * After a call to vTaskSuspendAll () the kernel will take control of which
\r
750 * task is executing at any time.
\r
752 * @return If resuming the scheduler caused a context switch then pdTRUE is
\r
753 * returned, otherwise pdFALSE is returned.
\r
757 void vTask1( void * pvParameters )
\r
761 // Task code goes here.
\r
765 // At some point the task wants to perform a long operation during
\r
766 // which it does not want to get swapped out. It cannot use
\r
767 // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the
\r
768 // operation may cause interrupts to be missed - including the
\r
771 // Prevent the real time kernel swapping out the task.
\r
772 vTaskSuspendAll ();
\r
774 // Perform the operation here. There is no need to use critical
\r
775 // sections as we have all the microcontroller processing time.
\r
776 // During this time interrupts will still operate and the real
\r
777 // time kernel tick count will be maintained.
\r
781 // The operation is complete. Restart the kernel. We want to force
\r
782 // a context switch - but there is no point if resuming the scheduler
\r
783 // caused a context switch already.
\r
784 if( !xTaskResumeAll () )
\r
791 * \defgroup xTaskResumeAll xTaskResumeAll
\r
792 * \ingroup SchedulerControl
\r
794 signed portBASE_TYPE xTaskResumeAll( void );
\r
798 * <pre>signed portBASE_TYPE xTaskIsTaskSuspended( xTaskHandle xTask );</pre>
\r
800 * Utility task that simply returns pdTRUE if the task referenced by xTask is
\r
801 * currently in the Suspended state, or pdFALSE if the task referenced by xTask
\r
802 * is in any other state.
\r
805 signed portBASE_TYPE xTaskIsTaskSuspended( xTaskHandle xTask );
\r
807 /*-----------------------------------------------------------
\r
809 *----------------------------------------------------------*/
\r
813 * <PRE>volatile portTickType xTaskGetTickCount( void );</PRE>
\r
815 * @return The count of ticks since vTaskStartScheduler was called.
\r
817 * \page xTaskGetTickCount xTaskGetTickCount
\r
818 * \ingroup TaskUtils
\r
820 portTickType xTaskGetTickCount( void );
\r
824 * <PRE>unsigned portSHORT uxTaskGetNumberOfTasks( void );</PRE>
\r
826 * @return The number of tasks that the real time kernel is currently managing.
\r
827 * This includes all ready, blocked and suspended tasks. A task that
\r
828 * has been deleted but not yet freed by the idle task will also be
\r
829 * included in the count.
\r
831 * \page uxTaskGetNumberOfTasks uxTaskGetNumberOfTasks
\r
832 * \ingroup TaskUtils
\r
834 unsigned portBASE_TYPE uxTaskGetNumberOfTasks( void );
\r
838 * <PRE>void vTaskList( portCHAR *pcWriteBuffer );</PRE>
\r
840 * configUSE_TRACE_FACILITY must be defined as 1 for this function to be
\r
841 * available. See the configuration section for more information.
\r
843 * NOTE: This function will disable interrupts for its duration. It is
\r
844 * not intended for normal application runtime use but as a debug aid.
\r
846 * Lists all the current tasks, along with their current state and stack
\r
847 * usage high water mark.
\r
849 * Tasks are reported as blocked ('B'), ready ('R'), deleted ('D') or
\r
852 * @param pcWriteBuffer A buffer into which the above mentioned details
\r
853 * will be written, in ascii form. This buffer is assumed to be large
\r
854 * enough to contain the generated report. Approximately 40 bytes per
\r
855 * task should be sufficient.
\r
857 * \page vTaskList vTaskList
\r
858 * \ingroup TaskUtils
\r
860 void vTaskList( signed portCHAR *pcWriteBuffer );
\r
864 * <PRE>void vTaskGetRunTimeStats( portCHAR *pcWriteBuffer );</PRE>
\r
866 * configGENERATE_RUN_TIME_STATS must be defined as 1 for this function
\r
867 * to be available. The application must also then provide definitions
\r
868 * for portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and
\r
869 * portGET_RUN_TIME_COUNTER_VALUE to configure a peripheral timer/counter
\r
870 * and return the timers current count value respectively. The counter
\r
871 * should be at least 10 times the frequency of the tick count.
\r
873 * NOTE: This function will disable interrupts for its duration. It is
\r
874 * not intended for normal application runtime use but as a debug aid.
\r
876 * Setting configGENERATE_RUN_TIME_STATS to 1 will result in a total
\r
877 * accumulated execution time being stored for each task. The resolution
\r
878 * of the accumulated time value depends on the frequency of the timer
\r
879 * configured by the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() macro.
\r
880 * Calling vTaskGetRunTimeStats() writes the total execution time of each
\r
881 * task into a buffer, both as an absolute count value and as a percentage
\r
882 * of the total system execution time.
\r
884 * @param pcWriteBuffer A buffer into which the execution times will be
\r
885 * written, in ascii form. This buffer is assumed to be large enough to
\r
886 * contain the generated report. Approximately 40 bytes per task should
\r
889 * \page vTaskGetRunTimeStats vTaskGetRunTimeStats
\r
890 * \ingroup TaskUtils
\r
892 void vTaskGetRunTimeStats( signed portCHAR *pcWriteBuffer );
\r
896 * <PRE>void vTaskStartTrace( portCHAR * pcBuffer, unsigned portBASE_TYPE uxBufferSize );</PRE>
\r
898 * Starts a real time kernel activity trace. The trace logs the identity of
\r
899 * which task is running when.
\r
901 * The trace file is stored in binary format. A separate DOS utility called
\r
902 * convtrce.exe is used to convert this into a tab delimited text file which
\r
903 * can be viewed and plotted in a spread sheet.
\r
905 * @param pcBuffer The buffer into which the trace will be written.
\r
907 * @param ulBufferSize The size of pcBuffer in bytes. The trace will continue
\r
908 * until either the buffer in full, or ulTaskEndTrace () is called.
\r
910 * \page vTaskStartTrace vTaskStartTrace
\r
911 * \ingroup TaskUtils
\r
913 void vTaskStartTrace( signed portCHAR * pcBuffer, unsigned portLONG ulBufferSize );
\r
917 * <PRE>unsigned portLONG ulTaskEndTrace( void );</PRE>
\r
919 * Stops a kernel activity trace. See vTaskStartTrace ().
\r
921 * @return The number of bytes that have been written into the trace buffer.
\r
923 * \page usTaskEndTrace usTaskEndTrace
\r
924 * \ingroup TaskUtils
\r
926 unsigned portLONG ulTaskEndTrace( void );
\r
930 * <PRE>unsigned portBASE_TYPE uxTaskGetStackHighWaterMark( xTaskHandle xTask );</PRE>
\r
932 * INCLUDE_uxTaskGetStackHighWaterMark must be set to 1 in FreeRTOSConfig.h for
\r
933 * this function to be available.
\r
935 * Returns the high water mark of the stack associated with xTask. That is,
\r
936 * the minimum free stack space there has been (in bytes) since the task
\r
937 * started. The smaller the returned number the closer the task has come
\r
938 * to overflowing its stack.
\r
940 * @param xTask Handle of the task associated with the stack to be checked.
\r
941 * Set xTask to NULL to check the stack of the calling task.
\r
943 * @return The smallest amount of free stack space there has been (in bytes)
\r
944 * since the task referenced by xTask was created.
\r
946 unsigned portBASE_TYPE uxTaskGetStackHighWaterMark( xTaskHandle xTask );
\r
950 * <pre>void vTaskSetApplicationTaskTag( xTaskHandle xTask, pdTASK_HOOK_CODE pxHookFunction );</pre>
\r
952 * Sets pxHookFunction to be the task hook function used by the task xTask.
\r
953 * Passing xTask as NULL has the effect of setting the calling tasks hook
\r
956 void vTaskSetApplicationTaskTag( xTaskHandle xTask, pdTASK_HOOK_CODE pxHookFunction );
\r
960 * <pre>portBASE_TYPE xTaskCallApplicationTaskHook( xTaskHandle xTask, pdTASK_HOOK_CODE pxHookFunction );</pre>
\r
962 * Calls the hook function associated with xTask. Passing xTask as NULL has
\r
963 * the effect of calling the Running tasks (the calling task) hook function.
\r
965 * pvParameter is passed to the hook function for the task to interpret as it
\r
968 portBASE_TYPE xTaskCallApplicationTaskHook( xTaskHandle xTask, void *pvParameter );
\r
971 /*-----------------------------------------------------------
\r
972 * SCHEDULER INTERNALS AVAILABLE FOR PORTING PURPOSES
\r
973 *----------------------------------------------------------*/
\r
976 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS ONLY
\r
977 * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS
\r
978 * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
\r
980 * Called from the real time kernel tick (either preemptive or cooperative),
\r
981 * this increments the tick count and checks if any tasks that are blocked
\r
982 * for a finite period required removing from a blocked list and placing on
\r
985 void vTaskIncrementTick( void );
\r
988 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN
\r
989 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
\r
991 * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED.
\r
993 * Removes the calling task from the ready list and places it both
\r
994 * on the list of tasks waiting for a particular event, and the
\r
995 * list of delayed tasks. The task will be removed from both lists
\r
996 * and replaced on the ready list should either the event occur (and
\r
997 * there be no higher priority tasks waiting on the same event) or
\r
998 * the delay period expires.
\r
1000 * @param pxEventList The list containing tasks that are blocked waiting
\r
1001 * for the event to occur.
\r
1003 * @param xTicksToWait The maximum amount of time that the task should wait
\r
1004 * for the event to occur. This is specified in kernel ticks,the constant
\r
1005 * portTICK_RATE_MS can be used to convert kernel ticks into a real time
\r
1008 void vTaskPlaceOnEventList( const xList * const pxEventList, portTickType xTicksToWait );
\r
1011 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN
\r
1012 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
\r
1014 * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED.
\r
1016 * Removes a task from both the specified event list and the list of blocked
\r
1017 * tasks, and places it on a ready queue.
\r
1019 * xTaskRemoveFromEventList () will be called if either an event occurs to
\r
1020 * unblock a task, or the block timeout period expires.
\r
1022 * @return pdTRUE if the task being removed has a higher priority than the task
\r
1023 * making the call, otherwise pdFALSE.
\r
1025 signed portBASE_TYPE xTaskRemoveFromEventList( const xList * const pxEventList );
\r
1028 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN
\r
1029 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
\r
1031 * INCLUDE_vTaskCleanUpResources and INCLUDE_vTaskSuspend must be defined as 1
\r
1032 * for this function to be available.
\r
1033 * See the configuration section for more information.
\r
1035 * Empties the ready and delayed queues of task control blocks, freeing the
\r
1036 * memory allocated for the task control block and task stacks as it goes.
\r
1038 void vTaskCleanUpResources( void );
\r
1041 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS ONLY
\r
1042 * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS
\r
1043 * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
\r
1045 * Sets the pointer to the current TCB to the TCB of the highest priority task
\r
1046 * that is ready to run.
\r
1048 void vTaskSwitchContext( void );
\r
1051 * Return the handle of the calling task.
\r
1053 xTaskHandle xTaskGetCurrentTaskHandle( void );
\r
1056 * Capture the current time status for future reference.
\r
1058 void vTaskSetTimeOutState( xTimeOutType * const pxTimeOut );
\r
1061 * Compare the time status now with that previously captured to see if the
\r
1062 * timeout has expired.
\r
1064 portBASE_TYPE xTaskCheckForTimeOut( xTimeOutType * const pxTimeOut, portTickType * const pxTicksToWait );
\r
1067 * Shortcut used by the queue implementation to prevent unnecessary call to
\r
1070 void vTaskMissedYield( void );
\r
1073 * Returns the scheduler state as taskSCHEDULER_RUNNING,
\r
1074 * taskSCHEDULER_NOT_STARTED or taskSCHEDULER_SUSPENDED.
\r
1076 portBASE_TYPE xTaskGetSchedulerState( void );
\r
1079 * Raises the priority of the mutex holder to that of the calling task should
\r
1080 * the mutex holder have a priority less than the calling task.
\r
1082 void vTaskPriorityInherit( xTaskHandle * const pxMutexHolder );
\r
1085 * Set the priority of a task back to its proper priority in the case that it
\r
1086 * inherited a higher priority while it was holding a semaphore.
\r
1088 void vTaskPriorityDisinherit( xTaskHandle * const pxMutexHolder );
\r
1090 #ifdef __cplusplus
\r
1093 #endif /* TASK_H */
\r