freertos- 任务管理数据结构和相关API （笔记）

1，任务相关数据结构

typedef void * TaskHandle_t;

typedef BaseType_t (*TaskHookFunction_t)( void * );

/* 任务的状态 5种 */
typedef enum
{
	eRunning = 0,	/* 任务正在查询自己的状态，因此必须正在运行. */
	eReady,			/* 正在查询的任务位于已就绪或待处理就绪列表中. */
	eBlocked,		/* 被查询的任务处于阻塞状态. */
	eSuspended,		/* 被查询的任务处于暂停状态，或者处于阻塞状态，超时时间为无限. */
	eDeleted,		/* 正在查询的任务已被删除，但其TCB尚未释放. */
	eInvalid		/* “无效状态”. */
} eTaskState;

/* 调用vTaskNotify()时可以执行的操作. */
typedef enum
{
	eNoAction = 0,				/* 在不更新通知值的情况下通知任务. */
	eSetBits,					/* 在任务的通知值中设置位. */
	eIncrement,					/* 增加任务的通知值. */
	eSetValueWithOverwrite,		/* 将任务的通知值设置为特定值，即使之前的值尚未被任务读取. */
	eSetValueWithoutOverwrite	/* 如果任务已经读取了之前的值，则设置任务的通知值. */
} eNotifyAction;

/*仅在内部使用 */
typedef struct xTIME_OUT
{
	BaseType_t xOverflowCount;
	TickType_t xTimeOnEntering;
} TimeOut_t;

/*定义使用MPU时分配给任务的内存范围 */
typedef struct xMEMORY_REGION
{
	void *pvBaseAddress;
	uint32_t ulLengthInBytes;
	uint32_t ulParameters;
} MemoryRegion_t;

/*创建受MPU保护的任务所需的参数 */
typedef struct xTASK_PARAMETERS
{
	TaskFunction_t pvTaskCode;
	const char * const pcName;	/*不合格字符类型只允许用于字符串和单个字符 */
	uint16_t usStackDepth;
	void *pvParameters;
	UBaseType_t uxPriority;
	StackType_t *puxStackBuffer;
	MemoryRegion_t xRegions[ portNUM_CONFIGURABLE_REGIONS ];
} TaskParameters_t;

/* 与uxTaskGetSystemState()函数一起使用，以返回系统中每个任务的状态 */
typedef struct xTASK_STATUS
{
	TaskHandle_t xHandle;			/* 结构中其余信息与之相关的任务的句柄。 */
	const char *pcTaskName;			/* 指向任务名称的指针。如果由于填充了结构而删除了任务，那么该值将无效! */ 
	UBaseType_t xTaskNumber;		/*任务特有的数字. */
	eTaskState eCurrentState;		/* 填充结构时任务存在的状态 */
	UBaseType_t uxCurrentPriority;	/*填充结构时任务运行的优先级(可能是继承的)。 */
	UBaseType_t uxBasePriority;		/* 如果任务的当前优先级已被继承，以避免在获取互斥锁时进行无界优先级反转，则任务将返回的优先级。只有当configuse_mutex在FreeRTOSConfig.h中定义为1时才有效。*/
	uint32_t ulRunTimeCounter;		/* 到目前为止分配给任务的总运行时间，由运行时统计时钟定义。 */
	StackType_t *pxStackBase;		/* 指向任务堆栈区域的最低地址. */
	uint16_t usStackHighWaterMark;	/* 自创建任务以来为任务保留的最小堆栈空间. */
} TaskStatus_t;

/* eTaskConfirmSleepModeStatus()的可能返回值。 */
typedef enum
{
	eAbortSleep = 0,		/* 在调用portSUPPORESS_TICKS_AND_SLEEP()之后，已经准备好了一个任务或者挂起了一个上下文切换——中止进入睡眠模式. */
	eStandardSleep,			/* 进入不超过预期空闲时间的睡眠模式。 */
	eNoTasksWaitingTimeout	/* 没有任务等待超时，所以进入只能由外部中断退出的睡眠模式是安全的. */
} eSleepModeStatus;


#define tskIDLE_PRIORITY			( ( UBaseType_t ) 0U )

 

2，任务操作相关API

#define taskYIELD()			 portYIELD()
#define taskENTER_CRITICAL()		portENTER_CRITICAL()
#define taskENTER_CRITICAL_FROM_ISR() portSET_INTERRUPT_MASK_FROM_ISR()
#define taskEXIT_CRITICAL()			portEXIT_CRITICAL()
#define taskEXIT_CRITICAL_FROM_ISR( x ) portCLEAR_INTERRUPT_MASK_FROM_ISR( x )
#define taskDISABLE_INTERRUPTS()	portDISABLE_INTERRUPTS()
#define taskENABLE_INTERRUPTS()		portENABLE_INTERRUPTS()
#define taskSCHEDULER_SUSPENDED		( ( BaseType_t ) 0 )
#define taskSCHEDULER_NOT_STARTED	( ( BaseType_t ) 1 )
#define taskSCHEDULER_RUNNING		( ( BaseType_t ) 2 )
PRIVILEGED_FUNCTION void vTaskAllocateMPURegions( TaskHandle_t xTask, const MemoryRegion_t * const pxRegions );
PRIVILEGED_FUNCTION void vTaskDelete( TaskHandle_t xTaskToDelete );
//对于给定数量的滴答声延迟任务。任务被阻塞的实际时间取决于滴答率。常数portTICK_PERIOD_MS可用于从滴答率实时计算时间——分辨率为一个滴答周期。
PRIVILEGED_FUNCTION void vTaskDelay( const TickType_t xTicksToDelay );
//将任务延迟到指定的时间。此函数可用于周期性任务，以确保执行频率恒定。
PRIVILEGED_FUNCTION void vTaskDelayUntil( TickType_t * const pxPreviousWakeTime, const TickType_t xTimeIncrement );
PRIVILEGED_FUNCTION BaseType_t xTaskAbortDelay( TaskHandle_t xTask );
PRIVILEGED_FUNCTION UBaseType_t uxTaskPriorityGet( TaskHandle_t xTask );
PRIVILEGED_FUNCTION UBaseType_t uxTaskPriorityGetFromISR( TaskHandle_t xTask );
PRIVILEGED_FUNCTION eTaskState eTaskGetState( TaskHandle_t xTask );
PRIVILEGED_FUNCTION void vTaskGetInfo( TaskHandle_t xTask, TaskStatus_t *pxTaskStatus, BaseType_t xGetFreeStackSpace, eTaskState eState );
PRIVILEGED_FUNCTION void vTaskPrioritySet( TaskHandle_t xTask, UBaseType_t uxNewPriority );
//暂停任何任务。当一个任务被挂起时，无论它的优先级如何，都不会得到任何单片机处理时间。
PRIVILEGED_FUNCTION void vTaskSuspend( TaskHandle_t xTaskToSuspend );
//恢复暂停的任务。
PRIVILEGED_FUNCTION void vTaskResume( TaskHandle_t xTaskToResume );
//不应该使用xTaskResumeFromISR()来同步一个任务和一个中断，如果有可能中断会在任务被挂起之前到达——因为这会导致中断被错过。使用信号量作为同步机制将避免这种可能性。
PRIVILEGED_FUNCTION BaseType_t xTaskResumeFromISR( TaskHandle_t xTaskToResume );
PRIVILEGED_FUNCTION void vTaskStartScheduler( void );
PRIVILEGED_FUNCTION void vTaskEndScheduler( void );
//挂起调度器而不禁用中断。在调度程序暂停时，不会发生上下文切换。调用vTaskSuspendAll()后，调用任务将继续执行，直到调用xTaskResumeAll()为止，不会有被交换出去的风险。
PRIVILEGED_FUNCTION void vTaskSuspendAll( void );
//通过调用vTaskSuspendAll()暂停调度程序活动后恢复该活动, xTaskResumeAll()只恢复调度程序。它不会解除以前通过调用vTaskSuspend()而暂停的任务。
PRIVILEGED_FUNCTION BaseType_t xTaskResumeAll( void );
//返回自调用vTaskStartScheduler以来的计时次数。
PRIVILEGED_FUNCTION TickType_t xTaskGetTickCount( void );
PRIVILEGED_FUNCTION TickType_t xTaskGetTickCountFromISR( void );
//返回实时内核当前管理的任务数量。这包括所有就绪、阻塞和挂起的任务。已删除但空闲任务尚未释放的任务也将包含在计数中。
PRIVILEGED_FUNCTION UBaseType_t uxTaskGetNumberOfTasks( void );
PRIVILEGED_FUNCTION char *pcTaskGetName( TaskHandle_t xTaskToQuery ); 
PRIVILEGED_FUNCTION TaskHandle_t xTaskGetHandle( const char *pcNameToQuery ); 
PRIVILEGED_FUNCTION UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask );
//调用与xTask关联的钩子函数。将xTask传递为NULL会调用正在运行的任务(调用任务)钩子函数。
PRIVILEGED_FUNCTION BaseType_t xTaskCallApplicationTaskHook( TaskHandle_t xTask, void *pvParameter );
//简单地返回空闲任务的句柄。在启动调度器之前调用xTaskGetIdleTaskHandle()是无效的。
PRIVILEGED_FUNCTION TaskHandle_t xTaskGetIdleTaskHandle( void );
PRIVILEGED_FUNCTION UBaseType_t uxTaskGetSystemState( TaskStatus_t * const pxTaskStatusArray, const UBaseType_t uxArraySize, uint32_t * const pulTotalRunTime );
PRIVILEGED_FUNCTION void vTaskList( char * pcWriteBuffer ); /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
PRIVILEGED_FUNCTION void vTaskGetRunTimeStats( char *pcWriteBuffer ); 
PRIVILEGED_FUNCTION BaseType_t xTaskGenericNotify( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue );
#define xTaskNotify( xTaskToNotify, ulValue, eAction ) xTaskGenericNotify( ( xTaskToNotify ), ( ulValue ), ( eAction ), NULL )
#define xTaskNotifyAndQuery( xTaskToNotify, ulValue, eAction, pulPreviousNotifyValue ) xTaskGenericNotify( ( xTaskToNotify ), ( ulValue ), ( eAction ), ( pulPreviousNotifyValue ) )
PRIVILEGED_FUNCTION BaseType_t xTaskGenericNotifyFromISR( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue, BaseType_t *pxHigherPriorityTaskWoken );
#define xTaskNotifyFromISR( xTaskToNotify, ulValue, eAction, pxHigherPriorityTaskWoken ) xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( ulValue ), ( eAction ), NULL, ( pxHigherPriorityTaskWoken ) )
#define xTaskNotifyAndQueryFromISR( xTaskToNotify, ulValue, eAction, pulPreviousNotificationValue, pxHigherPriorityTaskWoken ) xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( ulValue ), ( eAction ), ( pulPreviousNotificationValue ), ( pxHigherPriorityTaskWoken ) )
//任务可以使用xTaskNotifyWait()[可选]块来等待等待通知，或者使用ulTaskNotifyTake()[可选]块来等待其通知值具有非零值。当任务处于阻塞状态时，它不会消耗任何CPU时间。
PRIVILEGED_FUNCTION BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait );
//xTaskNotifyGive()是一个辅助宏，当任务通知被用作轻量级和更快的二进制或计数信号量时使用。实际的FreeRTOS信号量是使用xSemaphoreGive() API函数给出的，而使用任务通知的等效操作是xTaskNotifyGive()。
#define xTaskNotifyGive( xTaskToNotify ) xTaskGenericNotify( ( xTaskToNotify ), ( 0 ), eIncrement, NULL )
PRIVILEGED_FUNCTION void vTaskNotifyGiveFromISR( TaskHandle_t xTaskToNotify, BaseType_t *pxHigherPriorityTaskWoken );
// ulTaskNotifyTake()用于任务通知被用作更快、更轻的二进制或计数信号量替代时。实际的FreeRTOS信号量是使用xSemaphoreTake() API函数获取的，而使用任务通知的等效操作是ulTaskNotifyTake()。
PRIVILEGED_FUNCTION uint32_t ulTaskNotifyTake( BaseType_t xClearCountOnExit, TickType_t xTicksToWait );
//如果句柄xTask引用的任务的通知状态已经过enootification，则将任务的通知状态设置为eNotWaitingNotification。任务的通知值没有更改。将xTask设置为NULL以清除调用任务的通知状态。
BaseType_t xTaskNotifyStateClear( TaskHandle_t xTask );
//从实时内核滴答(抢占式或协作式)调用，这会增加滴答计数，并检查在有限时间内被阻塞的任务是否需要从阻塞列表中删除并放置到就绪列表中.
PRIVILEGED_FUNCTION BaseType_t xTaskIncrementTick( void );
//从就绪列表中移除调用任务，并将其置于等待特定事件的任务列表和延迟任务列表中。如果事件发生(没有更高优先级的任务在同一事件上等待)或延迟期过期，任务将从两个列表中删除并在就绪列表中替换。
PRIVILEGED_FUNCTION 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 );
//这个函数执行的函数与vTaskPlaceOnEventList()几乎相同。不同之处在于，这个函数不允许任务无限期地阻塞，而vTaskPlaceOnEventList()允许。
PRIVILEGED_FUNCTION void vTaskPlaceOnEventListRestricted( List_t * const pxEventList, TickType_t xTicksToWait, const BaseType_t xWaitIndefinitely );
//从指定的事件列表和阻塞任务列表中移除任务，并将其置于就绪队列中
PRIVILEGED_FUNCTION BaseType_t xTaskRemoveFromEventList( const List_t * const pxEventList );
PRIVILEGED_FUNCTION BaseType_t xTaskRemoveFromUnorderedEventList( ListItem_t * pxEventListItem, const TickType_t xItemValue );
//将当前TCB的指针设置为准备运行的最高优先级任务的TCB。
PRIVILEGED_FUNCTION void vTaskSwitchContext( void );
//这些函数不能从应用程序代码中使用。它们由事件位模块使用。
PRIVILEGED_FUNCTION TickType_t uxTaskResetEventItemValue( void );
//返回调用任务的句柄。
PRIVILEGED_FUNCTION TaskHandle_t xTaskGetCurrentTaskHandle( void );
//获取当前时间状态以备将来参考。
PRIVILEGED_FUNCTION void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut );
//将现在的时间状态与以前捕获的时间状态进行比较，看看超时是否已经过期。
PRIVILEGED_FUNCTION BaseType_t xTaskCheckForTimeOut( TimeOut_t * const pxTimeOut, TickType_t * const pxTicksToWait );
//队列实现使用的快捷方式，以防止对taskYIELD()的不必要调用;
PRIVILEGED_FUNCTION void vTaskMissedYield( void );
//返回调度程序状态为taskSCHEDULER_RUNNING、taskSCHEDULER_NOT_STARTED或taskscheduler _suspend。
PRIVILEGED_FUNCTION BaseType_t xTaskGetSchedulerState( void );
//如果互斥锁持有者的优先级小于调用任务，则将互斥锁持有者的优先级提升到调用任务的优先级。
PRIVILEGED_FUNCTION void vTaskPriorityInherit( TaskHandle_t const pxMutexHolder );
//如果任务在持有信号量时继承了更高的优先级，则将任务的优先级设置为适当的优先级。
PRIVILEGED_FUNCTION BaseType_t xTaskPriorityDisinherit( TaskHandle_t const pxMutexHolder );
//获取分配给xTask参数引用的任务的uxTCBNumber
PRIVILEGED_FUNCTION UBaseType_t uxTaskGetTaskNumber( TaskHandle_t xTask );
//将xTask参数引用的任务的uxTaskNumber设置为uxHandle
PRIVILEGED_FUNCTION void vTaskSetTaskNumber( TaskHandle_t xTask, const UBaseType_t uxHandle );
//只有configUSE_TICKLESS_IDLE设置为1时才可用。如果使用无tickless模式，或者实现低功耗模式，那么tick中断将不会在空闲期间执行。在这种情况下，调度器维护的tick count值需要通过向前跳过等于空闲周期的时间来与实际执行时间保持同步。
PRIVILEGED_FUNCTION void vTaskStepTick( const TickType_t xTicksToJump );
//只有当configUSE_TICKLESS_IDLE设置为1时才可以使用。提供在portSUPPRESS_TICKS_AND_SLEEP()中使用，以允许端口特定的sleep函数确定是否可以继续休眠，以及是否可以继续，是否可以无限期休眠。
PRIVILEGED_FUNCTION eSleepModeStatus eTaskConfirmSleepModeStatus( void );
//只供内部使用。在获取互斥锁时，增加互斥锁持有的计数，并返回已获取该互斥锁的任务的句柄。
PRIVILEGED_FUNCTION void *pvTaskIncrementMutexHeldCount( void );

3，重要的接口

   3.1任务的挂起和恢复

void vTaskSuspend（TaskHandle_t xTaskToSuspend）;
void vTaskResume（TaskHandle_t xTaskToResume）;
BaseType_t xTaskResumeFromISR（TaskHandle_t xTaskToResume）;

   3.2 任务的创建和删除

    BaseType_t xTaskCreate(    TaskFunction_t pxTaskCode,  const char * const pcName,   const uint16_t usStackDepth,
                            void * const pvParameters,UBaseType_t uxPriority, TaskHandle_t * const pxCreatedTask )

   void vTaskDelete( TaskHandle_t xTaskToDelete )

   3.3任务调度器

PRIVILEGED_FUNCTION void vTaskSuspendAll（void）;
PRIVILEGED_FUNCTION BaseType_t xTaskResumeAll（void）;

   3.4任务延时

PRIVILEGED_FUNCTION void vTaskDelete（TaskHandle_t xTaskToDelete）;
PRIVILEGED_FUNCTION void vTaskDelay（const TickType_t xTicksToDelay）;
PRIVILEGED_FUNCTION void vTaskDelayUntil（TickType_t * const pxPreviousWakeTime，const TickType_t xTimeIncrement）;

   3.5任务通知

略。