Rohit Grover
www.freertos.org
Dependents: Nucleo freertos_test FreeRTOS_test freertos_bluetooth ... more
Embed:
(wiki syntax)
Show/hide line numbers
task.h
00001 /* 00002 FreeRTOS V7.6.0 - Copyright (C) 2013 Real Time Engineers Ltd. 00003 All rights reserved 00004 00005 VISIT http://www.FreeRTOS.org TO ENSURE YOU ARE USING THE LATEST VERSION. 00006 00007 *************************************************************************** 00008 * * 00009 * FreeRTOS provides completely free yet professionally developed, * 00010 * robust, strictly quality controlled, supported, and cross * 00011 * platform software that has become a de facto standard. * 00012 * * 00013 * Help yourself get started quickly and support the FreeRTOS * 00014 * project by purchasing a FreeRTOS tutorial book, reference * 00015 * manual, or both from: http://www.FreeRTOS.org/Documentation * 00016 * * 00017 * Thank you! * 00018 * * 00019 *************************************************************************** 00020 00021 This file is part of the FreeRTOS distribution. 00022 00023 FreeRTOS is free software; you can redistribute it and/or modify it under 00024 the terms of the GNU General Public License (version 2) as published by the 00025 Free Software Foundation >>!AND MODIFIED BY!<< the FreeRTOS exception. 00026 00027 >>! NOTE: The modification to the GPL is included to allow you to distribute 00028 >>! a combined work that includes FreeRTOS without being obliged to provide 00029 >>! the source code for proprietary components outside of the FreeRTOS 00030 >>! kernel. 00031 00032 FreeRTOS is distributed in the hope that it will be useful, but WITHOUT ANY 00033 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 00034 FOR A PARTICULAR PURPOSE. Full license text is available from the following 00035 link: http://www.freertos.org/a00114.html 00036 00037 1 tab == 4 spaces! 00038 00039 *************************************************************************** 00040 * * 00041 * Having a problem? Start by reading the FAQ "My application does * 00042 * not run, what could be wrong?" * 00043 * * 00044 * http://www.FreeRTOS.org/FAQHelp.html * 00045 * * 00046 *************************************************************************** 00047 00048 http://www.FreeRTOS.org - Documentation, books, training, latest versions, 00049 license and Real Time Engineers Ltd. contact details. 00050 00051 http://www.FreeRTOS.org/plus - A selection of FreeRTOS ecosystem products, 00052 including FreeRTOS+Trace - an indispensable productivity tool, a DOS 00053 compatible FAT file system, and our tiny thread aware UDP/IP stack. 00054 00055 http://www.OpenRTOS.com - Real Time Engineers ltd license FreeRTOS to High 00056 Integrity Systems to sell under the OpenRTOS brand. Low cost OpenRTOS 00057 licenses offer ticketed support, indemnification and middleware. 00058 00059 http://www.SafeRTOS.com - High Integrity Systems also provide a safety 00060 engineered and independently SIL3 certified version for use in safety and 00061 mission critical applications that require provable dependability. 00062 00063 1 tab == 4 spaces! 00064 */ 00065 00066 00067 #ifndef INC_TASK_H 00068 #define INC_TASK_H 00069 00070 #ifndef INC_FREERTOS_H 00071 #error "include FreeRTOS.h must appear in source files before include task.h" 00072 #endif 00073 00074 #include "list.h" 00075 00076 #ifdef __cplusplus 00077 extern "C" { 00078 #endif 00079 00080 /*----------------------------------------------------------- 00081 * MACROS AND DEFINITIONS 00082 *----------------------------------------------------------*/ 00083 00084 #define tskKERNEL_VERSION_NUMBER "V7.6.0" 00085 00086 /** 00087 * task. h 00088 * 00089 * Type by which tasks are referenced. For example, a call to xTaskCreate 00090 * returns (via a pointer parameter) an xTaskHandle variable that can then 00091 * be used as a parameter to vTaskDelete to delete the task. 00092 * 00093 * \defgroup xTaskHandle xTaskHandle 00094 * \ingroup Tasks 00095 */ 00096 typedef void * xTaskHandle; 00097 00098 /* Task states returned by eTaskGetState. */ 00099 typedef enum 00100 { 00101 eRunning = 0, /* A task is querying the state of itself, so must be running. */ 00102 eReady, /* The task being queried is in a read or pending ready list. */ 00103 eBlocked, /* The task being queried is in the Blocked state. */ 00104 eSuspended, /* The task being queried is in the Suspended state, or is in the Blocked state with an infinite time out. */ 00105 eDeleted /* The task being queried has been deleted, but its TCB has not yet been freed. */ 00106 } eTaskState; 00107 00108 /* 00109 * Used internally only. 00110 */ 00111 typedef struct xTIME_OUT 00112 { 00113 portBASE_TYPE xOverflowCount; 00114 portTickType xTimeOnEntering; 00115 } xTimeOutType; 00116 00117 /* 00118 * Defines the memory ranges allocated to the task when an MPU is used. 00119 */ 00120 typedef struct xMEMORY_REGION 00121 { 00122 void *pvBaseAddress; 00123 unsigned long ulLengthInBytes; 00124 unsigned long ulParameters; 00125 } xMemoryRegion; 00126 00127 /* 00128 * Parameters required to create an MPU protected task. 00129 */ 00130 typedef struct xTASK_PARAMTERS 00131 { 00132 pdTASK_CODE pvTaskCode; 00133 const signed char * const pcName; 00134 unsigned short usStackDepth; 00135 void *pvParameters; 00136 unsigned portBASE_TYPE uxPriority; 00137 portSTACK_TYPE *puxStackBuffer; 00138 xMemoryRegion xRegions[ portNUM_CONFIGURABLE_REGIONS ]; 00139 } xTaskParameters; 00140 00141 /* Used with the uxTaskGetSystemState() function to return the state of each task 00142 in the system. */ 00143 typedef struct xTASK_STATUS 00144 { 00145 xTaskHandle xHandle; /* The handle of the task to which the rest of the information in the structure relates. */ 00146 const signed char *pcTaskName; /* A pointer to the task's name. This value will be invalid if the task was deleted since the structure was populated! */ 00147 unsigned portBASE_TYPE xTaskNumber; /* A number unique to the task. */ 00148 eTaskState eCurrentState; /* The state in which the task existed when the structure was populated. */ 00149 unsigned portBASE_TYPE uxCurrentPriority; /* The priority at which the task was running (may be inherited) when the structure was populated. */ 00150 unsigned portBASE_TYPE 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. */ 00151 unsigned long ulRunTimeCounter; /* The total run time allocated to the task so far, as defined by the run time stats clock. See http://www.freertos.org/rtos-run-time-stats.html. Only valid when configGENERATE_RUN_TIME_STATS is defined as 1 in FreeRTOSConfig.h. */ 00152 unsigned short 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. */ 00153 } xTaskStatusType; 00154 00155 /* Possible return values for eTaskConfirmSleepModeStatus(). */ 00156 typedef enum 00157 { 00158 eAbortSleep = 0, /* A task has been made ready or a context switch pended since portSUPPORESS_TICKS_AND_SLEEP() was called - abort entering a sleep mode. */ 00159 eStandardSleep, /* Enter a sleep mode that will not last any longer than the expected idle time. */ 00160 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. */ 00161 } eSleepModeStatus; 00162 00163 00164 /* 00165 * Defines the priority used by the idle task. This must not be modified. 00166 * 00167 * \ingroup TaskUtils 00168 */ 00169 #define tskIDLE_PRIORITY ( ( unsigned portBASE_TYPE ) 0U ) 00170 00171 /** 00172 * task. h 00173 * 00174 * Macro for forcing a context switch. 00175 * 00176 * \defgroup taskYIELD taskYIELD 00177 * \ingroup SchedulerControl 00178 */ 00179 #define taskYIELD() portYIELD() 00180 00181 /** 00182 * task. h 00183 * 00184 * Macro to mark the start of a critical code region. Preemptive context 00185 * switches cannot occur when in a critical region. 00186 * 00187 * NOTE: This may alter the stack (depending on the portable implementation) 00188 * so must be used with care! 00189 * 00190 * \defgroup taskENTER_CRITICAL taskENTER_CRITICAL 00191 * \ingroup SchedulerControl 00192 */ 00193 #define taskENTER_CRITICAL() portENTER_CRITICAL() 00194 00195 /** 00196 * task. h 00197 * 00198 * Macro to mark the end of a critical code region. Preemptive context 00199 * switches cannot occur when in a critical region. 00200 * 00201 * NOTE: This may alter the stack (depending on the portable implementation) 00202 * so must be used with care! 00203 * 00204 * \defgroup taskEXIT_CRITICAL taskEXIT_CRITICAL 00205 * \ingroup SchedulerControl 00206 */ 00207 #define taskEXIT_CRITICAL() portEXIT_CRITICAL() 00208 00209 /** 00210 * task. h 00211 * 00212 * Macro to disable all maskable interrupts. 00213 * 00214 * \defgroup taskDISABLE_INTERRUPTS taskDISABLE_INTERRUPTS 00215 * \ingroup SchedulerControl 00216 */ 00217 #define taskDISABLE_INTERRUPTS() portDISABLE_INTERRUPTS() 00218 00219 /** 00220 * task. h 00221 * 00222 * Macro to enable microcontroller interrupts. 00223 * 00224 * \defgroup taskENABLE_INTERRUPTS taskENABLE_INTERRUPTS 00225 * \ingroup SchedulerControl 00226 */ 00227 #define taskENABLE_INTERRUPTS() portENABLE_INTERRUPTS() 00228 00229 /* Definitions returned by xTaskGetSchedulerState(). */ 00230 #define taskSCHEDULER_NOT_STARTED ( ( portBASE_TYPE ) 0 ) 00231 #define taskSCHEDULER_RUNNING ( ( portBASE_TYPE ) 1 ) 00232 #define taskSCHEDULER_SUSPENDED ( ( portBASE_TYPE ) 2 ) 00233 00234 /*----------------------------------------------------------- 00235 * TASK CREATION API 00236 *----------------------------------------------------------*/ 00237 00238 /** 00239 * task. h 00240 *<pre> 00241 portBASE_TYPE xTaskCreate( 00242 pdTASK_CODE pvTaskCode, 00243 const char * const pcName, 00244 unsigned short usStackDepth, 00245 void *pvParameters, 00246 unsigned portBASE_TYPE uxPriority, 00247 xTaskHandle *pvCreatedTask 00248 );</pre> 00249 * 00250 * Create a new task and add it to the list of tasks that are ready to run. 00251 * 00252 * xTaskCreate() can only be used to create a task that has unrestricted 00253 * access to the entire microcontroller memory map. Systems that include MPU 00254 * support can alternatively create an MPU constrained task using 00255 * xTaskCreateRestricted(). 00256 * 00257 * @param pvTaskCode Pointer to the task entry function. Tasks 00258 * must be implemented to never return (i.e. continuous loop). 00259 * 00260 * @param pcName A descriptive name for the task. This is mainly used to 00261 * facilitate debugging. Max length defined by tskMAX_TASK_NAME_LEN - default 00262 * is 16. 00263 * 00264 * @param usStackDepth The size of the task stack specified as the number of 00265 * variables the stack can hold - not the number of bytes. For example, if 00266 * the stack is 16 bits wide and usStackDepth is defined as 100, 200 bytes 00267 * will be allocated for stack storage. 00268 * 00269 * @param pvParameters Pointer that will be used as the parameter for the task 00270 * being created. 00271 * 00272 * @param uxPriority The priority at which the task should run. Systems that 00273 * include MPU support can optionally create tasks in a privileged (system) 00274 * mode by setting bit portPRIVILEGE_BIT of the priority parameter. For 00275 * example, to create a privileged task at priority 2 the uxPriority parameter 00276 * should be set to ( 2 | portPRIVILEGE_BIT ). 00277 * 00278 * @param pvCreatedTask Used to pass back a handle by which the created task 00279 * can be referenced. 00280 * 00281 * @return pdPASS if the task was successfully created and added to a ready 00282 * list, otherwise an error code defined in the file errors. h 00283 * 00284 * Example usage: 00285 <pre> 00286 // Task to be created. 00287 void vTaskCode( void * pvParameters ) 00288 { 00289 for( ;; ) 00290 { 00291 // Task code goes here. 00292 } 00293 } 00294 00295 // Function that creates a task. 00296 void vOtherFunction( void ) 00297 { 00298 static unsigned char ucParameterToPass; 00299 xTaskHandle xHandle; 00300 00301 // Create the task, storing the handle. Note that the passed parameter ucParameterToPass 00302 // must exist for the lifetime of the task, so in this case is declared static. If it was just an 00303 // an automatic stack variable it might no longer exist, or at least have been corrupted, by the time 00304 // the new task attempts to access it. 00305 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, &ucParameterToPass, tskIDLE_PRIORITY, &xHandle ); 00306 00307 // Use the handle to delete the task. 00308 vTaskDelete( xHandle ); 00309 } 00310 </pre> 00311 * \defgroup xTaskCreate xTaskCreate 00312 * \ingroup Tasks 00313 */ 00314 #define xTaskCreate( pvTaskCode, pcName, usStackDepth, pvParameters, uxPriority, pxCreatedTask ) xTaskGenericCreate( ( pvTaskCode ), ( pcName ), ( usStackDepth ), ( pvParameters ), ( uxPriority ), ( pxCreatedTask ), ( NULL ), ( NULL ) ) 00315 00316 /** 00317 * task. h 00318 *<pre> 00319 portBASE_TYPE xTaskCreateRestricted( xTaskParameters *pxTaskDefinition, xTaskHandle *pxCreatedTask );</pre> 00320 * 00321 * xTaskCreateRestricted() should only be used in systems that include an MPU 00322 * implementation. 00323 * 00324 * Create a new task and add it to the list of tasks that are ready to run. 00325 * The function parameters define the memory regions and associated access 00326 * permissions allocated to the task. 00327 * 00328 * @param pxTaskDefinition Pointer to a structure that contains a member 00329 * for each of the normal xTaskCreate() parameters (see the xTaskCreate() API 00330 * documentation) plus an optional stack buffer and the memory region 00331 * definitions. 00332 * 00333 * @param pxCreatedTask Used to pass back a handle by which the created task 00334 * can be referenced. 00335 * 00336 * @return pdPASS if the task was successfully created and added to a ready 00337 * list, otherwise an error code defined in the file errors. h 00338 * 00339 * Example usage: 00340 <pre> 00341 // Create an xTaskParameters structure that defines the task to be created. 00342 static const xTaskParameters xCheckTaskParameters = 00343 { 00344 vATask, // pvTaskCode - the function that implements the task. 00345 "ATask", // pcName - just a text name for the task to assist debugging. 00346 100, // usStackDepth - the stack size DEFINED IN WORDS. 00347 NULL, // pvParameters - passed into the task function as the function parameters. 00348 ( 1UL | portPRIVILEGE_BIT ),// uxPriority - task priority, set the portPRIVILEGE_BIT if the task should run in a privileged state. 00349 cStackBuffer,// puxStackBuffer - the buffer to be used as the task stack. 00350 00351 // xRegions - Allocate up to three separate memory regions for access by 00352 // the task, with appropriate access permissions. Different processors have 00353 // different memory alignment requirements - refer to the FreeRTOS documentation 00354 // for full information. 00355 { 00356 // Base address Length Parameters 00357 { cReadWriteArray, 32, portMPU_REGION_READ_WRITE }, 00358 { cReadOnlyArray, 32, portMPU_REGION_READ_ONLY }, 00359 { cPrivilegedOnlyAccessArray, 128, portMPU_REGION_PRIVILEGED_READ_WRITE } 00360 } 00361 }; 00362 00363 int main( void ) 00364 { 00365 xTaskHandle xHandle; 00366 00367 // Create a task from the const structure defined above. The task handle 00368 // is requested (the second parameter is not NULL) but in this case just for 00369 // demonstration purposes as its not actually used. 00370 xTaskCreateRestricted( &xRegTest1Parameters, &xHandle ); 00371 00372 // Start the scheduler. 00373 vTaskStartScheduler(); 00374 00375 // Will only get here if there was insufficient memory to create the idle 00376 // task. 00377 for( ;; ); 00378 } 00379 </pre> 00380 * \defgroup xTaskCreateRestricted xTaskCreateRestricted 00381 * \ingroup Tasks 00382 */ 00383 #define xTaskCreateRestricted( x, pxCreatedTask ) xTaskGenericCreate( ((x)->pvTaskCode), ((x)->pcName), ((x)->usStackDepth), ((x)->pvParameters), ((x)->uxPriority), (pxCreatedTask), ((x)->puxStackBuffer), ((x)->xRegions) ) 00384 00385 /** 00386 * task. h 00387 *<pre> 00388 void vTaskAllocateMPURegions( xTaskHandle xTask, const xMemoryRegion * const pxRegions );</pre> 00389 * 00390 * Memory regions are assigned to a restricted task when the task is created by 00391 * a call to xTaskCreateRestricted(). These regions can be redefined using 00392 * vTaskAllocateMPURegions(). 00393 * 00394 * @param xTask The handle of the task being updated. 00395 * 00396 * @param xRegions A pointer to an xMemoryRegion structure that contains the 00397 * new memory region definitions. 00398 * 00399 * Example usage: 00400 <pre> 00401 // Define an array of xMemoryRegion structures that configures an MPU region 00402 // allowing read/write access for 1024 bytes starting at the beginning of the 00403 // ucOneKByte array. The other two of the maximum 3 definable regions are 00404 // unused so set to zero. 00405 static const xMemoryRegion xAltRegions[ portNUM_CONFIGURABLE_REGIONS ] = 00406 { 00407 // Base address Length Parameters 00408 { ucOneKByte, 1024, portMPU_REGION_READ_WRITE }, 00409 { 0, 0, 0 }, 00410 { 0, 0, 0 } 00411 }; 00412 00413 void vATask( void *pvParameters ) 00414 { 00415 // This task was created such that it has access to certain regions of 00416 // memory as defined by the MPU configuration. At some point it is 00417 // desired that these MPU regions are replaced with that defined in the 00418 // xAltRegions const struct above. Use a call to vTaskAllocateMPURegions() 00419 // for this purpose. NULL is used as the task handle to indicate that this 00420 // function should modify the MPU regions of the calling task. 00421 vTaskAllocateMPURegions( NULL, xAltRegions ); 00422 00423 // Now the task can continue its function, but from this point on can only 00424 // access its stack and the ucOneKByte array (unless any other statically 00425 // defined or shared regions have been declared elsewhere). 00426 } 00427 </pre> 00428 * \defgroup xTaskCreateRestricted xTaskCreateRestricted 00429 * \ingroup Tasks 00430 */ 00431 void vTaskAllocateMPURegions( xTaskHandle xTask, const xMemoryRegion * const pxRegions ) PRIVILEGED_FUNCTION; 00432 00433 /** 00434 * task. h 00435 * <pre>void vTaskDelete( xTaskHandle xTask );</pre> 00436 * 00437 * INCLUDE_vTaskDelete must be defined as 1 for this function to be available. 00438 * See the configuration section for more information. 00439 * 00440 * Remove a task from the RTOS real time kernels management. The task being 00441 * deleted will be removed from all ready, blocked, suspended and event lists. 00442 * 00443 * NOTE: The idle task is responsible for freeing the kernel allocated 00444 * memory from tasks that have been deleted. It is therefore important that 00445 * the idle task is not starved of microcontroller processing time if your 00446 * application makes any calls to vTaskDelete (). Memory allocated by the 00447 * task code is not automatically freed, and should be freed before the task 00448 * is deleted. 00449 * 00450 * See the demo application file death.c for sample code that utilises 00451 * vTaskDelete (). 00452 * 00453 * @param xTask The handle of the task to be deleted. Passing NULL will 00454 * cause the calling task to be deleted. 00455 * 00456 * Example usage: 00457 <pre> 00458 void vOtherFunction( void ) 00459 { 00460 xTaskHandle xHandle; 00461 00462 // Create the task, storing the handle. 00463 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle ); 00464 00465 // Use the handle to delete the task. 00466 vTaskDelete( xHandle ); 00467 } 00468 </pre> 00469 * \defgroup vTaskDelete vTaskDelete 00470 * \ingroup Tasks 00471 */ 00472 void vTaskDelete( xTaskHandle xTaskToDelete ) PRIVILEGED_FUNCTION; 00473 00474 /*----------------------------------------------------------- 00475 * TASK CONTROL API 00476 *----------------------------------------------------------*/ 00477 00478 /** 00479 * task. h 00480 * <pre>void vTaskDelay( portTickType xTicksToDelay );</pre> 00481 * 00482 * Delay a task for a given number of ticks. The actual time that the 00483 * task remains blocked depends on the tick rate. The constant 00484 * portTICK_RATE_MS can be used to calculate real time from the tick 00485 * rate - with the resolution of one tick period. 00486 * 00487 * INCLUDE_vTaskDelay must be defined as 1 for this function to be available. 00488 * See the configuration section for more information. 00489 * 00490 * 00491 * vTaskDelay() specifies a time at which the task wishes to unblock relative to 00492 * the time at which vTaskDelay() is called. For example, specifying a block 00493 * period of 100 ticks will cause the task to unblock 100 ticks after 00494 * vTaskDelay() is called. vTaskDelay() does not therefore provide a good method 00495 * of controlling the frequency of a cyclical task as the path taken through the 00496 * code, as well as other task and interrupt activity, will effect the frequency 00497 * at which vTaskDelay() gets called and therefore the time at which the task 00498 * next executes. See vTaskDelayUntil() for an alternative API function designed 00499 * to facilitate fixed frequency execution. It does this by specifying an 00500 * absolute time (rather than a relative time) at which the calling task should 00501 * unblock. 00502 * 00503 * @param xTicksToDelay The amount of time, in tick periods, that 00504 * the calling task should block. 00505 * 00506 * Example usage: 00507 00508 void vTaskFunction( void * pvParameters ) 00509 { 00510 void vTaskFunction( void * pvParameters ) 00511 { 00512 // Block for 500ms. 00513 const portTickType xDelay = 500 / portTICK_RATE_MS; 00514 00515 for( ;; ) 00516 { 00517 // Simply toggle the LED every 500ms, blocking between each toggle. 00518 vToggleLED(); 00519 vTaskDelay( xDelay ); 00520 } 00521 } 00522 00523 * \defgroup vTaskDelay vTaskDelay 00524 * \ingroup TaskCtrl 00525 */ 00526 void vTaskDelay( portTickType xTicksToDelay ) PRIVILEGED_FUNCTION; 00527 00528 /** 00529 * task. h 00530 * <pre>void vTaskDelayUntil( portTickType *pxPreviousWakeTime, portTickType xTimeIncrement );</pre> 00531 * 00532 * INCLUDE_vTaskDelayUntil must be defined as 1 for this function to be available. 00533 * See the configuration section for more information. 00534 * 00535 * Delay a task until a specified time. This function can be used by cyclical 00536 * tasks to ensure a constant execution frequency. 00537 * 00538 * This function differs from vTaskDelay () in one important aspect: vTaskDelay () will 00539 * cause a task to block for the specified number of ticks from the time vTaskDelay () is 00540 * called. It is therefore difficult to use vTaskDelay () by itself to generate a fixed 00541 * execution frequency as the time between a task starting to execute and that task 00542 * calling vTaskDelay () may not be fixed [the task may take a different path though the 00543 * code between calls, or may get interrupted or preempted a different number of times 00544 * each time it executes]. 00545 * 00546 * Whereas vTaskDelay () specifies a wake time relative to the time at which the function 00547 * is called, vTaskDelayUntil () specifies the absolute (exact) time at which it wishes to 00548 * unblock. 00549 * 00550 * The constant portTICK_RATE_MS can be used to calculate real time from the tick 00551 * rate - with the resolution of one tick period. 00552 * 00553 * @param pxPreviousWakeTime Pointer to a variable that holds the time at which the 00554 * task was last unblocked. The variable must be initialised with the current time 00555 * prior to its first use (see the example below). Following this the variable is 00556 * automatically updated within vTaskDelayUntil (). 00557 * 00558 * @param xTimeIncrement The cycle time period. The task will be unblocked at 00559 * time *pxPreviousWakeTime + xTimeIncrement. Calling vTaskDelayUntil with the 00560 * same xTimeIncrement parameter value will cause the task to execute with 00561 * a fixed interface period. 00562 * 00563 * Example usage: 00564 <pre> 00565 // Perform an action every 10 ticks. 00566 void vTaskFunction( void * pvParameters ) 00567 { 00568 portTickType xLastWakeTime; 00569 const portTickType xFrequency = 10; 00570 00571 // Initialise the xLastWakeTime variable with the current time. 00572 xLastWakeTime = xTaskGetTickCount (); 00573 for( ;; ) 00574 { 00575 // Wait for the next cycle. 00576 vTaskDelayUntil( &xLastWakeTime, xFrequency ); 00577 00578 // Perform action here. 00579 } 00580 } 00581 </pre> 00582 * \defgroup vTaskDelayUntil vTaskDelayUntil 00583 * \ingroup TaskCtrl 00584 */ 00585 void vTaskDelayUntil( portTickType * const pxPreviousWakeTime, portTickType xTimeIncrement ) PRIVILEGED_FUNCTION; 00586 00587 /** 00588 * task. h 00589 * <pre>unsigned portBASE_TYPE uxTaskPriorityGet( xTaskHandle xTask );</pre> 00590 * 00591 * INCLUDE_xTaskPriorityGet must be defined as 1 for this function to be available. 00592 * See the configuration section for more information. 00593 * 00594 * Obtain the priority of any task. 00595 * 00596 * @param xTask Handle of the task to be queried. Passing a NULL 00597 * handle results in the priority of the calling task being returned. 00598 * 00599 * @return The priority of xTask. 00600 * 00601 * Example usage: 00602 <pre> 00603 void vAFunction( void ) 00604 { 00605 xTaskHandle xHandle; 00606 00607 // Create a task, storing the handle. 00608 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle ); 00609 00610 // ... 00611 00612 // Use the handle to obtain the priority of the created task. 00613 // It was created with tskIDLE_PRIORITY, but may have changed 00614 // it itself. 00615 if( uxTaskPriorityGet( xHandle ) != tskIDLE_PRIORITY ) 00616 { 00617 // The task has changed it's priority. 00618 } 00619 00620 // ... 00621 00622 // Is our priority higher than the created task? 00623 if( uxTaskPriorityGet( xHandle ) < uxTaskPriorityGet( NULL ) ) 00624 { 00625 // Our priority (obtained using NULL handle) is higher. 00626 } 00627 } 00628 </pre> 00629 * \defgroup uxTaskPriorityGet uxTaskPriorityGet 00630 * \ingroup TaskCtrl 00631 */ 00632 unsigned portBASE_TYPE uxTaskPriorityGet( xTaskHandle xTask ) PRIVILEGED_FUNCTION; 00633 00634 /** 00635 * task. h 00636 * <pre>eTaskState eTaskGetState( xTaskHandle xTask );</pre> 00637 * 00638 * INCLUDE_eTaskGetState must be defined as 1 for this function to be available. 00639 * See the configuration section for more information. 00640 * 00641 * Obtain the state of any task. States are encoded by the eTaskState 00642 * enumerated type. 00643 * 00644 * @param xTask Handle of the task to be queried. 00645 * 00646 * @return The state of xTask at the time the function was called. Note the 00647 * state of the task might change between the function being called, and the 00648 * functions return value being tested by the calling task. 00649 */ 00650 eTaskState eTaskGetState( xTaskHandle xTask ) PRIVILEGED_FUNCTION; 00651 00652 /** 00653 * task. h 00654 * <pre>void vTaskPrioritySet( xTaskHandle xTask, unsigned portBASE_TYPE uxNewPriority );</pre> 00655 * 00656 * INCLUDE_vTaskPrioritySet must be defined as 1 for this function to be available. 00657 * See the configuration section for more information. 00658 * 00659 * Set the priority of any task. 00660 * 00661 * A context switch will occur before the function returns if the priority 00662 * being set is higher than the currently executing task. 00663 * 00664 * @param xTask Handle to the task for which the priority is being set. 00665 * Passing a NULL handle results in the priority of the calling task being set. 00666 * 00667 * @param uxNewPriority The priority to which the task will be set. 00668 * 00669 * Example usage: 00670 <pre> 00671 void vAFunction( void ) 00672 { 00673 xTaskHandle xHandle; 00674 00675 // Create a task, storing the handle. 00676 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle ); 00677 00678 // ... 00679 00680 // Use the handle to raise the priority of the created task. 00681 vTaskPrioritySet( xHandle, tskIDLE_PRIORITY + 1 ); 00682 00683 // ... 00684 00685 // Use a NULL handle to raise our priority to the same value. 00686 vTaskPrioritySet( NULL, tskIDLE_PRIORITY + 1 ); 00687 } 00688 </pre> 00689 * \defgroup vTaskPrioritySet vTaskPrioritySet 00690 * \ingroup TaskCtrl 00691 */ 00692 void vTaskPrioritySet( xTaskHandle xTask, unsigned portBASE_TYPE uxNewPriority ) PRIVILEGED_FUNCTION; 00693 00694 /** 00695 * task. h 00696 * <pre>void vTaskSuspend( xTaskHandle xTaskToSuspend );</pre> 00697 * 00698 * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available. 00699 * See the configuration section for more information. 00700 * 00701 * Suspend any task. When suspended a task will never get any microcontroller 00702 * processing time, no matter what its priority. 00703 * 00704 * Calls to vTaskSuspend are not accumulative - 00705 * i.e. calling vTaskSuspend () twice on the same task still only requires one 00706 * call to vTaskResume () to ready the suspended task. 00707 * 00708 * @param xTaskToSuspend Handle to the task being suspended. Passing a NULL 00709 * handle will cause the calling task to be suspended. 00710 * 00711 * Example usage: 00712 <pre> 00713 void vAFunction( void ) 00714 { 00715 xTaskHandle xHandle; 00716 00717 // Create a task, storing the handle. 00718 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle ); 00719 00720 // ... 00721 00722 // Use the handle to suspend the created task. 00723 vTaskSuspend( xHandle ); 00724 00725 // ... 00726 00727 // The created task will not run during this period, unless 00728 // another task calls vTaskResume( xHandle ). 00729 00730 //... 00731 00732 00733 // Suspend ourselves. 00734 vTaskSuspend( NULL ); 00735 00736 // We cannot get here unless another task calls vTaskResume 00737 // with our handle as the parameter. 00738 } 00739 </pre> 00740 * \defgroup vTaskSuspend vTaskSuspend 00741 * \ingroup TaskCtrl 00742 */ 00743 void vTaskSuspend( xTaskHandle xTaskToSuspend ) PRIVILEGED_FUNCTION; 00744 00745 /** 00746 * task. h 00747 * <pre>void vTaskResume( xTaskHandle xTaskToResume );</pre> 00748 * 00749 * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available. 00750 * See the configuration section for more information. 00751 * 00752 * Resumes a suspended task. 00753 * 00754 * A task that has been suspended by one of more calls to vTaskSuspend () 00755 * will be made available for running again by a single call to 00756 * vTaskResume (). 00757 * 00758 * @param xTaskToResume Handle to the task being readied. 00759 * 00760 * Example usage: 00761 <pre> 00762 void vAFunction( void ) 00763 { 00764 xTaskHandle xHandle; 00765 00766 // Create a task, storing the handle. 00767 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle ); 00768 00769 // ... 00770 00771 // Use the handle to suspend the created task. 00772 vTaskSuspend( xHandle ); 00773 00774 // ... 00775 00776 // The created task will not run during this period, unless 00777 // another task calls vTaskResume( xHandle ). 00778 00779 //... 00780 00781 00782 // Resume the suspended task ourselves. 00783 vTaskResume( xHandle ); 00784 00785 // The created task will once again get microcontroller processing 00786 // time in accordance with it priority within the system. 00787 } 00788 </pre> 00789 * \defgroup vTaskResume vTaskResume 00790 * \ingroup TaskCtrl 00791 */ 00792 void vTaskResume( xTaskHandle xTaskToResume ) PRIVILEGED_FUNCTION; 00793 00794 /** 00795 * task. h 00796 * <pre>void xTaskResumeFromISR( xTaskHandle xTaskToResume );</pre> 00797 * 00798 * INCLUDE_xTaskResumeFromISR must be defined as 1 for this function to be 00799 * available. See the configuration section for more information. 00800 * 00801 * An implementation of vTaskResume() that can be called from within an ISR. 00802 * 00803 * A task that has been suspended by one of more calls to vTaskSuspend () 00804 * will be made available for running again by a single call to 00805 * xTaskResumeFromISR (). 00806 * 00807 * @param xTaskToResume Handle to the task being readied. 00808 * 00809 * \defgroup vTaskResumeFromISR vTaskResumeFromISR 00810 * \ingroup TaskCtrl 00811 */ 00812 portBASE_TYPE xTaskResumeFromISR( xTaskHandle xTaskToResume ) PRIVILEGED_FUNCTION; 00813 00814 /*----------------------------------------------------------- 00815 * SCHEDULER CONTROL 00816 *----------------------------------------------------------*/ 00817 00818 /** 00819 * task. h 00820 * <pre>void vTaskStartScheduler( void );</pre> 00821 * 00822 * Starts the real time kernel tick processing. After calling the kernel 00823 * has control over which tasks are executed and when. This function 00824 * does not return until an executing task calls vTaskEndScheduler (). 00825 * 00826 * At least one task should be created via a call to xTaskCreate () 00827 * before calling vTaskStartScheduler (). The idle task is created 00828 * automatically when the first application task is created. 00829 * 00830 * See the demo application file main.c for an example of creating 00831 * tasks and starting the kernel. 00832 * 00833 * Example usage: 00834 <pre> 00835 void vAFunction( void ) 00836 { 00837 // Create at least one task before starting the kernel. 00838 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL ); 00839 00840 // Start the real time kernel with preemption. 00841 vTaskStartScheduler (); 00842 00843 // Will not get here unless a task calls vTaskEndScheduler () 00844 } 00845 </pre> 00846 * 00847 * \defgroup vTaskStartScheduler vTaskStartScheduler 00848 * \ingroup SchedulerControl 00849 */ 00850 void vTaskStartScheduler( void ) PRIVILEGED_FUNCTION; 00851 00852 /** 00853 * task. h 00854 * <pre>void vTaskEndScheduler( void );</pre> 00855 * 00856 * Stops the real time kernel tick. All created tasks will be automatically 00857 * deleted and multitasking (either preemptive or cooperative) will 00858 * stop. Execution then resumes from the point where vTaskStartScheduler () 00859 * was called, as if vTaskStartScheduler () had just returned. 00860 * 00861 * See the demo application file main. c in the demo/PC directory for an 00862 * example that uses vTaskEndScheduler (). 00863 * 00864 * vTaskEndScheduler () requires an exit function to be defined within the 00865 * portable layer (see vPortEndScheduler () in port. c for the PC port). This 00866 * performs hardware specific operations such as stopping the kernel tick. 00867 * 00868 * vTaskEndScheduler () will cause all of the resources allocated by the 00869 * kernel to be freed - but will not free resources allocated by application 00870 * tasks. 00871 * 00872 * Example usage: 00873 <pre> 00874 void vTaskCode( void * pvParameters ) 00875 { 00876 for( ;; ) 00877 { 00878 // Task code goes here. 00879 00880 // At some point we want to end the real time kernel processing 00881 // so call ... 00882 vTaskEndScheduler (); 00883 } 00884 } 00885 00886 void vAFunction( void ) 00887 { 00888 // Create at least one task before starting the kernel. 00889 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL ); 00890 00891 // Start the real time kernel with preemption. 00892 vTaskStartScheduler (); 00893 00894 // Will only get here when the vTaskCode () task has called 00895 // vTaskEndScheduler (). When we get here we are back to single task 00896 // execution. 00897 } 00898 </pre> 00899 * 00900 * \defgroup vTaskEndScheduler vTaskEndScheduler 00901 * \ingroup SchedulerControl 00902 */ 00903 void vTaskEndScheduler( void ) PRIVILEGED_FUNCTION; 00904 00905 /** 00906 * task. h 00907 * <pre>void vTaskSuspendAll( void );</pre> 00908 * 00909 * Suspends all real time kernel activity while keeping interrupts (including the 00910 * kernel tick) enabled. 00911 * 00912 * After calling vTaskSuspendAll () the calling task will continue to execute 00913 * without risk of being swapped out until a call to xTaskResumeAll () has been 00914 * made. 00915 * 00916 * API functions that have the potential to cause a context switch (for example, 00917 * vTaskDelayUntil(), xQueueSend(), etc.) must not be called while the scheduler 00918 * is suspended. 00919 * 00920 * Example usage: 00921 <pre> 00922 void vTask1( void * pvParameters ) 00923 { 00924 for( ;; ) 00925 { 00926 // Task code goes here. 00927 00928 // ... 00929 00930 // At some point the task wants to perform a long operation during 00931 // which it does not want to get swapped out. It cannot use 00932 // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the 00933 // operation may cause interrupts to be missed - including the 00934 // ticks. 00935 00936 // Prevent the real time kernel swapping out the task. 00937 vTaskSuspendAll (); 00938 00939 // Perform the operation here. There is no need to use critical 00940 // sections as we have all the microcontroller processing time. 00941 // During this time interrupts will still operate and the kernel 00942 // tick count will be maintained. 00943 00944 // ... 00945 00946 // The operation is complete. Restart the kernel. 00947 xTaskResumeAll (); 00948 } 00949 } 00950 </pre> 00951 * \defgroup vTaskSuspendAll vTaskSuspendAll 00952 * \ingroup SchedulerControl 00953 */ 00954 void vTaskSuspendAll( void ) PRIVILEGED_FUNCTION; 00955 00956 /** 00957 * task. h 00958 * <pre>char xTaskResumeAll( void );</pre> 00959 * 00960 * Resumes real time kernel activity following a call to vTaskSuspendAll (). 00961 * After a call to vTaskSuspendAll () the kernel will take control of which 00962 * task is executing at any time. 00963 * 00964 * @return If resuming the scheduler caused a context switch then pdTRUE is 00965 * returned, otherwise pdFALSE is returned. 00966 * 00967 * Example usage: 00968 <pre> 00969 void vTask1( void * pvParameters ) 00970 { 00971 for( ;; ) 00972 { 00973 // Task code goes here. 00974 00975 // ... 00976 00977 // At some point the task wants to perform a long operation during 00978 // which it does not want to get swapped out. It cannot use 00979 // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the 00980 // operation may cause interrupts to be missed - including the 00981 // ticks. 00982 00983 // Prevent the real time kernel swapping out the task. 00984 vTaskSuspendAll (); 00985 00986 // Perform the operation here. There is no need to use critical 00987 // sections as we have all the microcontroller processing time. 00988 // During this time interrupts will still operate and the real 00989 // time kernel tick count will be maintained. 00990 00991 // ... 00992 00993 // The operation is complete. Restart the kernel. We want to force 00994 // a context switch - but there is no point if resuming the scheduler 00995 // caused a context switch already. 00996 if( !xTaskResumeAll () ) 00997 { 00998 taskYIELD (); 00999 } 01000 } 01001 } 01002 </pre> 01003 * \defgroup xTaskResumeAll xTaskResumeAll 01004 * \ingroup SchedulerControl 01005 */ 01006 signed portBASE_TYPE xTaskResumeAll( void ) PRIVILEGED_FUNCTION; 01007 01008 /** 01009 * task. h 01010 * <pre>signed portBASE_TYPE xTaskIsTaskSuspended( const xTaskHandle xTask );</pre> 01011 * 01012 * Utility task that simply returns pdTRUE if the task referenced by xTask is 01013 * currently in the Suspended state, or pdFALSE if the task referenced by xTask 01014 * is in any other state. 01015 * 01016 */ 01017 signed portBASE_TYPE xTaskIsTaskSuspended( xTaskHandle xTask ) PRIVILEGED_FUNCTION; 01018 01019 /*----------------------------------------------------------- 01020 * TASK UTILITIES 01021 *----------------------------------------------------------*/ 01022 01023 /** 01024 * task. h 01025 * <PRE>portTickType xTaskGetTickCount( void );</PRE> 01026 * 01027 * @return The count of ticks since vTaskStartScheduler was called. 01028 * 01029 * \defgroup xTaskGetTickCount xTaskGetTickCount 01030 * \ingroup TaskUtils 01031 */ 01032 portTickType xTaskGetTickCount( void ) PRIVILEGED_FUNCTION; 01033 01034 /** 01035 * task. h 01036 * <PRE>portTickType xTaskGetTickCountFromISR( void );</PRE> 01037 * 01038 * @return The count of ticks since vTaskStartScheduler was called. 01039 * 01040 * This is a version of xTaskGetTickCount() that is safe to be called from an 01041 * ISR - provided that portTickType is the natural word size of the 01042 * microcontroller being used or interrupt nesting is either not supported or 01043 * not being used. 01044 * 01045 * \defgroup xTaskGetTickCount xTaskGetTickCount 01046 * \ingroup TaskUtils 01047 */ 01048 portTickType xTaskGetTickCountFromISR( void ) PRIVILEGED_FUNCTION; 01049 01050 /** 01051 * task. h 01052 * <PRE>unsigned short uxTaskGetNumberOfTasks( void );</PRE> 01053 * 01054 * @return The number of tasks that the real time kernel is currently managing. 01055 * This includes all ready, blocked and suspended tasks. A task that 01056 * has been deleted but not yet freed by the idle task will also be 01057 * included in the count. 01058 * 01059 * \defgroup uxTaskGetNumberOfTasks uxTaskGetNumberOfTasks 01060 * \ingroup TaskUtils 01061 */ 01062 unsigned portBASE_TYPE uxTaskGetNumberOfTasks( void ) PRIVILEGED_FUNCTION; 01063 01064 /** 01065 * task. h 01066 * <PRE>signed char *pcTaskGetTaskName( xTaskHandle xTaskToQuery );</PRE> 01067 * 01068 * @return The text (human readable) name of the task referenced by the handle 01069 * xTaskToQueury. A task can query its own name by either passing in its own 01070 * handle, or by setting xTaskToQuery to NULL. INCLUDE_pcTaskGetTaskName must be 01071 * set to 1 in FreeRTOSConfig.h for pcTaskGetTaskName() to be available. 01072 * 01073 * \defgroup pcTaskGetTaskName pcTaskGetTaskName 01074 * \ingroup TaskUtils 01075 */ 01076 signed char *pcTaskGetTaskName( xTaskHandle xTaskToQuery ); 01077 01078 /** 01079 * task.h 01080 * <PRE>unsigned portBASE_TYPE uxTaskGetStackHighWaterMark( xTaskHandle xTask );</PRE> 01081 * 01082 * INCLUDE_uxTaskGetStackHighWaterMark must be set to 1 in FreeRTOSConfig.h for 01083 * this function to be available. 01084 * 01085 * Returns the high water mark of the stack associated with xTask. That is, 01086 * the minimum free stack space there has been (in words, so on a 32 bit machine 01087 * a value of 1 means 4 bytes) since the task started. The smaller the returned 01088 * number the closer the task has come to overflowing its stack. 01089 * 01090 * @param xTask Handle of the task associated with the stack to be checked. 01091 * Set xTask to NULL to check the stack of the calling task. 01092 * 01093 * @return The smallest amount of free stack space there has been (in bytes) 01094 * since the task referenced by xTask was created. 01095 */ 01096 unsigned portBASE_TYPE uxTaskGetStackHighWaterMark( xTaskHandle xTask ) PRIVILEGED_FUNCTION; 01097 01098 /* When using trace macros it is sometimes necessary to include tasks.h before 01099 FreeRTOS.h. When this is done pdTASK_HOOK_CODE will not yet have been defined, 01100 so the following two prototypes will cause a compilation error. This can be 01101 fixed by simply guarding against the inclusion of these two prototypes unless 01102 they are explicitly required by the configUSE_APPLICATION_TASK_TAG configuration 01103 constant. */ 01104 #ifdef configUSE_APPLICATION_TASK_TAG 01105 #if configUSE_APPLICATION_TASK_TAG == 1 01106 /** 01107 * task.h 01108 * <pre>void vTaskSetApplicationTaskTag( xTaskHandle xTask, pdTASK_HOOK_CODE pxHookFunction );</pre> 01109 * 01110 * Sets pxHookFunction to be the task hook function used by the task xTask. 01111 * Passing xTask as NULL has the effect of setting the calling tasks hook 01112 * function. 01113 */ 01114 void vTaskSetApplicationTaskTag( xTaskHandle xTask, pdTASK_HOOK_CODE pxHookFunction ) PRIVILEGED_FUNCTION; 01115 01116 /** 01117 * task.h 01118 * <pre>void xTaskGetApplicationTaskTag( xTaskHandle xTask );</pre> 01119 * 01120 * Returns the pxHookFunction value assigned to the task xTask. 01121 */ 01122 pdTASK_HOOK_CODE xTaskGetApplicationTaskTag( xTaskHandle xTask ) PRIVILEGED_FUNCTION; 01123 #endif /* configUSE_APPLICATION_TASK_TAG ==1 */ 01124 #endif /* ifdef configUSE_APPLICATION_TASK_TAG */ 01125 01126 /** 01127 * task.h 01128 * <pre>portBASE_TYPE xTaskCallApplicationTaskHook( xTaskHandle xTask, pdTASK_HOOK_CODE pxHookFunction );</pre> 01129 * 01130 * Calls the hook function associated with xTask. Passing xTask as NULL has 01131 * the effect of calling the Running tasks (the calling task) hook function. 01132 * 01133 * pvParameter is passed to the hook function for the task to interpret as it 01134 * wants. 01135 */ 01136 portBASE_TYPE xTaskCallApplicationTaskHook( xTaskHandle xTask, void *pvParameter ) PRIVILEGED_FUNCTION; 01137 01138 /** 01139 * xTaskGetIdleTaskHandle() is only available if 01140 * INCLUDE_xTaskGetIdleTaskHandle is set to 1 in FreeRTOSConfig.h. 01141 * 01142 * Simply returns the handle of the idle task. It is not valid to call 01143 * xTaskGetIdleTaskHandle() before the scheduler has been started. 01144 */ 01145 xTaskHandle xTaskGetIdleTaskHandle( void ); 01146 01147 /** 01148 * configUSE_TRACE_FACILITY must bet defined as 1 in FreeRTOSConfig.h for 01149 * uxTaskGetSystemState() to be available. 01150 * 01151 * uxTaskGetSystemState() populates an xTaskStatusType structure for each task in 01152 * the system. xTaskStatusType structures contain, among other things, members 01153 * for the task handle, task name, task priority, task state, and total amount 01154 * of run time consumed by the task. See the xTaskStatusType structure 01155 * definition in this file for the full member list. 01156 * 01157 * NOTE: This function is intended for debugging use only as its use results in 01158 * the scheduler remaining suspended for an extended period. 01159 * 01160 * @param pxTaskStatusArray A pointer to an array of xTaskStatusType structures. 01161 * The array must contain at least one xTaskStatusType structure for each task 01162 * that is under the control of the RTOS. The number of tasks under the control 01163 * of the RTOS can be determined using the uxTaskGetNumberOfTasks() API function. 01164 * 01165 * @param uxArraySize The size of the array pointed to by the pxTaskStatusArray 01166 * parameter. The size is specified as the number of indexes in the array, or 01167 * the number of xTaskStatusType structures contained in the array, not by the 01168 * number of bytes in the array. 01169 * 01170 * @param pulTotalRunTime If configGENERATE_RUN_TIME_STATS is set to 1 in 01171 * FreeRTOSConfig.h then *pulTotalRunTime is set by uxTaskGetSystemState() to the 01172 * total run time (as defined by the run time stats clock, see 01173 * http://www.freertos.org/rtos-run-time-stats.html) since the target booted. 01174 * pulTotalRunTime can be set to NULL to omit the total run time information. 01175 * 01176 * @return The number of xTaskStatusType structures that were populated by 01177 * uxTaskGetSystemState(). This should equal the number returned by the 01178 * uxTaskGetNumberOfTasks() API function, but will be zero if the value passed 01179 * in the uxArraySize parameter was too small. 01180 * 01181 * Example usage: 01182 <pre> 01183 // This example demonstrates how a human readable table of run time stats 01184 // information is generated from raw data provided by uxTaskGetSystemState(). 01185 // The human readable table is written to pcWriteBuffer 01186 void vTaskGetRunTimeStats( signed char *pcWriteBuffer ) 01187 { 01188 xTaskStatusType *pxTaskStatusArray; 01189 volatile unsigned portBASE_TYPE uxArraySize, x; 01190 unsigned long ulTotalRunTime, ulStatsAsPercentage; 01191 01192 // Make sure the write buffer does not contain a string. 01193 *pcWriteBuffer = 0x00; 01194 01195 // Take a snapshot of the number of tasks in case it changes while this 01196 // function is executing. 01197 uxArraySize = uxCurrentNumberOfTasks(); 01198 01199 // Allocate a xTaskStatusType structure for each task. An array could be 01200 // allocated statically at compile time. 01201 pxTaskStatusArray = pvPortMalloc( uxCurrentNumberOfTasks * sizeof( xTaskStatusType ) ); 01202 01203 if( pxTaskStatusArray != NULL ) 01204 { 01205 // Generate raw status information about each task. 01206 uxArraySize = uxTaskGetSystemState( pxTaskStatusArray, uxArraySize, &ulTotalRunTime ); 01207 01208 // For percentage calculations. 01209 ulTotalRunTime /= 100UL; 01210 01211 // Avoid divide by zero errors. 01212 if( ulTotalRunTime > 0 ) 01213 { 01214 // For each populated position in the pxTaskStatusArray array, 01215 // format the raw data as human readable ASCII data 01216 for( x = 0; x < uxArraySize; x++ ) 01217 { 01218 // What percentage of the total run time has the task used? 01219 // This will always be rounded down to the nearest integer. 01220 // ulTotalRunTimeDiv100 has already been divided by 100. 01221 ulStatsAsPercentage = pxTaskStatusArray[ x ].ulRunTimeCounter / ulTotalRunTime; 01222 01223 if( ulStatsAsPercentage > 0UL ) 01224 { 01225 sprintf( ( char * ) pcWriteBuffer, ( char * ) "%s\t\t%lu\t\t%lu%%\r\n", pxTaskStatusArray[ x ].pcTaskName, pxTaskStatusArray[ x ].ulRunTimeCounter, ulStatsAsPercentage ); 01226 } 01227 else 01228 { 01229 // If the percentage is zero here then the task has 01230 // consumed less than 1% of the total run time. 01231 sprintf( ( char * ) pcWriteBuffer, ( char * ) "%s\t\t%lu\t\t<1%%\r\n", pxTaskStatusArray[ x ].pcTaskName, pxTaskStatusArray[ x ].ulRunTimeCounter ); 01232 } 01233 01234 pcWriteBuffer += strlen( ( char * ) pcWriteBuffer ); 01235 } 01236 } 01237 01238 // The array is no longer needed, free the memory it consumes. 01239 vPortFree( pxTaskStatusArray ); 01240 } 01241 } 01242 </pre> 01243 */ 01244 unsigned portBASE_TYPE uxTaskGetSystemState( xTaskStatusType *pxTaskStatusArray, unsigned portBASE_TYPE uxArraySize, unsigned long *pulTotalRunTime ); 01245 01246 /** 01247 * task. h 01248 * <PRE>void vTaskList( char *pcWriteBuffer );</PRE> 01249 * 01250 * configUSE_TRACE_FACILITY and configUSE_STATS_FORMATTING_FUNCTIONS must 01251 * both be defined as 1 for this function to be available. See the 01252 * configuration section of the FreeRTOS.org website for more information. 01253 * 01254 * NOTE 1: This function will disable interrupts for its duration. It is 01255 * not intended for normal application runtime use but as a debug aid. 01256 * 01257 * Lists all the current tasks, along with their current state and stack 01258 * usage high water mark. 01259 * 01260 * Tasks are reported as blocked ('B'), ready ('R'), deleted ('D') or 01261 * suspended ('S'). 01262 * 01263 * PLEASE NOTE: 01264 * 01265 * This function is provided for convenience only, and is used by many of the 01266 * demo applications. Do not consider it to be part of the scheduler. 01267 * 01268 * vTaskList() calls uxTaskGetSystemState(), then formats part of the 01269 * uxTaskGetSystemState() output into a human readable table that displays task 01270 * names, states and stack usage. 01271 * 01272 * vTaskList() has a dependency on the sprintf() C library function that might 01273 * bloat the code size, use a lot of stack, and provide different results on 01274 * different platforms. An alternative, tiny, third party, and limited 01275 * functionality implementation of sprintf() is provided in many of the 01276 * FreeRTOS/Demo sub-directories in a file called printf-stdarg.c (note 01277 * printf-stdarg.c does not provide a full snprintf() implementation!). 01278 * 01279 * It is recommended that production systems call uxTaskGetSystemState() 01280 * directly to get access to raw stats data, rather than indirectly through a 01281 * call to vTaskList(). 01282 * 01283 * @param pcWriteBuffer A buffer into which the above mentioned details 01284 * will be written, in ascii form. This buffer is assumed to be large 01285 * enough to contain the generated report. Approximately 40 bytes per 01286 * task should be sufficient. 01287 * 01288 * \defgroup vTaskList vTaskList 01289 * \ingroup TaskUtils 01290 */ 01291 void vTaskList( signed char *pcWriteBuffer ) PRIVILEGED_FUNCTION; 01292 01293 /** 01294 * task. h 01295 * <PRE>void vTaskGetRunTimeStats( char *pcWriteBuffer );</PRE> 01296 * 01297 * configGENERATE_RUN_TIME_STATS and configUSE_STATS_FORMATTING_FUNCTIONS 01298 * must both be defined as 1 for this function to be available. The application 01299 * must also then provide definitions for 01300 * portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and portGET_RUN_TIME_COUNTER_VALUE 01301 * to configure a peripheral timer/counter and return the timers current count 01302 * value respectively. The counter should be at least 10 times the frequency of 01303 * the tick count. 01304 * 01305 * NOTE 1: This function will disable interrupts for its duration. It is 01306 * not intended for normal application runtime use but as a debug aid. 01307 * 01308 * Setting configGENERATE_RUN_TIME_STATS to 1 will result in a total 01309 * accumulated execution time being stored for each task. The resolution 01310 * of the accumulated time value depends on the frequency of the timer 01311 * configured by the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() macro. 01312 * Calling vTaskGetRunTimeStats() writes the total execution time of each 01313 * task into a buffer, both as an absolute count value and as a percentage 01314 * of the total system execution time. 01315 * 01316 * NOTE 2: 01317 * 01318 * This function is provided for convenience only, and is used by many of the 01319 * demo applications. Do not consider it to be part of the scheduler. 01320 * 01321 * vTaskGetRunTimeStats() calls uxTaskGetSystemState(), then formats part of the 01322 * uxTaskGetSystemState() output into a human readable table that displays the 01323 * amount of time each task has spent in the Running state in both absolute and 01324 * percentage terms. 01325 * 01326 * vTaskGetRunTimeStats() has a dependency on the sprintf() C library function 01327 * that might bloat the code size, use a lot of stack, and provide different 01328 * results on different platforms. An alternative, tiny, third party, and 01329 * limited functionality implementation of sprintf() is provided in many of the 01330 * FreeRTOS/Demo sub-directories in a file called printf-stdarg.c (note 01331 * printf-stdarg.c does not provide a full snprintf() implementation!). 01332 * 01333 * It is recommended that production systems call uxTaskGetSystemState() directly 01334 * to get access to raw stats data, rather than indirectly through a call to 01335 * vTaskGetRunTimeStats(). 01336 * 01337 * @param pcWriteBuffer A buffer into which the execution times will be 01338 * written, in ascii form. This buffer is assumed to be large enough to 01339 * contain the generated report. Approximately 40 bytes per task should 01340 * be sufficient. 01341 * 01342 * \defgroup vTaskGetRunTimeStats vTaskGetRunTimeStats 01343 * \ingroup TaskUtils 01344 */ 01345 void vTaskGetRunTimeStats( signed char *pcWriteBuffer ) PRIVILEGED_FUNCTION; 01346 01347 /*----------------------------------------------------------- 01348 * SCHEDULER INTERNALS AVAILABLE FOR PORTING PURPOSES 01349 *----------------------------------------------------------*/ 01350 01351 /* 01352 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS ONLY 01353 * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS 01354 * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER. 01355 * 01356 * Called from the real time kernel tick (either preemptive or cooperative), 01357 * this increments the tick count and checks if any tasks that are blocked 01358 * for a finite period required removing from a blocked list and placing on 01359 * a ready list. If a non-zero value is returned then a context switch is 01360 * required because either: 01361 * + A task was removed from a blocked list because its timeout had expired, 01362 * or 01363 * + Time slicing is in use and there is a task of equal priority to the 01364 * currently running task. 01365 */ 01366 portBASE_TYPE xTaskIncrementTick( void ) PRIVILEGED_FUNCTION; 01367 01368 /* 01369 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN 01370 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER. 01371 * 01372 * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED. 01373 * 01374 * Removes the calling task from the ready list and places it both 01375 * on the list of tasks waiting for a particular event, and the 01376 * list of delayed tasks. The task will be removed from both lists 01377 * and replaced on the ready list should either the event occur (and 01378 * there be no higher priority tasks waiting on the same event) or 01379 * the delay period expires. 01380 * 01381 * @param pxEventList The list containing tasks that are blocked waiting 01382 * for the event to occur. 01383 * 01384 * @param xTicksToWait The maximum amount of time that the task should wait 01385 * for the event to occur. This is specified in kernel ticks,the constant 01386 * portTICK_RATE_MS can be used to convert kernel ticks into a real time 01387 * period. 01388 */ 01389 void vTaskPlaceOnEventList( xList * const pxEventList, portTickType xTicksToWait ) PRIVILEGED_FUNCTION; 01390 01391 /* 01392 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN 01393 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER. 01394 * 01395 * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED. 01396 * 01397 * This function performs nearly the same function as vTaskPlaceOnEventList(). 01398 * The difference being that this function does not permit tasks to block 01399 * indefinitely, whereas vTaskPlaceOnEventList() does. 01400 * 01401 * @return pdTRUE if the task being removed has a higher priority than the task 01402 * making the call, otherwise pdFALSE. 01403 */ 01404 void vTaskPlaceOnEventListRestricted( xList * const pxEventList, portTickType xTicksToWait ) PRIVILEGED_FUNCTION; 01405 01406 /* 01407 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN 01408 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER. 01409 * 01410 * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED. 01411 * 01412 * Removes a task from both the specified event list and the list of blocked 01413 * tasks, and places it on a ready queue. 01414 * 01415 * xTaskRemoveFromEventList () will be called if either an event occurs to 01416 * unblock a task, or the block timeout period expires. 01417 * 01418 * @return pdTRUE if the task being removed has a higher priority than the task 01419 * making the call, otherwise pdFALSE. 01420 */ 01421 signed portBASE_TYPE xTaskRemoveFromEventList( const xList * const pxEventList ) PRIVILEGED_FUNCTION; 01422 01423 /* 01424 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS ONLY 01425 * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS 01426 * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER. 01427 * 01428 * Sets the pointer to the current TCB to the TCB of the highest priority task 01429 * that is ready to run. 01430 */ 01431 void vTaskSwitchContext( void ) PRIVILEGED_FUNCTION; 01432 01433 /* 01434 * Return the handle of the calling task. 01435 */ 01436 xTaskHandle xTaskGetCurrentTaskHandle( void ) PRIVILEGED_FUNCTION; 01437 01438 /* 01439 * Capture the current time status for future reference. 01440 */ 01441 void vTaskSetTimeOutState( xTimeOutType * const pxTimeOut ) PRIVILEGED_FUNCTION; 01442 01443 /* 01444 * Compare the time status now with that previously captured to see if the 01445 * timeout has expired. 01446 */ 01447 portBASE_TYPE xTaskCheckForTimeOut( xTimeOutType * const pxTimeOut, portTickType * const pxTicksToWait ) PRIVILEGED_FUNCTION; 01448 01449 /* 01450 * Shortcut used by the queue implementation to prevent unnecessary call to 01451 * taskYIELD(); 01452 */ 01453 void vTaskMissedYield( void ) PRIVILEGED_FUNCTION; 01454 01455 /* 01456 * Returns the scheduler state as taskSCHEDULER_RUNNING, 01457 * taskSCHEDULER_NOT_STARTED or taskSCHEDULER_SUSPENDED. 01458 */ 01459 portBASE_TYPE xTaskGetSchedulerState( void ) PRIVILEGED_FUNCTION; 01460 01461 /* 01462 * Raises the priority of the mutex holder to that of the calling task should 01463 * the mutex holder have a priority less than the calling task. 01464 */ 01465 void vTaskPriorityInherit( xTaskHandle const pxMutexHolder ) PRIVILEGED_FUNCTION; 01466 01467 /* 01468 * Set the priority of a task back to its proper priority in the case that it 01469 * inherited a higher priority while it was holding a semaphore. 01470 */ 01471 void vTaskPriorityDisinherit( xTaskHandle const pxMutexHolder ) PRIVILEGED_FUNCTION; 01472 01473 /* 01474 * Generic version of the task creation function which is in turn called by the 01475 * xTaskCreate() and xTaskCreateRestricted() macros. 01476 */ 01477 signed portBASE_TYPE xTaskGenericCreate( pdTASK_CODE pxTaskCode, 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; 01478 01479 /* 01480 * Get the uxTCBNumber assigned to the task referenced by the xTask parameter. 01481 */ 01482 unsigned portBASE_TYPE uxTaskGetTaskNumber( xTaskHandle xTask ); 01483 01484 /* 01485 * Set the uxTCBNumber of the task referenced by the xTask parameter to 01486 * ucHandle. 01487 */ 01488 void vTaskSetTaskNumber( xTaskHandle xTask, unsigned portBASE_TYPE uxHandle ); 01489 01490 /* 01491 * If tickless mode is being used, or a low power mode is implemented, then 01492 * the tick interrupt will not execute during idle periods. When this is the 01493 * case, the tick count value maintained by the scheduler needs to be kept up 01494 * to date with the actual execution time by being skipped forward by the by 01495 * a time equal to the idle period. 01496 */ 01497 void vTaskStepTick( portTickType xTicksToJump ); 01498 01499 /* 01500 * Provided for use within portSUPPRESS_TICKS_AND_SLEEP() to allow the port 01501 * specific sleep function to determine if it is ok to proceed with the sleep, 01502 * and if it is ok to proceed, if it is ok to sleep indefinitely. 01503 * 01504 * This function is necessary because portSUPPRESS_TICKS_AND_SLEEP() is only 01505 * called with the scheduler suspended, not from within a critical section. It 01506 * is therefore possible for an interrupt to request a context switch between 01507 * portSUPPRESS_TICKS_AND_SLEEP() and the low power mode actually being 01508 * entered. eTaskConfirmSleepModeStatus() should be called from a short 01509 * critical section between the timer being stopped and the sleep mode being 01510 * entered to ensure it is ok to proceed into the sleep mode. 01511 */ 01512 eSleepModeStatus eTaskConfirmSleepModeStatus( void ); 01513 01514 #ifdef __cplusplus 01515 } 01516 #endif 01517 #endif /* INC_TASK_H */ 01518 01519 01520
Generated on Tue Jul 12 2022 11:36:40 by
1.7.2