RT-Thread操作系统的FreeRTOS兼容层-电子发烧友网

Github地址

https://github.com/RT-Thread-packages/FreeRTOS-Wrapper

期待您的Star

本项目是2022年开源之夏，RT-Thread社区项目。已经于2022年9月由唐照洲（美国佐治亚理工学院，大四）顺利结项完成。FreeRTOS兼容层目前已经落地到RT-Thread对ESP32-IDF（唐照洲）和core-v-mcu（王顺）两款SDK的兼容项目中。

1 概述

这是一个针对RT-Thread国产操作系统的FreeRTOS操作系统兼容层，可以让原有基于FreeRTOS操作系统的项目快速、无感地迁移到RT-Thread操作系统上，实现在RT-Thread操作系统上无感的使用FreeRTOS的API，同时可以使用RT-Thread的丰富组件。项目基于FreeRTOS V10.4.6版本。

1.1 RT-Thread的其他RTOS兼容层

RT-Thread操作系统的μCOS-III兼容层：https://github.com/mysterywolf/RT-Thread-wrapper-of-uCOS-III
RT-Thread操作系统的μCOS-II兼容层：https://github.com/mysterywolf/RT-Thread-wrapper-of-uCOS-II
RT-Thread操作系统的RTX(即CMSIS-RTOS1)兼容层：https://github.com/RT-Thread-packages/CMSIS_RTOS1
RT-Thread操作系统的RTX5(即CMSIS-RTOS2)兼容层：https://github.com/RT-Thread-packages/CMSIS_RTOS2
RT-Thread操作系统的Arduino生态兼容层：https://github.com/RTduino/RTduino

2 FreeRTOS的API支持情况及使用注意事项

API支持情况详见，readme 链接如下：

https://github.com/RT-Thread-packages/FreeRTOS-Wrapper

（请复制至外部浏览器打开）

兼容层对FreeRTOS的支持情况记录在issue中记录。一些支持的函数在功能和使用方法上和FreeRTOS略有不同，在迁移过程中需要注意。

2.1线程、消息队列与互斥量

2.1.1 vTaskSuspend

vTaskSuspend只支持挂起当前运行的线程，在使用时xTaskToSuspend参数必须为NULL。否则会触发断言。

2.1.2 xQueueSendToFront

xQueueSendToFront不支持设置超时，使用时xTicksToWait参数会被忽略，消息队列没有空间时会立即返回errQUEUE_FULL。

2.1.3 xQueueCreateStatic

静态消息队列需要参考以下的例子创建，确保为消息队列分配的内存足够大：

 1#defineQUEUE_LENGTH10
 2#defineITEM_SIZEsizeof(uint32_t)
 3
 4/*以下是在原版FreeRTOS分配内存的方法，由于RT-Thread消息队列内部的实现与FreeRTOS不同，这样分配的内存不够存放ITEM_SIZE个消息*/
 5//uint8_tucQueueStorage[QUEUE_LENGTH*ITEM_SIZE];
 6/*要使用QUEUE_BUFFER_SIZE宏分配内存*/
 7uint8_tucQueueStorage[QUEUE_BUFFER_SIZE(QUEUE_LENGTH,ITEM_SIZE)];
 8StaticQueue_txQueueBuffer;
 9QueueHandle_txQueue1;
10xQueue1=xQueueCreate(QUEUE_LENGTH,ITEM_SIZE,&(ucQueueStorage[0]),&xQueueBuffer);

2.1.4 Mutex和Recursive Mutex

FreeRTOS提供了两种互斥量，Mutex和Recursive Mutex。Recursive Mutex可以由同一个线程重复获取，Mutex不可以。RT-Thread提供的互斥量是可以重复获取的，因此兼容层也不对Mutex和Recursive Mutex做区分。

用xSemaphoreCreateMutex和xSemaphoreCreateRecursiveMutex创建的互斥量都是可以重复获取的。

2.2 定时器

和FreeRTOS不同，RT-Thread不使用一个消息队列向定时器线程传递命令。使用兼容层时任何需要设置超时的定时器函数，如xTimerStart( xTimer, xTicksToWait )，xTicksToWait参数会被忽略，函数会立即完成命令并返回。

2.3 FromISR函数

FreeRTOS为一些函数提供了在中断中使用的FromISR版本，如果这些函数唤醒了更高优先级的线程，需要手动调度，如下所示：

1BaseType_txHigherPrioritTaskWoken=pdFALSE;
2xQueueSendToFrontFromISR(xRxQueue,&cIn,&xHigherPriorityTaskWoken);
3if(xHigherPriorityTaskWoken)
4{
5taskYIELD();
6}

RT-Thread不为函数提供FromISR版本，函数可以在中断调用并在内部完成调度。因此在兼容层中使用FromISR函数后不需要手动调度，xHigherPriorityTaskWoken总会被设置成pdFALSE。

2.4 内存堆

兼容层保留了FreeRTOS的五种内存分配算法，默认使用heap_3，pvPortMalloc/vPortFree内部调用RT_KERNEL_MALLOC/RT_KERNEL_FREE在RT-Thread内部的内存堆分配。这种情况下内存堆的大小由RT-Thread BSP配置决定，无法在FreeRTOSConfig.h中通过configTOTAL_HEAP_SIZE设置。若使用其他算法，需要修改FreeRTOS/sSConscript，选择相应的源文件

1#可将heap_3.c替换成heap_1.c等
2src+=Glob(os.path.join("portable","MemMang","heap_3.c"))

在FreeRTOS/portable/rt-thread/FreeRTOSConfig.h中通过configTOTAL_HEAP_SIZE设置内存堆大小。应用调用pvPortMalloc/vPortFree会在一块独立于RT-Thread，大小为configTOTAL_HEAP_SIZE的内存堆中分配，RT-Thread内部的内存堆仍然存在，兼容层函数内部分配内存都在RT-Thread的内存堆完成。

2.5 线程优先级

RT-Threa线程优先级数值越小时优先级越高，而FreeRTOS线程优先级数值越大优先级越高。在使用兼容层的FreeRTOS API，如xTaskCreate，使用FreeRTOS的规则为线程指定优先级即可。若在应用中将RT-Thread和FreeRTOS API混合使用，在指定线程优先级时要特别注意。可以使用以下两个宏对RT-Thread和FreeRTOS线程优先级做转换：

1#defineFREERTOS_PRIORITY_TO_RTTHREAD(priority)(configMAX_PRIORITIES-1-(priority))
2#defineRTTHREAD_PRIORITY_TO_FREERTOS(priority)(RT_THREAD_PRIORITY_MAX-1-(priority))

2.6 线程堆栈大小

FreeRTOS线程堆栈大小的单位为sizeof(StackType_t)，RT-Thread线程堆栈大小为sizeof(rt_uint8_t)。使用FreeRTOS API创建线程时一定要遵守FreeRTOS的规则，切勿混淆。

2.7 vTaskStartScheduler

由于RT-Thread和FreeRTOS的内核启动流程不同，使用兼容层时，main函数是在一个线程中运行，该线程优先级为CONFIG_RT_MAIN_THREAD_PRIORITY。（此选项通过SCons配置，数值越小优先级越高。），此时调度器已经开启。一般的FreeRTOS应用采用以下的方式创建线程：

1xTaskCreate(pxTask1Code,......);
2xTaskCreate(pxTask2Code,......);
3......
4vTaskStartScheduler();

使用兼容层时，任何使用xTaskCreate创建的线程若优先级比CONFIG_RT_MAIN_THREAD_PRIORITY更高，会立即开始执行。vTaskStartScheduler只是为了提供对应用的兼容，没有任何实际效果。在使用兼容层时，创建线程要特别注意，确保在调用xTaskCreate时，该线程所需的所有资源已经完成初始化，可以正常运行。

3 使用方法

通过Env工具将兼容层加入到工程中：

1RT-Threadonlinepackages
2systempackages--->
3[*]FreeRTOSWrapper--->
4Version(latest)

使用scons --menuconfig配置RT-Thread内核，以下选项会影响到FreeRTOS兼容层：

1RT_USING_TIMER_SOFT/*使用FreeRTOS定时器时必须开启*/
2RT_TIMER_THREAD_PRIO/*定时器线程优先级。与FreeRTOS相反，该选项数值越小优先级越高*/
3RT_TIMER_THREAD_STACK_SIZE/*定时器线程栈大小，单位为sizeof(rt_uint8_t)*/
4RT_USING_MUTEX/*使用FreeRTOS互斥量时必须开启*/
5RT_USING_SEMAPHORE/*使用FreeRTOS信号量时必须开启*/
6RT_USING_HEAP/*使用FreeRTOS动态内存分配时必须开启*/
7RT_TICK_PER_SECOND/*相当于FreeRTOSconfigTICK_RATE_HZ*/
8RT_THREAD_PRIORITY_MAX/*相当于FreeRTOSconfigMAX_PRIORITIES*/
9RT_NAME_MAX/*相当于FreeRTOSconfigMAX_TASK_NAME_LEN*/

在FreeRTOS/portable/rt-thread提供了FreeRTOSConfig.h模版。大部分内容不可以修改或依赖RT-Thread内核的配置，可以手动修改的内容如下：

 1/*可以选择不使用recursivemutex*/
 2#ifdefRT_USING_MUTEX
 3#defineconfigUSE_RECURSIVE_MUTEXES1
 4#defineconfigUSE_MUTEXES1
 5#endif
 6
 7/*可以选择不使用countingsemaphore*/
 8#ifdefRT_USING_SEMAPHORE
 9#defineconfigUSE_COUNTING_SEMAPHORES1
10#endif
11
12/*若不使用heap_3，可以通过configTOTAL_HEAP_SIZE配置内存堆大小*/
13#defineconfigSUPPORT_STATIC_ALLOCATION1
14#ifdefRT_USING_HEAP
15#defineconfigSUPPORT_DYNAMIC_ALLOCATION1
16#defineconfigTOTAL_HEAP_SIZE10240
17#defineconfigAPPLICATION_ALLOCATED_HEAP0
18#endif
19
20#defineconfigMINIMAL_STACK_SIZE128
21
22/*可以选择的函数和功能*/
23#defineINCLUDE_vTaskPrioritySet1
24#defineINCLUDE_uxTaskPriorityGet1
25#defineINCLUDE_vTaskDelete1
26#defineINCLUDE_vTaskSuspend1
27#defineINCLUDE_xTaskDelayUntil1
28#defineINCLUDE_vTaskDelay1
29#defineINCLUDE_xTaskGetIdleTaskHandle1
30#defineINCLUDE_xTaskAbortDelay1
31#defineINCLUDE_xSemaphoreGetMutexHolder1
32#defineINCLUDE_xTaskGetHandle1
33#defineINCLUDE_uxTaskGetStackHighWaterMark1
34#defineINCLUDE_uxTaskGetStackHighWaterMark21
35#defineINCLUDE_eTaskGetState1
36#defineINCLUDE_xTaskResumeFromISR1
37#defineINCLUDE_xTaskGetSchedulerState1
38#defineINCLUDE_xTaskGetCurrentTaskHandle1
39#defineconfigUSE_APPLICATION_TASK_TAG1
40#defineconfigUSE_TASK_NOTIFICATIONS1
41#defineconfigTASK_NOTIFICATION_ARRAY_ENTRIES3

在test目录下提供了一些例程，可以将它们加入BSP目录下的applications文件夹中。使用SCons编译并烧录后，可以连接串口，输入相应的msh命令，观察例程的执行结果：

 1msh/>queue_dynamic
 2Task1receivedata0fromqueue
 3Task1receivedata1fromqueue
 4Task1receivedata2fromqueue
 5Task1receivedata3fromqueue
 6Task1receivedata4fromqueue
 7Task1receivedata5fromqueue
 8Task1receivedata6fromqueue
 9Task1receivedata7fromqueue
10Task1receivedata8fromqueue
11Task1receivedata9fromqueue
12Task1receivedata10fromqueue