Francisco Paez / freertos-cm3

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependents:   mbed_lpc1768_freertos_lib

src/include/task.h@0:5ff20db10a96, 2017-05-31 (annotated)

Committer:
fep
Date:
Wed May 31 02:36:43 2017 +0000
Revision:
0:5ff20db10a96
FreeRTOS v9.0.0 for ARM Cortex-M3 based boards.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
fep 0:5ff20db10a96 1 /*
fep 0:5ff20db10a96 2 FreeRTOS V9.0.0 - Copyright (C) 2016 Real Time Engineers Ltd.
fep 0:5ff20db10a96 3 All rights reserved
fep 0:5ff20db10a96 4
fep 0:5ff20db10a96 5 VISIT http://www.FreeRTOS.org TO ENSURE YOU ARE USING THE LATEST VERSION.
fep 0:5ff20db10a96 6
fep 0:5ff20db10a96 7 This file is part of the FreeRTOS distribution.
fep 0:5ff20db10a96 8
fep 0:5ff20db10a96 9 FreeRTOS is free software; you can redistribute it and/or modify it under
fep 0:5ff20db10a96 10 the terms of the GNU General Public License (version 2) as published by the
fep 0:5ff20db10a96 11 Free Software Foundation >>>> AND MODIFIED BY <<<< the FreeRTOS exception.
fep 0:5ff20db10a96 12
fep 0:5ff20db10a96 13 ***************************************************************************
fep 0:5ff20db10a96 14 >>! NOTE: The modification to the GPL is included to allow you to !<<
fep 0:5ff20db10a96 15 >>! distribute a combined work that includes FreeRTOS without being !<<
fep 0:5ff20db10a96 16 >>! obliged to provide the source code for proprietary components !<<
fep 0:5ff20db10a96 17 >>! outside of the FreeRTOS kernel. !<<
fep 0:5ff20db10a96 18 ***************************************************************************
fep 0:5ff20db10a96 19
fep 0:5ff20db10a96 20 FreeRTOS is distributed in the hope that it will be useful, but WITHOUT ANY
fep 0:5ff20db10a96 21 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
fep 0:5ff20db10a96 22 FOR A PARTICULAR PURPOSE. Full license text is available on the following
fep 0:5ff20db10a96 23 link: http://www.freertos.org/a00114.html
fep 0:5ff20db10a96 24
fep 0:5ff20db10a96 25 ***************************************************************************
fep 0:5ff20db10a96 26 * *
fep 0:5ff20db10a96 27 * FreeRTOS provides completely free yet professionally developed, *
fep 0:5ff20db10a96 28 * robust, strictly quality controlled, supported, and cross *
fep 0:5ff20db10a96 29 * platform software that is more than just the market leader, it *
fep 0:5ff20db10a96 30 * is the industry's de facto standard. *
fep 0:5ff20db10a96 31 * *
fep 0:5ff20db10a96 32 * Help yourself get started quickly while simultaneously helping *
fep 0:5ff20db10a96 33 * to support the FreeRTOS project by purchasing a FreeRTOS *
fep 0:5ff20db10a96 34 * tutorial book, reference manual, or both: *
fep 0:5ff20db10a96 35 * http://www.FreeRTOS.org/Documentation *
fep 0:5ff20db10a96 36 * *
fep 0:5ff20db10a96 37 ***************************************************************************
fep 0:5ff20db10a96 38
fep 0:5ff20db10a96 39 http://www.FreeRTOS.org/FAQHelp.html - Having a problem? Start by reading
fep 0:5ff20db10a96 40 the FAQ page "My application does not run, what could be wrong?". Have you
fep 0:5ff20db10a96 41 defined configASSERT()?
fep 0:5ff20db10a96 42
fep 0:5ff20db10a96 43 http://www.FreeRTOS.org/support - In return for receiving this top quality
fep 0:5ff20db10a96 44 embedded software for free we request you assist our global community by
fep 0:5ff20db10a96 45 participating in the support forum.
fep 0:5ff20db10a96 46
fep 0:5ff20db10a96 47 http://www.FreeRTOS.org/training - Investing in training allows your team to
fep 0:5ff20db10a96 48 be as productive as possible as early as possible. Now you can receive
fep 0:5ff20db10a96 49 FreeRTOS training directly from Richard Barry, CEO of Real Time Engineers
fep 0:5ff20db10a96 50 Ltd, and the world's leading authority on the world's leading RTOS.
fep 0:5ff20db10a96 51
fep 0:5ff20db10a96 52 http://www.FreeRTOS.org/plus - A selection of FreeRTOS ecosystem products,
fep 0:5ff20db10a96 53 including FreeRTOS+Trace - an indispensable productivity tool, a DOS
fep 0:5ff20db10a96 54 compatible FAT file system, and our tiny thread aware UDP/IP stack.
fep 0:5ff20db10a96 55
fep 0:5ff20db10a96 56 http://www.FreeRTOS.org/labs - Where new FreeRTOS products go to incubate.
fep 0:5ff20db10a96 57 Come and try FreeRTOS+TCP, our new open source TCP/IP stack for FreeRTOS.
fep 0:5ff20db10a96 58
fep 0:5ff20db10a96 59 http://www.OpenRTOS.com - Real Time Engineers ltd. license FreeRTOS to High
fep 0:5ff20db10a96 60 Integrity Systems ltd. to sell under the OpenRTOS brand. Low cost OpenRTOS
fep 0:5ff20db10a96 61 licenses offer ticketed support, indemnification and commercial middleware.
fep 0:5ff20db10a96 62
fep 0:5ff20db10a96 63 http://www.SafeRTOS.com - High Integrity Systems also provide a safety
fep 0:5ff20db10a96 64 engineered and independently SIL3 certified version for use in safety and
fep 0:5ff20db10a96 65 mission critical applications that require provable dependability.
fep 0:5ff20db10a96 66
fep 0:5ff20db10a96 67 1 tab == 4 spaces!
fep 0:5ff20db10a96 68 */
fep 0:5ff20db10a96 69
fep 0:5ff20db10a96 70
fep 0:5ff20db10a96 71 #ifndef INC_TASK_H
fep 0:5ff20db10a96 72 #define INC_TASK_H
fep 0:5ff20db10a96 73
fep 0:5ff20db10a96 74 #ifndef INC_FREERTOS_H
fep 0:5ff20db10a96 75 #error "include FreeRTOS.h must appear in source files before include task.h"
fep 0:5ff20db10a96 76 #endif
fep 0:5ff20db10a96 77
fep 0:5ff20db10a96 78 #include "list.h"
fep 0:5ff20db10a96 79
fep 0:5ff20db10a96 80 #ifdef __cplusplus
fep 0:5ff20db10a96 81 extern "C" {
fep 0:5ff20db10a96 82 #endif
fep 0:5ff20db10a96 83
fep 0:5ff20db10a96 84 /*-----------------------------------------------------------
fep 0:5ff20db10a96 85 * MACROS AND DEFINITIONS
fep 0:5ff20db10a96 86 *----------------------------------------------------------*/
fep 0:5ff20db10a96 87
fep 0:5ff20db10a96 88 #define tskKERNEL_VERSION_NUMBER "V9.0.0"
fep 0:5ff20db10a96 89 #define tskKERNEL_VERSION_MAJOR 9
fep 0:5ff20db10a96 90 #define tskKERNEL_VERSION_MINOR 0
fep 0:5ff20db10a96 91 #define tskKERNEL_VERSION_BUILD 0
fep 0:5ff20db10a96 92
fep 0:5ff20db10a96 93 /**
fep 0:5ff20db10a96 94 * task. h
fep 0:5ff20db10a96 95 *
fep 0:5ff20db10a96 96 * Type by which tasks are referenced. For example, a call to xTaskCreate
fep 0:5ff20db10a96 97 * returns (via a pointer parameter) an TaskHandle_t variable that can then
fep 0:5ff20db10a96 98 * be used as a parameter to vTaskDelete to delete the task.
fep 0:5ff20db10a96 99 *
fep 0:5ff20db10a96 100 * \defgroup TaskHandle_t TaskHandle_t
fep 0:5ff20db10a96 101 * \ingroup Tasks
fep 0:5ff20db10a96 102 */
fep 0:5ff20db10a96 103 typedef void * TaskHandle_t;
fep 0:5ff20db10a96 104
fep 0:5ff20db10a96 105 /*
fep 0:5ff20db10a96 106 * Defines the prototype to which the application task hook function must
fep 0:5ff20db10a96 107 * conform.
fep 0:5ff20db10a96 108 */
fep 0:5ff20db10a96 109 typedef BaseType_t (*TaskHookFunction_t)( void * );
fep 0:5ff20db10a96 110
fep 0:5ff20db10a96 111 /* Task states returned by eTaskGetState. */
fep 0:5ff20db10a96 112 typedef enum
fep 0:5ff20db10a96 113 {
fep 0:5ff20db10a96 114 eRunning = 0, /* A task is querying the state of itself, so must be running. */
fep 0:5ff20db10a96 115 eReady, /* The task being queried is in a read or pending ready list. */
fep 0:5ff20db10a96 116 eBlocked, /* The task being queried is in the Blocked state. */
fep 0:5ff20db10a96 117 eSuspended, /* The task being queried is in the Suspended state, or is in the Blocked state with an infinite time out. */
fep 0:5ff20db10a96 118 eDeleted, /* The task being queried has been deleted, but its TCB has not yet been freed. */
fep 0:5ff20db10a96 119 eInvalid /* Used as an 'invalid state' value. */
fep 0:5ff20db10a96 120 } eTaskState;
fep 0:5ff20db10a96 121
fep 0:5ff20db10a96 122 /* Actions that can be performed when vTaskNotify() is called. */
fep 0:5ff20db10a96 123 typedef enum
fep 0:5ff20db10a96 124 {
fep 0:5ff20db10a96 125 eNoAction = 0, /* Notify the task without updating its notify value. */
fep 0:5ff20db10a96 126 eSetBits, /* Set bits in the task's notification value. */
fep 0:5ff20db10a96 127 eIncrement, /* Increment the task's notification value. */
fep 0:5ff20db10a96 128 eSetValueWithOverwrite, /* Set the task's notification value to a specific value even if the previous value has not yet been read by the task. */
fep 0:5ff20db10a96 129 eSetValueWithoutOverwrite /* Set the task's notification value if the previous value has been read by the task. */
fep 0:5ff20db10a96 130 } eNotifyAction;
fep 0:5ff20db10a96 131
fep 0:5ff20db10a96 132 /*
fep 0:5ff20db10a96 133 * Used internally only.
fep 0:5ff20db10a96 134 */
fep 0:5ff20db10a96 135 typedef struct xTIME_OUT
fep 0:5ff20db10a96 136 {
fep 0:5ff20db10a96 137 BaseType_t xOverflowCount;
fep 0:5ff20db10a96 138 TickType_t xTimeOnEntering;
fep 0:5ff20db10a96 139 } TimeOut_t;
fep 0:5ff20db10a96 140
fep 0:5ff20db10a96 141 /*
fep 0:5ff20db10a96 142 * Defines the memory ranges allocated to the task when an MPU is used.
fep 0:5ff20db10a96 143 */
fep 0:5ff20db10a96 144 typedef struct xMEMORY_REGION
fep 0:5ff20db10a96 145 {
fep 0:5ff20db10a96 146 void *pvBaseAddress;
fep 0:5ff20db10a96 147 uint32_t ulLengthInBytes;
fep 0:5ff20db10a96 148 uint32_t ulParameters;
fep 0:5ff20db10a96 149 } MemoryRegion_t;
fep 0:5ff20db10a96 150
fep 0:5ff20db10a96 151 /*
fep 0:5ff20db10a96 152 * Parameters required to create an MPU protected task.
fep 0:5ff20db10a96 153 */
fep 0:5ff20db10a96 154 typedef struct xTASK_PARAMETERS
fep 0:5ff20db10a96 155 {
fep 0:5ff20db10a96 156 TaskFunction_t pvTaskCode;
fep 0:5ff20db10a96 157 const char * const pcName; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
fep 0:5ff20db10a96 158 uint16_t usStackDepth;
fep 0:5ff20db10a96 159 void *pvParameters;
fep 0:5ff20db10a96 160 UBaseType_t uxPriority;
fep 0:5ff20db10a96 161 StackType_t *puxStackBuffer;
fep 0:5ff20db10a96 162 MemoryRegion_t xRegions[ portNUM_CONFIGURABLE_REGIONS ];
fep 0:5ff20db10a96 163 } TaskParameters_t;
fep 0:5ff20db10a96 164
fep 0:5ff20db10a96 165 /* Used with the uxTaskGetSystemState() function to return the state of each task
fep 0:5ff20db10a96 166 in the system. */
fep 0:5ff20db10a96 167 typedef struct xTASK_STATUS
fep 0:5ff20db10a96 168 {
fep 0:5ff20db10a96 169 TaskHandle_t xHandle; /* The handle of the task to which the rest of the information in the structure relates. */
fep 0:5ff20db10a96 170 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. */
fep 0:5ff20db10a96 171 UBaseType_t xTaskNumber; /* A number unique to the task. */
fep 0:5ff20db10a96 172 eTaskState eCurrentState; /* The state in which the task existed when the structure was populated. */
fep 0:5ff20db10a96 173 UBaseType_t uxCurrentPriority; /* The priority at which the task was running (may be inherited) when the structure was populated. */
fep 0:5ff20db10a96 174 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. */
fep 0:5ff20db10a96 175 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. */
fep 0:5ff20db10a96 176 StackType_t *pxStackBase; /* Points to the lowest address of the task's stack area. */
fep 0:5ff20db10a96 177 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. */
fep 0:5ff20db10a96 178 } TaskStatus_t;
fep 0:5ff20db10a96 179
fep 0:5ff20db10a96 180 /* Possible return values for eTaskConfirmSleepModeStatus(). */
fep 0:5ff20db10a96 181 typedef enum
fep 0:5ff20db10a96 182 {
fep 0:5ff20db10a96 183 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. */
fep 0:5ff20db10a96 184 eStandardSleep, /* Enter a sleep mode that will not last any longer than the expected idle time. */
fep 0:5ff20db10a96 185 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. */
fep 0:5ff20db10a96 186 } eSleepModeStatus;
fep 0:5ff20db10a96 187
fep 0:5ff20db10a96 188 /**
fep 0:5ff20db10a96 189 * Defines the priority used by the idle task. This must not be modified.
fep 0:5ff20db10a96 190 *
fep 0:5ff20db10a96 191 * \ingroup TaskUtils
fep 0:5ff20db10a96 192 */
fep 0:5ff20db10a96 193 #define tskIDLE_PRIORITY ( ( UBaseType_t ) 0U )
fep 0:5ff20db10a96 194
fep 0:5ff20db10a96 195 /**
fep 0:5ff20db10a96 196 * task. h
fep 0:5ff20db10a96 197 *
fep 0:5ff20db10a96 198 * Macro for forcing a context switch.
fep 0:5ff20db10a96 199 *
fep 0:5ff20db10a96 200 * \defgroup taskYIELD taskYIELD
fep 0:5ff20db10a96 201 * \ingroup SchedulerControl
fep 0:5ff20db10a96 202 */
fep 0:5ff20db10a96 203 #define taskYIELD() portYIELD()
fep 0:5ff20db10a96 204
fep 0:5ff20db10a96 205 /**
fep 0:5ff20db10a96 206 * task. h
fep 0:5ff20db10a96 207 *
fep 0:5ff20db10a96 208 * Macro to mark the start of a critical code region. Preemptive context
fep 0:5ff20db10a96 209 * switches cannot occur when in a critical region.
fep 0:5ff20db10a96 210 *
fep 0:5ff20db10a96 211 * NOTE: This may alter the stack (depending on the portable implementation)
fep 0:5ff20db10a96 212 * so must be used with care!
fep 0:5ff20db10a96 213 *
fep 0:5ff20db10a96 214 * \defgroup taskENTER_CRITICAL taskENTER_CRITICAL
fep 0:5ff20db10a96 215 * \ingroup SchedulerControl
fep 0:5ff20db10a96 216 */
fep 0:5ff20db10a96 217 #define taskENTER_CRITICAL() portENTER_CRITICAL()
fep 0:5ff20db10a96 218 #define taskENTER_CRITICAL_FROM_ISR() portSET_INTERRUPT_MASK_FROM_ISR()
fep 0:5ff20db10a96 219
fep 0:5ff20db10a96 220 /**
fep 0:5ff20db10a96 221 * task. h
fep 0:5ff20db10a96 222 *
fep 0:5ff20db10a96 223 * Macro to mark the end of a critical code region. Preemptive context
fep 0:5ff20db10a96 224 * switches cannot occur when in a critical region.
fep 0:5ff20db10a96 225 *
fep 0:5ff20db10a96 226 * NOTE: This may alter the stack (depending on the portable implementation)
fep 0:5ff20db10a96 227 * so must be used with care!
fep 0:5ff20db10a96 228 *
fep 0:5ff20db10a96 229 * \defgroup taskEXIT_CRITICAL taskEXIT_CRITICAL
fep 0:5ff20db10a96 230 * \ingroup SchedulerControl
fep 0:5ff20db10a96 231 */
fep 0:5ff20db10a96 232 #define taskEXIT_CRITICAL() portEXIT_CRITICAL()
fep 0:5ff20db10a96 233 #define taskEXIT_CRITICAL_FROM_ISR( x ) portCLEAR_INTERRUPT_MASK_FROM_ISR( x )
fep 0:5ff20db10a96 234 /**
fep 0:5ff20db10a96 235 * task. h
fep 0:5ff20db10a96 236 *
fep 0:5ff20db10a96 237 * Macro to disable all maskable interrupts.
fep 0:5ff20db10a96 238 *
fep 0:5ff20db10a96 239 * \defgroup taskDISABLE_INTERRUPTS taskDISABLE_INTERRUPTS
fep 0:5ff20db10a96 240 * \ingroup SchedulerControl
fep 0:5ff20db10a96 241 */
fep 0:5ff20db10a96 242 #define taskDISABLE_INTERRUPTS() portDISABLE_INTERRUPTS()
fep 0:5ff20db10a96 243
fep 0:5ff20db10a96 244 /**
fep 0:5ff20db10a96 245 * task. h
fep 0:5ff20db10a96 246 *
fep 0:5ff20db10a96 247 * Macro to enable microcontroller interrupts.
fep 0:5ff20db10a96 248 *
fep 0:5ff20db10a96 249 * \defgroup taskENABLE_INTERRUPTS taskENABLE_INTERRUPTS
fep 0:5ff20db10a96 250 * \ingroup SchedulerControl
fep 0:5ff20db10a96 251 */
fep 0:5ff20db10a96 252 #define taskENABLE_INTERRUPTS() portENABLE_INTERRUPTS()
fep 0:5ff20db10a96 253
fep 0:5ff20db10a96 254 /* Definitions returned by xTaskGetSchedulerState(). taskSCHEDULER_SUSPENDED is
fep 0:5ff20db10a96 255 0 to generate more optimal code when configASSERT() is defined as the constant
fep 0:5ff20db10a96 256 is used in assert() statements. */
fep 0:5ff20db10a96 257 #define taskSCHEDULER_SUSPENDED ( ( BaseType_t ) 0 )
fep 0:5ff20db10a96 258 #define taskSCHEDULER_NOT_STARTED ( ( BaseType_t ) 1 )
fep 0:5ff20db10a96 259 #define taskSCHEDULER_RUNNING ( ( BaseType_t ) 2 )
fep 0:5ff20db10a96 260
fep 0:5ff20db10a96 261
fep 0:5ff20db10a96 262 /*-----------------------------------------------------------
fep 0:5ff20db10a96 263 * TASK CREATION API
fep 0:5ff20db10a96 264 *----------------------------------------------------------*/
fep 0:5ff20db10a96 265
fep 0:5ff20db10a96 266 /**
fep 0:5ff20db10a96 267 * task. h
fep 0:5ff20db10a96 268 *<pre>
fep 0:5ff20db10a96 269 BaseType_t xTaskCreate(
fep 0:5ff20db10a96 270 TaskFunction_t pvTaskCode,
fep 0:5ff20db10a96 271 const char * const pcName,
fep 0:5ff20db10a96 272 uint16_t usStackDepth,
fep 0:5ff20db10a96 273 void *pvParameters,
fep 0:5ff20db10a96 274 UBaseType_t uxPriority,
fep 0:5ff20db10a96 275 TaskHandle_t *pvCreatedTask
fep 0:5ff20db10a96 276 );</pre>
fep 0:5ff20db10a96 277 *
fep 0:5ff20db10a96 278 * Create a new task and add it to the list of tasks that are ready to run.
fep 0:5ff20db10a96 279 *
fep 0:5ff20db10a96 280 * Internally, within the FreeRTOS implementation, tasks use two blocks of
fep 0:5ff20db10a96 281 * memory. The first block is used to hold the task's data structures. The
fep 0:5ff20db10a96 282 * second block is used by the task as its stack. If a task is created using
fep 0:5ff20db10a96 283 * xTaskCreate() then both blocks of memory are automatically dynamically
fep 0:5ff20db10a96 284 * allocated inside the xTaskCreate() function. (see
fep 0:5ff20db10a96 285 * http://www.freertos.org/a00111.html). If a task is created using
fep 0:5ff20db10a96 286 * xTaskCreateStatic() then the application writer must provide the required
fep 0:5ff20db10a96 287 * memory. xTaskCreateStatic() therefore allows a task to be created without
fep 0:5ff20db10a96 288 * using any dynamic memory allocation.
fep 0:5ff20db10a96 289 *
fep 0:5ff20db10a96 290 * See xTaskCreateStatic() for a version that does not use any dynamic memory
fep 0:5ff20db10a96 291 * allocation.
fep 0:5ff20db10a96 292 *
fep 0:5ff20db10a96 293 * xTaskCreate() can only be used to create a task that has unrestricted
fep 0:5ff20db10a96 294 * access to the entire microcontroller memory map. Systems that include MPU
fep 0:5ff20db10a96 295 * support can alternatively create an MPU constrained task using
fep 0:5ff20db10a96 296 * xTaskCreateRestricted().
fep 0:5ff20db10a96 297 *
fep 0:5ff20db10a96 298 * @param pvTaskCode Pointer to the task entry function. Tasks
fep 0:5ff20db10a96 299 * must be implemented to never return (i.e. continuous loop).
fep 0:5ff20db10a96 300 *
fep 0:5ff20db10a96 301 * @param pcName A descriptive name for the task. This is mainly used to
fep 0:5ff20db10a96 302 * facilitate debugging. Max length defined by configMAX_TASK_NAME_LEN - default
fep 0:5ff20db10a96 303 * is 16.
fep 0:5ff20db10a96 304 *
fep 0:5ff20db10a96 305 * @param usStackDepth The size of the task stack specified as the number of
fep 0:5ff20db10a96 306 * variables the stack can hold - not the number of bytes. For example, if
fep 0:5ff20db10a96 307 * the stack is 16 bits wide and usStackDepth is defined as 100, 200 bytes
fep 0:5ff20db10a96 308 * will be allocated for stack storage.
fep 0:5ff20db10a96 309 *
fep 0:5ff20db10a96 310 * @param pvParameters Pointer that will be used as the parameter for the task
fep 0:5ff20db10a96 311 * being created.
fep 0:5ff20db10a96 312 *
fep 0:5ff20db10a96 313 * @param uxPriority The priority at which the task should run. Systems that
fep 0:5ff20db10a96 314 * include MPU support can optionally create tasks in a privileged (system)
fep 0:5ff20db10a96 315 * mode by setting bit portPRIVILEGE_BIT of the priority parameter. For
fep 0:5ff20db10a96 316 * example, to create a privileged task at priority 2 the uxPriority parameter
fep 0:5ff20db10a96 317 * should be set to ( 2 | portPRIVILEGE_BIT ).
fep 0:5ff20db10a96 318 *
fep 0:5ff20db10a96 319 * @param pvCreatedTask Used to pass back a handle by which the created task
fep 0:5ff20db10a96 320 * can be referenced.
fep 0:5ff20db10a96 321 *
fep 0:5ff20db10a96 322 * @return pdPASS if the task was successfully created and added to a ready
fep 0:5ff20db10a96 323 * list, otherwise an error code defined in the file projdefs.h
fep 0:5ff20db10a96 324 *
fep 0:5ff20db10a96 325 * Example usage:
fep 0:5ff20db10a96 326 <pre>
fep 0:5ff20db10a96 327 // Task to be created.
fep 0:5ff20db10a96 328 void vTaskCode( void * pvParameters )
fep 0:5ff20db10a96 329 {
fep 0:5ff20db10a96 330 for( ;; )
fep 0:5ff20db10a96 331 {
fep 0:5ff20db10a96 332 // Task code goes here.
fep 0:5ff20db10a96 333 }
fep 0:5ff20db10a96 334 }
fep 0:5ff20db10a96 335
fep 0:5ff20db10a96 336 // Function that creates a task.
fep 0:5ff20db10a96 337 void vOtherFunction( void )
fep 0:5ff20db10a96 338 {
fep 0:5ff20db10a96 339 static uint8_t ucParameterToPass;
fep 0:5ff20db10a96 340 TaskHandle_t xHandle = NULL;
fep 0:5ff20db10a96 341
fep 0:5ff20db10a96 342 // Create the task, storing the handle. Note that the passed parameter ucParameterToPass
fep 0:5ff20db10a96 343 // must exist for the lifetime of the task, so in this case is declared static. If it was just an
fep 0:5ff20db10a96 344 // an automatic stack variable it might no longer exist, or at least have been corrupted, by the time
fep 0:5ff20db10a96 345 // the new task attempts to access it.
fep 0:5ff20db10a96 346 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, &ucParameterToPass, tskIDLE_PRIORITY, &xHandle );
fep 0:5ff20db10a96 347 configASSERT( xHandle );
fep 0:5ff20db10a96 348
fep 0:5ff20db10a96 349 // Use the handle to delete the task.
fep 0:5ff20db10a96 350 if( xHandle != NULL )
fep 0:5ff20db10a96 351 {
fep 0:5ff20db10a96 352 vTaskDelete( xHandle );
fep 0:5ff20db10a96 353 }
fep 0:5ff20db10a96 354 }
fep 0:5ff20db10a96 355 </pre>
fep 0:5ff20db10a96 356 * \defgroup xTaskCreate xTaskCreate
fep 0:5ff20db10a96 357 * \ingroup Tasks
fep 0:5ff20db10a96 358 */
fep 0:5ff20db10a96 359 #if( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
fep 0:5ff20db10a96 360 BaseType_t xTaskCreate( TaskFunction_t pxTaskCode,
fep 0:5ff20db10a96 361 const char * const pcName,
fep 0:5ff20db10a96 362 const uint16_t usStackDepth,
fep 0:5ff20db10a96 363 void * const pvParameters,
fep 0:5ff20db10a96 364 UBaseType_t uxPriority,
fep 0:5ff20db10a96 365 TaskHandle_t * const pxCreatedTask ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
fep 0:5ff20db10a96 366 #endif
fep 0:5ff20db10a96 367
fep 0:5ff20db10a96 368 /**
fep 0:5ff20db10a96 369 * task. h
fep 0:5ff20db10a96 370 *<pre>
fep 0:5ff20db10a96 371 TaskHandle_t xTaskCreateStatic( TaskFunction_t pvTaskCode,
fep 0:5ff20db10a96 372 const char * const pcName,
fep 0:5ff20db10a96 373 uint32_t ulStackDepth,
fep 0:5ff20db10a96 374 void *pvParameters,
fep 0:5ff20db10a96 375 UBaseType_t uxPriority,
fep 0:5ff20db10a96 376 StackType_t *pxStackBuffer,
fep 0:5ff20db10a96 377 StaticTask_t *pxTaskBuffer );</pre>
fep 0:5ff20db10a96 378 *
fep 0:5ff20db10a96 379 * Create a new task and add it to the list of tasks that are ready to run.
fep 0:5ff20db10a96 380 *
fep 0:5ff20db10a96 381 * Internally, within the FreeRTOS implementation, tasks use two blocks of
fep 0:5ff20db10a96 382 * memory. The first block is used to hold the task's data structures. The
fep 0:5ff20db10a96 383 * second block is used by the task as its stack. If a task is created using
fep 0:5ff20db10a96 384 * xTaskCreate() then both blocks of memory are automatically dynamically
fep 0:5ff20db10a96 385 * allocated inside the xTaskCreate() function. (see
fep 0:5ff20db10a96 386 * http://www.freertos.org/a00111.html). If a task is created using
fep 0:5ff20db10a96 387 * xTaskCreateStatic() then the application writer must provide the required
fep 0:5ff20db10a96 388 * memory. xTaskCreateStatic() therefore allows a task to be created without
fep 0:5ff20db10a96 389 * using any dynamic memory allocation.
fep 0:5ff20db10a96 390 *
fep 0:5ff20db10a96 391 * @param pvTaskCode Pointer to the task entry function. Tasks
fep 0:5ff20db10a96 392 * must be implemented to never return (i.e. continuous loop).
fep 0:5ff20db10a96 393 *
fep 0:5ff20db10a96 394 * @param pcName A descriptive name for the task. This is mainly used to
fep 0:5ff20db10a96 395 * facilitate debugging. The maximum length of the string is defined by
fep 0:5ff20db10a96 396 * configMAX_TASK_NAME_LEN in FreeRTOSConfig.h.
fep 0:5ff20db10a96 397 *
fep 0:5ff20db10a96 398 * @param ulStackDepth The size of the task stack specified as the number of
fep 0:5ff20db10a96 399 * variables the stack can hold - not the number of bytes. For example, if
fep 0:5ff20db10a96 400 * the stack is 32-bits wide and ulStackDepth is defined as 100 then 400 bytes
fep 0:5ff20db10a96 401 * will be allocated for stack storage.
fep 0:5ff20db10a96 402 *
fep 0:5ff20db10a96 403 * @param pvParameters Pointer that will be used as the parameter for the task
fep 0:5ff20db10a96 404 * being created.
fep 0:5ff20db10a96 405 *
fep 0:5ff20db10a96 406 * @param uxPriority The priority at which the task will run.
fep 0:5ff20db10a96 407 *
fep 0:5ff20db10a96 408 * @param pxStackBuffer Must point to a StackType_t array that has at least
fep 0:5ff20db10a96 409 * ulStackDepth indexes - the array will then be used as the task's stack,
fep 0:5ff20db10a96 410 * removing the need for the stack to be allocated dynamically.
fep 0:5ff20db10a96 411 *
fep 0:5ff20db10a96 412 * @param pxTaskBuffer Must point to a variable of type StaticTask_t, which will
fep 0:5ff20db10a96 413 * then be used to hold the task's data structures, removing the need for the
fep 0:5ff20db10a96 414 * memory to be allocated dynamically.
fep 0:5ff20db10a96 415 *
fep 0:5ff20db10a96 416 * @return If neither pxStackBuffer or pxTaskBuffer are NULL, then the task will
fep 0:5ff20db10a96 417 * be created and pdPASS is returned. If either pxStackBuffer or pxTaskBuffer
fep 0:5ff20db10a96 418 * are NULL then the task will not be created and
fep 0:5ff20db10a96 419 * errCOULD_NOT_ALLOCATE_REQUIRED_MEMORY is returned.
fep 0:5ff20db10a96 420 *
fep 0:5ff20db10a96 421 * Example usage:
fep 0:5ff20db10a96 422 <pre>
fep 0:5ff20db10a96 423
fep 0:5ff20db10a96 424 // Dimensions the buffer that the task being created will use as its stack.
fep 0:5ff20db10a96 425 // NOTE: This is the number of words the stack will hold, not the number of
fep 0:5ff20db10a96 426 // bytes. For example, if each stack item is 32-bits, and this is set to 100,
fep 0:5ff20db10a96 427 // then 400 bytes (100 * 32-bits) will be allocated.
fep 0:5ff20db10a96 428 #define STACK_SIZE 200
fep 0:5ff20db10a96 429
fep 0:5ff20db10a96 430 // Structure that will hold the TCB of the task being created.
fep 0:5ff20db10a96 431 StaticTask_t xTaskBuffer;
fep 0:5ff20db10a96 432
fep 0:5ff20db10a96 433 // Buffer that the task being created will use as its stack. Note this is
fep 0:5ff20db10a96 434 // an array of StackType_t variables. The size of StackType_t is dependent on
fep 0:5ff20db10a96 435 // the RTOS port.
fep 0:5ff20db10a96 436 StackType_t xStack[ STACK_SIZE ];
fep 0:5ff20db10a96 437
fep 0:5ff20db10a96 438 // Function that implements the task being created.
fep 0:5ff20db10a96 439 void vTaskCode( void * pvParameters )
fep 0:5ff20db10a96 440 {
fep 0:5ff20db10a96 441 // The parameter value is expected to be 1 as 1 is passed in the
fep 0:5ff20db10a96 442 // pvParameters value in the call to xTaskCreateStatic().
fep 0:5ff20db10a96 443 configASSERT( ( uint32_t ) pvParameters == 1UL );
fep 0:5ff20db10a96 444
fep 0:5ff20db10a96 445 for( ;; )
fep 0:5ff20db10a96 446 {
fep 0:5ff20db10a96 447 // Task code goes here.
fep 0:5ff20db10a96 448 }
fep 0:5ff20db10a96 449 }
fep 0:5ff20db10a96 450
fep 0:5ff20db10a96 451 // Function that creates a task.
fep 0:5ff20db10a96 452 void vOtherFunction( void )
fep 0:5ff20db10a96 453 {
fep 0:5ff20db10a96 454 TaskHandle_t xHandle = NULL;
fep 0:5ff20db10a96 455
fep 0:5ff20db10a96 456 // Create the task without using any dynamic memory allocation.
fep 0:5ff20db10a96 457 xHandle = xTaskCreateStatic(
fep 0:5ff20db10a96 458 vTaskCode, // Function that implements the task.
fep 0:5ff20db10a96 459 "NAME", // Text name for the task.
fep 0:5ff20db10a96 460 STACK_SIZE, // Stack size in words, not bytes.
fep 0:5ff20db10a96 461 ( void * ) 1, // Parameter passed into the task.
fep 0:5ff20db10a96 462 tskIDLE_PRIORITY,// Priority at which the task is created.
fep 0:5ff20db10a96 463 xStack, // Array to use as the task's stack.
fep 0:5ff20db10a96 464 &xTaskBuffer ); // Variable to hold the task's data structure.
fep 0:5ff20db10a96 465
fep 0:5ff20db10a96 466 // puxStackBuffer and pxTaskBuffer were not NULL, so the task will have
fep 0:5ff20db10a96 467 // been created, and xHandle will be the task's handle. Use the handle
fep 0:5ff20db10a96 468 // to suspend the task.
fep 0:5ff20db10a96 469 vTaskSuspend( xHandle );
fep 0:5ff20db10a96 470 }
fep 0:5ff20db10a96 471 </pre>
fep 0:5ff20db10a96 472 * \defgroup xTaskCreateStatic xTaskCreateStatic
fep 0:5ff20db10a96 473 * \ingroup Tasks
fep 0:5ff20db10a96 474 */
fep 0:5ff20db10a96 475 #if( configSUPPORT_STATIC_ALLOCATION == 1 )
fep 0:5ff20db10a96 476 TaskHandle_t xTaskCreateStatic( TaskFunction_t pxTaskCode,
fep 0:5ff20db10a96 477 const char * const pcName,
fep 0:5ff20db10a96 478 const uint32_t ulStackDepth,
fep 0:5ff20db10a96 479 void * const pvParameters,
fep 0:5ff20db10a96 480 UBaseType_t uxPriority,
fep 0:5ff20db10a96 481 StackType_t * const puxStackBuffer,
fep 0:5ff20db10a96 482 StaticTask_t * const pxTaskBuffer ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
fep 0:5ff20db10a96 483 #endif /* configSUPPORT_STATIC_ALLOCATION */
fep 0:5ff20db10a96 484
fep 0:5ff20db10a96 485 /**
fep 0:5ff20db10a96 486 * task. h
fep 0:5ff20db10a96 487 *<pre>
fep 0:5ff20db10a96 488 BaseType_t xTaskCreateRestricted( TaskParameters_t *pxTaskDefinition, TaskHandle_t *pxCreatedTask );</pre>
fep 0:5ff20db10a96 489 *
fep 0:5ff20db10a96 490 * xTaskCreateRestricted() should only be used in systems that include an MPU
fep 0:5ff20db10a96 491 * implementation.
fep 0:5ff20db10a96 492 *
fep 0:5ff20db10a96 493 * Create a new task and add it to the list of tasks that are ready to run.
fep 0:5ff20db10a96 494 * The function parameters define the memory regions and associated access
fep 0:5ff20db10a96 495 * permissions allocated to the task.
fep 0:5ff20db10a96 496 *
fep 0:5ff20db10a96 497 * @param pxTaskDefinition Pointer to a structure that contains a member
fep 0:5ff20db10a96 498 * for each of the normal xTaskCreate() parameters (see the xTaskCreate() API
fep 0:5ff20db10a96 499 * documentation) plus an optional stack buffer and the memory region
fep 0:5ff20db10a96 500 * definitions.
fep 0:5ff20db10a96 501 *
fep 0:5ff20db10a96 502 * @param pxCreatedTask Used to pass back a handle by which the created task
fep 0:5ff20db10a96 503 * can be referenced.
fep 0:5ff20db10a96 504 *
fep 0:5ff20db10a96 505 * @return pdPASS if the task was successfully created and added to a ready
fep 0:5ff20db10a96 506 * list, otherwise an error code defined in the file projdefs.h
fep 0:5ff20db10a96 507 *
fep 0:5ff20db10a96 508 * Example usage:
fep 0:5ff20db10a96 509 <pre>
fep 0:5ff20db10a96 510 // Create an TaskParameters_t structure that defines the task to be created.
fep 0:5ff20db10a96 511 static const TaskParameters_t xCheckTaskParameters =
fep 0:5ff20db10a96 512 {
fep 0:5ff20db10a96 513 vATask, // pvTaskCode - the function that implements the task.
fep 0:5ff20db10a96 514 "ATask", // pcName - just a text name for the task to assist debugging.
fep 0:5ff20db10a96 515 100, // usStackDepth - the stack size DEFINED IN WORDS.
fep 0:5ff20db10a96 516 NULL, // pvParameters - passed into the task function as the function parameters.
fep 0:5ff20db10a96 517 ( 1UL | portPRIVILEGE_BIT ),// uxPriority - task priority, set the portPRIVILEGE_BIT if the task should run in a privileged state.
fep 0:5ff20db10a96 518 cStackBuffer,// puxStackBuffer - the buffer to be used as the task stack.
fep 0:5ff20db10a96 519
fep 0:5ff20db10a96 520 // xRegions - Allocate up to three separate memory regions for access by
fep 0:5ff20db10a96 521 // the task, with appropriate access permissions. Different processors have
fep 0:5ff20db10a96 522 // different memory alignment requirements - refer to the FreeRTOS documentation
fep 0:5ff20db10a96 523 // for full information.
fep 0:5ff20db10a96 524 {
fep 0:5ff20db10a96 525 // Base address Length Parameters
fep 0:5ff20db10a96 526 { cReadWriteArray, 32, portMPU_REGION_READ_WRITE },
fep 0:5ff20db10a96 527 { cReadOnlyArray, 32, portMPU_REGION_READ_ONLY },
fep 0:5ff20db10a96 528 { cPrivilegedOnlyAccessArray, 128, portMPU_REGION_PRIVILEGED_READ_WRITE }
fep 0:5ff20db10a96 529 }
fep 0:5ff20db10a96 530 };
fep 0:5ff20db10a96 531
fep 0:5ff20db10a96 532 int main( void )
fep 0:5ff20db10a96 533 {
fep 0:5ff20db10a96 534 TaskHandle_t xHandle;
fep 0:5ff20db10a96 535
fep 0:5ff20db10a96 536 // Create a task from the const structure defined above. The task handle
fep 0:5ff20db10a96 537 // is requested (the second parameter is not NULL) but in this case just for
fep 0:5ff20db10a96 538 // demonstration purposes as its not actually used.
fep 0:5ff20db10a96 539 xTaskCreateRestricted( &xRegTest1Parameters, &xHandle );
fep 0:5ff20db10a96 540
fep 0:5ff20db10a96 541 // Start the scheduler.
fep 0:5ff20db10a96 542 vTaskStartScheduler();
fep 0:5ff20db10a96 543
fep 0:5ff20db10a96 544 // Will only get here if there was insufficient memory to create the idle
fep 0:5ff20db10a96 545 // and/or timer task.
fep 0:5ff20db10a96 546 for( ;; );
fep 0:5ff20db10a96 547 }
fep 0:5ff20db10a96 548 </pre>
fep 0:5ff20db10a96 549 * \defgroup xTaskCreateRestricted xTaskCreateRestricted
fep 0:5ff20db10a96 550 * \ingroup Tasks
fep 0:5ff20db10a96 551 */
fep 0:5ff20db10a96 552 #if( portUSING_MPU_WRAPPERS == 1 )
fep 0:5ff20db10a96 553 BaseType_t xTaskCreateRestricted( const TaskParameters_t * const pxTaskDefinition, TaskHandle_t *pxCreatedTask ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 554 #endif
fep 0:5ff20db10a96 555
fep 0:5ff20db10a96 556 /**
fep 0:5ff20db10a96 557 * task. h
fep 0:5ff20db10a96 558 *<pre>
fep 0:5ff20db10a96 559 void vTaskAllocateMPURegions( TaskHandle_t xTask, const MemoryRegion_t * const pxRegions );</pre>
fep 0:5ff20db10a96 560 *
fep 0:5ff20db10a96 561 * Memory regions are assigned to a restricted task when the task is created by
fep 0:5ff20db10a96 562 * a call to xTaskCreateRestricted(). These regions can be redefined using
fep 0:5ff20db10a96 563 * vTaskAllocateMPURegions().
fep 0:5ff20db10a96 564 *
fep 0:5ff20db10a96 565 * @param xTask The handle of the task being updated.
fep 0:5ff20db10a96 566 *
fep 0:5ff20db10a96 567 * @param xRegions A pointer to an MemoryRegion_t structure that contains the
fep 0:5ff20db10a96 568 * new memory region definitions.
fep 0:5ff20db10a96 569 *
fep 0:5ff20db10a96 570 * Example usage:
fep 0:5ff20db10a96 571 <pre>
fep 0:5ff20db10a96 572 // Define an array of MemoryRegion_t structures that configures an MPU region
fep 0:5ff20db10a96 573 // allowing read/write access for 1024 bytes starting at the beginning of the
fep 0:5ff20db10a96 574 // ucOneKByte array. The other two of the maximum 3 definable regions are
fep 0:5ff20db10a96 575 // unused so set to zero.
fep 0:5ff20db10a96 576 static const MemoryRegion_t xAltRegions[ portNUM_CONFIGURABLE_REGIONS ] =
fep 0:5ff20db10a96 577 {
fep 0:5ff20db10a96 578 // Base address Length Parameters
fep 0:5ff20db10a96 579 { ucOneKByte, 1024, portMPU_REGION_READ_WRITE },
fep 0:5ff20db10a96 580 { 0, 0, 0 },
fep 0:5ff20db10a96 581 { 0, 0, 0 }
fep 0:5ff20db10a96 582 };
fep 0:5ff20db10a96 583
fep 0:5ff20db10a96 584 void vATask( void *pvParameters )
fep 0:5ff20db10a96 585 {
fep 0:5ff20db10a96 586 // This task was created such that it has access to certain regions of
fep 0:5ff20db10a96 587 // memory as defined by the MPU configuration. At some point it is
fep 0:5ff20db10a96 588 // desired that these MPU regions are replaced with that defined in the
fep 0:5ff20db10a96 589 // xAltRegions const struct above. Use a call to vTaskAllocateMPURegions()
fep 0:5ff20db10a96 590 // for this purpose. NULL is used as the task handle to indicate that this
fep 0:5ff20db10a96 591 // function should modify the MPU regions of the calling task.
fep 0:5ff20db10a96 592 vTaskAllocateMPURegions( NULL, xAltRegions );
fep 0:5ff20db10a96 593
fep 0:5ff20db10a96 594 // Now the task can continue its function, but from this point on can only
fep 0:5ff20db10a96 595 // access its stack and the ucOneKByte array (unless any other statically
fep 0:5ff20db10a96 596 // defined or shared regions have been declared elsewhere).
fep 0:5ff20db10a96 597 }
fep 0:5ff20db10a96 598 </pre>
fep 0:5ff20db10a96 599 * \defgroup xTaskCreateRestricted xTaskCreateRestricted
fep 0:5ff20db10a96 600 * \ingroup Tasks
fep 0:5ff20db10a96 601 */
fep 0:5ff20db10a96 602 void vTaskAllocateMPURegions( TaskHandle_t xTask, const MemoryRegion_t * const pxRegions ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 603
fep 0:5ff20db10a96 604 /**
fep 0:5ff20db10a96 605 * task. h
fep 0:5ff20db10a96 606 * <pre>void vTaskDelete( TaskHandle_t xTask );</pre>
fep 0:5ff20db10a96 607 *
fep 0:5ff20db10a96 608 * INCLUDE_vTaskDelete must be defined as 1 for this function to be available.
fep 0:5ff20db10a96 609 * See the configuration section for more information.
fep 0:5ff20db10a96 610 *
fep 0:5ff20db10a96 611 * Remove a task from the RTOS real time kernel's management. The task being
fep 0:5ff20db10a96 612 * deleted will be removed from all ready, blocked, suspended and event lists.
fep 0:5ff20db10a96 613 *
fep 0:5ff20db10a96 614 * NOTE: The idle task is responsible for freeing the kernel allocated
fep 0:5ff20db10a96 615 * memory from tasks that have been deleted. It is therefore important that
fep 0:5ff20db10a96 616 * the idle task is not starved of microcontroller processing time if your
fep 0:5ff20db10a96 617 * application makes any calls to vTaskDelete (). Memory allocated by the
fep 0:5ff20db10a96 618 * task code is not automatically freed, and should be freed before the task
fep 0:5ff20db10a96 619 * is deleted.
fep 0:5ff20db10a96 620 *
fep 0:5ff20db10a96 621 * See the demo application file death.c for sample code that utilises
fep 0:5ff20db10a96 622 * vTaskDelete ().
fep 0:5ff20db10a96 623 *
fep 0:5ff20db10a96 624 * @param xTask The handle of the task to be deleted. Passing NULL will
fep 0:5ff20db10a96 625 * cause the calling task to be deleted.
fep 0:5ff20db10a96 626 *
fep 0:5ff20db10a96 627 * Example usage:
fep 0:5ff20db10a96 628 <pre>
fep 0:5ff20db10a96 629 void vOtherFunction( void )
fep 0:5ff20db10a96 630 {
fep 0:5ff20db10a96 631 TaskHandle_t xHandle;
fep 0:5ff20db10a96 632
fep 0:5ff20db10a96 633 // Create the task, storing the handle.
fep 0:5ff20db10a96 634 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
fep 0:5ff20db10a96 635
fep 0:5ff20db10a96 636 // Use the handle to delete the task.
fep 0:5ff20db10a96 637 vTaskDelete( xHandle );
fep 0:5ff20db10a96 638 }
fep 0:5ff20db10a96 639 </pre>
fep 0:5ff20db10a96 640 * \defgroup vTaskDelete vTaskDelete
fep 0:5ff20db10a96 641 * \ingroup Tasks
fep 0:5ff20db10a96 642 */
fep 0:5ff20db10a96 643 void vTaskDelete( TaskHandle_t xTaskToDelete ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 644
fep 0:5ff20db10a96 645 /*-----------------------------------------------------------
fep 0:5ff20db10a96 646 * TASK CONTROL API
fep 0:5ff20db10a96 647 *----------------------------------------------------------*/
fep 0:5ff20db10a96 648
fep 0:5ff20db10a96 649 /**
fep 0:5ff20db10a96 650 * task. h
fep 0:5ff20db10a96 651 * <pre>void vTaskDelay( const TickType_t xTicksToDelay );</pre>
fep 0:5ff20db10a96 652 *
fep 0:5ff20db10a96 653 * Delay a task for a given number of ticks. The actual time that the
fep 0:5ff20db10a96 654 * task remains blocked depends on the tick rate. The constant
fep 0:5ff20db10a96 655 * portTICK_PERIOD_MS can be used to calculate real time from the tick
fep 0:5ff20db10a96 656 * rate - with the resolution of one tick period.
fep 0:5ff20db10a96 657 *
fep 0:5ff20db10a96 658 * INCLUDE_vTaskDelay must be defined as 1 for this function to be available.
fep 0:5ff20db10a96 659 * See the configuration section for more information.
fep 0:5ff20db10a96 660 *
fep 0:5ff20db10a96 661 *
fep 0:5ff20db10a96 662 * vTaskDelay() specifies a time at which the task wishes to unblock relative to
fep 0:5ff20db10a96 663 * the time at which vTaskDelay() is called. For example, specifying a block
fep 0:5ff20db10a96 664 * period of 100 ticks will cause the task to unblock 100 ticks after
fep 0:5ff20db10a96 665 * vTaskDelay() is called. vTaskDelay() does not therefore provide a good method
fep 0:5ff20db10a96 666 * of controlling the frequency of a periodic task as the path taken through the
fep 0:5ff20db10a96 667 * code, as well as other task and interrupt activity, will effect the frequency
fep 0:5ff20db10a96 668 * at which vTaskDelay() gets called and therefore the time at which the task
fep 0:5ff20db10a96 669 * next executes. See vTaskDelayUntil() for an alternative API function designed
fep 0:5ff20db10a96 670 * to facilitate fixed frequency execution. It does this by specifying an
fep 0:5ff20db10a96 671 * absolute time (rather than a relative time) at which the calling task should
fep 0:5ff20db10a96 672 * unblock.
fep 0:5ff20db10a96 673 *
fep 0:5ff20db10a96 674 * @param xTicksToDelay The amount of time, in tick periods, that
fep 0:5ff20db10a96 675 * the calling task should block.
fep 0:5ff20db10a96 676 *
fep 0:5ff20db10a96 677 * Example usage:
fep 0:5ff20db10a96 678
fep 0:5ff20db10a96 679 void vTaskFunction( void * pvParameters )
fep 0:5ff20db10a96 680 {
fep 0:5ff20db10a96 681 // Block for 500ms.
fep 0:5ff20db10a96 682 const TickType_t xDelay = 500 / portTICK_PERIOD_MS;
fep 0:5ff20db10a96 683
fep 0:5ff20db10a96 684 for( ;; )
fep 0:5ff20db10a96 685 {
fep 0:5ff20db10a96 686 // Simply toggle the LED every 500ms, blocking between each toggle.
fep 0:5ff20db10a96 687 vToggleLED();
fep 0:5ff20db10a96 688 vTaskDelay( xDelay );
fep 0:5ff20db10a96 689 }
fep 0:5ff20db10a96 690 }
fep 0:5ff20db10a96 691
fep 0:5ff20db10a96 692 * \defgroup vTaskDelay vTaskDelay
fep 0:5ff20db10a96 693 * \ingroup TaskCtrl
fep 0:5ff20db10a96 694 */
fep 0:5ff20db10a96 695 void vTaskDelay( const TickType_t xTicksToDelay ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 696
fep 0:5ff20db10a96 697 /**
fep 0:5ff20db10a96 698 * task. h
fep 0:5ff20db10a96 699 * <pre>void vTaskDelayUntil( TickType_t *pxPreviousWakeTime, const TickType_t xTimeIncrement );</pre>
fep 0:5ff20db10a96 700 *
fep 0:5ff20db10a96 701 * INCLUDE_vTaskDelayUntil must be defined as 1 for this function to be available.
fep 0:5ff20db10a96 702 * See the configuration section for more information.
fep 0:5ff20db10a96 703 *
fep 0:5ff20db10a96 704 * Delay a task until a specified time. This function can be used by periodic
fep 0:5ff20db10a96 705 * tasks to ensure a constant execution frequency.
fep 0:5ff20db10a96 706 *
fep 0:5ff20db10a96 707 * This function differs from vTaskDelay () in one important aspect: vTaskDelay () will
fep 0:5ff20db10a96 708 * cause a task to block for the specified number of ticks from the time vTaskDelay () is
fep 0:5ff20db10a96 709 * called. It is therefore difficult to use vTaskDelay () by itself to generate a fixed
fep 0:5ff20db10a96 710 * execution frequency as the time between a task starting to execute and that task
fep 0:5ff20db10a96 711 * calling vTaskDelay () may not be fixed [the task may take a different path though the
fep 0:5ff20db10a96 712 * code between calls, or may get interrupted or preempted a different number of times
fep 0:5ff20db10a96 713 * each time it executes].
fep 0:5ff20db10a96 714 *
fep 0:5ff20db10a96 715 * Whereas vTaskDelay () specifies a wake time relative to the time at which the function
fep 0:5ff20db10a96 716 * is called, vTaskDelayUntil () specifies the absolute (exact) time at which it wishes to
fep 0:5ff20db10a96 717 * unblock.
fep 0:5ff20db10a96 718 *
fep 0:5ff20db10a96 719 * The constant portTICK_PERIOD_MS can be used to calculate real time from the tick
fep 0:5ff20db10a96 720 * rate - with the resolution of one tick period.
fep 0:5ff20db10a96 721 *
fep 0:5ff20db10a96 722 * @param pxPreviousWakeTime Pointer to a variable that holds the time at which the
fep 0:5ff20db10a96 723 * task was last unblocked. The variable must be initialised with the current time
fep 0:5ff20db10a96 724 * prior to its first use (see the example below). Following this the variable is
fep 0:5ff20db10a96 725 * automatically updated within vTaskDelayUntil ().
fep 0:5ff20db10a96 726 *
fep 0:5ff20db10a96 727 * @param xTimeIncrement The cycle time period. The task will be unblocked at
fep 0:5ff20db10a96 728 * time *pxPreviousWakeTime + xTimeIncrement. Calling vTaskDelayUntil with the
fep 0:5ff20db10a96 729 * same xTimeIncrement parameter value will cause the task to execute with
fep 0:5ff20db10a96 730 * a fixed interface period.
fep 0:5ff20db10a96 731 *
fep 0:5ff20db10a96 732 * Example usage:
fep 0:5ff20db10a96 733 <pre>
fep 0:5ff20db10a96 734 // Perform an action every 10 ticks.
fep 0:5ff20db10a96 735 void vTaskFunction( void * pvParameters )
fep 0:5ff20db10a96 736 {
fep 0:5ff20db10a96 737 TickType_t xLastWakeTime;
fep 0:5ff20db10a96 738 const TickType_t xFrequency = 10;
fep 0:5ff20db10a96 739
fep 0:5ff20db10a96 740 // Initialise the xLastWakeTime variable with the current time.
fep 0:5ff20db10a96 741 xLastWakeTime = xTaskGetTickCount ();
fep 0:5ff20db10a96 742 for( ;; )
fep 0:5ff20db10a96 743 {
fep 0:5ff20db10a96 744 // Wait for the next cycle.
fep 0:5ff20db10a96 745 vTaskDelayUntil( &xLastWakeTime, xFrequency );
fep 0:5ff20db10a96 746
fep 0:5ff20db10a96 747 // Perform action here.
fep 0:5ff20db10a96 748 }
fep 0:5ff20db10a96 749 }
fep 0:5ff20db10a96 750 </pre>
fep 0:5ff20db10a96 751 * \defgroup vTaskDelayUntil vTaskDelayUntil
fep 0:5ff20db10a96 752 * \ingroup TaskCtrl
fep 0:5ff20db10a96 753 */
fep 0:5ff20db10a96 754 void vTaskDelayUntil( TickType_t * const pxPreviousWakeTime, const TickType_t xTimeIncrement ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 755
fep 0:5ff20db10a96 756 /**
fep 0:5ff20db10a96 757 * task. h
fep 0:5ff20db10a96 758 * <pre>BaseType_t xTaskAbortDelay( TaskHandle_t xTask );</pre>
fep 0:5ff20db10a96 759 *
fep 0:5ff20db10a96 760 * INCLUDE_xTaskAbortDelay must be defined as 1 in FreeRTOSConfig.h for this
fep 0:5ff20db10a96 761 * function to be available.
fep 0:5ff20db10a96 762 *
fep 0:5ff20db10a96 763 * A task will enter the Blocked state when it is waiting for an event. The
fep 0:5ff20db10a96 764 * event it is waiting for can be a temporal event (waiting for a time), such
fep 0:5ff20db10a96 765 * as when vTaskDelay() is called, or an event on an object, such as when
fep 0:5ff20db10a96 766 * xQueueReceive() or ulTaskNotifyTake() is called. If the handle of a task
fep 0:5ff20db10a96 767 * that is in the Blocked state is used in a call to xTaskAbortDelay() then the
fep 0:5ff20db10a96 768 * task will leave the Blocked state, and return from whichever function call
fep 0:5ff20db10a96 769 * placed the task into the Blocked state.
fep 0:5ff20db10a96 770 *
fep 0:5ff20db10a96 771 * @param xTask The handle of the task to remove from the Blocked state.
fep 0:5ff20db10a96 772 *
fep 0:5ff20db10a96 773 * @return If the task referenced by xTask was not in the Blocked state then
fep 0:5ff20db10a96 774 * pdFAIL is returned. Otherwise pdPASS is returned.
fep 0:5ff20db10a96 775 *
fep 0:5ff20db10a96 776 * \defgroup xTaskAbortDelay xTaskAbortDelay
fep 0:5ff20db10a96 777 * \ingroup TaskCtrl
fep 0:5ff20db10a96 778 */
fep 0:5ff20db10a96 779 BaseType_t xTaskAbortDelay( TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 780
fep 0:5ff20db10a96 781 /**
fep 0:5ff20db10a96 782 * task. h
fep 0:5ff20db10a96 783 * <pre>UBaseType_t uxTaskPriorityGet( TaskHandle_t xTask );</pre>
fep 0:5ff20db10a96 784 *
fep 0:5ff20db10a96 785 * INCLUDE_uxTaskPriorityGet must be defined as 1 for this function to be available.
fep 0:5ff20db10a96 786 * See the configuration section for more information.
fep 0:5ff20db10a96 787 *
fep 0:5ff20db10a96 788 * Obtain the priority of any task.
fep 0:5ff20db10a96 789 *
fep 0:5ff20db10a96 790 * @param xTask Handle of the task to be queried. Passing a NULL
fep 0:5ff20db10a96 791 * handle results in the priority of the calling task being returned.
fep 0:5ff20db10a96 792 *
fep 0:5ff20db10a96 793 * @return The priority of xTask.
fep 0:5ff20db10a96 794 *
fep 0:5ff20db10a96 795 * Example usage:
fep 0:5ff20db10a96 796 <pre>
fep 0:5ff20db10a96 797 void vAFunction( void )
fep 0:5ff20db10a96 798 {
fep 0:5ff20db10a96 799 TaskHandle_t xHandle;
fep 0:5ff20db10a96 800
fep 0:5ff20db10a96 801 // Create a task, storing the handle.
fep 0:5ff20db10a96 802 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
fep 0:5ff20db10a96 803
fep 0:5ff20db10a96 804 // ...
fep 0:5ff20db10a96 805
fep 0:5ff20db10a96 806 // Use the handle to obtain the priority of the created task.
fep 0:5ff20db10a96 807 // It was created with tskIDLE_PRIORITY, but may have changed
fep 0:5ff20db10a96 808 // it itself.
fep 0:5ff20db10a96 809 if( uxTaskPriorityGet( xHandle ) != tskIDLE_PRIORITY )
fep 0:5ff20db10a96 810 {
fep 0:5ff20db10a96 811 // The task has changed it's priority.
fep 0:5ff20db10a96 812 }
fep 0:5ff20db10a96 813
fep 0:5ff20db10a96 814 // ...
fep 0:5ff20db10a96 815
fep 0:5ff20db10a96 816 // Is our priority higher than the created task?
fep 0:5ff20db10a96 817 if( uxTaskPriorityGet( xHandle ) < uxTaskPriorityGet( NULL ) )
fep 0:5ff20db10a96 818 {
fep 0:5ff20db10a96 819 // Our priority (obtained using NULL handle) is higher.
fep 0:5ff20db10a96 820 }
fep 0:5ff20db10a96 821 }
fep 0:5ff20db10a96 822 </pre>
fep 0:5ff20db10a96 823 * \defgroup uxTaskPriorityGet uxTaskPriorityGet
fep 0:5ff20db10a96 824 * \ingroup TaskCtrl
fep 0:5ff20db10a96 825 */
fep 0:5ff20db10a96 826 UBaseType_t uxTaskPriorityGet( TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 827
fep 0:5ff20db10a96 828 /**
fep 0:5ff20db10a96 829 * task. h
fep 0:5ff20db10a96 830 * <pre>UBaseType_t uxTaskPriorityGetFromISR( TaskHandle_t xTask );</pre>
fep 0:5ff20db10a96 831 *
fep 0:5ff20db10a96 832 * A version of uxTaskPriorityGet() that can be used from an ISR.
fep 0:5ff20db10a96 833 */
fep 0:5ff20db10a96 834 UBaseType_t uxTaskPriorityGetFromISR( TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 835
fep 0:5ff20db10a96 836 /**
fep 0:5ff20db10a96 837 * task. h
fep 0:5ff20db10a96 838 * <pre>eTaskState eTaskGetState( TaskHandle_t xTask );</pre>
fep 0:5ff20db10a96 839 *
fep 0:5ff20db10a96 840 * INCLUDE_eTaskGetState must be defined as 1 for this function to be available.
fep 0:5ff20db10a96 841 * See the configuration section for more information.
fep 0:5ff20db10a96 842 *
fep 0:5ff20db10a96 843 * Obtain the state of any task. States are encoded by the eTaskState
fep 0:5ff20db10a96 844 * enumerated type.
fep 0:5ff20db10a96 845 *
fep 0:5ff20db10a96 846 * @param xTask Handle of the task to be queried.
fep 0:5ff20db10a96 847 *
fep 0:5ff20db10a96 848 * @return The state of xTask at the time the function was called. Note the
fep 0:5ff20db10a96 849 * state of the task might change between the function being called, and the
fep 0:5ff20db10a96 850 * functions return value being tested by the calling task.
fep 0:5ff20db10a96 851 */
fep 0:5ff20db10a96 852 eTaskState eTaskGetState( TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 853
fep 0:5ff20db10a96 854 /**
fep 0:5ff20db10a96 855 * task. h
fep 0:5ff20db10a96 856 * <pre>void vTaskGetInfo( TaskHandle_t xTask, TaskStatus_t *pxTaskStatus, BaseType_t xGetFreeStackSpace, eTaskState eState );</pre>
fep 0:5ff20db10a96 857 *
fep 0:5ff20db10a96 858 * configUSE_TRACE_FACILITY must be defined as 1 for this function to be
fep 0:5ff20db10a96 859 * available. See the configuration section for more information.
fep 0:5ff20db10a96 860 *
fep 0:5ff20db10a96 861 * Populates a TaskStatus_t structure with information about a task.
fep 0:5ff20db10a96 862 *
fep 0:5ff20db10a96 863 * @param xTask Handle of the task being queried. If xTask is NULL then
fep 0:5ff20db10a96 864 * information will be returned about the calling task.
fep 0:5ff20db10a96 865 *
fep 0:5ff20db10a96 866 * @param pxTaskStatus A pointer to the TaskStatus_t structure that will be
fep 0:5ff20db10a96 867 * filled with information about the task referenced by the handle passed using
fep 0:5ff20db10a96 868 * the xTask parameter.
fep 0:5ff20db10a96 869 *
fep 0:5ff20db10a96 870 * @xGetFreeStackSpace The TaskStatus_t structure contains a member to report
fep 0:5ff20db10a96 871 * the stack high water mark of the task being queried. Calculating the stack
fep 0:5ff20db10a96 872 * high water mark takes a relatively long time, and can make the system
fep 0:5ff20db10a96 873 * temporarily unresponsive - so the xGetFreeStackSpace parameter is provided to
fep 0:5ff20db10a96 874 * allow the high water mark checking to be skipped. The high watermark value
fep 0:5ff20db10a96 875 * will only be written to the TaskStatus_t structure if xGetFreeStackSpace is
fep 0:5ff20db10a96 876 * not set to pdFALSE;
fep 0:5ff20db10a96 877 *
fep 0:5ff20db10a96 878 * @param eState The TaskStatus_t structure contains a member to report the
fep 0:5ff20db10a96 879 * state of the task being queried. Obtaining the task state is not as fast as
fep 0:5ff20db10a96 880 * a simple assignment - so the eState parameter is provided to allow the state
fep 0:5ff20db10a96 881 * information to be omitted from the TaskStatus_t structure. To obtain state
fep 0:5ff20db10a96 882 * information then set eState to eInvalid - otherwise the value passed in
fep 0:5ff20db10a96 883 * eState will be reported as the task state in the TaskStatus_t structure.
fep 0:5ff20db10a96 884 *
fep 0:5ff20db10a96 885 * Example usage:
fep 0:5ff20db10a96 886 <pre>
fep 0:5ff20db10a96 887 void vAFunction( void )
fep 0:5ff20db10a96 888 {
fep 0:5ff20db10a96 889 TaskHandle_t xHandle;
fep 0:5ff20db10a96 890 TaskStatus_t xTaskDetails;
fep 0:5ff20db10a96 891
fep 0:5ff20db10a96 892 // Obtain the handle of a task from its name.
fep 0:5ff20db10a96 893 xHandle = xTaskGetHandle( "Task_Name" );
fep 0:5ff20db10a96 894
fep 0:5ff20db10a96 895 // Check the handle is not NULL.
fep 0:5ff20db10a96 896 configASSERT( xHandle );
fep 0:5ff20db10a96 897
fep 0:5ff20db10a96 898 // Use the handle to obtain further information about the task.
fep 0:5ff20db10a96 899 vTaskGetInfo( xHandle,
fep 0:5ff20db10a96 900 &xTaskDetails,
fep 0:5ff20db10a96 901 pdTRUE, // Include the high water mark in xTaskDetails.
fep 0:5ff20db10a96 902 eInvalid ); // Include the task state in xTaskDetails.
fep 0:5ff20db10a96 903 }
fep 0:5ff20db10a96 904 </pre>
fep 0:5ff20db10a96 905 * \defgroup vTaskGetInfo vTaskGetInfo
fep 0:5ff20db10a96 906 * \ingroup TaskCtrl
fep 0:5ff20db10a96 907 */
fep 0:5ff20db10a96 908 void vTaskGetInfo( TaskHandle_t xTask, TaskStatus_t *pxTaskStatus, BaseType_t xGetFreeStackSpace, eTaskState eState ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 909
fep 0:5ff20db10a96 910 /**
fep 0:5ff20db10a96 911 * task. h
fep 0:5ff20db10a96 912 * <pre>void vTaskPrioritySet( TaskHandle_t xTask, UBaseType_t uxNewPriority );</pre>
fep 0:5ff20db10a96 913 *
fep 0:5ff20db10a96 914 * INCLUDE_vTaskPrioritySet must be defined as 1 for this function to be available.
fep 0:5ff20db10a96 915 * See the configuration section for more information.
fep 0:5ff20db10a96 916 *
fep 0:5ff20db10a96 917 * Set the priority of any task.
fep 0:5ff20db10a96 918 *
fep 0:5ff20db10a96 919 * A context switch will occur before the function returns if the priority
fep 0:5ff20db10a96 920 * being set is higher than the currently executing task.
fep 0:5ff20db10a96 921 *
fep 0:5ff20db10a96 922 * @param xTask Handle to the task for which the priority is being set.
fep 0:5ff20db10a96 923 * Passing a NULL handle results in the priority of the calling task being set.
fep 0:5ff20db10a96 924 *
fep 0:5ff20db10a96 925 * @param uxNewPriority The priority to which the task will be set.
fep 0:5ff20db10a96 926 *
fep 0:5ff20db10a96 927 * Example usage:
fep 0:5ff20db10a96 928 <pre>
fep 0:5ff20db10a96 929 void vAFunction( void )
fep 0:5ff20db10a96 930 {
fep 0:5ff20db10a96 931 TaskHandle_t xHandle;
fep 0:5ff20db10a96 932
fep 0:5ff20db10a96 933 // Create a task, storing the handle.
fep 0:5ff20db10a96 934 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
fep 0:5ff20db10a96 935
fep 0:5ff20db10a96 936 // ...
fep 0:5ff20db10a96 937
fep 0:5ff20db10a96 938 // Use the handle to raise the priority of the created task.
fep 0:5ff20db10a96 939 vTaskPrioritySet( xHandle, tskIDLE_PRIORITY + 1 );
fep 0:5ff20db10a96 940
fep 0:5ff20db10a96 941 // ...
fep 0:5ff20db10a96 942
fep 0:5ff20db10a96 943 // Use a NULL handle to raise our priority to the same value.
fep 0:5ff20db10a96 944 vTaskPrioritySet( NULL, tskIDLE_PRIORITY + 1 );
fep 0:5ff20db10a96 945 }
fep 0:5ff20db10a96 946 </pre>
fep 0:5ff20db10a96 947 * \defgroup vTaskPrioritySet vTaskPrioritySet
fep 0:5ff20db10a96 948 * \ingroup TaskCtrl
fep 0:5ff20db10a96 949 */
fep 0:5ff20db10a96 950 void vTaskPrioritySet( TaskHandle_t xTask, UBaseType_t uxNewPriority ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 951
fep 0:5ff20db10a96 952 /**
fep 0:5ff20db10a96 953 * task. h
fep 0:5ff20db10a96 954 * <pre>void vTaskSuspend( TaskHandle_t xTaskToSuspend );</pre>
fep 0:5ff20db10a96 955 *
fep 0:5ff20db10a96 956 * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available.
fep 0:5ff20db10a96 957 * See the configuration section for more information.
fep 0:5ff20db10a96 958 *
fep 0:5ff20db10a96 959 * Suspend any task. When suspended a task will never get any microcontroller
fep 0:5ff20db10a96 960 * processing time, no matter what its priority.
fep 0:5ff20db10a96 961 *
fep 0:5ff20db10a96 962 * Calls to vTaskSuspend are not accumulative -
fep 0:5ff20db10a96 963 * i.e. calling vTaskSuspend () twice on the same task still only requires one
fep 0:5ff20db10a96 964 * call to vTaskResume () to ready the suspended task.
fep 0:5ff20db10a96 965 *
fep 0:5ff20db10a96 966 * @param xTaskToSuspend Handle to the task being suspended. Passing a NULL
fep 0:5ff20db10a96 967 * handle will cause the calling task to be suspended.
fep 0:5ff20db10a96 968 *
fep 0:5ff20db10a96 969 * Example usage:
fep 0:5ff20db10a96 970 <pre>
fep 0:5ff20db10a96 971 void vAFunction( void )
fep 0:5ff20db10a96 972 {
fep 0:5ff20db10a96 973 TaskHandle_t xHandle;
fep 0:5ff20db10a96 974
fep 0:5ff20db10a96 975 // Create a task, storing the handle.
fep 0:5ff20db10a96 976 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
fep 0:5ff20db10a96 977
fep 0:5ff20db10a96 978 // ...
fep 0:5ff20db10a96 979
fep 0:5ff20db10a96 980 // Use the handle to suspend the created task.
fep 0:5ff20db10a96 981 vTaskSuspend( xHandle );
fep 0:5ff20db10a96 982
fep 0:5ff20db10a96 983 // ...
fep 0:5ff20db10a96 984
fep 0:5ff20db10a96 985 // The created task will not run during this period, unless
fep 0:5ff20db10a96 986 // another task calls vTaskResume( xHandle ).
fep 0:5ff20db10a96 987
fep 0:5ff20db10a96 988 //...
fep 0:5ff20db10a96 989
fep 0:5ff20db10a96 990
fep 0:5ff20db10a96 991 // Suspend ourselves.
fep 0:5ff20db10a96 992 vTaskSuspend( NULL );
fep 0:5ff20db10a96 993
fep 0:5ff20db10a96 994 // We cannot get here unless another task calls vTaskResume
fep 0:5ff20db10a96 995 // with our handle as the parameter.
fep 0:5ff20db10a96 996 }
fep 0:5ff20db10a96 997 </pre>
fep 0:5ff20db10a96 998 * \defgroup vTaskSuspend vTaskSuspend
fep 0:5ff20db10a96 999 * \ingroup TaskCtrl
fep 0:5ff20db10a96 1000 */
fep 0:5ff20db10a96 1001 void vTaskSuspend( TaskHandle_t xTaskToSuspend ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 1002
fep 0:5ff20db10a96 1003 /**
fep 0:5ff20db10a96 1004 * task. h
fep 0:5ff20db10a96 1005 * <pre>void vTaskResume( TaskHandle_t xTaskToResume );</pre>
fep 0:5ff20db10a96 1006 *
fep 0:5ff20db10a96 1007 * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available.
fep 0:5ff20db10a96 1008 * See the configuration section for more information.
fep 0:5ff20db10a96 1009 *
fep 0:5ff20db10a96 1010 * Resumes a suspended task.
fep 0:5ff20db10a96 1011 *
fep 0:5ff20db10a96 1012 * A task that has been suspended by one or more calls to vTaskSuspend ()
fep 0:5ff20db10a96 1013 * will be made available for running again by a single call to
fep 0:5ff20db10a96 1014 * vTaskResume ().
fep 0:5ff20db10a96 1015 *
fep 0:5ff20db10a96 1016 * @param xTaskToResume Handle to the task being readied.
fep 0:5ff20db10a96 1017 *
fep 0:5ff20db10a96 1018 * Example usage:
fep 0:5ff20db10a96 1019 <pre>
fep 0:5ff20db10a96 1020 void vAFunction( void )
fep 0:5ff20db10a96 1021 {
fep 0:5ff20db10a96 1022 TaskHandle_t xHandle;
fep 0:5ff20db10a96 1023
fep 0:5ff20db10a96 1024 // Create a task, storing the handle.
fep 0:5ff20db10a96 1025 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
fep 0:5ff20db10a96 1026
fep 0:5ff20db10a96 1027 // ...
fep 0:5ff20db10a96 1028
fep 0:5ff20db10a96 1029 // Use the handle to suspend the created task.
fep 0:5ff20db10a96 1030 vTaskSuspend( xHandle );
fep 0:5ff20db10a96 1031
fep 0:5ff20db10a96 1032 // ...
fep 0:5ff20db10a96 1033
fep 0:5ff20db10a96 1034 // The created task will not run during this period, unless
fep 0:5ff20db10a96 1035 // another task calls vTaskResume( xHandle ).
fep 0:5ff20db10a96 1036
fep 0:5ff20db10a96 1037 //...
fep 0:5ff20db10a96 1038
fep 0:5ff20db10a96 1039
fep 0:5ff20db10a96 1040 // Resume the suspended task ourselves.
fep 0:5ff20db10a96 1041 vTaskResume( xHandle );
fep 0:5ff20db10a96 1042
fep 0:5ff20db10a96 1043 // The created task will once again get microcontroller processing
fep 0:5ff20db10a96 1044 // time in accordance with its priority within the system.
fep 0:5ff20db10a96 1045 }
fep 0:5ff20db10a96 1046 </pre>
fep 0:5ff20db10a96 1047 * \defgroup vTaskResume vTaskResume
fep 0:5ff20db10a96 1048 * \ingroup TaskCtrl
fep 0:5ff20db10a96 1049 */
fep 0:5ff20db10a96 1050 void vTaskResume( TaskHandle_t xTaskToResume ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 1051
fep 0:5ff20db10a96 1052 /**
fep 0:5ff20db10a96 1053 * task. h
fep 0:5ff20db10a96 1054 * <pre>void xTaskResumeFromISR( TaskHandle_t xTaskToResume );</pre>
fep 0:5ff20db10a96 1055 *
fep 0:5ff20db10a96 1056 * INCLUDE_xTaskResumeFromISR must be defined as 1 for this function to be
fep 0:5ff20db10a96 1057 * available. See the configuration section for more information.
fep 0:5ff20db10a96 1058 *
fep 0:5ff20db10a96 1059 * An implementation of vTaskResume() that can be called from within an ISR.
fep 0:5ff20db10a96 1060 *
fep 0:5ff20db10a96 1061 * A task that has been suspended by one or more calls to vTaskSuspend ()
fep 0:5ff20db10a96 1062 * will be made available for running again by a single call to
fep 0:5ff20db10a96 1063 * xTaskResumeFromISR ().
fep 0:5ff20db10a96 1064 *
fep 0:5ff20db10a96 1065 * xTaskResumeFromISR() should not be used to synchronise a task with an
fep 0:5ff20db10a96 1066 * interrupt if there is a chance that the interrupt could arrive prior to the
fep 0:5ff20db10a96 1067 * task being suspended - as this can lead to interrupts being missed. Use of a
fep 0:5ff20db10a96 1068 * semaphore as a synchronisation mechanism would avoid this eventuality.
fep 0:5ff20db10a96 1069 *
fep 0:5ff20db10a96 1070 * @param xTaskToResume Handle to the task being readied.
fep 0:5ff20db10a96 1071 *
fep 0:5ff20db10a96 1072 * @return pdTRUE if resuming the task should result in a context switch,
fep 0:5ff20db10a96 1073 * otherwise pdFALSE. This is used by the ISR to determine if a context switch
fep 0:5ff20db10a96 1074 * may be required following the ISR.
fep 0:5ff20db10a96 1075 *
fep 0:5ff20db10a96 1076 * \defgroup vTaskResumeFromISR vTaskResumeFromISR
fep 0:5ff20db10a96 1077 * \ingroup TaskCtrl
fep 0:5ff20db10a96 1078 */
fep 0:5ff20db10a96 1079 BaseType_t xTaskResumeFromISR( TaskHandle_t xTaskToResume ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 1080
fep 0:5ff20db10a96 1081 /*-----------------------------------------------------------
fep 0:5ff20db10a96 1082 * SCHEDULER CONTROL
fep 0:5ff20db10a96 1083 *----------------------------------------------------------*/
fep 0:5ff20db10a96 1084
fep 0:5ff20db10a96 1085 /**
fep 0:5ff20db10a96 1086 * task. h
fep 0:5ff20db10a96 1087 * <pre>void vTaskStartScheduler( void );</pre>
fep 0:5ff20db10a96 1088 *
fep 0:5ff20db10a96 1089 * Starts the real time kernel tick processing. After calling the kernel
fep 0:5ff20db10a96 1090 * has control over which tasks are executed and when.
fep 0:5ff20db10a96 1091 *
fep 0:5ff20db10a96 1092 * See the demo application file main.c for an example of creating
fep 0:5ff20db10a96 1093 * tasks and starting the kernel.
fep 0:5ff20db10a96 1094 *
fep 0:5ff20db10a96 1095 * Example usage:
fep 0:5ff20db10a96 1096 <pre>
fep 0:5ff20db10a96 1097 void vAFunction( void )
fep 0:5ff20db10a96 1098 {
fep 0:5ff20db10a96 1099 // Create at least one task before starting the kernel.
fep 0:5ff20db10a96 1100 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL );
fep 0:5ff20db10a96 1101
fep 0:5ff20db10a96 1102 // Start the real time kernel with preemption.
fep 0:5ff20db10a96 1103 vTaskStartScheduler ();
fep 0:5ff20db10a96 1104
fep 0:5ff20db10a96 1105 // Will not get here unless a task calls vTaskEndScheduler ()
fep 0:5ff20db10a96 1106 }
fep 0:5ff20db10a96 1107 </pre>
fep 0:5ff20db10a96 1108 *
fep 0:5ff20db10a96 1109 * \defgroup vTaskStartScheduler vTaskStartScheduler
fep 0:5ff20db10a96 1110 * \ingroup SchedulerControl
fep 0:5ff20db10a96 1111 */
fep 0:5ff20db10a96 1112 void vTaskStartScheduler( void ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 1113
fep 0:5ff20db10a96 1114 /**
fep 0:5ff20db10a96 1115 * task. h
fep 0:5ff20db10a96 1116 * <pre>void vTaskEndScheduler( void );</pre>
fep 0:5ff20db10a96 1117 *
fep 0:5ff20db10a96 1118 * NOTE: At the time of writing only the x86 real mode port, which runs on a PC
fep 0:5ff20db10a96 1119 * in place of DOS, implements this function.
fep 0:5ff20db10a96 1120 *
fep 0:5ff20db10a96 1121 * Stops the real time kernel tick. All created tasks will be automatically
fep 0:5ff20db10a96 1122 * deleted and multitasking (either preemptive or cooperative) will
fep 0:5ff20db10a96 1123 * stop. Execution then resumes from the point where vTaskStartScheduler ()
fep 0:5ff20db10a96 1124 * was called, as if vTaskStartScheduler () had just returned.
fep 0:5ff20db10a96 1125 *
fep 0:5ff20db10a96 1126 * See the demo application file main. c in the demo/PC directory for an
fep 0:5ff20db10a96 1127 * example that uses vTaskEndScheduler ().
fep 0:5ff20db10a96 1128 *
fep 0:5ff20db10a96 1129 * vTaskEndScheduler () requires an exit function to be defined within the
fep 0:5ff20db10a96 1130 * portable layer (see vPortEndScheduler () in port. c for the PC port). This
fep 0:5ff20db10a96 1131 * performs hardware specific operations such as stopping the kernel tick.
fep 0:5ff20db10a96 1132 *
fep 0:5ff20db10a96 1133 * vTaskEndScheduler () will cause all of the resources allocated by the
fep 0:5ff20db10a96 1134 * kernel to be freed - but will not free resources allocated by application
fep 0:5ff20db10a96 1135 * tasks.
fep 0:5ff20db10a96 1136 *
fep 0:5ff20db10a96 1137 * Example usage:
fep 0:5ff20db10a96 1138 <pre>
fep 0:5ff20db10a96 1139 void vTaskCode( void * pvParameters )
fep 0:5ff20db10a96 1140 {
fep 0:5ff20db10a96 1141 for( ;; )
fep 0:5ff20db10a96 1142 {
fep 0:5ff20db10a96 1143 // Task code goes here.
fep 0:5ff20db10a96 1144
fep 0:5ff20db10a96 1145 // At some point we want to end the real time kernel processing
fep 0:5ff20db10a96 1146 // so call ...
fep 0:5ff20db10a96 1147 vTaskEndScheduler ();
fep 0:5ff20db10a96 1148 }
fep 0:5ff20db10a96 1149 }
fep 0:5ff20db10a96 1150
fep 0:5ff20db10a96 1151 void vAFunction( void )
fep 0:5ff20db10a96 1152 {
fep 0:5ff20db10a96 1153 // Create at least one task before starting the kernel.
fep 0:5ff20db10a96 1154 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL );
fep 0:5ff20db10a96 1155
fep 0:5ff20db10a96 1156 // Start the real time kernel with preemption.
fep 0:5ff20db10a96 1157 vTaskStartScheduler ();
fep 0:5ff20db10a96 1158
fep 0:5ff20db10a96 1159 // Will only get here when the vTaskCode () task has called
fep 0:5ff20db10a96 1160 // vTaskEndScheduler (). When we get here we are back to single task
fep 0:5ff20db10a96 1161 // execution.
fep 0:5ff20db10a96 1162 }
fep 0:5ff20db10a96 1163 </pre>
fep 0:5ff20db10a96 1164 *
fep 0:5ff20db10a96 1165 * \defgroup vTaskEndScheduler vTaskEndScheduler
fep 0:5ff20db10a96 1166 * \ingroup SchedulerControl
fep 0:5ff20db10a96 1167 */
fep 0:5ff20db10a96 1168 void vTaskEndScheduler( void ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 1169
fep 0:5ff20db10a96 1170 /**
fep 0:5ff20db10a96 1171 * task. h
fep 0:5ff20db10a96 1172 * <pre>void vTaskSuspendAll( void );</pre>
fep 0:5ff20db10a96 1173 *
fep 0:5ff20db10a96 1174 * Suspends the scheduler without disabling interrupts. Context switches will
fep 0:5ff20db10a96 1175 * not occur while the scheduler is suspended.
fep 0:5ff20db10a96 1176 *
fep 0:5ff20db10a96 1177 * After calling vTaskSuspendAll () the calling task will continue to execute
fep 0:5ff20db10a96 1178 * without risk of being swapped out until a call to xTaskResumeAll () has been
fep 0:5ff20db10a96 1179 * made.
fep 0:5ff20db10a96 1180 *
fep 0:5ff20db10a96 1181 * API functions that have the potential to cause a context switch (for example,
fep 0:5ff20db10a96 1182 * vTaskDelayUntil(), xQueueSend(), etc.) must not be called while the scheduler
fep 0:5ff20db10a96 1183 * is suspended.
fep 0:5ff20db10a96 1184 *
fep 0:5ff20db10a96 1185 * Example usage:
fep 0:5ff20db10a96 1186 <pre>
fep 0:5ff20db10a96 1187 void vTask1( void * pvParameters )
fep 0:5ff20db10a96 1188 {
fep 0:5ff20db10a96 1189 for( ;; )
fep 0:5ff20db10a96 1190 {
fep 0:5ff20db10a96 1191 // Task code goes here.
fep 0:5ff20db10a96 1192
fep 0:5ff20db10a96 1193 // ...
fep 0:5ff20db10a96 1194
fep 0:5ff20db10a96 1195 // At some point the task wants to perform a long operation during
fep 0:5ff20db10a96 1196 // which it does not want to get swapped out. It cannot use
fep 0:5ff20db10a96 1197 // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the
fep 0:5ff20db10a96 1198 // operation may cause interrupts to be missed - including the
fep 0:5ff20db10a96 1199 // ticks.
fep 0:5ff20db10a96 1200
fep 0:5ff20db10a96 1201 // Prevent the real time kernel swapping out the task.
fep 0:5ff20db10a96 1202 vTaskSuspendAll ();
fep 0:5ff20db10a96 1203
fep 0:5ff20db10a96 1204 // Perform the operation here. There is no need to use critical
fep 0:5ff20db10a96 1205 // sections as we have all the microcontroller processing time.
fep 0:5ff20db10a96 1206 // During this time interrupts will still operate and the kernel
fep 0:5ff20db10a96 1207 // tick count will be maintained.
fep 0:5ff20db10a96 1208
fep 0:5ff20db10a96 1209 // ...
fep 0:5ff20db10a96 1210
fep 0:5ff20db10a96 1211 // The operation is complete. Restart the kernel.
fep 0:5ff20db10a96 1212 xTaskResumeAll ();
fep 0:5ff20db10a96 1213 }
fep 0:5ff20db10a96 1214 }
fep 0:5ff20db10a96 1215 </pre>
fep 0:5ff20db10a96 1216 * \defgroup vTaskSuspendAll vTaskSuspendAll
fep 0:5ff20db10a96 1217 * \ingroup SchedulerControl
fep 0:5ff20db10a96 1218 */
fep 0:5ff20db10a96 1219 void vTaskSuspendAll( void ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 1220
fep 0:5ff20db10a96 1221 /**
fep 0:5ff20db10a96 1222 * task. h
fep 0:5ff20db10a96 1223 * <pre>BaseType_t xTaskResumeAll( void );</pre>
fep 0:5ff20db10a96 1224 *
fep 0:5ff20db10a96 1225 * Resumes scheduler activity after it was suspended by a call to
fep 0:5ff20db10a96 1226 * vTaskSuspendAll().
fep 0:5ff20db10a96 1227 *
fep 0:5ff20db10a96 1228 * xTaskResumeAll() only resumes the scheduler. It does not unsuspend tasks
fep 0:5ff20db10a96 1229 * that were previously suspended by a call to vTaskSuspend().
fep 0:5ff20db10a96 1230 *
fep 0:5ff20db10a96 1231 * @return If resuming the scheduler caused a context switch then pdTRUE is
fep 0:5ff20db10a96 1232 * returned, otherwise pdFALSE is returned.
fep 0:5ff20db10a96 1233 *
fep 0:5ff20db10a96 1234 * Example usage:
fep 0:5ff20db10a96 1235 <pre>
fep 0:5ff20db10a96 1236 void vTask1( void * pvParameters )
fep 0:5ff20db10a96 1237 {
fep 0:5ff20db10a96 1238 for( ;; )
fep 0:5ff20db10a96 1239 {
fep 0:5ff20db10a96 1240 // Task code goes here.
fep 0:5ff20db10a96 1241
fep 0:5ff20db10a96 1242 // ...
fep 0:5ff20db10a96 1243
fep 0:5ff20db10a96 1244 // At some point the task wants to perform a long operation during
fep 0:5ff20db10a96 1245 // which it does not want to get swapped out. It cannot use
fep 0:5ff20db10a96 1246 // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the
fep 0:5ff20db10a96 1247 // operation may cause interrupts to be missed - including the
fep 0:5ff20db10a96 1248 // ticks.
fep 0:5ff20db10a96 1249
fep 0:5ff20db10a96 1250 // Prevent the real time kernel swapping out the task.
fep 0:5ff20db10a96 1251 vTaskSuspendAll ();
fep 0:5ff20db10a96 1252
fep 0:5ff20db10a96 1253 // Perform the operation here. There is no need to use critical
fep 0:5ff20db10a96 1254 // sections as we have all the microcontroller processing time.
fep 0:5ff20db10a96 1255 // During this time interrupts will still operate and the real
fep 0:5ff20db10a96 1256 // time kernel tick count will be maintained.
fep 0:5ff20db10a96 1257
fep 0:5ff20db10a96 1258 // ...
fep 0:5ff20db10a96 1259
fep 0:5ff20db10a96 1260 // The operation is complete. Restart the kernel. We want to force
fep 0:5ff20db10a96 1261 // a context switch - but there is no point if resuming the scheduler
fep 0:5ff20db10a96 1262 // caused a context switch already.
fep 0:5ff20db10a96 1263 if( !xTaskResumeAll () )
fep 0:5ff20db10a96 1264 {
fep 0:5ff20db10a96 1265 taskYIELD ();
fep 0:5ff20db10a96 1266 }
fep 0:5ff20db10a96 1267 }
fep 0:5ff20db10a96 1268 }
fep 0:5ff20db10a96 1269 </pre>
fep 0:5ff20db10a96 1270 * \defgroup xTaskResumeAll xTaskResumeAll
fep 0:5ff20db10a96 1271 * \ingroup SchedulerControl
fep 0:5ff20db10a96 1272 */
fep 0:5ff20db10a96 1273 BaseType_t xTaskResumeAll( void ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 1274
fep 0:5ff20db10a96 1275 /*-----------------------------------------------------------
fep 0:5ff20db10a96 1276 * TASK UTILITIES
fep 0:5ff20db10a96 1277 *----------------------------------------------------------*/
fep 0:5ff20db10a96 1278
fep 0:5ff20db10a96 1279 /**
fep 0:5ff20db10a96 1280 * task. h
fep 0:5ff20db10a96 1281 * <PRE>TickType_t xTaskGetTickCount( void );</PRE>
fep 0:5ff20db10a96 1282 *
fep 0:5ff20db10a96 1283 * @return The count of ticks since vTaskStartScheduler was called.
fep 0:5ff20db10a96 1284 *
fep 0:5ff20db10a96 1285 * \defgroup xTaskGetTickCount xTaskGetTickCount
fep 0:5ff20db10a96 1286 * \ingroup TaskUtils
fep 0:5ff20db10a96 1287 */
fep 0:5ff20db10a96 1288 TickType_t xTaskGetTickCount( void ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 1289
fep 0:5ff20db10a96 1290 /**
fep 0:5ff20db10a96 1291 * task. h
fep 0:5ff20db10a96 1292 * <PRE>TickType_t xTaskGetTickCountFromISR( void );</PRE>
fep 0:5ff20db10a96 1293 *
fep 0:5ff20db10a96 1294 * @return The count of ticks since vTaskStartScheduler was called.
fep 0:5ff20db10a96 1295 *
fep 0:5ff20db10a96 1296 * This is a version of xTaskGetTickCount() that is safe to be called from an
fep 0:5ff20db10a96 1297 * ISR - provided that TickType_t is the natural word size of the
fep 0:5ff20db10a96 1298 * microcontroller being used or interrupt nesting is either not supported or
fep 0:5ff20db10a96 1299 * not being used.
fep 0:5ff20db10a96 1300 *
fep 0:5ff20db10a96 1301 * \defgroup xTaskGetTickCountFromISR xTaskGetTickCountFromISR
fep 0:5ff20db10a96 1302 * \ingroup TaskUtils
fep 0:5ff20db10a96 1303 */
fep 0:5ff20db10a96 1304 TickType_t xTaskGetTickCountFromISR( void ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 1305
fep 0:5ff20db10a96 1306 /**
fep 0:5ff20db10a96 1307 * task. h
fep 0:5ff20db10a96 1308 * <PRE>uint16_t uxTaskGetNumberOfTasks( void );</PRE>
fep 0:5ff20db10a96 1309 *
fep 0:5ff20db10a96 1310 * @return The number of tasks that the real time kernel is currently managing.
fep 0:5ff20db10a96 1311 * This includes all ready, blocked and suspended tasks. A task that
fep 0:5ff20db10a96 1312 * has been deleted but not yet freed by the idle task will also be
fep 0:5ff20db10a96 1313 * included in the count.
fep 0:5ff20db10a96 1314 *
fep 0:5ff20db10a96 1315 * \defgroup uxTaskGetNumberOfTasks uxTaskGetNumberOfTasks
fep 0:5ff20db10a96 1316 * \ingroup TaskUtils
fep 0:5ff20db10a96 1317 */
fep 0:5ff20db10a96 1318 UBaseType_t uxTaskGetNumberOfTasks( void ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 1319
fep 0:5ff20db10a96 1320 /**
fep 0:5ff20db10a96 1321 * task. h
fep 0:5ff20db10a96 1322 * <PRE>char *pcTaskGetName( TaskHandle_t xTaskToQuery );</PRE>
fep 0:5ff20db10a96 1323 *
fep 0:5ff20db10a96 1324 * @return The text (human readable) name of the task referenced by the handle
fep 0:5ff20db10a96 1325 * xTaskToQuery. A task can query its own name by either passing in its own
fep 0:5ff20db10a96 1326 * handle, or by setting xTaskToQuery to NULL.
fep 0:5ff20db10a96 1327 *
fep 0:5ff20db10a96 1328 * \defgroup pcTaskGetName pcTaskGetName
fep 0:5ff20db10a96 1329 * \ingroup TaskUtils
fep 0:5ff20db10a96 1330 */
fep 0:5ff20db10a96 1331 char *pcTaskGetName( TaskHandle_t xTaskToQuery ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
fep 0:5ff20db10a96 1332
fep 0:5ff20db10a96 1333 /**
fep 0:5ff20db10a96 1334 * task. h
fep 0:5ff20db10a96 1335 * <PRE>TaskHandle_t xTaskGetHandle( const char *pcNameToQuery );</PRE>
fep 0:5ff20db10a96 1336 *
fep 0:5ff20db10a96 1337 * NOTE: This function takes a relatively long time to complete and should be
fep 0:5ff20db10a96 1338 * used sparingly.
fep 0:5ff20db10a96 1339 *
fep 0:5ff20db10a96 1340 * @return The handle of the task that has the human readable name pcNameToQuery.
fep 0:5ff20db10a96 1341 * NULL is returned if no matching name is found. INCLUDE_xTaskGetHandle
fep 0:5ff20db10a96 1342 * must be set to 1 in FreeRTOSConfig.h for pcTaskGetHandle() to be available.
fep 0:5ff20db10a96 1343 *
fep 0:5ff20db10a96 1344 * \defgroup pcTaskGetHandle pcTaskGetHandle
fep 0:5ff20db10a96 1345 * \ingroup TaskUtils
fep 0:5ff20db10a96 1346 */
fep 0:5ff20db10a96 1347 TaskHandle_t xTaskGetHandle( const char *pcNameToQuery ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
fep 0:5ff20db10a96 1348
fep 0:5ff20db10a96 1349 /**
fep 0:5ff20db10a96 1350 * task.h
fep 0:5ff20db10a96 1351 * <PRE>UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask );</PRE>
fep 0:5ff20db10a96 1352 *
fep 0:5ff20db10a96 1353 * INCLUDE_uxTaskGetStackHighWaterMark must be set to 1 in FreeRTOSConfig.h for
fep 0:5ff20db10a96 1354 * this function to be available.
fep 0:5ff20db10a96 1355 *
fep 0:5ff20db10a96 1356 * Returns the high water mark of the stack associated with xTask. That is,
fep 0:5ff20db10a96 1357 * the minimum free stack space there has been (in words, so on a 32 bit machine
fep 0:5ff20db10a96 1358 * a value of 1 means 4 bytes) since the task started. The smaller the returned
fep 0:5ff20db10a96 1359 * number the closer the task has come to overflowing its stack.
fep 0:5ff20db10a96 1360 *
fep 0:5ff20db10a96 1361 * @param xTask Handle of the task associated with the stack to be checked.
fep 0:5ff20db10a96 1362 * Set xTask to NULL to check the stack of the calling task.
fep 0:5ff20db10a96 1363 *
fep 0:5ff20db10a96 1364 * @return The smallest amount of free stack space there has been (in words, so
fep 0:5ff20db10a96 1365 * actual spaces on the stack rather than bytes) since the task referenced by
fep 0:5ff20db10a96 1366 * xTask was created.
fep 0:5ff20db10a96 1367 */
fep 0:5ff20db10a96 1368 UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 1369
fep 0:5ff20db10a96 1370 /* When using trace macros it is sometimes necessary to include task.h before
fep 0:5ff20db10a96 1371 FreeRTOS.h. When this is done TaskHookFunction_t will not yet have been defined,
fep 0:5ff20db10a96 1372 so the following two prototypes will cause a compilation error. This can be
fep 0:5ff20db10a96 1373 fixed by simply guarding against the inclusion of these two prototypes unless
fep 0:5ff20db10a96 1374 they are explicitly required by the configUSE_APPLICATION_TASK_TAG configuration
fep 0:5ff20db10a96 1375 constant. */
fep 0:5ff20db10a96 1376 #ifdef configUSE_APPLICATION_TASK_TAG
fep 0:5ff20db10a96 1377 #if configUSE_APPLICATION_TASK_TAG == 1
fep 0:5ff20db10a96 1378 /**
fep 0:5ff20db10a96 1379 * task.h
fep 0:5ff20db10a96 1380 * <pre>void vTaskSetApplicationTaskTag( TaskHandle_t xTask, TaskHookFunction_t pxHookFunction );</pre>
fep 0:5ff20db10a96 1381 *
fep 0:5ff20db10a96 1382 * Sets pxHookFunction to be the task hook function used by the task xTask.
fep 0:5ff20db10a96 1383 * Passing xTask as NULL has the effect of setting the calling tasks hook
fep 0:5ff20db10a96 1384 * function.
fep 0:5ff20db10a96 1385 */
fep 0:5ff20db10a96 1386 void vTaskSetApplicationTaskTag( TaskHandle_t xTask, TaskHookFunction_t pxHookFunction ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 1387
fep 0:5ff20db10a96 1388 /**
fep 0:5ff20db10a96 1389 * task.h
fep 0:5ff20db10a96 1390 * <pre>void xTaskGetApplicationTaskTag( TaskHandle_t xTask );</pre>
fep 0:5ff20db10a96 1391 *
fep 0:5ff20db10a96 1392 * Returns the pxHookFunction value assigned to the task xTask.
fep 0:5ff20db10a96 1393 */
fep 0:5ff20db10a96 1394 TaskHookFunction_t xTaskGetApplicationTaskTag( TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 1395 #endif /* configUSE_APPLICATION_TASK_TAG ==1 */
fep 0:5ff20db10a96 1396 #endif /* ifdef configUSE_APPLICATION_TASK_TAG */
fep 0:5ff20db10a96 1397
fep 0:5ff20db10a96 1398 #if( configNUM_THREAD_LOCAL_STORAGE_POINTERS > 0 )
fep 0:5ff20db10a96 1399
fep 0:5ff20db10a96 1400 /* Each task contains an array of pointers that is dimensioned by the
fep 0:5ff20db10a96 1401 configNUM_THREAD_LOCAL_STORAGE_POINTERS setting in FreeRTOSConfig.h. The
fep 0:5ff20db10a96 1402 kernel does not use the pointers itself, so the application writer can use
fep 0:5ff20db10a96 1403 the pointers for any purpose they wish. The following two functions are
fep 0:5ff20db10a96 1404 used to set and query a pointer respectively. */
fep 0:5ff20db10a96 1405 void vTaskSetThreadLocalStoragePointer( TaskHandle_t xTaskToSet, BaseType_t xIndex, void *pvValue ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 1406 void *pvTaskGetThreadLocalStoragePointer( TaskHandle_t xTaskToQuery, BaseType_t xIndex ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 1407
fep 0:5ff20db10a96 1408 #endif
fep 0:5ff20db10a96 1409
fep 0:5ff20db10a96 1410 /**
fep 0:5ff20db10a96 1411 * task.h
fep 0:5ff20db10a96 1412 * <pre>BaseType_t xTaskCallApplicationTaskHook( TaskHandle_t xTask, void *pvParameter );</pre>
fep 0:5ff20db10a96 1413 *
fep 0:5ff20db10a96 1414 * Calls the hook function associated with xTask. Passing xTask as NULL has
fep 0:5ff20db10a96 1415 * the effect of calling the Running tasks (the calling task) hook function.
fep 0:5ff20db10a96 1416 *
fep 0:5ff20db10a96 1417 * pvParameter is passed to the hook function for the task to interpret as it
fep 0:5ff20db10a96 1418 * wants. The return value is the value returned by the task hook function
fep 0:5ff20db10a96 1419 * registered by the user.
fep 0:5ff20db10a96 1420 */
fep 0:5ff20db10a96 1421 BaseType_t xTaskCallApplicationTaskHook( TaskHandle_t xTask, void *pvParameter ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 1422
fep 0:5ff20db10a96 1423 /**
fep 0:5ff20db10a96 1424 * xTaskGetIdleTaskHandle() is only available if
fep 0:5ff20db10a96 1425 * INCLUDE_xTaskGetIdleTaskHandle is set to 1 in FreeRTOSConfig.h.
fep 0:5ff20db10a96 1426 *
fep 0:5ff20db10a96 1427 * Simply returns the handle of the idle task. It is not valid to call
fep 0:5ff20db10a96 1428 * xTaskGetIdleTaskHandle() before the scheduler has been started.
fep 0:5ff20db10a96 1429 */
fep 0:5ff20db10a96 1430 TaskHandle_t xTaskGetIdleTaskHandle( void ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 1431
fep 0:5ff20db10a96 1432 /**
fep 0:5ff20db10a96 1433 * configUSE_TRACE_FACILITY must be defined as 1 in FreeRTOSConfig.h for
fep 0:5ff20db10a96 1434 * uxTaskGetSystemState() to be available.
fep 0:5ff20db10a96 1435 *
fep 0:5ff20db10a96 1436 * uxTaskGetSystemState() populates an TaskStatus_t structure for each task in
fep 0:5ff20db10a96 1437 * the system. TaskStatus_t structures contain, among other things, members
fep 0:5ff20db10a96 1438 * for the task handle, task name, task priority, task state, and total amount
fep 0:5ff20db10a96 1439 * of run time consumed by the task. See the TaskStatus_t structure
fep 0:5ff20db10a96 1440 * definition in this file for the full member list.
fep 0:5ff20db10a96 1441 *
fep 0:5ff20db10a96 1442 * NOTE: This function is intended for debugging use only as its use results in
fep 0:5ff20db10a96 1443 * the scheduler remaining suspended for an extended period.
fep 0:5ff20db10a96 1444 *
fep 0:5ff20db10a96 1445 * @param pxTaskStatusArray A pointer to an array of TaskStatus_t structures.
fep 0:5ff20db10a96 1446 * The array must contain at least one TaskStatus_t structure for each task
fep 0:5ff20db10a96 1447 * that is under the control of the RTOS. The number of tasks under the control
fep 0:5ff20db10a96 1448 * of the RTOS can be determined using the uxTaskGetNumberOfTasks() API function.
fep 0:5ff20db10a96 1449 *
fep 0:5ff20db10a96 1450 * @param uxArraySize The size of the array pointed to by the pxTaskStatusArray
fep 0:5ff20db10a96 1451 * parameter. The size is specified as the number of indexes in the array, or
fep 0:5ff20db10a96 1452 * the number of TaskStatus_t structures contained in the array, not by the
fep 0:5ff20db10a96 1453 * number of bytes in the array.
fep 0:5ff20db10a96 1454 *
fep 0:5ff20db10a96 1455 * @param pulTotalRunTime If configGENERATE_RUN_TIME_STATS is set to 1 in
fep 0:5ff20db10a96 1456 * FreeRTOSConfig.h then *pulTotalRunTime is set by uxTaskGetSystemState() to the
fep 0:5ff20db10a96 1457 * total run time (as defined by the run time stats clock, see
fep 0:5ff20db10a96 1458 * http://www.freertos.org/rtos-run-time-stats.html) since the target booted.
fep 0:5ff20db10a96 1459 * pulTotalRunTime can be set to NULL to omit the total run time information.
fep 0:5ff20db10a96 1460 *
fep 0:5ff20db10a96 1461 * @return The number of TaskStatus_t structures that were populated by
fep 0:5ff20db10a96 1462 * uxTaskGetSystemState(). This should equal the number returned by the
fep 0:5ff20db10a96 1463 * uxTaskGetNumberOfTasks() API function, but will be zero if the value passed
fep 0:5ff20db10a96 1464 * in the uxArraySize parameter was too small.
fep 0:5ff20db10a96 1465 *
fep 0:5ff20db10a96 1466 * Example usage:
fep 0:5ff20db10a96 1467 <pre>
fep 0:5ff20db10a96 1468 // This example demonstrates how a human readable table of run time stats
fep 0:5ff20db10a96 1469 // information is generated from raw data provided by uxTaskGetSystemState().
fep 0:5ff20db10a96 1470 // The human readable table is written to pcWriteBuffer
fep 0:5ff20db10a96 1471 void vTaskGetRunTimeStats( char *pcWriteBuffer )
fep 0:5ff20db10a96 1472 {
fep 0:5ff20db10a96 1473 TaskStatus_t *pxTaskStatusArray;
fep 0:5ff20db10a96 1474 volatile UBaseType_t uxArraySize, x;
fep 0:5ff20db10a96 1475 uint32_t ulTotalRunTime, ulStatsAsPercentage;
fep 0:5ff20db10a96 1476
fep 0:5ff20db10a96 1477 // Make sure the write buffer does not contain a string.
fep 0:5ff20db10a96 1478 *pcWriteBuffer = 0x00;
fep 0:5ff20db10a96 1479
fep 0:5ff20db10a96 1480 // Take a snapshot of the number of tasks in case it changes while this
fep 0:5ff20db10a96 1481 // function is executing.
fep 0:5ff20db10a96 1482 uxArraySize = uxTaskGetNumberOfTasks();
fep 0:5ff20db10a96 1483
fep 0:5ff20db10a96 1484 // Allocate a TaskStatus_t structure for each task. An array could be
fep 0:5ff20db10a96 1485 // allocated statically at compile time.
fep 0:5ff20db10a96 1486 pxTaskStatusArray = pvPortMalloc( uxArraySize * sizeof( TaskStatus_t ) );
fep 0:5ff20db10a96 1487
fep 0:5ff20db10a96 1488 if( pxTaskStatusArray != NULL )
fep 0:5ff20db10a96 1489 {
fep 0:5ff20db10a96 1490 // Generate raw status information about each task.
fep 0:5ff20db10a96 1491 uxArraySize = uxTaskGetSystemState( pxTaskStatusArray, uxArraySize, &ulTotalRunTime );
fep 0:5ff20db10a96 1492
fep 0:5ff20db10a96 1493 // For percentage calculations.
fep 0:5ff20db10a96 1494 ulTotalRunTime /= 100UL;
fep 0:5ff20db10a96 1495
fep 0:5ff20db10a96 1496 // Avoid divide by zero errors.
fep 0:5ff20db10a96 1497 if( ulTotalRunTime > 0 )
fep 0:5ff20db10a96 1498 {
fep 0:5ff20db10a96 1499 // For each populated position in the pxTaskStatusArray array,
fep 0:5ff20db10a96 1500 // format the raw data as human readable ASCII data
fep 0:5ff20db10a96 1501 for( x = 0; x < uxArraySize; x++ )
fep 0:5ff20db10a96 1502 {
fep 0:5ff20db10a96 1503 // What percentage of the total run time has the task used?
fep 0:5ff20db10a96 1504 // This will always be rounded down to the nearest integer.
fep 0:5ff20db10a96 1505 // ulTotalRunTimeDiv100 has already been divided by 100.
fep 0:5ff20db10a96 1506 ulStatsAsPercentage = pxTaskStatusArray[ x ].ulRunTimeCounter / ulTotalRunTime;
fep 0:5ff20db10a96 1507
fep 0:5ff20db10a96 1508 if( ulStatsAsPercentage > 0UL )
fep 0:5ff20db10a96 1509 {
fep 0:5ff20db10a96 1510 sprintf( pcWriteBuffer, "%s\t\t%lu\t\t%lu%%\r\n", pxTaskStatusArray[ x ].pcTaskName, pxTaskStatusArray[ x ].ulRunTimeCounter, ulStatsAsPercentage );
fep 0:5ff20db10a96 1511 }
fep 0:5ff20db10a96 1512 else
fep 0:5ff20db10a96 1513 {
fep 0:5ff20db10a96 1514 // If the percentage is zero here then the task has
fep 0:5ff20db10a96 1515 // consumed less than 1% of the total run time.
fep 0:5ff20db10a96 1516 sprintf( pcWriteBuffer, "%s\t\t%lu\t\t<1%%\r\n", pxTaskStatusArray[ x ].pcTaskName, pxTaskStatusArray[ x ].ulRunTimeCounter );
fep 0:5ff20db10a96 1517 }
fep 0:5ff20db10a96 1518
fep 0:5ff20db10a96 1519 pcWriteBuffer += strlen( ( char * ) pcWriteBuffer );
fep 0:5ff20db10a96 1520 }
fep 0:5ff20db10a96 1521 }
fep 0:5ff20db10a96 1522
fep 0:5ff20db10a96 1523 // The array is no longer needed, free the memory it consumes.
fep 0:5ff20db10a96 1524 vPortFree( pxTaskStatusArray );
fep 0:5ff20db10a96 1525 }
fep 0:5ff20db10a96 1526 }
fep 0:5ff20db10a96 1527 </pre>
fep 0:5ff20db10a96 1528 */
fep 0:5ff20db10a96 1529 UBaseType_t uxTaskGetSystemState( TaskStatus_t * const pxTaskStatusArray, const UBaseType_t uxArraySize, uint32_t * const pulTotalRunTime ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 1530
fep 0:5ff20db10a96 1531 /**
fep 0:5ff20db10a96 1532 * task. h
fep 0:5ff20db10a96 1533 * <PRE>void vTaskList( char *pcWriteBuffer );</PRE>
fep 0:5ff20db10a96 1534 *
fep 0:5ff20db10a96 1535 * configUSE_TRACE_FACILITY and configUSE_STATS_FORMATTING_FUNCTIONS must
fep 0:5ff20db10a96 1536 * both be defined as 1 for this function to be available. See the
fep 0:5ff20db10a96 1537 * configuration section of the FreeRTOS.org website for more information.
fep 0:5ff20db10a96 1538 *
fep 0:5ff20db10a96 1539 * NOTE 1: This function will disable interrupts for its duration. It is
fep 0:5ff20db10a96 1540 * not intended for normal application runtime use but as a debug aid.
fep 0:5ff20db10a96 1541 *
fep 0:5ff20db10a96 1542 * Lists all the current tasks, along with their current state and stack
fep 0:5ff20db10a96 1543 * usage high water mark.
fep 0:5ff20db10a96 1544 *
fep 0:5ff20db10a96 1545 * Tasks are reported as blocked ('B'), ready ('R'), deleted ('D') or
fep 0:5ff20db10a96 1546 * suspended ('S').
fep 0:5ff20db10a96 1547 *
fep 0:5ff20db10a96 1548 * PLEASE NOTE:
fep 0:5ff20db10a96 1549 *
fep 0:5ff20db10a96 1550 * This function is provided for convenience only, and is used by many of the
fep 0:5ff20db10a96 1551 * demo applications. Do not consider it to be part of the scheduler.
fep 0:5ff20db10a96 1552 *
fep 0:5ff20db10a96 1553 * vTaskList() calls uxTaskGetSystemState(), then formats part of the
fep 0:5ff20db10a96 1554 * uxTaskGetSystemState() output into a human readable table that displays task
fep 0:5ff20db10a96 1555 * names, states and stack usage.
fep 0:5ff20db10a96 1556 *
fep 0:5ff20db10a96 1557 * vTaskList() has a dependency on the sprintf() C library function that might
fep 0:5ff20db10a96 1558 * bloat the code size, use a lot of stack, and provide different results on
fep 0:5ff20db10a96 1559 * different platforms. An alternative, tiny, third party, and limited
fep 0:5ff20db10a96 1560 * functionality implementation of sprintf() is provided in many of the
fep 0:5ff20db10a96 1561 * FreeRTOS/Demo sub-directories in a file called printf-stdarg.c (note
fep 0:5ff20db10a96 1562 * printf-stdarg.c does not provide a full snprintf() implementation!).
fep 0:5ff20db10a96 1563 *
fep 0:5ff20db10a96 1564 * It is recommended that production systems call uxTaskGetSystemState()
fep 0:5ff20db10a96 1565 * directly to get access to raw stats data, rather than indirectly through a
fep 0:5ff20db10a96 1566 * call to vTaskList().
fep 0:5ff20db10a96 1567 *
fep 0:5ff20db10a96 1568 * @param pcWriteBuffer A buffer into which the above mentioned details
fep 0:5ff20db10a96 1569 * will be written, in ASCII form. This buffer is assumed to be large
fep 0:5ff20db10a96 1570 * enough to contain the generated report. Approximately 40 bytes per
fep 0:5ff20db10a96 1571 * task should be sufficient.
fep 0:5ff20db10a96 1572 *
fep 0:5ff20db10a96 1573 * \defgroup vTaskList vTaskList
fep 0:5ff20db10a96 1574 * \ingroup TaskUtils
fep 0:5ff20db10a96 1575 */
fep 0:5ff20db10a96 1576 void vTaskList( char * pcWriteBuffer ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
fep 0:5ff20db10a96 1577
fep 0:5ff20db10a96 1578 /**
fep 0:5ff20db10a96 1579 * task. h
fep 0:5ff20db10a96 1580 * <PRE>void vTaskGetRunTimeStats( char *pcWriteBuffer );</PRE>
fep 0:5ff20db10a96 1581 *
fep 0:5ff20db10a96 1582 * configGENERATE_RUN_TIME_STATS and configUSE_STATS_FORMATTING_FUNCTIONS
fep 0:5ff20db10a96 1583 * must both be defined as 1 for this function to be available. The application
fep 0:5ff20db10a96 1584 * must also then provide definitions for
fep 0:5ff20db10a96 1585 * portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and portGET_RUN_TIME_COUNTER_VALUE()
fep 0:5ff20db10a96 1586 * to configure a peripheral timer/counter and return the timers current count
fep 0:5ff20db10a96 1587 * value respectively. The counter should be at least 10 times the frequency of
fep 0:5ff20db10a96 1588 * the tick count.
fep 0:5ff20db10a96 1589 *
fep 0:5ff20db10a96 1590 * NOTE 1: This function will disable interrupts for its duration. It is
fep 0:5ff20db10a96 1591 * not intended for normal application runtime use but as a debug aid.
fep 0:5ff20db10a96 1592 *
fep 0:5ff20db10a96 1593 * Setting configGENERATE_RUN_TIME_STATS to 1 will result in a total
fep 0:5ff20db10a96 1594 * accumulated execution time being stored for each task. The resolution
fep 0:5ff20db10a96 1595 * of the accumulated time value depends on the frequency of the timer
fep 0:5ff20db10a96 1596 * configured by the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() macro.
fep 0:5ff20db10a96 1597 * Calling vTaskGetRunTimeStats() writes the total execution time of each
fep 0:5ff20db10a96 1598 * task into a buffer, both as an absolute count value and as a percentage
fep 0:5ff20db10a96 1599 * of the total system execution time.
fep 0:5ff20db10a96 1600 *
fep 0:5ff20db10a96 1601 * NOTE 2:
fep 0:5ff20db10a96 1602 *
fep 0:5ff20db10a96 1603 * This function is provided for convenience only, and is used by many of the
fep 0:5ff20db10a96 1604 * demo applications. Do not consider it to be part of the scheduler.
fep 0:5ff20db10a96 1605 *
fep 0:5ff20db10a96 1606 * vTaskGetRunTimeStats() calls uxTaskGetSystemState(), then formats part of the
fep 0:5ff20db10a96 1607 * uxTaskGetSystemState() output into a human readable table that displays the
fep 0:5ff20db10a96 1608 * amount of time each task has spent in the Running state in both absolute and
fep 0:5ff20db10a96 1609 * percentage terms.
fep 0:5ff20db10a96 1610 *
fep 0:5ff20db10a96 1611 * vTaskGetRunTimeStats() has a dependency on the sprintf() C library function
fep 0:5ff20db10a96 1612 * that might bloat the code size, use a lot of stack, and provide different
fep 0:5ff20db10a96 1613 * results on different platforms. An alternative, tiny, third party, and
fep 0:5ff20db10a96 1614 * limited functionality implementation of sprintf() is provided in many of the
fep 0:5ff20db10a96 1615 * FreeRTOS/Demo sub-directories in a file called printf-stdarg.c (note
fep 0:5ff20db10a96 1616 * printf-stdarg.c does not provide a full snprintf() implementation!).
fep 0:5ff20db10a96 1617 *
fep 0:5ff20db10a96 1618 * It is recommended that production systems call uxTaskGetSystemState() directly
fep 0:5ff20db10a96 1619 * to get access to raw stats data, rather than indirectly through a call to
fep 0:5ff20db10a96 1620 * vTaskGetRunTimeStats().
fep 0:5ff20db10a96 1621 *
fep 0:5ff20db10a96 1622 * @param pcWriteBuffer A buffer into which the execution times will be
fep 0:5ff20db10a96 1623 * written, in ASCII form. This buffer is assumed to be large enough to
fep 0:5ff20db10a96 1624 * contain the generated report. Approximately 40 bytes per task should
fep 0:5ff20db10a96 1625 * be sufficient.
fep 0:5ff20db10a96 1626 *
fep 0:5ff20db10a96 1627 * \defgroup vTaskGetRunTimeStats vTaskGetRunTimeStats
fep 0:5ff20db10a96 1628 * \ingroup TaskUtils
fep 0:5ff20db10a96 1629 */
fep 0:5ff20db10a96 1630 void vTaskGetRunTimeStats( char *pcWriteBuffer ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
fep 0:5ff20db10a96 1631
fep 0:5ff20db10a96 1632 /**
fep 0:5ff20db10a96 1633 * task. h
fep 0:5ff20db10a96 1634 * <PRE>BaseType_t xTaskNotify( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction );</PRE>
fep 0:5ff20db10a96 1635 *
fep 0:5ff20db10a96 1636 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this
fep 0:5ff20db10a96 1637 * function to be available.
fep 0:5ff20db10a96 1638 *
fep 0:5ff20db10a96 1639 * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private
fep 0:5ff20db10a96 1640 * "notification value", which is a 32-bit unsigned integer (uint32_t).
fep 0:5ff20db10a96 1641 *
fep 0:5ff20db10a96 1642 * Events can be sent to a task using an intermediary object. Examples of such
fep 0:5ff20db10a96 1643 * objects are queues, semaphores, mutexes and event groups. Task notifications
fep 0:5ff20db10a96 1644 * are a method of sending an event directly to a task without the need for such
fep 0:5ff20db10a96 1645 * an intermediary object.
fep 0:5ff20db10a96 1646 *
fep 0:5ff20db10a96 1647 * A notification sent to a task can optionally perform an action, such as
fep 0:5ff20db10a96 1648 * update, overwrite or increment the task's notification value. In that way
fep 0:5ff20db10a96 1649 * task notifications can be used to send data to a task, or be used as light
fep 0:5ff20db10a96 1650 * weight and fast binary or counting semaphores.
fep 0:5ff20db10a96 1651 *
fep 0:5ff20db10a96 1652 * A notification sent to a task will remain pending until it is cleared by the
fep 0:5ff20db10a96 1653 * task calling xTaskNotifyWait() or ulTaskNotifyTake(). If the task was
fep 0:5ff20db10a96 1654 * already in the Blocked state to wait for a notification when the notification
fep 0:5ff20db10a96 1655 * arrives then the task will automatically be removed from the Blocked state
fep 0:5ff20db10a96 1656 * (unblocked) and the notification cleared.
fep 0:5ff20db10a96 1657 *
fep 0:5ff20db10a96 1658 * A task can use xTaskNotifyWait() to [optionally] block to wait for a
fep 0:5ff20db10a96 1659 * notification to be pending, or ulTaskNotifyTake() to [optionally] block
fep 0:5ff20db10a96 1660 * to wait for its notification value to have a non-zero value. The task does
fep 0:5ff20db10a96 1661 * not consume any CPU time while it is in the Blocked state.
fep 0:5ff20db10a96 1662 *
fep 0:5ff20db10a96 1663 * See http://www.FreeRTOS.org/RTOS-task-notifications.html for details.
fep 0:5ff20db10a96 1664 *
fep 0:5ff20db10a96 1665 * @param xTaskToNotify The handle of the task being notified. The handle to a
fep 0:5ff20db10a96 1666 * task can be returned from the xTaskCreate() API function used to create the
fep 0:5ff20db10a96 1667 * task, and the handle of the currently running task can be obtained by calling
fep 0:5ff20db10a96 1668 * xTaskGetCurrentTaskHandle().
fep 0:5ff20db10a96 1669 *
fep 0:5ff20db10a96 1670 * @param ulValue Data that can be sent with the notification. How the data is
fep 0:5ff20db10a96 1671 * used depends on the value of the eAction parameter.
fep 0:5ff20db10a96 1672 *
fep 0:5ff20db10a96 1673 * @param eAction Specifies how the notification updates the task's notification
fep 0:5ff20db10a96 1674 * value, if at all. Valid values for eAction are as follows:
fep 0:5ff20db10a96 1675 *
fep 0:5ff20db10a96 1676 * eSetBits -
fep 0:5ff20db10a96 1677 * The task's notification value is bitwise ORed with ulValue. xTaskNofify()
fep 0:5ff20db10a96 1678 * always returns pdPASS in this case.
fep 0:5ff20db10a96 1679 *
fep 0:5ff20db10a96 1680 * eIncrement -
fep 0:5ff20db10a96 1681 * The task's notification value is incremented. ulValue is not used and
fep 0:5ff20db10a96 1682 * xTaskNotify() always returns pdPASS in this case.
fep 0:5ff20db10a96 1683 *
fep 0:5ff20db10a96 1684 * eSetValueWithOverwrite -
fep 0:5ff20db10a96 1685 * The task's notification value is set to the value of ulValue, even if the
fep 0:5ff20db10a96 1686 * task being notified had not yet processed the previous notification (the
fep 0:5ff20db10a96 1687 * task already had a notification pending). xTaskNotify() always returns
fep 0:5ff20db10a96 1688 * pdPASS in this case.
fep 0:5ff20db10a96 1689 *
fep 0:5ff20db10a96 1690 * eSetValueWithoutOverwrite -
fep 0:5ff20db10a96 1691 * If the task being notified did not already have a notification pending then
fep 0:5ff20db10a96 1692 * the task's notification value is set to ulValue and xTaskNotify() will
fep 0:5ff20db10a96 1693 * return pdPASS. If the task being notified already had a notification
fep 0:5ff20db10a96 1694 * pending then no action is performed and pdFAIL is returned.
fep 0:5ff20db10a96 1695 *
fep 0:5ff20db10a96 1696 * eNoAction -
fep 0:5ff20db10a96 1697 * The task receives a notification without its notification value being
fep 0:5ff20db10a96 1698 * updated. ulValue is not used and xTaskNotify() always returns pdPASS in
fep 0:5ff20db10a96 1699 * this case.
fep 0:5ff20db10a96 1700 *
fep 0:5ff20db10a96 1701 * pulPreviousNotificationValue -
fep 0:5ff20db10a96 1702 * Can be used to pass out the subject task's notification value before any
fep 0:5ff20db10a96 1703 * bits are modified by the notify function.
fep 0:5ff20db10a96 1704 *
fep 0:5ff20db10a96 1705 * @return Dependent on the value of eAction. See the description of the
fep 0:5ff20db10a96 1706 * eAction parameter.
fep 0:5ff20db10a96 1707 *
fep 0:5ff20db10a96 1708 * \defgroup xTaskNotify xTaskNotify
fep 0:5ff20db10a96 1709 * \ingroup TaskNotifications
fep 0:5ff20db10a96 1710 */
fep 0:5ff20db10a96 1711 BaseType_t xTaskGenericNotify( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 1712 #define xTaskNotify( xTaskToNotify, ulValue, eAction ) xTaskGenericNotify( ( xTaskToNotify ), ( ulValue ), ( eAction ), NULL )
fep 0:5ff20db10a96 1713 #define xTaskNotifyAndQuery( xTaskToNotify, ulValue, eAction, pulPreviousNotifyValue ) xTaskGenericNotify( ( xTaskToNotify ), ( ulValue ), ( eAction ), ( pulPreviousNotifyValue ) )
fep 0:5ff20db10a96 1714
fep 0:5ff20db10a96 1715 /**
fep 0:5ff20db10a96 1716 * task. h
fep 0:5ff20db10a96 1717 * <PRE>BaseType_t xTaskNotifyFromISR( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, BaseType_t *pxHigherPriorityTaskWoken );</PRE>
fep 0:5ff20db10a96 1718 *
fep 0:5ff20db10a96 1719 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this
fep 0:5ff20db10a96 1720 * function to be available.
fep 0:5ff20db10a96 1721 *
fep 0:5ff20db10a96 1722 * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private
fep 0:5ff20db10a96 1723 * "notification value", which is a 32-bit unsigned integer (uint32_t).
fep 0:5ff20db10a96 1724 *
fep 0:5ff20db10a96 1725 * A version of xTaskNotify() that can be used from an interrupt service routine
fep 0:5ff20db10a96 1726 * (ISR).
fep 0:5ff20db10a96 1727 *
fep 0:5ff20db10a96 1728 * Events can be sent to a task using an intermediary object. Examples of such
fep 0:5ff20db10a96 1729 * objects are queues, semaphores, mutexes and event groups. Task notifications
fep 0:5ff20db10a96 1730 * are a method of sending an event directly to a task without the need for such
fep 0:5ff20db10a96 1731 * an intermediary object.
fep 0:5ff20db10a96 1732 *
fep 0:5ff20db10a96 1733 * A notification sent to a task can optionally perform an action, such as
fep 0:5ff20db10a96 1734 * update, overwrite or increment the task's notification value. In that way
fep 0:5ff20db10a96 1735 * task notifications can be used to send data to a task, or be used as light
fep 0:5ff20db10a96 1736 * weight and fast binary or counting semaphores.
fep 0:5ff20db10a96 1737 *
fep 0:5ff20db10a96 1738 * A notification sent to a task will remain pending until it is cleared by the
fep 0:5ff20db10a96 1739 * task calling xTaskNotifyWait() or ulTaskNotifyTake(). If the task was
fep 0:5ff20db10a96 1740 * already in the Blocked state to wait for a notification when the notification
fep 0:5ff20db10a96 1741 * arrives then the task will automatically be removed from the Blocked state
fep 0:5ff20db10a96 1742 * (unblocked) and the notification cleared.
fep 0:5ff20db10a96 1743 *
fep 0:5ff20db10a96 1744 * A task can use xTaskNotifyWait() to [optionally] block to wait for a
fep 0:5ff20db10a96 1745 * notification to be pending, or ulTaskNotifyTake() to [optionally] block
fep 0:5ff20db10a96 1746 * to wait for its notification value to have a non-zero value. The task does
fep 0:5ff20db10a96 1747 * not consume any CPU time while it is in the Blocked state.
fep 0:5ff20db10a96 1748 *
fep 0:5ff20db10a96 1749 * See http://www.FreeRTOS.org/RTOS-task-notifications.html for details.
fep 0:5ff20db10a96 1750 *
fep 0:5ff20db10a96 1751 * @param xTaskToNotify The handle of the task being notified. The handle to a
fep 0:5ff20db10a96 1752 * task can be returned from the xTaskCreate() API function used to create the
fep 0:5ff20db10a96 1753 * task, and the handle of the currently running task can be obtained by calling
fep 0:5ff20db10a96 1754 * xTaskGetCurrentTaskHandle().
fep 0:5ff20db10a96 1755 *
fep 0:5ff20db10a96 1756 * @param ulValue Data that can be sent with the notification. How the data is
fep 0:5ff20db10a96 1757 * used depends on the value of the eAction parameter.
fep 0:5ff20db10a96 1758 *
fep 0:5ff20db10a96 1759 * @param eAction Specifies how the notification updates the task's notification
fep 0:5ff20db10a96 1760 * value, if at all. Valid values for eAction are as follows:
fep 0:5ff20db10a96 1761 *
fep 0:5ff20db10a96 1762 * eSetBits -
fep 0:5ff20db10a96 1763 * The task's notification value is bitwise ORed with ulValue. xTaskNofify()
fep 0:5ff20db10a96 1764 * always returns pdPASS in this case.
fep 0:5ff20db10a96 1765 *
fep 0:5ff20db10a96 1766 * eIncrement -
fep 0:5ff20db10a96 1767 * The task's notification value is incremented. ulValue is not used and
fep 0:5ff20db10a96 1768 * xTaskNotify() always returns pdPASS in this case.
fep 0:5ff20db10a96 1769 *
fep 0:5ff20db10a96 1770 * eSetValueWithOverwrite -
fep 0:5ff20db10a96 1771 * The task's notification value is set to the value of ulValue, even if the
fep 0:5ff20db10a96 1772 * task being notified had not yet processed the previous notification (the
fep 0:5ff20db10a96 1773 * task already had a notification pending). xTaskNotify() always returns
fep 0:5ff20db10a96 1774 * pdPASS in this case.
fep 0:5ff20db10a96 1775 *
fep 0:5ff20db10a96 1776 * eSetValueWithoutOverwrite -
fep 0:5ff20db10a96 1777 * If the task being notified did not already have a notification pending then
fep 0:5ff20db10a96 1778 * the task's notification value is set to ulValue and xTaskNotify() will
fep 0:5ff20db10a96 1779 * return pdPASS. If the task being notified already had a notification
fep 0:5ff20db10a96 1780 * pending then no action is performed and pdFAIL is returned.
fep 0:5ff20db10a96 1781 *
fep 0:5ff20db10a96 1782 * eNoAction -
fep 0:5ff20db10a96 1783 * The task receives a notification without its notification value being
fep 0:5ff20db10a96 1784 * updated. ulValue is not used and xTaskNotify() always returns pdPASS in
fep 0:5ff20db10a96 1785 * this case.
fep 0:5ff20db10a96 1786 *
fep 0:5ff20db10a96 1787 * @param pxHigherPriorityTaskWoken xTaskNotifyFromISR() will set
fep 0:5ff20db10a96 1788 * *pxHigherPriorityTaskWoken to pdTRUE if sending the notification caused the
fep 0:5ff20db10a96 1789 * task to which the notification was sent to leave the Blocked state, and the
fep 0:5ff20db10a96 1790 * unblocked task has a priority higher than the currently running task. If
fep 0:5ff20db10a96 1791 * xTaskNotifyFromISR() sets this value to pdTRUE then a context switch should
fep 0:5ff20db10a96 1792 * be requested before the interrupt is exited. How a context switch is
fep 0:5ff20db10a96 1793 * requested from an ISR is dependent on the port - see the documentation page
fep 0:5ff20db10a96 1794 * for the port in use.
fep 0:5ff20db10a96 1795 *
fep 0:5ff20db10a96 1796 * @return Dependent on the value of eAction. See the description of the
fep 0:5ff20db10a96 1797 * eAction parameter.
fep 0:5ff20db10a96 1798 *
fep 0:5ff20db10a96 1799 * \defgroup xTaskNotify xTaskNotify
fep 0:5ff20db10a96 1800 * \ingroup TaskNotifications
fep 0:5ff20db10a96 1801 */
fep 0:5ff20db10a96 1802 BaseType_t xTaskGenericNotifyFromISR( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue, BaseType_t *pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 1803 #define xTaskNotifyFromISR( xTaskToNotify, ulValue, eAction, pxHigherPriorityTaskWoken ) xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( ulValue ), ( eAction ), NULL, ( pxHigherPriorityTaskWoken ) )
fep 0:5ff20db10a96 1804 #define xTaskNotifyAndQueryFromISR( xTaskToNotify, ulValue, eAction, pulPreviousNotificationValue, pxHigherPriorityTaskWoken ) xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( ulValue ), ( eAction ), ( pulPreviousNotificationValue ), ( pxHigherPriorityTaskWoken ) )
fep 0:5ff20db10a96 1805
fep 0:5ff20db10a96 1806 /**
fep 0:5ff20db10a96 1807 * task. h
fep 0:5ff20db10a96 1808 * <PRE>BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait );</pre>
fep 0:5ff20db10a96 1809 *
fep 0:5ff20db10a96 1810 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this
fep 0:5ff20db10a96 1811 * function to be available.
fep 0:5ff20db10a96 1812 *
fep 0:5ff20db10a96 1813 * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private
fep 0:5ff20db10a96 1814 * "notification value", which is a 32-bit unsigned integer (uint32_t).
fep 0:5ff20db10a96 1815 *
fep 0:5ff20db10a96 1816 * Events can be sent to a task using an intermediary object. Examples of such
fep 0:5ff20db10a96 1817 * objects are queues, semaphores, mutexes and event groups. Task notifications
fep 0:5ff20db10a96 1818 * are a method of sending an event directly to a task without the need for such
fep 0:5ff20db10a96 1819 * an intermediary object.
fep 0:5ff20db10a96 1820 *
fep 0:5ff20db10a96 1821 * A notification sent to a task can optionally perform an action, such as
fep 0:5ff20db10a96 1822 * update, overwrite or increment the task's notification value. In that way
fep 0:5ff20db10a96 1823 * task notifications can be used to send data to a task, or be used as light
fep 0:5ff20db10a96 1824 * weight and fast binary or counting semaphores.
fep 0:5ff20db10a96 1825 *
fep 0:5ff20db10a96 1826 * A notification sent to a task will remain pending until it is cleared by the
fep 0:5ff20db10a96 1827 * task calling xTaskNotifyWait() or ulTaskNotifyTake(). If the task was
fep 0:5ff20db10a96 1828 * already in the Blocked state to wait for a notification when the notification
fep 0:5ff20db10a96 1829 * arrives then the task will automatically be removed from the Blocked state
fep 0:5ff20db10a96 1830 * (unblocked) and the notification cleared.
fep 0:5ff20db10a96 1831 *
fep 0:5ff20db10a96 1832 * A task can use xTaskNotifyWait() to [optionally] block to wait for a
fep 0:5ff20db10a96 1833 * notification to be pending, or ulTaskNotifyTake() to [optionally] block
fep 0:5ff20db10a96 1834 * to wait for its notification value to have a non-zero value. The task does
fep 0:5ff20db10a96 1835 * not consume any CPU time while it is in the Blocked state.
fep 0:5ff20db10a96 1836 *
fep 0:5ff20db10a96 1837 * See http://www.FreeRTOS.org/RTOS-task-notifications.html for details.
fep 0:5ff20db10a96 1838 *
fep 0:5ff20db10a96 1839 * @param ulBitsToClearOnEntry Bits that are set in ulBitsToClearOnEntry value
fep 0:5ff20db10a96 1840 * will be cleared in the calling task's notification value before the task
fep 0:5ff20db10a96 1841 * checks to see if any notifications are pending, and optionally blocks if no
fep 0:5ff20db10a96 1842 * notifications are pending. Setting ulBitsToClearOnEntry to ULONG_MAX (if
fep 0:5ff20db10a96 1843 * limits.h is included) or 0xffffffffUL (if limits.h is not included) will have
fep 0:5ff20db10a96 1844 * the effect of resetting the task's notification value to 0. Setting
fep 0:5ff20db10a96 1845 * ulBitsToClearOnEntry to 0 will leave the task's notification value unchanged.
fep 0:5ff20db10a96 1846 *
fep 0:5ff20db10a96 1847 * @param ulBitsToClearOnExit If a notification is pending or received before
fep 0:5ff20db10a96 1848 * the calling task exits the xTaskNotifyWait() function then the task's
fep 0:5ff20db10a96 1849 * notification value (see the xTaskNotify() API function) is passed out using
fep 0:5ff20db10a96 1850 * the pulNotificationValue parameter. Then any bits that are set in
fep 0:5ff20db10a96 1851 * ulBitsToClearOnExit will be cleared in the task's notification value (note
fep 0:5ff20db10a96 1852 * *pulNotificationValue is set before any bits are cleared). Setting
fep 0:5ff20db10a96 1853 * ulBitsToClearOnExit to ULONG_MAX (if limits.h is included) or 0xffffffffUL
fep 0:5ff20db10a96 1854 * (if limits.h is not included) will have the effect of resetting the task's
fep 0:5ff20db10a96 1855 * notification value to 0 before the function exits. Setting
fep 0:5ff20db10a96 1856 * ulBitsToClearOnExit to 0 will leave the task's notification value unchanged
fep 0:5ff20db10a96 1857 * when the function exits (in which case the value passed out in
fep 0:5ff20db10a96 1858 * pulNotificationValue will match the task's notification value).
fep 0:5ff20db10a96 1859 *
fep 0:5ff20db10a96 1860 * @param pulNotificationValue Used to pass the task's notification value out
fep 0:5ff20db10a96 1861 * of the function. Note the value passed out will not be effected by the
fep 0:5ff20db10a96 1862 * clearing of any bits caused by ulBitsToClearOnExit being non-zero.
fep 0:5ff20db10a96 1863 *
fep 0:5ff20db10a96 1864 * @param xTicksToWait The maximum amount of time that the task should wait in
fep 0:5ff20db10a96 1865 * the Blocked state for a notification to be received, should a notification
fep 0:5ff20db10a96 1866 * not already be pending when xTaskNotifyWait() was called. The task
fep 0:5ff20db10a96 1867 * will not consume any processing time while it is in the Blocked state. This
fep 0:5ff20db10a96 1868 * is specified in kernel ticks, the macro pdMS_TO_TICSK( value_in_ms ) can be
fep 0:5ff20db10a96 1869 * used to convert a time specified in milliseconds to a time specified in
fep 0:5ff20db10a96 1870 * ticks.
fep 0:5ff20db10a96 1871 *
fep 0:5ff20db10a96 1872 * @return If a notification was received (including notifications that were
fep 0:5ff20db10a96 1873 * already pending when xTaskNotifyWait was called) then pdPASS is
fep 0:5ff20db10a96 1874 * returned. Otherwise pdFAIL is returned.
fep 0:5ff20db10a96 1875 *
fep 0:5ff20db10a96 1876 * \defgroup xTaskNotifyWait xTaskNotifyWait
fep 0:5ff20db10a96 1877 * \ingroup TaskNotifications
fep 0:5ff20db10a96 1878 */
fep 0:5ff20db10a96 1879 BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 1880
fep 0:5ff20db10a96 1881 /**
fep 0:5ff20db10a96 1882 * task. h
fep 0:5ff20db10a96 1883 * <PRE>BaseType_t xTaskNotifyGive( TaskHandle_t xTaskToNotify );</PRE>
fep 0:5ff20db10a96 1884 *
fep 0:5ff20db10a96 1885 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this macro
fep 0:5ff20db10a96 1886 * to be available.
fep 0:5ff20db10a96 1887 *
fep 0:5ff20db10a96 1888 * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private
fep 0:5ff20db10a96 1889 * "notification value", which is a 32-bit unsigned integer (uint32_t).
fep 0:5ff20db10a96 1890 *
fep 0:5ff20db10a96 1891 * Events can be sent to a task using an intermediary object. Examples of such
fep 0:5ff20db10a96 1892 * objects are queues, semaphores, mutexes and event groups. Task notifications
fep 0:5ff20db10a96 1893 * are a method of sending an event directly to a task without the need for such
fep 0:5ff20db10a96 1894 * an intermediary object.
fep 0:5ff20db10a96 1895 *
fep 0:5ff20db10a96 1896 * A notification sent to a task can optionally perform an action, such as
fep 0:5ff20db10a96 1897 * update, overwrite or increment the task's notification value. In that way
fep 0:5ff20db10a96 1898 * task notifications can be used to send data to a task, or be used as light
fep 0:5ff20db10a96 1899 * weight and fast binary or counting semaphores.
fep 0:5ff20db10a96 1900 *
fep 0:5ff20db10a96 1901 * xTaskNotifyGive() is a helper macro intended for use when task notifications
fep 0:5ff20db10a96 1902 * are used as light weight and faster binary or counting semaphore equivalents.
fep 0:5ff20db10a96 1903 * Actual FreeRTOS semaphores are given using the xSemaphoreGive() API function,
fep 0:5ff20db10a96 1904 * the equivalent action that instead uses a task notification is
fep 0:5ff20db10a96 1905 * xTaskNotifyGive().
fep 0:5ff20db10a96 1906 *
fep 0:5ff20db10a96 1907 * When task notifications are being used as a binary or counting semaphore
fep 0:5ff20db10a96 1908 * equivalent then the task being notified should wait for the notification
fep 0:5ff20db10a96 1909 * using the ulTaskNotificationTake() API function rather than the
fep 0:5ff20db10a96 1910 * xTaskNotifyWait() API function.
fep 0:5ff20db10a96 1911 *
fep 0:5ff20db10a96 1912 * See http://www.FreeRTOS.org/RTOS-task-notifications.html for more details.
fep 0:5ff20db10a96 1913 *
fep 0:5ff20db10a96 1914 * @param xTaskToNotify The handle of the task being notified. The handle to a
fep 0:5ff20db10a96 1915 * task can be returned from the xTaskCreate() API function used to create the
fep 0:5ff20db10a96 1916 * task, and the handle of the currently running task can be obtained by calling
fep 0:5ff20db10a96 1917 * xTaskGetCurrentTaskHandle().
fep 0:5ff20db10a96 1918 *
fep 0:5ff20db10a96 1919 * @return xTaskNotifyGive() is a macro that calls xTaskNotify() with the
fep 0:5ff20db10a96 1920 * eAction parameter set to eIncrement - so pdPASS is always returned.
fep 0:5ff20db10a96 1921 *
fep 0:5ff20db10a96 1922 * \defgroup xTaskNotifyGive xTaskNotifyGive
fep 0:5ff20db10a96 1923 * \ingroup TaskNotifications
fep 0:5ff20db10a96 1924 */
fep 0:5ff20db10a96 1925 #define xTaskNotifyGive( xTaskToNotify ) xTaskGenericNotify( ( xTaskToNotify ), ( 0 ), eIncrement, NULL )
fep 0:5ff20db10a96 1926
fep 0:5ff20db10a96 1927 /**
fep 0:5ff20db10a96 1928 * task. h
fep 0:5ff20db10a96 1929 * <PRE>void vTaskNotifyGiveFromISR( TaskHandle_t xTaskHandle, BaseType_t *pxHigherPriorityTaskWoken );
fep 0:5ff20db10a96 1930 *
fep 0:5ff20db10a96 1931 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this macro
fep 0:5ff20db10a96 1932 * to be available.
fep 0:5ff20db10a96 1933 *
fep 0:5ff20db10a96 1934 * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private
fep 0:5ff20db10a96 1935 * "notification value", which is a 32-bit unsigned integer (uint32_t).
fep 0:5ff20db10a96 1936 *
fep 0:5ff20db10a96 1937 * A version of xTaskNotifyGive() that can be called from an interrupt service
fep 0:5ff20db10a96 1938 * routine (ISR).
fep 0:5ff20db10a96 1939 *
fep 0:5ff20db10a96 1940 * Events can be sent to a task using an intermediary object. Examples of such
fep 0:5ff20db10a96 1941 * objects are queues, semaphores, mutexes and event groups. Task notifications
fep 0:5ff20db10a96 1942 * are a method of sending an event directly to a task without the need for such
fep 0:5ff20db10a96 1943 * an intermediary object.
fep 0:5ff20db10a96 1944 *
fep 0:5ff20db10a96 1945 * A notification sent to a task can optionally perform an action, such as
fep 0:5ff20db10a96 1946 * update, overwrite or increment the task's notification value. In that way
fep 0:5ff20db10a96 1947 * task notifications can be used to send data to a task, or be used as light
fep 0:5ff20db10a96 1948 * weight and fast binary or counting semaphores.
fep 0:5ff20db10a96 1949 *
fep 0:5ff20db10a96 1950 * vTaskNotifyGiveFromISR() is intended for use when task notifications are
fep 0:5ff20db10a96 1951 * used as light weight and faster binary or counting semaphore equivalents.
fep 0:5ff20db10a96 1952 * Actual FreeRTOS semaphores are given from an ISR using the
fep 0:5ff20db10a96 1953 * xSemaphoreGiveFromISR() API function, the equivalent action that instead uses
fep 0:5ff20db10a96 1954 * a task notification is vTaskNotifyGiveFromISR().
fep 0:5ff20db10a96 1955 *
fep 0:5ff20db10a96 1956 * When task notifications are being used as a binary or counting semaphore
fep 0:5ff20db10a96 1957 * equivalent then the task being notified should wait for the notification
fep 0:5ff20db10a96 1958 * using the ulTaskNotificationTake() API function rather than the
fep 0:5ff20db10a96 1959 * xTaskNotifyWait() API function.
fep 0:5ff20db10a96 1960 *
fep 0:5ff20db10a96 1961 * See http://www.FreeRTOS.org/RTOS-task-notifications.html for more details.
fep 0:5ff20db10a96 1962 *
fep 0:5ff20db10a96 1963 * @param xTaskToNotify The handle of the task being notified. The handle to a
fep 0:5ff20db10a96 1964 * task can be returned from the xTaskCreate() API function used to create the
fep 0:5ff20db10a96 1965 * task, and the handle of the currently running task can be obtained by calling
fep 0:5ff20db10a96 1966 * xTaskGetCurrentTaskHandle().
fep 0:5ff20db10a96 1967 *
fep 0:5ff20db10a96 1968 * @param pxHigherPriorityTaskWoken vTaskNotifyGiveFromISR() will set
fep 0:5ff20db10a96 1969 * *pxHigherPriorityTaskWoken to pdTRUE if sending the notification caused the
fep 0:5ff20db10a96 1970 * task to which the notification was sent to leave the Blocked state, and the
fep 0:5ff20db10a96 1971 * unblocked task has a priority higher than the currently running task. If
fep 0:5ff20db10a96 1972 * vTaskNotifyGiveFromISR() sets this value to pdTRUE then a context switch
fep 0:5ff20db10a96 1973 * should be requested before the interrupt is exited. How a context switch is
fep 0:5ff20db10a96 1974 * requested from an ISR is dependent on the port - see the documentation page
fep 0:5ff20db10a96 1975 * for the port in use.
fep 0:5ff20db10a96 1976 *
fep 0:5ff20db10a96 1977 * \defgroup xTaskNotifyWait xTaskNotifyWait
fep 0:5ff20db10a96 1978 * \ingroup TaskNotifications
fep 0:5ff20db10a96 1979 */
fep 0:5ff20db10a96 1980 void vTaskNotifyGiveFromISR( TaskHandle_t xTaskToNotify, BaseType_t *pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 1981
fep 0:5ff20db10a96 1982 /**
fep 0:5ff20db10a96 1983 * task. h
fep 0:5ff20db10a96 1984 * <PRE>uint32_t ulTaskNotifyTake( BaseType_t xClearCountOnExit, TickType_t xTicksToWait );</pre>
fep 0:5ff20db10a96 1985 *
fep 0:5ff20db10a96 1986 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this
fep 0:5ff20db10a96 1987 * function to be available.
fep 0:5ff20db10a96 1988 *
fep 0:5ff20db10a96 1989 * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private
fep 0:5ff20db10a96 1990 * "notification value", which is a 32-bit unsigned integer (uint32_t).
fep 0:5ff20db10a96 1991 *
fep 0:5ff20db10a96 1992 * Events can be sent to a task using an intermediary object. Examples of such
fep 0:5ff20db10a96 1993 * objects are queues, semaphores, mutexes and event groups. Task notifications
fep 0:5ff20db10a96 1994 * are a method of sending an event directly to a task without the need for such
fep 0:5ff20db10a96 1995 * an intermediary object.
fep 0:5ff20db10a96 1996 *
fep 0:5ff20db10a96 1997 * A notification sent to a task can optionally perform an action, such as
fep 0:5ff20db10a96 1998 * update, overwrite or increment the task's notification value. In that way
fep 0:5ff20db10a96 1999 * task notifications can be used to send data to a task, or be used as light
fep 0:5ff20db10a96 2000 * weight and fast binary or counting semaphores.
fep 0:5ff20db10a96 2001 *
fep 0:5ff20db10a96 2002 * ulTaskNotifyTake() is intended for use when a task notification is used as a
fep 0:5ff20db10a96 2003 * faster and lighter weight binary or counting semaphore alternative. Actual
fep 0:5ff20db10a96 2004 * FreeRTOS semaphores are taken using the xSemaphoreTake() API function, the
fep 0:5ff20db10a96 2005 * equivalent action that instead uses a task notification is
fep 0:5ff20db10a96 2006 * ulTaskNotifyTake().
fep 0:5ff20db10a96 2007 *
fep 0:5ff20db10a96 2008 * When a task is using its notification value as a binary or counting semaphore
fep 0:5ff20db10a96 2009 * other tasks should send notifications to it using the xTaskNotifyGive()
fep 0:5ff20db10a96 2010 * macro, or xTaskNotify() function with the eAction parameter set to
fep 0:5ff20db10a96 2011 * eIncrement.
fep 0:5ff20db10a96 2012 *
fep 0:5ff20db10a96 2013 * ulTaskNotifyTake() can either clear the task's notification value to
fep 0:5ff20db10a96 2014 * zero on exit, in which case the notification value acts like a binary
fep 0:5ff20db10a96 2015 * semaphore, or decrement the task's notification value on exit, in which case
fep 0:5ff20db10a96 2016 * the notification value acts like a counting semaphore.
fep 0:5ff20db10a96 2017 *
fep 0:5ff20db10a96 2018 * A task can use ulTaskNotifyTake() to [optionally] block to wait for a
fep 0:5ff20db10a96 2019 * the task's notification value to be non-zero. The task does not consume any
fep 0:5ff20db10a96 2020 * CPU time while it is in the Blocked state.
fep 0:5ff20db10a96 2021 *
fep 0:5ff20db10a96 2022 * Where as xTaskNotifyWait() will return when a notification is pending,
fep 0:5ff20db10a96 2023 * ulTaskNotifyTake() will return when the task's notification value is
fep 0:5ff20db10a96 2024 * not zero.
fep 0:5ff20db10a96 2025 *
fep 0:5ff20db10a96 2026 * See http://www.FreeRTOS.org/RTOS-task-notifications.html for details.
fep 0:5ff20db10a96 2027 *
fep 0:5ff20db10a96 2028 * @param xClearCountOnExit if xClearCountOnExit is pdFALSE then the task's
fep 0:5ff20db10a96 2029 * notification value is decremented when the function exits. In this way the
fep 0:5ff20db10a96 2030 * notification value acts like a counting semaphore. If xClearCountOnExit is
fep 0:5ff20db10a96 2031 * not pdFALSE then the task's notification value is cleared to zero when the
fep 0:5ff20db10a96 2032 * function exits. In this way the notification value acts like a binary
fep 0:5ff20db10a96 2033 * semaphore.
fep 0:5ff20db10a96 2034 *
fep 0:5ff20db10a96 2035 * @param xTicksToWait The maximum amount of time that the task should wait in
fep 0:5ff20db10a96 2036 * the Blocked state for the task's notification value to be greater than zero,
fep 0:5ff20db10a96 2037 * should the count not already be greater than zero when
fep 0:5ff20db10a96 2038 * ulTaskNotifyTake() was called. The task will not consume any processing
fep 0:5ff20db10a96 2039 * time while it is in the Blocked state. This is specified in kernel ticks,
fep 0:5ff20db10a96 2040 * the macro pdMS_TO_TICSK( value_in_ms ) can be used to convert a time
fep 0:5ff20db10a96 2041 * specified in milliseconds to a time specified in ticks.
fep 0:5ff20db10a96 2042 *
fep 0:5ff20db10a96 2043 * @return The task's notification count before it is either cleared to zero or
fep 0:5ff20db10a96 2044 * decremented (see the xClearCountOnExit parameter).
fep 0:5ff20db10a96 2045 *
fep 0:5ff20db10a96 2046 * \defgroup ulTaskNotifyTake ulTaskNotifyTake
fep 0:5ff20db10a96 2047 * \ingroup TaskNotifications
fep 0:5ff20db10a96 2048 */
fep 0:5ff20db10a96 2049 uint32_t ulTaskNotifyTake( BaseType_t xClearCountOnExit, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 2050
fep 0:5ff20db10a96 2051 /**
fep 0:5ff20db10a96 2052 * task. h
fep 0:5ff20db10a96 2053 * <PRE>BaseType_t xTaskNotifyStateClear( TaskHandle_t xTask );</pre>
fep 0:5ff20db10a96 2054 *
fep 0:5ff20db10a96 2055 * If the notification state of the task referenced by the handle xTask is
fep 0:5ff20db10a96 2056 * eNotified, then set the task's notification state to eNotWaitingNotification.
fep 0:5ff20db10a96 2057 * The task's notification value is not altered. Set xTask to NULL to clear the
fep 0:5ff20db10a96 2058 * notification state of the calling task.
fep 0:5ff20db10a96 2059 *
fep 0:5ff20db10a96 2060 * @return pdTRUE if the task's notification state was set to
fep 0:5ff20db10a96 2061 * eNotWaitingNotification, otherwise pdFALSE.
fep 0:5ff20db10a96 2062 * \defgroup xTaskNotifyStateClear xTaskNotifyStateClear
fep 0:5ff20db10a96 2063 * \ingroup TaskNotifications
fep 0:5ff20db10a96 2064 */
fep 0:5ff20db10a96 2065 BaseType_t xTaskNotifyStateClear( TaskHandle_t xTask );
fep 0:5ff20db10a96 2066
fep 0:5ff20db10a96 2067 /*-----------------------------------------------------------
fep 0:5ff20db10a96 2068 * SCHEDULER INTERNALS AVAILABLE FOR PORTING PURPOSES
fep 0:5ff20db10a96 2069 *----------------------------------------------------------*/
fep 0:5ff20db10a96 2070
fep 0:5ff20db10a96 2071 /*
fep 0:5ff20db10a96 2072 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS ONLY
fep 0:5ff20db10a96 2073 * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS
fep 0:5ff20db10a96 2074 * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
fep 0:5ff20db10a96 2075 *
fep 0:5ff20db10a96 2076 * Called from the real time kernel tick (either preemptive or cooperative),
fep 0:5ff20db10a96 2077 * this increments the tick count and checks if any tasks that are blocked
fep 0:5ff20db10a96 2078 * for a finite period required removing from a blocked list and placing on
fep 0:5ff20db10a96 2079 * a ready list. If a non-zero value is returned then a context switch is
fep 0:5ff20db10a96 2080 * required because either:
fep 0:5ff20db10a96 2081 * + A task was removed from a blocked list because its timeout had expired,
fep 0:5ff20db10a96 2082 * or
fep 0:5ff20db10a96 2083 * + Time slicing is in use and there is a task of equal priority to the
fep 0:5ff20db10a96 2084 * currently running task.
fep 0:5ff20db10a96 2085 */
fep 0:5ff20db10a96 2086 BaseType_t xTaskIncrementTick( void ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 2087
fep 0:5ff20db10a96 2088 /*
fep 0:5ff20db10a96 2089 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN
fep 0:5ff20db10a96 2090 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
fep 0:5ff20db10a96 2091 *
fep 0:5ff20db10a96 2092 * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED.
fep 0:5ff20db10a96 2093 *
fep 0:5ff20db10a96 2094 * Removes the calling task from the ready list and places it both
fep 0:5ff20db10a96 2095 * on the list of tasks waiting for a particular event, and the
fep 0:5ff20db10a96 2096 * list of delayed tasks. The task will be removed from both lists
fep 0:5ff20db10a96 2097 * and replaced on the ready list should either the event occur (and
fep 0:5ff20db10a96 2098 * there be no higher priority tasks waiting on the same event) or
fep 0:5ff20db10a96 2099 * the delay period expires.
fep 0:5ff20db10a96 2100 *
fep 0:5ff20db10a96 2101 * The 'unordered' version replaces the event list item value with the
fep 0:5ff20db10a96 2102 * xItemValue value, and inserts the list item at the end of the list.
fep 0:5ff20db10a96 2103 *
fep 0:5ff20db10a96 2104 * The 'ordered' version uses the existing event list item value (which is the
fep 0:5ff20db10a96 2105 * owning tasks priority) to insert the list item into the event list is task
fep 0:5ff20db10a96 2106 * priority order.
fep 0:5ff20db10a96 2107 *
fep 0:5ff20db10a96 2108 * @param pxEventList The list containing tasks that are blocked waiting
fep 0:5ff20db10a96 2109 * for the event to occur.
fep 0:5ff20db10a96 2110 *
fep 0:5ff20db10a96 2111 * @param xItemValue The item value to use for the event list item when the
fep 0:5ff20db10a96 2112 * event list is not ordered by task priority.
fep 0:5ff20db10a96 2113 *
fep 0:5ff20db10a96 2114 * @param xTicksToWait The maximum amount of time that the task should wait
fep 0:5ff20db10a96 2115 * for the event to occur. This is specified in kernel ticks,the constant
fep 0:5ff20db10a96 2116 * portTICK_PERIOD_MS can be used to convert kernel ticks into a real time
fep 0:5ff20db10a96 2117 * period.
fep 0:5ff20db10a96 2118 */
fep 0:5ff20db10a96 2119 void vTaskPlaceOnEventList( List_t * const pxEventList, const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 2120 void vTaskPlaceOnUnorderedEventList( List_t * pxEventList, const TickType_t xItemValue, const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 2121
fep 0:5ff20db10a96 2122 /*
fep 0:5ff20db10a96 2123 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN
fep 0:5ff20db10a96 2124 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
fep 0:5ff20db10a96 2125 *
fep 0:5ff20db10a96 2126 * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED.
fep 0:5ff20db10a96 2127 *
fep 0:5ff20db10a96 2128 * This function performs nearly the same function as vTaskPlaceOnEventList().
fep 0:5ff20db10a96 2129 * The difference being that this function does not permit tasks to block
fep 0:5ff20db10a96 2130 * indefinitely, whereas vTaskPlaceOnEventList() does.
fep 0:5ff20db10a96 2131 *
fep 0:5ff20db10a96 2132 */
fep 0:5ff20db10a96 2133 void vTaskPlaceOnEventListRestricted( List_t * const pxEventList, TickType_t xTicksToWait, const BaseType_t xWaitIndefinitely ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 2134
fep 0:5ff20db10a96 2135 /*
fep 0:5ff20db10a96 2136 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN
fep 0:5ff20db10a96 2137 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
fep 0:5ff20db10a96 2138 *
fep 0:5ff20db10a96 2139 * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED.
fep 0:5ff20db10a96 2140 *
fep 0:5ff20db10a96 2141 * Removes a task from both the specified event list and the list of blocked
fep 0:5ff20db10a96 2142 * tasks, and places it on a ready queue.
fep 0:5ff20db10a96 2143 *
fep 0:5ff20db10a96 2144 * xTaskRemoveFromEventList()/xTaskRemoveFromUnorderedEventList() will be called
fep 0:5ff20db10a96 2145 * if either an event occurs to unblock a task, or the block timeout period
fep 0:5ff20db10a96 2146 * expires.
fep 0:5ff20db10a96 2147 *
fep 0:5ff20db10a96 2148 * xTaskRemoveFromEventList() is used when the event list is in task priority
fep 0:5ff20db10a96 2149 * order. It removes the list item from the head of the event list as that will
fep 0:5ff20db10a96 2150 * have the highest priority owning task of all the tasks on the event list.
fep 0:5ff20db10a96 2151 * xTaskRemoveFromUnorderedEventList() is used when the event list is not
fep 0:5ff20db10a96 2152 * ordered and the event list items hold something other than the owning tasks
fep 0:5ff20db10a96 2153 * priority. In this case the event list item value is updated to the value
fep 0:5ff20db10a96 2154 * passed in the xItemValue parameter.
fep 0:5ff20db10a96 2155 *
fep 0:5ff20db10a96 2156 * @return pdTRUE if the task being removed has a higher priority than the task
fep 0:5ff20db10a96 2157 * making the call, otherwise pdFALSE.
fep 0:5ff20db10a96 2158 */
fep 0:5ff20db10a96 2159 BaseType_t xTaskRemoveFromEventList( const List_t * const pxEventList ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 2160 BaseType_t xTaskRemoveFromUnorderedEventList( ListItem_t * pxEventListItem, const TickType_t xItemValue ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 2161
fep 0:5ff20db10a96 2162 /*
fep 0:5ff20db10a96 2163 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS ONLY
fep 0:5ff20db10a96 2164 * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS
fep 0:5ff20db10a96 2165 * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
fep 0:5ff20db10a96 2166 *
fep 0:5ff20db10a96 2167 * Sets the pointer to the current TCB to the TCB of the highest priority task
fep 0:5ff20db10a96 2168 * that is ready to run.
fep 0:5ff20db10a96 2169 */
fep 0:5ff20db10a96 2170 void vTaskSwitchContext( void ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 2171
fep 0:5ff20db10a96 2172 /*
fep 0:5ff20db10a96 2173 * THESE FUNCTIONS MUST NOT BE USED FROM APPLICATION CODE. THEY ARE USED BY
fep 0:5ff20db10a96 2174 * THE EVENT BITS MODULE.
fep 0:5ff20db10a96 2175 */
fep 0:5ff20db10a96 2176 TickType_t uxTaskResetEventItemValue( void ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 2177
fep 0:5ff20db10a96 2178 /*
fep 0:5ff20db10a96 2179 * Return the handle of the calling task.
fep 0:5ff20db10a96 2180 */
fep 0:5ff20db10a96 2181 TaskHandle_t xTaskGetCurrentTaskHandle( void ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 2182
fep 0:5ff20db10a96 2183 /*
fep 0:5ff20db10a96 2184 * Capture the current time status for future reference.
fep 0:5ff20db10a96 2185 */
fep 0:5ff20db10a96 2186 void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 2187
fep 0:5ff20db10a96 2188 /*
fep 0:5ff20db10a96 2189 * Compare the time status now with that previously captured to see if the
fep 0:5ff20db10a96 2190 * timeout has expired.
fep 0:5ff20db10a96 2191 */
fep 0:5ff20db10a96 2192 BaseType_t xTaskCheckForTimeOut( TimeOut_t * const pxTimeOut, TickType_t * const pxTicksToWait ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 2193
fep 0:5ff20db10a96 2194 /*
fep 0:5ff20db10a96 2195 * Shortcut used by the queue implementation to prevent unnecessary call to
fep 0:5ff20db10a96 2196 * taskYIELD();
fep 0:5ff20db10a96 2197 */
fep 0:5ff20db10a96 2198 void vTaskMissedYield( void ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 2199
fep 0:5ff20db10a96 2200 /*
fep 0:5ff20db10a96 2201 * Returns the scheduler state as taskSCHEDULER_RUNNING,
fep 0:5ff20db10a96 2202 * taskSCHEDULER_NOT_STARTED or taskSCHEDULER_SUSPENDED.
fep 0:5ff20db10a96 2203 */
fep 0:5ff20db10a96 2204 BaseType_t xTaskGetSchedulerState( void ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 2205
fep 0:5ff20db10a96 2206 /*
fep 0:5ff20db10a96 2207 * Raises the priority of the mutex holder to that of the calling task should
fep 0:5ff20db10a96 2208 * the mutex holder have a priority less than the calling task.
fep 0:5ff20db10a96 2209 */
fep 0:5ff20db10a96 2210 void vTaskPriorityInherit( TaskHandle_t const pxMutexHolder ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 2211
fep 0:5ff20db10a96 2212 /*
fep 0:5ff20db10a96 2213 * Set the priority of a task back to its proper priority in the case that it
fep 0:5ff20db10a96 2214 * inherited a higher priority while it was holding a semaphore.
fep 0:5ff20db10a96 2215 */
fep 0:5ff20db10a96 2216 BaseType_t xTaskPriorityDisinherit( TaskHandle_t const pxMutexHolder ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 2217
fep 0:5ff20db10a96 2218 /*
fep 0:5ff20db10a96 2219 * Get the uxTCBNumber assigned to the task referenced by the xTask parameter.
fep 0:5ff20db10a96 2220 */
fep 0:5ff20db10a96 2221 UBaseType_t uxTaskGetTaskNumber( TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 2222
fep 0:5ff20db10a96 2223 /*
fep 0:5ff20db10a96 2224 * Set the uxTaskNumber of the task referenced by the xTask parameter to
fep 0:5ff20db10a96 2225 * uxHandle.
fep 0:5ff20db10a96 2226 */
fep 0:5ff20db10a96 2227 void vTaskSetTaskNumber( TaskHandle_t xTask, const UBaseType_t uxHandle ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 2228
fep 0:5ff20db10a96 2229 /*
fep 0:5ff20db10a96 2230 * Only available when configUSE_TICKLESS_IDLE is set to 1.
fep 0:5ff20db10a96 2231 * If tickless mode is being used, or a low power mode is implemented, then
fep 0:5ff20db10a96 2232 * the tick interrupt will not execute during idle periods. When this is the
fep 0:5ff20db10a96 2233 * case, the tick count value maintained by the scheduler needs to be kept up
fep 0:5ff20db10a96 2234 * to date with the actual execution time by being skipped forward by a time
fep 0:5ff20db10a96 2235 * equal to the idle period.
fep 0:5ff20db10a96 2236 */
fep 0:5ff20db10a96 2237 void vTaskStepTick( const TickType_t xTicksToJump ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 2238
fep 0:5ff20db10a96 2239 /*
fep 0:5ff20db10a96 2240 * Only avilable when configUSE_TICKLESS_IDLE is set to 1.
fep 0:5ff20db10a96 2241 * Provided for use within portSUPPRESS_TICKS_AND_SLEEP() to allow the port
fep 0:5ff20db10a96 2242 * specific sleep function to determine if it is ok to proceed with the sleep,
fep 0:5ff20db10a96 2243 * and if it is ok to proceed, if it is ok to sleep indefinitely.
fep 0:5ff20db10a96 2244 *
fep 0:5ff20db10a96 2245 * This function is necessary because portSUPPRESS_TICKS_AND_SLEEP() is only
fep 0:5ff20db10a96 2246 * called with the scheduler suspended, not from within a critical section. It
fep 0:5ff20db10a96 2247 * is therefore possible for an interrupt to request a context switch between
fep 0:5ff20db10a96 2248 * portSUPPRESS_TICKS_AND_SLEEP() and the low power mode actually being
fep 0:5ff20db10a96 2249 * entered. eTaskConfirmSleepModeStatus() should be called from a short
fep 0:5ff20db10a96 2250 * critical section between the timer being stopped and the sleep mode being
fep 0:5ff20db10a96 2251 * entered to ensure it is ok to proceed into the sleep mode.
fep 0:5ff20db10a96 2252 */
fep 0:5ff20db10a96 2253 eSleepModeStatus eTaskConfirmSleepModeStatus( void ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 2254
fep 0:5ff20db10a96 2255 /*
fep 0:5ff20db10a96 2256 * For internal use only. Increment the mutex held count when a mutex is
fep 0:5ff20db10a96 2257 * taken and return the handle of the task that has taken the mutex.
fep 0:5ff20db10a96 2258 */
fep 0:5ff20db10a96 2259 void *pvTaskIncrementMutexHeldCount( void ) PRIVILEGED_FUNCTION;
fep 0:5ff20db10a96 2260
fep 0:5ff20db10a96 2261 #ifdef __cplusplus
fep 0:5ff20db10a96 2262 }
fep 0:5ff20db10a96 2263 #endif
fep 0:5ff20db10a96 2264 #endif /* INC_TASK_H */
fep 0:5ff20db10a96 2265
fep 0:5ff20db10a96 2266
fep 0:5ff20db10a96 2267
fep 0:5ff20db10a96 2268