RT-Thread操作系统μC/OS-III兼容层

让基于μC/OS-III开发的应用层无感地迁移到RT-Thread操作系统

https://github.com/mysterywolf/RT-Thread-wrapper-of-uCOS-III

详细说明请戳上面的github链接↑，如果喜欢的话请在github上给我一个star，这对我很重要，开源项目的成就感就靠star了！

软件包已经发布(uCOSIII_Wrapper)，可以通过ENV工具进行自动配置

1 概述

这是一个针对国产RT-Thread操作系统的μCOS-III操作系统兼容层，可以让基于美国Micriμm公司的μCOS-III操作系统的项目快速迁移到RT-Thread操作系统上。

1.1 本兼容层适合于：

• 之前学习过μCOS-III操作系统，意图转向学习RT-Thread国产操作系统。本兼容层可以帮您用已有的μCOS-III编程经验和习惯快速将项目跑起来，日后在应用过程中深入熟悉RT-Thread的API函数，逐步向RT-Thread过度，降低您的学习门槛和时间成本。有了本兼容层，对RT-Thread API以及编程风格的不熟悉再也不是您学习RT-Thread的阻力！
• 现有任务（线程）模块采用μCOS-III编写，想要用在基于RT-Thread的工程上
• 老项目需要从μCOS-III操作系统向RT-Thread操作系统迁移
• 当需要快速基于RT-Thread开发产品，但是工程师之前均采用μC/OS开发，从未用过RT-Thread的开发经验。本兼容层可以帮助让工程师快速基于μC/OS开发经验开发产品，简化软件的重用、缩短微控制器新开发人员的学习过程，并缩短新设备的上市时间。
• 避免在从μCOS-III迁移到RT-Thread时，由于μCOS-III的编程经验导致的思维定式引发的错误，这种错误一般很难被发现
• 本兼容层实现了与Micriμm公司专门为其旗下产品μC/OS等开发的专用软件μC/Probe的对接，可以通过该软件以图像化形式查看、调试RT-Thread内核以及μCOS-III兼容层的相关信息

1.2 版本详细信息

兼容uCOS-III 3.00-3.08全系列

1.3 官网

RT-Thread：https://www.rt-thread.org/

文档中心：https://www.rt-thread.org/document/site/tutorial/nano/an0038-nano-introduction/

μCOS-III：https://www.micrium.com/

文档中心：https://doc.micrium.com/display/kernel304/uC-OS-III+Documentation+Home

2 使用

2.1 Keil-MDK仿真工程

本仿真工程是基于STM32F103RB平台。

Keil工程路径：<u>RT-Thread-wrapper-of-uCOS-IIIrt_thread_3.1.3-ucosiii_3.03-wrapperrt-thread-3.1.3bspstm32f103-msh-628Project.uvprojx</u>

需要提前安装好RT-Thread Nano-3.1.3 Keil支持包：https://www.rt-thread.org/download/mdk/RealThread.RT-Thread.3.1.3.pack

注意：调试串口使用的是USART2，不是USART1

2.2 迁移步骤

1. 浏览一下μC-CPU/cpu.h文件，看一下头文件中的定义是否符合你的CPU，一般不需要改这个文件
2. 浏览一下μCOS-III/os.h文件，看一下错误代码，这个错误代码和原版μCOS-III是有一定区别的。
   
   注意: 请勿随意打开注释掉的枚举体成员,如果用户使用到了这些注释掉的成员,则会在迁移时编译报错,用以提醒用户这些错误代码在兼容层已经不可用。

1. 配置os_cfg.h和os_cfg_app.h
   每个选项的配置说明和原版μCOS-III一致，若有不同，我已经在注释中有所解释。
   
   原版μCOS-III配置说明可参见：
   
   a)《嵌入式实时操作系统μC/OS-III》北京航空航天大学出版社 宫辉等译 邵贝贝审校
   
   b) Micriμm公司文档中心: https://doc.micrium.com/display/kernel304/uC-OS-III+Features+os_cfg.h

2.3 os_cfg.h配置文件

#define  OS_CFG_DBG_EN  1     /* Enable (1) debug code/variables  */  

​ 该宏定义定义是否启用兼容层调试，建议在第一次迁移时打开，因为在兼容层内部，一部分uCOS-III原版功能没有实现，如果用户用到了这部分没有实现的功能，将会通过调试的方式输出，予以提示。用户务必对业务逻辑予以修改。

#define  OS_CFG_TMR_TASK_RATE_HZ 100u /* Rate for timers (100 Hz Typ.) */

​ 在原版μCOS-III中，该宏定义定义了软件定时器的时基信号，这与RT-Thread的软件定时器有本质的不同，在RT-Thread中，软件定时器的时基信号就等于OS ticks。因此为了能够将μCOS-III软件定时器时间参数转为RT-Thread软件定时器的时间参数，需要用到该宏定义。请使该宏定义与原工程使用μCOS-III时的该宏定义参数一致。

2.4 os_cfg_app.h配置文件

RT-Thread无需实现μCOS-III的中断任务，因此相关配置予以取消。

2.5 运行

int main(void) /*RT-Thread main线程*/
{
    OS_ERR err;
    
    OSInit(&err);                                   /*uCOS-III操作系统初始化*/
    
    OSStart(&err);                                  /*开始运行uCOS-III操作系统*/
    
#if OS_CFG_APP_HOOKS_EN > 0u
    App_OS_SetAllHooks();                           /*设置钩子函数*/
#endif  
    
#if OS_CFG_STAT_TASK_EN > 0u
    OSStatTaskCPUUsageInit(&err);                   /*统计任务*/    
    OSStatReset(&err);                              /*复位统计数据*/    
#endif      

}

3 接口

3.1 没有实现兼容的API（仅2个）

虽然RT-Thread没有任务内建消息队列、任务内建信号量、任务内建寄存器机制，但是本兼容层均已实现，可以正常兼容。但是由于RT-Thread没有提供相关接口，以下μCOS-III API无法兼容：

void  OSTaskChangePrio (OS_TCB *p_tcb, OS_PRIO prio_new, OS_ERR *p_err);
void  OSTaskTimeQuantaSet (OS_TCB *p_tcb, OS_TICK time_quanta, OS_ERR *p_err);

3.2 钩子函数

​ μCOS-III的钩子函数仅对μCOS-III兼容层负责。 即如果你注册了OSTaskDelHook函数，他仅会在调用OSTaskDel函数时被调用，不会在调用rt_thread_detach函数时被调用(这个由RTT的钩子函数负责)。这样做是为了层次分明，防止μCOS-III兼容层插手RT-Thread内部事务。

​ μCOS-III的钩子函数在两个文件中实现：os_cpu_c.c和os_app_hooks.c 。按照μCOS-III的思想，os_cpu_c.c提供原始的钩子函数（即这些钩子函数被相应的函数直接调用），该文件以及其内部的钩子函数是移植工程师编写的内容，应用工程师不应该操作这个文件的内容，os_cpu_c.c文件的钩子函数提供相应的函数指针供os_app_hooks.c文件内的钩子函数注册和使用，这个文件内的钩子函数应用工程师是可以操作的。换句话说，我们有什么需要在钩子函数中调用的函数，应该放在os_app_hooks.c文件中。

​ 以下原版μCOS-III钩子函数将予以取消，由RT-Thread接管相关钩子函数接管：

void          OSTaskReturnHook          (OS_TCB *p_tcb);
void          OSTaskSwHook              (void);
void          OSTimeTickHook            (void);

​ 同时，上述钩子函数对应的应用级钩子函数也被取消：

void  App_OS_TaskReturnHook (OS_TCB  *p_tcb);
void  App_OS_InitHook (void);/*按照手册要求OS初始化的钩子函数不应该出现在应用层,在3.03版本中出现应该是失误,在3.08版本中已经将该应用级钩子函数取消*/
void  App_OS_TaskSwHook (void);
void  App_OS_TimeTickHook (void);

3.3 统计任务（OS_StatTask()、os_stat.c）

​ 在μCOS-III中，统计任务是一个系统任务，可以在系统运行时做一些统计工作，例如统计总的CPU使用率（0.00% - 100.00%）、各任务的CPU使用率（0.00% - 100.00%）以及各任务的堆栈使用量。从内核版本V3.03.00起，CPU的利用率用一个0-10000之间的整数表示（对应0.00% - 100.00%）。

​ 但是RT-Thread并没有统计任务，因此需要创建一个任务来兼容原版μCOS-III的统计任务，完成上述功能。该统计任务会在兼容层初始化时自动创建，用户无需干预。用户仅需调用OSStatTaskCPUUsage全局变量即可获取当前的CPU使用率，CPU使用率的计算策略和原版μCOS-III完全一致

​ 目前统计任务实现的功能：

1. 计算全局CPU使用率
2. 计算每个任务的任务堆栈使用情况（当 OS_CFG_DBG_EN 和 OS_CFG_STAT_TASK_STK_CHK_EN 为1）

3.4 全局变量

目前，本兼容层可以使用以下μCOS-III原版全局变量（位于os.h）。这些全局变量的具体含义请参见2.2节中所列举出的参考资料。（论坛放不下了，请大家到github上去看详细介绍吧！）