Skip to content

Latest commit

 

History

History
344 lines (306 loc) · 20.7 KB

readme_zh.md

File metadata and controls

344 lines (306 loc) · 20.7 KB
Raw

RT-Thread操作系统的FreeRTOS兼容层

FreeRTOS Application Compatibility Layer (ACL) for RT-Thread

让基于FreeRTOS开发的应用层无感地迁移到RT-Thread操作系统

中文 | English

1 概述

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

1.1 RT-Thread的其他RTOS兼容层

2 FreeRTOS的API支持情况

兼容层对FreeRTOS API的支持情况如下：

2.1 任务控制

2.2 内核控制

2.3 任务通知

2.4 消息队列

2.5 信号量/互斥量

2.6 定时器

2.7 事件集

2.8 不支持的功能

3 使用注意事项

一些函数在功能和使用方法上和FreeRTOS略有不同，在迁移过程中需要注意。

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

3.1.1 vTaskSuspend

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

3.1.2 xQueueSendToFront

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

3.1.3 xQueueCreateStatic

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

#define QUEUE_LENGTH 10
#define ITEM_SIZE sizeof( uint32_t )

/* 以下是在原版FreeRTOS分配内存的方法，由于RT-Thread消息队列内部的实现与FreeRTOS不同，这样分配的内存不够存放QUEUE_LENGTH个消息 */
//uint8_t ucQueueStorage[ QUEUE_LENGTH * ITEM_SIZE ];
/* 要使用QUEUE_BUFFER_SIZE宏分配内存 */
uint8_t ucQueueStorage[ QUEUE_BUFFER_SIZE(QUEUE_LENGTH, ITEM_SIZE)];
StaticQueue_t xQueueBuffer;
QueueHandle_t xQueue1;
xQueue1 = xQueueCreate( QUEUE_LENGTH, ITEM_SIZE, &( ucQueueStorage[ 0 ] ), &xQueueBuffer );

3.1.4 Mutex和Recursive Mutex

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

3.2 定时器

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

3.3 FromISR函数

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

BaseType_t xHigherPrioritTaskWoken = pdFALSE;
xQueueSendToFrontFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );
if( xHigherPriorityTaskWoken )
{
  taskYIELD ();
}

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

3.4 内存堆

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

#可将heap_3.c替换成heap_1.c等
src += 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的内存堆完成。

3.5 线程优先级

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

#define FREERTOS_PRIORITY_TO_RTTHREAD(priority)    ( configMAX_PRIORITIES - 1 - ( priority ) )
#define RTTHREAD_PRIORITY_TO_FREERTOS(priority)    ( RT_THREAD_PRIORITY_MAX - 1 - ( priority ) )

3.6 线程堆栈大小

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

3.7 vTaskStartScheduler

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

xTaskCreate(pxTask1Code, ......);
xTaskCreate(pxTask2Code, ......);
......
vTaskStartScheduler();

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

4 使用方法

通过Env工具或RT-Thread Studio将FreeRTOS兼容层加入到工程中：

RT-Thread online packages
    system packages --->
        [*] FreeRTOS Wrapper --->
            Version (latest)

以下选项会影响到FreeRTOS兼容层：

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

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

/* 可以选择不使用recursive mutex */
#ifdef RT_USING_MUTEX
    #define configUSE_RECURSIVE_MUTEXES         1
    #define configUSE_MUTEXES                   1
#endif

/* 可以选择不使用counting semaphore */
#ifdef RT_USING_SEMAPHORE
    #define configUSE_COUNTING_SEMAPHORES       1
#endif

/* 若不使用heap_3，可以通过configTOTAL_HEAP_SIZE配置内存堆大小 */
#define configSUPPORT_STATIC_ALLOCATION         1
#ifdef RT_USING_HEAP
    #define configSUPPORT_DYNAMIC_ALLOCATION    1
    #define configTOTAL_HEAP_SIZE               10240
    #define configAPPLICATION_ALLOCATED_HEAP    0
#endif

#define configMINIMAL_STACK_SIZE                128

/* 可以选择的函数和功能 */
#define INCLUDE_vTaskPrioritySet                1
#define INCLUDE_uxTaskPriorityGet               1
#define INCLUDE_vTaskDelete                     1
#define INCLUDE_vTaskSuspend                    1
#define INCLUDE_xTaskDelayUntil                 1
#define INCLUDE_vTaskDelay                      1
#define INCLUDE_xTaskGetIdleTaskHandle          1
#define INCLUDE_xTaskAbortDelay                 1
#define INCLUDE_xSemaphoreGetMutexHolder        1
#define INCLUDE_xTaskGetHandle                  1
#define INCLUDE_uxTaskGetStackHighWaterMark     1
#define INCLUDE_uxTaskGetStackHighWaterMark2    1
#define INCLUDE_eTaskGetState                   1
#define INCLUDE_xTaskResumeFromISR              1
#define INCLUDE_xTaskGetSchedulerState          1
#define INCLUDE_xTaskGetCurrentTaskHandle       1
#define configUSE_APPLICATION_TASK_TAG          1
#define configUSE_TASK_NOTIFICATIONS            1
#define configTASK_NOTIFICATION_ARRAY_ENTRIES   3

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

msh />queue_dynamic
Task 1 receive data 0 from queue
Task 1 receive data 1 from queue
Task 1 receive data 2 from queue
Task 1 receive data 3 from queue
Task 1 receive data 4 from queue
Task 1 receive data 5 from queue
Task 1 receive data 6 from queue
Task 1 receive data 7 from queue
Task 1 receive data 8 from queue
Task 1 receive data 9 from queue
Task 1 receive data 10 from queue

5 注意事项 & 补充说明

1、该版本FreeRTOS由乐鑫公司的esp-idf库中迁移而来，部分函数需要根据芯片来实现，如出现编译问题可参考bsp/ESP32_C3和RT-Thread-packages/esp-idf。

2、在menuconfig页面中可以开启PKG_FREERTOS_USING_CONFIG_H宏定义，该宏定义允许用户自定义相关freertos配置，具体使用案例可以参考bsp/ESP32_C3/idf_port/include/freertos/FreeRTOSConfig.h，注意只有部分配置宏定义可以被覆盖，详见FreeRTOS/include/freertos/FreeRTOS.h。

6 参考资料

RT-Thread文档 https://www.rt-thread.org/document/site/#/rt-thread-version/rt-thread-standard/README

FreeRTOS文档 https://www.freertos.org/a00106.html

7 维护

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

维护：唐照洲