目录

1. FreeRTOSConfig.h 文件

2. "INCLUDE_" 开始的宏

2.1 INCLUDE_xSemaphoreGetMutexHolder

2.2 INCLUDE_xTaskAbortDelay

2.3 INCLUDE_vTaskDelay

2.4 INCLUDE_vTaskDelayUntil

2.5 INCLUDE_vTaskDelete

2.6 INCLUDE_xTaskGetCurrentTaskHandle

2.7 INCLUDE_xTaskGetHandle

2.8 INCLUDE_xTaskGetIdleTaskHandle

2.9 INCLUDE_xTaskGetSchedulerState

2.10 INCLUDE_uxTaskGetStackHighWaterMark

2.11 INCLUDE_uxTaskPriorityGet

2.12 INCLUDE_vTaskPrioritySet

2.13 INCLUDE_xTaskResumeFromISR

2.14 INCLUDE_eTaskGetState

2.15 INCLUDE_vTaskSuspend

2.16 INCLUDE_xTimerPendFunctionCall

3. "config" 开始的宏

3.1 configAPPLICATION_ALLOCATED_HEAP

3.2 configASSERT

3.3 configCHECK_FOR_STACK_OVERFLOW

3.4 configCPU_CLOCK_HZ

3.5 configSUPPORT_DYNAMIC_ALLOCATION

3.6 configENABLE_BACKWARD_COMPATIBILITY

3.7 configGENERATE_RUN_TIME_STATS

3.8 configIDLE_SHOULD_YIELD

3.9 configKERNEL_INTERRUPT_PRIORITY、configMAX_SYSCALL_INTERRUPT_PRIORITY、configMAX_API_CALL_INTERRUPT_PRIORITY

3.10 configMAX_CO_ROUTINE_PRIORITIES

3.11 configMAX_PRIORITIES

3.12 configMAX_TASK_NAME_LEN

3.13 configMINIMAL_STACK_SIZE

3.14 configNUM_THREAD_LOCAL_STORAGE_POINTERS        

3.15 configQUEUE_REGISTRY_SIZE

3.16 configSUPPORT_STATIC_ALLOCATION

3.17 configTICK_RATE_HZ

3.18 configTIMER_QUEUE_LENGTH

3.19 configTIMER_TASK_PRIORITY

3.20 configTIMER_TASK_STACK_DEPTH

3.21 configTOTAL_HEAP_SIZE

3.22 configUSE_16_BIT_TICKS

3.23 configUSE_APPLICATION_TASK_TAG

3.24 configUSE_CO_ROUTINES

3.25 configUSE_COUNTING_SEMAPHORES

3.26 configUSE_DAEMON_TASK_STARTUP_HOOK

3.27 configUSE_IDLE_HOOK

3.28 configUSE_MALLOC_FAILED_HOOK

3.29 configUSE_MUTEXES

3.30 configUSE_PORT_OPTIMISED_TASK_SELECTION

3.31 configUSE_PREEMPTION

3.32 configUSE_QUEUE_SETS

3.33 configUSE_RECURSIVE_MUTEXES

3.34 configUSE_STATS_FORMATTING_FUNCTIONS

3.35 configUSE_TASK_NOTIFICATIONS

3.36 configUSE_TICK_HOOK

3.37 configUSE_TICKLESS_IDLE

3.38 configUSE_TIMERS

3.39 configUSE_TIME_SLICING

3.40 configUSE_TRACE_FACILITY

---

        在实际使用 FreeRTOS 的时候我们时常需要根据自己的需求来配置 FreeRTOS，而且不同架构的 MCU 在使用的时候配置也不同。正点原子的 FreeRTOS 的系统配置文件为 FreeRTOSConfig.h，在此配置文件中可以完成 FreeRTOS 的裁剪和配置。

1. FreeRTOSConfig.h 文件

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

2. "INCLUDE_" 开始的宏

        使用 "INCLUDE_" 开头的宏来表示使能或除能 FreeRTOS 中相应的 API 函数，作用就是用来配置 FreeRTOS 中的可选 API函数 的；比如说当宏 INCLUDE_vTaskPrioritySet 设置为 0 的时候表示不能使用函数 vTaskPrioritySet()，当设置为 1 的时候就表示可以使用函数 vTaskPrioritySet()。这个功能其实就是条件编译：

        从上图可以看出：INCLUDE_vTaskPrioritySet == 1 的时候，函数 vTaskPrioritySet() 才会被编译，注意，这里为了缩小篇幅将函数 vTaskPrioritySet() 的内容进行了折叠。FreeRTOS 中的裁剪和配置就是这种用条件编译的方法来实现的，不止是 FreeRTOS 这么干，很多的协议栈、RTOS系统和 GUI 库等都是使用条件编译的方法来完成配置和裁剪的。条件编译的好处就是节省空间，不需要的功能就不用编译，这样就可以根据实际需求来减少系统占用的 ROM 和 RAM 大小，根据自己所使用的 MCU 来调整系统消耗，降低成本。

什么是 API ？

        API 全称为 Application Programming Interface（应用程序编程接口）：是一套明确定义的各种软件组件之间的通信方法。

举个例子来看什么是 API？

有两个软件甲和乙，软件甲是已经开发测试完成的，软件乙是正在开发测试的，软件乙的某一部分功能想要调用软件甲来实现，但是又不想从头看一遍软件甲的源码，这个时候软件甲的工程师把软件乙想要调用的功能封装成一个函数；软件乙只需要把工程师封装好的这个函数放在软件乙里即可，就能直接用软件甲的功能了。

其中，API 就是软件甲说的那个封装好的函数。

更加通俗一点的说：就是别人写好的代码，或者编译好的程序，提供给你用，就叫做 API。

下面来看看 "INCLUDE_" 开始的都有哪些宏，它们的功能都是什么。

2.1 INCLUDE_xSemaphoreGetMutexHolder

如果要使用函数 xQueueGetMutexHolder()的话宏 INCLUDE_xSemaphoreGetMutexHolder 必须定义为 1 。

2.2 INCLUDE_xTaskAbortDelay

如果要使用函数 xTaskAbortDelay()的话将宏 INCLUDE_xTaskAbortDelay 定义为 1。

2.3 INCLUDE_vTaskDelay

如果要使用函数 vTaskDelay()的话需要将宏 INCLUDE_vTaskDelay 定义为 1。

2.4 INCLUDE_vTaskDelayUntil

如果要使用函数 vTaskDelayUntil()的话需要将宏 INCLUDE_vTaskDelayUntil 定义为 1。

2.5 INCLUDE_vTaskDelete

如果要使用函数 vTaskDelete()的话需要将宏 INCLUDE_vTaskDelete 定义为 1。

2.6 INCLUDE_xTaskGetCurrentTaskHandle

如果要使用函数 xTaskGetCurentTaskHandle() 的 话 需 要 将 宏INCLUDE_xTaskGetCurrentTaskHandle 定义为 1。

2.7 INCLUDE_xTaskGetHandle

如果要使用函数 xTaskGetHandle()的话需要将宏 INCLUDE_xTaskGetHandle 定义为 1。

2.8 INCLUDE_xTaskGetIdleTaskHandle

如果要使用函数 xTaskGetIdleTaskHandle() 的 话 需 要 将 宏INCLUDE_xTaskGetIdleTaskHandle 定义为 1。

2.9 INCLUDE_xTaskGetSchedulerState

如果要使用函数 xTaskGetSchedulerState()的话需要将宏 INCLUDE_xTaskGetSchedulerState 定义为 1。

2.10 INCLUDE_uxTaskGetStackHighWaterMark

如果要使用函数 uxTaskGetStackHighWaterMark() 的 话 需 要 将 宏INCLUDE_uxTaskGetStackHighWaterMark 定义为 1。

2.11 INCLUDE_uxTaskPriorityGet

如果要使用函数 uxTaskPriorityGet()的话需要将宏 INCLUDE_uxTaskPriorityGet 定义为 1。

2.12 INCLUDE_vTaskPrioritySet

如果要使用函数 vTaskPrioritySet()的话需要将宏 INCLUDE_vTaskPrioritySet 定义为 1。

2.13 INCLUDE_xTaskResumeFromISR

如果要使用函数 xTaskResumeFromISR()的话需要将宏 INCLUDE_xTaskResumeFromISR 和 INCLUDE_vTaskSuspend 都定义为 1。

2.14 INCLUDE_eTaskGetState

如果要使用函数 eTaskGetState()的话需要将宏 INCLUDE_eTaskGetState 定义为 1。

2.15 INCLUDE_vTaskSuspend

如果要使用函数 vTaskSuspend() 、 vTaskResume() 、 prvTaskIsTaskSuspended() 、xTaskResumeFromISR()的话宏 INCLUDE_vTaskSuspend 要定义为 1。

如果要使用函数 xTaskResumeFromISR() 的 话 宏 INCLUDE_xTaskResumeFromISR 和 INCLUDE_vTaskSuspend 都必须定义为 1。

2.16 INCLUDE_xTimerPendFunctionCall

如果要使用函数 xTimerPendFunctionCall()和 xTimerPendFunctionCallFromISR() 的话宏 INCLUDE_xTimerPendFunctionCall 和 configUSE_TIMERS 都必须定义为 1。

3. "config" 开始的宏

        "config" 开始的宏和 "INCLUDE_" 开始的宏一样，都是用来完成 FreeRTOS 的配置和裁剪的，接下来我们就看一下这些 "config" 开始的宏。

3.1 configAPPLICATION_ALLOCATED_HEAP

        默认情况下，FreeRTOS 的堆内存是由编译器来分配的，将宏 configAPPLICATION_ALLOCATED_HEAP 定义为 1 的话堆内存可以由用户自行设置，堆内存在 heap_1.c、heap_2.c、heap_3.c、heap_4.c 和 heap_5.c 中有定义，具体在哪个文件取决于用户选择哪种内存管理方式。

/* Allocate the memory for the heap. */
#if( configAPPLICATION_ALLOCATED_HEAP == 1 )
	/* The application writer has already defined the array used for the RTOS
	heap - probably so it can be placed in a special segment or address. */
	extern uint8_t ucHeap[ configTOTAL_HEAP_SIZE ];
#else
	static uint8_t ucHeap[ configTOTAL_HEAP_SIZE ];
#endif /* configAPPLICATION_ALLOCATED_HEAP */

/* Define the linked list structure.  This is used to link free blocks in order
of their memory address. */

        当宏 configAPPLICATION_ALLOCATED_HEAP 定义为 1 时，需要用户自行堆内存 ucHeap，否则的话就是编译器来分配的。

3.2 configASSERT

        断言，类似于 C 标准库中的 assert() 函数，调试代码的时候可以检查传入的参数是否合理，FreeRTOS 内核中的关键点都会调用 configASSERT(x)，当 x 为 0 的时候说明有错误发生，使用断言的话会导致开销加大，一般在调试阶段使用。configASSERT() 需要在 FreeRTOSConfig.h 文件中定义，

#define configASSERT((x)) if((x)==0) vAssertCalled(__FILE_,__LINE__);

        注意：vAssertCalled() 函数需要用户自行去定义，可以是显示到 LCD 上的函数，也可以是通过串口打印出来的函数，本教程的所有例程采用如下的定义：

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

        当参数 x 错误的时候就通过串口打印出发生错误的文件名和错误所在的行号，调试代码可以使用断言，当调试完成以后尽量去掉断言，防止增加开销！

3.3 configCHECK_FOR_STACK_OVERFLOW

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

        堆栈溢出是导致应用程序不稳定的主要因素，FreeRTOS 提供了两种可选的机制来帮助检测和调试堆栈溢出，不管使用哪种机制都要设置宏 configCHECK_FOR_STACK_OVERFLOW。如果使能了堆栈检测功能的话，即宏 configCHECK_FOR_STACK_OVERFLOW 不为 0，那么用户必须提供一个钩子函数（回调函数），当内核检测到堆栈溢出以后就会调用这个钩子函数，

void vApplicationStackOverflowHook( TaskHandle_t xTask, 
                                    char * pcTaskName );

        参数 xTask 是任务句柄，pcTaskName 是任务名字，要注意的是堆栈溢出太严重的话可能会 损毁这两个参数，如果发生这种情况的话可以直接查看变量 pxCurrentTCB 来确定哪个任务发 生了堆栈溢出。有些处理器可能在堆栈溢出的时候生成一个 fault 中断来提示这种错误，另外， 堆栈溢出检测会增加上下文切换的开销，建议在调试的时候使用。

        configCHECK_FOR_STACK_OVERFLOW==1，使用堆栈溢出检测方法 1。

        上下文切换的时候需要保存现场，现场是保存在堆栈中的，这个时候任务堆栈使用率很可 能达到最大值，方法一就是不断的检测任务堆栈指针是否指向有效空间，如果指向了无效空间 的话就会调用钩子函数。方法一的优点就是快！但是缺点就是不能检测所有的堆栈溢出。         

        configCHECK_FOR_STACK_OVERFLOW==2，使用堆栈溢出检测方法 2。

        使用方法二的话在创建任务的时候会向任务堆栈填充一个已知的标记值，方法二会一直检 测堆栈后面的几个 bytes(标记值)是否被改写，如果被改写的话就会调用堆栈溢出钩子函数，方 法二也会使用方法一中的机制！方法二比方法一要慢一些，但是对用户而言还是很快的！方法 二能检测到几乎所有的堆栈溢出，但是也有一些情况检测不到，比如溢出值和标记值相同的时 候。

3.4 configCPU_CLOCK_HZ

        设置 CPU 的频率。

3.5 configSUPPORT_DYNAMIC_ALLOCATION

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

configSUPPORT_DYNAMIC_ALLOCATION 为 1。

3.6 configENABLE_BACKWARD_COMPATIBILITY

        FreeRTOS.h 中由一些列的 #define 宏定义，这些宏定义都是一些数据类型名字，

        默认情况下宏 configENABLE_BACKWARD_COMPATIBILITY 为 1。

3.7 configGENERATE_RUN_TIME_STATS

        设置为 1 开启时间统计功能，相应的 API 函数会被编译，为 0 时关闭时间统计功能。如果宏 configGENERATE_RUN_TIME_STATS 为 1 的话还需要定义以下两个宏。

portCONFIGURE_TIMER_FOR_RUN_TIME_STATS()
//此宏用来初始化一个外设来作为时钟统计的基准时钟

portGET_RUN_TIME_COUNTER_VALUE() 或
portALT_GET_RUN_TIME_COUNTER_VALUE(Time)
//此宏用来返回当前基准时钟的时钟值

3.8 configIDLE_SHOULD_YIELD

        此宏定义了与空闲任务 (idle Task) 处于同等优先级的其他用户任务的行为，当为 0 的时候空闲任务不会为其他处于同优先级的任务让出 CPU 使用权。当为 1 的时候空闲任务就会为处于同等优先级的用户任务让出 CPU 使用权，除非没有就绪的用户任务，这样花费在空闲任务上的时间就会很少，但是这种方法也带了副作用。

        上图中有三个用户任务：A、B、C，还有一个空闲任务 I ，用户任务和空闲任务处于同一优先级，任务切换发生在 T0~T7 时刻。T0~T1 之间的时间为一个时间片，从图中可以看出一 开始任务 B、C 都执行了一个完成的时间片，在 T2 时刻空闲任务 I 开始执行，I 任务运行了一段时间以后被 A 任务抢走了 CPU 使用权，A 任务运行到 T3 时刻发生任务切换，B 任务开始运行。可以看出其实任务 I 和任务 A 一起使用了一个时间片，所以任务 A 运行的时间就比其他任务少！

3.9 configKERNEL_INTERRUPT_PRIORITY、configMAX_SYSCALL_INTERRUPT_PRIORITY、configMAX_API_CALL_INTERRUPT_PRIORITY

        configKERNEL_INTERRUPT_PRIORITY、configMAX_SYSCALL_INTERRUPT_PRIORITY、configMAX_API_CALL_INTERRUPT_PRIORITY

        这三个宏和 FreeRTOS 的中断配置有关；

3.10 configMAX_CO_ROUTINE_PRIORITIES

        设置可以分配给协程的最大优先级，也就是协程的优先级数。设置好以后协程的优先级可以从 0 到 configMAX_CO_ROUTINE_PRIORITIES - 1，其中 0 是最低的优先级，configMAX_CO_ROUTINE_PRIORITIES - 1 为最高的优先级。

3.11 configMAX_PRIORITIES

        设置任务的优先级数量，设置好以后任务就可以使用从 0 到 configMAX_PRIORITIES - 1 的优先级，其中 0 是最低优先级，configMAX_PRIORITIES - 1 是最高优先级。注意：和 UCOS 的区别，UCOS 中 0 是最高优先级！

3.12 configMAX_TASK_NAME_LEN

        设置任务名的最大长度。

3.13 configMINIMAL_STACK_SIZE

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

3.14 configNUM_THREAD_LOCAL_STORAGE_POINTERS        

        设置每个任务的本地存储指针数组大小，任务控制块中有本地存储数组指针，用户应用程序可以在这些本地存储中存入一些数据。

3.15 configQUEUE_REGISTRY_SIZE

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

3.16 configSUPPORT_STATIC_ALLOCATION

        当此宏定义为 1 ，在创建一些内核对象的时候需要用户指定的 RAM，当为 0 的时候就会自己使用 heap.c 中的动态内存管理函数来自动的申请 RAM。

3.17 configTICK_RATE_HZ

        设置 FreeRTOS 的系统时钟节拍频率，单位为 HZ ，此频率就是滴答定时器的中断频率，需要使用此宏来配置滴答定时器的中断。本教程中我们将此宏设置为 1000 ，周期就是 1ms。

3.18 configTIMER_QUEUE_LENGTH

        此宏是配置 FreeRTOS 软件定时器的，FreeRTOS 的软件定时器 API 函数会通过命令队列向软件定时器任务发送消息，此宏用来设置这个软件定时器的命令队列长度。

3.19 configTIMER_TASK_PRIORITY

        设置软件定时器任务的任务优先级。

3.20 configTIMER_TASK_STACK_DEPTH

        设置定时器服务任务的任务堆栈大小。

3.21 configTOTAL_HEAP_SIZE

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

3.22 configUSE_16_BIT_TICKS

        设置系统节拍计数器变量数据类型，系统节拍计数器变量类型为 TickType_t，当 configUSE_16_BIT_TICK 为 1 的时候 TickType_t 就是 16 位的，当 configUSE_16_BIT_TICKS 为 0 的话 TickType_t 就是 32 位的。

3.23 configUSE_APPLICATION_TASK_TAG

        此宏设置为 1 的话函数 configUSE_APPLICATION_TASK_TAGF() 和 xTaskCallApplicationTaskHook() 就会被编译。

3.24 configUSE_CO_ROUTINES

        此宏为 1 的时候启动协程，协程可以节省开销，但是功能有限。

3.25 configUSE_COUNTING_SEMAPHORES

        设置为 1 的时候启用计数型信号量，相关的 API 函数会被编译。

3.26 configUSE_DAEMON_TASK_STARTUP_HOOK

        当宏 configUSE_TIMERS 和 configUSE_DAEMON_TASK_STARTUP_HOOK 都为 1 的时需要定义函数 vApplicationDaemonTaskStartupHook()，函数原型如下：

void vApplicationDaemonTaskStartupHook(void);

3.27 configUSE_IDLE_HOOK

        为 1 时使用空闲任务钩子函数，用户需要实现空闲任务钩子函数，函数的原型如下：

void vApplicationIdleHook(void);

3.28 configUSE_MALLOC_FAILED_HOOK

        为 1 时使用内存分配失败钩子函数，用户需要实现内存分配失败钩子函数，函数原型如下：

void vApplicationMallocFailedHook(void);

3.29 configUSE_MUTEXES

        为 1 时使用互斥信号量，相关的 API 函数会被编译。

3.30 configUSE_PORT_OPTIMISED_TASK_SELECTION

        FreeRTOS 有两种方法来选择下一个要运行的任务，一个是通用的方法，另外一个是特殊的方法，也就是硬件方法，使用 MCU 自带的硬件指令来实现。

通用方法：

        当宏 configUSE_PORT_OPTIMISED_TASK_SELECTION 为0，或者硬件不支持的时候。

        希望所有硬件通用的时候。

        全部用 C 语言来实现，但是效率比特殊方法低。

        不限制最大优先级数目的时候。

特殊方法：

        不是所有的硬件都支持。

        当宏 configUSE_PORT_OPTIMISED_TASK_SELECTION 为 1 的时候。

        硬件拥有特殊的指令，比如计算前导零（CLZ）指令。

        比通用方法效率高。

        会限制优先级数目，一般是 32 个。

3.31 configUSE_PREEMPTION

        为 1 时使用抢占式调度器，为 0 时使用协程。如果使用抢占式调度器的话内核会在每个时钟节拍中断中进行任务切换，当使用协程的话会在如下地方进行任务切换：

•         一个任务调用了函数 taskYIELD()。
•         一个任务调用了可以使任务进入阻塞态的 API 函数。
•         应用程序明确定义了在中断中执行上下文切换。

3.32 configUSE_QUEUE_SETS

        为 1 时启用队列集功能。

3.33 configUSE_RECURSIVE_MUTEXES

        为 1 时使用递归互斥信号量，相关的 API 函数会被编译。

3.34 configUSE_STATS_FORMATTING_FUNCTIONS

        宏 configUSE_TRACE_FACILITY 和 configUSE_STATS_FORMATTING_FUNCTIONS 都为 1 的时候函数 vTaskList() 和 vTaskGetRunTimeStats() 会被编译。

3.35 configUSE_TASK_NOTIFICATIONS

        为 1 的时候使用任务通知功能，相关的 API 函数会被编译，开启了此功能的话每个任务会多消耗 8 个字节。

3.36 configUSE_TICK_HOOK

        为 1 时使能时间片钩子函数，用户需要实现时间片钩子函数，函数的原型如下：

void vApplicationTickHook(void)；

3.37 configUSE_TICKLESS_IDLE

        为 1 时使能低功耗 tickless 模式。

3.38 configUSE_TIMERS

        为 1 时使用软件定时器，相关的 API 函数会被编译，当宏 configUSE_TIMERS 为 1 的话，那么宏 configTIMER_TASK_PRIORITY、configTIMER_QUEUE_LENGTH 和 configTIMER_TASK_STACK_DEPTH 必须定义。

3.39 configUSE_TIME_SLICING

        默认情况下，FreeRTOS 使用抢占式调度器，这意味着调度器永远都在执行已经就绪了的最高优先级任务，优先级相同的任务在时钟节拍中断中进行切换，当宏 configUSE_TIME_SLICING 为 0 的时候不会在时钟节拍中断中执行相同优先级任务的任务切换，默认情况下宏 configUSE_TIME_SLICING 为1。

3.40 configUSE_TRACE_FACILITY

         为 1 启用可视化跟踪调试，会增加一些结构体成员和 API 函数。