Joao Vieira / FreeRTOS

www.freertos.org

Dependents:   mbed_freeRTOS_send

Fork of FreeRTOS by Rohit Grover

Source/include/task.h@0:8e57f3e9cc89, 2014-01-24 (annotated)

Committer:
rgrover1
Date:
Fri Jan 24 14:56:04 2014 +0000
Revision:
0:8e57f3e9cc89
Making FreeRTOS available as a library

Who changed what in which revision?

UserRevisionLine numberNew contents of line
rgrover1 0:8e57f3e9cc89 1 /*
rgrover1 0:8e57f3e9cc89 2 FreeRTOS V7.6.0 - Copyright (C) 2013 Real Time Engineers Ltd.
rgrover1 0:8e57f3e9cc89 3 All rights reserved
rgrover1 0:8e57f3e9cc89 4
rgrover1 0:8e57f3e9cc89 5 VISIT http://www.FreeRTOS.org TO ENSURE YOU ARE USING THE LATEST VERSION.
rgrover1 0:8e57f3e9cc89 6
rgrover1 0:8e57f3e9cc89 7 ***************************************************************************
rgrover1 0:8e57f3e9cc89 8 * *
rgrover1 0:8e57f3e9cc89 9 * FreeRTOS provides completely free yet professionally developed, *
rgrover1 0:8e57f3e9cc89 10 * robust, strictly quality controlled, supported, and cross *
rgrover1 0:8e57f3e9cc89 11 * platform software that has become a de facto standard. *
rgrover1 0:8e57f3e9cc89 12 * *
rgrover1 0:8e57f3e9cc89 13 * Help yourself get started quickly and support the FreeRTOS *
rgrover1 0:8e57f3e9cc89 14 * project by purchasing a FreeRTOS tutorial book, reference *
rgrover1 0:8e57f3e9cc89 15 * manual, or both from: http://www.FreeRTOS.org/Documentation *
rgrover1 0:8e57f3e9cc89 16 * *
rgrover1 0:8e57f3e9cc89 17 * Thank you! *
rgrover1 0:8e57f3e9cc89 18 * *
rgrover1 0:8e57f3e9cc89 19 ***************************************************************************
rgrover1 0:8e57f3e9cc89 20
rgrover1 0:8e57f3e9cc89 21 This file is part of the FreeRTOS distribution.
rgrover1 0:8e57f3e9cc89 22
rgrover1 0:8e57f3e9cc89 23 FreeRTOS is free software; you can redistribute it and/or modify it under
rgrover1 0:8e57f3e9cc89 24 the terms of the GNU General Public License (version 2) as published by the
rgrover1 0:8e57f3e9cc89 25 Free Software Foundation >>!AND MODIFIED BY!<< the FreeRTOS exception.
rgrover1 0:8e57f3e9cc89 26
rgrover1 0:8e57f3e9cc89 27 >>! NOTE: The modification to the GPL is included to allow you to distribute
rgrover1 0:8e57f3e9cc89 28 >>! a combined work that includes FreeRTOS without being obliged to provide
rgrover1 0:8e57f3e9cc89 29 >>! the source code for proprietary components outside of the FreeRTOS
rgrover1 0:8e57f3e9cc89 30 >>! kernel.
rgrover1 0:8e57f3e9cc89 31
rgrover1 0:8e57f3e9cc89 32 FreeRTOS is distributed in the hope that it will be useful, but WITHOUT ANY
rgrover1 0:8e57f3e9cc89 33 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
rgrover1 0:8e57f3e9cc89 34 FOR A PARTICULAR PURPOSE. Full license text is available from the following
rgrover1 0:8e57f3e9cc89 35 link: http://www.freertos.org/a00114.html
rgrover1 0:8e57f3e9cc89 36
rgrover1 0:8e57f3e9cc89 37 1 tab == 4 spaces!
rgrover1 0:8e57f3e9cc89 38
rgrover1 0:8e57f3e9cc89 39 ***************************************************************************
rgrover1 0:8e57f3e9cc89 40 * *
rgrover1 0:8e57f3e9cc89 41 * Having a problem? Start by reading the FAQ "My application does *
rgrover1 0:8e57f3e9cc89 42 * not run, what could be wrong?" *
rgrover1 0:8e57f3e9cc89 43 * *
rgrover1 0:8e57f3e9cc89 44 * http://www.FreeRTOS.org/FAQHelp.html *
rgrover1 0:8e57f3e9cc89 45 * *
rgrover1 0:8e57f3e9cc89 46 ***************************************************************************
rgrover1 0:8e57f3e9cc89 47
rgrover1 0:8e57f3e9cc89 48 http://www.FreeRTOS.org - Documentation, books, training, latest versions,
rgrover1 0:8e57f3e9cc89 49 license and Real Time Engineers Ltd. contact details.
rgrover1 0:8e57f3e9cc89 50
rgrover1 0:8e57f3e9cc89 51 http://www.FreeRTOS.org/plus - A selection of FreeRTOS ecosystem products,
rgrover1 0:8e57f3e9cc89 52 including FreeRTOS+Trace - an indispensable productivity tool, a DOS
rgrover1 0:8e57f3e9cc89 53 compatible FAT file system, and our tiny thread aware UDP/IP stack.
rgrover1 0:8e57f3e9cc89 54
rgrover1 0:8e57f3e9cc89 55 http://www.OpenRTOS.com - Real Time Engineers ltd license FreeRTOS to High
rgrover1 0:8e57f3e9cc89 56 Integrity Systems to sell under the OpenRTOS brand. Low cost OpenRTOS
rgrover1 0:8e57f3e9cc89 57 licenses offer ticketed support, indemnification and middleware.
rgrover1 0:8e57f3e9cc89 58
rgrover1 0:8e57f3e9cc89 59 http://www.SafeRTOS.com - High Integrity Systems also provide a safety
rgrover1 0:8e57f3e9cc89 60 engineered and independently SIL3 certified version for use in safety and
rgrover1 0:8e57f3e9cc89 61 mission critical applications that require provable dependability.
rgrover1 0:8e57f3e9cc89 62
rgrover1 0:8e57f3e9cc89 63 1 tab == 4 spaces!
rgrover1 0:8e57f3e9cc89 64 */
rgrover1 0:8e57f3e9cc89 65
rgrover1 0:8e57f3e9cc89 66
rgrover1 0:8e57f3e9cc89 67 #ifndef INC_TASK_H
rgrover1 0:8e57f3e9cc89 68 #define INC_TASK_H
rgrover1 0:8e57f3e9cc89 69
rgrover1 0:8e57f3e9cc89 70 #ifndef INC_FREERTOS_H
rgrover1 0:8e57f3e9cc89 71 #error "include FreeRTOS.h must appear in source files before include task.h"
rgrover1 0:8e57f3e9cc89 72 #endif
rgrover1 0:8e57f3e9cc89 73
rgrover1 0:8e57f3e9cc89 74 #include "list.h"
rgrover1 0:8e57f3e9cc89 75
rgrover1 0:8e57f3e9cc89 76 #ifdef __cplusplus
rgrover1 0:8e57f3e9cc89 77 extern "C" {
rgrover1 0:8e57f3e9cc89 78 #endif
rgrover1 0:8e57f3e9cc89 79
rgrover1 0:8e57f3e9cc89 80 /*-----------------------------------------------------------
rgrover1 0:8e57f3e9cc89 81 * MACROS AND DEFINITIONS
rgrover1 0:8e57f3e9cc89 82 *----------------------------------------------------------*/
rgrover1 0:8e57f3e9cc89 83
rgrover1 0:8e57f3e9cc89 84 #define tskKERNEL_VERSION_NUMBER "V7.6.0"
rgrover1 0:8e57f3e9cc89 85
rgrover1 0:8e57f3e9cc89 86 /**
rgrover1 0:8e57f3e9cc89 87 * task. h
rgrover1 0:8e57f3e9cc89 88 *
rgrover1 0:8e57f3e9cc89 89 * Type by which tasks are referenced. For example, a call to xTaskCreate
rgrover1 0:8e57f3e9cc89 90 * returns (via a pointer parameter) an xTaskHandle variable that can then
rgrover1 0:8e57f3e9cc89 91 * be used as a parameter to vTaskDelete to delete the task.
rgrover1 0:8e57f3e9cc89 92 *
rgrover1 0:8e57f3e9cc89 93 * \defgroup xTaskHandle xTaskHandle
rgrover1 0:8e57f3e9cc89 94 * \ingroup Tasks
rgrover1 0:8e57f3e9cc89 95 */
rgrover1 0:8e57f3e9cc89 96 typedef void * xTaskHandle;
rgrover1 0:8e57f3e9cc89 97
rgrover1 0:8e57f3e9cc89 98 /* Task states returned by eTaskGetState. */
rgrover1 0:8e57f3e9cc89 99 typedef enum
rgrover1 0:8e57f3e9cc89 100 {
rgrover1 0:8e57f3e9cc89 101 eRunning = 0, /* A task is querying the state of itself, so must be running. */
rgrover1 0:8e57f3e9cc89 102 eReady, /* The task being queried is in a read or pending ready list. */
rgrover1 0:8e57f3e9cc89 103 eBlocked, /* The task being queried is in the Blocked state. */
rgrover1 0:8e57f3e9cc89 104 eSuspended, /* The task being queried is in the Suspended state, or is in the Blocked state with an infinite time out. */
rgrover1 0:8e57f3e9cc89 105 eDeleted /* The task being queried has been deleted, but its TCB has not yet been freed. */
rgrover1 0:8e57f3e9cc89 106 } eTaskState;
rgrover1 0:8e57f3e9cc89 107
rgrover1 0:8e57f3e9cc89 108 /*
rgrover1 0:8e57f3e9cc89 109 * Used internally only.
rgrover1 0:8e57f3e9cc89 110 */
rgrover1 0:8e57f3e9cc89 111 typedef struct xTIME_OUT
rgrover1 0:8e57f3e9cc89 112 {
rgrover1 0:8e57f3e9cc89 113 portBASE_TYPE xOverflowCount;
rgrover1 0:8e57f3e9cc89 114 portTickType xTimeOnEntering;
rgrover1 0:8e57f3e9cc89 115 } xTimeOutType;
rgrover1 0:8e57f3e9cc89 116
rgrover1 0:8e57f3e9cc89 117 /*
rgrover1 0:8e57f3e9cc89 118 * Defines the memory ranges allocated to the task when an MPU is used.
rgrover1 0:8e57f3e9cc89 119 */
rgrover1 0:8e57f3e9cc89 120 typedef struct xMEMORY_REGION
rgrover1 0:8e57f3e9cc89 121 {
rgrover1 0:8e57f3e9cc89 122 void *pvBaseAddress;
rgrover1 0:8e57f3e9cc89 123 unsigned long ulLengthInBytes;
rgrover1 0:8e57f3e9cc89 124 unsigned long ulParameters;
rgrover1 0:8e57f3e9cc89 125 } xMemoryRegion;
rgrover1 0:8e57f3e9cc89 126
rgrover1 0:8e57f3e9cc89 127 /*
rgrover1 0:8e57f3e9cc89 128 * Parameters required to create an MPU protected task.
rgrover1 0:8e57f3e9cc89 129 */
rgrover1 0:8e57f3e9cc89 130 typedef struct xTASK_PARAMTERS
rgrover1 0:8e57f3e9cc89 131 {
rgrover1 0:8e57f3e9cc89 132 pdTASK_CODE pvTaskCode;
rgrover1 0:8e57f3e9cc89 133 const signed char * const pcName;
rgrover1 0:8e57f3e9cc89 134 unsigned short usStackDepth;
rgrover1 0:8e57f3e9cc89 135 void *pvParameters;
rgrover1 0:8e57f3e9cc89 136 unsigned portBASE_TYPE uxPriority;
rgrover1 0:8e57f3e9cc89 137 portSTACK_TYPE *puxStackBuffer;
rgrover1 0:8e57f3e9cc89 138 xMemoryRegion xRegions[ portNUM_CONFIGURABLE_REGIONS ];
rgrover1 0:8e57f3e9cc89 139 } xTaskParameters;
rgrover1 0:8e57f3e9cc89 140
rgrover1 0:8e57f3e9cc89 141 /* Used with the uxTaskGetSystemState() function to return the state of each task
rgrover1 0:8e57f3e9cc89 142 in the system. */
rgrover1 0:8e57f3e9cc89 143 typedef struct xTASK_STATUS
rgrover1 0:8e57f3e9cc89 144 {
rgrover1 0:8e57f3e9cc89 145 xTaskHandle xHandle; /* The handle of the task to which the rest of the information in the structure relates. */
rgrover1 0:8e57f3e9cc89 146 const signed char *pcTaskName; /* A pointer to the task's name. This value will be invalid if the task was deleted since the structure was populated! */
rgrover1 0:8e57f3e9cc89 147 unsigned portBASE_TYPE xTaskNumber; /* A number unique to the task. */
rgrover1 0:8e57f3e9cc89 148 eTaskState eCurrentState; /* The state in which the task existed when the structure was populated. */
rgrover1 0:8e57f3e9cc89 149 unsigned portBASE_TYPE uxCurrentPriority; /* The priority at which the task was running (may be inherited) when the structure was populated. */
rgrover1 0:8e57f3e9cc89 150 unsigned portBASE_TYPE uxBasePriority; /* The priority to which the task will return if the task's current priority has been inherited to avoid unbounded priority inversion when obtaining a mutex. Only valid if configUSE_MUTEXES is defined as 1 in FreeRTOSConfig.h. */
rgrover1 0:8e57f3e9cc89 151 unsigned long ulRunTimeCounter; /* The total run time allocated to the task so far, as defined by the run time stats clock. See http://www.freertos.org/rtos-run-time-stats.html. Only valid when configGENERATE_RUN_TIME_STATS is defined as 1 in FreeRTOSConfig.h. */
rgrover1 0:8e57f3e9cc89 152 unsigned short usStackHighWaterMark; /* The minimum amount of stack space that has remained for the task since the task was created. The closer this value is to zero the closer the task has come to overflowing its stack. */
rgrover1 0:8e57f3e9cc89 153 } xTaskStatusType;
rgrover1 0:8e57f3e9cc89 154
rgrover1 0:8e57f3e9cc89 155 /* Possible return values for eTaskConfirmSleepModeStatus(). */
rgrover1 0:8e57f3e9cc89 156 typedef enum
rgrover1 0:8e57f3e9cc89 157 {
rgrover1 0:8e57f3e9cc89 158 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. */
rgrover1 0:8e57f3e9cc89 159 eStandardSleep, /* Enter a sleep mode that will not last any longer than the expected idle time. */
rgrover1 0:8e57f3e9cc89 160 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. */
rgrover1 0:8e57f3e9cc89 161 } eSleepModeStatus;
rgrover1 0:8e57f3e9cc89 162
rgrover1 0:8e57f3e9cc89 163
rgrover1 0:8e57f3e9cc89 164 /*
rgrover1 0:8e57f3e9cc89 165 * Defines the priority used by the idle task. This must not be modified.
rgrover1 0:8e57f3e9cc89 166 *
rgrover1 0:8e57f3e9cc89 167 * \ingroup TaskUtils
rgrover1 0:8e57f3e9cc89 168 */
rgrover1 0:8e57f3e9cc89 169 #define tskIDLE_PRIORITY ( ( unsigned portBASE_TYPE ) 0U )
rgrover1 0:8e57f3e9cc89 170
rgrover1 0:8e57f3e9cc89 171 /**
rgrover1 0:8e57f3e9cc89 172 * task. h
rgrover1 0:8e57f3e9cc89 173 *
rgrover1 0:8e57f3e9cc89 174 * Macro for forcing a context switch.
rgrover1 0:8e57f3e9cc89 175 *
rgrover1 0:8e57f3e9cc89 176 * \defgroup taskYIELD taskYIELD
rgrover1 0:8e57f3e9cc89 177 * \ingroup SchedulerControl
rgrover1 0:8e57f3e9cc89 178 */
rgrover1 0:8e57f3e9cc89 179 #define taskYIELD() portYIELD()
rgrover1 0:8e57f3e9cc89 180
rgrover1 0:8e57f3e9cc89 181 /**
rgrover1 0:8e57f3e9cc89 182 * task. h
rgrover1 0:8e57f3e9cc89 183 *
rgrover1 0:8e57f3e9cc89 184 * Macro to mark the start of a critical code region. Preemptive context
rgrover1 0:8e57f3e9cc89 185 * switches cannot occur when in a critical region.
rgrover1 0:8e57f3e9cc89 186 *
rgrover1 0:8e57f3e9cc89 187 * NOTE: This may alter the stack (depending on the portable implementation)
rgrover1 0:8e57f3e9cc89 188 * so must be used with care!
rgrover1 0:8e57f3e9cc89 189 *
rgrover1 0:8e57f3e9cc89 190 * \defgroup taskENTER_CRITICAL taskENTER_CRITICAL
rgrover1 0:8e57f3e9cc89 191 * \ingroup SchedulerControl
rgrover1 0:8e57f3e9cc89 192 */
rgrover1 0:8e57f3e9cc89 193 #define taskENTER_CRITICAL() portENTER_CRITICAL()
rgrover1 0:8e57f3e9cc89 194
rgrover1 0:8e57f3e9cc89 195 /**
rgrover1 0:8e57f3e9cc89 196 * task. h
rgrover1 0:8e57f3e9cc89 197 *
rgrover1 0:8e57f3e9cc89 198 * Macro to mark the end of a critical code region. Preemptive context
rgrover1 0:8e57f3e9cc89 199 * switches cannot occur when in a critical region.
rgrover1 0:8e57f3e9cc89 200 *
rgrover1 0:8e57f3e9cc89 201 * NOTE: This may alter the stack (depending on the portable implementation)
rgrover1 0:8e57f3e9cc89 202 * so must be used with care!
rgrover1 0:8e57f3e9cc89 203 *
rgrover1 0:8e57f3e9cc89 204 * \defgroup taskEXIT_CRITICAL taskEXIT_CRITICAL
rgrover1 0:8e57f3e9cc89 205 * \ingroup SchedulerControl
rgrover1 0:8e57f3e9cc89 206 */
rgrover1 0:8e57f3e9cc89 207 #define taskEXIT_CRITICAL() portEXIT_CRITICAL()
rgrover1 0:8e57f3e9cc89 208
rgrover1 0:8e57f3e9cc89 209 /**
rgrover1 0:8e57f3e9cc89 210 * task. h
rgrover1 0:8e57f3e9cc89 211 *
rgrover1 0:8e57f3e9cc89 212 * Macro to disable all maskable interrupts.
rgrover1 0:8e57f3e9cc89 213 *
rgrover1 0:8e57f3e9cc89 214 * \defgroup taskDISABLE_INTERRUPTS taskDISABLE_INTERRUPTS
rgrover1 0:8e57f3e9cc89 215 * \ingroup SchedulerControl
rgrover1 0:8e57f3e9cc89 216 */
rgrover1 0:8e57f3e9cc89 217 #define taskDISABLE_INTERRUPTS() portDISABLE_INTERRUPTS()
rgrover1 0:8e57f3e9cc89 218
rgrover1 0:8e57f3e9cc89 219 /**
rgrover1 0:8e57f3e9cc89 220 * task. h
rgrover1 0:8e57f3e9cc89 221 *
rgrover1 0:8e57f3e9cc89 222 * Macro to enable microcontroller interrupts.
rgrover1 0:8e57f3e9cc89 223 *
rgrover1 0:8e57f3e9cc89 224 * \defgroup taskENABLE_INTERRUPTS taskENABLE_INTERRUPTS
rgrover1 0:8e57f3e9cc89 225 * \ingroup SchedulerControl
rgrover1 0:8e57f3e9cc89 226 */
rgrover1 0:8e57f3e9cc89 227 #define taskENABLE_INTERRUPTS() portENABLE_INTERRUPTS()
rgrover1 0:8e57f3e9cc89 228
rgrover1 0:8e57f3e9cc89 229 /* Definitions returned by xTaskGetSchedulerState(). */
rgrover1 0:8e57f3e9cc89 230 #define taskSCHEDULER_NOT_STARTED ( ( portBASE_TYPE ) 0 )
rgrover1 0:8e57f3e9cc89 231 #define taskSCHEDULER_RUNNING ( ( portBASE_TYPE ) 1 )
rgrover1 0:8e57f3e9cc89 232 #define taskSCHEDULER_SUSPENDED ( ( portBASE_TYPE ) 2 )
rgrover1 0:8e57f3e9cc89 233
rgrover1 0:8e57f3e9cc89 234 /*-----------------------------------------------------------
rgrover1 0:8e57f3e9cc89 235 * TASK CREATION API
rgrover1 0:8e57f3e9cc89 236 *----------------------------------------------------------*/
rgrover1 0:8e57f3e9cc89 237
rgrover1 0:8e57f3e9cc89 238 /**
rgrover1 0:8e57f3e9cc89 239 * task. h
rgrover1 0:8e57f3e9cc89 240 *<pre>
rgrover1 0:8e57f3e9cc89 241 portBASE_TYPE xTaskCreate(
rgrover1 0:8e57f3e9cc89 242 pdTASK_CODE pvTaskCode,
rgrover1 0:8e57f3e9cc89 243 const char * const pcName,
rgrover1 0:8e57f3e9cc89 244 unsigned short usStackDepth,
rgrover1 0:8e57f3e9cc89 245 void *pvParameters,
rgrover1 0:8e57f3e9cc89 246 unsigned portBASE_TYPE uxPriority,
rgrover1 0:8e57f3e9cc89 247 xTaskHandle *pvCreatedTask
rgrover1 0:8e57f3e9cc89 248 );</pre>
rgrover1 0:8e57f3e9cc89 249 *
rgrover1 0:8e57f3e9cc89 250 * Create a new task and add it to the list of tasks that are ready to run.
rgrover1 0:8e57f3e9cc89 251 *
rgrover1 0:8e57f3e9cc89 252 * xTaskCreate() can only be used to create a task that has unrestricted
rgrover1 0:8e57f3e9cc89 253 * access to the entire microcontroller memory map. Systems that include MPU
rgrover1 0:8e57f3e9cc89 254 * support can alternatively create an MPU constrained task using
rgrover1 0:8e57f3e9cc89 255 * xTaskCreateRestricted().
rgrover1 0:8e57f3e9cc89 256 *
rgrover1 0:8e57f3e9cc89 257 * @param pvTaskCode Pointer to the task entry function. Tasks
rgrover1 0:8e57f3e9cc89 258 * must be implemented to never return (i.e. continuous loop).
rgrover1 0:8e57f3e9cc89 259 *
rgrover1 0:8e57f3e9cc89 260 * @param pcName A descriptive name for the task. This is mainly used to
rgrover1 0:8e57f3e9cc89 261 * facilitate debugging. Max length defined by tskMAX_TASK_NAME_LEN - default
rgrover1 0:8e57f3e9cc89 262 * is 16.
rgrover1 0:8e57f3e9cc89 263 *
rgrover1 0:8e57f3e9cc89 264 * @param usStackDepth The size of the task stack specified as the number of
rgrover1 0:8e57f3e9cc89 265 * variables the stack can hold - not the number of bytes. For example, if
rgrover1 0:8e57f3e9cc89 266 * the stack is 16 bits wide and usStackDepth is defined as 100, 200 bytes
rgrover1 0:8e57f3e9cc89 267 * will be allocated for stack storage.
rgrover1 0:8e57f3e9cc89 268 *
rgrover1 0:8e57f3e9cc89 269 * @param pvParameters Pointer that will be used as the parameter for the task
rgrover1 0:8e57f3e9cc89 270 * being created.
rgrover1 0:8e57f3e9cc89 271 *
rgrover1 0:8e57f3e9cc89 272 * @param uxPriority The priority at which the task should run. Systems that
rgrover1 0:8e57f3e9cc89 273 * include MPU support can optionally create tasks in a privileged (system)
rgrover1 0:8e57f3e9cc89 274 * mode by setting bit portPRIVILEGE_BIT of the priority parameter. For
rgrover1 0:8e57f3e9cc89 275 * example, to create a privileged task at priority 2 the uxPriority parameter
rgrover1 0:8e57f3e9cc89 276 * should be set to ( 2 | portPRIVILEGE_BIT ).
rgrover1 0:8e57f3e9cc89 277 *
rgrover1 0:8e57f3e9cc89 278 * @param pvCreatedTask Used to pass back a handle by which the created task
rgrover1 0:8e57f3e9cc89 279 * can be referenced.
rgrover1 0:8e57f3e9cc89 280 *
rgrover1 0:8e57f3e9cc89 281 * @return pdPASS if the task was successfully created and added to a ready
rgrover1 0:8e57f3e9cc89 282 * list, otherwise an error code defined in the file errors. h
rgrover1 0:8e57f3e9cc89 283 *
rgrover1 0:8e57f3e9cc89 284 * Example usage:
rgrover1 0:8e57f3e9cc89 285 <pre>
rgrover1 0:8e57f3e9cc89 286 // Task to be created.
rgrover1 0:8e57f3e9cc89 287 void vTaskCode( void * pvParameters )
rgrover1 0:8e57f3e9cc89 288 {
rgrover1 0:8e57f3e9cc89 289 for( ;; )
rgrover1 0:8e57f3e9cc89 290 {
rgrover1 0:8e57f3e9cc89 291 // Task code goes here.
rgrover1 0:8e57f3e9cc89 292 }
rgrover1 0:8e57f3e9cc89 293 }
rgrover1 0:8e57f3e9cc89 294
rgrover1 0:8e57f3e9cc89 295 // Function that creates a task.
rgrover1 0:8e57f3e9cc89 296 void vOtherFunction( void )
rgrover1 0:8e57f3e9cc89 297 {
rgrover1 0:8e57f3e9cc89 298 static unsigned char ucParameterToPass;
rgrover1 0:8e57f3e9cc89 299 xTaskHandle xHandle;
rgrover1 0:8e57f3e9cc89 300
rgrover1 0:8e57f3e9cc89 301 // Create the task, storing the handle. Note that the passed parameter ucParameterToPass
rgrover1 0:8e57f3e9cc89 302 // must exist for the lifetime of the task, so in this case is declared static. If it was just an
rgrover1 0:8e57f3e9cc89 303 // an automatic stack variable it might no longer exist, or at least have been corrupted, by the time
rgrover1 0:8e57f3e9cc89 304 // the new task attempts to access it.
rgrover1 0:8e57f3e9cc89 305 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, &ucParameterToPass, tskIDLE_PRIORITY, &xHandle );
rgrover1 0:8e57f3e9cc89 306
rgrover1 0:8e57f3e9cc89 307 // Use the handle to delete the task.
rgrover1 0:8e57f3e9cc89 308 vTaskDelete( xHandle );
rgrover1 0:8e57f3e9cc89 309 }
rgrover1 0:8e57f3e9cc89 310 </pre>
rgrover1 0:8e57f3e9cc89 311 * \defgroup xTaskCreate xTaskCreate
rgrover1 0:8e57f3e9cc89 312 * \ingroup Tasks
rgrover1 0:8e57f3e9cc89 313 */
rgrover1 0:8e57f3e9cc89 314 #define xTaskCreate( pvTaskCode, pcName, usStackDepth, pvParameters, uxPriority, pxCreatedTask ) xTaskGenericCreate( ( pvTaskCode ), ( pcName ), ( usStackDepth ), ( pvParameters ), ( uxPriority ), ( pxCreatedTask ), ( NULL ), ( NULL ) )
rgrover1 0:8e57f3e9cc89 315
rgrover1 0:8e57f3e9cc89 316 /**
rgrover1 0:8e57f3e9cc89 317 * task. h
rgrover1 0:8e57f3e9cc89 318 *<pre>
rgrover1 0:8e57f3e9cc89 319 portBASE_TYPE xTaskCreateRestricted( xTaskParameters *pxTaskDefinition, xTaskHandle *pxCreatedTask );</pre>
rgrover1 0:8e57f3e9cc89 320 *
rgrover1 0:8e57f3e9cc89 321 * xTaskCreateRestricted() should only be used in systems that include an MPU
rgrover1 0:8e57f3e9cc89 322 * implementation.
rgrover1 0:8e57f3e9cc89 323 *
rgrover1 0:8e57f3e9cc89 324 * Create a new task and add it to the list of tasks that are ready to run.
rgrover1 0:8e57f3e9cc89 325 * The function parameters define the memory regions and associated access
rgrover1 0:8e57f3e9cc89 326 * permissions allocated to the task.
rgrover1 0:8e57f3e9cc89 327 *
rgrover1 0:8e57f3e9cc89 328 * @param pxTaskDefinition Pointer to a structure that contains a member
rgrover1 0:8e57f3e9cc89 329 * for each of the normal xTaskCreate() parameters (see the xTaskCreate() API
rgrover1 0:8e57f3e9cc89 330 * documentation) plus an optional stack buffer and the memory region
rgrover1 0:8e57f3e9cc89 331 * definitions.
rgrover1 0:8e57f3e9cc89 332 *
rgrover1 0:8e57f3e9cc89 333 * @param pxCreatedTask Used to pass back a handle by which the created task
rgrover1 0:8e57f3e9cc89 334 * can be referenced.
rgrover1 0:8e57f3e9cc89 335 *
rgrover1 0:8e57f3e9cc89 336 * @return pdPASS if the task was successfully created and added to a ready
rgrover1 0:8e57f3e9cc89 337 * list, otherwise an error code defined in the file errors. h
rgrover1 0:8e57f3e9cc89 338 *
rgrover1 0:8e57f3e9cc89 339 * Example usage:
rgrover1 0:8e57f3e9cc89 340 <pre>
rgrover1 0:8e57f3e9cc89 341 // Create an xTaskParameters structure that defines the task to be created.
rgrover1 0:8e57f3e9cc89 342 static const xTaskParameters xCheckTaskParameters =
rgrover1 0:8e57f3e9cc89 343 {
rgrover1 0:8e57f3e9cc89 344 vATask, // pvTaskCode - the function that implements the task.
rgrover1 0:8e57f3e9cc89 345 "ATask", // pcName - just a text name for the task to assist debugging.
rgrover1 0:8e57f3e9cc89 346 100, // usStackDepth - the stack size DEFINED IN WORDS.
rgrover1 0:8e57f3e9cc89 347 NULL, // pvParameters - passed into the task function as the function parameters.
rgrover1 0:8e57f3e9cc89 348 ( 1UL | portPRIVILEGE_BIT ),// uxPriority - task priority, set the portPRIVILEGE_BIT if the task should run in a privileged state.
rgrover1 0:8e57f3e9cc89 349 cStackBuffer,// puxStackBuffer - the buffer to be used as the task stack.
rgrover1 0:8e57f3e9cc89 350
rgrover1 0:8e57f3e9cc89 351 // xRegions - Allocate up to three separate memory regions for access by
rgrover1 0:8e57f3e9cc89 352 // the task, with appropriate access permissions. Different processors have
rgrover1 0:8e57f3e9cc89 353 // different memory alignment requirements - refer to the FreeRTOS documentation
rgrover1 0:8e57f3e9cc89 354 // for full information.
rgrover1 0:8e57f3e9cc89 355 {
rgrover1 0:8e57f3e9cc89 356 // Base address Length Parameters
rgrover1 0:8e57f3e9cc89 357 { cReadWriteArray, 32, portMPU_REGION_READ_WRITE },
rgrover1 0:8e57f3e9cc89 358 { cReadOnlyArray, 32, portMPU_REGION_READ_ONLY },
rgrover1 0:8e57f3e9cc89 359 { cPrivilegedOnlyAccessArray, 128, portMPU_REGION_PRIVILEGED_READ_WRITE }
rgrover1 0:8e57f3e9cc89 360 }
rgrover1 0:8e57f3e9cc89 361 };
rgrover1 0:8e57f3e9cc89 362
rgrover1 0:8e57f3e9cc89 363 int main( void )
rgrover1 0:8e57f3e9cc89 364 {
rgrover1 0:8e57f3e9cc89 365 xTaskHandle xHandle;
rgrover1 0:8e57f3e9cc89 366
rgrover1 0:8e57f3e9cc89 367 // Create a task from the const structure defined above. The task handle
rgrover1 0:8e57f3e9cc89 368 // is requested (the second parameter is not NULL) but in this case just for
rgrover1 0:8e57f3e9cc89 369 // demonstration purposes as its not actually used.
rgrover1 0:8e57f3e9cc89 370 xTaskCreateRestricted( &xRegTest1Parameters, &xHandle );
rgrover1 0:8e57f3e9cc89 371
rgrover1 0:8e57f3e9cc89 372 // Start the scheduler.
rgrover1 0:8e57f3e9cc89 373 vTaskStartScheduler();
rgrover1 0:8e57f3e9cc89 374
rgrover1 0:8e57f3e9cc89 375 // Will only get here if there was insufficient memory to create the idle
rgrover1 0:8e57f3e9cc89 376 // task.
rgrover1 0:8e57f3e9cc89 377 for( ;; );
rgrover1 0:8e57f3e9cc89 378 }
rgrover1 0:8e57f3e9cc89 379 </pre>
rgrover1 0:8e57f3e9cc89 380 * \defgroup xTaskCreateRestricted xTaskCreateRestricted
rgrover1 0:8e57f3e9cc89 381 * \ingroup Tasks
rgrover1 0:8e57f3e9cc89 382 */
rgrover1 0:8e57f3e9cc89 383 #define xTaskCreateRestricted( x, pxCreatedTask ) xTaskGenericCreate( ((x)->pvTaskCode), ((x)->pcName), ((x)->usStackDepth), ((x)->pvParameters), ((x)->uxPriority), (pxCreatedTask), ((x)->puxStackBuffer), ((x)->xRegions) )
rgrover1 0:8e57f3e9cc89 384
rgrover1 0:8e57f3e9cc89 385 /**
rgrover1 0:8e57f3e9cc89 386 * task. h
rgrover1 0:8e57f3e9cc89 387 *<pre>
rgrover1 0:8e57f3e9cc89 388 void vTaskAllocateMPURegions( xTaskHandle xTask, const xMemoryRegion * const pxRegions );</pre>
rgrover1 0:8e57f3e9cc89 389 *
rgrover1 0:8e57f3e9cc89 390 * Memory regions are assigned to a restricted task when the task is created by
rgrover1 0:8e57f3e9cc89 391 * a call to xTaskCreateRestricted(). These regions can be redefined using
rgrover1 0:8e57f3e9cc89 392 * vTaskAllocateMPURegions().
rgrover1 0:8e57f3e9cc89 393 *
rgrover1 0:8e57f3e9cc89 394 * @param xTask The handle of the task being updated.
rgrover1 0:8e57f3e9cc89 395 *
rgrover1 0:8e57f3e9cc89 396 * @param xRegions A pointer to an xMemoryRegion structure that contains the
rgrover1 0:8e57f3e9cc89 397 * new memory region definitions.
rgrover1 0:8e57f3e9cc89 398 *
rgrover1 0:8e57f3e9cc89 399 * Example usage:
rgrover1 0:8e57f3e9cc89 400 <pre>
rgrover1 0:8e57f3e9cc89 401 // Define an array of xMemoryRegion structures that configures an MPU region
rgrover1 0:8e57f3e9cc89 402 // allowing read/write access for 1024 bytes starting at the beginning of the
rgrover1 0:8e57f3e9cc89 403 // ucOneKByte array. The other two of the maximum 3 definable regions are
rgrover1 0:8e57f3e9cc89 404 // unused so set to zero.
rgrover1 0:8e57f3e9cc89 405 static const xMemoryRegion xAltRegions[ portNUM_CONFIGURABLE_REGIONS ] =
rgrover1 0:8e57f3e9cc89 406 {
rgrover1 0:8e57f3e9cc89 407 // Base address Length Parameters
rgrover1 0:8e57f3e9cc89 408 { ucOneKByte, 1024, portMPU_REGION_READ_WRITE },
rgrover1 0:8e57f3e9cc89 409 { 0, 0, 0 },
rgrover1 0:8e57f3e9cc89 410 { 0, 0, 0 }
rgrover1 0:8e57f3e9cc89 411 };
rgrover1 0:8e57f3e9cc89 412
rgrover1 0:8e57f3e9cc89 413 void vATask( void *pvParameters )
rgrover1 0:8e57f3e9cc89 414 {
rgrover1 0:8e57f3e9cc89 415 // This task was created such that it has access to certain regions of
rgrover1 0:8e57f3e9cc89 416 // memory as defined by the MPU configuration. At some point it is
rgrover1 0:8e57f3e9cc89 417 // desired that these MPU regions are replaced with that defined in the
rgrover1 0:8e57f3e9cc89 418 // xAltRegions const struct above. Use a call to vTaskAllocateMPURegions()
rgrover1 0:8e57f3e9cc89 419 // for this purpose. NULL is used as the task handle to indicate that this
rgrover1 0:8e57f3e9cc89 420 // function should modify the MPU regions of the calling task.
rgrover1 0:8e57f3e9cc89 421 vTaskAllocateMPURegions( NULL, xAltRegions );
rgrover1 0:8e57f3e9cc89 422
rgrover1 0:8e57f3e9cc89 423 // Now the task can continue its function, but from this point on can only
rgrover1 0:8e57f3e9cc89 424 // access its stack and the ucOneKByte array (unless any other statically
rgrover1 0:8e57f3e9cc89 425 // defined or shared regions have been declared elsewhere).
rgrover1 0:8e57f3e9cc89 426 }
rgrover1 0:8e57f3e9cc89 427 </pre>
rgrover1 0:8e57f3e9cc89 428 * \defgroup xTaskCreateRestricted xTaskCreateRestricted
rgrover1 0:8e57f3e9cc89 429 * \ingroup Tasks
rgrover1 0:8e57f3e9cc89 430 */
rgrover1 0:8e57f3e9cc89 431 void vTaskAllocateMPURegions( xTaskHandle xTask, const xMemoryRegion * const pxRegions ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 432
rgrover1 0:8e57f3e9cc89 433 /**
rgrover1 0:8e57f3e9cc89 434 * task. h
rgrover1 0:8e57f3e9cc89 435 * <pre>void vTaskDelete( xTaskHandle xTask );</pre>
rgrover1 0:8e57f3e9cc89 436 *
rgrover1 0:8e57f3e9cc89 437 * INCLUDE_vTaskDelete must be defined as 1 for this function to be available.
rgrover1 0:8e57f3e9cc89 438 * See the configuration section for more information.
rgrover1 0:8e57f3e9cc89 439 *
rgrover1 0:8e57f3e9cc89 440 * Remove a task from the RTOS real time kernels management. The task being
rgrover1 0:8e57f3e9cc89 441 * deleted will be removed from all ready, blocked, suspended and event lists.
rgrover1 0:8e57f3e9cc89 442 *
rgrover1 0:8e57f3e9cc89 443 * NOTE: The idle task is responsible for freeing the kernel allocated
rgrover1 0:8e57f3e9cc89 444 * memory from tasks that have been deleted. It is therefore important that
rgrover1 0:8e57f3e9cc89 445 * the idle task is not starved of microcontroller processing time if your
rgrover1 0:8e57f3e9cc89 446 * application makes any calls to vTaskDelete (). Memory allocated by the
rgrover1 0:8e57f3e9cc89 447 * task code is not automatically freed, and should be freed before the task
rgrover1 0:8e57f3e9cc89 448 * is deleted.
rgrover1 0:8e57f3e9cc89 449 *
rgrover1 0:8e57f3e9cc89 450 * See the demo application file death.c for sample code that utilises
rgrover1 0:8e57f3e9cc89 451 * vTaskDelete ().
rgrover1 0:8e57f3e9cc89 452 *
rgrover1 0:8e57f3e9cc89 453 * @param xTask The handle of the task to be deleted. Passing NULL will
rgrover1 0:8e57f3e9cc89 454 * cause the calling task to be deleted.
rgrover1 0:8e57f3e9cc89 455 *
rgrover1 0:8e57f3e9cc89 456 * Example usage:
rgrover1 0:8e57f3e9cc89 457 <pre>
rgrover1 0:8e57f3e9cc89 458 void vOtherFunction( void )
rgrover1 0:8e57f3e9cc89 459 {
rgrover1 0:8e57f3e9cc89 460 xTaskHandle xHandle;
rgrover1 0:8e57f3e9cc89 461
rgrover1 0:8e57f3e9cc89 462 // Create the task, storing the handle.
rgrover1 0:8e57f3e9cc89 463 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
rgrover1 0:8e57f3e9cc89 464
rgrover1 0:8e57f3e9cc89 465 // Use the handle to delete the task.
rgrover1 0:8e57f3e9cc89 466 vTaskDelete( xHandle );
rgrover1 0:8e57f3e9cc89 467 }
rgrover1 0:8e57f3e9cc89 468 </pre>
rgrover1 0:8e57f3e9cc89 469 * \defgroup vTaskDelete vTaskDelete
rgrover1 0:8e57f3e9cc89 470 * \ingroup Tasks
rgrover1 0:8e57f3e9cc89 471 */
rgrover1 0:8e57f3e9cc89 472 void vTaskDelete( xTaskHandle xTaskToDelete ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 473
rgrover1 0:8e57f3e9cc89 474 /*-----------------------------------------------------------
rgrover1 0:8e57f3e9cc89 475 * TASK CONTROL API
rgrover1 0:8e57f3e9cc89 476 *----------------------------------------------------------*/
rgrover1 0:8e57f3e9cc89 477
rgrover1 0:8e57f3e9cc89 478 /**
rgrover1 0:8e57f3e9cc89 479 * task. h
rgrover1 0:8e57f3e9cc89 480 * <pre>void vTaskDelay( portTickType xTicksToDelay );</pre>
rgrover1 0:8e57f3e9cc89 481 *
rgrover1 0:8e57f3e9cc89 482 * Delay a task for a given number of ticks. The actual time that the
rgrover1 0:8e57f3e9cc89 483 * task remains blocked depends on the tick rate. The constant
rgrover1 0:8e57f3e9cc89 484 * portTICK_RATE_MS can be used to calculate real time from the tick
rgrover1 0:8e57f3e9cc89 485 * rate - with the resolution of one tick period.
rgrover1 0:8e57f3e9cc89 486 *
rgrover1 0:8e57f3e9cc89 487 * INCLUDE_vTaskDelay must be defined as 1 for this function to be available.
rgrover1 0:8e57f3e9cc89 488 * See the configuration section for more information.
rgrover1 0:8e57f3e9cc89 489 *
rgrover1 0:8e57f3e9cc89 490 *
rgrover1 0:8e57f3e9cc89 491 * vTaskDelay() specifies a time at which the task wishes to unblock relative to
rgrover1 0:8e57f3e9cc89 492 * the time at which vTaskDelay() is called. For example, specifying a block
rgrover1 0:8e57f3e9cc89 493 * period of 100 ticks will cause the task to unblock 100 ticks after
rgrover1 0:8e57f3e9cc89 494 * vTaskDelay() is called. vTaskDelay() does not therefore provide a good method
rgrover1 0:8e57f3e9cc89 495 * of controlling the frequency of a cyclical task as the path taken through the
rgrover1 0:8e57f3e9cc89 496 * code, as well as other task and interrupt activity, will effect the frequency
rgrover1 0:8e57f3e9cc89 497 * at which vTaskDelay() gets called and therefore the time at which the task
rgrover1 0:8e57f3e9cc89 498 * next executes. See vTaskDelayUntil() for an alternative API function designed
rgrover1 0:8e57f3e9cc89 499 * to facilitate fixed frequency execution. It does this by specifying an
rgrover1 0:8e57f3e9cc89 500 * absolute time (rather than a relative time) at which the calling task should
rgrover1 0:8e57f3e9cc89 501 * unblock.
rgrover1 0:8e57f3e9cc89 502 *
rgrover1 0:8e57f3e9cc89 503 * @param xTicksToDelay The amount of time, in tick periods, that
rgrover1 0:8e57f3e9cc89 504 * the calling task should block.
rgrover1 0:8e57f3e9cc89 505 *
rgrover1 0:8e57f3e9cc89 506 * Example usage:
rgrover1 0:8e57f3e9cc89 507
rgrover1 0:8e57f3e9cc89 508 void vTaskFunction( void * pvParameters )
rgrover1 0:8e57f3e9cc89 509 {
rgrover1 0:8e57f3e9cc89 510 void vTaskFunction( void * pvParameters )
rgrover1 0:8e57f3e9cc89 511 {
rgrover1 0:8e57f3e9cc89 512 // Block for 500ms.
rgrover1 0:8e57f3e9cc89 513 const portTickType xDelay = 500 / portTICK_RATE_MS;
rgrover1 0:8e57f3e9cc89 514
rgrover1 0:8e57f3e9cc89 515 for( ;; )
rgrover1 0:8e57f3e9cc89 516 {
rgrover1 0:8e57f3e9cc89 517 // Simply toggle the LED every 500ms, blocking between each toggle.
rgrover1 0:8e57f3e9cc89 518 vToggleLED();
rgrover1 0:8e57f3e9cc89 519 vTaskDelay( xDelay );
rgrover1 0:8e57f3e9cc89 520 }
rgrover1 0:8e57f3e9cc89 521 }
rgrover1 0:8e57f3e9cc89 522
rgrover1 0:8e57f3e9cc89 523 * \defgroup vTaskDelay vTaskDelay
rgrover1 0:8e57f3e9cc89 524 * \ingroup TaskCtrl
rgrover1 0:8e57f3e9cc89 525 */
rgrover1 0:8e57f3e9cc89 526 void vTaskDelay( portTickType xTicksToDelay ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 527
rgrover1 0:8e57f3e9cc89 528 /**
rgrover1 0:8e57f3e9cc89 529 * task. h
rgrover1 0:8e57f3e9cc89 530 * <pre>void vTaskDelayUntil( portTickType *pxPreviousWakeTime, portTickType xTimeIncrement );</pre>
rgrover1 0:8e57f3e9cc89 531 *
rgrover1 0:8e57f3e9cc89 532 * INCLUDE_vTaskDelayUntil must be defined as 1 for this function to be available.
rgrover1 0:8e57f3e9cc89 533 * See the configuration section for more information.
rgrover1 0:8e57f3e9cc89 534 *
rgrover1 0:8e57f3e9cc89 535 * Delay a task until a specified time. This function can be used by cyclical
rgrover1 0:8e57f3e9cc89 536 * tasks to ensure a constant execution frequency.
rgrover1 0:8e57f3e9cc89 537 *
rgrover1 0:8e57f3e9cc89 538 * This function differs from vTaskDelay () in one important aspect: vTaskDelay () will
rgrover1 0:8e57f3e9cc89 539 * cause a task to block for the specified number of ticks from the time vTaskDelay () is
rgrover1 0:8e57f3e9cc89 540 * called. It is therefore difficult to use vTaskDelay () by itself to generate a fixed
rgrover1 0:8e57f3e9cc89 541 * execution frequency as the time between a task starting to execute and that task
rgrover1 0:8e57f3e9cc89 542 * calling vTaskDelay () may not be fixed [the task may take a different path though the
rgrover1 0:8e57f3e9cc89 543 * code between calls, or may get interrupted or preempted a different number of times
rgrover1 0:8e57f3e9cc89 544 * each time it executes].
rgrover1 0:8e57f3e9cc89 545 *
rgrover1 0:8e57f3e9cc89 546 * Whereas vTaskDelay () specifies a wake time relative to the time at which the function
rgrover1 0:8e57f3e9cc89 547 * is called, vTaskDelayUntil () specifies the absolute (exact) time at which it wishes to
rgrover1 0:8e57f3e9cc89 548 * unblock.
rgrover1 0:8e57f3e9cc89 549 *
rgrover1 0:8e57f3e9cc89 550 * The constant portTICK_RATE_MS can be used to calculate real time from the tick
rgrover1 0:8e57f3e9cc89 551 * rate - with the resolution of one tick period.
rgrover1 0:8e57f3e9cc89 552 *
rgrover1 0:8e57f3e9cc89 553 * @param pxPreviousWakeTime Pointer to a variable that holds the time at which the
rgrover1 0:8e57f3e9cc89 554 * task was last unblocked. The variable must be initialised with the current time
rgrover1 0:8e57f3e9cc89 555 * prior to its first use (see the example below). Following this the variable is
rgrover1 0:8e57f3e9cc89 556 * automatically updated within vTaskDelayUntil ().
rgrover1 0:8e57f3e9cc89 557 *
rgrover1 0:8e57f3e9cc89 558 * @param xTimeIncrement The cycle time period. The task will be unblocked at
rgrover1 0:8e57f3e9cc89 559 * time *pxPreviousWakeTime + xTimeIncrement. Calling vTaskDelayUntil with the
rgrover1 0:8e57f3e9cc89 560 * same xTimeIncrement parameter value will cause the task to execute with
rgrover1 0:8e57f3e9cc89 561 * a fixed interface period.
rgrover1 0:8e57f3e9cc89 562 *
rgrover1 0:8e57f3e9cc89 563 * Example usage:
rgrover1 0:8e57f3e9cc89 564 <pre>
rgrover1 0:8e57f3e9cc89 565 // Perform an action every 10 ticks.
rgrover1 0:8e57f3e9cc89 566 void vTaskFunction( void * pvParameters )
rgrover1 0:8e57f3e9cc89 567 {
rgrover1 0:8e57f3e9cc89 568 portTickType xLastWakeTime;
rgrover1 0:8e57f3e9cc89 569 const portTickType xFrequency = 10;
rgrover1 0:8e57f3e9cc89 570
rgrover1 0:8e57f3e9cc89 571 // Initialise the xLastWakeTime variable with the current time.
rgrover1 0:8e57f3e9cc89 572 xLastWakeTime = xTaskGetTickCount ();
rgrover1 0:8e57f3e9cc89 573 for( ;; )
rgrover1 0:8e57f3e9cc89 574 {
rgrover1 0:8e57f3e9cc89 575 // Wait for the next cycle.
rgrover1 0:8e57f3e9cc89 576 vTaskDelayUntil( &xLastWakeTime, xFrequency );
rgrover1 0:8e57f3e9cc89 577
rgrover1 0:8e57f3e9cc89 578 // Perform action here.
rgrover1 0:8e57f3e9cc89 579 }
rgrover1 0:8e57f3e9cc89 580 }
rgrover1 0:8e57f3e9cc89 581 </pre>
rgrover1 0:8e57f3e9cc89 582 * \defgroup vTaskDelayUntil vTaskDelayUntil
rgrover1 0:8e57f3e9cc89 583 * \ingroup TaskCtrl
rgrover1 0:8e57f3e9cc89 584 */
rgrover1 0:8e57f3e9cc89 585 void vTaskDelayUntil( portTickType * const pxPreviousWakeTime, portTickType xTimeIncrement ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 586
rgrover1 0:8e57f3e9cc89 587 /**
rgrover1 0:8e57f3e9cc89 588 * task. h
rgrover1 0:8e57f3e9cc89 589 * <pre>unsigned portBASE_TYPE uxTaskPriorityGet( xTaskHandle xTask );</pre>
rgrover1 0:8e57f3e9cc89 590 *
rgrover1 0:8e57f3e9cc89 591 * INCLUDE_xTaskPriorityGet must be defined as 1 for this function to be available.
rgrover1 0:8e57f3e9cc89 592 * See the configuration section for more information.
rgrover1 0:8e57f3e9cc89 593 *
rgrover1 0:8e57f3e9cc89 594 * Obtain the priority of any task.
rgrover1 0:8e57f3e9cc89 595 *
rgrover1 0:8e57f3e9cc89 596 * @param xTask Handle of the task to be queried. Passing a NULL
rgrover1 0:8e57f3e9cc89 597 * handle results in the priority of the calling task being returned.
rgrover1 0:8e57f3e9cc89 598 *
rgrover1 0:8e57f3e9cc89 599 * @return The priority of xTask.
rgrover1 0:8e57f3e9cc89 600 *
rgrover1 0:8e57f3e9cc89 601 * Example usage:
rgrover1 0:8e57f3e9cc89 602 <pre>
rgrover1 0:8e57f3e9cc89 603 void vAFunction( void )
rgrover1 0:8e57f3e9cc89 604 {
rgrover1 0:8e57f3e9cc89 605 xTaskHandle xHandle;
rgrover1 0:8e57f3e9cc89 606
rgrover1 0:8e57f3e9cc89 607 // Create a task, storing the handle.
rgrover1 0:8e57f3e9cc89 608 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
rgrover1 0:8e57f3e9cc89 609
rgrover1 0:8e57f3e9cc89 610 // ...
rgrover1 0:8e57f3e9cc89 611
rgrover1 0:8e57f3e9cc89 612 // Use the handle to obtain the priority of the created task.
rgrover1 0:8e57f3e9cc89 613 // It was created with tskIDLE_PRIORITY, but may have changed
rgrover1 0:8e57f3e9cc89 614 // it itself.
rgrover1 0:8e57f3e9cc89 615 if( uxTaskPriorityGet( xHandle ) != tskIDLE_PRIORITY )
rgrover1 0:8e57f3e9cc89 616 {
rgrover1 0:8e57f3e9cc89 617 // The task has changed it's priority.
rgrover1 0:8e57f3e9cc89 618 }
rgrover1 0:8e57f3e9cc89 619
rgrover1 0:8e57f3e9cc89 620 // ...
rgrover1 0:8e57f3e9cc89 621
rgrover1 0:8e57f3e9cc89 622 // Is our priority higher than the created task?
rgrover1 0:8e57f3e9cc89 623 if( uxTaskPriorityGet( xHandle ) < uxTaskPriorityGet( NULL ) )
rgrover1 0:8e57f3e9cc89 624 {
rgrover1 0:8e57f3e9cc89 625 // Our priority (obtained using NULL handle) is higher.
rgrover1 0:8e57f3e9cc89 626 }
rgrover1 0:8e57f3e9cc89 627 }
rgrover1 0:8e57f3e9cc89 628 </pre>
rgrover1 0:8e57f3e9cc89 629 * \defgroup uxTaskPriorityGet uxTaskPriorityGet
rgrover1 0:8e57f3e9cc89 630 * \ingroup TaskCtrl
rgrover1 0:8e57f3e9cc89 631 */
rgrover1 0:8e57f3e9cc89 632 unsigned portBASE_TYPE uxTaskPriorityGet( xTaskHandle xTask ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 633
rgrover1 0:8e57f3e9cc89 634 /**
rgrover1 0:8e57f3e9cc89 635 * task. h
rgrover1 0:8e57f3e9cc89 636 * <pre>eTaskState eTaskGetState( xTaskHandle xTask );</pre>
rgrover1 0:8e57f3e9cc89 637 *
rgrover1 0:8e57f3e9cc89 638 * INCLUDE_eTaskGetState must be defined as 1 for this function to be available.
rgrover1 0:8e57f3e9cc89 639 * See the configuration section for more information.
rgrover1 0:8e57f3e9cc89 640 *
rgrover1 0:8e57f3e9cc89 641 * Obtain the state of any task. States are encoded by the eTaskState
rgrover1 0:8e57f3e9cc89 642 * enumerated type.
rgrover1 0:8e57f3e9cc89 643 *
rgrover1 0:8e57f3e9cc89 644 * @param xTask Handle of the task to be queried.
rgrover1 0:8e57f3e9cc89 645 *
rgrover1 0:8e57f3e9cc89 646 * @return The state of xTask at the time the function was called. Note the
rgrover1 0:8e57f3e9cc89 647 * state of the task might change between the function being called, and the
rgrover1 0:8e57f3e9cc89 648 * functions return value being tested by the calling task.
rgrover1 0:8e57f3e9cc89 649 */
rgrover1 0:8e57f3e9cc89 650 eTaskState eTaskGetState( xTaskHandle xTask ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 651
rgrover1 0:8e57f3e9cc89 652 /**
rgrover1 0:8e57f3e9cc89 653 * task. h
rgrover1 0:8e57f3e9cc89 654 * <pre>void vTaskPrioritySet( xTaskHandle xTask, unsigned portBASE_TYPE uxNewPriority );</pre>
rgrover1 0:8e57f3e9cc89 655 *
rgrover1 0:8e57f3e9cc89 656 * INCLUDE_vTaskPrioritySet must be defined as 1 for this function to be available.
rgrover1 0:8e57f3e9cc89 657 * See the configuration section for more information.
rgrover1 0:8e57f3e9cc89 658 *
rgrover1 0:8e57f3e9cc89 659 * Set the priority of any task.
rgrover1 0:8e57f3e9cc89 660 *
rgrover1 0:8e57f3e9cc89 661 * A context switch will occur before the function returns if the priority
rgrover1 0:8e57f3e9cc89 662 * being set is higher than the currently executing task.
rgrover1 0:8e57f3e9cc89 663 *
rgrover1 0:8e57f3e9cc89 664 * @param xTask Handle to the task for which the priority is being set.
rgrover1 0:8e57f3e9cc89 665 * Passing a NULL handle results in the priority of the calling task being set.
rgrover1 0:8e57f3e9cc89 666 *
rgrover1 0:8e57f3e9cc89 667 * @param uxNewPriority The priority to which the task will be set.
rgrover1 0:8e57f3e9cc89 668 *
rgrover1 0:8e57f3e9cc89 669 * Example usage:
rgrover1 0:8e57f3e9cc89 670 <pre>
rgrover1 0:8e57f3e9cc89 671 void vAFunction( void )
rgrover1 0:8e57f3e9cc89 672 {
rgrover1 0:8e57f3e9cc89 673 xTaskHandle xHandle;
rgrover1 0:8e57f3e9cc89 674
rgrover1 0:8e57f3e9cc89 675 // Create a task, storing the handle.
rgrover1 0:8e57f3e9cc89 676 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
rgrover1 0:8e57f3e9cc89 677
rgrover1 0:8e57f3e9cc89 678 // ...
rgrover1 0:8e57f3e9cc89 679
rgrover1 0:8e57f3e9cc89 680 // Use the handle to raise the priority of the created task.
rgrover1 0:8e57f3e9cc89 681 vTaskPrioritySet( xHandle, tskIDLE_PRIORITY + 1 );
rgrover1 0:8e57f3e9cc89 682
rgrover1 0:8e57f3e9cc89 683 // ...
rgrover1 0:8e57f3e9cc89 684
rgrover1 0:8e57f3e9cc89 685 // Use a NULL handle to raise our priority to the same value.
rgrover1 0:8e57f3e9cc89 686 vTaskPrioritySet( NULL, tskIDLE_PRIORITY + 1 );
rgrover1 0:8e57f3e9cc89 687 }
rgrover1 0:8e57f3e9cc89 688 </pre>
rgrover1 0:8e57f3e9cc89 689 * \defgroup vTaskPrioritySet vTaskPrioritySet
rgrover1 0:8e57f3e9cc89 690 * \ingroup TaskCtrl
rgrover1 0:8e57f3e9cc89 691 */
rgrover1 0:8e57f3e9cc89 692 void vTaskPrioritySet( xTaskHandle xTask, unsigned portBASE_TYPE uxNewPriority ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 693
rgrover1 0:8e57f3e9cc89 694 /**
rgrover1 0:8e57f3e9cc89 695 * task. h
rgrover1 0:8e57f3e9cc89 696 * <pre>void vTaskSuspend( xTaskHandle xTaskToSuspend );</pre>
rgrover1 0:8e57f3e9cc89 697 *
rgrover1 0:8e57f3e9cc89 698 * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available.
rgrover1 0:8e57f3e9cc89 699 * See the configuration section for more information.
rgrover1 0:8e57f3e9cc89 700 *
rgrover1 0:8e57f3e9cc89 701 * Suspend any task. When suspended a task will never get any microcontroller
rgrover1 0:8e57f3e9cc89 702 * processing time, no matter what its priority.
rgrover1 0:8e57f3e9cc89 703 *
rgrover1 0:8e57f3e9cc89 704 * Calls to vTaskSuspend are not accumulative -
rgrover1 0:8e57f3e9cc89 705 * i.e. calling vTaskSuspend () twice on the same task still only requires one
rgrover1 0:8e57f3e9cc89 706 * call to vTaskResume () to ready the suspended task.
rgrover1 0:8e57f3e9cc89 707 *
rgrover1 0:8e57f3e9cc89 708 * @param xTaskToSuspend Handle to the task being suspended. Passing a NULL
rgrover1 0:8e57f3e9cc89 709 * handle will cause the calling task to be suspended.
rgrover1 0:8e57f3e9cc89 710 *
rgrover1 0:8e57f3e9cc89 711 * Example usage:
rgrover1 0:8e57f3e9cc89 712 <pre>
rgrover1 0:8e57f3e9cc89 713 void vAFunction( void )
rgrover1 0:8e57f3e9cc89 714 {
rgrover1 0:8e57f3e9cc89 715 xTaskHandle xHandle;
rgrover1 0:8e57f3e9cc89 716
rgrover1 0:8e57f3e9cc89 717 // Create a task, storing the handle.
rgrover1 0:8e57f3e9cc89 718 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
rgrover1 0:8e57f3e9cc89 719
rgrover1 0:8e57f3e9cc89 720 // ...
rgrover1 0:8e57f3e9cc89 721
rgrover1 0:8e57f3e9cc89 722 // Use the handle to suspend the created task.
rgrover1 0:8e57f3e9cc89 723 vTaskSuspend( xHandle );
rgrover1 0:8e57f3e9cc89 724
rgrover1 0:8e57f3e9cc89 725 // ...
rgrover1 0:8e57f3e9cc89 726
rgrover1 0:8e57f3e9cc89 727 // The created task will not run during this period, unless
rgrover1 0:8e57f3e9cc89 728 // another task calls vTaskResume( xHandle ).
rgrover1 0:8e57f3e9cc89 729
rgrover1 0:8e57f3e9cc89 730 //...
rgrover1 0:8e57f3e9cc89 731
rgrover1 0:8e57f3e9cc89 732
rgrover1 0:8e57f3e9cc89 733 // Suspend ourselves.
rgrover1 0:8e57f3e9cc89 734 vTaskSuspend( NULL );
rgrover1 0:8e57f3e9cc89 735
rgrover1 0:8e57f3e9cc89 736 // We cannot get here unless another task calls vTaskResume
rgrover1 0:8e57f3e9cc89 737 // with our handle as the parameter.
rgrover1 0:8e57f3e9cc89 738 }
rgrover1 0:8e57f3e9cc89 739 </pre>
rgrover1 0:8e57f3e9cc89 740 * \defgroup vTaskSuspend vTaskSuspend
rgrover1 0:8e57f3e9cc89 741 * \ingroup TaskCtrl
rgrover1 0:8e57f3e9cc89 742 */
rgrover1 0:8e57f3e9cc89 743 void vTaskSuspend( xTaskHandle xTaskToSuspend ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 744
rgrover1 0:8e57f3e9cc89 745 /**
rgrover1 0:8e57f3e9cc89 746 * task. h
rgrover1 0:8e57f3e9cc89 747 * <pre>void vTaskResume( xTaskHandle xTaskToResume );</pre>
rgrover1 0:8e57f3e9cc89 748 *
rgrover1 0:8e57f3e9cc89 749 * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available.
rgrover1 0:8e57f3e9cc89 750 * See the configuration section for more information.
rgrover1 0:8e57f3e9cc89 751 *
rgrover1 0:8e57f3e9cc89 752 * Resumes a suspended task.
rgrover1 0:8e57f3e9cc89 753 *
rgrover1 0:8e57f3e9cc89 754 * A task that has been suspended by one of more calls to vTaskSuspend ()
rgrover1 0:8e57f3e9cc89 755 * will be made available for running again by a single call to
rgrover1 0:8e57f3e9cc89 756 * vTaskResume ().
rgrover1 0:8e57f3e9cc89 757 *
rgrover1 0:8e57f3e9cc89 758 * @param xTaskToResume Handle to the task being readied.
rgrover1 0:8e57f3e9cc89 759 *
rgrover1 0:8e57f3e9cc89 760 * Example usage:
rgrover1 0:8e57f3e9cc89 761 <pre>
rgrover1 0:8e57f3e9cc89 762 void vAFunction( void )
rgrover1 0:8e57f3e9cc89 763 {
rgrover1 0:8e57f3e9cc89 764 xTaskHandle xHandle;
rgrover1 0:8e57f3e9cc89 765
rgrover1 0:8e57f3e9cc89 766 // Create a task, storing the handle.
rgrover1 0:8e57f3e9cc89 767 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
rgrover1 0:8e57f3e9cc89 768
rgrover1 0:8e57f3e9cc89 769 // ...
rgrover1 0:8e57f3e9cc89 770
rgrover1 0:8e57f3e9cc89 771 // Use the handle to suspend the created task.
rgrover1 0:8e57f3e9cc89 772 vTaskSuspend( xHandle );
rgrover1 0:8e57f3e9cc89 773
rgrover1 0:8e57f3e9cc89 774 // ...
rgrover1 0:8e57f3e9cc89 775
rgrover1 0:8e57f3e9cc89 776 // The created task will not run during this period, unless
rgrover1 0:8e57f3e9cc89 777 // another task calls vTaskResume( xHandle ).
rgrover1 0:8e57f3e9cc89 778
rgrover1 0:8e57f3e9cc89 779 //...
rgrover1 0:8e57f3e9cc89 780
rgrover1 0:8e57f3e9cc89 781
rgrover1 0:8e57f3e9cc89 782 // Resume the suspended task ourselves.
rgrover1 0:8e57f3e9cc89 783 vTaskResume( xHandle );
rgrover1 0:8e57f3e9cc89 784
rgrover1 0:8e57f3e9cc89 785 // The created task will once again get microcontroller processing
rgrover1 0:8e57f3e9cc89 786 // time in accordance with it priority within the system.
rgrover1 0:8e57f3e9cc89 787 }
rgrover1 0:8e57f3e9cc89 788 </pre>
rgrover1 0:8e57f3e9cc89 789 * \defgroup vTaskResume vTaskResume
rgrover1 0:8e57f3e9cc89 790 * \ingroup TaskCtrl
rgrover1 0:8e57f3e9cc89 791 */
rgrover1 0:8e57f3e9cc89 792 void vTaskResume( xTaskHandle xTaskToResume ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 793
rgrover1 0:8e57f3e9cc89 794 /**
rgrover1 0:8e57f3e9cc89 795 * task. h
rgrover1 0:8e57f3e9cc89 796 * <pre>void xTaskResumeFromISR( xTaskHandle xTaskToResume );</pre>
rgrover1 0:8e57f3e9cc89 797 *
rgrover1 0:8e57f3e9cc89 798 * INCLUDE_xTaskResumeFromISR must be defined as 1 for this function to be
rgrover1 0:8e57f3e9cc89 799 * available. See the configuration section for more information.
rgrover1 0:8e57f3e9cc89 800 *
rgrover1 0:8e57f3e9cc89 801 * An implementation of vTaskResume() that can be called from within an ISR.
rgrover1 0:8e57f3e9cc89 802 *
rgrover1 0:8e57f3e9cc89 803 * A task that has been suspended by one of more calls to vTaskSuspend ()
rgrover1 0:8e57f3e9cc89 804 * will be made available for running again by a single call to
rgrover1 0:8e57f3e9cc89 805 * xTaskResumeFromISR ().
rgrover1 0:8e57f3e9cc89 806 *
rgrover1 0:8e57f3e9cc89 807 * @param xTaskToResume Handle to the task being readied.
rgrover1 0:8e57f3e9cc89 808 *
rgrover1 0:8e57f3e9cc89 809 * \defgroup vTaskResumeFromISR vTaskResumeFromISR
rgrover1 0:8e57f3e9cc89 810 * \ingroup TaskCtrl
rgrover1 0:8e57f3e9cc89 811 */
rgrover1 0:8e57f3e9cc89 812 portBASE_TYPE xTaskResumeFromISR( xTaskHandle xTaskToResume ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 813
rgrover1 0:8e57f3e9cc89 814 /*-----------------------------------------------------------
rgrover1 0:8e57f3e9cc89 815 * SCHEDULER CONTROL
rgrover1 0:8e57f3e9cc89 816 *----------------------------------------------------------*/
rgrover1 0:8e57f3e9cc89 817
rgrover1 0:8e57f3e9cc89 818 /**
rgrover1 0:8e57f3e9cc89 819 * task. h
rgrover1 0:8e57f3e9cc89 820 * <pre>void vTaskStartScheduler( void );</pre>
rgrover1 0:8e57f3e9cc89 821 *
rgrover1 0:8e57f3e9cc89 822 * Starts the real time kernel tick processing. After calling the kernel
rgrover1 0:8e57f3e9cc89 823 * has control over which tasks are executed and when. This function
rgrover1 0:8e57f3e9cc89 824 * does not return until an executing task calls vTaskEndScheduler ().
rgrover1 0:8e57f3e9cc89 825 *
rgrover1 0:8e57f3e9cc89 826 * At least one task should be created via a call to xTaskCreate ()
rgrover1 0:8e57f3e9cc89 827 * before calling vTaskStartScheduler (). The idle task is created
rgrover1 0:8e57f3e9cc89 828 * automatically when the first application task is created.
rgrover1 0:8e57f3e9cc89 829 *
rgrover1 0:8e57f3e9cc89 830 * See the demo application file main.c for an example of creating
rgrover1 0:8e57f3e9cc89 831 * tasks and starting the kernel.
rgrover1 0:8e57f3e9cc89 832 *
rgrover1 0:8e57f3e9cc89 833 * Example usage:
rgrover1 0:8e57f3e9cc89 834 <pre>
rgrover1 0:8e57f3e9cc89 835 void vAFunction( void )
rgrover1 0:8e57f3e9cc89 836 {
rgrover1 0:8e57f3e9cc89 837 // Create at least one task before starting the kernel.
rgrover1 0:8e57f3e9cc89 838 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL );
rgrover1 0:8e57f3e9cc89 839
rgrover1 0:8e57f3e9cc89 840 // Start the real time kernel with preemption.
rgrover1 0:8e57f3e9cc89 841 vTaskStartScheduler ();
rgrover1 0:8e57f3e9cc89 842
rgrover1 0:8e57f3e9cc89 843 // Will not get here unless a task calls vTaskEndScheduler ()
rgrover1 0:8e57f3e9cc89 844 }
rgrover1 0:8e57f3e9cc89 845 </pre>
rgrover1 0:8e57f3e9cc89 846 *
rgrover1 0:8e57f3e9cc89 847 * \defgroup vTaskStartScheduler vTaskStartScheduler
rgrover1 0:8e57f3e9cc89 848 * \ingroup SchedulerControl
rgrover1 0:8e57f3e9cc89 849 */
rgrover1 0:8e57f3e9cc89 850 void vTaskStartScheduler( void ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 851
rgrover1 0:8e57f3e9cc89 852 /**
rgrover1 0:8e57f3e9cc89 853 * task. h
rgrover1 0:8e57f3e9cc89 854 * <pre>void vTaskEndScheduler( void );</pre>
rgrover1 0:8e57f3e9cc89 855 *
rgrover1 0:8e57f3e9cc89 856 * Stops the real time kernel tick. All created tasks will be automatically
rgrover1 0:8e57f3e9cc89 857 * deleted and multitasking (either preemptive or cooperative) will
rgrover1 0:8e57f3e9cc89 858 * stop. Execution then resumes from the point where vTaskStartScheduler ()
rgrover1 0:8e57f3e9cc89 859 * was called, as if vTaskStartScheduler () had just returned.
rgrover1 0:8e57f3e9cc89 860 *
rgrover1 0:8e57f3e9cc89 861 * See the demo application file main. c in the demo/PC directory for an
rgrover1 0:8e57f3e9cc89 862 * example that uses vTaskEndScheduler ().
rgrover1 0:8e57f3e9cc89 863 *
rgrover1 0:8e57f3e9cc89 864 * vTaskEndScheduler () requires an exit function to be defined within the
rgrover1 0:8e57f3e9cc89 865 * portable layer (see vPortEndScheduler () in port. c for the PC port). This
rgrover1 0:8e57f3e9cc89 866 * performs hardware specific operations such as stopping the kernel tick.
rgrover1 0:8e57f3e9cc89 867 *
rgrover1 0:8e57f3e9cc89 868 * vTaskEndScheduler () will cause all of the resources allocated by the
rgrover1 0:8e57f3e9cc89 869 * kernel to be freed - but will not free resources allocated by application
rgrover1 0:8e57f3e9cc89 870 * tasks.
rgrover1 0:8e57f3e9cc89 871 *
rgrover1 0:8e57f3e9cc89 872 * Example usage:
rgrover1 0:8e57f3e9cc89 873 <pre>
rgrover1 0:8e57f3e9cc89 874 void vTaskCode( void * pvParameters )
rgrover1 0:8e57f3e9cc89 875 {
rgrover1 0:8e57f3e9cc89 876 for( ;; )
rgrover1 0:8e57f3e9cc89 877 {
rgrover1 0:8e57f3e9cc89 878 // Task code goes here.
rgrover1 0:8e57f3e9cc89 879
rgrover1 0:8e57f3e9cc89 880 // At some point we want to end the real time kernel processing
rgrover1 0:8e57f3e9cc89 881 // so call ...
rgrover1 0:8e57f3e9cc89 882 vTaskEndScheduler ();
rgrover1 0:8e57f3e9cc89 883 }
rgrover1 0:8e57f3e9cc89 884 }
rgrover1 0:8e57f3e9cc89 885
rgrover1 0:8e57f3e9cc89 886 void vAFunction( void )
rgrover1 0:8e57f3e9cc89 887 {
rgrover1 0:8e57f3e9cc89 888 // Create at least one task before starting the kernel.
rgrover1 0:8e57f3e9cc89 889 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL );
rgrover1 0:8e57f3e9cc89 890
rgrover1 0:8e57f3e9cc89 891 // Start the real time kernel with preemption.
rgrover1 0:8e57f3e9cc89 892 vTaskStartScheduler ();
rgrover1 0:8e57f3e9cc89 893
rgrover1 0:8e57f3e9cc89 894 // Will only get here when the vTaskCode () task has called
rgrover1 0:8e57f3e9cc89 895 // vTaskEndScheduler (). When we get here we are back to single task
rgrover1 0:8e57f3e9cc89 896 // execution.
rgrover1 0:8e57f3e9cc89 897 }
rgrover1 0:8e57f3e9cc89 898 </pre>
rgrover1 0:8e57f3e9cc89 899 *
rgrover1 0:8e57f3e9cc89 900 * \defgroup vTaskEndScheduler vTaskEndScheduler
rgrover1 0:8e57f3e9cc89 901 * \ingroup SchedulerControl
rgrover1 0:8e57f3e9cc89 902 */
rgrover1 0:8e57f3e9cc89 903 void vTaskEndScheduler( void ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 904
rgrover1 0:8e57f3e9cc89 905 /**
rgrover1 0:8e57f3e9cc89 906 * task. h
rgrover1 0:8e57f3e9cc89 907 * <pre>void vTaskSuspendAll( void );</pre>
rgrover1 0:8e57f3e9cc89 908 *
rgrover1 0:8e57f3e9cc89 909 * Suspends all real time kernel activity while keeping interrupts (including the
rgrover1 0:8e57f3e9cc89 910 * kernel tick) enabled.
rgrover1 0:8e57f3e9cc89 911 *
rgrover1 0:8e57f3e9cc89 912 * After calling vTaskSuspendAll () the calling task will continue to execute
rgrover1 0:8e57f3e9cc89 913 * without risk of being swapped out until a call to xTaskResumeAll () has been
rgrover1 0:8e57f3e9cc89 914 * made.
rgrover1 0:8e57f3e9cc89 915 *
rgrover1 0:8e57f3e9cc89 916 * API functions that have the potential to cause a context switch (for example,
rgrover1 0:8e57f3e9cc89 917 * vTaskDelayUntil(), xQueueSend(), etc.) must not be called while the scheduler
rgrover1 0:8e57f3e9cc89 918 * is suspended.
rgrover1 0:8e57f3e9cc89 919 *
rgrover1 0:8e57f3e9cc89 920 * Example usage:
rgrover1 0:8e57f3e9cc89 921 <pre>
rgrover1 0:8e57f3e9cc89 922 void vTask1( void * pvParameters )
rgrover1 0:8e57f3e9cc89 923 {
rgrover1 0:8e57f3e9cc89 924 for( ;; )
rgrover1 0:8e57f3e9cc89 925 {
rgrover1 0:8e57f3e9cc89 926 // Task code goes here.
rgrover1 0:8e57f3e9cc89 927
rgrover1 0:8e57f3e9cc89 928 // ...
rgrover1 0:8e57f3e9cc89 929
rgrover1 0:8e57f3e9cc89 930 // At some point the task wants to perform a long operation during
rgrover1 0:8e57f3e9cc89 931 // which it does not want to get swapped out. It cannot use
rgrover1 0:8e57f3e9cc89 932 // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the
rgrover1 0:8e57f3e9cc89 933 // operation may cause interrupts to be missed - including the
rgrover1 0:8e57f3e9cc89 934 // ticks.
rgrover1 0:8e57f3e9cc89 935
rgrover1 0:8e57f3e9cc89 936 // Prevent the real time kernel swapping out the task.
rgrover1 0:8e57f3e9cc89 937 vTaskSuspendAll ();
rgrover1 0:8e57f3e9cc89 938
rgrover1 0:8e57f3e9cc89 939 // Perform the operation here. There is no need to use critical
rgrover1 0:8e57f3e9cc89 940 // sections as we have all the microcontroller processing time.
rgrover1 0:8e57f3e9cc89 941 // During this time interrupts will still operate and the kernel
rgrover1 0:8e57f3e9cc89 942 // tick count will be maintained.
rgrover1 0:8e57f3e9cc89 943
rgrover1 0:8e57f3e9cc89 944 // ...
rgrover1 0:8e57f3e9cc89 945
rgrover1 0:8e57f3e9cc89 946 // The operation is complete. Restart the kernel.
rgrover1 0:8e57f3e9cc89 947 xTaskResumeAll ();
rgrover1 0:8e57f3e9cc89 948 }
rgrover1 0:8e57f3e9cc89 949 }
rgrover1 0:8e57f3e9cc89 950 </pre>
rgrover1 0:8e57f3e9cc89 951 * \defgroup vTaskSuspendAll vTaskSuspendAll
rgrover1 0:8e57f3e9cc89 952 * \ingroup SchedulerControl
rgrover1 0:8e57f3e9cc89 953 */
rgrover1 0:8e57f3e9cc89 954 void vTaskSuspendAll( void ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 955
rgrover1 0:8e57f3e9cc89 956 /**
rgrover1 0:8e57f3e9cc89 957 * task. h
rgrover1 0:8e57f3e9cc89 958 * <pre>char xTaskResumeAll( void );</pre>
rgrover1 0:8e57f3e9cc89 959 *
rgrover1 0:8e57f3e9cc89 960 * Resumes real time kernel activity following a call to vTaskSuspendAll ().
rgrover1 0:8e57f3e9cc89 961 * After a call to vTaskSuspendAll () the kernel will take control of which
rgrover1 0:8e57f3e9cc89 962 * task is executing at any time.
rgrover1 0:8e57f3e9cc89 963 *
rgrover1 0:8e57f3e9cc89 964 * @return If resuming the scheduler caused a context switch then pdTRUE is
rgrover1 0:8e57f3e9cc89 965 * returned, otherwise pdFALSE is returned.
rgrover1 0:8e57f3e9cc89 966 *
rgrover1 0:8e57f3e9cc89 967 * Example usage:
rgrover1 0:8e57f3e9cc89 968 <pre>
rgrover1 0:8e57f3e9cc89 969 void vTask1( void * pvParameters )
rgrover1 0:8e57f3e9cc89 970 {
rgrover1 0:8e57f3e9cc89 971 for( ;; )
rgrover1 0:8e57f3e9cc89 972 {
rgrover1 0:8e57f3e9cc89 973 // Task code goes here.
rgrover1 0:8e57f3e9cc89 974
rgrover1 0:8e57f3e9cc89 975 // ...
rgrover1 0:8e57f3e9cc89 976
rgrover1 0:8e57f3e9cc89 977 // At some point the task wants to perform a long operation during
rgrover1 0:8e57f3e9cc89 978 // which it does not want to get swapped out. It cannot use
rgrover1 0:8e57f3e9cc89 979 // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the
rgrover1 0:8e57f3e9cc89 980 // operation may cause interrupts to be missed - including the
rgrover1 0:8e57f3e9cc89 981 // ticks.
rgrover1 0:8e57f3e9cc89 982
rgrover1 0:8e57f3e9cc89 983 // Prevent the real time kernel swapping out the task.
rgrover1 0:8e57f3e9cc89 984 vTaskSuspendAll ();
rgrover1 0:8e57f3e9cc89 985
rgrover1 0:8e57f3e9cc89 986 // Perform the operation here. There is no need to use critical
rgrover1 0:8e57f3e9cc89 987 // sections as we have all the microcontroller processing time.
rgrover1 0:8e57f3e9cc89 988 // During this time interrupts will still operate and the real
rgrover1 0:8e57f3e9cc89 989 // time kernel tick count will be maintained.
rgrover1 0:8e57f3e9cc89 990
rgrover1 0:8e57f3e9cc89 991 // ...
rgrover1 0:8e57f3e9cc89 992
rgrover1 0:8e57f3e9cc89 993 // The operation is complete. Restart the kernel. We want to force
rgrover1 0:8e57f3e9cc89 994 // a context switch - but there is no point if resuming the scheduler
rgrover1 0:8e57f3e9cc89 995 // caused a context switch already.
rgrover1 0:8e57f3e9cc89 996 if( !xTaskResumeAll () )
rgrover1 0:8e57f3e9cc89 997 {
rgrover1 0:8e57f3e9cc89 998 taskYIELD ();
rgrover1 0:8e57f3e9cc89 999 }
rgrover1 0:8e57f3e9cc89 1000 }
rgrover1 0:8e57f3e9cc89 1001 }
rgrover1 0:8e57f3e9cc89 1002 </pre>
rgrover1 0:8e57f3e9cc89 1003 * \defgroup xTaskResumeAll xTaskResumeAll
rgrover1 0:8e57f3e9cc89 1004 * \ingroup SchedulerControl
rgrover1 0:8e57f3e9cc89 1005 */
rgrover1 0:8e57f3e9cc89 1006 signed portBASE_TYPE xTaskResumeAll( void ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 1007
rgrover1 0:8e57f3e9cc89 1008 /**
rgrover1 0:8e57f3e9cc89 1009 * task. h
rgrover1 0:8e57f3e9cc89 1010 * <pre>signed portBASE_TYPE xTaskIsTaskSuspended( const xTaskHandle xTask );</pre>
rgrover1 0:8e57f3e9cc89 1011 *
rgrover1 0:8e57f3e9cc89 1012 * Utility task that simply returns pdTRUE if the task referenced by xTask is
rgrover1 0:8e57f3e9cc89 1013 * currently in the Suspended state, or pdFALSE if the task referenced by xTask
rgrover1 0:8e57f3e9cc89 1014 * is in any other state.
rgrover1 0:8e57f3e9cc89 1015 *
rgrover1 0:8e57f3e9cc89 1016 */
rgrover1 0:8e57f3e9cc89 1017 signed portBASE_TYPE xTaskIsTaskSuspended( xTaskHandle xTask ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 1018
rgrover1 0:8e57f3e9cc89 1019 /*-----------------------------------------------------------
rgrover1 0:8e57f3e9cc89 1020 * TASK UTILITIES
rgrover1 0:8e57f3e9cc89 1021 *----------------------------------------------------------*/
rgrover1 0:8e57f3e9cc89 1022
rgrover1 0:8e57f3e9cc89 1023 /**
rgrover1 0:8e57f3e9cc89 1024 * task. h
rgrover1 0:8e57f3e9cc89 1025 * <PRE>portTickType xTaskGetTickCount( void );</PRE>
rgrover1 0:8e57f3e9cc89 1026 *
rgrover1 0:8e57f3e9cc89 1027 * @return The count of ticks since vTaskStartScheduler was called.
rgrover1 0:8e57f3e9cc89 1028 *
rgrover1 0:8e57f3e9cc89 1029 * \defgroup xTaskGetTickCount xTaskGetTickCount
rgrover1 0:8e57f3e9cc89 1030 * \ingroup TaskUtils
rgrover1 0:8e57f3e9cc89 1031 */
rgrover1 0:8e57f3e9cc89 1032 portTickType xTaskGetTickCount( void ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 1033
rgrover1 0:8e57f3e9cc89 1034 /**
rgrover1 0:8e57f3e9cc89 1035 * task. h
rgrover1 0:8e57f3e9cc89 1036 * <PRE>portTickType xTaskGetTickCountFromISR( void );</PRE>
rgrover1 0:8e57f3e9cc89 1037 *
rgrover1 0:8e57f3e9cc89 1038 * @return The count of ticks since vTaskStartScheduler was called.
rgrover1 0:8e57f3e9cc89 1039 *
rgrover1 0:8e57f3e9cc89 1040 * This is a version of xTaskGetTickCount() that is safe to be called from an
rgrover1 0:8e57f3e9cc89 1041 * ISR - provided that portTickType is the natural word size of the
rgrover1 0:8e57f3e9cc89 1042 * microcontroller being used or interrupt nesting is either not supported or
rgrover1 0:8e57f3e9cc89 1043 * not being used.
rgrover1 0:8e57f3e9cc89 1044 *
rgrover1 0:8e57f3e9cc89 1045 * \defgroup xTaskGetTickCount xTaskGetTickCount
rgrover1 0:8e57f3e9cc89 1046 * \ingroup TaskUtils
rgrover1 0:8e57f3e9cc89 1047 */
rgrover1 0:8e57f3e9cc89 1048 portTickType xTaskGetTickCountFromISR( void ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 1049
rgrover1 0:8e57f3e9cc89 1050 /**
rgrover1 0:8e57f3e9cc89 1051 * task. h
rgrover1 0:8e57f3e9cc89 1052 * <PRE>unsigned short uxTaskGetNumberOfTasks( void );</PRE>
rgrover1 0:8e57f3e9cc89 1053 *
rgrover1 0:8e57f3e9cc89 1054 * @return The number of tasks that the real time kernel is currently managing.
rgrover1 0:8e57f3e9cc89 1055 * This includes all ready, blocked and suspended tasks. A task that
rgrover1 0:8e57f3e9cc89 1056 * has been deleted but not yet freed by the idle task will also be
rgrover1 0:8e57f3e9cc89 1057 * included in the count.
rgrover1 0:8e57f3e9cc89 1058 *
rgrover1 0:8e57f3e9cc89 1059 * \defgroup uxTaskGetNumberOfTasks uxTaskGetNumberOfTasks
rgrover1 0:8e57f3e9cc89 1060 * \ingroup TaskUtils
rgrover1 0:8e57f3e9cc89 1061 */
rgrover1 0:8e57f3e9cc89 1062 unsigned portBASE_TYPE uxTaskGetNumberOfTasks( void ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 1063
rgrover1 0:8e57f3e9cc89 1064 /**
rgrover1 0:8e57f3e9cc89 1065 * task. h
rgrover1 0:8e57f3e9cc89 1066 * <PRE>signed char *pcTaskGetTaskName( xTaskHandle xTaskToQuery );</PRE>
rgrover1 0:8e57f3e9cc89 1067 *
rgrover1 0:8e57f3e9cc89 1068 * @return The text (human readable) name of the task referenced by the handle
rgrover1 0:8e57f3e9cc89 1069 * xTaskToQueury. A task can query its own name by either passing in its own
rgrover1 0:8e57f3e9cc89 1070 * handle, or by setting xTaskToQuery to NULL. INCLUDE_pcTaskGetTaskName must be
rgrover1 0:8e57f3e9cc89 1071 * set to 1 in FreeRTOSConfig.h for pcTaskGetTaskName() to be available.
rgrover1 0:8e57f3e9cc89 1072 *
rgrover1 0:8e57f3e9cc89 1073 * \defgroup pcTaskGetTaskName pcTaskGetTaskName
rgrover1 0:8e57f3e9cc89 1074 * \ingroup TaskUtils
rgrover1 0:8e57f3e9cc89 1075 */
rgrover1 0:8e57f3e9cc89 1076 signed char *pcTaskGetTaskName( xTaskHandle xTaskToQuery );
rgrover1 0:8e57f3e9cc89 1077
rgrover1 0:8e57f3e9cc89 1078 /**
rgrover1 0:8e57f3e9cc89 1079 * task.h
rgrover1 0:8e57f3e9cc89 1080 * <PRE>unsigned portBASE_TYPE uxTaskGetStackHighWaterMark( xTaskHandle xTask );</PRE>
rgrover1 0:8e57f3e9cc89 1081 *
rgrover1 0:8e57f3e9cc89 1082 * INCLUDE_uxTaskGetStackHighWaterMark must be set to 1 in FreeRTOSConfig.h for
rgrover1 0:8e57f3e9cc89 1083 * this function to be available.
rgrover1 0:8e57f3e9cc89 1084 *
rgrover1 0:8e57f3e9cc89 1085 * Returns the high water mark of the stack associated with xTask. That is,
rgrover1 0:8e57f3e9cc89 1086 * the minimum free stack space there has been (in words, so on a 32 bit machine
rgrover1 0:8e57f3e9cc89 1087 * a value of 1 means 4 bytes) since the task started. The smaller the returned
rgrover1 0:8e57f3e9cc89 1088 * number the closer the task has come to overflowing its stack.
rgrover1 0:8e57f3e9cc89 1089 *
rgrover1 0:8e57f3e9cc89 1090 * @param xTask Handle of the task associated with the stack to be checked.
rgrover1 0:8e57f3e9cc89 1091 * Set xTask to NULL to check the stack of the calling task.
rgrover1 0:8e57f3e9cc89 1092 *
rgrover1 0:8e57f3e9cc89 1093 * @return The smallest amount of free stack space there has been (in bytes)
rgrover1 0:8e57f3e9cc89 1094 * since the task referenced by xTask was created.
rgrover1 0:8e57f3e9cc89 1095 */
rgrover1 0:8e57f3e9cc89 1096 unsigned portBASE_TYPE uxTaskGetStackHighWaterMark( xTaskHandle xTask ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 1097
rgrover1 0:8e57f3e9cc89 1098 /* When using trace macros it is sometimes necessary to include tasks.h before
rgrover1 0:8e57f3e9cc89 1099 FreeRTOS.h. When this is done pdTASK_HOOK_CODE will not yet have been defined,
rgrover1 0:8e57f3e9cc89 1100 so the following two prototypes will cause a compilation error. This can be
rgrover1 0:8e57f3e9cc89 1101 fixed by simply guarding against the inclusion of these two prototypes unless
rgrover1 0:8e57f3e9cc89 1102 they are explicitly required by the configUSE_APPLICATION_TASK_TAG configuration
rgrover1 0:8e57f3e9cc89 1103 constant. */
rgrover1 0:8e57f3e9cc89 1104 #ifdef configUSE_APPLICATION_TASK_TAG
rgrover1 0:8e57f3e9cc89 1105 #if configUSE_APPLICATION_TASK_TAG == 1
rgrover1 0:8e57f3e9cc89 1106 /**
rgrover1 0:8e57f3e9cc89 1107 * task.h
rgrover1 0:8e57f3e9cc89 1108 * <pre>void vTaskSetApplicationTaskTag( xTaskHandle xTask, pdTASK_HOOK_CODE pxHookFunction );</pre>
rgrover1 0:8e57f3e9cc89 1109 *
rgrover1 0:8e57f3e9cc89 1110 * Sets pxHookFunction to be the task hook function used by the task xTask.
rgrover1 0:8e57f3e9cc89 1111 * Passing xTask as NULL has the effect of setting the calling tasks hook
rgrover1 0:8e57f3e9cc89 1112 * function.
rgrover1 0:8e57f3e9cc89 1113 */
rgrover1 0:8e57f3e9cc89 1114 void vTaskSetApplicationTaskTag( xTaskHandle xTask, pdTASK_HOOK_CODE pxHookFunction ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 1115
rgrover1 0:8e57f3e9cc89 1116 /**
rgrover1 0:8e57f3e9cc89 1117 * task.h
rgrover1 0:8e57f3e9cc89 1118 * <pre>void xTaskGetApplicationTaskTag( xTaskHandle xTask );</pre>
rgrover1 0:8e57f3e9cc89 1119 *
rgrover1 0:8e57f3e9cc89 1120 * Returns the pxHookFunction value assigned to the task xTask.
rgrover1 0:8e57f3e9cc89 1121 */
rgrover1 0:8e57f3e9cc89 1122 pdTASK_HOOK_CODE xTaskGetApplicationTaskTag( xTaskHandle xTask ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 1123 #endif /* configUSE_APPLICATION_TASK_TAG ==1 */
rgrover1 0:8e57f3e9cc89 1124 #endif /* ifdef configUSE_APPLICATION_TASK_TAG */
rgrover1 0:8e57f3e9cc89 1125
rgrover1 0:8e57f3e9cc89 1126 /**
rgrover1 0:8e57f3e9cc89 1127 * task.h
rgrover1 0:8e57f3e9cc89 1128 * <pre>portBASE_TYPE xTaskCallApplicationTaskHook( xTaskHandle xTask, pdTASK_HOOK_CODE pxHookFunction );</pre>
rgrover1 0:8e57f3e9cc89 1129 *
rgrover1 0:8e57f3e9cc89 1130 * Calls the hook function associated with xTask. Passing xTask as NULL has
rgrover1 0:8e57f3e9cc89 1131 * the effect of calling the Running tasks (the calling task) hook function.
rgrover1 0:8e57f3e9cc89 1132 *
rgrover1 0:8e57f3e9cc89 1133 * pvParameter is passed to the hook function for the task to interpret as it
rgrover1 0:8e57f3e9cc89 1134 * wants.
rgrover1 0:8e57f3e9cc89 1135 */
rgrover1 0:8e57f3e9cc89 1136 portBASE_TYPE xTaskCallApplicationTaskHook( xTaskHandle xTask, void *pvParameter ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 1137
rgrover1 0:8e57f3e9cc89 1138 /**
rgrover1 0:8e57f3e9cc89 1139 * xTaskGetIdleTaskHandle() is only available if
rgrover1 0:8e57f3e9cc89 1140 * INCLUDE_xTaskGetIdleTaskHandle is set to 1 in FreeRTOSConfig.h.
rgrover1 0:8e57f3e9cc89 1141 *
rgrover1 0:8e57f3e9cc89 1142 * Simply returns the handle of the idle task. It is not valid to call
rgrover1 0:8e57f3e9cc89 1143 * xTaskGetIdleTaskHandle() before the scheduler has been started.
rgrover1 0:8e57f3e9cc89 1144 */
rgrover1 0:8e57f3e9cc89 1145 xTaskHandle xTaskGetIdleTaskHandle( void );
rgrover1 0:8e57f3e9cc89 1146
rgrover1 0:8e57f3e9cc89 1147 /**
rgrover1 0:8e57f3e9cc89 1148 * configUSE_TRACE_FACILITY must bet defined as 1 in FreeRTOSConfig.h for
rgrover1 0:8e57f3e9cc89 1149 * uxTaskGetSystemState() to be available.
rgrover1 0:8e57f3e9cc89 1150 *
rgrover1 0:8e57f3e9cc89 1151 * uxTaskGetSystemState() populates an xTaskStatusType structure for each task in
rgrover1 0:8e57f3e9cc89 1152 * the system. xTaskStatusType structures contain, among other things, members
rgrover1 0:8e57f3e9cc89 1153 * for the task handle, task name, task priority, task state, and total amount
rgrover1 0:8e57f3e9cc89 1154 * of run time consumed by the task. See the xTaskStatusType structure
rgrover1 0:8e57f3e9cc89 1155 * definition in this file for the full member list.
rgrover1 0:8e57f3e9cc89 1156 *
rgrover1 0:8e57f3e9cc89 1157 * NOTE: This function is intended for debugging use only as its use results in
rgrover1 0:8e57f3e9cc89 1158 * the scheduler remaining suspended for an extended period.
rgrover1 0:8e57f3e9cc89 1159 *
rgrover1 0:8e57f3e9cc89 1160 * @param pxTaskStatusArray A pointer to an array of xTaskStatusType structures.
rgrover1 0:8e57f3e9cc89 1161 * The array must contain at least one xTaskStatusType structure for each task
rgrover1 0:8e57f3e9cc89 1162 * that is under the control of the RTOS. The number of tasks under the control
rgrover1 0:8e57f3e9cc89 1163 * of the RTOS can be determined using the uxTaskGetNumberOfTasks() API function.
rgrover1 0:8e57f3e9cc89 1164 *
rgrover1 0:8e57f3e9cc89 1165 * @param uxArraySize The size of the array pointed to by the pxTaskStatusArray
rgrover1 0:8e57f3e9cc89 1166 * parameter. The size is specified as the number of indexes in the array, or
rgrover1 0:8e57f3e9cc89 1167 * the number of xTaskStatusType structures contained in the array, not by the
rgrover1 0:8e57f3e9cc89 1168 * number of bytes in the array.
rgrover1 0:8e57f3e9cc89 1169 *
rgrover1 0:8e57f3e9cc89 1170 * @param pulTotalRunTime If configGENERATE_RUN_TIME_STATS is set to 1 in
rgrover1 0:8e57f3e9cc89 1171 * FreeRTOSConfig.h then *pulTotalRunTime is set by uxTaskGetSystemState() to the
rgrover1 0:8e57f3e9cc89 1172 * total run time (as defined by the run time stats clock, see
rgrover1 0:8e57f3e9cc89 1173 * http://www.freertos.org/rtos-run-time-stats.html) since the target booted.
rgrover1 0:8e57f3e9cc89 1174 * pulTotalRunTime can be set to NULL to omit the total run time information.
rgrover1 0:8e57f3e9cc89 1175 *
rgrover1 0:8e57f3e9cc89 1176 * @return The number of xTaskStatusType structures that were populated by
rgrover1 0:8e57f3e9cc89 1177 * uxTaskGetSystemState(). This should equal the number returned by the
rgrover1 0:8e57f3e9cc89 1178 * uxTaskGetNumberOfTasks() API function, but will be zero if the value passed
rgrover1 0:8e57f3e9cc89 1179 * in the uxArraySize parameter was too small.
rgrover1 0:8e57f3e9cc89 1180 *
rgrover1 0:8e57f3e9cc89 1181 * Example usage:
rgrover1 0:8e57f3e9cc89 1182 <pre>
rgrover1 0:8e57f3e9cc89 1183 // This example demonstrates how a human readable table of run time stats
rgrover1 0:8e57f3e9cc89 1184 // information is generated from raw data provided by uxTaskGetSystemState().
rgrover1 0:8e57f3e9cc89 1185 // The human readable table is written to pcWriteBuffer
rgrover1 0:8e57f3e9cc89 1186 void vTaskGetRunTimeStats( signed char *pcWriteBuffer )
rgrover1 0:8e57f3e9cc89 1187 {
rgrover1 0:8e57f3e9cc89 1188 xTaskStatusType *pxTaskStatusArray;
rgrover1 0:8e57f3e9cc89 1189 volatile unsigned portBASE_TYPE uxArraySize, x;
rgrover1 0:8e57f3e9cc89 1190 unsigned long ulTotalRunTime, ulStatsAsPercentage;
rgrover1 0:8e57f3e9cc89 1191
rgrover1 0:8e57f3e9cc89 1192 // Make sure the write buffer does not contain a string.
rgrover1 0:8e57f3e9cc89 1193 *pcWriteBuffer = 0x00;
rgrover1 0:8e57f3e9cc89 1194
rgrover1 0:8e57f3e9cc89 1195 // Take a snapshot of the number of tasks in case it changes while this
rgrover1 0:8e57f3e9cc89 1196 // function is executing.
rgrover1 0:8e57f3e9cc89 1197 uxArraySize = uxCurrentNumberOfTasks();
rgrover1 0:8e57f3e9cc89 1198
rgrover1 0:8e57f3e9cc89 1199 // Allocate a xTaskStatusType structure for each task. An array could be
rgrover1 0:8e57f3e9cc89 1200 // allocated statically at compile time.
rgrover1 0:8e57f3e9cc89 1201 pxTaskStatusArray = pvPortMalloc( uxCurrentNumberOfTasks * sizeof( xTaskStatusType ) );
rgrover1 0:8e57f3e9cc89 1202
rgrover1 0:8e57f3e9cc89 1203 if( pxTaskStatusArray != NULL )
rgrover1 0:8e57f3e9cc89 1204 {
rgrover1 0:8e57f3e9cc89 1205 // Generate raw status information about each task.
rgrover1 0:8e57f3e9cc89 1206 uxArraySize = uxTaskGetSystemState( pxTaskStatusArray, uxArraySize, &ulTotalRunTime );
rgrover1 0:8e57f3e9cc89 1207
rgrover1 0:8e57f3e9cc89 1208 // For percentage calculations.
rgrover1 0:8e57f3e9cc89 1209 ulTotalRunTime /= 100UL;
rgrover1 0:8e57f3e9cc89 1210
rgrover1 0:8e57f3e9cc89 1211 // Avoid divide by zero errors.
rgrover1 0:8e57f3e9cc89 1212 if( ulTotalRunTime > 0 )
rgrover1 0:8e57f3e9cc89 1213 {
rgrover1 0:8e57f3e9cc89 1214 // For each populated position in the pxTaskStatusArray array,
rgrover1 0:8e57f3e9cc89 1215 // format the raw data as human readable ASCII data
rgrover1 0:8e57f3e9cc89 1216 for( x = 0; x < uxArraySize; x++ )
rgrover1 0:8e57f3e9cc89 1217 {
rgrover1 0:8e57f3e9cc89 1218 // What percentage of the total run time has the task used?
rgrover1 0:8e57f3e9cc89 1219 // This will always be rounded down to the nearest integer.
rgrover1 0:8e57f3e9cc89 1220 // ulTotalRunTimeDiv100 has already been divided by 100.
rgrover1 0:8e57f3e9cc89 1221 ulStatsAsPercentage = pxTaskStatusArray[ x ].ulRunTimeCounter / ulTotalRunTime;
rgrover1 0:8e57f3e9cc89 1222
rgrover1 0:8e57f3e9cc89 1223 if( ulStatsAsPercentage > 0UL )
rgrover1 0:8e57f3e9cc89 1224 {
rgrover1 0:8e57f3e9cc89 1225 sprintf( ( char * ) pcWriteBuffer, ( char * ) "%s\t\t%lu\t\t%lu%%\r\n", pxTaskStatusArray[ x ].pcTaskName, pxTaskStatusArray[ x ].ulRunTimeCounter, ulStatsAsPercentage );
rgrover1 0:8e57f3e9cc89 1226 }
rgrover1 0:8e57f3e9cc89 1227 else
rgrover1 0:8e57f3e9cc89 1228 {
rgrover1 0:8e57f3e9cc89 1229 // If the percentage is zero here then the task has
rgrover1 0:8e57f3e9cc89 1230 // consumed less than 1% of the total run time.
rgrover1 0:8e57f3e9cc89 1231 sprintf( ( char * ) pcWriteBuffer, ( char * ) "%s\t\t%lu\t\t<1%%\r\n", pxTaskStatusArray[ x ].pcTaskName, pxTaskStatusArray[ x ].ulRunTimeCounter );
rgrover1 0:8e57f3e9cc89 1232 }
rgrover1 0:8e57f3e9cc89 1233
rgrover1 0:8e57f3e9cc89 1234 pcWriteBuffer += strlen( ( char * ) pcWriteBuffer );
rgrover1 0:8e57f3e9cc89 1235 }
rgrover1 0:8e57f3e9cc89 1236 }
rgrover1 0:8e57f3e9cc89 1237
rgrover1 0:8e57f3e9cc89 1238 // The array is no longer needed, free the memory it consumes.
rgrover1 0:8e57f3e9cc89 1239 vPortFree( pxTaskStatusArray );
rgrover1 0:8e57f3e9cc89 1240 }
rgrover1 0:8e57f3e9cc89 1241 }
rgrover1 0:8e57f3e9cc89 1242 </pre>
rgrover1 0:8e57f3e9cc89 1243 */
rgrover1 0:8e57f3e9cc89 1244 unsigned portBASE_TYPE uxTaskGetSystemState( xTaskStatusType *pxTaskStatusArray, unsigned portBASE_TYPE uxArraySize, unsigned long *pulTotalRunTime );
rgrover1 0:8e57f3e9cc89 1245
rgrover1 0:8e57f3e9cc89 1246 /**
rgrover1 0:8e57f3e9cc89 1247 * task. h
rgrover1 0:8e57f3e9cc89 1248 * <PRE>void vTaskList( char *pcWriteBuffer );</PRE>
rgrover1 0:8e57f3e9cc89 1249 *
rgrover1 0:8e57f3e9cc89 1250 * configUSE_TRACE_FACILITY and configUSE_STATS_FORMATTING_FUNCTIONS must
rgrover1 0:8e57f3e9cc89 1251 * both be defined as 1 for this function to be available. See the
rgrover1 0:8e57f3e9cc89 1252 * configuration section of the FreeRTOS.org website for more information.
rgrover1 0:8e57f3e9cc89 1253 *
rgrover1 0:8e57f3e9cc89 1254 * NOTE 1: This function will disable interrupts for its duration. It is
rgrover1 0:8e57f3e9cc89 1255 * not intended for normal application runtime use but as a debug aid.
rgrover1 0:8e57f3e9cc89 1256 *
rgrover1 0:8e57f3e9cc89 1257 * Lists all the current tasks, along with their current state and stack
rgrover1 0:8e57f3e9cc89 1258 * usage high water mark.
rgrover1 0:8e57f3e9cc89 1259 *
rgrover1 0:8e57f3e9cc89 1260 * Tasks are reported as blocked ('B'), ready ('R'), deleted ('D') or
rgrover1 0:8e57f3e9cc89 1261 * suspended ('S').
rgrover1 0:8e57f3e9cc89 1262 *
rgrover1 0:8e57f3e9cc89 1263 * PLEASE NOTE:
rgrover1 0:8e57f3e9cc89 1264 *
rgrover1 0:8e57f3e9cc89 1265 * This function is provided for convenience only, and is used by many of the
rgrover1 0:8e57f3e9cc89 1266 * demo applications. Do not consider it to be part of the scheduler.
rgrover1 0:8e57f3e9cc89 1267 *
rgrover1 0:8e57f3e9cc89 1268 * vTaskList() calls uxTaskGetSystemState(), then formats part of the
rgrover1 0:8e57f3e9cc89 1269 * uxTaskGetSystemState() output into a human readable table that displays task
rgrover1 0:8e57f3e9cc89 1270 * names, states and stack usage.
rgrover1 0:8e57f3e9cc89 1271 *
rgrover1 0:8e57f3e9cc89 1272 * vTaskList() has a dependency on the sprintf() C library function that might
rgrover1 0:8e57f3e9cc89 1273 * bloat the code size, use a lot of stack, and provide different results on
rgrover1 0:8e57f3e9cc89 1274 * different platforms. An alternative, tiny, third party, and limited
rgrover1 0:8e57f3e9cc89 1275 * functionality implementation of sprintf() is provided in many of the
rgrover1 0:8e57f3e9cc89 1276 * FreeRTOS/Demo sub-directories in a file called printf-stdarg.c (note
rgrover1 0:8e57f3e9cc89 1277 * printf-stdarg.c does not provide a full snprintf() implementation!).
rgrover1 0:8e57f3e9cc89 1278 *
rgrover1 0:8e57f3e9cc89 1279 * It is recommended that production systems call uxTaskGetSystemState()
rgrover1 0:8e57f3e9cc89 1280 * directly to get access to raw stats data, rather than indirectly through a
rgrover1 0:8e57f3e9cc89 1281 * call to vTaskList().
rgrover1 0:8e57f3e9cc89 1282 *
rgrover1 0:8e57f3e9cc89 1283 * @param pcWriteBuffer A buffer into which the above mentioned details
rgrover1 0:8e57f3e9cc89 1284 * will be written, in ascii form. This buffer is assumed to be large
rgrover1 0:8e57f3e9cc89 1285 * enough to contain the generated report. Approximately 40 bytes per
rgrover1 0:8e57f3e9cc89 1286 * task should be sufficient.
rgrover1 0:8e57f3e9cc89 1287 *
rgrover1 0:8e57f3e9cc89 1288 * \defgroup vTaskList vTaskList
rgrover1 0:8e57f3e9cc89 1289 * \ingroup TaskUtils
rgrover1 0:8e57f3e9cc89 1290 */
rgrover1 0:8e57f3e9cc89 1291 void vTaskList( signed char *pcWriteBuffer ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 1292
rgrover1 0:8e57f3e9cc89 1293 /**
rgrover1 0:8e57f3e9cc89 1294 * task. h
rgrover1 0:8e57f3e9cc89 1295 * <PRE>void vTaskGetRunTimeStats( char *pcWriteBuffer );</PRE>
rgrover1 0:8e57f3e9cc89 1296 *
rgrover1 0:8e57f3e9cc89 1297 * configGENERATE_RUN_TIME_STATS and configUSE_STATS_FORMATTING_FUNCTIONS
rgrover1 0:8e57f3e9cc89 1298 * must both be defined as 1 for this function to be available. The application
rgrover1 0:8e57f3e9cc89 1299 * must also then provide definitions for
rgrover1 0:8e57f3e9cc89 1300 * portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and portGET_RUN_TIME_COUNTER_VALUE
rgrover1 0:8e57f3e9cc89 1301 * to configure a peripheral timer/counter and return the timers current count
rgrover1 0:8e57f3e9cc89 1302 * value respectively. The counter should be at least 10 times the frequency of
rgrover1 0:8e57f3e9cc89 1303 * the tick count.
rgrover1 0:8e57f3e9cc89 1304 *
rgrover1 0:8e57f3e9cc89 1305 * NOTE 1: This function will disable interrupts for its duration. It is
rgrover1 0:8e57f3e9cc89 1306 * not intended for normal application runtime use but as a debug aid.
rgrover1 0:8e57f3e9cc89 1307 *
rgrover1 0:8e57f3e9cc89 1308 * Setting configGENERATE_RUN_TIME_STATS to 1 will result in a total
rgrover1 0:8e57f3e9cc89 1309 * accumulated execution time being stored for each task. The resolution
rgrover1 0:8e57f3e9cc89 1310 * of the accumulated time value depends on the frequency of the timer
rgrover1 0:8e57f3e9cc89 1311 * configured by the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() macro.
rgrover1 0:8e57f3e9cc89 1312 * Calling vTaskGetRunTimeStats() writes the total execution time of each
rgrover1 0:8e57f3e9cc89 1313 * task into a buffer, both as an absolute count value and as a percentage
rgrover1 0:8e57f3e9cc89 1314 * of the total system execution time.
rgrover1 0:8e57f3e9cc89 1315 *
rgrover1 0:8e57f3e9cc89 1316 * NOTE 2:
rgrover1 0:8e57f3e9cc89 1317 *
rgrover1 0:8e57f3e9cc89 1318 * This function is provided for convenience only, and is used by many of the
rgrover1 0:8e57f3e9cc89 1319 * demo applications. Do not consider it to be part of the scheduler.
rgrover1 0:8e57f3e9cc89 1320 *
rgrover1 0:8e57f3e9cc89 1321 * vTaskGetRunTimeStats() calls uxTaskGetSystemState(), then formats part of the
rgrover1 0:8e57f3e9cc89 1322 * uxTaskGetSystemState() output into a human readable table that displays the
rgrover1 0:8e57f3e9cc89 1323 * amount of time each task has spent in the Running state in both absolute and
rgrover1 0:8e57f3e9cc89 1324 * percentage terms.
rgrover1 0:8e57f3e9cc89 1325 *
rgrover1 0:8e57f3e9cc89 1326 * vTaskGetRunTimeStats() has a dependency on the sprintf() C library function
rgrover1 0:8e57f3e9cc89 1327 * that might bloat the code size, use a lot of stack, and provide different
rgrover1 0:8e57f3e9cc89 1328 * results on different platforms. An alternative, tiny, third party, and
rgrover1 0:8e57f3e9cc89 1329 * limited functionality implementation of sprintf() is provided in many of the
rgrover1 0:8e57f3e9cc89 1330 * FreeRTOS/Demo sub-directories in a file called printf-stdarg.c (note
rgrover1 0:8e57f3e9cc89 1331 * printf-stdarg.c does not provide a full snprintf() implementation!).
rgrover1 0:8e57f3e9cc89 1332 *
rgrover1 0:8e57f3e9cc89 1333 * It is recommended that production systems call uxTaskGetSystemState() directly
rgrover1 0:8e57f3e9cc89 1334 * to get access to raw stats data, rather than indirectly through a call to
rgrover1 0:8e57f3e9cc89 1335 * vTaskGetRunTimeStats().
rgrover1 0:8e57f3e9cc89 1336 *
rgrover1 0:8e57f3e9cc89 1337 * @param pcWriteBuffer A buffer into which the execution times will be
rgrover1 0:8e57f3e9cc89 1338 * written, in ascii form. This buffer is assumed to be large enough to
rgrover1 0:8e57f3e9cc89 1339 * contain the generated report. Approximately 40 bytes per task should
rgrover1 0:8e57f3e9cc89 1340 * be sufficient.
rgrover1 0:8e57f3e9cc89 1341 *
rgrover1 0:8e57f3e9cc89 1342 * \defgroup vTaskGetRunTimeStats vTaskGetRunTimeStats
rgrover1 0:8e57f3e9cc89 1343 * \ingroup TaskUtils
rgrover1 0:8e57f3e9cc89 1344 */
rgrover1 0:8e57f3e9cc89 1345 void vTaskGetRunTimeStats( signed char *pcWriteBuffer ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 1346
rgrover1 0:8e57f3e9cc89 1347 /*-----------------------------------------------------------
rgrover1 0:8e57f3e9cc89 1348 * SCHEDULER INTERNALS AVAILABLE FOR PORTING PURPOSES
rgrover1 0:8e57f3e9cc89 1349 *----------------------------------------------------------*/
rgrover1 0:8e57f3e9cc89 1350
rgrover1 0:8e57f3e9cc89 1351 /*
rgrover1 0:8e57f3e9cc89 1352 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS ONLY
rgrover1 0:8e57f3e9cc89 1353 * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS
rgrover1 0:8e57f3e9cc89 1354 * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
rgrover1 0:8e57f3e9cc89 1355 *
rgrover1 0:8e57f3e9cc89 1356 * Called from the real time kernel tick (either preemptive or cooperative),
rgrover1 0:8e57f3e9cc89 1357 * this increments the tick count and checks if any tasks that are blocked
rgrover1 0:8e57f3e9cc89 1358 * for a finite period required removing from a blocked list and placing on
rgrover1 0:8e57f3e9cc89 1359 * a ready list. If a non-zero value is returned then a context switch is
rgrover1 0:8e57f3e9cc89 1360 * required because either:
rgrover1 0:8e57f3e9cc89 1361 * + A task was removed from a blocked list because its timeout had expired,
rgrover1 0:8e57f3e9cc89 1362 * or
rgrover1 0:8e57f3e9cc89 1363 * + Time slicing is in use and there is a task of equal priority to the
rgrover1 0:8e57f3e9cc89 1364 * currently running task.
rgrover1 0:8e57f3e9cc89 1365 */
rgrover1 0:8e57f3e9cc89 1366 portBASE_TYPE xTaskIncrementTick( void ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 1367
rgrover1 0:8e57f3e9cc89 1368 /*
rgrover1 0:8e57f3e9cc89 1369 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN
rgrover1 0:8e57f3e9cc89 1370 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
rgrover1 0:8e57f3e9cc89 1371 *
rgrover1 0:8e57f3e9cc89 1372 * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED.
rgrover1 0:8e57f3e9cc89 1373 *
rgrover1 0:8e57f3e9cc89 1374 * Removes the calling task from the ready list and places it both
rgrover1 0:8e57f3e9cc89 1375 * on the list of tasks waiting for a particular event, and the
rgrover1 0:8e57f3e9cc89 1376 * list of delayed tasks. The task will be removed from both lists
rgrover1 0:8e57f3e9cc89 1377 * and replaced on the ready list should either the event occur (and
rgrover1 0:8e57f3e9cc89 1378 * there be no higher priority tasks waiting on the same event) or
rgrover1 0:8e57f3e9cc89 1379 * the delay period expires.
rgrover1 0:8e57f3e9cc89 1380 *
rgrover1 0:8e57f3e9cc89 1381 * @param pxEventList The list containing tasks that are blocked waiting
rgrover1 0:8e57f3e9cc89 1382 * for the event to occur.
rgrover1 0:8e57f3e9cc89 1383 *
rgrover1 0:8e57f3e9cc89 1384 * @param xTicksToWait The maximum amount of time that the task should wait
rgrover1 0:8e57f3e9cc89 1385 * for the event to occur. This is specified in kernel ticks,the constant
rgrover1 0:8e57f3e9cc89 1386 * portTICK_RATE_MS can be used to convert kernel ticks into a real time
rgrover1 0:8e57f3e9cc89 1387 * period.
rgrover1 0:8e57f3e9cc89 1388 */
rgrover1 0:8e57f3e9cc89 1389 void vTaskPlaceOnEventList( xList * const pxEventList, portTickType xTicksToWait ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 1390
rgrover1 0:8e57f3e9cc89 1391 /*
rgrover1 0:8e57f3e9cc89 1392 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN
rgrover1 0:8e57f3e9cc89 1393 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
rgrover1 0:8e57f3e9cc89 1394 *
rgrover1 0:8e57f3e9cc89 1395 * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED.
rgrover1 0:8e57f3e9cc89 1396 *
rgrover1 0:8e57f3e9cc89 1397 * This function performs nearly the same function as vTaskPlaceOnEventList().
rgrover1 0:8e57f3e9cc89 1398 * The difference being that this function does not permit tasks to block
rgrover1 0:8e57f3e9cc89 1399 * indefinitely, whereas vTaskPlaceOnEventList() does.
rgrover1 0:8e57f3e9cc89 1400 *
rgrover1 0:8e57f3e9cc89 1401 * @return pdTRUE if the task being removed has a higher priority than the task
rgrover1 0:8e57f3e9cc89 1402 * making the call, otherwise pdFALSE.
rgrover1 0:8e57f3e9cc89 1403 */
rgrover1 0:8e57f3e9cc89 1404 void vTaskPlaceOnEventListRestricted( xList * const pxEventList, portTickType xTicksToWait ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 1405
rgrover1 0:8e57f3e9cc89 1406 /*
rgrover1 0:8e57f3e9cc89 1407 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN
rgrover1 0:8e57f3e9cc89 1408 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
rgrover1 0:8e57f3e9cc89 1409 *
rgrover1 0:8e57f3e9cc89 1410 * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED.
rgrover1 0:8e57f3e9cc89 1411 *
rgrover1 0:8e57f3e9cc89 1412 * Removes a task from both the specified event list and the list of blocked
rgrover1 0:8e57f3e9cc89 1413 * tasks, and places it on a ready queue.
rgrover1 0:8e57f3e9cc89 1414 *
rgrover1 0:8e57f3e9cc89 1415 * xTaskRemoveFromEventList () will be called if either an event occurs to
rgrover1 0:8e57f3e9cc89 1416 * unblock a task, or the block timeout period expires.
rgrover1 0:8e57f3e9cc89 1417 *
rgrover1 0:8e57f3e9cc89 1418 * @return pdTRUE if the task being removed has a higher priority than the task
rgrover1 0:8e57f3e9cc89 1419 * making the call, otherwise pdFALSE.
rgrover1 0:8e57f3e9cc89 1420 */
rgrover1 0:8e57f3e9cc89 1421 signed portBASE_TYPE xTaskRemoveFromEventList( const xList * const pxEventList ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 1422
rgrover1 0:8e57f3e9cc89 1423 /*
rgrover1 0:8e57f3e9cc89 1424 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS ONLY
rgrover1 0:8e57f3e9cc89 1425 * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS
rgrover1 0:8e57f3e9cc89 1426 * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
rgrover1 0:8e57f3e9cc89 1427 *
rgrover1 0:8e57f3e9cc89 1428 * Sets the pointer to the current TCB to the TCB of the highest priority task
rgrover1 0:8e57f3e9cc89 1429 * that is ready to run.
rgrover1 0:8e57f3e9cc89 1430 */
rgrover1 0:8e57f3e9cc89 1431 void vTaskSwitchContext( void ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 1432
rgrover1 0:8e57f3e9cc89 1433 /*
rgrover1 0:8e57f3e9cc89 1434 * Return the handle of the calling task.
rgrover1 0:8e57f3e9cc89 1435 */
rgrover1 0:8e57f3e9cc89 1436 xTaskHandle xTaskGetCurrentTaskHandle( void ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 1437
rgrover1 0:8e57f3e9cc89 1438 /*
rgrover1 0:8e57f3e9cc89 1439 * Capture the current time status for future reference.
rgrover1 0:8e57f3e9cc89 1440 */
rgrover1 0:8e57f3e9cc89 1441 void vTaskSetTimeOutState( xTimeOutType * const pxTimeOut ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 1442
rgrover1 0:8e57f3e9cc89 1443 /*
rgrover1 0:8e57f3e9cc89 1444 * Compare the time status now with that previously captured to see if the
rgrover1 0:8e57f3e9cc89 1445 * timeout has expired.
rgrover1 0:8e57f3e9cc89 1446 */
rgrover1 0:8e57f3e9cc89 1447 portBASE_TYPE xTaskCheckForTimeOut( xTimeOutType * const pxTimeOut, portTickType * const pxTicksToWait ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 1448
rgrover1 0:8e57f3e9cc89 1449 /*
rgrover1 0:8e57f3e9cc89 1450 * Shortcut used by the queue implementation to prevent unnecessary call to
rgrover1 0:8e57f3e9cc89 1451 * taskYIELD();
rgrover1 0:8e57f3e9cc89 1452 */
rgrover1 0:8e57f3e9cc89 1453 void vTaskMissedYield( void ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 1454
rgrover1 0:8e57f3e9cc89 1455 /*
rgrover1 0:8e57f3e9cc89 1456 * Returns the scheduler state as taskSCHEDULER_RUNNING,
rgrover1 0:8e57f3e9cc89 1457 * taskSCHEDULER_NOT_STARTED or taskSCHEDULER_SUSPENDED.
rgrover1 0:8e57f3e9cc89 1458 */
rgrover1 0:8e57f3e9cc89 1459 portBASE_TYPE xTaskGetSchedulerState( void ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 1460
rgrover1 0:8e57f3e9cc89 1461 /*
rgrover1 0:8e57f3e9cc89 1462 * Raises the priority of the mutex holder to that of the calling task should
rgrover1 0:8e57f3e9cc89 1463 * the mutex holder have a priority less than the calling task.
rgrover1 0:8e57f3e9cc89 1464 */
rgrover1 0:8e57f3e9cc89 1465 void vTaskPriorityInherit( xTaskHandle const pxMutexHolder ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 1466
rgrover1 0:8e57f3e9cc89 1467 /*
rgrover1 0:8e57f3e9cc89 1468 * Set the priority of a task back to its proper priority in the case that it
rgrover1 0:8e57f3e9cc89 1469 * inherited a higher priority while it was holding a semaphore.
rgrover1 0:8e57f3e9cc89 1470 */
rgrover1 0:8e57f3e9cc89 1471 void vTaskPriorityDisinherit( xTaskHandle const pxMutexHolder ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 1472
rgrover1 0:8e57f3e9cc89 1473 /*
rgrover1 0:8e57f3e9cc89 1474 * Generic version of the task creation function which is in turn called by the
rgrover1 0:8e57f3e9cc89 1475 * xTaskCreate() and xTaskCreateRestricted() macros.
rgrover1 0:8e57f3e9cc89 1476 */
rgrover1 0:8e57f3e9cc89 1477 signed portBASE_TYPE xTaskGenericCreate( pdTASK_CODE pxTaskCode, const signed char * const pcName, unsigned short usStackDepth, void *pvParameters, unsigned portBASE_TYPE uxPriority, xTaskHandle *pxCreatedTask, portSTACK_TYPE *puxStackBuffer, const xMemoryRegion * const xRegions ) PRIVILEGED_FUNCTION;
rgrover1 0:8e57f3e9cc89 1478
rgrover1 0:8e57f3e9cc89 1479 /*
rgrover1 0:8e57f3e9cc89 1480 * Get the uxTCBNumber assigned to the task referenced by the xTask parameter.
rgrover1 0:8e57f3e9cc89 1481 */
rgrover1 0:8e57f3e9cc89 1482 unsigned portBASE_TYPE uxTaskGetTaskNumber( xTaskHandle xTask );
rgrover1 0:8e57f3e9cc89 1483
rgrover1 0:8e57f3e9cc89 1484 /*
rgrover1 0:8e57f3e9cc89 1485 * Set the uxTCBNumber of the task referenced by the xTask parameter to
rgrover1 0:8e57f3e9cc89 1486 * ucHandle.
rgrover1 0:8e57f3e9cc89 1487 */
rgrover1 0:8e57f3e9cc89 1488 void vTaskSetTaskNumber( xTaskHandle xTask, unsigned portBASE_TYPE uxHandle );
rgrover1 0:8e57f3e9cc89 1489
rgrover1 0:8e57f3e9cc89 1490 /*
rgrover1 0:8e57f3e9cc89 1491 * If tickless mode is being used, or a low power mode is implemented, then
rgrover1 0:8e57f3e9cc89 1492 * the tick interrupt will not execute during idle periods. When this is the
rgrover1 0:8e57f3e9cc89 1493 * case, the tick count value maintained by the scheduler needs to be kept up
rgrover1 0:8e57f3e9cc89 1494 * to date with the actual execution time by being skipped forward by the by
rgrover1 0:8e57f3e9cc89 1495 * a time equal to the idle period.
rgrover1 0:8e57f3e9cc89 1496 */
rgrover1 0:8e57f3e9cc89 1497 void vTaskStepTick( portTickType xTicksToJump );
rgrover1 0:8e57f3e9cc89 1498
rgrover1 0:8e57f3e9cc89 1499 /*
rgrover1 0:8e57f3e9cc89 1500 * Provided for use within portSUPPRESS_TICKS_AND_SLEEP() to allow the port
rgrover1 0:8e57f3e9cc89 1501 * specific sleep function to determine if it is ok to proceed with the sleep,
rgrover1 0:8e57f3e9cc89 1502 * and if it is ok to proceed, if it is ok to sleep indefinitely.
rgrover1 0:8e57f3e9cc89 1503 *
rgrover1 0:8e57f3e9cc89 1504 * This function is necessary because portSUPPRESS_TICKS_AND_SLEEP() is only
rgrover1 0:8e57f3e9cc89 1505 * called with the scheduler suspended, not from within a critical section. It
rgrover1 0:8e57f3e9cc89 1506 * is therefore possible for an interrupt to request a context switch between
rgrover1 0:8e57f3e9cc89 1507 * portSUPPRESS_TICKS_AND_SLEEP() and the low power mode actually being
rgrover1 0:8e57f3e9cc89 1508 * entered. eTaskConfirmSleepModeStatus() should be called from a short
rgrover1 0:8e57f3e9cc89 1509 * critical section between the timer being stopped and the sleep mode being
rgrover1 0:8e57f3e9cc89 1510 * entered to ensure it is ok to proceed into the sleep mode.
rgrover1 0:8e57f3e9cc89 1511 */
rgrover1 0:8e57f3e9cc89 1512 eSleepModeStatus eTaskConfirmSleepModeStatus( void );
rgrover1 0:8e57f3e9cc89 1513
rgrover1 0:8e57f3e9cc89 1514 #ifdef __cplusplus
rgrover1 0:8e57f3e9cc89 1515 }
rgrover1 0:8e57f3e9cc89 1516 #endif
rgrover1 0:8e57f3e9cc89 1517 #endif /* INC_TASK_H */
rgrover1 0:8e57f3e9cc89 1518
rgrover1 0:8e57f3e9cc89 1519
rgrover1 0:8e57f3e9cc89 1520