David Fletcher
/
cc3100_Test_mqtt_CM4F
TI's MQTT Demo with freertos CM4F
Embed:
(wiki syntax)
Show/hide line numbers
task.h
00001 /* 00002 FreeRTOS V8.2.1 - Copyright (C) 2015 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 This file is part of the FreeRTOS distribution. 00008 00009 FreeRTOS is free software; you can redistribute it and/or modify it under 00010 the terms of the GNU General Public License (version 2) as published by the 00011 Free Software Foundation >>!AND MODIFIED BY!<< the FreeRTOS exception. 00012 00013 *************************************************************************** 00014 >>! NOTE: The modification to the GPL is included to allow you to !<< 00015 >>! distribute a combined work that includes FreeRTOS without being !<< 00016 >>! obliged to provide the source code for proprietary components !<< 00017 >>! outside of the FreeRTOS kernel. !<< 00018 *************************************************************************** 00019 00020 FreeRTOS is distributed in the hope that it will be useful, but WITHOUT ANY 00021 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 00022 FOR A PARTICULAR PURPOSE. Full license text is available on the following 00023 link: http://www.freertos.org/a00114.html 00024 00025 *************************************************************************** 00026 * * 00027 * FreeRTOS provides completely free yet professionally developed, * 00028 * robust, strictly quality controlled, supported, and cross * 00029 * platform software that is more than just the market leader, it * 00030 * is the industry's de facto standard. * 00031 * * 00032 * Help yourself get started quickly while simultaneously helping * 00033 * to support the FreeRTOS project by purchasing a FreeRTOS * 00034 * tutorial book, reference manual, or both: * 00035 * http://www.FreeRTOS.org/Documentation * 00036 * * 00037 *************************************************************************** 00038 00039 http://www.FreeRTOS.org/FAQHelp.html - Having a problem? Start by reading 00040 the FAQ page "My application does not run, what could be wrong?". Have you 00041 defined configASSERT()? 00042 00043 http://www.FreeRTOS.org/support - In return for receiving this top quality 00044 embedded software for free we request you assist our global community by 00045 participating in the support forum. 00046 00047 http://www.FreeRTOS.org/training - Investing in training allows your team to 00048 be as productive as possible as early as possible. Now you can receive 00049 FreeRTOS training directly from Richard Barry, CEO of Real Time Engineers 00050 Ltd, and the world's leading authority on the world's leading RTOS. 00051 00052 http://www.FreeRTOS.org/plus - A selection of FreeRTOS ecosystem products, 00053 including FreeRTOS+Trace - an indispensable productivity tool, a DOS 00054 compatible FAT file system, and our tiny thread aware UDP/IP stack. 00055 00056 http://www.FreeRTOS.org/labs - Where new FreeRTOS products go to incubate. 00057 Come and try FreeRTOS+TCP, our new open source TCP/IP stack for FreeRTOS. 00058 00059 http://www.OpenRTOS.com - Real Time Engineers ltd. license FreeRTOS to High 00060 Integrity Systems ltd. to sell under the OpenRTOS brand. Low cost OpenRTOS 00061 licenses offer ticketed support, indemnification and commercial middleware. 00062 00063 http://www.SafeRTOS.com - High Integrity Systems also provide a safety 00064 engineered and independently SIL3 certified version for use in safety and 00065 mission critical applications that require provable dependability. 00066 00067 1 tab == 4 spaces! 00068 */ 00069 00070 00071 #ifndef INC_TASK_H 00072 #define INC_TASK_H 00073 00074 #ifndef INC_FREERTOS_H 00075 #error "include FreeRTOS.h must appear in source files before include task.h" 00076 #endif 00077 00078 #include "list.h" 00079 00080 #ifdef __cplusplus 00081 extern "C" { 00082 #endif 00083 00084 /*----------------------------------------------------------- 00085 * MACROS AND DEFINITIONS 00086 *----------------------------------------------------------*/ 00087 00088 #define tskKERNEL_VERSION_NUMBER "V8.2.1" 00089 #define tskKERNEL_VERSION_MAJOR 8 00090 #define tskKERNEL_VERSION_MINOR 2 00091 #define tskKERNEL_VERSION_BUILD 1 00092 00093 /** 00094 * task. h 00095 * 00096 * Type by which tasks are referenced. For example, a call to xTaskCreate 00097 * returns (via a pointer parameter) an TaskHandle_t variable that can then 00098 * be used as a parameter to vTaskDelete to delete the task. 00099 * 00100 * \defgroup TaskHandle_t TaskHandle_t 00101 * \ingroup Tasks 00102 */ 00103 typedef void * TaskHandle_t; 00104 00105 /* 00106 * Defines the prototype to which the application task hook function must 00107 * conform. 00108 */ 00109 typedef BaseType_t (*TaskHookFunction_t)( void * ); 00110 00111 /* Task states returned by eTaskGetState. */ 00112 typedef enum 00113 { 00114 eRunning = 0, /* A task is querying the state of itself, so must be running. */ 00115 eReady, /* The task being queried is in a read or pending ready list. */ 00116 eBlocked, /* The task being queried is in the Blocked state. */ 00117 eSuspended, /* The task being queried is in the Suspended state, or is in the Blocked state with an infinite time out. */ 00118 eDeleted /* The task being queried has been deleted, but its TCB has not yet been freed. */ 00119 } eTaskState; 00120 00121 /* Actions that can be performed when vTaskNotify() is called. */ 00122 typedef enum 00123 { 00124 eNoAction = 0, /* Notify the task without updating its notify value. */ 00125 eSetBits, /* Set bits in the task's notification value. */ 00126 eIncrement, /* Increment the task's notification value. */ 00127 eSetValueWithOverwrite, /* Set the task's notification value to a specific value even if the previous value has not yet been read by the task. */ 00128 eSetValueWithoutOverwrite /* Set the task's notification value if the previous value has been read by the task. */ 00129 } eNotifyAction; 00130 00131 /* 00132 * Used internally only. 00133 */ 00134 typedef struct xTIME_OUT 00135 { 00136 BaseType_t xOverflowCount; 00137 TickType_t xTimeOnEntering; 00138 } TimeOut_t; 00139 00140 /* 00141 * Defines the memory ranges allocated to the task when an MPU is used. 00142 */ 00143 typedef struct xMEMORY_REGION 00144 { 00145 void *pvBaseAddress; 00146 uint32_t ulLengthInBytes; 00147 uint32_t ulParameters; 00148 } MemoryRegion_t; 00149 00150 /* 00151 * Parameters required to create an MPU protected task. 00152 */ 00153 typedef struct xTASK_PARAMETERS 00154 { 00155 TaskFunction_t pvTaskCode; 00156 const char * const pcName; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ 00157 uint16_t usStackDepth; 00158 void *pvParameters; 00159 UBaseType_t uxPriority; 00160 StackType_t *puxStackBuffer; 00161 MemoryRegion_t xRegions[ portNUM_CONFIGURABLE_REGIONS ]; 00162 } TaskParameters_t; 00163 00164 /* Used with the uxTaskGetSystemState() function to return the state of each task 00165 in the system. */ 00166 typedef struct xTASK_STATUS 00167 { 00168 TaskHandle_t xHandle; /* The handle of the task to which the rest of the information in the structure relates. */ 00169 const char *pcTaskName; /* A pointer to the task's name. This value will be invalid if the task was deleted since the structure was populated! */ /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ 00170 UBaseType_t xTaskNumber; /* A number unique to the task. */ 00171 eTaskState eCurrentState; /* The state in which the task existed when the structure was populated. */ 00172 UBaseType_t uxCurrentPriority; /* The priority at which the task was running (may be inherited) when the structure was populated. */ 00173 UBaseType_t uxBasePriority; /* The priority to which the task will return if the task's current priority has been inherited to avoid unbounded priority inversion when obtaining a mutex. Only valid if configUSE_MUTEXES is defined as 1 in FreeRTOSConfig.h. */ 00174 uint32_t 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. */ 00175 uint16_t 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. */ 00176 } TaskStatus_t; 00177 00178 /* Possible return values for eTaskConfirmSleepModeStatus(). */ 00179 typedef enum 00180 { 00181 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. */ 00182 eStandardSleep, /* Enter a sleep mode that will not last any longer than the expected idle time. */ 00183 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. */ 00184 } eSleepModeStatus; 00185 00186 00187 /** 00188 * Defines the priority used by the idle task. This must not be modified. 00189 * 00190 * \ingroup TaskUtils 00191 */ 00192 #define tskIDLE_PRIORITY ( ( UBaseType_t ) 0U ) 00193 00194 /** 00195 * task. h 00196 * 00197 * Macro for forcing a context switch. 00198 * 00199 * \defgroup taskYIELD taskYIELD 00200 * \ingroup SchedulerControl 00201 */ 00202 #define taskYIELD() portYIELD() 00203 00204 /** 00205 * task. h 00206 * 00207 * Macro to mark the start of a critical code region. Preemptive context 00208 * switches cannot occur when in a critical region. 00209 * 00210 * NOTE: This may alter the stack (depending on the portable implementation) 00211 * so must be used with care! 00212 * 00213 * \defgroup taskENTER_CRITICAL taskENTER_CRITICAL 00214 * \ingroup SchedulerControl 00215 */ 00216 #define taskENTER_CRITICAL() portENTER_CRITICAL() 00217 #define taskENTER_CRITICAL_FROM_ISR( x ) portSET_INTERRUPT_MASK_FROM_ISR( x ) 00218 00219 /** 00220 * task. h 00221 * 00222 * Macro to mark the end of a critical code region. Preemptive context 00223 * switches cannot occur when in a critical region. 00224 * 00225 * NOTE: This may alter the stack (depending on the portable implementation) 00226 * so must be used with care! 00227 * 00228 * \defgroup taskEXIT_CRITICAL taskEXIT_CRITICAL 00229 * \ingroup SchedulerControl 00230 */ 00231 #define taskEXIT_CRITICAL() portEXIT_CRITICAL() 00232 #define taskEXIT_CRITICAL_FROM_ISR() portCLEAR_INTERRUPT_MASK_FROM_ISR() 00233 /** 00234 * task. h 00235 * 00236 * Macro to disable all maskable interrupts. 00237 * 00238 * \defgroup taskDISABLE_INTERRUPTS taskDISABLE_INTERRUPTS 00239 * \ingroup SchedulerControl 00240 */ 00241 #define taskDISABLE_INTERRUPTS() portDISABLE_INTERRUPTS() 00242 00243 /** 00244 * task. h 00245 * 00246 * Macro to enable microcontroller interrupts. 00247 * 00248 * \defgroup taskENABLE_INTERRUPTS taskENABLE_INTERRUPTS 00249 * \ingroup SchedulerControl 00250 */ 00251 #define taskENABLE_INTERRUPTS() portENABLE_INTERRUPTS() 00252 00253 /* Definitions returned by xTaskGetSchedulerState(). taskSCHEDULER_SUSPENDED is 00254 0 to generate more optimal code when configASSERT() is defined as the constant 00255 is used in assert() statements. */ 00256 #define taskSCHEDULER_SUSPENDED ( ( BaseType_t ) 0 ) 00257 #define taskSCHEDULER_NOT_STARTED ( ( BaseType_t ) 1 ) 00258 #define taskSCHEDULER_RUNNING ( ( BaseType_t ) 2 ) 00259 00260 00261 /*----------------------------------------------------------- 00262 * TASK CREATION API 00263 *----------------------------------------------------------*/ 00264 00265 /** 00266 * task. h 00267 *<pre> 00268 BaseType_t xTaskCreate( 00269 TaskFunction_t pvTaskCode, 00270 const char * const pcName, 00271 uint16_t usStackDepth, 00272 void *pvParameters, 00273 UBaseType_t uxPriority, 00274 TaskHandle_t *pvCreatedTask 00275 );</pre> 00276 * 00277 * Create a new task and add it to the list of tasks that are ready to run. 00278 * 00279 * xTaskCreate() can only be used to create a task that has unrestricted 00280 * access to the entire microcontroller memory map. Systems that include MPU 00281 * support can alternatively create an MPU constrained task using 00282 * xTaskCreateRestricted(). 00283 * 00284 * @param pvTaskCode Pointer to the task entry function. Tasks 00285 * must be implemented to never return (i.e. continuous loop). 00286 * 00287 * @param pcName A descriptive name for the task. This is mainly used to 00288 * facilitate debugging. Max length defined by configMAX_TASK_NAME_LEN - default 00289 * is 16. 00290 * 00291 * @param usStackDepth The size of the task stack specified as the number of 00292 * variables the stack can hold - not the number of bytes. For example, if 00293 * the stack is 16 bits wide and usStackDepth is defined as 100, 200 bytes 00294 * will be allocated for stack storage. 00295 * 00296 * @param pvParameters Pointer that will be used as the parameter for the task 00297 * being created. 00298 * 00299 * @param uxPriority The priority at which the task should run. Systems that 00300 * include MPU support can optionally create tasks in a privileged (system) 00301 * mode by setting bit portPRIVILEGE_BIT of the priority parameter. For 00302 * example, to create a privileged task at priority 2 the uxPriority parameter 00303 * should be set to ( 2 | portPRIVILEGE_BIT ). 00304 * 00305 * @param pvCreatedTask Used to pass back a handle by which the created task 00306 * can be referenced. 00307 * 00308 * @return pdPASS if the task was successfully created and added to a ready 00309 * list, otherwise an error code defined in the file projdefs.h 00310 * 00311 * Example usage: 00312 <pre> 00313 // Task to be created. 00314 void vTaskCode( void * pvParameters ) 00315 { 00316 for( ;; ) 00317 { 00318 // Task code goes here. 00319 } 00320 } 00321 00322 // Function that creates a task. 00323 void vOtherFunction( void ) 00324 { 00325 static uint8_t ucParameterToPass; 00326 TaskHandle_t xHandle = NULL; 00327 00328 // Create the task, storing the handle. Note that the passed parameter ucParameterToPass 00329 // must exist for the lifetime of the task, so in this case is declared static. If it was just an 00330 // an automatic stack variable it might no longer exist, or at least have been corrupted, by the time 00331 // the new task attempts to access it. 00332 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, &ucParameterToPass, tskIDLE_PRIORITY, &xHandle ); 00333 configASSERT( xHandle ); 00334 00335 // Use the handle to delete the task. 00336 if( xHandle != NULL ) 00337 { 00338 vTaskDelete( xHandle ); 00339 } 00340 } 00341 </pre> 00342 * \defgroup xTaskCreate xTaskCreate 00343 * \ingroup Tasks 00344 */ 00345 #define xTaskCreate( pvTaskCode, pcName, usStackDepth, pvParameters, uxPriority, pxCreatedTask ) xTaskGenericCreate( ( pvTaskCode ), ( pcName ), ( usStackDepth ), ( pvParameters ), ( uxPriority ), ( pxCreatedTask ), ( NULL ), ( NULL ) ) 00346 00347 /** 00348 * task. h 00349 *<pre> 00350 BaseType_t xTaskCreateRestricted( TaskParameters_t *pxTaskDefinition, TaskHandle_t *pxCreatedTask );</pre> 00351 * 00352 * xTaskCreateRestricted() should only be used in systems that include an MPU 00353 * implementation. 00354 * 00355 * Create a new task and add it to the list of tasks that are ready to run. 00356 * The function parameters define the memory regions and associated access 00357 * permissions allocated to the task. 00358 * 00359 * @param pxTaskDefinition Pointer to a structure that contains a member 00360 * for each of the normal xTaskCreate() parameters (see the xTaskCreate() API 00361 * documentation) plus an optional stack buffer and the memory region 00362 * definitions. 00363 * 00364 * @param pxCreatedTask Used to pass back a handle by which the created task 00365 * can be referenced. 00366 * 00367 * @return pdPASS if the task was successfully created and added to a ready 00368 * list, otherwise an error code defined in the file projdefs.h 00369 * 00370 * Example usage: 00371 <pre> 00372 // Create an TaskParameters_t structure that defines the task to be created. 00373 static const TaskParameters_t xCheckTaskParameters = 00374 { 00375 vATask, // pvTaskCode - the function that implements the task. 00376 "ATask", // pcName - just a text name for the task to assist debugging. 00377 100, // usStackDepth - the stack size DEFINED IN WORDS. 00378 NULL, // pvParameters - passed into the task function as the function parameters. 00379 ( 1UL | portPRIVILEGE_BIT ),// uxPriority - task priority, set the portPRIVILEGE_BIT if the task should run in a privileged state. 00380 cStackBuffer,// puxStackBuffer - the buffer to be used as the task stack. 00381 00382 // xRegions - Allocate up to three separate memory regions for access by 00383 // the task, with appropriate access permissions. Different processors have 00384 // different memory alignment requirements - refer to the FreeRTOS documentation 00385 // for full information. 00386 { 00387 // Base address Length Parameters 00388 { cReadWriteArray, 32, portMPU_REGION_READ_WRITE }, 00389 { cReadOnlyArray, 32, portMPU_REGION_READ_ONLY }, 00390 { cPrivilegedOnlyAccessArray, 128, portMPU_REGION_PRIVILEGED_READ_WRITE } 00391 } 00392 }; 00393 00394 int main( void ) 00395 { 00396 TaskHandle_t xHandle; 00397 00398 // Create a task from the const structure defined above. The task handle 00399 // is requested (the second parameter is not NULL) but in this case just for 00400 // demonstration purposes as its not actually used. 00401 xTaskCreateRestricted( &xRegTest1Parameters, &xHandle ); 00402 00403 // Start the scheduler. 00404 vTaskStartScheduler(); 00405 00406 // Will only get here if there was insufficient memory to create the idle 00407 // and/or timer task. 00408 for( ;; ); 00409 } 00410 </pre> 00411 * \defgroup xTaskCreateRestricted xTaskCreateRestricted 00412 * \ingroup Tasks 00413 */ 00414 #define xTaskCreateRestricted( x, pxCreatedTask ) xTaskGenericCreate( ((x)->pvTaskCode), ((x)->pcName), ((x)->usStackDepth), ((x)->pvParameters), ((x)->uxPriority), (pxCreatedTask), ((x)->puxStackBuffer), ((x)->xRegions) ) 00415 00416 /** 00417 * task. h 00418 *<pre> 00419 void vTaskAllocateMPURegions( TaskHandle_t xTask, const MemoryRegion_t * const pxRegions );</pre> 00420 * 00421 * Memory regions are assigned to a restricted task when the task is created by 00422 * a call to xTaskCreateRestricted(). These regions can be redefined using 00423 * vTaskAllocateMPURegions(). 00424 * 00425 * @param xTask The handle of the task being updated. 00426 * 00427 * @param xRegions A pointer to an MemoryRegion_t structure that contains the 00428 * new memory region definitions. 00429 * 00430 * Example usage: 00431 <pre> 00432 // Define an array of MemoryRegion_t structures that configures an MPU region 00433 // allowing read/write access for 1024 bytes starting at the beginning of the 00434 // ucOneKByte array. The other two of the maximum 3 definable regions are 00435 // unused so set to zero. 00436 static const MemoryRegion_t xAltRegions[ portNUM_CONFIGURABLE_REGIONS ] = 00437 { 00438 // Base address Length Parameters 00439 { ucOneKByte, 1024, portMPU_REGION_READ_WRITE }, 00440 { 0, 0, 0 }, 00441 { 0, 0, 0 } 00442 }; 00443 00444 void vATask( void *pvParameters ) 00445 { 00446 // This task was created such that it has access to certain regions of 00447 // memory as defined by the MPU configuration. At some point it is 00448 // desired that these MPU regions are replaced with that defined in the 00449 // xAltRegions const struct above. Use a call to vTaskAllocateMPURegions() 00450 // for this purpose. NULL is used as the task handle to indicate that this 00451 // function should modify the MPU regions of the calling task. 00452 vTaskAllocateMPURegions( NULL, xAltRegions ); 00453 00454 // Now the task can continue its function, but from this point on can only 00455 // access its stack and the ucOneKByte array (unless any other statically 00456 // defined or shared regions have been declared elsewhere). 00457 } 00458 </pre> 00459 * \defgroup xTaskCreateRestricted xTaskCreateRestricted 00460 * \ingroup Tasks 00461 */ 00462 void vTaskAllocateMPURegions( TaskHandle_t xTask, const MemoryRegion_t * const pxRegions ) PRIVILEGED_FUNCTION; 00463 00464 /** 00465 * task. h 00466 * <pre>void vTaskDelete( TaskHandle_t xTask );</pre> 00467 * 00468 * INCLUDE_vTaskDelete must be defined as 1 for this function to be available. 00469 * See the configuration section for more information. 00470 * 00471 * Remove a task from the RTOS real time kernel's management. The task being 00472 * deleted will be removed from all ready, blocked, suspended and event lists. 00473 * 00474 * NOTE: The idle task is responsible for freeing the kernel allocated 00475 * memory from tasks that have been deleted. It is therefore important that 00476 * the idle task is not starved of microcontroller processing time if your 00477 * application makes any calls to vTaskDelete (). Memory allocated by the 00478 * task code is not automatically freed, and should be freed before the task 00479 * is deleted. 00480 * 00481 * See the demo application file death.c for sample code that utilises 00482 * vTaskDelete (). 00483 * 00484 * @param xTask The handle of the task to be deleted. Passing NULL will 00485 * cause the calling task to be deleted. 00486 * 00487 * Example usage: 00488 <pre> 00489 void vOtherFunction( void ) 00490 { 00491 TaskHandle_t xHandle; 00492 00493 // Create the task, storing the handle. 00494 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle ); 00495 00496 // Use the handle to delete the task. 00497 vTaskDelete( xHandle ); 00498 } 00499 </pre> 00500 * \defgroup vTaskDelete vTaskDelete 00501 * \ingroup Tasks 00502 */ 00503 void vTaskDelete( TaskHandle_t xTaskToDelete ) PRIVILEGED_FUNCTION; 00504 00505 /*----------------------------------------------------------- 00506 * TASK CONTROL API 00507 *----------------------------------------------------------*/ 00508 00509 /** 00510 * task. h 00511 * <pre>void vTaskDelay( const TickType_t xTicksToDelay );</pre> 00512 * 00513 * Delay a task for a given number of ticks. The actual time that the 00514 * task remains blocked depends on the tick rate. The constant 00515 * portTICK_PERIOD_MS can be used to calculate real time from the tick 00516 * rate - with the resolution of one tick period. 00517 * 00518 * INCLUDE_vTaskDelay must be defined as 1 for this function to be available. 00519 * See the configuration section for more information. 00520 * 00521 * 00522 * vTaskDelay() specifies a time at which the task wishes to unblock relative to 00523 * the time at which vTaskDelay() is called. For example, specifying a block 00524 * period of 100 ticks will cause the task to unblock 100 ticks after 00525 * vTaskDelay() is called. vTaskDelay() does not therefore provide a good method 00526 * of controlling the frequency of a periodic task as the path taken through the 00527 * code, as well as other task and interrupt activity, will effect the frequency 00528 * at which vTaskDelay() gets called and therefore the time at which the task 00529 * next executes. See vTaskDelayUntil() for an alternative API function designed 00530 * to facilitate fixed frequency execution. It does this by specifying an 00531 * absolute time (rather than a relative time) at which the calling task should 00532 * unblock. 00533 * 00534 * @param xTicksToDelay The amount of time, in tick periods, that 00535 * the calling task should block. 00536 * 00537 * Example usage: 00538 00539 void vTaskFunction( void * pvParameters ) 00540 { 00541 // Block for 500ms. 00542 const TickType_t xDelay = 500 / portTICK_PERIOD_MS; 00543 00544 for( ;; ) 00545 { 00546 // Simply toggle the LED every 500ms, blocking between each toggle. 00547 vToggleLED(); 00548 vTaskDelay( xDelay ); 00549 } 00550 } 00551 00552 * \defgroup vTaskDelay vTaskDelay 00553 * \ingroup TaskCtrl 00554 */ 00555 void vTaskDelay( const TickType_t xTicksToDelay ) PRIVILEGED_FUNCTION; 00556 00557 /** 00558 * task. h 00559 * <pre>void vTaskDelayUntil( TickType_t *pxPreviousWakeTime, const TickType_t xTimeIncrement );</pre> 00560 * 00561 * INCLUDE_vTaskDelayUntil must be defined as 1 for this function to be available. 00562 * See the configuration section for more information. 00563 * 00564 * Delay a task until a specified time. This function can be used by periodic 00565 * tasks to ensure a constant execution frequency. 00566 * 00567 * This function differs from vTaskDelay () in one important aspect: vTaskDelay () will 00568 * cause a task to block for the specified number of ticks from the time vTaskDelay () is 00569 * called. It is therefore difficult to use vTaskDelay () by itself to generate a fixed 00570 * execution frequency as the time between a task starting to execute and that task 00571 * calling vTaskDelay () may not be fixed [the task may take a different path though the 00572 * code between calls, or may get interrupted or preempted a different number of times 00573 * each time it executes]. 00574 * 00575 * Whereas vTaskDelay () specifies a wake time relative to the time at which the function 00576 * is called, vTaskDelayUntil () specifies the absolute (exact) time at which it wishes to 00577 * unblock. 00578 * 00579 * The constant portTICK_PERIOD_MS can be used to calculate real time from the tick 00580 * rate - with the resolution of one tick period. 00581 * 00582 * @param pxPreviousWakeTime Pointer to a variable that holds the time at which the 00583 * task was last unblocked. The variable must be initialised with the current time 00584 * prior to its first use (see the example below). Following this the variable is 00585 * automatically updated within vTaskDelayUntil (). 00586 * 00587 * @param xTimeIncrement The cycle time period. The task will be unblocked at 00588 * time *pxPreviousWakeTime + xTimeIncrement. Calling vTaskDelayUntil with the 00589 * same xTimeIncrement parameter value will cause the task to execute with 00590 * a fixed interface period. 00591 * 00592 * Example usage: 00593 <pre> 00594 // Perform an action every 10 ticks. 00595 void vTaskFunction( void * pvParameters ) 00596 { 00597 TickType_t xLastWakeTime; 00598 const TickType_t xFrequency = 10; 00599 00600 // Initialise the xLastWakeTime variable with the current time. 00601 xLastWakeTime = xTaskGetTickCount (); 00602 for( ;; ) 00603 { 00604 // Wait for the next cycle. 00605 vTaskDelayUntil( &xLastWakeTime, xFrequency ); 00606 00607 // Perform action here. 00608 } 00609 } 00610 </pre> 00611 * \defgroup vTaskDelayUntil vTaskDelayUntil 00612 * \ingroup TaskCtrl 00613 */ 00614 void vTaskDelayUntil( TickType_t * const pxPreviousWakeTime, const TickType_t xTimeIncrement ) PRIVILEGED_FUNCTION; 00615 00616 /** 00617 * task. h 00618 * <pre>UBaseType_t uxTaskPriorityGet( TaskHandle_t xTask );</pre> 00619 * 00620 * INCLUDE_uxTaskPriorityGet must be defined as 1 for this function to be available. 00621 * See the configuration section for more information. 00622 * 00623 * Obtain the priority of any task. 00624 * 00625 * @param xTask Handle of the task to be queried. Passing a NULL 00626 * handle results in the priority of the calling task being returned. 00627 * 00628 * @return The priority of xTask. 00629 * 00630 * Example usage: 00631 <pre> 00632 void vAFunction( void ) 00633 { 00634 TaskHandle_t xHandle; 00635 00636 // Create a task, storing the handle. 00637 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle ); 00638 00639 // ... 00640 00641 // Use the handle to obtain the priority of the created task. 00642 // It was created with tskIDLE_PRIORITY, but may have changed 00643 // it itself. 00644 if( uxTaskPriorityGet( xHandle ) != tskIDLE_PRIORITY ) 00645 { 00646 // The task has changed it's priority. 00647 } 00648 00649 // ... 00650 00651 // Is our priority higher than the created task? 00652 if( uxTaskPriorityGet( xHandle ) < uxTaskPriorityGet( NULL ) ) 00653 { 00654 // Our priority (obtained using NULL handle) is higher. 00655 } 00656 } 00657 </pre> 00658 * \defgroup uxTaskPriorityGet uxTaskPriorityGet 00659 * \ingroup TaskCtrl 00660 */ 00661 UBaseType_t uxTaskPriorityGet( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; 00662 00663 /** 00664 * task. h 00665 * <pre>UBaseType_t uxTaskPriorityGetFromISR( TaskHandle_t xTask );</pre> 00666 * 00667 * A version of uxTaskPriorityGet() that can be used from an ISR. 00668 */ 00669 UBaseType_t uxTaskPriorityGetFromISR( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; 00670 00671 /** 00672 * task. h 00673 * <pre>eTaskState eTaskGetState( TaskHandle_t xTask );</pre> 00674 * 00675 * INCLUDE_eTaskGetState must be defined as 1 for this function to be available. 00676 * See the configuration section for more information. 00677 * 00678 * Obtain the state of any task. States are encoded by the eTaskState 00679 * enumerated type. 00680 * 00681 * @param xTask Handle of the task to be queried. 00682 * 00683 * @return The state of xTask at the time the function was called. Note the 00684 * state of the task might change between the function being called, and the 00685 * functions return value being tested by the calling task. 00686 */ 00687 eTaskState eTaskGetState( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; 00688 00689 /** 00690 * task. h 00691 * <pre>void vTaskPrioritySet( TaskHandle_t xTask, UBaseType_t uxNewPriority );</pre> 00692 * 00693 * INCLUDE_vTaskPrioritySet must be defined as 1 for this function to be available. 00694 * See the configuration section for more information. 00695 * 00696 * Set the priority of any task. 00697 * 00698 * A context switch will occur before the function returns if the priority 00699 * being set is higher than the currently executing task. 00700 * 00701 * @param xTask Handle to the task for which the priority is being set. 00702 * Passing a NULL handle results in the priority of the calling task being set. 00703 * 00704 * @param uxNewPriority The priority to which the task will be set. 00705 * 00706 * Example usage: 00707 <pre> 00708 void vAFunction( void ) 00709 { 00710 TaskHandle_t xHandle; 00711 00712 // Create a task, storing the handle. 00713 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle ); 00714 00715 // ... 00716 00717 // Use the handle to raise the priority of the created task. 00718 vTaskPrioritySet( xHandle, tskIDLE_PRIORITY + 1 ); 00719 00720 // ... 00721 00722 // Use a NULL handle to raise our priority to the same value. 00723 vTaskPrioritySet( NULL, tskIDLE_PRIORITY + 1 ); 00724 } 00725 </pre> 00726 * \defgroup vTaskPrioritySet vTaskPrioritySet 00727 * \ingroup TaskCtrl 00728 */ 00729 void vTaskPrioritySet( TaskHandle_t xTask, UBaseType_t uxNewPriority ) PRIVILEGED_FUNCTION; 00730 00731 /** 00732 * task. h 00733 * <pre>void vTaskSuspend( TaskHandle_t xTaskToSuspend );</pre> 00734 * 00735 * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available. 00736 * See the configuration section for more information. 00737 * 00738 * Suspend any task. When suspended a task will never get any microcontroller 00739 * processing time, no matter what its priority. 00740 * 00741 * Calls to vTaskSuspend are not accumulative - 00742 * i.e. calling vTaskSuspend () twice on the same task still only requires one 00743 * call to vTaskResume () to ready the suspended task. 00744 * 00745 * @param xTaskToSuspend Handle to the task being suspended. Passing a NULL 00746 * handle will cause the calling task to be suspended. 00747 * 00748 * Example usage: 00749 <pre> 00750 void vAFunction( void ) 00751 { 00752 TaskHandle_t xHandle; 00753 00754 // Create a task, storing the handle. 00755 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle ); 00756 00757 // ... 00758 00759 // Use the handle to suspend the created task. 00760 vTaskSuspend( xHandle ); 00761 00762 // ... 00763 00764 // The created task will not run during this period, unless 00765 // another task calls vTaskResume( xHandle ). 00766 00767 //... 00768 00769 00770 // Suspend ourselves. 00771 vTaskSuspend( NULL ); 00772 00773 // We cannot get here unless another task calls vTaskResume 00774 // with our handle as the parameter. 00775 } 00776 </pre> 00777 * \defgroup vTaskSuspend vTaskSuspend 00778 * \ingroup TaskCtrl 00779 */ 00780 void vTaskSuspend( TaskHandle_t xTaskToSuspend ) PRIVILEGED_FUNCTION; 00781 00782 /** 00783 * task. h 00784 * <pre>void vTaskResume( TaskHandle_t xTaskToResume );</pre> 00785 * 00786 * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available. 00787 * See the configuration section for more information. 00788 * 00789 * Resumes a suspended task. 00790 * 00791 * A task that has been suspended by one or more calls to vTaskSuspend () 00792 * will be made available for running again by a single call to 00793 * vTaskResume (). 00794 * 00795 * @param xTaskToResume Handle to the task being readied. 00796 * 00797 * Example usage: 00798 <pre> 00799 void vAFunction( void ) 00800 { 00801 TaskHandle_t xHandle; 00802 00803 // Create a task, storing the handle. 00804 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle ); 00805 00806 // ... 00807 00808 // Use the handle to suspend the created task. 00809 vTaskSuspend( xHandle ); 00810 00811 // ... 00812 00813 // The created task will not run during this period, unless 00814 // another task calls vTaskResume( xHandle ). 00815 00816 //... 00817 00818 00819 // Resume the suspended task ourselves. 00820 vTaskResume( xHandle ); 00821 00822 // The created task will once again get microcontroller processing 00823 // time in accordance with its priority within the system. 00824 } 00825 </pre> 00826 * \defgroup vTaskResume vTaskResume 00827 * \ingroup TaskCtrl 00828 */ 00829 void vTaskResume( TaskHandle_t xTaskToResume ) PRIVILEGED_FUNCTION; 00830 00831 /** 00832 * task. h 00833 * <pre>void xTaskResumeFromISR( TaskHandle_t xTaskToResume );</pre> 00834 * 00835 * INCLUDE_xTaskResumeFromISR must be defined as 1 for this function to be 00836 * available. See the configuration section for more information. 00837 * 00838 * An implementation of vTaskResume() that can be called from within an ISR. 00839 * 00840 * A task that has been suspended by one or more calls to vTaskSuspend () 00841 * will be made available for running again by a single call to 00842 * xTaskResumeFromISR (). 00843 * 00844 * xTaskResumeFromISR() should not be used to synchronise a task with an 00845 * interrupt if there is a chance that the interrupt could arrive prior to the 00846 * task being suspended - as this can lead to interrupts being missed. Use of a 00847 * semaphore as a synchronisation mechanism would avoid this eventuality. 00848 * 00849 * @param xTaskToResume Handle to the task being readied. 00850 * 00851 * @return pdTRUE if resuming the task should result in a context switch, 00852 * otherwise pdFALSE. This is used by the ISR to determine if a context switch 00853 * may be required following the ISR. 00854 * 00855 * \defgroup vTaskResumeFromISR vTaskResumeFromISR 00856 * \ingroup TaskCtrl 00857 */ 00858 BaseType_t xTaskResumeFromISR( TaskHandle_t xTaskToResume ) PRIVILEGED_FUNCTION; 00859 00860 /*----------------------------------------------------------- 00861 * SCHEDULER CONTROL 00862 *----------------------------------------------------------*/ 00863 00864 /** 00865 * task. h 00866 * <pre>void vTaskStartScheduler( void );</pre> 00867 * 00868 * Starts the real time kernel tick processing. After calling the kernel 00869 * has control over which tasks are executed and when. 00870 * 00871 * See the demo application file main.c for an example of creating 00872 * tasks and starting the kernel. 00873 * 00874 * Example usage: 00875 <pre> 00876 void vAFunction( void ) 00877 { 00878 // Create at least one task before starting the kernel. 00879 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL ); 00880 00881 // Start the real time kernel with preemption. 00882 vTaskStartScheduler (); 00883 00884 // Will not get here unless a task calls vTaskEndScheduler () 00885 } 00886 </pre> 00887 * 00888 * \defgroup vTaskStartScheduler vTaskStartScheduler 00889 * \ingroup SchedulerControl 00890 */ 00891 void vTaskStartScheduler( void ) PRIVILEGED_FUNCTION; 00892 00893 /** 00894 * task. h 00895 * <pre>void vTaskEndScheduler( void );</pre> 00896 * 00897 * NOTE: At the time of writing only the x86 real mode port, which runs on a PC 00898 * in place of DOS, implements this function. 00899 * 00900 * Stops the real time kernel tick. All created tasks will be automatically 00901 * deleted and multitasking (either preemptive or cooperative) will 00902 * stop. Execution then resumes from the point where vTaskStartScheduler () 00903 * was called, as if vTaskStartScheduler () had just returned. 00904 * 00905 * See the demo application file main. c in the demo/PC directory for an 00906 * example that uses vTaskEndScheduler (). 00907 * 00908 * vTaskEndScheduler () requires an exit function to be defined within the 00909 * portable layer (see vPortEndScheduler () in port. c for the PC port). This 00910 * performs hardware specific operations such as stopping the kernel tick. 00911 * 00912 * vTaskEndScheduler () will cause all of the resources allocated by the 00913 * kernel to be freed - but will not free resources allocated by application 00914 * tasks. 00915 * 00916 * Example usage: 00917 <pre> 00918 void vTaskCode( void * pvParameters ) 00919 { 00920 for( ;; ) 00921 { 00922 // Task code goes here. 00923 00924 // At some point we want to end the real time kernel processing 00925 // so call ... 00926 vTaskEndScheduler (); 00927 } 00928 } 00929 00930 void vAFunction( void ) 00931 { 00932 // Create at least one task before starting the kernel. 00933 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL ); 00934 00935 // Start the real time kernel with preemption. 00936 vTaskStartScheduler (); 00937 00938 // Will only get here when the vTaskCode () task has called 00939 // vTaskEndScheduler (). When we get here we are back to single task 00940 // execution. 00941 } 00942 </pre> 00943 * 00944 * \defgroup vTaskEndScheduler vTaskEndScheduler 00945 * \ingroup SchedulerControl 00946 */ 00947 void vTaskEndScheduler( void ) PRIVILEGED_FUNCTION; 00948 00949 /** 00950 * task. h 00951 * <pre>void vTaskSuspendAll( void );</pre> 00952 * 00953 * Suspends the scheduler without disabling interrupts. Context switches will 00954 * not occur while the scheduler is suspended. 00955 * 00956 * After calling vTaskSuspendAll () the calling task will continue to execute 00957 * without risk of being swapped out until a call to xTaskResumeAll () has been 00958 * made. 00959 * 00960 * API functions that have the potential to cause a context switch (for example, 00961 * vTaskDelayUntil(), xQueueSend(), etc.) must not be called while the scheduler 00962 * is suspended. 00963 * 00964 * Example usage: 00965 <pre> 00966 void vTask1( void * pvParameters ) 00967 { 00968 for( ;; ) 00969 { 00970 // Task code goes here. 00971 00972 // ... 00973 00974 // At some point the task wants to perform a long operation during 00975 // which it does not want to get swapped out. It cannot use 00976 // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the 00977 // operation may cause interrupts to be missed - including the 00978 // ticks. 00979 00980 // Prevent the real time kernel swapping out the task. 00981 vTaskSuspendAll (); 00982 00983 // Perform the operation here. There is no need to use critical 00984 // sections as we have all the microcontroller processing time. 00985 // During this time interrupts will still operate and the kernel 00986 // tick count will be maintained. 00987 00988 // ... 00989 00990 // The operation is complete. Restart the kernel. 00991 xTaskResumeAll (); 00992 } 00993 } 00994 </pre> 00995 * \defgroup vTaskSuspendAll vTaskSuspendAll 00996 * \ingroup SchedulerControl 00997 */ 00998 void vTaskSuspendAll( void ) PRIVILEGED_FUNCTION; 00999 01000 /** 01001 * task. h 01002 * <pre>BaseType_t xTaskResumeAll( void );</pre> 01003 * 01004 * Resumes scheduler activity after it was suspended by a call to 01005 * vTaskSuspendAll(). 01006 * 01007 * xTaskResumeAll() only resumes the scheduler. It does not unsuspend tasks 01008 * that were previously suspended by a call to vTaskSuspend(). 01009 * 01010 * @return If resuming the scheduler caused a context switch then pdTRUE is 01011 * returned, otherwise pdFALSE is returned. 01012 * 01013 * Example usage: 01014 <pre> 01015 void vTask1( void * pvParameters ) 01016 { 01017 for( ;; ) 01018 { 01019 // Task code goes here. 01020 01021 // ... 01022 01023 // At some point the task wants to perform a long operation during 01024 // which it does not want to get swapped out. It cannot use 01025 // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the 01026 // operation may cause interrupts to be missed - including the 01027 // ticks. 01028 01029 // Prevent the real time kernel swapping out the task. 01030 vTaskSuspendAll (); 01031 01032 // Perform the operation here. There is no need to use critical 01033 // sections as we have all the microcontroller processing time. 01034 // During this time interrupts will still operate and the real 01035 // time kernel tick count will be maintained. 01036 01037 // ... 01038 01039 // The operation is complete. Restart the kernel. We want to force 01040 // a context switch - but there is no point if resuming the scheduler 01041 // caused a context switch already. 01042 if( !xTaskResumeAll () ) 01043 { 01044 taskYIELD (); 01045 } 01046 } 01047 } 01048 </pre> 01049 * \defgroup xTaskResumeAll xTaskResumeAll 01050 * \ingroup SchedulerControl 01051 */ 01052 BaseType_t xTaskResumeAll( void ) PRIVILEGED_FUNCTION; 01053 01054 /*----------------------------------------------------------- 01055 * TASK UTILITIES 01056 *----------------------------------------------------------*/ 01057 01058 /** 01059 * task. h 01060 * <PRE>TickType_t xTaskGetTickCount( void );</PRE> 01061 * 01062 * @return The count of ticks since vTaskStartScheduler was called. 01063 * 01064 * \defgroup xTaskGetTickCount xTaskGetTickCount 01065 * \ingroup TaskUtils 01066 */ 01067 TickType_t xTaskGetTickCount( void ) PRIVILEGED_FUNCTION; 01068 01069 /** 01070 * task. h 01071 * <PRE>TickType_t xTaskGetTickCountFromISR( void );</PRE> 01072 * 01073 * @return The count of ticks since vTaskStartScheduler was called. 01074 * 01075 * This is a version of xTaskGetTickCount() that is safe to be called from an 01076 * ISR - provided that TickType_t is the natural word size of the 01077 * microcontroller being used or interrupt nesting is either not supported or 01078 * not being used. 01079 * 01080 * \defgroup xTaskGetTickCountFromISR xTaskGetTickCountFromISR 01081 * \ingroup TaskUtils 01082 */ 01083 TickType_t xTaskGetTickCountFromISR( void ) PRIVILEGED_FUNCTION; 01084 01085 /** 01086 * task. h 01087 * <PRE>uint16_t uxTaskGetNumberOfTasks( void );</PRE> 01088 * 01089 * @return The number of tasks that the real time kernel is currently managing. 01090 * This includes all ready, blocked and suspended tasks. A task that 01091 * has been deleted but not yet freed by the idle task will also be 01092 * included in the count. 01093 * 01094 * \defgroup uxTaskGetNumberOfTasks uxTaskGetNumberOfTasks 01095 * \ingroup TaskUtils 01096 */ 01097 UBaseType_t uxTaskGetNumberOfTasks( void ) PRIVILEGED_FUNCTION; 01098 01099 /** 01100 * task. h 01101 * <PRE>char *pcTaskGetTaskName( TaskHandle_t xTaskToQuery );</PRE> 01102 * 01103 * @return The text (human readable) name of the task referenced by the handle 01104 * xTaskToQuery. A task can query its own name by either passing in its own 01105 * handle, or by setting xTaskToQuery to NULL. INCLUDE_pcTaskGetTaskName must be 01106 * set to 1 in FreeRTOSConfig.h for pcTaskGetTaskName() to be available. 01107 * 01108 * \defgroup pcTaskGetTaskName pcTaskGetTaskName 01109 * \ingroup TaskUtils 01110 */ 01111 char *pcTaskGetTaskName( TaskHandle_t xTaskToQuery ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ 01112 01113 /** 01114 * task.h 01115 * <PRE>UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask );</PRE> 01116 * 01117 * INCLUDE_uxTaskGetStackHighWaterMark must be set to 1 in FreeRTOSConfig.h for 01118 * this function to be available. 01119 * 01120 * Returns the high water mark of the stack associated with xTask. That is, 01121 * the minimum free stack space there has been (in words, so on a 32 bit machine 01122 * a value of 1 means 4 bytes) since the task started. The smaller the returned 01123 * number the closer the task has come to overflowing its stack. 01124 * 01125 * @param xTask Handle of the task associated with the stack to be checked. 01126 * Set xTask to NULL to check the stack of the calling task. 01127 * 01128 * @return The smallest amount of free stack space there has been (in words, so 01129 * actual spaces on the stack rather than bytes) since the task referenced by 01130 * xTask was created. 01131 */ 01132 UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; 01133 01134 /* When using trace macros it is sometimes necessary to include task.h before 01135 FreeRTOS.h. When this is done TaskHookFunction_t will not yet have been defined, 01136 so the following two prototypes will cause a compilation error. This can be 01137 fixed by simply guarding against the inclusion of these two prototypes unless 01138 they are explicitly required by the configUSE_APPLICATION_TASK_TAG configuration 01139 constant. */ 01140 #ifdef configUSE_APPLICATION_TASK_TAG 01141 #if configUSE_APPLICATION_TASK_TAG == 1 01142 /** 01143 * task.h 01144 * <pre>void vTaskSetApplicationTaskTag( TaskHandle_t xTask, TaskHookFunction_t pxHookFunction );</pre> 01145 * 01146 * Sets pxHookFunction to be the task hook function used by the task xTask. 01147 * Passing xTask as NULL has the effect of setting the calling tasks hook 01148 * function. 01149 */ 01150 void vTaskSetApplicationTaskTag( TaskHandle_t xTask, TaskHookFunction_t pxHookFunction ) PRIVILEGED_FUNCTION; 01151 01152 /** 01153 * task.h 01154 * <pre>void xTaskGetApplicationTaskTag( TaskHandle_t xTask );</pre> 01155 * 01156 * Returns the pxHookFunction value assigned to the task xTask. 01157 */ 01158 TaskHookFunction_t xTaskGetApplicationTaskTag( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; 01159 #endif /* configUSE_APPLICATION_TASK_TAG ==1 */ 01160 #endif /* ifdef configUSE_APPLICATION_TASK_TAG */ 01161 01162 #if( configNUM_THREAD_LOCAL_STORAGE_POINTERS > 0 ) 01163 01164 /* Each task contains an array of pointers that is dimensioned by the 01165 configNUM_THREAD_LOCAL_STORAGE_POINTERS setting in FreeRTOSConfig.h. The 01166 kernel does not use the pointers itself, so the application writer can use 01167 the pointers for any purpose they wish. The following two functions are 01168 used to set and query a pointer respectively. */ 01169 void vTaskSetThreadLocalStoragePointer( TaskHandle_t xTaskToSet, BaseType_t xIndex, void *pvValue ); 01170 void *pvTaskGetThreadLocalStoragePointer( TaskHandle_t xTaskToQuery, BaseType_t xIndex ); 01171 01172 #endif 01173 01174 /** 01175 * task.h 01176 * <pre>BaseType_t xTaskCallApplicationTaskHook( TaskHandle_t xTask, void *pvParameter );</pre> 01177 * 01178 * Calls the hook function associated with xTask. Passing xTask as NULL has 01179 * the effect of calling the Running tasks (the calling task) hook function. 01180 * 01181 * pvParameter is passed to the hook function for the task to interpret as it 01182 * wants. The return value is the value returned by the task hook function 01183 * registered by the user. 01184 */ 01185 BaseType_t xTaskCallApplicationTaskHook( TaskHandle_t xTask, void *pvParameter ) PRIVILEGED_FUNCTION; 01186 01187 /** 01188 * xTaskGetIdleTaskHandle() is only available if 01189 * INCLUDE_xTaskGetIdleTaskHandle is set to 1 in FreeRTOSConfig.h. 01190 * 01191 * Simply returns the handle of the idle task. It is not valid to call 01192 * xTaskGetIdleTaskHandle() before the scheduler has been started. 01193 */ 01194 TaskHandle_t xTaskGetIdleTaskHandle( void ); 01195 01196 /** 01197 * configUSE_TRACE_FACILITY must be defined as 1 in FreeRTOSConfig.h for 01198 * uxTaskGetSystemState() to be available. 01199 * 01200 * uxTaskGetSystemState() populates an TaskStatus_t structure for each task in 01201 * the system. TaskStatus_t structures contain, among other things, members 01202 * for the task handle, task name, task priority, task state, and total amount 01203 * of run time consumed by the task. See the TaskStatus_t structure 01204 * definition in this file for the full member list. 01205 * 01206 * NOTE: This function is intended for debugging use only as its use results in 01207 * the scheduler remaining suspended for an extended period. 01208 * 01209 * @param pxTaskStatusArray A pointer to an array of TaskStatus_t structures. 01210 * The array must contain at least one TaskStatus_t structure for each task 01211 * that is under the control of the RTOS. The number of tasks under the control 01212 * of the RTOS can be determined using the uxTaskGetNumberOfTasks() API function. 01213 * 01214 * @param uxArraySize The size of the array pointed to by the pxTaskStatusArray 01215 * parameter. The size is specified as the number of indexes in the array, or 01216 * the number of TaskStatus_t structures contained in the array, not by the 01217 * number of bytes in the array. 01218 * 01219 * @param pulTotalRunTime If configGENERATE_RUN_TIME_STATS is set to 1 in 01220 * FreeRTOSConfig.h then *pulTotalRunTime is set by uxTaskGetSystemState() to the 01221 * total run time (as defined by the run time stats clock, see 01222 * http://www.freertos.org/rtos-run-time-stats.html) since the target booted. 01223 * pulTotalRunTime can be set to NULL to omit the total run time information. 01224 * 01225 * @return The number of TaskStatus_t structures that were populated by 01226 * uxTaskGetSystemState(). This should equal the number returned by the 01227 * uxTaskGetNumberOfTasks() API function, but will be zero if the value passed 01228 * in the uxArraySize parameter was too small. 01229 * 01230 * Example usage: 01231 <pre> 01232 // This example demonstrates how a human readable table of run time stats 01233 // information is generated from raw data provided by uxTaskGetSystemState(). 01234 // The human readable table is written to pcWriteBuffer 01235 void vTaskGetRunTimeStats( char *pcWriteBuffer ) 01236 { 01237 TaskStatus_t *pxTaskStatusArray; 01238 volatile UBaseType_t uxArraySize, x; 01239 uint32_t ulTotalRunTime, ulStatsAsPercentage; 01240 01241 // Make sure the write buffer does not contain a string. 01242 *pcWriteBuffer = 0x00; 01243 01244 // Take a snapshot of the number of tasks in case it changes while this 01245 // function is executing. 01246 uxArraySize = uxTaskGetNumberOfTasks(); 01247 01248 // Allocate a TaskStatus_t structure for each task. An array could be 01249 // allocated statically at compile time. 01250 pxTaskStatusArray = pvPortMalloc( uxArraySize * sizeof( TaskStatus_t ) ); 01251 01252 if( pxTaskStatusArray != NULL ) 01253 { 01254 // Generate raw status information about each task. 01255 uxArraySize = uxTaskGetSystemState( pxTaskStatusArray, uxArraySize, &ulTotalRunTime ); 01256 01257 // For percentage calculations. 01258 ulTotalRunTime /= 100UL; 01259 01260 // Avoid divide by zero errors. 01261 if( ulTotalRunTime > 0 ) 01262 { 01263 // For each populated position in the pxTaskStatusArray array, 01264 // format the raw data as human readable ASCII data 01265 for( x = 0; x < uxArraySize; x++ ) 01266 { 01267 // What percentage of the total run time has the task used? 01268 // This will always be rounded down to the nearest integer. 01269 // ulTotalRunTimeDiv100 has already been divided by 100. 01270 ulStatsAsPercentage = pxTaskStatusArray[ x ].ulRunTimeCounter / ulTotalRunTime; 01271 01272 if( ulStatsAsPercentage > 0UL ) 01273 { 01274 sprintf( pcWriteBuffer, "%s\t\t%lu\t\t%lu%%\r\n", pxTaskStatusArray[ x ].pcTaskName, pxTaskStatusArray[ x ].ulRunTimeCounter, ulStatsAsPercentage ); 01275 } 01276 else 01277 { 01278 // If the percentage is zero here then the task has 01279 // consumed less than 1% of the total run time. 01280 sprintf( pcWriteBuffer, "%s\t\t%lu\t\t<1%%\r\n", pxTaskStatusArray[ x ].pcTaskName, pxTaskStatusArray[ x ].ulRunTimeCounter ); 01281 } 01282 01283 pcWriteBuffer += strlen( ( char * ) pcWriteBuffer ); 01284 } 01285 } 01286 01287 // The array is no longer needed, free the memory it consumes. 01288 vPortFree( pxTaskStatusArray ); 01289 } 01290 } 01291 </pre> 01292 */ 01293 UBaseType_t uxTaskGetSystemState( TaskStatus_t * const pxTaskStatusArray, const UBaseType_t uxArraySize, uint32_t * const pulTotalRunTime ); 01294 01295 /** 01296 * task. h 01297 * <PRE>void vTaskList( char *pcWriteBuffer );</PRE> 01298 * 01299 * configUSE_TRACE_FACILITY and configUSE_STATS_FORMATTING_FUNCTIONS must 01300 * both be defined as 1 for this function to be available. See the 01301 * configuration section of the FreeRTOS.org website for more information. 01302 * 01303 * NOTE 1: This function will disable interrupts for its duration. It is 01304 * not intended for normal application runtime use but as a debug aid. 01305 * 01306 * Lists all the current tasks, along with their current state and stack 01307 * usage high water mark. 01308 * 01309 * Tasks are reported as blocked ('B'), ready ('R'), deleted ('D') or 01310 * suspended ('S'). 01311 * 01312 * PLEASE NOTE: 01313 * 01314 * This function is provided for convenience only, and is used by many of the 01315 * demo applications. Do not consider it to be part of the scheduler. 01316 * 01317 * vTaskList() calls uxTaskGetSystemState(), then formats part of the 01318 * uxTaskGetSystemState() output into a human readable table that displays task 01319 * names, states and stack usage. 01320 * 01321 * vTaskList() has a dependency on the sprintf() C library function that might 01322 * bloat the code size, use a lot of stack, and provide different results on 01323 * different platforms. An alternative, tiny, third party, and limited 01324 * functionality implementation of sprintf() is provided in many of the 01325 * FreeRTOS/Demo sub-directories in a file called printf-stdarg.c (note 01326 * printf-stdarg.c does not provide a full snprintf() implementation!). 01327 * 01328 * It is recommended that production systems call uxTaskGetSystemState() 01329 * directly to get access to raw stats data, rather than indirectly through a 01330 * call to vTaskList(). 01331 * 01332 * @param pcWriteBuffer A buffer into which the above mentioned details 01333 * will be written, in ASCII form. This buffer is assumed to be large 01334 * enough to contain the generated report. Approximately 40 bytes per 01335 * task should be sufficient. 01336 * 01337 * \defgroup vTaskList vTaskList 01338 * \ingroup TaskUtils 01339 */ 01340 void vTaskList( char * pcWriteBuffer ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ 01341 01342 /** 01343 * task. h 01344 * <PRE>void vTaskGetRunTimeStats( char *pcWriteBuffer );</PRE> 01345 * 01346 * configGENERATE_RUN_TIME_STATS and configUSE_STATS_FORMATTING_FUNCTIONS 01347 * must both be defined as 1 for this function to be available. The application 01348 * must also then provide definitions for 01349 * portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and portGET_RUN_TIME_COUNTER_VALUE() 01350 * to configure a peripheral timer/counter and return the timers current count 01351 * value respectively. The counter should be at least 10 times the frequency of 01352 * the tick count. 01353 * 01354 * NOTE 1: This function will disable interrupts for its duration. It is 01355 * not intended for normal application runtime use but as a debug aid. 01356 * 01357 * Setting configGENERATE_RUN_TIME_STATS to 1 will result in a total 01358 * accumulated execution time being stored for each task. The resolution 01359 * of the accumulated time value depends on the frequency of the timer 01360 * configured by the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() macro. 01361 * Calling vTaskGetRunTimeStats() writes the total execution time of each 01362 * task into a buffer, both as an absolute count value and as a percentage 01363 * of the total system execution time. 01364 * 01365 * NOTE 2: 01366 * 01367 * This function is provided for convenience only, and is used by many of the 01368 * demo applications. Do not consider it to be part of the scheduler. 01369 * 01370 * vTaskGetRunTimeStats() calls uxTaskGetSystemState(), then formats part of the 01371 * uxTaskGetSystemState() output into a human readable table that displays the 01372 * amount of time each task has spent in the Running state in both absolute and 01373 * percentage terms. 01374 * 01375 * vTaskGetRunTimeStats() has a dependency on the sprintf() C library function 01376 * that might bloat the code size, use a lot of stack, and provide different 01377 * results on different platforms. An alternative, tiny, third party, and 01378 * limited functionality implementation of sprintf() is provided in many of the 01379 * FreeRTOS/Demo sub-directories in a file called printf-stdarg.c (note 01380 * printf-stdarg.c does not provide a full snprintf() implementation!). 01381 * 01382 * It is recommended that production systems call uxTaskGetSystemState() directly 01383 * to get access to raw stats data, rather than indirectly through a call to 01384 * vTaskGetRunTimeStats(). 01385 * 01386 * @param pcWriteBuffer A buffer into which the execution times will be 01387 * written, in ASCII form. This buffer is assumed to be large enough to 01388 * contain the generated report. Approximately 40 bytes per task should 01389 * be sufficient. 01390 * 01391 * \defgroup vTaskGetRunTimeStats vTaskGetRunTimeStats 01392 * \ingroup TaskUtils 01393 */ 01394 void vTaskGetRunTimeStats( char *pcWriteBuffer ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ 01395 01396 /** 01397 * task. h 01398 * <PRE>BaseType_t xTaskNotify( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction );</PRE> 01399 * 01400 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this 01401 * function to be available. 01402 * 01403 * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private 01404 * "notification value", which is a 32-bit unsigned integer (uint32_t). 01405 * 01406 * Events can be sent to a task using an intermediary object. Examples of such 01407 * objects are queues, semaphores, mutexes and event groups. Task notifications 01408 * are a method of sending an event directly to a task without the need for such 01409 * an intermediary object. 01410 * 01411 * A notification sent to a task can optionally perform an action, such as 01412 * update, overwrite or increment the task's notification value. In that way 01413 * task notifications can be used to send data to a task, or be used as light 01414 * weight and fast binary or counting semaphores. 01415 * 01416 * A notification sent to a task will remain pending until it is cleared by the 01417 * task calling xTaskNotifyWait() or ulTaskNotifyTake(). If the task was 01418 * already in the Blocked state to wait for a notification when the notification 01419 * arrives then the task will automatically be removed from the Blocked state 01420 * (unblocked) and the notification cleared. 01421 * 01422 * A task can use xTaskNotifyWait() to [optionally] block to wait for a 01423 * notification to be pending, or ulTaskNotifyTake() to [optionally] block 01424 * to wait for its notification value to have a non-zero value. The task does 01425 * not consume any CPU time while it is in the Blocked state. 01426 * 01427 * See http://www.FreeRTOS.org/RTOS-task-notifications.html for details. 01428 * 01429 * @param xTaskToNotify The handle of the task being notified. The handle to a 01430 * task can be returned from the xTaskCreate() API function used to create the 01431 * task, and the handle of the currently running task can be obtained by calling 01432 * xTaskGetCurrentTaskHandle(). 01433 * 01434 * @param ulValue Data that can be sent with the notification. How the data is 01435 * used depends on the value of the eAction parameter. 01436 * 01437 * @param eAction Specifies how the notification updates the task's notification 01438 * value, if at all. Valid values for eAction are as follows: 01439 * 01440 * eSetBits - 01441 * The task's notification value is bitwise ORed with ulValue. xTaskNofify() 01442 * always returns pdPASS in this case. 01443 * 01444 * eIncrement - 01445 * The task's notification value is incremented. ulValue is not used and 01446 * xTaskNotify() always returns pdPASS in this case. 01447 * 01448 * eSetValueWithOverwrite - 01449 * The task's notification value is set to the value of ulValue, even if the 01450 * task being notified had not yet processed the previous notification (the 01451 * task already had a notification pending). xTaskNotify() always returns 01452 * pdPASS in this case. 01453 * 01454 * eSetValueWithoutOverwrite - 01455 * If the task being notified did not already have a notification pending then 01456 * the task's notification value is set to ulValue and xTaskNotify() will 01457 * return pdPASS. If the task being notified already had a notification 01458 * pending then no action is performed and pdFAIL is returned. 01459 * 01460 * eNoAction - 01461 * The task receives a notification without its notification value being 01462 * updated. ulValue is not used and xTaskNotify() always returns pdPASS in 01463 * this case. 01464 * 01465 * pulPreviousNotificationValue - 01466 * Can be used to pass out the subject task's notification value before any 01467 * bits are modified by the notify function. 01468 * 01469 * @return Dependent on the value of eAction. See the description of the 01470 * eAction parameter. 01471 * 01472 * \defgroup xTaskNotify xTaskNotify 01473 * \ingroup TaskNotifications 01474 */ 01475 BaseType_t xTaskGenericNotify( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue ); 01476 #define xTaskNotify( xTaskToNotify, ulValue, eAction ) xTaskGenericNotify( ( xTaskToNotify ), ( ulValue ), ( eAction ), NULL ) 01477 #define xTaskNotifyAndQuery( xTaskToNotify, ulValue, eAction, pulPreviousNotifyValue ) xTaskGenericNotify( ( xTaskToNotify ), ( ulValue ), ( eAction ), ( pulPreviousNotifyValue ) ) 01478 01479 /** 01480 * task. h 01481 * <PRE>BaseType_t xTaskNotifyFromISR( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, BaseType_t *pxHigherPriorityTaskWoken );</PRE> 01482 * 01483 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this 01484 * function to be available. 01485 * 01486 * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private 01487 * "notification value", which is a 32-bit unsigned integer (uint32_t). 01488 * 01489 * A version of xTaskNotify() that can be used from an interrupt service routine 01490 * (ISR). 01491 * 01492 * Events can be sent to a task using an intermediary object. Examples of such 01493 * objects are queues, semaphores, mutexes and event groups. Task notifications 01494 * are a method of sending an event directly to a task without the need for such 01495 * an intermediary object. 01496 * 01497 * A notification sent to a task can optionally perform an action, such as 01498 * update, overwrite or increment the task's notification value. In that way 01499 * task notifications can be used to send data to a task, or be used as light 01500 * weight and fast binary or counting semaphores. 01501 * 01502 * A notification sent to a task will remain pending until it is cleared by the 01503 * task calling xTaskNotifyWait() or ulTaskNotifyTake(). If the task was 01504 * already in the Blocked state to wait for a notification when the notification 01505 * arrives then the task will automatically be removed from the Blocked state 01506 * (unblocked) and the notification cleared. 01507 * 01508 * A task can use xTaskNotifyWait() to [optionally] block to wait for a 01509 * notification to be pending, or ulTaskNotifyTake() to [optionally] block 01510 * to wait for its notification value to have a non-zero value. The task does 01511 * not consume any CPU time while it is in the Blocked state. 01512 * 01513 * See http://www.FreeRTOS.org/RTOS-task-notifications.html for details. 01514 * 01515 * @param xTaskToNotify The handle of the task being notified. The handle to a 01516 * task can be returned from the xTaskCreate() API function used to create the 01517 * task, and the handle of the currently running task can be obtained by calling 01518 * xTaskGetCurrentTaskHandle(). 01519 * 01520 * @param ulValue Data that can be sent with the notification. How the data is 01521 * used depends on the value of the eAction parameter. 01522 * 01523 * @param eAction Specifies how the notification updates the task's notification 01524 * value, if at all. Valid values for eAction are as follows: 01525 * 01526 * eSetBits - 01527 * The task's notification value is bitwise ORed with ulValue. xTaskNofify() 01528 * always returns pdPASS in this case. 01529 * 01530 * eIncrement - 01531 * The task's notification value is incremented. ulValue is not used and 01532 * xTaskNotify() always returns pdPASS in this case. 01533 * 01534 * eSetValueWithOverwrite - 01535 * The task's notification value is set to the value of ulValue, even if the 01536 * task being notified had not yet processed the previous notification (the 01537 * task already had a notification pending). xTaskNotify() always returns 01538 * pdPASS in this case. 01539 * 01540 * eSetValueWithoutOverwrite - 01541 * If the task being notified did not already have a notification pending then 01542 * the task's notification value is set to ulValue and xTaskNotify() will 01543 * return pdPASS. If the task being notified already had a notification 01544 * pending then no action is performed and pdFAIL is returned. 01545 * 01546 * eNoAction - 01547 * The task receives a notification without its notification value being 01548 * updated. ulValue is not used and xTaskNotify() always returns pdPASS in 01549 * this case. 01550 * 01551 * @param pxHigherPriorityTaskWoken xTaskNotifyFromISR() will set 01552 * *pxHigherPriorityTaskWoken to pdTRUE if sending the notification caused the 01553 * task to which the notification was sent to leave the Blocked state, and the 01554 * unblocked task has a priority higher than the currently running task. If 01555 * xTaskNotifyFromISR() sets this value to pdTRUE then a context switch should 01556 * be requested before the interrupt is exited. How a context switch is 01557 * requested from an ISR is dependent on the port - see the documentation page 01558 * for the port in use. 01559 * 01560 * @return Dependent on the value of eAction. See the description of the 01561 * eAction parameter. 01562 * 01563 * \defgroup xTaskNotify xTaskNotify 01564 * \ingroup TaskNotifications 01565 */ 01566 BaseType_t xTaskNotifyFromISR( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, BaseType_t *pxHigherPriorityTaskWoken ); 01567 01568 /** 01569 * task. h 01570 * <PRE>BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait );</pre> 01571 * 01572 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this 01573 * function to be available. 01574 * 01575 * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private 01576 * "notification value", which is a 32-bit unsigned integer (uint32_t). 01577 * 01578 * Events can be sent to a task using an intermediary object. Examples of such 01579 * objects are queues, semaphores, mutexes and event groups. Task notifications 01580 * are a method of sending an event directly to a task without the need for such 01581 * an intermediary object. 01582 * 01583 * A notification sent to a task can optionally perform an action, such as 01584 * update, overwrite or increment the task's notification value. In that way 01585 * task notifications can be used to send data to a task, or be used as light 01586 * weight and fast binary or counting semaphores. 01587 * 01588 * A notification sent to a task will remain pending until it is cleared by the 01589 * task calling xTaskNotifyWait() or ulTaskNotifyTake(). If the task was 01590 * already in the Blocked state to wait for a notification when the notification 01591 * arrives then the task will automatically be removed from the Blocked state 01592 * (unblocked) and the notification cleared. 01593 * 01594 * A task can use xTaskNotifyWait() to [optionally] block to wait for a 01595 * notification to be pending, or ulTaskNotifyTake() to [optionally] block 01596 * to wait for its notification value to have a non-zero value. The task does 01597 * not consume any CPU time while it is in the Blocked state. 01598 * 01599 * See http://www.FreeRTOS.org/RTOS-task-notifications.html for details. 01600 * 01601 * @param ulBitsToClearOnEntry Bits that are set in ulBitsToClearOnEntry value 01602 * will be cleared in the calling task's notification value before the task 01603 * checks to see if any notifications are pending, and optionally blocks if no 01604 * notifications are pending. Setting ulBitsToClearOnEntry to ULONG_MAX (if 01605 * limits.h is included) or 0xffffffffUL (if limits.h is not included) will have 01606 * the effect of resetting the task's notification value to 0. Setting 01607 * ulBitsToClearOnEntry to 0 will leave the task's notification value unchanged. 01608 * 01609 * @param ulBitsToClearOnExit If a notification is pending or received before 01610 * the calling task exits the xTaskNotifyWait() function then the task's 01611 * notification value (see the xTaskNotify() API function) is passed out using 01612 * the pulNotificationValue parameter. Then any bits that are set in 01613 * ulBitsToClearOnExit will be cleared in the task's notification value (note 01614 * *pulNotificationValue is set before any bits are cleared). Setting 01615 * ulBitsToClearOnExit to ULONG_MAX (if limits.h is included) or 0xffffffffUL 01616 * (if limits.h is not included) will have the effect of resetting the task's 01617 * notification value to 0 before the function exits. Setting 01618 * ulBitsToClearOnExit to 0 will leave the task's notification value unchanged 01619 * when the function exits (in which case the value passed out in 01620 * pulNotificationValue will match the task's notification value). 01621 * 01622 * @param pulNotificationValue Used to pass the task's notification value out 01623 * of the function. Note the value passed out will not be effected by the 01624 * clearing of any bits caused by ulBitsToClearOnExit being non-zero. 01625 * 01626 * @param xTicksToWait The maximum amount of time that the task should wait in 01627 * the Blocked state for a notification to be received, should a notification 01628 * not already be pending when xTaskNotifyWait() was called. The task 01629 * will not consume any processing time while it is in the Blocked state. This 01630 * is specified in kernel ticks, the macro pdMS_TO_TICSK( value_in_ms ) can be 01631 * used to convert a time specified in milliseconds to a time specified in 01632 * ticks. 01633 * 01634 * @return If a notification was received (including notifications that were 01635 * already pending when xTaskNotifyWait was called) then pdPASS is 01636 * returned. Otherwise pdFAIL is returned. 01637 * 01638 * \defgroup xTaskNotifyWait xTaskNotifyWait 01639 * \ingroup TaskNotifications 01640 */ 01641 BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait ); 01642 01643 /** 01644 * task. h 01645 * <PRE>BaseType_t xTaskNotifyGive( TaskHandle_t xTaskToNotify );</PRE> 01646 * 01647 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this macro 01648 * to be available. 01649 * 01650 * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private 01651 * "notification value", which is a 32-bit unsigned integer (uint32_t). 01652 * 01653 * Events can be sent to a task using an intermediary object. Examples of such 01654 * objects are queues, semaphores, mutexes and event groups. Task notifications 01655 * are a method of sending an event directly to a task without the need for such 01656 * an intermediary object. 01657 * 01658 * A notification sent to a task can optionally perform an action, such as 01659 * update, overwrite or increment the task's notification value. In that way 01660 * task notifications can be used to send data to a task, or be used as light 01661 * weight and fast binary or counting semaphores. 01662 * 01663 * xTaskNotifyGive() is a helper macro intended for use when task notifications 01664 * are used as light weight and faster binary or counting semaphore equivalents. 01665 * Actual FreeRTOS semaphores are given using the xSemaphoreGive() API function, 01666 * the equivalent action that instead uses a task notification is 01667 * xTaskNotifyGive(). 01668 * 01669 * When task notifications are being used as a binary or counting semaphore 01670 * equivalent then the task being notified should wait for the notification 01671 * using the ulTaskNotificationTake() API function rather than the 01672 * xTaskNotifyWait() API function. 01673 * 01674 * See http://www.FreeRTOS.org/RTOS-task-notifications.html for more details. 01675 * 01676 * @param xTaskToNotify The handle of the task being notified. The handle to a 01677 * task can be returned from the xTaskCreate() API function used to create the 01678 * task, and the handle of the currently running task can be obtained by calling 01679 * xTaskGetCurrentTaskHandle(). 01680 * 01681 * @return xTaskNotifyGive() is a macro that calls xTaskNotify() with the 01682 * eAction parameter set to eIncrement - so pdPASS is always returned. 01683 * 01684 * \defgroup xTaskNotifyGive xTaskNotifyGive 01685 * \ingroup TaskNotifications 01686 */ 01687 #define xTaskNotifyGive( xTaskToNotify ) xTaskNotify( ( xTaskToNotify ), 0, eIncrement ); 01688 01689 /** 01690 * task. h 01691 * <PRE>void vTaskNotifyGiveFromISR( TaskHandle_t xTaskHandle, BaseType_t *pxHigherPriorityTaskWoken ); 01692 * 01693 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this macro 01694 * to be available. 01695 * 01696 * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private 01697 * "notification value", which is a 32-bit unsigned integer (uint32_t). 01698 * 01699 * A version of xTaskNotifyGive() that can be called from an interrupt service 01700 * routine (ISR). 01701 * 01702 * Events can be sent to a task using an intermediary object. Examples of such 01703 * objects are queues, semaphores, mutexes and event groups. Task notifications 01704 * are a method of sending an event directly to a task without the need for such 01705 * an intermediary object. 01706 * 01707 * A notification sent to a task can optionally perform an action, such as 01708 * update, overwrite or increment the task's notification value. In that way 01709 * task notifications can be used to send data to a task, or be used as light 01710 * weight and fast binary or counting semaphores. 01711 * 01712 * vTaskNotifyGiveFromISR() is intended for use when task notifications are 01713 * used as light weight and faster binary or counting semaphore equivalents. 01714 * Actual FreeRTOS semaphores are given from an ISR using the 01715 * xSemaphoreGiveFromISR() API function, the equivalent action that instead uses 01716 * a task notification is vTaskNotifyGiveFromISR(). 01717 * 01718 * When task notifications are being used as a binary or counting semaphore 01719 * equivalent then the task being notified should wait for the notification 01720 * using the ulTaskNotificationTake() API function rather than the 01721 * xTaskNotifyWait() API function. 01722 * 01723 * See http://www.FreeRTOS.org/RTOS-task-notifications.html for more details. 01724 * 01725 * @param xTaskToNotify The handle of the task being notified. The handle to a 01726 * task can be returned from the xTaskCreate() API function used to create the 01727 * task, and the handle of the currently running task can be obtained by calling 01728 * xTaskGetCurrentTaskHandle(). 01729 * 01730 * @param pxHigherPriorityTaskWoken vTaskNotifyGiveFromISR() will set 01731 * *pxHigherPriorityTaskWoken to pdTRUE if sending the notification caused the 01732 * task to which the notification was sent to leave the Blocked state, and the 01733 * unblocked task has a priority higher than the currently running task. If 01734 * vTaskNotifyGiveFromISR() sets this value to pdTRUE then a context switch 01735 * should be requested before the interrupt is exited. How a context switch is 01736 * requested from an ISR is dependent on the port - see the documentation page 01737 * for the port in use. 01738 * 01739 * \defgroup xTaskNotifyWait xTaskNotifyWait 01740 * \ingroup TaskNotifications 01741 */ 01742 void vTaskNotifyGiveFromISR( TaskHandle_t xTaskToNotify, BaseType_t *pxHigherPriorityTaskWoken ); 01743 01744 /** 01745 * task. h 01746 * <PRE>uint32_t ulTaskNotifyTake( BaseType_t xClearCountOnExit, TickType_t xTicksToWait );</pre> 01747 * 01748 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this 01749 * function to be available. 01750 * 01751 * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private 01752 * "notification value", which is a 32-bit unsigned integer (uint32_t). 01753 * 01754 * Events can be sent to a task using an intermediary object. Examples of such 01755 * objects are queues, semaphores, mutexes and event groups. Task notifications 01756 * are a method of sending an event directly to a task without the need for such 01757 * an intermediary object. 01758 * 01759 * A notification sent to a task can optionally perform an action, such as 01760 * update, overwrite or increment the task's notification value. In that way 01761 * task notifications can be used to send data to a task, or be used as light 01762 * weight and fast binary or counting semaphores. 01763 * 01764 * ulTaskNotifyTake() is intended for use when a task notification is used as a 01765 * faster and lighter weight binary or counting semaphore alternative. Actual 01766 * FreeRTOS semaphores are taken using the xSemaphoreTake() API function, the 01767 * equivalent action that instead uses a task notification is 01768 * ulTaskNotifyTake(). 01769 * 01770 * When a task is using its notification value as a binary or counting semaphore 01771 * other tasks should send notifications to it using the xTaskNotifyGive() 01772 * macro, or xTaskNotify() function with the eAction parameter set to 01773 * eIncrement. 01774 * 01775 * ulTaskNotifyTake() can either clear the task's notification value to 01776 * zero on exit, in which case the notification value acts like a binary 01777 * semaphore, or decrement the task's notification value on exit, in which case 01778 * the notification value acts like a counting semaphore. 01779 * 01780 * A task can use ulTaskNotifyTake() to [optionally] block to wait for a 01781 * the task's notification value to be non-zero. The task does not consume any 01782 * CPU time while it is in the Blocked state. 01783 * 01784 * Where as xTaskNotifyWait() will return when a notification is pending, 01785 * ulTaskNotifyTake() will return when the task's notification value is 01786 * not zero. 01787 * 01788 * See http://www.FreeRTOS.org/RTOS-task-notifications.html for details. 01789 * 01790 * @param xClearCountOnExit if xClearCountOnExit is pdFALSE then the task's 01791 * notification value is decremented when the function exits. In this way the 01792 * notification value acts like a counting semaphore. If xClearCountOnExit is 01793 * not pdFALSE then the task's notification value is cleared to zero when the 01794 * function exits. In this way the notification value acts like a binary 01795 * semaphore. 01796 * 01797 * @param xTicksToWait The maximum amount of time that the task should wait in 01798 * the Blocked state for the task's notification value to be greater than zero, 01799 * should the count not already be greater than zero when 01800 * ulTaskNotifyTake() was called. The task will not consume any processing 01801 * time while it is in the Blocked state. This is specified in kernel ticks, 01802 * the macro pdMS_TO_TICSK( value_in_ms ) can be used to convert a time 01803 * specified in milliseconds to a time specified in ticks. 01804 * 01805 * @return The task's notification count before it is either cleared to zero or 01806 * decremented (see the xClearCountOnExit parameter). 01807 * 01808 * \defgroup ulTaskNotifyTake ulTaskNotifyTake 01809 * \ingroup TaskNotifications 01810 */ 01811 uint32_t ulTaskNotifyTake( BaseType_t xClearCountOnExit, TickType_t xTicksToWait ); 01812 01813 /*----------------------------------------------------------- 01814 * SCHEDULER INTERNALS AVAILABLE FOR PORTING PURPOSES 01815 *----------------------------------------------------------*/ 01816 01817 /* 01818 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS ONLY 01819 * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS 01820 * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER. 01821 * 01822 * Called from the real time kernel tick (either preemptive or cooperative), 01823 * this increments the tick count and checks if any tasks that are blocked 01824 * for a finite period required removing from a blocked list and placing on 01825 * a ready list. If a non-zero value is returned then a context switch is 01826 * required because either: 01827 * + A task was removed from a blocked list because its timeout had expired, 01828 * or 01829 * + Time slicing is in use and there is a task of equal priority to the 01830 * currently running task. 01831 */ 01832 BaseType_t xTaskIncrementTick( void ) PRIVILEGED_FUNCTION; 01833 01834 /* 01835 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN 01836 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER. 01837 * 01838 * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED. 01839 * 01840 * Removes the calling task from the ready list and places it both 01841 * on the list of tasks waiting for a particular event, and the 01842 * list of delayed tasks. The task will be removed from both lists 01843 * and replaced on the ready list should either the event occur (and 01844 * there be no higher priority tasks waiting on the same event) or 01845 * the delay period expires. 01846 * 01847 * The 'unordered' version replaces the event list item value with the 01848 * xItemValue value, and inserts the list item at the end of the list. 01849 * 01850 * The 'ordered' version uses the existing event list item value (which is the 01851 * owning tasks priority) to insert the list item into the event list is task 01852 * priority order. 01853 * 01854 * @param pxEventList The list containing tasks that are blocked waiting 01855 * for the event to occur. 01856 * 01857 * @param xItemValue The item value to use for the event list item when the 01858 * event list is not ordered by task priority. 01859 * 01860 * @param xTicksToWait The maximum amount of time that the task should wait 01861 * for the event to occur. This is specified in kernel ticks,the constant 01862 * portTICK_PERIOD_MS can be used to convert kernel ticks into a real time 01863 * period. 01864 */ 01865 void vTaskPlaceOnEventList( List_t * const pxEventList, const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; 01866 void vTaskPlaceOnUnorderedEventList( List_t * pxEventList, const TickType_t xItemValue, const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; 01867 01868 /* 01869 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN 01870 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER. 01871 * 01872 * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED. 01873 * 01874 * This function performs nearly the same function as vTaskPlaceOnEventList(). 01875 * The difference being that this function does not permit tasks to block 01876 * indefinitely, whereas vTaskPlaceOnEventList() does. 01877 * 01878 */ 01879 void vTaskPlaceOnEventListRestricted( List_t * const pxEventList, const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; 01880 01881 /* 01882 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN 01883 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER. 01884 * 01885 * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED. 01886 * 01887 * Removes a task from both the specified event list and the list of blocked 01888 * tasks, and places it on a ready queue. 01889 * 01890 * xTaskRemoveFromEventList()/xTaskRemoveFromUnorderedEventList() will be called 01891 * if either an event occurs to unblock a task, or the block timeout period 01892 * expires. 01893 * 01894 * xTaskRemoveFromEventList() is used when the event list is in task priority 01895 * order. It removes the list item from the head of the event list as that will 01896 * have the highest priority owning task of all the tasks on the event list. 01897 * xTaskRemoveFromUnorderedEventList() is used when the event list is not 01898 * ordered and the event list items hold something other than the owning tasks 01899 * priority. In this case the event list item value is updated to the value 01900 * passed in the xItemValue parameter. 01901 * 01902 * @return pdTRUE if the task being removed has a higher priority than the task 01903 * making the call, otherwise pdFALSE. 01904 */ 01905 BaseType_t xTaskRemoveFromEventList( const List_t * const pxEventList ) PRIVILEGED_FUNCTION; 01906 BaseType_t xTaskRemoveFromUnorderedEventList( ListItem_t * pxEventListItem, const TickType_t xItemValue ) PRIVILEGED_FUNCTION; 01907 01908 /* 01909 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS ONLY 01910 * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS 01911 * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER. 01912 * 01913 * Sets the pointer to the current TCB to the TCB of the highest priority task 01914 * that is ready to run. 01915 */ 01916 void vTaskSwitchContext( void ) PRIVILEGED_FUNCTION; 01917 01918 /* 01919 * THESE FUNCTIONS MUST NOT BE USED FROM APPLICATION CODE. THEY ARE USED BY 01920 * THE EVENT BITS MODULE. 01921 */ 01922 TickType_t uxTaskResetEventItemValue( void ) PRIVILEGED_FUNCTION; 01923 01924 /* 01925 * Return the handle of the calling task. 01926 */ 01927 TaskHandle_t xTaskGetCurrentTaskHandle( void ) PRIVILEGED_FUNCTION; 01928 01929 /* 01930 * Capture the current time status for future reference. 01931 */ 01932 void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut ) PRIVILEGED_FUNCTION; 01933 01934 /* 01935 * Compare the time status now with that previously captured to see if the 01936 * timeout has expired. 01937 */ 01938 BaseType_t xTaskCheckForTimeOut( TimeOut_t * const pxTimeOut, TickType_t * const pxTicksToWait ) PRIVILEGED_FUNCTION; 01939 01940 /* 01941 * Shortcut used by the queue implementation to prevent unnecessary call to 01942 * taskYIELD(); 01943 */ 01944 void vTaskMissedYield( void ) PRIVILEGED_FUNCTION; 01945 01946 /* 01947 * Returns the scheduler state as taskSCHEDULER_RUNNING, 01948 * taskSCHEDULER_NOT_STARTED or taskSCHEDULER_SUSPENDED. 01949 */ 01950 BaseType_t xTaskGetSchedulerState( void ) PRIVILEGED_FUNCTION; 01951 01952 /* 01953 * Raises the priority of the mutex holder to that of the calling task should 01954 * the mutex holder have a priority less than the calling task. 01955 */ 01956 void vTaskPriorityInherit( TaskHandle_t const pxMutexHolder ) PRIVILEGED_FUNCTION; 01957 01958 /* 01959 * Set the priority of a task back to its proper priority in the case that it 01960 * inherited a higher priority while it was holding a semaphore. 01961 */ 01962 BaseType_t xTaskPriorityDisinherit( TaskHandle_t const pxMutexHolder ) PRIVILEGED_FUNCTION; 01963 01964 /* 01965 * Generic version of the task creation function which is in turn called by the 01966 * xTaskCreate() and xTaskCreateRestricted() macros. 01967 */ 01968 BaseType_t xTaskGenericCreate( TaskFunction_t pxTaskCode, const char * const pcName, const uint16_t usStackDepth, void * const pvParameters, UBaseType_t uxPriority, TaskHandle_t * const pxCreatedTask, StackType_t * const puxStackBuffer, const MemoryRegion_t * const xRegions ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ 01969 01970 /* 01971 * Get the uxTCBNumber assigned to the task referenced by the xTask parameter. 01972 */ 01973 UBaseType_t uxTaskGetTaskNumber( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; 01974 01975 /* 01976 * Set the uxTaskNumber of the task referenced by the xTask parameter to 01977 * uxHandle. 01978 */ 01979 void vTaskSetTaskNumber( TaskHandle_t xTask, const UBaseType_t uxHandle ) PRIVILEGED_FUNCTION; 01980 01981 /* 01982 * Only available when configUSE_TICKLESS_IDLE is set to 1. 01983 * If tickless mode is being used, or a low power mode is implemented, then 01984 * the tick interrupt will not execute during idle periods. When this is the 01985 * case, the tick count value maintained by the scheduler needs to be kept up 01986 * to date with the actual execution time by being skipped forward by a time 01987 * equal to the idle period. 01988 */ 01989 void vTaskStepTick( const TickType_t xTicksToJump ) PRIVILEGED_FUNCTION; 01990 01991 /* 01992 * Only avilable when configUSE_TICKLESS_IDLE is set to 1. 01993 * Provided for use within portSUPPRESS_TICKS_AND_SLEEP() to allow the port 01994 * specific sleep function to determine if it is ok to proceed with the sleep, 01995 * and if it is ok to proceed, if it is ok to sleep indefinitely. 01996 * 01997 * This function is necessary because portSUPPRESS_TICKS_AND_SLEEP() is only 01998 * called with the scheduler suspended, not from within a critical section. It 01999 * is therefore possible for an interrupt to request a context switch between 02000 * portSUPPRESS_TICKS_AND_SLEEP() and the low power mode actually being 02001 * entered. eTaskConfirmSleepModeStatus() should be called from a short 02002 * critical section between the timer being stopped and the sleep mode being 02003 * entered to ensure it is ok to proceed into the sleep mode. 02004 */ 02005 eSleepModeStatus eTaskConfirmSleepModeStatus( void ) PRIVILEGED_FUNCTION; 02006 02007 /* 02008 * For internal use only. Increment the mutex held count when a mutex is 02009 * taken and return the handle of the task that has taken the mutex. 02010 */ 02011 void *pvTaskIncrementMutexHeldCount( void ); 02012 02013 #ifdef __cplusplus 02014 } 02015 #endif 02016 #endif /* INC_TASK_H */ 02017 02018 02019 02020
Generated on Wed Jul 13 2022 09:55:39 by 1.7.2