FreeRTOS Task && Scheduler API

最新推荐文章于 2024-05-22 10:00:00 发布
___Crystal
最新推荐文章于 2024-05-22 10:00:00 发布
阅读量270
点赞数
分类专栏： FreeRTOS 文章标签：嵌入式 arm stm32 单片机
本文链接：https://blog.csdn.net/CrystalTri/article/details/127252963
版权
FreeRTOS 专栏收录该内容
1 篇文章 0 订阅
订阅专栏
FreeRTOS Task && Scheduler API 函数总结:
void	portSWITCH_TO_USER_MODE( void );	
/*1.和使用MPU相关*/


void    vTaskAllocateMPURegions( TaskHandle_t                 xTaskToModify, 
                                 const MemoryRegion_t * const xRegions );
/*2.和使用MPU相关,限定任务使用的内存区域*/


BaseType_t		xTaskAbortDelay( TaskHandle_t	xTask );
/*
3.即使任务等待的事件没有发生,并且进入阻塞态持续的时间没有结束,
强制将一个任务从阻塞态转移到就绪态
INCLUDE_xTaskAbortDelay must be set to 1 in FreeRTOSConfig.h for xTaskAbortDelay()  to be available.
*/


BaseType_t	xTaskCallApplicationTaskHook( TaskHandle_t	xTask, void	*pvParameters );
/*
4.特殊应用,可以为一个任务分配一个回调函数,例如调试信息应用(pvParameters可以为一个函数指针);
xTaskCallApplicationTaskHook() is only available when configUSE_APPLICATION_TASK_TAGis set to 1 in FreeRTOSConfig.h.
*/
	
BaseType_t	xTaskCheckForTimeOut( TimeOut_t	* const pxTimeOut, 
                                  TickType_t* const pxTicksToWait );
/*
5.调用vTaskSetTimeOutState()设置初始条件(pxTimeOut指针),随后调用xTaskCheckForTimeOut()检查超时条件,如果没有发生超时,则调整剩余时间
应用在不期望超过最大阻塞时间的场景,灵活调整剩余的阻塞时间以使总阻塞时间不超过pxTicksToWait
*/


BaseType_t		xTaskCreate(TaskFunction_t	 pvTaskCode, 
							const char*		 const pcName, 
							unsigned short	 usStackDepth, 
							void*			 pvParameters, 
							UBaseType_t		 uxPriority, 
							TaskHandle_t*	 pxCreatedTask);
/*
6.创建一个任务实例,由FreeRTOS的heap动态分配内存;
新创建的任务默认初始化为就绪态,如果没有更高优先级的任务则会立即变为运行态;
configSUPPORT_DYNAMIC_ALLOCATION must be set to 1 in FreeRTOSConfig.h, or simply left undefined, for this function to be available.
*/

	
TaskHandle_t    xTaskCreateStatic(TaskFunction_t	pvTaskCode,
								  const char*		const pcName, 
								  uint32_t			ulStackDepth, 
								  void	*			pvParameters, 
								  UBaseType_t		uxPriority,
								  StackType_t*		const puxStackBuffer,
								  StaticTask_t*		const pxTaskBuffer);
/*
7.configSUPPORT_STATIC_ALLOCATION  must  be  set  to  1  in  FreeRTOSConfig.h  for  this function to be available.
*/

	
BaseType_t	xTaskCreateRestricted( TaskParameters_t	*pxTaskDefinition,                                 
                                   TaskHandle_t		*pxCreatedTask );
/*
8.和使用MPU相关Create a new Memory Protection Unit (MPU) restricted task
*/


void    vTaskDelay( TickType_t	xTicksToDelay );
/*
9.调用vTaskDelay(0)相当于调用了taskYIELD(),会使任务切换到同优先级的处于就绪态的任务;
vTaskDelay(20)---使任务进入阻塞态20个tick,时间取决于tick频率
vTaskDelay(pdMS_TO_TICKS(20))--使任务阻塞20ms
INCLUDE_vTaskDelaymust  be  set  to  1  in  FreeRTOSConfig.h  for  the  vTaskDelay()  API function to be available.
*/
	

void	 vTaskDelayUntil( TickType_t*	pxPreviousWakeTime, TickType_t	xTimeIncrement);
/*
10.周期性任务可以使用vTaskDelayUntil() 来获取一个持续的执行频率;
使用xTaskGetTickCount()获取时间作为pxPreviousWakeTime,然后设置周期xTimeIncrement,
达到周期性调用;
INCLUDE_vTaskDelayUntilmust be set to 1 in FreeRTOSConfig.h for the vTaskDelay() API function to be available.
*/

	
void	vTaskDelete( TaskHandle_t	pxTask );
/*
11.删除任务使之再也不能进入运行态;
不能使用已经删除任务的任务句柄;
删除任务之后应给空闲任务处理时间来清理内存;
*/

	
void	taskDISABLE_INTERRUPTS( void);
/*
12.如果FreeRTOS没有使用configMAX_SYSCALL_INTERRUPT_PRIORITY,则调用taskDISABLE_INTERRUPTS()会禁用所有中断;
反之,则会使低于configMAX_SYSCALL_INTERRUPT_PRIORITY的中断禁止;
taskDISABLE_INTERRUPTS() 和taskENABLE_INTERRUPTS() 不是嵌套使用的,比如调用了两次禁止中断,只需调用一次taskENABLE_INTERRUPTS()便可使能中断;
嵌套的场景使用 taskENTER_CRITICAL() 和taskEXIT_CRITICAL()替代; 
*/

	
void	 taskENABLE_INTERRUPTS( void );/*13.*/


void	 taskENTER_CRITICAL(void );
/*
14.如果在中断服务程序中,使用taskENTER_CRITICAL_FROM_ISR() ;
禁止中断的优先级同样和configMAX_SYSCALL_INTERRUPT_PRIORITY有关;
taskENTER_CRITICAL() 和taskEXIT_CRITICAL() 是嵌套使用的;
FreeRTOS的API函数不能在关键部分被调用
*/

	
UBaseType_t	taskENTER_CRITICAL_FROM_ISR(void );               /*15.*/
void        taskEXIT_CRITICAL( void );                        /*16.*/
void	    taskENTER_CRITICAL_FROM_ISR(UBaseType_t	uxSavedInterruptStatus );/*17.*/
void	    taskEXIT_CRITICAL_FROM_ISR(UBaseType_t	uxSavedInterruptStatus );/*18.*/


TaskHookFunction_t		xTaskGetApplicationTaskTag( TaskHandle_t	xTask );
/*
19.返回任务分配的一个‘tag’值,该值由应用程序作者指定(vTaskSetApplicationTaskTag);
configUSE_APPLICATION_TASK_TAG must be set to 1 in  FreeRTOSConfig.h for xTaskGetApplicationTaskTag()to be available.
*/

	
TaskHandle_t	xTaskGetCurrentTaskHandle(void );
/*
20.获取当前处于运行态的任务句柄,即当前调用xTaskGetCurrentTaskHandle的任务的任务句柄
INCLUDE_xTaskGetCurrentTaskHandle must be set to 1 in FreeRTOSConfig.h for xTaskGetCurrentTaskHandle() to be available.
*/

	
TaskHandle_t	xTaskGetIdleTaskHandle(void );
/*
21.返回空闲任务句柄,空闲任务在调度器开始时自动创建;
INCLUDE_xTaskGetIdleTaskHandle must be set to 1 in FreeRTOSConfig.h for xTaskGetIdleTaskHandle() to be available.
*/

	
TaskHandle_t	xTaskGetHandle( const char	*	pcNameToQuery );
/*
22.利用创建任务时的参数pcName来查询对应的任务句柄;
由于xTaskGetHandle()花费的时间较长,建议对每个任务名字只使用一次,然后将任务句柄存储起来重复用;
不能处理两个不同任务具有相同任务名字的情况;
INCLUDE_xTaskGetHandle must be set to 1 in FreeRTOSConfig.h for xTaskGetHandle() to be available.
*/

	
UBaseType_t	uxTaskGetNumberOfTasks( void );
/*
23.返回调用uxTaskGetNumberOfTasks时存在的总任务数量;
任务包括所有挂起态,阻塞态,就绪态,运行态和空闲任务的加和;
*/
	
void	vTaskGetRunTimeStats( char*	pcWriteBuffer);
/*
24.用来统计任务的运行时间信息;
该API函数将统计信息转化为可读的3列信息,包括任务名称,任务耗时和任务耗时占比,统计包括所有任务
要保证pcWriteBuffer足够大,因为API没有执行边界检查,建议声明为static放置在静态存储区;
vTaskGetRunTimeStats统计信息源自uxTaskGetSystemState的返回值;
configGENERATE_RUN_TIME_STATS and configUSE_STATS_FORMATTING_FUNCTIONS must both be  set  to 1 in FreeRTOSConfig.h  for  vTaskGetRunTimeStats() to be available.
另外需要定义的宏:	portCONFIGURE_TIMER_FOR_RUN_TIME_STATS()推荐时间基准频率为10-20倍的tick频率,保证统计的精度;						portGET_RUN_TIME_COUNTER_VALUE()/portALT_GET_RUN_TIME_COUNTER_VALUE(Time)返回当前时间;
*/


BaseType_t	xTaskGetSchedulerState( void );
/*
25.返回调用该API函数时调度器的状态;
	3种状态:	taskSCHEDULER_NOT_STARTED	-	未启动,调用vTaskStartScheduler() 之前;
				taskSCHEDULER_RUNNING		-	运行态,已经调用了vTaskStartScheduler() ,并                                                                            
                                               且未被挂起;
				taskSCHEDULER_SUSPENDED	-	挂起态,调用了vTaskSuspendAll() ;
	INCLUDE_xTaskGetSchedulerStatemust be set to 1 in FreeRTOSConfig.h for xTaskGetSchedulerState() to be available.
*/

	
UBaseType_t	uxTaskGetStackHighWaterMark( TaskHandle_t	xTask );
/*
26.随着任务的运行和中断的处理,栈空间的数量会一直增减,uxTaskGetStackHighWaterMark返回任务执行期间最小的栈剩余空间;
该API函数消耗时间较长,仅推荐在测试或调试程序中使用;
INCLUDE_uxTaskGetStackHighWaterMarkmust be set to 1 in FreeRTOSConfig.h for uxTaskGetStackHighWaterMark() to be available.
*/


eTaskState	eTaskGetState( TaskHandle_t	pxTask);
/*
27.返回调用eTaskGetState时的指定任务的任务状态,eRunning,eReady,eBlocked,eSuspended,eDeleted (任务的结构等待被清除);
INCLUDE_eTaskGetState must be set to 1 in FreeRTOSConfig.h for the eTaskGetState() API function to be available.
*/
	
UBaseType_t	uxTaskGetSystemState(	TaskStatus_t*			const pxTaskStatusArray, 
									const UBaseType_t	    uxArraySize, 
									unsigned long	*		const pulTotalRunTime );
/*
28.返回任务结构体TaskStatus_t的数量应该和uxTaskGetNumberOfTasks保持一致;
结构体参数包括:任务句柄,任务名字,任务序号,任务状态,任务优先级,时间信息,栈底指针,剩余栈空间信息;
进获取任务耗时信息的话直接应用vTaskGetRunTimeStats更方便,因为后者直接将时间时间信息的统计结果格式化为易读的了;
同样的道理,获取其它详细的信息也可以使用vTaskList
*/
void	vTaskGetTaskInfo( TaskHandle_t		xTask,
						  TaskStatus_t*		pxTaskStatus,
						  BaseType_t		xGetFreeStackSpace,
						  eTaskState		eState );
/*29.xGetFreeStackSpace写pdTRUE时TaskStatus_t中将写入High water mark信息*/


void*	pvTaskGetThreadLocalStoragePointer( TaskHandle_t	xTaskToQuery,
                                            BaseType_t	    xIndex );
/*
30.每个任务都有自己的线程本地存储指针,允许用户向其中存储一些值,configNUM_THREAD_LOCAL_STORAGE_POINTERS定义索引的数量;
在TCB_t中有定义,其实就是一个数组而已;
调用当前线程index为5的值:
ulVariable = ( uint32_t ) pvTaskGetThreadLocalStoragePointer( NULL, 5 );
*/


char*	pcTaskGetName( TaskHandle_t	xTaskToQuery);
/*
31.返回任务的名字;该名称是在创建任务时分配的;
*/


TickType_t		xTaskGetTickCount( void );
/*
32.返回自调度器启动开始的总tick数;
tick溢出不会影响FreeRTOS内核操作,但用户应用程序必要时要考虑时间溢出
configUSE_16_BIT_TICKS为1,为16位计数,为0,则tick为32位计数
*/


TickType_t		xTaskGetTickCountFromISR( void );/*33.*/
void	vTaskList(char*	pcWriteBuffer);
/*34.格式化输出名称,状态,优先级,栈,序列号信息*/


BaseType_t	xTaskNotify(	TaskHandle_t	xTaskToNotify, 
							uint32_t		ulValue, 
							eNotifyAction	eAction );
/*
35.TCB_t中定义了任务中有一个32位的ulNotifiedValue值,创建任务时被初始化为0;
xTaskNotify用来发送事件来解除任务的阻塞状态,并以下面4种方式更新接收任务的ulNotifiedValue值:
		(1)eSetValueWithOverwrite/eSetValueWithoutOverwrite:写一个32位的数到                
           ulNotifiedValue,覆盖还是不覆盖原来的值;
		(2)eIncrement:使ulNotifiedValue加1;
		(3)eSetBits:设置一个或多个ulNotifiedValue的位;
		(4)eNoAction:对ulNotifiedValue不做任何改变
	仅当eAction设置为eSetValueWithoutOverwrite并且任务的ulNotifiedValue没有更新时才会返回 pdFAIL;
	如果任务的通知值被用作二值信号量或者计数信号量,用xTaskNotifyGive替代
*/


BaseType_t	xTaskNotifyAndQuery(	TaskHandle_t	xTaskToNotify, 
									uint32_t		ulValue, 
									eNotifyAction eAction,
									uint32_t*		pulPreviousNotifyValue );
/*36.在xTaskNotify基础上增加了查询指定任务原来的通知值;*/


BaseType_t	xTaskNotifyAndQueryFromISR(	TaskHandle_t		xTaskToNotify, 
										uint32_t			ulValue, 
										eNotifyAction		eAction,
										uint32_t*			pulPreviousNotifyValue,
										BaseType_t *		pxHigherPriorityTaskWoken );
/*
37.xHigherPriorityTaskWoken开始要设置成pdFALSE;
xHigherPriorityTaskWoken如果变成了pdTRUE,调用之后要进行上下位切换;
portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
*/
	

BaseType_t	xTaskNotifyFromISR(	TaskHandle_t	xTaskToNotify, 
								uint32_t		ulValue, 
								eNotifyAction	eActionBase
								Type_t*			pxHigherPriorityTaskWoken );
/*
38.
*/


BaseType_t	xTaskNotifyGive( TaskHandle_t	xTaskToNotify );/*39.*/
void	    vTaskNotifyGiveFromISR( TaskHandle_t	xTaskToNotify, 
                                    BaseType_t *	pxHigherPriorityTaskWoken);
/*
40.
*/


BaseType_t	xTaskNotifyStateClear( TaskHandle_t	xTask );
/*41.
	如果一个任务在通知到达时没有等待通知,则任务将保持挂起状态直到:
		(1)该接收任务读取了它的通知值;
		(2)该接收任务调用了xTaskNotifyStateClear
	调用xTaskNotifyStateClear将会清除通知的挂起态,但不会改变通知的值;
*/


uint32_t    ulTaskNotifyTake( BaseType_t	xClearCountOnExit, 
                              TickType_t	xTicksToWait );
/*42.
	使用二值信号量或计数信号量时推荐使用ulTaskNotifyTake替代 xSemaphoreTake;
	通知挂起时xTaskNotifyWait()会返回,通知值不是0时,ulTaskNotifyTake() 会返回并且其通知值在返回前自减;
	xClearCountOnExit设置为pdFALSE,返回时会自减,等同于调用xSemaphoreTake()的计数信号量,
					设置为pdTRUE,返回时会清零,等同于调用xSemaphoreTake()的二值信号量;
	返回自减或清零之前的值;
*/


BaseType_t	xTaskNotifyWait(	uint32_t		ulBitsToClearOnEntry,
								uint32_t		ulBitsToClearOnExit,
								uint32_t *		pulNotificationValue,
								TickType_t	    xTicksToWait );
/*43.
	在通知未被挂起时,通知值的任何ulBitsToClearOnEntry设置的位都在进入xTaskNotifyWait时清零;
	接收到通知时,通知值的任何ulBitsToClearOnExit设置的位都将在退出xTaskNotifyWait时清零;
	在改变ulBitsToClearOnExit设置的位之前保存通知值;
*/


UBaseType_t	uxTaskPriorityGet( TaskHandle_t	pxTask );
/*
44.查询任务优先级;
*/


void	vTaskPrioritySet( TaskHandle_t	pxTask, UBaseType_t	uxNewPriority );
/*
45.改变任务优先级(0~configMAX_PRIORITIES –1);
vTaskPrioritySet一定只能在启动调度器之前使用;
多个任务允许在阻塞时等待同一个队列或者信号量,按优先级顺序执行
*/
	

void	vTaskResume( TaskHandle_t	pxTaskToResume );
/*
46.使一个挂起态的任务转变为就绪态;
前提是该任务通过调用vTaskSuspend()被挂起;
只能在启动调度器成功后调用;
*/

	
BaseType_t	xTaskResumeAll( void );
/*
47.将所有任务从挂起态转化为就绪态;
*/
BaseType_t	xTaskResumeFromISR( TaskHandle_t	pxTaskToResume );/*48.*/
void	vTaskSetApplicationTaskTag( TaskHandle_t	xTask, 
                                    TaskHookFunction_t	pxTagValue );
/*
49.tag值可以设置为一个函数指针,当调用xTaskCallApplicationTaskHook时调用该指针函数;
configUSE_APPLICATION_TASK_TAG  must  be set  to 1 inFreeRTOSConfig.h for vTaskSetApplicationTaskTag()to be available.
	#define traceTASK_SWITCHED_OUT()	xTaskCallApplicationTaskHook( pxCurrentTCB, 0 )基于此可用于执行跟踪;
*/
void    vTaskSetThreadLocalStoragePointer( TaskHandle_t		xTaskToSet,
										   BaseType_t		xIndex, 
										   void*			pvValue );
/*
50.设置任务线程本地存储(LTS)内容;
可以用pvTaskGetThreadLocalStoragePointer访问;
*/

	
void	vTaskSetTimeOutState( TimeOut_t*	 const pxTimeOut );
/*
51.和 xTaskCheckForTimeOut连用,初始化任务阻塞时间,用来调节剩余阻塞任务时间;
*/


void	vTaskStartScheduler( void );
/*
52.启动FreeRTOS任务调度器;
启动之后,会使优先级最高的任务进入运行态;
自动创建空闲任务;
ARM7和ARM9的微控制器需要在调用vTaskStartScheduler之前先开启Supervisor模式;
*/

	
void	vTaskStepTick( TickType_t	xTicksToJump );
/*
53.和低功耗相关;如何补偿tick休眠的时间差值?
*/

	
void	vTaskSuspend( TaskHandle_t	pxTaskToSuspend );/*54.*/
void	vTaskSuspendAll( void );                      /*55.*/
void taskYIELD( void );
/*
56.切换到另外一个同优先级的任务;
不能在执行的任务中调用,否则它将被调度器以另一个相同优先级的的处于就绪态的任务替代;
如果没有处于就绪态的相同优先级的任务,它将恢复原来的运行态任务;
注意一定是相同优先级;
*/