diff options
Diffstat (limited to 'freertos/Source/include/task.h')
| -rw-r--r-- | freertos/Source/include/task.h | 424 |
1 files changed, 329 insertions, 95 deletions
diff --git a/freertos/Source/include/task.h b/freertos/Source/include/task.h index 3e9402f..4c6913f 100644 --- a/freertos/Source/include/task.h +++ b/freertos/Source/include/task.h @@ -1,5 +1,5 @@ /* - FreeRTOS V8.2.3 - Copyright (C) 2015 Real Time Engineers Ltd. + FreeRTOS V9.0.0 - Copyright (C) 2016 Real Time Engineers Ltd. All rights reserved VISIT http://www.FreeRTOS.org TO ENSURE YOU ARE USING THE LATEST VERSION. @@ -85,10 +85,10 @@ extern "C" { * MACROS AND DEFINITIONS *----------------------------------------------------------*/ -#define tskKERNEL_VERSION_NUMBER "V8.2.3" -#define tskKERNEL_VERSION_MAJOR 8 -#define tskKERNEL_VERSION_MINOR 2 -#define tskKERNEL_VERSION_BUILD 3 +#define tskKERNEL_VERSION_NUMBER "V9.0.0" +#define tskKERNEL_VERSION_MAJOR 9 +#define tskKERNEL_VERSION_MINOR 0 +#define tskKERNEL_VERSION_BUILD 0 /** * task. h @@ -115,7 +115,8 @@ typedef enum eReady, /* The task being queried is in a read or pending ready list. */ eBlocked, /* The task being queried is in the Blocked state. */ eSuspended, /* The task being queried is in the Suspended state, or is in the Blocked state with an infinite time out. */ - eDeleted /* The task being queried has been deleted, but its TCB has not yet been freed. */ + eDeleted, /* The task being queried has been deleted, but its TCB has not yet been freed. */ + eInvalid /* Used as an 'invalid state' value. */ } eTaskState; /* Actions that can be performed when vTaskNotify() is called. */ @@ -166,24 +167,24 @@ in the system. */ typedef struct xTASK_STATUS { TaskHandle_t xHandle; /* The handle of the task to which the rest of the information in the structure relates. */ - const char *pcTaskName; /* A pointer to the task's name. This value is invalid if the task was deleted since the structure was populated! */ /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ + const char *pcTaskName; /* A pointer to the task's name. This value will be invalid if the task was deleted since the structure was populated! */ /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ UBaseType_t xTaskNumber; /* A number unique to the task. */ eTaskState eCurrentState; /* The state in which the task existed when the structure was populated. */ UBaseType_t uxCurrentPriority; /* The priority at which the task was running (may be inherited) when the structure was populated. */ - UBaseType_t uxBasePriority; /* The priority to which the task returns 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. */ + UBaseType_t uxBasePriority; /* The priority to which the task will return if the task's current priority has been inherited to avoid unbounded priority inversion when obtaining a mutex. Only valid if configUSE_MUTEXES is defined as 1 in FreeRTOSConfig.h. */ uint32_t ulRunTimeCounter; /* The total run time allocated to the task so far, as defined by the run time stats clock. See http://www.freertos.org/rtos-run-time-stats.html. Only valid when configGENERATE_RUN_TIME_STATS is defined as 1 in FreeRTOSConfig.h. */ + StackType_t *pxStackBase; /* Points to the lowest address of the task's stack area. */ uint16_t usStackHighWaterMark; /* The minimum amount of stack space that has remained for the task since the task was created. The closer this value is to zero the closer the task has come to overflowing its stack. */ } TaskStatus_t; /* Possible return values for eTaskConfirmSleepModeStatus(). */ typedef enum { - eAbortSleep = 0, /* A task has been made ready or a context switch was pending since portSUPPORESS_TICKS_AND_SLEEP() was called - abort entering a sleep mode. */ - eStandardSleep, /* Enter a sleep mode that does not last any longer than the expected idle time. */ + 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. */ + eStandardSleep, /* Enter a sleep mode that will not last any longer than the expected idle time. */ 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. */ } eSleepModeStatus; - /** * Defines the priority used by the idle task. This must not be modified. * @@ -276,6 +277,19 @@ is used in assert() statements. */ * * Create a new task and add it to the list of tasks that are ready to run. * + * Internally, within the FreeRTOS implementation, tasks use two blocks of + * memory. The first block is used to hold the task's data structures. The + * second block is used by the task as its stack. If a task is created using + * xTaskCreate() then both blocks of memory are automatically dynamically + * allocated inside the xTaskCreate() function. (see + * http://www.freertos.org/a00111.html). If a task is created using + * xTaskCreateStatic() then the application writer must provide the required + * memory. xTaskCreateStatic() therefore allows a task to be created without + * using any dynamic memory allocation. + * + * See xTaskCreateStatic() for a version that does not use any dynamic memory + * allocation. + * * xTaskCreate() can only be used to create a task that has unrestricted * access to the entire microcontroller memory map. Systems that include MPU * support can alternatively create an MPU constrained task using @@ -291,9 +305,9 @@ is used in assert() statements. */ * @param usStackDepth The size of the task stack specified as the number of * variables the stack can hold - not the number of bytes. For example, if * the stack is 16 bits wide and usStackDepth is defined as 100, 200 bytes - * are allocated for stack storage. + * will be allocated for stack storage. * - * @param pvParameters Pointer that is used as the parameter for the task + * @param pvParameters Pointer that will be used as the parameter for the task * being created. * * @param uxPriority The priority at which the task should run. Systems that @@ -342,7 +356,131 @@ is used in assert() statements. */ * \defgroup xTaskCreate xTaskCreate * \ingroup Tasks */ -#define xTaskCreate( pvTaskCode, pcName, usStackDepth, pvParameters, uxPriority, pxCreatedTask ) xTaskGenericCreate( ( pvTaskCode ), ( pcName ), ( usStackDepth ), ( pvParameters ), ( uxPriority ), ( pxCreatedTask ), ( NULL ), ( NULL ) ) +#if( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) + BaseType_t xTaskCreate( TaskFunction_t pxTaskCode, + const char * const pcName, + const uint16_t usStackDepth, + void * const pvParameters, + UBaseType_t uxPriority, + TaskHandle_t * const pxCreatedTask ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ +#endif + +/** + * task. h + *<pre> + TaskHandle_t xTaskCreateStatic( TaskFunction_t pvTaskCode, + const char * const pcName, + uint32_t ulStackDepth, + void *pvParameters, + UBaseType_t uxPriority, + StackType_t *pxStackBuffer, + StaticTask_t *pxTaskBuffer );</pre> + * + * Create a new task and add it to the list of tasks that are ready to run. + * + * Internally, within the FreeRTOS implementation, tasks use two blocks of + * memory. The first block is used to hold the task's data structures. The + * second block is used by the task as its stack. If a task is created using + * xTaskCreate() then both blocks of memory are automatically dynamically + * allocated inside the xTaskCreate() function. (see + * http://www.freertos.org/a00111.html). If a task is created using + * xTaskCreateStatic() then the application writer must provide the required + * memory. xTaskCreateStatic() therefore allows a task to be created without + * using any dynamic memory allocation. + * + * @param pvTaskCode Pointer to the task entry function. Tasks + * must be implemented to never return (i.e. continuous loop). + * + * @param pcName A descriptive name for the task. This is mainly used to + * facilitate debugging. The maximum length of the string is defined by + * configMAX_TASK_NAME_LEN in FreeRTOSConfig.h. + * + * @param ulStackDepth The size of the task stack specified as the number of + * variables the stack can hold - not the number of bytes. For example, if + * the stack is 32-bits wide and ulStackDepth is defined as 100 then 400 bytes + * will be allocated for stack storage. + * + * @param pvParameters Pointer that will be used as the parameter for the task + * being created. + * + * @param uxPriority The priority at which the task will run. + * + * @param pxStackBuffer Must point to a StackType_t array that has at least + * ulStackDepth indexes - the array will then be used as the task's stack, + * removing the need for the stack to be allocated dynamically. + * + * @param pxTaskBuffer Must point to a variable of type StaticTask_t, which will + * then be used to hold the task's data structures, removing the need for the + * memory to be allocated dynamically. + * + * @return If neither pxStackBuffer or pxTaskBuffer are NULL, then the task will + * be created and pdPASS is returned. If either pxStackBuffer or pxTaskBuffer + * are NULL then the task will not be created and + * errCOULD_NOT_ALLOCATE_REQUIRED_MEMORY is returned. + * + * Example usage: + <pre> + + // Dimensions the buffer that the task being created will use as its stack. + // NOTE: This is the number of words the stack will hold, not the number of + // bytes. For example, if each stack item is 32-bits, and this is set to 100, + // then 400 bytes (100 * 32-bits) will be allocated. + #define STACK_SIZE 200 + + // Structure that will hold the TCB of the task being created. + StaticTask_t xTaskBuffer; + + // Buffer that the task being created will use as its stack. Note this is + // an array of StackType_t variables. The size of StackType_t is dependent on + // the RTOS port. + StackType_t xStack[ STACK_SIZE ]; + + // Function that implements the task being created. + void vTaskCode( void * pvParameters ) + { + // The parameter value is expected to be 1 as 1 is passed in the + // pvParameters value in the call to xTaskCreateStatic(). + configASSERT( ( uint32_t ) pvParameters == 1UL ); + + for( ;; ) + { + // Task code goes here. + } + } + + // Function that creates a task. + void vOtherFunction( void ) + { + TaskHandle_t xHandle = NULL; + + // Create the task without using any dynamic memory allocation. + xHandle = xTaskCreateStatic( + vTaskCode, // Function that implements the task. + "NAME", // Text name for the task. + STACK_SIZE, // Stack size in words, not bytes. + ( void * ) 1, // Parameter passed into the task. + tskIDLE_PRIORITY,// Priority at which the task is created. + xStack, // Array to use as the task's stack. + &xTaskBuffer ); // Variable to hold the task's data structure. + + // puxStackBuffer and pxTaskBuffer were not NULL, so the task will have + // been created, and xHandle will be the task's handle. Use the handle + // to suspend the task. + vTaskSuspend( xHandle ); + } + </pre> + * \defgroup xTaskCreateStatic xTaskCreateStatic + * \ingroup Tasks + */ +#if( configSUPPORT_STATIC_ALLOCATION == 1 ) + TaskHandle_t xTaskCreateStatic( TaskFunction_t pxTaskCode, + const char * const pcName, + const uint32_t ulStackDepth, + void * const pvParameters, + UBaseType_t uxPriority, + StackType_t * const puxStackBuffer, + StaticTask_t * const pxTaskBuffer ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ +#endif /* configSUPPORT_STATIC_ALLOCATION */ /** * task. h @@ -411,7 +549,9 @@ TaskHandle_t xHandle; * \defgroup xTaskCreateRestricted xTaskCreateRestricted * \ingroup Tasks */ -#define xTaskCreateRestricted( x, pxCreatedTask ) xTaskGenericCreate( ((x)->pvTaskCode), ((x)->pcName), ((x)->usStackDepth), ((x)->pvParameters), ((x)->uxPriority), (pxCreatedTask), ((x)->puxStackBuffer), ((x)->xRegions) ) +#if( portUSING_MPU_WRAPPERS == 1 ) + BaseType_t xTaskCreateRestricted( const TaskParameters_t * const pxTaskDefinition, TaskHandle_t *pxCreatedTask ) PRIVILEGED_FUNCTION; +#endif /** * task. h @@ -469,7 +609,7 @@ void vTaskAllocateMPURegions( TaskHandle_t xTask, const MemoryRegion_t * const p * See the configuration section for more information. * * Remove a task from the RTOS real time kernel's management. The task being - * deleted is removed from all ready, blocked, suspended and event lists. + * deleted will be removed from all ready, blocked, suspended and event lists. * * NOTE: The idle task is responsible for freeing the kernel allocated * memory from tasks that have been deleted. It is therefore important that @@ -481,8 +621,8 @@ void vTaskAllocateMPURegions( TaskHandle_t xTask, const MemoryRegion_t * const p * See the demo application file death.c for sample code that utilises * vTaskDelete (). * - * @param xTask The handle of the task to be deleted. Passing NULL - * causes the calling task to be deleted. + * @param xTask The handle of the task to be deleted. Passing NULL will + * cause the calling task to be deleted. * * Example usage: <pre> @@ -521,10 +661,10 @@ void vTaskDelete( TaskHandle_t xTaskToDelete ) PRIVILEGED_FUNCTION; * * vTaskDelay() specifies a time at which the task wishes to unblock relative to * the time at which vTaskDelay() is called. For example, specifying a block - * period of 100 ticks causes the task to unblock 100 ticks after + * period of 100 ticks will cause the task to unblock 100 ticks after * vTaskDelay() is called. vTaskDelay() does not therefore provide a good method * of controlling the frequency of a periodic task as the path taken through the - * code, as well as other task and interrupt activity, effects the frequency + * code, as well as other task and interrupt activity, will effect the frequency * at which vTaskDelay() gets called and therefore the time at which the task * next executes. See vTaskDelayUntil() for an alternative API function designed * to facilitate fixed frequency execution. It does this by specifying an @@ -564,8 +704,8 @@ void vTaskDelay( const TickType_t xTicksToDelay ) PRIVILEGED_FUNCTION; * Delay a task until a specified time. This function can be used by periodic * tasks to ensure a constant execution frequency. * - * This function differs from vTaskDelay () in one important aspect: vTaskDelay () - * causes a task to block for the specified number of ticks from the time vTaskDelay () is + * This function differs from vTaskDelay () in one important aspect: vTaskDelay () will + * cause a task to block for the specified number of ticks from the time vTaskDelay () is * called. It is therefore difficult to use vTaskDelay () by itself to generate a fixed * execution frequency as the time between a task starting to execute and that task * calling vTaskDelay () may not be fixed [the task may take a different path though the @@ -584,9 +724,9 @@ void vTaskDelay( const TickType_t xTicksToDelay ) PRIVILEGED_FUNCTION; * prior to its first use (see the example below). Following this the variable is * automatically updated within vTaskDelayUntil (). * - * @param xTimeIncrement The cycle time period. The task is unblocked at + * @param xTimeIncrement The cycle time period. The task will be unblocked at * time *pxPreviousWakeTime + xTimeIncrement. Calling vTaskDelayUntil with the - * same xTimeIncrement parameter value causes the task to execute with + * same xTimeIncrement parameter value will cause the task to execute with * a fixed interface period. * * Example usage: @@ -615,6 +755,31 @@ void vTaskDelayUntil( TickType_t * const pxPreviousWakeTime, const TickType_t xT /** * task. h + * <pre>BaseType_t xTaskAbortDelay( TaskHandle_t xTask );</pre> + * + * INCLUDE_xTaskAbortDelay must be defined as 1 in FreeRTOSConfig.h for this + * function to be available. + * + * A task will enter the Blocked state when it is waiting for an event. The + * event it is waiting for can be a temporal event (waiting for a time), such + * as when vTaskDelay() is called, or an event on an object, such as when + * xQueueReceive() or ulTaskNotifyTake() is called. If the handle of a task + * that is in the Blocked state is used in a call to xTaskAbortDelay() then the + * task will leave the Blocked state, and return from whichever function call + * placed the task into the Blocked state. + * + * @param xTask The handle of the task to remove from the Blocked state. + * + * @return If the task referenced by xTask was not in the Blocked state then + * pdFAIL is returned. Otherwise pdPASS is returned. + * + * \defgroup xTaskAbortDelay xTaskAbortDelay + * \ingroup TaskCtrl + */ +BaseType_t xTaskAbortDelay( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; + +/** + * task. h * <pre>UBaseType_t uxTaskPriorityGet( TaskHandle_t xTask );</pre> * * INCLUDE_uxTaskPriorityGet must be defined as 1 for this function to be available. @@ -688,6 +853,62 @@ eTaskState eTaskGetState( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; /** * task. h + * <pre>void vTaskGetInfo( TaskHandle_t xTask, TaskStatus_t *pxTaskStatus, BaseType_t xGetFreeStackSpace, eTaskState eState );</pre> + * + * configUSE_TRACE_FACILITY must be defined as 1 for this function to be + * available. See the configuration section for more information. + * + * Populates a TaskStatus_t structure with information about a task. + * + * @param xTask Handle of the task being queried. If xTask is NULL then + * information will be returned about the calling task. + * + * @param pxTaskStatus A pointer to the TaskStatus_t structure that will be + * filled with information about the task referenced by the handle passed using + * the xTask parameter. + * + * @xGetFreeStackSpace The TaskStatus_t structure contains a member to report + * the stack high water mark of the task being queried. Calculating the stack + * high water mark takes a relatively long time, and can make the system + * temporarily unresponsive - so the xGetFreeStackSpace parameter is provided to + * allow the high water mark checking to be skipped. The high watermark value + * will only be written to the TaskStatus_t structure if xGetFreeStackSpace is + * not set to pdFALSE; + * + * @param eState The TaskStatus_t structure contains a member to report the + * state of the task being queried. Obtaining the task state is not as fast as + * a simple assignment - so the eState parameter is provided to allow the state + * information to be omitted from the TaskStatus_t structure. To obtain state + * information then set eState to eInvalid - otherwise the value passed in + * eState will be reported as the task state in the TaskStatus_t structure. + * + * Example usage: + <pre> + void vAFunction( void ) + { + TaskHandle_t xHandle; + TaskStatus_t xTaskDetails; + + // Obtain the handle of a task from its name. + xHandle = xTaskGetHandle( "Task_Name" ); + + // Check the handle is not NULL. + configASSERT( xHandle ); + + // Use the handle to obtain further information about the task. + vTaskGetInfo( xHandle, + &xTaskDetails, + pdTRUE, // Include the high water mark in xTaskDetails. + eInvalid ); // Include the task state in xTaskDetails. + } + </pre> + * \defgroup vTaskGetInfo vTaskGetInfo + * \ingroup TaskCtrl + */ +void vTaskGetInfo( TaskHandle_t xTask, TaskStatus_t *pxTaskStatus, BaseType_t xGetFreeStackSpace, eTaskState eState ) PRIVILEGED_FUNCTION; + +/** + * task. h * <pre>void vTaskPrioritySet( TaskHandle_t xTask, UBaseType_t uxNewPriority );</pre> * * INCLUDE_vTaskPrioritySet must be defined as 1 for this function to be available. @@ -695,13 +916,13 @@ eTaskState eTaskGetState( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; * * Set the priority of any task. * - * A context switch occurs before the function returns if the priority + * A context switch will occur before the function returns if the priority * being set is higher than the currently executing task. * * @param xTask Handle to the task for which the priority is being set. * Passing a NULL handle results in the priority of the calling task being set. * - * @param uxNewPriority The priority to which the task is set. + * @param uxNewPriority The priority to which the task will be set. * * Example usage: <pre> @@ -735,7 +956,7 @@ void vTaskPrioritySet( TaskHandle_t xTask, UBaseType_t uxNewPriority ) PRIVILEGE * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available. * See the configuration section for more information. * - * Suspend any task. When suspended a task never gets any microcontroller + * Suspend any task. When suspended a task will never get any microcontroller * processing time, no matter what its priority. * * Calls to vTaskSuspend are not accumulative - @@ -743,7 +964,7 @@ void vTaskPrioritySet( TaskHandle_t xTask, UBaseType_t uxNewPriority ) PRIVILEGE * call to vTaskResume () to ready the suspended task. * * @param xTaskToSuspend Handle to the task being suspended. Passing a NULL - * handle causes the calling task to be suspended. + * handle will cause the calling task to be suspended. * * Example usage: <pre> @@ -761,7 +982,7 @@ void vTaskPrioritySet( TaskHandle_t xTask, UBaseType_t uxNewPriority ) PRIVILEGE // ... - // The created task does not run during this period, unless + // The created task will not run during this period, unless // another task calls vTaskResume( xHandle ). //... @@ -789,7 +1010,7 @@ void vTaskSuspend( TaskHandle_t xTaskToSuspend ) PRIVILEGED_FUNCTION; * Resumes a suspended task. * * A task that has been suspended by one or more calls to vTaskSuspend () - * is made available for running again by a single call to + * will be made available for running again by a single call to * vTaskResume (). * * @param xTaskToResume Handle to the task being readied. @@ -810,7 +1031,7 @@ void vTaskSuspend( TaskHandle_t xTaskToSuspend ) PRIVILEGED_FUNCTION; // ... - // The created task does not run during this period, unless + // The created task will not run during this period, unless // another task calls vTaskResume( xHandle ). //... @@ -819,7 +1040,7 @@ void vTaskSuspend( TaskHandle_t xTaskToSuspend ) PRIVILEGED_FUNCTION; // Resume the suspended task ourselves. vTaskResume( xHandle ); - // The created task once again gets the microcontroller processing + // The created task will once again get microcontroller processing // time in accordance with its priority within the system. } </pre> @@ -838,7 +1059,7 @@ void vTaskResume( TaskHandle_t xTaskToResume ) PRIVILEGED_FUNCTION; * An implementation of vTaskResume() that can be called from within an ISR. * * A task that has been suspended by one or more calls to vTaskSuspend () - * is made available for running again by a single call to + * will be made available for running again by a single call to * xTaskResumeFromISR (). * * xTaskResumeFromISR() should not be used to synchronise a task with an @@ -897,9 +1118,9 @@ void vTaskStartScheduler( void ) PRIVILEGED_FUNCTION; * NOTE: At the time of writing only the x86 real mode port, which runs on a PC * in place of DOS, implements this function. * - * Stops the real time kernel tick. All created tasks are automatically - * deleted and multitasking (either preemptive or cooperative) - * stops. Execution then resumes from the point where vTaskStartScheduler () + * Stops the real time kernel tick. All created tasks will be automatically + * deleted and multitasking (either preemptive or cooperative) will + * stop. Execution then resumes from the point where vTaskStartScheduler () * was called, as if vTaskStartScheduler () had just returned. * * See the demo application file main. c in the demo/PC directory for an @@ -909,8 +1130,8 @@ void vTaskStartScheduler( void ) PRIVILEGED_FUNCTION; * portable layer (see vPortEndScheduler () in port. c for the PC port). This * performs hardware specific operations such as stopping the kernel tick. * - * vTaskEndScheduler () causes all of the resources allocated by the - * kernel to be freed - but does not free resources allocated by application + * vTaskEndScheduler () will cause all of the resources allocated by the + * kernel to be freed - but will not free resources allocated by application * tasks. * * Example usage: @@ -950,7 +1171,7 @@ void vTaskEndScheduler( void ) PRIVILEGED_FUNCTION; * task. h * <pre>void vTaskSuspendAll( void );</pre> * - * Suspends the scheduler without disabling interrupts. Context switches does + * Suspends the scheduler without disabling interrupts. Context switches will * not occur while the scheduler is suspended. * * After calling vTaskSuspendAll () the calling task will continue to execute @@ -958,7 +1179,7 @@ void vTaskEndScheduler( void ) PRIVILEGED_FUNCTION; * made. * * API functions that have the potential to cause a context switch (for example, - * vTaskDelayUntil(), xQueueSend(), and so on.) must not be called while the scheduler + * vTaskDelayUntil(), xQueueSend(), etc.) must not be called while the scheduler * is suspended. * * Example usage: @@ -982,8 +1203,8 @@ void vTaskEndScheduler( void ) PRIVILEGED_FUNCTION; // Perform the operation here. There is no need to use critical // sections as we have all the microcontroller processing time. - // During this time interrupts still operate and the kernel - // tick count is maintained. + // During this time interrupts will still operate and the kernel + // tick count will be maintained. // ... @@ -1031,8 +1252,8 @@ void vTaskSuspendAll( void ) PRIVILEGED_FUNCTION; // Perform the operation here. There is no need to use critical // sections as we have all the microcontroller processing time. - // During this time interrupts still operate and the real - // time kernel tick count is maintained. + // During this time interrupts will still operate and the real + // time kernel tick count will be maintained. // ... @@ -1088,7 +1309,7 @@ TickType_t xTaskGetTickCountFromISR( void ) PRIVILEGED_FUNCTION; * * @return The number of tasks that the real time kernel is currently managing. * This includes all ready, blocked and suspended tasks. A task that - * has been deleted but not yet freed by the idle task is also + * has been deleted but not yet freed by the idle task will also be * included in the count. * * \defgroup uxTaskGetNumberOfTasks uxTaskGetNumberOfTasks @@ -1098,17 +1319,32 @@ UBaseType_t uxTaskGetNumberOfTasks( void ) PRIVILEGED_FUNCTION; /** * task. h - * <PRE>char *pcTaskGetTaskName( TaskHandle_t xTaskToQuery );</PRE> + * <PRE>char *pcTaskGetName( TaskHandle_t xTaskToQuery );</PRE> * * @return The text (human readable) name of the task referenced by the handle * xTaskToQuery. A task can query its own name by either passing in its own - * handle, or by setting xTaskToQuery to NULL. INCLUDE_pcTaskGetTaskName must be - * set to 1 in FreeRTOSConfig.h for pcTaskGetTaskName() to be available. + * handle, or by setting xTaskToQuery to NULL. * - * \defgroup pcTaskGetTaskName pcTaskGetTaskName + * \defgroup pcTaskGetName pcTaskGetName * \ingroup TaskUtils */ -char *pcTaskGetTaskName( TaskHandle_t xTaskToQuery ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ +char *pcTaskGetName( TaskHandle_t xTaskToQuery ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ + +/** + * task. h + * <PRE>TaskHandle_t xTaskGetHandle( const char *pcNameToQuery );</PRE> + * + * NOTE: This function takes a relatively long time to complete and should be + * used sparingly. + * + * @return The handle of the task that has the human readable name pcNameToQuery. + * NULL is returned if no matching name is found. INCLUDE_xTaskGetHandle + * must be set to 1 in FreeRTOSConfig.h for pcTaskGetHandle() to be available. + * + * \defgroup pcTaskGetHandle pcTaskGetHandle + * \ingroup TaskUtils + */ +TaskHandle_t xTaskGetHandle( const char *pcNameToQuery ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ /** * task.h @@ -1132,8 +1368,8 @@ char *pcTaskGetTaskName( TaskHandle_t xTaskToQuery ) PRIVILEGED_FUNCTION; /*lint UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; /* When using trace macros it is sometimes necessary to include task.h before -FreeRTOS.h. When this is done TaskHookFunction_t has not yet have been defined, -so the following two prototypes cause a compilation error. This can be +FreeRTOS.h. When this is done TaskHookFunction_t will not yet have been defined, +so the following two prototypes will cause a compilation error. This can be fixed by simply guarding against the inclusion of these two prototypes unless they are explicitly required by the configUSE_APPLICATION_TASK_TAG configuration constant. */ @@ -1224,7 +1460,7 @@ TaskHandle_t xTaskGetIdleTaskHandle( void ) PRIVILEGED_FUNCTION; * * @return The number of TaskStatus_t structures that were populated by * uxTaskGetSystemState(). This should equal the number returned by the - * uxTaskGetNumberOfTasks() API function, but is zero if the value passed + * uxTaskGetNumberOfTasks() API function, but will be zero if the value passed * in the uxArraySize parameter was too small. * * Example usage: @@ -1265,7 +1501,7 @@ TaskHandle_t xTaskGetIdleTaskHandle( void ) PRIVILEGED_FUNCTION; for( x = 0; x < uxArraySize; x++ ) { // What percentage of the total run time has the task used? - // This is always rounded down to the nearest integer. + // This will always be rounded down to the nearest integer. // ulTotalRunTimeDiv100 has already been divided by 100. ulStatsAsPercentage = pxTaskStatusArray[ x ].ulRunTimeCounter / ulTotalRunTime; @@ -1300,7 +1536,7 @@ UBaseType_t uxTaskGetSystemState( TaskStatus_t * const pxTaskStatusArray, const * both be defined as 1 for this function to be available. See the * configuration section of the FreeRTOS.org website for more information. * - * NOTE 1: This function disables interrupts for its duration. It is + * NOTE 1: This function will disable interrupts for its duration. It is * not intended for normal application runtime use but as a debug aid. * * Lists all the current tasks, along with their current state and stack @@ -1330,7 +1566,7 @@ UBaseType_t uxTaskGetSystemState( TaskStatus_t * const pxTaskStatusArray, const * call to vTaskList(). * * @param pcWriteBuffer A buffer into which the above mentioned details - * are written, in ASCII form. This buffer is assumed to be large + * will be written, in ASCII form. This buffer is assumed to be large * enough to contain the generated report. Approximately 40 bytes per * task should be sufficient. * @@ -1351,10 +1587,10 @@ void vTaskList( char * pcWriteBuffer ) PRIVILEGED_FUNCTION; /*lint !e971 Unquali * value respectively. The counter should be at least 10 times the frequency of * the tick count. * - * NOTE 1: This function disables interrupts for its duration. It is + * NOTE 1: This function will disable interrupts for its duration. It is * not intended for normal application runtime use but as a debug aid. * - * Setting configGENERATE_RUN_TIME_STATS to 1 results in a total + * Setting configGENERATE_RUN_TIME_STATS to 1 will result in a total * accumulated execution time being stored for each task. The resolution * of the accumulated time value depends on the frequency of the timer * configured by the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() macro. @@ -1383,7 +1619,7 @@ void vTaskList( char * pcWriteBuffer ) PRIVILEGED_FUNCTION; /*lint !e971 Unquali * to get access to raw stats data, rather than indirectly through a call to * vTaskGetRunTimeStats(). * - * @param pcWriteBuffer A buffer into which the execution times are + * @param pcWriteBuffer A buffer into which the execution times will be * written, in ASCII form. This buffer is assumed to be large enough to * contain the generated report. Approximately 40 bytes per task should * be sufficient. @@ -1413,10 +1649,10 @@ void vTaskGetRunTimeStats( char *pcWriteBuffer ) PRIVILEGED_FUNCTION; /*lint !e9 * task notifications can be used to send data to a task, or be used as light * weight and fast binary or counting semaphores. * - * A notification sent to a task remains pending until it is cleared by the + * A notification sent to a task will remain pending until it is cleared by the * task calling xTaskNotifyWait() or ulTaskNotifyTake(). If the task was * already in the Blocked state to wait for a notification when the notification - * arrives then the task is automatically removed from the Blocked state + * arrives then the task will automatically be removed from the Blocked state * (unblocked) and the notification cleared. * * A task can use xTaskNotifyWait() to [optionally] block to wait for a @@ -1453,8 +1689,8 @@ void vTaskGetRunTimeStats( char *pcWriteBuffer ) PRIVILEGED_FUNCTION; /*lint !e9 * * eSetValueWithoutOverwrite - * If the task being notified did not already have a notification pending then - * the task's notification value is set to ulValue and xTaskNotify() - * returns pdPASS. If the task being notified already had a notification + * the task's notification value is set to ulValue and xTaskNotify() will + * return pdPASS. If the task being notified already had a notification * pending then no action is performed and pdFAIL is returned. * * eNoAction - @@ -1499,10 +1735,10 @@ BaseType_t xTaskGenericNotify( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNo * task notifications can be used to send data to a task, or be used as light * weight and fast binary or counting semaphores. * - * A notification sent to a task remains pending until it is cleared by the + * A notification sent to a task will remain pending until it is cleared by the * task calling xTaskNotifyWait() or ulTaskNotifyTake(). If the task was * already in the Blocked state to wait for a notification when the notification - * arrives then the task is automatically removed from the Blocked state + * arrives then the task will automatically be removed from the Blocked state * (unblocked) and the notification cleared. * * A task can use xTaskNotifyWait() to [optionally] block to wait for a @@ -1539,8 +1775,8 @@ BaseType_t xTaskGenericNotify( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNo * * eSetValueWithoutOverwrite - * If the task being notified did not already have a notification pending then - * the task's notification value is set to ulValue and xTaskNotify() - * returns pdPASS. If the task being notified already had a notification + * the task's notification value is set to ulValue and xTaskNotify() will + * return pdPASS. If the task being notified already had a notification * pending then no action is performed and pdFAIL is returned. * * eNoAction - @@ -1548,7 +1784,7 @@ BaseType_t xTaskGenericNotify( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNo * updated. ulValue is not used and xTaskNotify() always returns pdPASS in * this case. * - * @param pxHigherPriorityTaskWoken xTaskNotifyFromISR() sets + * @param pxHigherPriorityTaskWoken xTaskNotifyFromISR() will set * *pxHigherPriorityTaskWoken to pdTRUE if sending the notification caused the * task to which the notification was sent to leave the Blocked state, and the * unblocked task has a priority higher than the currently running task. If @@ -1587,10 +1823,10 @@ BaseType_t xTaskGenericNotifyFromISR( TaskHandle_t xTaskToNotify, uint32_t ulVal * task notifications can be used to send data to a task, or be used as light * weight and fast binary or counting semaphores. * - * A notification sent to a task remains pending until it is cleared by the + * A notification sent to a task will remain pending until it is cleared by the * task calling xTaskNotifyWait() or ulTaskNotifyTake(). If the task was * already in the Blocked state to wait for a notification when the notification - * arrives then the task is automatically removed from the Blocked state + * arrives then the task will automatically be removed from the Blocked state * (unblocked) and the notification cleared. * * A task can use xTaskNotifyWait() to [optionally] block to wait for a @@ -1601,34 +1837,34 @@ BaseType_t xTaskGenericNotifyFromISR( TaskHandle_t xTaskToNotify, uint32_t ulVal * See http://www.FreeRTOS.org/RTOS-task-notifications.html for details. * * @param ulBitsToClearOnEntry Bits that are set in ulBitsToClearOnEntry value - * is cleared in the calling task's notification value before the task + * will be cleared in the calling task's notification value before the task * checks to see if any notifications are pending, and optionally blocks if no * notifications are pending. Setting ulBitsToClearOnEntry to ULONG_MAX (if - * limits.h is included) or 0xffffffffUL (if limits.h is not included) has + * limits.h is included) or 0xffffffffUL (if limits.h is not included) will have * the effect of resetting the task's notification value to 0. Setting - * ulBitsToClearOnEntry to 0 leaves the task's notification value unchanged. + * ulBitsToClearOnEntry to 0 will leave the task's notification value unchanged. * * @param ulBitsToClearOnExit If a notification is pending or received before * the calling task exits the xTaskNotifyWait() function then the task's * notification value (see the xTaskNotify() API function) is passed out using * the pulNotificationValue parameter. Then any bits that are set in - * ulBitsToClearOnExit are cleared in the task's notification value (note + * ulBitsToClearOnExit will be cleared in the task's notification value (note * *pulNotificationValue is set before any bits are cleared). Setting * ulBitsToClearOnExit to ULONG_MAX (if limits.h is included) or 0xffffffffUL - * (if limits.h is not included) has the effect of resetting the task's + * (if limits.h is not included) will have the effect of resetting the task's * notification value to 0 before the function exits. Setting - * ulBitsToClearOnExit to 0 leaves the task's notification value unchanged + * ulBitsToClearOnExit to 0 will leave the task's notification value unchanged * when the function exits (in which case the value passed out in - * pulNotificationValue matches the task's notification value). + * pulNotificationValue will match the task's notification value). * * @param pulNotificationValue Used to pass the task's notification value out - * of the function. Note the value passed out is not effected by the + * of the function. Note the value passed out will not be effected by the * clearing of any bits caused by ulBitsToClearOnExit being non-zero. * * @param xTicksToWait The maximum amount of time that the task should wait in * the Blocked state for a notification to be received, should a notification * not already be pending when xTaskNotifyWait() was called. The task - * does not consume any processing time while it is in the Blocked state. This + * will not consume any processing time while it is in the Blocked state. This * is specified in kernel ticks, the macro pdMS_TO_TICSK( value_in_ms ) can be * used to convert a time specified in milliseconds to a time specified in * ticks. @@ -1729,7 +1965,7 @@ BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClea * task, and the handle of the currently running task can be obtained by calling * xTaskGetCurrentTaskHandle(). * - * @param pxHigherPriorityTaskWoken vTaskNotifyGiveFromISR() sets + * @param pxHigherPriorityTaskWoken vTaskNotifyGiveFromISR() will set * *pxHigherPriorityTaskWoken to pdTRUE if sending the notification caused the * task to which the notification was sent to leave the Blocked state, and the * unblocked task has a priority higher than the currently running task. If @@ -1783,8 +2019,8 @@ void vTaskNotifyGiveFromISR( TaskHandle_t xTaskToNotify, BaseType_t *pxHigherPri * the task's notification value to be non-zero. The task does not consume any * CPU time while it is in the Blocked state. * - * Where as xTaskNotifyWait() returns when a notification is pending, - * ulTaskNotifyTake() returns when the task's notification value is + * Where as xTaskNotifyWait() will return when a notification is pending, + * ulTaskNotifyTake() will return when the task's notification value is * not zero. * * See http://www.FreeRTOS.org/RTOS-task-notifications.html for details. @@ -1799,7 +2035,7 @@ void vTaskNotifyGiveFromISR( TaskHandle_t xTaskToNotify, BaseType_t *pxHigherPri * @param xTicksToWait The maximum amount of time that the task should wait in * the Blocked state for the task's notification value to be greater than zero, * should the count not already be greater than zero when - * ulTaskNotifyTake() was called. The task does not consume any processing + * ulTaskNotifyTake() was called. The task will not consume any processing * time while it is in the Blocked state. This is specified in kernel ticks, * the macro pdMS_TO_TICSK( value_in_ms ) can be used to convert a time * specified in milliseconds to a time specified in ticks. @@ -1857,7 +2093,7 @@ BaseType_t xTaskIncrementTick( void ) PRIVILEGED_FUNCTION; * * Removes the calling task from the ready list and places it both * on the list of tasks waiting for a particular event, and the - * list of delayed tasks. The task is removed from both lists + * list of delayed tasks. The task will be removed from both lists * and replaced on the ready list should either the event occur (and * there be no higher priority tasks waiting on the same event) or * the delay period expires. @@ -1894,7 +2130,7 @@ void vTaskPlaceOnUnorderedEventList( List_t * pxEventList, const TickType_t xIte * indefinitely, whereas vTaskPlaceOnEventList() does. * */ -void vTaskPlaceOnEventListRestricted( List_t * const pxEventList, const TickType_t xTicksToWait, const BaseType_t xWaitIndefinitely ) PRIVILEGED_FUNCTION; +void vTaskPlaceOnEventListRestricted( List_t * const pxEventList, TickType_t xTicksToWait, const BaseType_t xWaitIndefinitely ) PRIVILEGED_FUNCTION; /* * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN @@ -1905,13 +2141,13 @@ void vTaskPlaceOnEventListRestricted( List_t * const pxEventList, const TickType * Removes a task from both the specified event list and the list of blocked * tasks, and places it on a ready queue. * - * xTaskRemoveFromEventList()/xTaskRemoveFromUnorderedEventList() is called + * xTaskRemoveFromEventList()/xTaskRemoveFromUnorderedEventList() will be called * if either an event occurs to unblock a task, or the block timeout period * expires. * * xTaskRemoveFromEventList() is used when the event list is in task priority - * order. It removes the list item from the head of the event list as that - * has the highest priority owning task of all the tasks on the event list. + * order. It removes the list item from the head of the event list as that will + * have the highest priority owning task of all the tasks on the event list. * xTaskRemoveFromUnorderedEventList() is used when the event list is not * ordered and the event list items hold something other than the owning tasks * priority. In this case the event list item value is updated to the value @@ -1931,7 +2167,11 @@ BaseType_t xTaskRemoveFromUnorderedEventList( ListItem_t * pxEventListItem, cons * Sets the pointer to the current TCB to the TCB of the highest priority task * that is ready to run. */ +#if defined(__GNUC__) +void vTaskSwitchContext( void ) PRIVILEGED_FUNCTION __attribute__((used)); +#else void vTaskSwitchContext( void ) PRIVILEGED_FUNCTION; +#endif /* * THESE FUNCTIONS MUST NOT BE USED FROM APPLICATION CODE. THEY ARE USED BY @@ -1980,12 +2220,6 @@ void vTaskPriorityInherit( TaskHandle_t const pxMutexHolder ) PRIVILEGED_FUNCTIO BaseType_t xTaskPriorityDisinherit( TaskHandle_t const pxMutexHolder ) PRIVILEGED_FUNCTION; /* - * Generic version of the task creation function which is in turn called by the - * xTaskCreate() and xTaskCreateRestricted() macros. - */ -BaseType_t xTaskGenericCreate( TaskFunction_t pxTaskCode, const char * const pcName, const uint16_t usStackDepth, void * const pvParameters, UBaseType_t uxPriority, TaskHandle_t * const pxCreatedTask, StackType_t * const puxStackBuffer, const MemoryRegion_t * const xRegions ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ - -/* * Get the uxTCBNumber assigned to the task referenced by the xTask parameter. */ UBaseType_t uxTaskGetTaskNumber( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; @@ -1999,7 +2233,7 @@ void vTaskSetTaskNumber( TaskHandle_t xTask, const UBaseType_t uxHandle ) PRIVIL /* * Only available when configUSE_TICKLESS_IDLE is set to 1. * If tickless mode is being used, or a low power mode is implemented, then - * the tick interrupt does not execute during idle periods. When this is the + * the tick interrupt will not execute during idle periods. When this is the * case, the tick count value maintained by the scheduler needs to be kept up * to date with the actual execution time by being skipped forward by a time * equal to the idle period. |