len0rd/FreeRTOS-Kernel
1
0
Fork 0
mirror of https://github.com/FreeRTOS/FreeRTOS-Kernel.git synced 2025-07-04 03:17:16 -04:00
Code Issues Packages Projects Releases Wiki Activity
FreeRTOS-Kernel/include/task.h

2200 lines
88 KiB
C
Raw Blame History

/*
* FreeRTOS Kernel <DEVELOPMENT BRANCH>
* Copyright (C) 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
*
* SPDX-License-Identifier: MIT
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of
* this software and associated documentation files (the "Software"), to deal in
* the Software without restriction, including without limitation the rights to
* use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
* the Software, and to permit persons to whom the Software is furnished to do so,
* subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
* FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
* COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
* IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*
* https://www.FreeRTOS.org
* https://github.com/FreeRTOS
*
*/
#ifndef INC_TASK_H
#define INC_TASK_H
#ifndef INC_FREERTOS_H
#error "include FreeRTOS.h must appear in source files before include task.h"
#endif
#include "list.h"
/* *INDENT-OFF* */
#ifdef __cplusplus
extern "C" {
#endif
/* *INDENT-ON* */
/*-----------------------------------------------------------
* MACROS AND DEFINITIONS
*----------------------------------------------------------*/
/*
* If tskKERNEL_VERSION_NUMBER ends with + it represents the version in development
* after the numbered release.
*
* The tskKERNEL_VERSION_MAJOR, tskKERNEL_VERSION_MINOR, tskKERNEL_VERSION_BUILD
* values will reflect the last released version number.
*/
#define tskKERNEL_VERSION_NUMBER "V11.1.0+"
#define tskKERNEL_VERSION_MAJOR 11
#define tskKERNEL_VERSION_MINOR 1
#define tskKERNEL_VERSION_BUILD 0
/* MPU region parameters passed in ulParameters
* of MemoryRegion_t struct. */
#define tskMPU_REGION_READ_ONLY ( 1U << 0U )
#define tskMPU_REGION_READ_WRITE ( 1U << 1U )
#define tskMPU_REGION_EXECUTE_NEVER ( 1U << 2U )
#define tskMPU_REGION_NORMAL_MEMORY ( 1U << 3U )
#define tskMPU_REGION_DEVICE_MEMORY ( 1U << 4U )
#if defined( portARMV8M_MINOR_VERSION ) && ( portARMV8M_MINOR_VERSION >= 1 )
#define tskMPU_REGION_PRIVILEGED_EXECUTE_NEVER ( 1U << 5U )
#endif /* portARMV8M_MINOR_VERSION >= 1 */
/* MPU region permissions stored in MPU settings to
* authorize access requests. */
#define tskMPU_READ_PERMISSION ( 1U << 0U )
#define tskMPU_WRITE_PERMISSION ( 1U << 1U )
/* The direct to task notification feature used to have only a single notification
* per task. Now there is an array of notifications per task that is dimensioned by
* configTASK_NOTIFICATION_ARRAY_ENTRIES. For backward compatibility, any use of the
* original direct to task notification defaults to using the first index in the
* array. */
#define tskDEFAULT_INDEX_TO_NOTIFY ( 0 )
/**
* task. h
*
* Type by which tasks are referenced. For example, a call to xTaskCreate
* returns (via a pointer parameter) an TaskHandle_t variable that can then
* be used as a parameter to vTaskDelete to delete the task.
*
* \defgroup TaskHandle_t TaskHandle_t
* \ingroup Tasks
*/
struct tskTaskControlBlock; /* The old naming convention is used to prevent breaking kernel aware debuggers. */
typedef struct tskTaskControlBlock * TaskHandle_t;
typedef const struct tskTaskControlBlock * ConstTaskHandle_t;
/*
* Defines the prototype to which the application task hook function must
* conform.
*/
typedef BaseType_t (* TaskHookFunction_t)( void * arg );
/* Task states returned by eTaskGetState. */
typedef enum
{
eRunning = 0, /* A task is querying the state of itself, so must be running. */
eReady, /* The task being queried is in a ready 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. */
eInvalid /* Used as an 'invalid state' value. */
} eTaskState;
/* Actions that can be performed when vTaskNotify() is called. */
typedef enum
{
eNoAction = 0, /* Notify the task without updating its notify value. */
eSetBits, /* Set bits in the task's notification value. */
eIncrement, /* Increment the task's notification value. */
eSetValueWithOverwrite, /* Set the task's notification value to a specific value even if the previous value has not yet been read by the task. */
eSetValueWithoutOverwrite /* Set the task's notification value if the previous value has been read by the task. */
} eNotifyAction;
/*
* Used internally only.
*/
typedef struct xTIME_OUT
{
BaseType_t xOverflowCount;
TickType_t xTimeOnEntering;
} TimeOut_t;
/*
* Defines the memory ranges allocated to the task when an MPU is used.
*/
typedef struct xMEMORY_REGION
{
void * pvBaseAddress;
uint32_t ulLengthInBytes;
uint32_t ulParameters;
} MemoryRegion_t;
/*
* Parameters required to create an MPU protected task.
*/
typedef struct xTASK_PARAMETERS
{
TaskFunction_t pvTaskCode;
const char * pcName;
configSTACK_DEPTH_TYPE usStackDepth;
void * pvParameters;
UBaseType_t uxPriority;
StackType_t * puxStackBuffer;
MemoryRegion_t xRegions[ portNUM_CONFIGURABLE_REGIONS ];
#if ( ( portUSING_MPU_WRAPPERS == 1 ) && ( configSUPPORT_STATIC_ALLOCATION == 1 ) )
StaticTask_t * const pxTaskBuffer;
#endif
} TaskParameters_t;
/* Used with the uxTaskGetSystemState() function to return the state of each task
* 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 will be invalid if the task was deleted since the structure was populated! */
UBaseType_t xTaskNumber; /* A number unique to the task. Note that this is not the task number that may be modified using vTaskSetTaskNumber() and uxTaskGetTaskNumber(), but a separate TCB-specific and unique identifier automatically assigned on task generation. */
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 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. */
configRUN_TIME_COUNTER_TYPE ulRunTimeCounter; /* The total run time allocated to the task so far, as defined by the run time stats clock. See https://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. */
#if ( ( portSTACK_GROWTH > 0 ) || ( configRECORD_STACK_HIGH_ADDRESS == 1 ) )
StackType_t * pxTopOfStack; /* Points to the top address of the task's stack area. */
StackType_t * pxEndOfStack; /* Points to the end address of the task's stack area. */
#endif
configSTACK_DEPTH_TYPE 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. */
#if ( ( configUSE_CORE_AFFINITY == 1 ) && ( configNUMBER_OF_CORES > 1 ) )
UBaseType_t uxCoreAffinityMask; /* The core affinity mask for the task */
#endif
} TaskStatus_t;
/* Possible return values for eTaskConfirmSleepModeStatus(). */
typedef enum
{
eAbortSleep = 0, /* A task has been made ready or a context switch pended since portSUPPRESS_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. */
#if ( INCLUDE_vTaskSuspend == 1 )
,
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. */
#endif /* INCLUDE_vTaskSuspend */
} eSleepModeStatus;
/**
* Defines the priority used by the idle task. This must not be modified.
*
* \ingroup TaskUtils
*/
#define tskIDLE_PRIORITY ( ( UBaseType_t ) 0U )
/**
* Defines affinity to all available cores.
*
* \ingroup TaskUtils
*/
#define tskNO_AFFINITY ( ( UBaseType_t ) -1 )
/**
* task. h
*
* Macro for forcing a context switch.
*
* \defgroup taskYIELD taskYIELD
* \ingroup SchedulerControl
*/
#define taskYIELD() portYIELD()
/**
* task. h
*
* Macro to mark the start of a critical code region. Preemptive context
* switches cannot occur when in a critical region.
*
* NOTE: This may alter the stack (depending on the portable implementation)
* so must be used with care!
*
* \defgroup taskENTER_CRITICAL taskENTER_CRITICAL
* \ingroup SchedulerControl
*/
#define taskENTER_CRITICAL() portENTER_CRITICAL()
#if ( configNUMBER_OF_CORES == 1 )
#define taskENTER_CRITICAL_FROM_ISR() portSET_INTERRUPT_MASK_FROM_ISR()
#else
#define taskENTER_CRITICAL_FROM_ISR() portENTER_CRITICAL_FROM_ISR()
#endif
/**
* task. h
*
* Macro to mark the end of a critical code region. Preemptive context
* switches cannot occur when in a critical region.
*
* NOTE: This may alter the stack (depending on the portable implementation)
* so must be used with care!
*
* \defgroup taskEXIT_CRITICAL taskEXIT_CRITICAL
* \ingroup SchedulerControl
*/
#define taskEXIT_CRITICAL() portEXIT_CRITICAL()
#if ( configNUMBER_OF_CORES == 1 )
#define taskEXIT_CRITICAL_FROM_ISR( x ) portCLEAR_INTERRUPT_MASK_FROM_ISR( x )
#else
#define taskEXIT_CRITICAL_FROM_ISR( x ) portEXIT_CRITICAL_FROM_ISR( x )
#endif
/**
* task. h
*
* Macro to disable all maskable interrupts.
*
* \defgroup taskDISABLE_INTERRUPTS taskDISABLE_INTERRUPTS
* \ingroup SchedulerControl
*/
#define taskDISABLE_INTERRUPTS() portDISABLE_INTERRUPTS()
/**
* task. h
*
* Macro to enable microcontroller interrupts.
*
* \defgroup taskENABLE_INTERRUPTS taskENABLE_INTERRUPTS
* \ingroup SchedulerControl
*/
#define taskENABLE_INTERRUPTS() portENABLE_INTERRUPTS()
/* Definitions returned by xTaskGetSchedulerState(). taskSCHEDULER_SUSPENDED is
* 0 to generate more optimal code when configASSERT() is defined as the constant
* is used in assert() statements. */
#define taskSCHEDULER_SUSPENDED ( ( BaseType_t ) 0 )
#define taskSCHEDULER_NOT_STARTED ( ( BaseType_t ) 1 )
#define taskSCHEDULER_RUNNING ( ( BaseType_t ) 2 )
/* Checks if core ID is valid. */
#define taskVALID_CORE_ID( xCoreID ) ( ( ( ( ( BaseType_t ) 0 <= ( xCoreID ) ) && ( ( xCoreID ) < ( BaseType_t ) configNUMBER_OF_CORES ) ) ) ? ( pdTRUE ) : ( pdFALSE ) )
/*-----------------------------------------------------------
* TASK CREATION API
*----------------------------------------------------------*/
/**
* task. h
* @code{c}
* BaseType_t xTaskCreate(
* TaskFunction_t pxTaskCode,
* const char * const pcName,
* const configSTACK_DEPTH_TYPE uxStackDepth,
* void *pvParameters,
* UBaseType_t uxPriority,
* TaskHandle_t *pxCreatedTask
* );
* @endcode
*
* 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
* https://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
* xTaskCreateRestricted().
*
* @param pxTaskCode 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. Max length defined by configMAX_TASK_NAME_LEN - default
* is 16.
*
* @param uxStackDepth 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 uxStackDepth is defined as 100, 200 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 should run. Systems that
* include MPU support can optionally create tasks in a privileged (system)
* mode by setting bit portPRIVILEGE_BIT of the priority parameter. For
* example, to create a privileged task at priority 2 the uxPriority parameter
* should be set to ( 2 | portPRIVILEGE_BIT ).
*
* @param pxCreatedTask Used to pass back a handle by which the created task
* can be referenced.
*
* @return pdPASS if the task was successfully created and added to a ready
* list, otherwise an error code defined in the file projdefs.h
*
* Example usage:
* @code{c}
* // Task to be created.
* void vTaskCode( void * pvParameters )
* {
* for( ;; )
* {
* // Task code goes here.
* }
* }
*
* // Function that creates a task.
* void vOtherFunction( void )
* {
* static uint8_t ucParameterToPass;
* TaskHandle_t xHandle = NULL;
*
* // Create the task, storing the handle. Note that the passed parameter ucParameterToPass
* // must exist for the lifetime of the task, so in this case is declared static. If it was just an
* // an automatic stack variable it might no longer exist, or at least have been corrupted, by the time
* // the new task attempts to access it.
* xTaskCreate( vTaskCode, "NAME", STACK_SIZE, &ucParameterToPass, tskIDLE_PRIORITY, &xHandle );
* configASSERT( xHandle );
*
* // Use the handle to delete the task.
* if( xHandle != NULL )
* {
* vTaskDelete( xHandle );
* }
* }
* @endcode
* \defgroup xTaskCreate xTaskCreate
* \ingroup Tasks
*/
#if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
BaseType_t xTaskCreate( TaskFunction_t pxTaskCode,
const char * const pcName,
const configSTACK_DEPTH_TYPE uxStackDepth,
void * const pvParameters,
UBaseType_t uxPriority,
TaskHandle_t * const pxCreatedTask ) PRIVILEGED_FUNCTION;
#endif
#if ( ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) && ( configNUMBER_OF_CORES > 1 ) && ( configUSE_CORE_AFFINITY == 1 ) )
BaseType_t xTaskCreateAffinitySet( TaskFunction_t pxTaskCode,
const char * const pcName,
const configSTACK_DEPTH_TYPE uxStackDepth,
void * const pvParameters,
UBaseType_t uxPriority,
UBaseType_t uxCoreAffinityMask,
TaskHandle_t * const pxCreatedTask ) PRIVILEGED_FUNCTION;
#endif
/**
* task. h
* @code{c}
* TaskHandle_t xTaskCreateStatic( TaskFunction_t pxTaskCode,
* const char * const pcName,
* const configSTACK_DEPTH_TYPE uxStackDepth,
* void *pvParameters,
* UBaseType_t uxPriority,
* StackType_t *puxStackBuffer,
* StaticTask_t *pxTaskBuffer );
* @endcode
*
* 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
* https://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 pxTaskCode 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 uxStackDepth 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 uxStackDepth 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 puxStackBuffer Must point to a StackType_t array that has at least
* uxStackDepth 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 puxStackBuffer nor pxTaskBuffer are NULL, then the task
* will be created and a handle to the created task is returned. If either
* puxStackBuffer or pxTaskBuffer are NULL then the task will not be created and
* NULL is returned.
*
* Example usage:
* @code{c}
*
* // Dimensions of 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 == 1U );
*
* 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 );
* }
* @endcode
* \defgroup xTaskCreateStatic xTaskCreateStatic
* \ingroup Tasks
*/
#if ( configSUPPORT_STATIC_ALLOCATION == 1 )
TaskHandle_t xTaskCreateStatic
( TaskFunction_t pxTaskCode,
const char * const pcName,
const configSTACK_DEPTH_TYPE uxStackDepth,
void * const pvParameters,
UBaseType_t uxPriority,
StackType_t * const puxStackBuffer,
StaticTask_t * const pxTaskBuffer ) PRIVILEGED_FUNCTION;
#endif /* configSUPPORT_STATIC_ALLOCATION */
#if ( ( configSUPPORT_STATIC_ALLOCATION == 1 ) && ( configNUMBER_OF_CORES > 1 ) && ( configUSE_CORE_AFFINITY == 1 ) )
TaskHandle_t xTaskCreateStaticAffinitySet( TaskFunction_t pxTaskCode,
const char * const pcName,
const configSTACK_DEPTH_TYPE uxStackDepth,
void * const pvParameters,
UBaseType_t uxPriority,
StackType_t * const puxStackBuffer,
StaticTask_t * const pxTaskBuffer,
UBaseType_t uxCoreAffinityMask ) PRIVILEGED_FUNCTION;
#endif
/**
* task. h
* @code{c}
* BaseType_t xTaskCreateRestricted( TaskParameters_t *pxTaskDefinition, TaskHandle_t *pxCreatedTask );
* @endcode
*
* Only available when configSUPPORT_DYNAMIC_ALLOCATION is set to 1.
*
* xTaskCreateRestricted() should only be used in systems that include an MPU
* implementation.
*
* Create a new task and add it to the list of tasks that are ready to run.
* The function parameters define the memory regions and associated access
* permissions allocated to the task.
*
* See xTaskCreateRestrictedStatic() for a version that does not use any
* dynamic memory allocation.
*
* @param pxTaskDefinition Pointer to a structure that contains a member
* for each of the normal xTaskCreate() parameters (see the xTaskCreate() API
* documentation) plus an optional stack buffer and the memory region
* definitions.
*
* @param pxCreatedTask Used to pass back a handle by which the created task
* can be referenced.
*
* @return pdPASS if the task was successfully created and added to a ready
* list, otherwise an error code defined in the file projdefs.h
*
* Example usage:
* @code{c}
* // Create an TaskParameters_t structure that defines the task to be created.
* static const TaskParameters_t xCheckTaskParameters =
* {
* vATask, // pvTaskCode - the function that implements the task.
* "ATask", // pcName - just a text name for the task to assist debugging.
* 100, // uxStackDepth - the stack size DEFINED IN WORDS.
* NULL, // pvParameters - passed into the task function as the function parameters.
* ( 1U | portPRIVILEGE_BIT ),// uxPriority - task priority, set the portPRIVILEGE_BIT if the task should run in a privileged state.
* cStackBuffer,// puxStackBuffer - the buffer to be used as the task stack.
*
* // xRegions - Allocate up to three separate memory regions for access by
* // the task, with appropriate access permissions. Different processors have
* // different memory alignment requirements - refer to the FreeRTOS documentation
* // for full information.
* {
* // Base address Length Parameters
* { cReadWriteArray, 32, portMPU_REGION_READ_WRITE },
* { cReadOnlyArray, 32, portMPU_REGION_READ_ONLY },
* { cPrivilegedOnlyAccessArray, 128, portMPU_REGION_PRIVILEGED_READ_WRITE }
* }
* };
*
* int main( void )
* {
* TaskHandle_t xHandle;
*
* // Create a task from the const structure defined above. The task handle
* // is requested (the second parameter is not NULL) but in this case just for
* // demonstration purposes as its not actually used.
* xTaskCreateRestricted( &xRegTest1Parameters, &xHandle );
*
* // Start the scheduler.
* vTaskStartScheduler();
*
* // Will only get here if there was insufficient memory to create the idle
* // and/or timer task.
* for( ;; );
* }
* @endcode
* \defgroup xTaskCreateRestricted xTaskCreateRestricted
* \ingroup Tasks
*/
#if ( portUSING_MPU_WRAPPERS == 1 )
BaseType_t xTaskCreateRestricted( const TaskParameters_t * const pxTaskDefinition,
TaskHandle_t * pxCreatedTask ) PRIVILEGED_FUNCTION;
#endif
#if ( ( portUSING_MPU_WRAPPERS == 1 ) && ( configNUMBER_OF_CORES > 1 ) && ( configUSE_CORE_AFFINITY == 1 ) )
BaseType_t xTaskCreateRestrictedAffinitySet( const TaskParameters_t * const pxTaskDefinition,
UBaseType_t uxCoreAffinityMask,
TaskHandle_t * pxCreatedTask ) PRIVILEGED_FUNCTION;
#endif
/**
* task. h
* @code{c}
* BaseType_t xTaskCreateRestrictedStatic( TaskParameters_t *pxTaskDefinition, TaskHandle_t *pxCreatedTask );
* @endcode
*
* Only available when configSUPPORT_STATIC_ALLOCATION is set to 1.
*
* xTaskCreateRestrictedStatic() should only be used in systems that include an
* MPU implementation.
*
* 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
* xTaskCreateRestricted() then the stack is provided by the application writer,
* and the memory used to hold the task's data structure is automatically
* dynamically allocated inside the xTaskCreateRestricted() function. If a task
* is created using xTaskCreateRestrictedStatic() then the application writer
* must provide the memory used to hold the task's data structures too.
* xTaskCreateRestrictedStatic() therefore allows a memory protected task to be
* created without using any dynamic memory allocation.
*
* @param pxTaskDefinition Pointer to a structure that contains a member
* for each of the normal xTaskCreate() parameters (see the xTaskCreate() API
* documentation) plus an optional stack buffer and the memory region
* definitions. If configSUPPORT_STATIC_ALLOCATION is set to 1 the structure
* contains an additional member, which is used to point to a variable of type
* StaticTask_t - which is then used to hold the task's data structure.
*
* @param pxCreatedTask Used to pass back a handle by which the created task
* can be referenced.
*
* @return pdPASS if the task was successfully created and added to a ready
* list, otherwise an error code defined in the file projdefs.h
*
* Example usage:
* @code{c}
*
* // Dimensions of 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 == 1U );
*
* 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 );
* }
* @endcode
* \defgroup xTaskCreateRestrictedStatic xTaskCreateRestrictedStatic
* \ingroup Tasks
*/
#if ( ( portUSING_MPU_WRAPPERS == 1 ) && ( configSUPPORT_STATIC_ALLOCATION == 1 ) )
BaseType_t xTaskCreateRestrictedStatic( const TaskParameters_t * const pxTaskDefinition,
TaskHandle_t * pxCreatedTask ) PRIVILEGED_FUNCTION;
#endif
/**
* task. h
* @code{c}
* BaseType_t xTaskNotify( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction );
* @endcode
*
* See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
*
* configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this
* function to be available.
*
* Sends a direct to task notification to a task, with an optional value and
* action.
*
* Each task has a private array of "notification values" (or 'notifications'),
* each of which is a 32-bit unsigned integer (uint32_t). The constant
* configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
* array, and (for backward compatibility) defaults to 1 if left undefined.
* Prior to FreeRTOS V10.4.0 there was only one notification value per task.
*
* Events can be sent to a task using an intermediary object. Examples of such
* objects are queues, semaphores, mutexes and event groups. Task notifications
* are a method of sending an event directly to a task without the need for such
* an intermediary object.
*
* A notification sent to a task can optionally perform an action, such as
* update, overwrite or increment one of the task's notification values. In
* that way task notifications can be used to send data to a task, or be used as
* light weight and fast binary or counting semaphores.
*
* A task can use xTaskNotifyWait() or ulTaskNotifyTake() to
* [optionally] block to wait for a notification to be pending. The task does
* not consume any CPU time while it is in the Blocked state.
*
* A notification sent to a task will remain pending until it is cleared by the
* task calling xTaskNotifyWait() or ulTaskNotifyTake() (or their
* un-indexed equivalents). If the task was already in the Blocked state to
* wait for a notification when the notification arrives then the task will
* automatically be removed from the Blocked state (unblocked) and the
* notification cleared.
*
* @param xTaskToNotify The handle of the task being notified. The handle to a
* task can be returned from the xTaskCreate() API function used to create the
* task, and the handle of the currently running task can be obtained by calling
* xTaskGetCurrentTaskHandle().
*
* @param ulValue Data that can be sent with the notification. How the data is
* used depends on the value of the eAction parameter.
*
* @param eAction Specifies how the notification updates the task's notification
* value, if at all. Valid values for eAction are as follows:
*
* eSetBits -
* The target notification value is bitwise ORed with ulValue.
* xTaskNotify() always returns pdPASS in this case.
*
* eIncrement -
* The target notification value is incremented. ulValue is not used and
* xTaskNotify() always returns pdPASS in this case.
*
* eSetValueWithOverwrite -
* The target notification value is set to the value of ulValue, even if the
* task being notified had not yet processed the previous notification (the
* task already had a notification pending). xTaskNotify() always returns
* pdPASS in this case.
*
* eSetValueWithoutOverwrite -
* If the task being notified did not already have a notification pending then
* the target 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 -
* The task receives a notification without the notification value at that index
* being updated. ulValue is not used and xTaskNotify() always returns pdPASS in
* this case.
*
* @return Dependent on the value of eAction. See the description of the
* eAction parameter.
*
* \defgroup xTaskNotify xTaskNotify
* \ingroup TaskNotifications
*/
#define xTaskNotify( xTaskToNotify, ulValue, eAction ) \
xTaskGenericNotify( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), NULL )
/**
* task. h
* @code{c}
* BaseType_t xTaskNotifyAndQuery( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotifyValue );
* @endcode
*
* See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
*
* xTaskNotifyAndQuery() performs the same operation as xTaskNotify() with the
* addition that it also returns the subject task's prior notification value
* (the notification value at the time the function is called rather than when
* the function returns) in the additional pulPreviousNotifyValue parameter.
*
* \defgroup xTaskNotifyAndQuery xTaskNotifyAndQuery
* \ingroup TaskNotifications
*/
#define xTaskNotifyAndQuery( xTaskToNotify, ulValue, eAction, pulPreviousNotifyValue ) \
xTaskGenericNotify( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), ( pulPreviousNotifyValue ) )
/**
* task. h
* @code{c}
* BaseType_t xTaskNotifyIndexed( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction );
* BaseType_t xTaskNotify( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction );
* @endcode
*
* See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
*
* configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these
* functions to be available.
*
* A version of xTaskNotify() that can be used from an interrupt service
* routine (ISR).
*
* Each task has a private array of "notification values" (or 'notifications'),
* each of which is a 32-bit unsigned integer (uint32_t). The constant
* configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
* array, and (for backward compatibility) defaults to 1 if left undefined.
* Prior to FreeRTOS V10.4.0 there was only one notification value per task.
*
* Events can be sent to a task using an intermediary object. Examples of such
* objects are queues, semaphores, mutexes and event groups. Task notifications
* are a method of sending an event directly to a task without the need for such
* an intermediary object.
*
* A notification sent to a task can optionally perform an action, such as
* update, overwrite or increment one of the task's notification values. In
* that way task notifications can be used to send data to a task, or be used as
* light weight and fast binary or counting semaphores.
*
* xTaskNotifyFromISR() is intended for use when task notifications
* are used as light weight and faster binary or counting semaphore equivalents.
* Actual FreeRTOS semaphores are given from an ISR using the
* xSemaphoreGiveFromISR() API function, the equivalent action that instead uses
* a task notification is xTaskNotifyFromISR().
*
* When task notifications are being used as a binary or counting semaphore
* equivalent then the task being notified should wait for the notification
* using the ulTaskNotifyTakeIndexed() API function rather than the
* xTaskNotifyWaitIndexed() API function.
*
* **NOTE** Each notification within the array operates independently - a task
* can only block on one notification within the array at a time and will not be
* unblocked by a notification sent to any other array index.
*
* Backward compatibility information:
* Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
* all task notification API functions operated on that value. Replacing the
* single notification value with an array of notification values necessitated a
* new set of API functions that could address specific notifications within the
* array. xTaskNotifyFromISR() is the original API function, and remains
* backward compatible by always operating on the notification value at index 0
* within the array. Calling xTaskNotifyFromISR() is equivalent to calling
* xTaskNotifyIndexedFromISR() with the uxIndexToNotify parameter set to 0.
*
* @param uxIndexToNotify The index within the target task's array of
* notification values to which the notification is to be sent. uxIndexToNotify
* must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyFromISR()
* does not have this parameter and always sends notifications to index 0.
*
* @param xTaskToNotify The handle of the task being notified. The handle to a
* task can be returned from the xTaskCreate() API function used to create the
* task, and the handle of the currently running task can be obtained by calling
* xTaskGetCurrentTaskHandle().
*
* @param ulValue Data that can be sent with the notification. How the data is
* used depends on the value of the eAction parameter.
*
* @param eAction Specifies how the notification updates the task's notification
* value, if at all. Valid values for eAction are as follows:
*
* eSetBits -
* The task's notification value is bitwise ORed with ulValue. xTaskNotify()
* always returns pdPASS in this case.
*
* eIncrement -
* The task's notification value is incremented. ulValue is not used and
* xTaskNotify() always returns pdPASS in this case.
*
* eSetValueWithOverwrite -
* The task's notification value is set to the value of ulValue, even if the
* task being notified had not yet processed the previous notification (the
* task already had a notification pending). xTaskNotify() always returns
* pdPASS in this case.
*
* 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() will
* return pdPASS. If the task being notified already had a notification
* pending then no action is performed and pdFAIL is returned.
*
* eNoAction -
* The task receives a notification without its notification value being
* updated. ulValue is not used and xTaskNotify() always returns pdPASS in
* this case.
*
* @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
* xTaskNotifyFromISR() sets this value to pdTRUE then a context switch
* should be requested before the interrupt is exited. How a context switch is
* requested from an ISR is dependent on the port - see the documentation page
* for the port in use.
*
* @return Dependent on the value of eAction. See the description of the
* eAction parameter.
*
* \defgroup xTaskNotifyFromISR xTaskNotifyFromISR
* \ingroup TaskNotifications
*/
#define xTaskNotifyFromISR( xTaskToNotify, ulValue, eAction, pxHigherPriorityTaskWoken ) \
xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), NULL, ( pxHigherPriorityTaskWoken ) )
#define xTaskNotifyIndexedFromISR( xTaskToNotify, uxIndexToNotify, ulValue, eAction, pxHigherPriorityTaskWoken ) \
xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( uxIndexToNotify ), ( ulValue ), ( eAction ), NULL, ( pxHigherPriorityTaskWoken ) )
/**
* task. h
* @code{c}
* BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait );
*
* BaseType_t xTaskNotifyWaitIndexed( UBaseType_t uxIndexToWaitOn, uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait );
* @endcode
*
* Waits for a direct to task notification to be pending at a given index within
* an array of direct to task notifications.
*
* See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
*
* configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this
* function to be available.
*
* Each task has a private array of "notification values" (or 'notifications'),
* each of which is a 32-bit unsigned integer (uint32_t). The constant
* configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
* array, and (for backward compatibility) defaults to 1 if left undefined.
* Prior to FreeRTOS V10.4.0 there was only one notification value per task.
*
* Events can be sent to a task using an intermediary object. Examples of such
* objects are queues, semaphores, mutexes and event groups. Task notifications
* are a method of sending an event directly to a task without the need for such
* an intermediary object.
*
* A notification sent to a task can optionally perform an action, such as
* update, overwrite or increment one of the task's notification values. In
* that way 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 will remain pending until it is cleared by the
* task calling xTaskNotifyWait() or ulTaskNotifyTake() (or their
* un-indexed equivalents). If the task was already in the Blocked state to
* wait for a notification when the notification arrives then the task will
* automatically be removed from the Blocked state (unblocked) and the
* notification cleared.
*
* **NOTE** Each notification within the array operates independently - a task
* can only block on one notification within the array at a time and will not be
* unblocked by a notification sent to any other array index.
*
* Backward compatibility information:
* Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
* all task notification API functions operated on that value. Replacing the
* single notification value with an array of notification values necessitated a
* new set of API functions that could address specific notifications within the
* array. xTaskNotifyWait() is the original API function, and remains backward
* compatible by always operating on the notification value at index 0 in the
* array. Calling xTaskNotifyWait() is equivalent to calling
* xTaskNotifyWaitIndexed() with the uxIndexToWaitOn parameter set to 0.
*
* @param uxIndexToWaitOn The index within the calling task's array of
* notification values on which the calling task will wait for a notification to
* be pending. uxIndexToWaitOn must be less than
* configTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyWait() does
* not have this parameter and always waits for notifications on index 0.
*
* @param ulBitsToClearOnEntry Bits that are set in ulBitsToClearOnEntry value
* 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 0xffffffffU (if limits.h is not included) will have
* the effect of resetting the task's notification value to 0. Setting
* 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 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) will have the effect of resetting the task's
* notification value to 0 before the function exits. Setting
* ulBitsToClearOnExit to 0 will leave the task's notification value unchanged
* when the function exits (in which case the value passed out in
* 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 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
* will not consume any processing time while it is in the Blocked state. This
* is specified in kernel ticks, the macro pdMS_TO_TICKS( value_in_ms ) can be
* used to convert a time specified in milliseconds to a time specified in
* ticks.
*
* @return If a notification was received (including notifications that were
* already pending when xTaskNotifyWait was called) then pdPASS is
* returned. Otherwise pdFAIL is returned.
*
* \defgroup xTaskNotifyWait xTaskNotifyWait
* \ingroup TaskNotifications
*/
#define xTaskNotifyWait( ulBitsToClearOnEntry, ulBitsToClearOnExit, pulNotificationValue, xTicksToWait ) \
xTaskGenericNotifyWait( tskDEFAULT_INDEX_TO_NOTIFY, ( ulBitsToClearOnEntry ), ( ulBitsToClearOnExit ), ( pulNotificationValue ), ( xTicksToWait ) )
#define xTaskNotifyWaitIndexed( uxIndexToWaitOn, ulBitsToClearOnEntry, ulBitsToClearOnExit, pulNotificationValue, xTicksToWait ) \
xTaskGenericNotifyWait( ( uxIndexToWaitOn ), ( ulBitsToClearOnEntry ), ( ulBitsToClearOnExit ), ( pulNotificationValue ), ( xTicksToWait ) )
/**
* task. h
* @code{c}
* BaseType_t xTaskNotifyGive( TaskHandle_t xTaskToNotify );
* @endcode
*
* Sends a direct to task notification to a particular index in the target
* task's notification array in a manner similar to giving a counting semaphore.
*
* See https://www.FreeRTOS.org/RTOS-task-notifications.html for more details.
*
* configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this macro
* to be available.
*
* Each task has a private array of "notification values" (or 'notifications'),
* each of which is a 32-bit unsigned integer (uint32_t). The constant
* configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
* array, and (for backward compatibility) defaults to 1 if left undefined.
* Prior to FreeRTOS V10.4.0 there was only one notification value per task.
*
* Events can be sent to a task using an intermediary object. Examples of such
* objects are queues, semaphores, mutexes and event groups. Task notifications
* are a method of sending an event directly to a task without the need for such
* an intermediary object.
*
* A notification sent to a task can optionally perform an action, such as
* update, overwrite or increment one of the task's notification values. In
* that way task notifications can be used to send data to a task, or be used as
* light weight and fast binary or counting semaphores.
*
* vTaskNotifyGive() is a helper macro intended for use when task
* notifications are used as light weight and faster binary or counting
* semaphore equivalents. Actual FreeRTOS semaphores are given using the
* xSemaphoreGive() API function, the equivalent action that instead uses a task
* notification is vTaskNotifyGive().
*
* When task notifications are being used as a binary or counting semaphore
* equivalent then the task being notified should wait for the notification
* using the ulTaskNotifyTakeIndexed() API function rather than the
* xTaskNotifyWaitIndexed() API function.
*
* **NOTE** Each notification within the array operates independently - a task
* can only block on one notification within the array at a time and will not be
* unblocked by a notification sent to any other array index.
*
* Backward compatibility information:
* Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
* all task notification API functions operated on that value. Replacing the
* single notification value with an array of notification values necessitated a
* new set of API functions that could address specific notifications within the
* array. xTaskNotifyGive() is the original API function, and remains
* backward compatible by always operating on the notification value at index 0
* within the array. Calling xTaskNotifyGive() is equivalent to calling
* xTaskNotifyGiveIndexed() with the uxIndexToNotify parameter set to 0.
*
* @param xTaskToNotify The handle of the task being notified. The handle to a
* task can be returned from the xTaskCreate() API function used to create the
* task, and the handle of the currently running task can be obtained by calling
* xTaskGetCurrentTaskHandle().
*
* @return xTaskNotifyGive() is a macro that calls xTaskNotify() with the
* eAction parameter set to eIncrement - so pdPASS is always returned.
*
* \defgroup xTaskNotifyGive xTaskNotifyGive
* \ingroup TaskNotifications
*/
#define xTaskNotifyGive( xTaskToNotify ) \
xTaskGenericNotify( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( 0 ), eIncrement, NULL )
#define xTaskNotifyGiveIndexed( xTaskToNotify, uxIndexToNotify ) \
xTaskGenericNotify( ( xTaskToNotify ), ( uxIndexToNotify ), ( 0 ), eIncrement, NULL )
/**
* task. h
* @code{c}
* void vTaskNotifyGiveIndexedFromISR( TaskHandle_t xTaskHandle, UBaseType_t uxIndexToNotify, BaseType_t *pxHigherPriorityTaskWoken );
* void vTaskNotifyGiveFromISR( TaskHandle_t xTaskHandle, BaseType_t *pxHigherPriorityTaskWoken );
* @endcode
*
* A version of xTaskNotifyGiveIndexed() that can be called from an interrupt
* service routine (ISR).
*
* See https://www.FreeRTOS.org/RTOS-task-notifications.html for more details.
*
* configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this macro
* to be available.
*
* Each task has a private array of "notification values" (or 'notifications'),
* each of which is a 32-bit unsigned integer (uint32_t). The constant
* configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
* array, and (for backward compatibility) defaults to 1 if left undefined.
* Prior to FreeRTOS V10.4.0 there was only one notification value per task.
*
* Events can be sent to a task using an intermediary object. Examples of such
* objects are queues, semaphores, mutexes and event groups. Task notifications
* are a method of sending an event directly to a task without the need for such
* an intermediary object.
*
* A notification sent to a task can optionally perform an action, such as
* update, overwrite or increment one of the task's notification values. In
* that way task notifications can be used to send data to a task, or be used as
* light weight and fast binary or counting semaphores.
*
* vTaskNotifyGiveIndexedFromISR() is intended for use when task notifications
* are used as light weight and faster binary or counting semaphore equivalents.
* Actual FreeRTOS semaphores are given from an ISR using the
* xSemaphoreGiveFromISR() API function, the equivalent action that instead uses
* a task notification is vTaskNotifyGiveIndexedFromISR().
*
* When task notifications are being used as a binary or counting semaphore
* equivalent then the task being notified should wait for the notification
* using the ulTaskNotifyTakeIndexed() API function rather than the
* xTaskNotifyWaitIndexed() API function.
*
* **NOTE** Each notification within the array operates independently - a task
* can only block on one notification within the array at a time and will not be
* unblocked by a notification sent to any other array index.
*
* Backward compatibility information:
* Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
* all task notification API functions operated on that value. Replacing the
* single notification value with an array of notification values necessitated a
* new set of API functions that could address specific notifications within the
* array. xTaskNotifyFromISR() is the original API function, and remains
* backward compatible by always operating on the notification value at index 0
* within the array. Calling xTaskNotifyGiveFromISR() is equivalent to calling
* xTaskNotifyGiveIndexedFromISR() with the uxIndexToNotify parameter set to 0.
*
* @param xTaskToNotify The handle of the task being notified. The handle to a
* task can be returned from the xTaskCreate() API function used to create the
* task, and the handle of the currently running task can be obtained by calling
* xTaskGetCurrentTaskHandle().
*
* @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
* vTaskNotifyGiveFromISR() sets this value to pdTRUE then a context switch
* should be requested before the interrupt is exited. How a context switch is
* requested from an ISR is dependent on the port - see the documentation page
* for the port in use.
*
* \defgroup vTaskNotifyGiveIndexedFromISR vTaskNotifyGiveIndexedFromISR
* \ingroup TaskNotifications
*/
void vTaskGenericNotifyGiveFromISR( TaskHandle_t xTaskToNotify,
UBaseType_t uxIndexToNotify,
BaseType_t * pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
#define vTaskNotifyGiveFromISR( xTaskToNotify, pxHigherPriorityTaskWoken ) \
vTaskGenericNotifyGiveFromISR( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( pxHigherPriorityTaskWoken ) )
#define vTaskNotifyGiveIndexedFromISR( xTaskToNotify, uxIndexToNotify, pxHigherPriorityTaskWoken ) \
vTaskGenericNotifyGiveFromISR( ( xTaskToNotify ), ( uxIndexToNotify ), ( pxHigherPriorityTaskWoken ) )
/**
* task. h
* @code{c}
* uint32_t ulTaskNotifyTakeIndexed( UBaseType_t uxIndexToWaitOn, BaseType_t xClearCountOnExit, TickType_t xTicksToWait );
*
* uint32_t ulTaskNotifyTake( BaseType_t xClearCountOnExit, TickType_t xTicksToWait );
* @endcode
*
* Waits for a direct to task notification on a particular index in the calling
* task's notification array in a manner similar to taking a counting semaphore.
*
* See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
*
* configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this
* function to be available.
*
* Each task has a private array of "notification values" (or 'notifications'),
* each of which is a 32-bit unsigned integer (uint32_t). The constant
* configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
* array, and (for backward compatibility) defaults to 1 if left undefined.
* Prior to FreeRTOS V10.4.0 there was only one notification value per task.
*
* Events can be sent to a task using an intermediary object. Examples of such
* objects are queues, semaphores, mutexes and event groups. Task notifications
* are a method of sending an event directly to a task without the need for such
* an intermediary object.
*
* A notification sent to a task can optionally perform an action, such as
* update, overwrite or increment one of the task's notification values. In
* that way task notifications can be used to send data to a task, or be used as
* light weight and fast binary or counting semaphores.
*
* ulTaskNotifyTakeIndexed() is intended for use when a task notification is
* used as a faster and lighter weight binary or counting semaphore alternative.
* Actual FreeRTOS semaphores are taken using the xSemaphoreTake() API function,
* the equivalent action that instead uses a task notification is
* ulTaskNotifyTakeIndexed().
*
* When a task is using its notification value as a binary or counting semaphore
* other tasks should send notifications to it using the xTaskNotifyGiveIndexed()
* macro, or xTaskNotifyIndex() function with the eAction parameter set to
* eIncrement.
*
* ulTaskNotifyTakeIndexed() can either clear the task's notification value at
* the array index specified by the uxIndexToWaitOn parameter to zero on exit,
* in which case the notification value acts like a binary semaphore, or
* decrement the notification value on exit, in which case the notification
* value acts like a counting semaphore.
*
* A task can use ulTaskNotifyTakeIndexed() to [optionally] block to wait for
* a notification. The task does not consume any CPU time while it is in the
* Blocked state.
*
* Where as xTaskNotifyWaitIndexed() will return when a notification is pending,
* ulTaskNotifyTakeIndexed() will return when the task's notification value is
* not zero.
*
* **NOTE** Each notification within the array operates independently - a task
* can only block on one notification within the array at a time and will not be
* unblocked by a notification sent to any other array index.
*
* Backward compatibility information:
* Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
* all task notification API functions operated on that value. Replacing the
* single notification value with an array of notification values necessitated a
* new set of API functions that could address specific notifications within the
* array. ulTaskNotifyTake() is the original API function, and remains backward
* compatible by always operating on the notification value at index 0 in the
* array. Calling ulTaskNotifyTake() is equivalent to calling
* ulTaskNotifyTakeIndexed() with the uxIndexToWaitOn parameter set to 0.
*
* @param uxIndexToWaitOn The index within the calling task's array of
* notification values on which the calling task will wait for a notification to
* be non-zero. uxIndexToWaitOn must be less than
* configTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyTake() does
* not have this parameter and always waits for notifications on index 0.
*
* @param xClearCountOnExit if xClearCountOnExit is pdFALSE then the task's
* notification value is decremented when the function exits. In this way the
* notification value acts like a counting semaphore. If xClearCountOnExit is
* not pdFALSE then the task's notification value is cleared to zero when the
* function exits. In this way the notification value acts like a binary
* semaphore.
*
* @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 will not consume any processing
* time while it is in the Blocked state. This is specified in kernel ticks,
* the macro pdMS_TO_TICKS( value_in_ms ) can be used to convert a time
* specified in milliseconds to a time specified in ticks.
*
* @return The task's notification count before it is either cleared to zero or
* decremented (see the xClearCountOnExit parameter).
*
* \defgroup ulTaskNotifyTake ulTaskNotifyTake
* \ingroup TaskNotifications
*/
uint32_t ulTaskGenericNotifyTake( UBaseType_t uxIndexToWaitOn,
BaseType_t xClearCountOnExit,
TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
#define ulTaskNotifyTake( xClearCountOnExit, xTicksToWait ) \
ulTaskGenericNotifyTake( ( tskDEFAULT_INDEX_TO_NOTIFY ), ( xClearCountOnExit ), ( xTicksToWait ) )
#define ulTaskNotifyTakeIndexed( uxIndexToWaitOn, xClearCountOnExit, xTicksToWait ) \
ulTaskGenericNotifyTake( ( uxIndexToWaitOn ), ( xClearCountOnExit ), ( xTicksToWait ) )
/**
* task. h
* @code{c}
* BaseType_t xTaskNotifyStateClear( TaskHandle_t xTask );
* @endcode
*
* See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
*
* configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this
* function to be available.
*
* Each task has a private array of "notification values" (or 'notifications'),
* each of which is a 32-bit unsigned integer (uint32_t). The constant
* configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
* array, and (for backward compatibility) defaults to 1 if left undefined.
* Prior to FreeRTOS V10.4.0 there was only one notification value per task.
*
* If a notification is sent to an index within the array of notifications then
* the notification at that index is said to be 'pending' until it is read or
* explicitly cleared by the receiving task. xTaskNotifyStateClear() is the
* function that clears a pending notification without reading the
* notification value. The notification value at the same array index is not
* altered. Set xTask to NULL to clear the notification state of the calling
* task.
*
* Backward compatibility information:
* Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
* all task notification API functions operated on that value. Replacing the
* single notification value with an array of notification values necessitated a
* new set of API functions that could address specific notifications within the
* array. xTaskNotifyStateClear() is the original API function, and remains
* backward compatible by always operating on the notification value at index 0
* within the array. Calling xTaskNotifyStateClear() is equivalent to calling
* xTaskNotifyStateClearIndexed() with the uxIndexToNotify parameter set to 0.
*
* @param xTask The handle of the RTOS task that will have a notification state
* cleared. Set xTask to NULL to clear a notification state in the calling
* task. To obtain a task's handle create the task using xTaskCreate() and
* make use of the pxCreatedTask parameter, or create the task using
* xTaskCreateStatic() and store the returned value, or use the task's name in
* a call to xTaskGetHandle().
*
* @param uxIndexToClear The index within the target task's array of
* notification values to act upon. For example, setting uxIndexToClear to 1
* will clear the state of the notification at index 1 within the array.
* uxIndexToClear must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES.
* ulTaskNotifyStateClear() does not have this parameter and always acts on the
* notification at index 0.
*
* @return pdTRUE if the task's notification state was set to
* eNotWaitingNotification, otherwise pdFALSE.
*
* \defgroup xTaskNotifyStateClear xTaskNotifyStateClear
* \ingroup TaskNotifications
*/
#define xTaskNotifyStateClear( xTask ) \
xTaskGenericNotifyStateClear( ( xTask ), ( tskDEFAULT_INDEX_TO_NOTIFY ) )
#define xTaskNotifyStateClearIndexed( xTask, uxIndexToClear ) \
xTaskGenericNotifyStateClear( ( xTask ), ( uxIndexToClear ) )
/**
* task. h
* @code{c}
* uint32_t ulTaskNotifyValueClear( TaskHandle_t xTask, uint32_t ulBitsToClear );
*
* uint32_t ulTaskNotifyValueClearIndexed( TaskHandle_t xTask, UBaseType_t uxIndexToClear, uint32_t ulBitsToClear );
* @endcode
*
* See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
*
* configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these
* functions to be available.
*
* Each task has a private array of "notification values" (or 'notifications'),
* each of which is a 32-bit unsigned integer (uint32_t). The constant
* configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
* array, and (for backward compatibility) defaults to 1 if left undefined.
* Prior to FreeRTOS V10.4.0 there was only one notification value per task.
*
* ulTaskNotifyValueClear() clears the bits specified by the
* ulBitsToClear bit mask in the notification value at array index uxIndexToClear
* of the task referenced by xTask.
*
* Backward compatibility information:
* Prior to FreeRTOS V10.4.0 each task had a single "notification value", and
* all task notification API functions operated on that value. Replacing the
* single notification value with an array of notification values necessitated a
* new set of API functions that could address specific notifications within the
* array. ulTaskNotifyValueClear() is the original API function, and remains
* backward compatible by always operating on the notification value at index 0
* within the array. Calling ulTaskNotifyValueClear() is equivalent to calling
* ulTaskNotifyValueClearIndexed() with the uxIndexToClear parameter set to 0.
*
* @param xTask The handle of the RTOS task that will have bits in one of its
* notification values cleared. Set xTask to NULL to clear bits in a
* notification value of the calling task. To obtain a task's handle create the
* task using xTaskCreate() and make use of the pxCreatedTask parameter, or
* create the task using xTaskCreateStatic() and store the returned value, or
* use the task's name in a call to xTaskGetHandle().
*
* @param uxIndexToClear The index within the target task's array of
* notification values in which to clear the bits. uxIndexToClear
* must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES.
* ulTaskNotifyValueClear() does not have this parameter and always clears bits
* in the notification value at index 0.
*
* @param ulBitsToClear Bit mask of the bits to clear in the notification value of
* xTask. Set a bit to 1 to clear the corresponding bits in the task's notification
* value. Set ulBitsToClear to 0xffffffff (UINT_MAX on 32-bit architectures) to clear
* the notification value to 0. Set ulBitsToClear to 0 to query the task's
* notification value without clearing any bits.
*
*
* @return The value of the target task's notification value before the bits
* specified by ulBitsToClear were cleared.
* \defgroup ulTaskNotifyValueClear ulTaskNotifyValueClear
* \ingroup TaskNotifications
*/
uint32_t ulTaskGenericNotifyValueClear( TaskHandle_t xTask,
UBaseType_t uxIndexToClear,
uint32_t ulBitsToClear ) PRIVILEGED_FUNCTION;
#define ulTaskNotifyValueClear( xTask, ulBitsToClear ) \
ulTaskGenericNotifyValueClear( ( xTask ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulBitsToClear ) )
#define ulTaskNotifyValueClearIndexed( xTask, uxIndexToClear, ulBitsToClear ) \
ulTaskGenericNotifyValueClear( ( xTask ), ( uxIndexToClear ), ( ulBitsToClear ) )
/**
* task.h
* @code{c}
* void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut );
* @endcode
*
* Capture the current time for future use with xTaskCheckForTimeOut().
*
* @param pxTimeOut Pointer to a timeout object into which the current time
* is to be captured. The captured time includes the tick count and the number
* of times the tick count has overflowed since the system first booted.
* \defgroup vTaskSetTimeOutState vTaskSetTimeOutState
* \ingroup TaskCtrl
*/
void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut ) PRIVILEGED_FUNCTION;
/**
* task.h
* @code{c}
* BaseType_t xTaskCheckForTimeOut( TimeOut_t * const pxTimeOut, TickType_t * const pxTicksToWait );
* @endcode
*
* Determines if pxTicksToWait ticks has passed since a time was captured
* using a call to vTaskSetTimeOutState(). The captured time includes the tick
* count and the number of times the tick count has overflowed.
*
* @param pxTimeOut The time status as captured previously using
* vTaskSetTimeOutState. If the timeout has not yet occurred, it is updated
* to reflect the current time status.
* @param pxTicksToWait The number of ticks to check for timeout i.e. if
* pxTicksToWait ticks have passed since pxTimeOut was last updated (either by
* vTaskSetTimeOutState() or xTaskCheckForTimeOut()), the timeout has occurred.
* If the timeout has not occurred, pxTicksToWait is updated to reflect the number of remaining ticks.
*
* @return If timeout has occurred, pdTRUE is returned. Otherwise pdFALSE is
* returned and pxTicksToWait is updated to reflect the number of remaining
* ticks.
*
* @see https://www.FreeRTOS.org/xTaskCheckForTimeOut.html
*
* Example Usage:
* @code{c}
* // Driver library function used to receive uxWantedBytes from an Rx buffer
* // that is filled by a UART interrupt. If there are not enough bytes in the
* // Rx buffer then the task enters the Blocked state until it is notified that
* // more data has been placed into the buffer. If there is still not enough
* // data then the task re-enters the Blocked state, and xTaskCheckForTimeOut()
* // is used to re-calculate the Block time to ensure the total amount of time
* // spent in the Blocked state does not exceed MAX_TIME_TO_WAIT. This
* // continues until either the buffer contains at least uxWantedBytes bytes,
* // or the total amount of time spent in the Blocked state reaches
* // MAX_TIME_TO_WAIT - at which point the task reads however many bytes are
* // available up to a maximum of uxWantedBytes.
*
* size_t xUART_Receive( uint8_t *pucBuffer, size_t uxWantedBytes )
* {
* size_t uxReceived = 0;
* TickType_t xTicksToWait = MAX_TIME_TO_WAIT;
* TimeOut_t xTimeOut;
*
* // Initialize xTimeOut. This records the time at which this function
* // was entered.
* vTaskSetTimeOutState( &xTimeOut );
*
* // Loop until the buffer contains the wanted number of bytes, or a
* // timeout occurs.
* while( UART_bytes_in_rx_buffer( pxUARTInstance ) < uxWantedBytes )
* {
* // The buffer didn't contain enough data so this task is going to
* // enter the Blocked state. Adjusting xTicksToWait to account for
* // any time that has been spent in the Blocked state within this
* // function so far to ensure the total amount of time spent in the
* // Blocked state does not exceed MAX_TIME_TO_WAIT.
* if( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait ) != pdFALSE )
* {
* //Timed out before the wanted number of bytes were available,
* // exit the loop.
* break;
* }
*
* // Wait for a maximum of xTicksToWait ticks to be notified that the
* // receive interrupt has placed more data into the buffer.
* ulTaskNotifyTake( pdTRUE, xTicksToWait );
* }
*
* // Attempt to read uxWantedBytes from the receive buffer into pucBuffer.
* // The actual number of bytes read (which might be less than
* // uxWantedBytes) is returned.
* uxReceived = UART_read_from_receive_buffer( pxUARTInstance,
* pucBuffer,
* uxWantedBytes );
*
* return uxReceived;
* }
* @endcode
* \defgroup xTaskCheckForTimeOut xTaskCheckForTimeOut
* \ingroup TaskCtrl
*/
BaseType_t xTaskCheckForTimeOut( TimeOut_t * const pxTimeOut,
TickType_t * const pxTicksToWait ) PRIVILEGED_FUNCTION;
/**
* task.h
* @code{c}
* BaseType_t xTaskCatchUpTicks( TickType_t xTicksToCatchUp );
* @endcode
*
* This function corrects the tick count value after the application code has held
* interrupts disabled for an extended period resulting in tick interrupts having
* been missed.
*
* This function is similar to vTaskStepTick(), however, unlike
* vTaskStepTick(), xTaskCatchUpTicks() may move the tick count forward past a
* time at which a task should be removed from the blocked state. That means
* tasks may have to be removed from the blocked state as the tick count is
* moved.
*
* @param xTicksToCatchUp The number of tick interrupts that have been missed due to
* interrupts being disabled. Its value is not computed automatically, so must be
* computed by the application writer.
*
* @return pdTRUE if moving the tick count forward resulted in a task leaving the
* blocked state and a context switch being performed. Otherwise pdFALSE.
*
* \defgroup xTaskCatchUpTicks xTaskCatchUpTicks
* \ingroup TaskCtrl
*/
BaseType_t xTaskCatchUpTicks( TickType_t xTicksToCatchUp ) PRIVILEGED_FUNCTION;
/**
* task.h
* @code{c}
* void vTaskResetState( void );
* @endcode
*
* This function resets the internal state of the task. It must be called by the
* application before restarting the scheduler.
*
* \defgroup vTaskResetState vTaskResetState
* \ingroup SchedulerControl
*/
void vTaskResetState( void ) PRIVILEGED_FUNCTION;
/*-----------------------------------------------------------
* SCHEDULER INTERNALS AVAILABLE FOR PORTING PURPOSES
*----------------------------------------------------------*/
#if ( configNUMBER_OF_CORES == 1 )
#define taskYIELD_WITHIN_API() portYIELD_WITHIN_API()
#else /* #if ( configNUMBER_OF_CORES == 1 ) */
#define taskYIELD_WITHIN_API() vTaskYieldWithinAPI()
#endif /* #if ( configNUMBER_OF_CORES == 1 ) */
/*
* THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS ONLY
* INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS
* AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
*
* Called from the real time kernel tick (either preemptive or cooperative),
* this increments the tick count and checks if any tasks that are blocked
* for a finite period required removing from a blocked list and placing on
* a ready list. If a non-zero value is returned then a context switch is
* required because either:
* + A task was removed from a blocked list because its timeout had expired,
* or
* + Time slicing is in use and there is a task of equal priority to the
* currently running task.
*/
BaseType_t xTaskIncrementTick( void ) PRIVILEGED_FUNCTION;
/*
* THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN
* INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
*
* THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED.
*
* 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 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.
*
* The 'unordered' version replaces the event list item value with the
* xItemValue value, and inserts the list item at the end of the list.
*
* The 'ordered' version uses the existing event list item value (which is the
* owning task's priority) to insert the list item into the event list in task
* priority order.
*
* @param pxEventList The list containing tasks that are blocked waiting
* for the event to occur.
*
* @param xItemValue The item value to use for the event list item when the
* event list is not ordered by task priority.
*
* @param xTicksToWait The maximum amount of time that the task should wait
* for the event to occur. This is specified in kernel ticks, the constant
* portTICK_PERIOD_MS can be used to convert a time specified in milliseconds to a
* time specified in ticks.
*/
void vTaskPlaceOnEventList( List_t * const pxEventList,
const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
void vTaskPlaceOnUnorderedEventList( List_t * pxEventList,
const TickType_t xItemValue,
const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
/*
* THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN
* INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
*
* THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED.
*
* This function performs nearly the same function as vTaskPlaceOnEventList().
* The difference being that this function does not permit tasks to block
* indefinitely, whereas vTaskPlaceOnEventList() does.
*
*/
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
* INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
*
* THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED.
*
* Removes a task from both the specified event list and the list of blocked
* tasks, and places it on a ready queue.
*
* xTaskRemoveFromEventList()/vTaskRemoveFromUnorderedEventList() 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 will
* have the highest priority owning task of all of the tasks on the event list.
* vTaskRemoveFromUnorderedEventList() 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
* passed in the xItemValue parameter.
*
* @return pdTRUE if the task being removed has a higher priority than the task
* making the call, otherwise pdFALSE.
*/
BaseType_t xTaskRemoveFromEventList( const List_t * const pxEventList ) PRIVILEGED_FUNCTION;
void vTaskRemoveFromUnorderedEventList( ListItem_t * pxEventListItem,
const TickType_t xItemValue ) PRIVILEGED_FUNCTION;
/*
* THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS ONLY
* INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS
* AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
*
* Sets the pointer to the current TCB to the TCB of the highest priority task
* that is ready to run.
*/
#if ( configNUMBER_OF_CORES == 1 )
portDONT_DISCARD void vTaskSwitchContext( void ) PRIVILEGED_FUNCTION;
#else
portDONT_DISCARD void vTaskSwitchContext( BaseType_t xCoreID ) PRIVILEGED_FUNCTION;
#endif
/*
* THESE FUNCTIONS MUST NOT BE USED FROM APPLICATION CODE. THEY ARE USED BY
* THE EVENT BITS MODULE.
*/
TickType_t uxTaskResetEventItemValue( void ) PRIVILEGED_FUNCTION;
/*
* Return the handle of the calling task.
*/
TaskHandle_t xTaskGetCurrentTaskHandle( void ) PRIVILEGED_FUNCTION;
/*
* Return the handle of the task running on specified core.
*/
TaskHandle_t xTaskGetCurrentTaskHandleForCore( BaseType_t xCoreID ) PRIVILEGED_FUNCTION;
/*
* Shortcut used by the queue implementation to prevent unnecessary call to
* taskYIELD();
*/
void vTaskMissedYield( void ) PRIVILEGED_FUNCTION;
/*
* Returns the scheduler state as taskSCHEDULER_RUNNING,
* taskSCHEDULER_NOT_STARTED or taskSCHEDULER_SUSPENDED.
*/
BaseType_t xTaskGetSchedulerState( void ) PRIVILEGED_FUNCTION;
/*
* Raises the priority of the mutex holder to that of the calling task should
* the mutex holder have a priority less than the calling task.
*/
BaseType_t xTaskPriorityInherit( TaskHandle_t const pxMutexHolder ) PRIVILEGED_FUNCTION;
/*
* Set the priority of a task back to its proper priority in the case that it
* inherited a higher priority while it was holding a semaphore.
*/
BaseType_t xTaskPriorityDisinherit( TaskHandle_t const pxMutexHolder ) PRIVILEGED_FUNCTION;
/*
* If a higher priority task attempting to obtain a mutex caused a lower
* priority task to inherit the higher priority task's priority - but the higher
* priority task then timed out without obtaining the mutex, then the lower
* priority task will disinherit the priority again - but only down as far as
* the highest priority task that is still waiting for the mutex (if there were
* more than one task waiting for the mutex).
*/
void vTaskPriorityDisinheritAfterTimeout( TaskHandle_t const pxMutexHolder,
UBaseType_t uxHighestPriorityWaitingTask ) PRIVILEGED_FUNCTION;
/*
* Get the uxTaskNumber assigned to the task referenced by the xTask parameter.
*/
#if ( configUSE_TRACE_FACILITY == 1 )
UBaseType_t uxTaskGetTaskNumber( TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
#endif
/*
* Set the uxTaskNumber of the task referenced by the xTask parameter to
* uxHandle.
*/
#if ( configUSE_TRACE_FACILITY == 1 )
void vTaskSetTaskNumber( TaskHandle_t xTask,
const UBaseType_t uxHandle ) PRIVILEGED_FUNCTION;
#endif
/*
* 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 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.
*/
#if ( configUSE_TICKLESS_IDLE != 0 )
void vTaskStepTick( TickType_t xTicksToJump ) PRIVILEGED_FUNCTION;
#endif
/*
* Only available when configUSE_TICKLESS_IDLE is set to 1.
* Provided for use within portSUPPRESS_TICKS_AND_SLEEP() to allow the port
* specific sleep function to determine if it is ok to proceed with the sleep,
* and if it is ok to proceed, if it is ok to sleep indefinitely.
*
* This function is necessary because portSUPPRESS_TICKS_AND_SLEEP() is only
* called with the scheduler suspended, not from within a critical section. It
* is therefore possible for an interrupt to request a context switch between
* portSUPPRESS_TICKS_AND_SLEEP() and the low power mode actually being
* entered. eTaskConfirmSleepModeStatus() should be called from a short
* critical section between the timer being stopped and the sleep mode being
* entered to ensure it is ok to proceed into the sleep mode.
*/
#if ( configUSE_TICKLESS_IDLE != 0 )
eSleepModeStatus eTaskConfirmSleepModeStatus( void ) PRIVILEGED_FUNCTION;
#endif
/*
* For internal use only. Increment the mutex held count when a mutex is
* taken and return the handle of the task that has taken the mutex.
*/
TaskHandle_t pvTaskIncrementMutexHeldCount( void ) PRIVILEGED_FUNCTION;
/*
* For internal use only. Same as vTaskSetTimeOutState(), but without a critical
* section.
*/
void vTaskInternalSetTimeOutState( TimeOut_t * const pxTimeOut ) PRIVILEGED_FUNCTION;
/*
* For internal use only. Same as portYIELD_WITHIN_API() in single core FreeRTOS.
* For SMP this is not defined by the port.
*/
#if ( configNUMBER_OF_CORES > 1 )
void vTaskYieldWithinAPI( void );
#endif
/*
* This function is only intended for use when implementing a port of the scheduler
* and is only available when portCRITICAL_NESTING_IN_TCB is set to 1 or configNUMBER_OF_CORES
* is greater than 1. This function can be used in the implementation of portENTER_CRITICAL
* if port wants to maintain critical nesting count in TCB in single core FreeRTOS.
* It should be used in the implementation of portENTER_CRITICAL if port is running a
* multiple core FreeRTOS.
*/
#if ( ( portCRITICAL_NESTING_IN_TCB == 1 ) || ( configNUMBER_OF_CORES > 1 ) )
void vTaskEnterCritical( void );
#endif
/*
* This function is only intended for use when implementing a port of the scheduler
* and is only available when portCRITICAL_NESTING_IN_TCB is set to 1 or configNUMBER_OF_CORES
* is greater than 1. This function can be used in the implementation of portEXIT_CRITICAL
* if port wants to maintain critical nesting count in TCB in single core FreeRTOS.
* It should be used in the implementation of portEXIT_CRITICAL if port is running a
* multiple core FreeRTOS.
*/
#if ( ( portCRITICAL_NESTING_IN_TCB == 1 ) || ( configNUMBER_OF_CORES > 1 ) )
void vTaskExitCritical( void );
#endif
/*
* This function is only intended for use when implementing a port of the scheduler
* and is only available when configNUMBER_OF_CORES is greater than 1. This function
* should be used in the implementation of portENTER_CRITICAL_FROM_ISR if port is
* running a multiple core FreeRTOS.
*/
#if ( configNUMBER_OF_CORES > 1 )
UBaseType_t vTaskEnterCriticalFromISR( void );
#endif
/*
* This function is only intended for use when implementing a port of the scheduler
* and is only available when configNUMBER_OF_CORES is greater than 1. This function
* should be used in the implementation of portEXIT_CRITICAL_FROM_ISR if port is
* running a multiple core FreeRTOS.
*/
#if ( configNUMBER_OF_CORES > 1 )
void vTaskExitCriticalFromISR( UBaseType_t uxSavedInterruptStatus );
#endif
#if ( portUSING_MPU_WRAPPERS == 1 )
/*
* For internal use only. Get MPU settings associated with a task.
*/
xMPU_SETTINGS * xTaskGetMPUSettings( TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
#endif /* portUSING_MPU_WRAPPERS */
#if ( ( portUSING_MPU_WRAPPERS == 1 ) && ( configUSE_MPU_WRAPPERS_V1 == 0 ) && ( configENABLE_ACCESS_CONTROL_LIST == 1 ) )
/*
* For internal use only. Grant/Revoke a task's access to a kernel object.
*/
void vGrantAccessToKernelObject( TaskHandle_t xExternalTaskHandle,
int32_t lExternalKernelObjectHandle ) PRIVILEGED_FUNCTION;
void vRevokeAccessToKernelObject( TaskHandle_t xExternalTaskHandle,
int32_t lExternalKernelObjectHandle ) PRIVILEGED_FUNCTION;
/*
* For internal use only. Grant/Revoke a task's access to a kernel object.
*/
void vPortGrantAccessToKernelObject( TaskHandle_t xInternalTaskHandle,
int32_t lInternalIndexOfKernelObject ) PRIVILEGED_FUNCTION;
void vPortRevokeAccessToKernelObject( TaskHandle_t xInternalTaskHandle,
int32_t lInternalIndexOfKernelObject ) PRIVILEGED_FUNCTION;
#endif /* #if ( ( portUSING_MPU_WRAPPERS == 1 ) && ( configUSE_MPU_WRAPPERS_V1 == 0 ) && ( configENABLE_ACCESS_CONTROL_LIST == 1 ) ) */
/* *INDENT-OFF* */
#ifdef __cplusplus
}
#endif
/* *INDENT-ON* */
#endif /* INC_TASK_H */
Reference in a new issue View git blame Copy permalink