FreeRTOS学习 -- FreeRTOSConfig.h介绍

一、FreeRTOSConfig.h文件

FreeRTOS 的系统配置文件为 FreeRTOSConfig.h，在此配置文件中可以完成 FreeRTOS 的裁剪和配置。

FreeRTOS 的配置基本是通过在 FreeRTOSConfig.h 中使用“#define”这样的语句来定义宏定义实现的。在 FreeRTOS 的官方 demo 中，每个工程都有一个 FreeRTOSConfig.h 文件，我们在使用的时候可以参考这个文件，甚至直接复制粘贴使用。

/*
    FreeRTOS V9.0.0 - Copyright (C) 2016 Real Time Engineers Ltd.
    All rights reserved

    VISIT http://www.FreeRTOS.org TO ENSURE YOU ARE USING THE LATEST VERSION.

    This file is part of the FreeRTOS distribution.

    FreeRTOS is free software; you can redistribute it and/or modify it under
    the terms of the GNU General Public License (version 2) as published by the
    Free Software Foundation >>>> AND MODIFIED BY <<<< the FreeRTOS exception.

    ***************************************************************************
    >>!   NOTE: The modification to the GPL is included to allow you to     !<<
    >>!   distribute a combined work that includes FreeRTOS without being   !<<
    >>!   obliged to provide the source code for proprietary components     !<<
    >>!   outside of the FreeRTOS kernel.                                   !<<
    ***************************************************************************

    FreeRTOS is distributed in the hope that it will be useful, but WITHOUT ANY
    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
    FOR A PARTICULAR PURPOSE.  Full license text is available on the following
    link: http://www.freertos.org/a00114.html

    ***************************************************************************
     *                                                                       *
     *    FreeRTOS provides completely free yet professionally developed,    *
     *    robust, strictly quality controlled, supported, and cross          *
     *    platform software that is more than just the market leader, it     *
     *    is the industry's de facto standard.                               *
     *                                                                       *
     *    Help yourself get started quickly while simultaneously helping     *
     *    to support the FreeRTOS project by purchasing a FreeRTOS           *
     *    tutorial book, reference manual, or both:                          *
     *    http://www.FreeRTOS.org/Documentation                              *
     *                                                                       *
    ***************************************************************************

    http://www.FreeRTOS.org/FAQHelp.html - Having a problem?  Start by reading
    the FAQ page "My application does not run, what could be wrong?".  Have you
    defined configASSERT()?

    http://www.FreeRTOS.org/support - In return for receiving this top quality
    embedded software for free we request you assist our global community by
    participating in the support forum.

    http://www.FreeRTOS.org/training - Investing in training allows your team to
    be as productive as possible as early as possible.  Now you can receive
    FreeRTOS training directly from Richard Barry, CEO of Real Time Engineers
    Ltd, and the world's leading authority on the world's leading RTOS.

    http://www.FreeRTOS.org/plus - A selection of FreeRTOS ecosystem products,
    including FreeRTOS+Trace - an indispensable productivity tool, a DOS
    compatible FAT file system, and our tiny thread aware UDP/IP stack.

    http://www.FreeRTOS.org/labs - Where new FreeRTOS products go to incubate.
    Come and try FreeRTOS+TCP, our new open source TCP/IP stack for FreeRTOS.

    http://www.OpenRTOS.com - Real Time Engineers ltd. license FreeRTOS to High
    Integrity Systems ltd. to sell under the OpenRTOS brand.  Low cost OpenRTOS
    licenses offer ticketed support, indemnification and commercial middleware.

    http://www.SafeRTOS.com - High Integrity Systems also provide a safety
    engineered and independently SIL3 certified version for use in safety and
    mission critical applications that require provable dependability.

    1 tab == 4 spaces!
*/


#ifndef FREERTOS_CONFIG_H
#define FREERTOS_CONFIG_H

#include "sys.h"
//针对不同的编译器调用不同的stdint.h文件
#if defined(__ICCARM__) || defined(__CC_ARM) || defined(__GNUC__)
    #include <stdint.h>
    extern uint32_t SystemCoreClock;
#endif

//断言
#define vAssertCalled(char,int) printf("Error:%s,%d\r\n",char,int)
#define configASSERT(x) if((x)==0) vAssertCalled(__FILE__,__LINE__)

/***************************************************************************************************************/
/*                                        FreeRTOS基础配置配置选项                                              */
/***************************************************************************************************************/
#define configUSE_PREEMPTION					1                       //1使用抢占式内核，0使用协程
#define configUSE_TIME_SLICING					1						//1使能时间片调度(默认式使能的)
#define configUSE_PORT_OPTIMISED_TASK_SELECTION	1                       //1启用特殊方法来选择下一个要运行的任务
                                                                        //一般是硬件计算前导零指令，如果所使用的
                                                                        //MCU没有这些硬件指令的话此宏应该设置为0！
#define configUSE_TICKLESS_IDLE					0                       //1启用低功耗tickless模式
#define configUSE_QUEUE_SETS					1                       //为1时启用队列集
#define configCPU_CLOCK_HZ						(SystemCoreClock)       //CPU频率
#define configTICK_RATE_HZ						(1000)                  //时钟节拍频率，这里设置为1000，周期就是1ms
#define configMAX_PRIORITIES					(32)                    //可使用的最大优先级
#define configMINIMAL_STACK_SIZE				((unsigned short)130)   //空闲任务使用的堆栈大小
#define configMAX_TASK_NAME_LEN					(16)                    //任务名字字符串长度

#define configUSE_16_BIT_TICKS					0                       //系统节拍计数器变量数据类型，
                                                                        //1表示为16位无符号整形，0表示为32位无符号整形
#define configIDLE_SHOULD_YIELD					1                       //为1时空闲任务放弃CPU使用权给其他同优先级的用户任务
#define configUSE_TASK_NOTIFICATIONS            1                       //为1时开启任务通知功能，默认开启
#define configUSE_MUTEXES						1                       //为1时使用互斥信号量
#define configQUEUE_REGISTRY_SIZE				8                       //不为0时表示启用队列记录，具体的值是可以
                                                                        //记录的队列和信号量最大数目。
#define configCHECK_FOR_STACK_OVERFLOW			0                       //大于0时启用堆栈溢出检测功能，如果使用此功能
                                                                        //用户必须提供一个栈溢出钩子函数，如果使用的话
                                                                        //此值可以为1或者2，因为有两种栈溢出检测方法。
#define configUSE_RECURSIVE_MUTEXES				1                       //为1时使用递归互斥信号量
#define configUSE_MALLOC_FAILED_HOOK			0                       //1使用内存申请失败钩子函数
#define configUSE_APPLICATION_TASK_TAG			0                       
#define configUSE_COUNTING_SEMAPHORES			1                       //为1时使用计数信号量

/***************************************************************************************************************/
/*                                FreeRTOS与内存申请有关配置选项                                                */
/***************************************************************************************************************/
#define configSUPPORT_DYNAMIC_ALLOCATION        1                       //支持动态内存申请
#define configTOTAL_HEAP_SIZE					((size_t)(46*1024))     //系统所有总的堆大小

/***************************************************************************************************************/
/*                                FreeRTOS与钩子函数有关的配置选项                                              */
/***************************************************************************************************************/
#define configUSE_IDLE_HOOK						0                       //1，使用空闲钩子；0，不使用
#define configUSE_TICK_HOOK						0                       //1，使用时间片钩子；0，不使用

/***************************************************************************************************************/
/*                                FreeRTOS与运行时间和任务状态收集有关的配置选项                                 */
/***************************************************************************************************************/
#define configGENERATE_RUN_TIME_STATS	        0                       //为1时启用运行时间统计功能
#define configUSE_TRACE_FACILITY				1                       //为1启用可视化跟踪调试
#define configUSE_STATS_FORMATTING_FUNCTIONS	1                       //与宏configUSE_TRACE_FACILITY同时为1时会编译下面3个函数
                                                                        //prvWriteNameToBuffer(),vTaskList(),
                                                                        //vTaskGetRunTimeStats()
                                                                        
/***************************************************************************************************************/
/*                                FreeRTOS与协程有关的配置选项                                                  */
/***************************************************************************************************************/
#define configUSE_CO_ROUTINES 			        0                       //为1时启用协程，启用协程以后必须添加文件croutine.c
#define configMAX_CO_ROUTINE_PRIORITIES         ( 2 )                   //协程的有效优先级数目

/***************************************************************************************************************/
/*                                FreeRTOS与软件定时器有关的配置选项                                            */
/***************************************************************************************************************/
#define configUSE_TIMERS				        1                               //为1时启用软件定时器
#define configTIMER_TASK_PRIORITY		        (configMAX_PRIORITIES-1)        //软件定时器优先级
#define configTIMER_QUEUE_LENGTH		        5                               //软件定时器队列长度
#define configTIMER_TASK_STACK_DEPTH	        (configMINIMAL_STACK_SIZE*2)    //软件定时器任务堆栈大小

/***************************************************************************************************************/
/*                                FreeRTOS可选函数配置选项                                                      */
/***************************************************************************************************************/
#define INCLUDE_xTaskGetSchedulerState          1                       
#define INCLUDE_vTaskPrioritySet		        1
#define INCLUDE_uxTaskPriorityGet		        1
#define INCLUDE_vTaskDelete				        1
#define INCLUDE_vTaskCleanUpResources	        1
#define INCLUDE_vTaskSuspend			        1
#define INCLUDE_vTaskDelayUntil			        1
#define INCLUDE_vTaskDelay				        1
#define INCLUDE_eTaskGetState			        1
#define INCLUDE_xTimerPendFunctionCall	        1

/***************************************************************************************************************/
/*                                FreeRTOS与中断有关的配置选项                                                  */
/***************************************************************************************************************/
#ifdef __NVIC_PRIO_BITS
	#define configPRIO_BITS       		__NVIC_PRIO_BITS
#else
	#define configPRIO_BITS       		4                  
#endif

#define configLIBRARY_LOWEST_INTERRUPT_PRIORITY			15                      //中断最低优先级
#define configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY	5                       //系统可管理的最高中断优先级
#define configKERNEL_INTERRUPT_PRIORITY 		( configLIBRARY_LOWEST_INTERRUPT_PRIORITY << (8 - configPRIO_BITS) )
#define configMAX_SYSCALL_INTERRUPT_PRIORITY 	( configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY << (8 - configPRIO_BITS) )

/***************************************************************************************************************/
/*                                FreeRTOS与中断服务函数有关的配置选项                                          */
/***************************************************************************************************************/
#define xPortPendSVHandler 	PendSV_Handler
#define vPortSVCHandler 	SVC_Handler

#endif /* FREERTOS_CONFIG_H */

二、解析

'‘INCLUDE_’'开始的宏

在这里插入图片描述
使用“INCLUDE_”开头的宏用来表示使能或除能 FreeRTOS 中相应的 API 函数，作用就是用来配置 FreeRTOS 中的可选 API 函数的。
比如当宏 INCLUDE_vTaskPrioritySet 设置为 0 的时候表示不能使用函数 vTaskPrioritySet() ，当设置为 1 的时候就表示可以使用函数。
在这里插入图片描述

'‘confi’'开始的宏

'‘confi’‘开始的宏和’‘INCLUDE’'开始的宏一样，都是用来完成 FreeRTOS 的配置和裁剪的。

1、configAPPLICATION_ALLOCATED_HEAP

默认情况下FreeRTOS 的堆内存是由编译器来分配的，将宏，configAPPLICATION_ALLOCATED_HEAP 定义为 1 的话堆内存可以由用户自行设置。
堆内存在 heap_1.c、heap_2.c、heap_3.c、heap_4.c 和 heap_5.c 中有定义，具体在哪个文件取决于用户的选择哪种内存管理方式。
在这里插入图片描述
上图可以看出当宏 configAPPLICATION_ALLOCATED_HEAP 定义为 1 的话需要用户自行堆内存 ucHeap，否则的话就是编译器来分配的。

2、configASSERT

断言，类似 C 标准库中的 assert()函数，调试代码的时候可以检查传入的参数是否合理， FreeRTOS 内核中的关键点都会调用 configASSERT(x)，当 x 为 0 的时候说明有错误发生，使用断言的话会导致开销加大，一般在调试阶段使用。configASSERT()需要在 FreeRTOSConfig.h 文件中定义，如下实例
在这里插入图片描述
注意，vAssertCalled()函数需要用户自行去定义，可以是显示到 LCD 上的函数，也可以是通过串口打印出来的函数。
当参数 x 错误的时候就通过串口打印出发生错误的文件名和错误所在的行号，调试代码的可以使用断言，当调试完成以后尽量去掉断言，防止增加开销！

3、configCHECK_FOR_STACK_OVERFLOW

设置堆栈溢出检测，每个任务都有一个任务堆栈，如果使用函数 xTaskCreat()创建一个任务的话那么这个任务的堆栈是自动从FreeRTOS的堆（ucHeap）中分配的，堆栈的大小是由函数 xTaskCreate() 的参数usStackDepth 来决定的。如果使用函数 xTaskCreateStatic() 创建任务的话任务堆栈是由用户设置的，参数 pxStackBuffer 为任务堆栈，一般是一个数组。

FreeRTOS提供了两种可选的机制来帮助检测和调试堆栈溢出。不管使用哪种机制都要设置宏 configCHECK_FOR_STACK_OVERFLOW。如果使能了堆栈检测功能的话，即宏 configCHECK_FOR_STACK_OVERFLOW 不为 0。
那么用户必须提供一个钩子函数（回调函数），当内核检测到堆栈溢出以后就会调用这个钩子函数，该函数原型如下：
在这里插入图片描述
参数 xTask 是任务句柄，pcTaskName 是任务名字，要注意的是堆栈溢出太严重的话可能会损毁这两个参数，如果发生这种情况的话可以直接查看变量 pxCurrentTCB 来确定哪个任务发生了堆栈溢出。有些处理器可能在堆栈溢出的时候生成一个 fault 中断来提示这种错误，另外，堆栈溢出检测会增加上下文切换的开销，建议在调试的时候使用。

堆栈溢出检测方法1:

configCHECK_FOR_STACK_OVERFLOW==1
检测原理：通过在任务切换时，检测栈顶指针和栈起始指针，或者帧顶指针和栈结束指针是否越界，如果越界，在任务切换的时候触发堆栈溢出钩子Hook函数。
方法一的优点就是快！但是缺点就是不能检测所有的堆栈溢出。比如任务执行中确实出现了栈顶指针越界的情况，但是在任务切换之前栈顶指针又指回到了合法位置，这个时候就检测不到栈溢出了。

堆栈溢出检测方法2:

configCHECK_FOR_STACK_OVERFLOW==2
检测原理：在任务创建时，将任务栈所有的数据初始化为一个固定值0xa5，通过任务切换的时候，来判断栈底16个或20个字节是否都为0xa5，如果被修改过，会触发堆栈溢出钩子Hook函数。
方法二比方法一要慢一些，但是对用户而言还是很快的！方法二能检测到几乎所有的堆栈溢出，但是也有一些情况检测不到，比如溢出值和标记值相同的时候。

任务创建时，configCHECK_FOR_STACK_OVERFLOW 宏的值为2。
则会将栈空间都填充成 0x5a (tskSTACK_FILL_BYTE宏)
在这里插入图片描述

判断栈溢出检测的时机：
当然是在任务进行切换的时候，即 vTaskSwitchContext(void) 函数中，该函数中调用了taskCHECK_FOR_STACK_OVERFLOW() 函数。
在这里插入图片描述

4、configCPU_CLOCK_HZ

设置 CPU 的频率。
在这里插入图片描述

5、configSUPPORT_DYNAMIC_ALLOCATION

定义为 1 的话在创建 FreeRTOS 的内核对象的时候所需要的RAM 就会从FreeRTOS 的堆中动态的获取内存，如果定义为 0 的话所需的 RAM 就需要用户自行提供，默认情况下宏 configSUPPORT_DYNAMIC_ALLOCATION 为 1。
在这里插入图片描述

6、configENABLE_BACKWARD_COMPATIBILITY

FreeRTOS.h 中由一些列的#define 宏定义，这些宏定义都是一些数据类型名字
在这里插入图片描述

7、configMAX_CO_ROUTINE_PRIORITIES

设置可以分配给协程的最大优先级，也就是协程的优先级数。设置号以后协程的优先级可以从 0 到 configMAX_CO_ROUTINE_PRIORITIES-1 ，其中 0 是最低的优先级， configMAX_CO_ROUTINE_PRIORITIES-1 为最高的优先级。
在这里插入图片描述

8、configMAX_PRIORITIES

设置任务的优先级数量，设置好以后任务就可以使用从0到configMAX_PRIORITIES-1的优先级，其中 0 是最低优先级，configMAX_PRIORITIES-1 是最高优先级。注意和 uC/OS 的区别，uC/OS 中 0 是最高优先级！
在这里插入图片描述

9、configMAX_TASK_NAME_LEN

设置任务名最大长度
在这里插入图片描述

10、configMINIMAL_STACK_SIZE

设置空闲任务的最小任务堆栈大小，以字为单位，不是字节。比如在STM32上设置为100的话，那么真正的堆栈大小就是 100*4=400字节。
在这里插入图片描述

11、configQUEUE_REGISTRY_SIZE

设置可以注册的队列和信号量的最大数量，在使用内核调试器查看信号量和队列的时候需要设置此宏。而且要先将消息队列和信号量进行注册，只有注册了的队列和信号量才会再内核调试器中看到，如果不使用内核调试器的话此宏设置为0即可。
在这里插入图片描述

12、configTICK_RATE_HZ

设置FreeRTOS的系统时钟节拍频率，单位是Hz，此频率就是滴答定时器的中断频率，需要使用此宏来配置滴答定时器的中断。为了兼容 ST最新的 HAL 库，我们将此宏设置为 1000，周期就是 1ms。
在这里插入图片描述

13、软件定时器相关

configTIMER_QUEUE_LENGTH
此宏用来设置这个软件定时器的命令队列长度
configTIMER_TASK_PRIORITY
设置软件定时器任务的任务优先级。
configTIMER_TASK_STACK_DEPTH
设置定时器服务任务的任务堆栈大小。

14、configTOTAL_HEAP_SIZE

设置堆大小，如果使用了动态内存管理的话，FreeRTOS 在创建任务、信号量、队列等的时候就会使用 heap_x.c(x 为 1~5) 中的内存申请函数来申请内存。这些内存就是从堆 ucHeap[configTOTAL_HEAP_SIZE]中申请的，堆的大小有 configTOTAL_HEAP_SIZE 决定。
在这里插入图片描述