Github地址

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

期待您的Star

本項(xiàng)目是2022年開源之夏，RT-Thread社區(qū)項(xiàng)目。已經(jīng)于2022年9月由唐照洲（美國(guó)佐治亞理工學(xué)院，大四）順利結(jié)項(xiàng)完成。FreeRTOS兼容層目前已經(jīng)落地到RT-Thread對(duì)ESP32-IDF（唐照洲）和core-v-mcu（王順）兩款SDK的兼容項(xiàng)目中。

1 概述

這是一個(gè)針對(duì)RT-Thread國(guó)產(chǎn)操作系統(tǒng)的FreeRTOS操作系統(tǒng)兼容層，可以讓原有基于FreeRTOS操作系統(tǒng)的項(xiàng)目快速、無(wú)感地遷移到RT-Thread操作系統(tǒng)上，實(shí)現(xiàn)在RT-Thread操作系統(tǒng)上無(wú)感的使用FreeRTOS的API，同時(shí)可以使用RT-Thread的豐富組件。項(xiàng)目基于FreeRTOS V10.4.6版本。

1.1 RT-Thread的其他RTOS兼容層

• RT-Thread操作系統(tǒng)的μCOS-III兼容層：https://github.com/mysterywolf/RT-Thread-wrapper-of-uCOS-III

• RT-Thread操作系統(tǒng)的μCOS-II兼容層：https://github.com/mysterywolf/RT-Thread-wrapper-of-uCOS-II

• RT-Thread操作系統(tǒng)的RTX(即CMSIS-RTOS1)兼容層：https://github.com/RT-Thread-packages/CMSIS_RTOS1

• RT-Thread操作系統(tǒng)的RTX5(即CMSIS-RTOS2)兼容層：https://github.com/RT-Thread-packages/CMSIS_RTOS2

• RT-Thread操作系統(tǒng)的Arduino生態(tài)兼容層：https://github.com/RTduino/RTduino

2 FreeRTOS的API支持情況及使用注意事項(xiàng)

API支持情況詳見，readme 鏈接如下：

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

（請(qǐng)復(fù)制至外部瀏覽器打開）

兼容層對(duì)FreeRTOS的支持情況記錄在issue中記錄。一些支持的函數(shù)在功能和使用方法上和FreeRTOS略有不同，在遷移過程中需要注意。

2.1線程、消息隊(duì)列與互斥量

2.1.1 vTaskSuspend

vTaskSuspend只支持掛起當(dāng)前運(yùn)行的線程，在使用時(shí)xTaskToSuspend參數(shù)必須為NULL。否則會(huì)觸發(fā)斷言。

2.1.2 xQueueSendToFront

xQueueSendToFront不支持設(shè)置超時(shí)，使用時(shí)xTicksToWait參數(shù)會(huì)被忽略，消息隊(duì)列沒有空間時(shí)會(huì)立即返回errQUEUE_FULL。

2.1.3 xQueueCreateStatic

靜態(tài)消息隊(duì)列需要參考以下的例子創(chuàng)建，確保為消息隊(duì)列分配的內(nèi)存足夠大：

 1#defineQUEUE_LENGTH10
 2#defineITEM_SIZEsizeof(uint32_t)
 3
 4/*以下是在原版FreeRTOS分配內(nèi)存的方法，由于RT-Thread消息隊(duì)列內(nèi)部的實(shí)現(xiàn)與FreeRTOS不同，這樣分配的內(nèi)存不夠存放ITEM_SIZE個(gè)消息*/
 5//uint8_tucQueueStorage[QUEUE_LENGTH*ITEM_SIZE];
 6/*要使用QUEUE_BUFFER_SIZE宏分配內(nèi)存*/
 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可以由同一個(gè)線程重復(fù)獲取，Mutex不可以。RT-Thread提供的互斥量是可以重復(fù)獲取的，因此兼容層也不對(duì)Mutex和Recursive Mutex做區(qū)分。

用xSemaphoreCreateMutex和xSemaphoreCreateRecursiveMutex創(chuàng)建的互斥量都是可以重復(fù)獲取的。

2.2 定時(shí)器

和FreeRTOS不同，RT-Thread不使用一個(gè)消息隊(duì)列向定時(shí)器線程傳遞命令。使用兼容層時(shí)任何需要設(shè)置超時(shí)的定時(shí)器函數(shù)，如xTimerStart( xTimer, xTicksToWait )，xTicksToWait參數(shù)會(huì)被忽略，函數(shù)會(huì)立即完成命令并返回。

2.3 FromISR函數(shù)

FreeRTOS為一些函數(shù)提供了在中斷中使用的FromISR版本，如果這些函數(shù)喚醒了更高優(yōu)先級(jí)的線程，需要手動(dòng)調(diào)度，如下所示：

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

RT-Thread不為函數(shù)提供FromISR版本，函數(shù)可以在中斷調(diào)用并在內(nèi)部完成調(diào)度。因此在兼容層中使用FromISR函數(shù)后不需要手動(dòng)調(diào)度，xHigherPriorityTaskWoken總會(huì)被設(shè)置成pdFALSE。

2.4 內(nèi)存堆

兼容層保留了FreeRTOS的五種內(nèi)存分配算法，默認(rèn)使用heap_3，pvPortMalloc/vPortFree內(nèi)部調(diào)用RT_KERNEL_MALLOC/RT_KERNEL_FREE在RT-Thread內(nèi)部的內(nèi)存堆分配。這種情況下內(nèi)存堆的大小由RT-Thread BSP配置決定，無(wú)法在FreeRTOSConfig.h中通過configTOTAL_HEAP_SIZE設(shè)置。若使用其他算法，需要修改FreeRTOS/sSConscript，選擇相應(yīng)的源文件

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設(shè)置內(nèi)存堆大小。應(yīng)用調(diào)用pvPortMalloc/vPortFree會(huì)在一塊獨(dú)立于RT-Thread，大小為configTOTAL_HEAP_SIZE的內(nèi)存堆中分配，RT-Thread內(nèi)部的內(nèi)存堆仍然存在，兼容層函數(shù)內(nèi)部分配內(nèi)存都在RT-Thread的內(nèi)存堆完成。

2.5 線程優(yōu)先級(jí)

RT-Threa線程優(yōu)先級(jí)數(shù)值越小時(shí)優(yōu)先級(jí)越高，而FreeRTOS線程優(yōu)先級(jí)數(shù)值越大優(yōu)先級(jí)越高。在使用兼容層的FreeRTOS API，如xTaskCreate，使用FreeRTOS的規(guī)則為線程指定優(yōu)先級(jí)即可。若在應(yīng)用中將RT-Thread和FreeRTOS API混合使用，在指定線程優(yōu)先級(jí)時(shí)要特別注意。可以使用以下兩個(gè)宏對(duì)RT-Thread和FreeRTOS線程優(yōu)先級(jí)做轉(zhuǎn)換：

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創(chuàng)建線程時(shí)一定要遵守FreeRTOS的規(guī)則，切勿混淆。

2.7 vTaskStartScheduler

由于RT-Thread和FreeRTOS的內(nèi)核啟動(dòng)流程不同，使用兼容層時(shí)，main函數(shù)是在一個(gè)線程中運(yùn)行，該線程優(yōu)先級(jí)為CONFIG_RT_MAIN_THREAD_PRIORITY。（此選項(xiàng)通過SCons配置，數(shù)值越小優(yōu)先級(jí)越高。），此時(shí)調(diào)度器已經(jīng)開啟。一般的FreeRTOS應(yīng)用采用以下的方式創(chuàng)建線程：

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

使用兼容層時(shí)，任何使用xTaskCreate創(chuàng)建的線程若優(yōu)先級(jí)比CONFIG_RT_MAIN_THREAD_PRIORITY更高，會(huì)立即開始執(zhí)行。vTaskStartScheduler只是為了提供對(duì)應(yīng)用的兼容，沒有任何實(shí)際效果。在使用兼容層時(shí)，創(chuàng)建線程要特別注意，確保在調(diào)用xTaskCreate時(shí)，該線程所需的所有資源已經(jīng)完成初始化，可以正常運(yùn)行。

3 使用方法

通過Env工具將兼容層加入到工程中：

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

使用scons --menuconfig配置RT-Thread內(nèi)核，以下選項(xiàng)會(huì)影響到FreeRTOS兼容層：

1RT_USING_TIMER_SOFT/*使用FreeRTOS定時(shí)器時(shí)必須開啟*/
2RT_TIMER_THREAD_PRIO/*定時(shí)器線程優(yōu)先級(jí)。與FreeRTOS相反，該選項(xiàng)數(shù)值越小優(yōu)先級(jí)越高*/
3RT_TIMER_THREAD_STACK_SIZE/*定時(shí)器線程棧大小，單位為sizeof(rt_uint8_t)*/
4RT_USING_MUTEX/*使用FreeRTOS互斥量時(shí)必須開啟*/
5RT_USING_SEMAPHORE/*使用FreeRTOS信號(hào)量時(shí)必須開啟*/
6RT_USING_HEAP/*使用FreeRTOS動(dòng)態(tài)內(nèi)存分配時(shí)必須開啟*/
7RT_TICK_PER_SECOND/*相當(dāng)于FreeRTOSconfigTICK_RATE_HZ*/
8RT_THREAD_PRIORITY_MAX/*相當(dāng)于FreeRTOSconfigMAX_PRIORITIES*/
9RT_NAME_MAX/*相當(dāng)于FreeRTOSconfigMAX_TASK_NAME_LEN*/

在FreeRTOS/portable/rt-thread提供了FreeRTOSConfig.h模版。大部分內(nèi)容不可以修改或依賴RT-Thread內(nèi)核的配置，可以手動(dòng)修改的內(nèi)容如下：

 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配置內(nèi)存堆大小*/
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/*可以選擇的函數(shù)和功能*/
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編譯并燒錄后，可以連接串口，輸入相應(yīng)的msh命令，觀察例程的執(zhí)行結(jié)果：

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

4 參考資料

RT-Thread文檔

https://www.rt-thread.org/document/site/#/rt-thread-version/rt-thread-standard/README

FreeRTOS文檔

https://www.freertos.org/a00106.html

Github地址

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

期待您的Star

———————End———————

你可以添加微信：rtthread2020 為好友，注明：公司+姓名，拉進(jìn)RT-Thread官方微信交流群！