00001 /* 00002 FreeRTOS V6.0.0 - Copyright (C) 2009 Real Time Engineers Ltd. 00003 00004 *************************************************************************** 00005 * * 00006 * If you are: * 00007 * * 00008 * + New to FreeRTOS, * 00009 * + Wanting to learn FreeRTOS or multitasking in general quickly * 00010 * + Looking for basic training, * 00011 * + Wanting to improve your FreeRTOS skills and productivity * 00012 * * 00013 * then take a look at the FreeRTOS eBook * 00014 * * 00015 * "Using the FreeRTOS Real Time Kernel - a Practical Guide" * 00016 * http://www.FreeRTOS.org/Documentation * 00017 * * 00018 * A pdf reference manual is also available. Both are usually delivered * 00019 * to your inbox within 20 minutes to two hours when purchased between 8am * 00020 * and 8pm GMT (although please allow up to 24 hours in case of * 00021 * exceptional circumstances). Thank you for your support! * 00022 * * 00023 *************************************************************************** 00024 00025 This file is part of the FreeRTOS distribution. 00026 00027 FreeRTOS is free software; you can redistribute it and/or modify it under 00028 the terms of the GNU General Public License (version 2) as published by the 00029 Free Software Foundation AND MODIFIED BY the FreeRTOS exception. 00030 ***NOTE*** The exception to the GPL is included to allow you to distribute 00031 a combined work that includes FreeRTOS without being obliged to provide the 00032 source code for proprietary components outside of the FreeRTOS kernel. 00033 FreeRTOS is distributed in the hope that it will be useful, but WITHOUT 00034 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 00035 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for 00036 more details. You should have received a copy of the GNU General Public 00037 License and the FreeRTOS license exception along with FreeRTOS; if not it 00038 can be viewed here: http://www.freertos.org/a00114.html and also obtained 00039 by writing to Richard Barry, contact details for whom are available on the 00040 FreeRTOS WEB site. 00041 00042 1 tab == 4 spaces! 00043 00044 http://www.FreeRTOS.org - Documentation, latest information, license and 00045 contact details. 00046 00047 http://www.SafeRTOS.com - A version that is certified for use in safety 00048 critical systems. 00049 00050 http://www.OpenRTOS.com - Commercial support, development, porting, 00051 licensing and training services. 00052 */ 00053 00054 00055 #ifndef INC_FREERTOS_H 00056 #error "#include FreeRTOS.h" must appear in source files before "#include task.h" 00057 #endif 00058 00059 00060 00061 #ifndef TASK_H 00062 #define TASK_H 00063 00064 #include "portable.h" 00065 #include "list.h" 00066 00067 #ifdef __cplusplus 00068 extern "C" { 00069 #endif 00070 00071 /*----------------------------------------------------------- 00072 * MACROS AND DEFINITIONS 00073 *----------------------------------------------------------*/ 00074 00075 #define tskKERNEL_VERSION_NUMBER "V6.0.0" 00076 00087 typedef void * xTaskHandle; 00088 00089 /* 00090 * Used internally only. 00091 */ 00092 typedef struct xTIME_OUT 00093 { 00094 portBASE_TYPE xOverflowCount; 00095 portTickType xTimeOnEntering; 00096 } xTimeOutType; 00097 00098 /* 00099 * Defines the memory ranges allocated to the task when an MPU is used. 00100 */ 00101 typedef struct xMEMORY_REGION 00102 { 00103 void *pvBaseAddress; 00104 unsigned long ulLengthInBytes; 00105 unsigned long ulParameters; 00106 } xMemoryRegion; 00107 00108 /* 00109 * Parameters required to create an MPU protected task. 00110 */ 00111 typedef struct xTASK_PARAMTERS 00112 { 00113 pdTASK_CODE pvTaskCode; 00114 const signed char * const pcName; 00115 unsigned short usStackDepth; 00116 void *pvParameters; 00117 unsigned portBASE_TYPE uxPriority; 00118 portSTACK_TYPE *puxStackBuffer; 00119 xMemoryRegion xRegions[ portNUM_CONFIGURABLE_REGIONS ]; 00120 } xTaskParameters; 00121 00122 /* 00123 * Defines the priority used by the idle task. This must not be modified. 00124 * 00125 * \ingroup TaskUtils 00126 */ 00127 #define tskIDLE_PRIORITY ( ( unsigned portBASE_TYPE ) 0 ) 00128 00137 #define taskYIELD() portYIELD() 00138 00151 #define taskENTER_CRITICAL() portENTER_CRITICAL() 00152 00165 #define taskEXIT_CRITICAL() portEXIT_CRITICAL() 00166 00175 #define taskDISABLE_INTERRUPTS() portDISABLE_INTERRUPTS() 00176 00185 #define taskENABLE_INTERRUPTS() portENABLE_INTERRUPTS() 00186 00187 /* Definitions returned by xTaskGetSchedulerState(). */ 00188 #define taskSCHEDULER_NOT_STARTED 0 00189 #define taskSCHEDULER_RUNNING 1 00190 #define taskSCHEDULER_SUSPENDED 2 00191 00192 /*----------------------------------------------------------- 00193 * TASK CREATION API 00194 *----------------------------------------------------------*/ 00195 00272 #define xTaskCreate( pvTaskCode, pcName, usStackDepth, pvParameters, uxPriority, pxCreatedTask ) xTaskGenericCreate( ( pvTaskCode ), ( pcName ), ( usStackDepth ), ( pvParameters ), ( uxPriority ), ( pxCreatedTask ), ( NULL ), ( NULL ) ) 00273 00345 #define xTaskCreateRestricted( x, pxCreatedTask ) xTaskGenericCreate( ((x)->pvTaskCode), ((x)->pcName), ((x)->usStackDepth), ((x)->pvParameters), ((x)->uxPriority), (pxCreatedTask), ((x)->puxStackBuffer), ((x)->xRegions) ) 00346 00393 void vTaskAllocateMPURegions( xTaskHandle xTask, const xMemoryRegion * const pxRegions ) PRIVILEGED_FUNCTION; 00394 00434 void vTaskDelete( xTaskHandle pxTask ) PRIVILEGED_FUNCTION; 00435 00436 00437 /*----------------------------------------------------------- 00438 * TASK CONTROL API 00439 *----------------------------------------------------------*/ 00440 00489 void vTaskDelay( portTickType xTicksToDelay ) PRIVILEGED_FUNCTION; 00490 00548 void vTaskDelayUntil( portTickType * const pxPreviousWakeTime, portTickType xTimeIncrement ) PRIVILEGED_FUNCTION; 00549 00595 unsigned portBASE_TYPE uxTaskPriorityGet( xTaskHandle pxTask ) PRIVILEGED_FUNCTION; 00596 00637 void vTaskPrioritySet( xTaskHandle pxTask, unsigned portBASE_TYPE uxNewPriority ) PRIVILEGED_FUNCTION; 00638 00688 void vTaskSuspend( xTaskHandle pxTaskToSuspend ) PRIVILEGED_FUNCTION; 00689 00737 void vTaskResume( xTaskHandle pxTaskToResume ) PRIVILEGED_FUNCTION; 00738 00757 portBASE_TYPE xTaskResumeFromISR( xTaskHandle pxTaskToResume ) PRIVILEGED_FUNCTION; 00758 00759 /*----------------------------------------------------------- 00760 * SCHEDULER CONTROL 00761 *----------------------------------------------------------*/ 00762 00795 void vTaskStartScheduler( void ) PRIVILEGED_FUNCTION; 00796 00848 void vTaskEndScheduler( void ) PRIVILEGED_FUNCTION; 00849 00899 void vTaskSuspendAll( void ) PRIVILEGED_FUNCTION; 00900 00951 signed portBASE_TYPE xTaskResumeAll( void ) PRIVILEGED_FUNCTION; 00952 00962 signed portBASE_TYPE xTaskIsTaskSuspended( xTaskHandle xTask ) PRIVILEGED_FUNCTION; 00963 00964 /*----------------------------------------------------------- 00965 * TASK UTILITIES 00966 *----------------------------------------------------------*/ 00967 00977 portTickType xTaskGetTickCount( void ) PRIVILEGED_FUNCTION; 00978 00991 unsigned portBASE_TYPE uxTaskGetNumberOfTasks( void ) PRIVILEGED_FUNCTION; 00992 01017 void vTaskList( signed char *pcWriteBuffer ) PRIVILEGED_FUNCTION; 01018 01049 void vTaskGetRunTimeStats( signed char *pcWriteBuffer ) PRIVILEGED_FUNCTION; 01050 01070 void vTaskStartTrace( signed char * pcBuffer, unsigned long ulBufferSize ) PRIVILEGED_FUNCTION; 01071 01083 unsigned long ulTaskEndTrace( void ) PRIVILEGED_FUNCTION; 01084 01103 unsigned portBASE_TYPE uxTaskGetStackHighWaterMark( xTaskHandle xTask ) PRIVILEGED_FUNCTION; 01104 01113 void vTaskSetApplicationTaskTag( xTaskHandle xTask, pdTASK_HOOK_CODE pxHookFunction ) PRIVILEGED_FUNCTION; 01114 01121 pdTASK_HOOK_CODE xTaskGetApplicationTaskTag( xTaskHandle xTask ) PRIVILEGED_FUNCTION; 01122 01133 portBASE_TYPE xTaskCallApplicationTaskHook( xTaskHandle xTask, void *pvParameter ) PRIVILEGED_FUNCTION; 01134 01135 01136 /*----------------------------------------------------------- 01137 * SCHEDULER INTERNALS AVAILABLE FOR PORTING PURPOSES 01138 *----------------------------------------------------------*/ 01139 01140 /* 01141 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS ONLY 01142 * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS 01143 * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER. 01144 * 01145 * Called from the real time kernel tick (either preemptive or cooperative), 01146 * this increments the tick count and checks if any tasks that are blocked 01147 * for a finite period required removing from a blocked list and placing on 01148 * a ready list. 01149 */ 01150 void vTaskIncrementTick( void ) PRIVILEGED_FUNCTION; 01151 01152 /* 01153 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN 01154 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER. 01155 * 01156 * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED. 01157 * 01158 * Removes the calling task from the ready list and places it both 01159 * on the list of tasks waiting for a particular event, and the 01160 * list of delayed tasks. The task will be removed from both lists 01161 * and replaced on the ready list should either the event occur (and 01162 * there be no higher priority tasks waiting on the same event) or 01163 * the delay period expires. 01164 * 01165 * @param pxEventList The list containing tasks that are blocked waiting 01166 * for the event to occur. 01167 * 01168 * @param xTicksToWait The maximum amount of time that the task should wait 01169 * for the event to occur. This is specified in kernel ticks,the constant 01170 * portTICK_RATE_MS can be used to convert kernel ticks into a real time 01171 * period. 01172 */ 01173 void vTaskPlaceOnEventList( const xList * const pxEventList, portTickType xTicksToWait ) PRIVILEGED_FUNCTION; 01174 01175 /* 01176 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN 01177 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER. 01178 * 01179 * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED. 01180 * 01181 * Removes a task from both the specified event list and the list of blocked 01182 * tasks, and places it on a ready queue. 01183 * 01184 * xTaskRemoveFromEventList () will be called if either an event occurs to 01185 * unblock a task, or the block timeout period expires. 01186 * 01187 * @return pdTRUE if the task being removed has a higher priority than the task 01188 * making the call, otherwise pdFALSE. 01189 */ 01190 signed portBASE_TYPE xTaskRemoveFromEventList( const xList * const pxEventList ) PRIVILEGED_FUNCTION; 01191 01192 /* 01193 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN 01194 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER. 01195 * 01196 * INCLUDE_vTaskCleanUpResources and INCLUDE_vTaskSuspend must be defined as 1 01197 * for this function to be available. 01198 * See the configuration section for more information. 01199 * 01200 * Empties the ready and delayed queues of task control blocks, freeing the 01201 * memory allocated for the task control block and task stacks as it goes. 01202 */ 01203 void vTaskCleanUpResources( void ) PRIVILEGED_FUNCTION; 01204 01205 /* 01206 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS ONLY 01207 * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS 01208 * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER. 01209 * 01210 * Sets the pointer to the current TCB to the TCB of the highest priority task 01211 * that is ready to run. 01212 */ 01213 void vTaskSwitchContext( void ) PRIVILEGED_FUNCTION; 01214 01215 /* 01216 * Return the handle of the calling task. 01217 */ 01218 xTaskHandle xTaskGetCurrentTaskHandle( void ) PRIVILEGED_FUNCTION; 01219 01220 /* 01221 * Capture the current time status for future reference. 01222 */ 01223 void vTaskSetTimeOutState( xTimeOutType * const pxTimeOut ) PRIVILEGED_FUNCTION; 01224 01225 /* 01226 * Compare the time status now with that previously captured to see if the 01227 * timeout has expired. 01228 */ 01229 portBASE_TYPE xTaskCheckForTimeOut( xTimeOutType * const pxTimeOut, portTickType * const pxTicksToWait ) PRIVILEGED_FUNCTION; 01230 01231 /* 01232 * Shortcut used by the queue implementation to prevent unnecessary call to 01233 * taskYIELD(); 01234 */ 01235 void vTaskMissedYield( void ) PRIVILEGED_FUNCTION; 01236 01237 /* 01238 * Returns the scheduler state as taskSCHEDULER_RUNNING, 01239 * taskSCHEDULER_NOT_STARTED or taskSCHEDULER_SUSPENDED. 01240 */ 01241 portBASE_TYPE xTaskGetSchedulerState( void ) PRIVILEGED_FUNCTION; 01242 01243 /* 01244 * Raises the priority of the mutex holder to that of the calling task should 01245 * the mutex holder have a priority less than the calling task. 01246 */ 01247 void vTaskPriorityInherit( xTaskHandle * const pxMutexHolder ) PRIVILEGED_FUNCTION; 01248 01249 /* 01250 * Set the priority of a task back to its proper priority in the case that it 01251 * inherited a higher priority while it was holding a semaphore. 01252 */ 01253 void vTaskPriorityDisinherit( xTaskHandle * const pxMutexHolder ) PRIVILEGED_FUNCTION; 01254 01255 /* 01256 * Generic version of the task creation function which is in turn called by the 01257 * xTaskCreate() and xTaskCreateProtected() macros. 01258 */ 01259 signed portBASE_TYPE xTaskGenericCreate( pdTASK_CODE pvTaskCode, 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; 01260 01261 #ifdef __cplusplus 01262 } 01263 #endif 01264 #endif /* TASK_H */ 01265 01266 01267