ThreadX移植——STM32H7+MDK-AC6平台

• 作者：zzssdd2
• E-mail：zzssdd2@foxmail.com

一、前言

在uCOS全家桶宣布开源之后被微软收购的ThreadX也开源了，真是喜大普奔，对于我们这些嵌入式行业从业者来说，能够学习这些高含金量的代码对于眼界的开拓和能力的提升都是很有帮助的。ThreadX还包含了NETX、GUIX、FILEX、USBX等丰富的组件，几乎包含了嵌入式开发中的所有场景，这些组件和ThreadX-RTOS能够完美的配合完成一条龙的开发。ThreadX的github地址：[Azure RTOS (github.com)]:

二、准备

ThreadX在更新了几个版本之后已经提供了多个平台的移植端口，包括AC5、AC6、GCC、IAR，现在可以更方便地移植到各编译器平台了。本次移植是在STM32H743 + MDK-AC6 + ThreadX6.1.2下完成。首先使用STM32CubeMX新建一个工程，配置了LED、KEY、UART，然后将下载的ThreadX放在同一工程下（移植用到common和ports/cortex_m7/ac6下的文件）。

三、配置

1、添加文件及参数

• 工程新增ThreadX/Port、ThreadX/Src分组，ThreadX/Portf组中添加ports/cortex_m7/ac6/src目录下所有文件以及ports\cortex_m7\ac6\example_build\sample_threadx目录下的tx_initialize_low_level.S文件； ThreadX/Src组中添加threadx\common\src下所有文件。添加完成如下图所示：

  

• 配置工程宏定义参数和文件包含路径如下所示。

其中USE_HAL_DRIVER和STM32H743xx是使用HAL库创建工程需要包含的定义，TX_ENABLE_FPU_SUPPORT是使能ThreadX的浮点运算支持需要定义的，在readme_threadx.txt文档中有如下描述：

If saving the context of the FPU registers
is needed, the ThreadX library should be re-built with TX_ENABLE_FPU_SUPPORT defined.

当然要正确的使用硬件浮点运算功能还应该开启MDK中的如下配置：

2、修改适配文件

主要是对tx_initialize_low_level.S文件进行修改，该文件作用是初始化栈地址和向量表、配置系统心跳节拍、配置部分中断优先级、定义部分中断处理函数。但是其中有些工作在STM32H743的启动文件startup_stm32h743xx.s中已经做了，而STM32启动文件所实现的一些功能这个文件又没有实现。因为该文件是针对cortex_m7内核芯片做的，没有针对具体某一款芯片，所以没有STM32的启动文件实现的功能完善，因此不能替代启动文件。这里的修改方法是不动STM32启动文件，修改tx_initialize_low_level.S文件，在此提供两种修改方案：1、根据冲突修改tx_initialize_low_level.S文件内容；2、将tx_initialize_low_level.S文件改为C语言实现（STM32启动文件已经实现的不管，只需将ThreadX需要配置的功能用C实现）。

• 方案1修改后内容如下（修改处已标注）：

  @/**************************************************************************/
  @/*                                                                        */
  @/*       Copyright (c) Microsoft Corporation. All rights reserved.        */
  @/*                                                                        */
  @/*       This software is licensed under the Microsoft Software License   */
  @/*       Terms for Microsoft Azure RTOS. Full text of the license can be  */
  @/*       found in the LICENSE file at https://aka.ms/AzureRTOS_EULA       */
  @/*       and in the root directory of this software.                      */
  @/*                                                                        */
  @/**************************************************************************/
  @
  @
  @/**************************************************************************/
  @/**************************************************************************/
  @/**                                                                       */
  @/** ThreadX Component                                                     */
  @/**                                                                       */
  @/**   Initialize                                                          */
  @/**                                                                       */
  @/**************************************************************************/
  @/**************************************************************************/
  @
  @
      .global     _tx_thread_system_stack_ptr
      .global     _tx_initialize_unused_memory
      .global     _tx_timer_interrupt
      .global     __main
      .global     __tx_SVCallHandler
      .global     __tx_PendSVHandler
      .global     __tx_NMIHandler                     @ NMI
      .global     __tx_BadHandler                     @ HardFault
      .global     __tx_SVCallHandler                  @ SVCall
      .global     __tx_DBGHandler                     @ Monitor
      .global     __tx_PendSVHandler                  @ PendSV
      .global     __tx_SysTickHandler                 @ SysTick
      .global     __tx_IntHandler                     @ Int 0
  @
  @
  SYSTEM_CLOCK      =   480000000						@---modify by user(系统频率)
  SYSTICK_CYCLES    =   ((SYSTEM_CLOCK / 1000) -1)	@---modify by user(时钟节拍)
  
      .text 32
      .align 4
      .syntax unified
  @/**************************************************************************/
  @/*                                                                        */
  @/*  FUNCTION                                               RELEASE        */
  @/*                                                                        */
  @/*    _tx_initialize_low_level                          Cortex-M7/AC6     */
  @/*                                                           6.1          */
  @/*  AUTHOR                                                                */
  @/*                                                                        */
  @/*    William E. Lamie, Microsoft Corporation                             */
  @/*                                                                        */
  @/*  DESCRIPTION                                                           */
  @/*                                                                        */
  @/*    This function is responsible for any low-level processor            */
  @/*    initialization, including setting up interrupt vectors, setting     */
  @/*    up a periodic timer interrupt source, saving the system stack       */
  @/*    pointer for use in ISR processing later, and finding the first      */
  @/*    available RAM memory address for tx_application_define.             */
  @/*                                                                        */
  @/*  INPUT                                                                 */
  @/*                                                                        */
  @/*    None                                                                */
  @/*                                                                        */
  @/*  OUTPUT                                                                */
  @/*                                                                        */
  @/*    None                                                                */
  @/*                                                                        */
  @/*  CALLS                                                                 */
  @/*                                                                        */
  @/*    None                                                                */
  @/*                                                                        */
  @/*  CALLED BY                                                             */
  @/*                                                                        */
  @/*    _tx_initialize_kernel_enter           ThreadX entry function        */
  @/*                                                                        */
  @/*  RELEASE HISTORY                                                       */
  @/*                                                                        */
  @/*    DATE              NAME                      DESCRIPTION             */
  @/*                                                                        */
  @/*  09-30-2020     William E. Lamie         Initial Version 6.1           */
  @/*                                                                        */
  @/**************************************************************************/
  @VOID   _tx_initialize_low_level(VOID)
  @{
      .global  _tx_initialize_low_level
      .thumb_func
  _tx_initialize_low_level:
  @
  @    /* Disable interrupts during ThreadX initialization.  */
  @
      CPSID   i
  @
  @    /* Set base of available memory to end of non-initialised RAM area.  */
  @
      LDR     r0, =_tx_initialize_unused_memory       @ Build address of unused memory pointer
      LDR     r1, =__initial_sp						@ Image$$ARM_LIB_STACKHEAP$$ZI$$Limit @ Build first free address		---modify by user
      ADD     r1, r1, #4                              @
      STR     r1, [r0]                                @ Setup first unused memory pointer
  @
  @    /* Setup Vector Table Offset Register.  */
  @
      MOV     r0, #0xE000E000                         @ Build address of NVIC registers
      LDR     r1, =__Vectors							@ vector_table                       @ Pickup address of vector table	---modify by user
      STR     r1, [r0, #0xD08]                        @ Set vector table address
  @
  @    /* Set system stack pointer from vector value.  */
  @
      LDR     r0, =_tx_thread_system_stack_ptr        @ Build address of system stack pointer
      LDR     r1, =__Vectors							@ vector_table                       @ Pickup address of vector table	---modify by user
      LDR     r1, [r1]                                @ Pickup reset stack pointer
      STR     r1, [r0]                                @ Save system stack pointer
  @
  @    /* Enable the cycle count register.  */
  @
      LDR     r0, =0xE0001000                         @ Build address of DWT register
      LDR     r1, [r0]                                @ Pickup the current value
      ORR     r1, r1, #1                              @ Set the CYCCNTENA bit
      STR     r1, [r0]                                @ Enable the cycle count register
  @
  @    /* Configure SysTick for 100Hz clock, or 16384 cycles if no reference.  */
  @
      MOV     r0, #0xE000E000                         @ Build address of NVIC registers
      LDR     r1, =SYSTICK_CYCLES
      STR     r1, [r0, #0x14]                         @ Setup SysTick Reload Value
      MOV     r1, #0x7                                @ Build SysTick Control Enable Value
      STR     r1, [r0, #0x10]                         @ Setup SysTick Control
  @
  @    /* Configure handler priorities.  */
  @
      LDR     r1, =0x00000000                         @ Rsrv, UsgF, BusF, MemM
      STR     r1, [r0, #0xD18]                        @ Setup System Handlers 4-7 Priority Registers
  
      LDR     r1, =0xFF000000                         @ SVCl, Rsrv, Rsrv, Rsrv
      STR     r1, [r0, #0xD1C]                        @ Setup System Handlers 8-11 Priority Registers
                                                      @ Note: SVC must be lowest priority, which is 0xFF
  
      LDR     r1, =0x40FF0000                         @ SysT, PnSV, Rsrv, DbgM
      STR     r1, [r0, #0xD20]                        @ Setup System Handlers 12-15 Priority Registers
                                                      @ Note: PnSV must be lowest priority, which is 0xFF
  @
  @    /* Return to caller.  */
  @
      BX      lr
  @}
  @
  
  @/* Define shells for each of the unused vectors.  */
  @
      .global  __tx_BadHandler
      .thumb_func
  __tx_BadHandler:
      B       __tx_BadHandler
  
  @ /* added to catch the hardfault */
  
      .global  __tx_HardfaultHandler
      .thumb_func
  __tx_HardfaultHandler:
      B       __tx_HardfaultHandler
  
  @ /* added to catch the SVC */
  
      .global  __tx_SVCallHandler
      .thumb_func
  __tx_SVCallHandler:
      B       __tx_SVCallHandler
  
  @ /* Generic interrupt handler template */
      .global  __tx_IntHandler
      .thumb_func
  __tx_IntHandler:
  @ VOID InterruptHandler (VOID)
  @ {
      PUSH    {r0, lr}
  #ifdef TX_ENABLE_EXECUTION_CHANGE_NOTIFY
      BL      _tx_execution_isr_enter             @ Call the ISR enter function
  #endif
  
  @    /* Do interrupt handler work here */
  @    /* BL <your C Function>.... */
  
  #ifdef TX_ENABLE_EXECUTION_CHANGE_NOTIFY
      BL      _tx_execution_isr_exit              @ Call the ISR exit function
  #endif
      POP     {r0, lr}
      BX      LR
  @ }
  
  @ /* System Tick timer interrupt handler */
      .global  __tx_SysTickHandler
      .global  SysTick_Handler
      .thumb_func
  __tx_SysTickHandler:
      .thumb_func
  SysTick_Handler:
  @ VOID TimerInterruptHandler (VOID)
  @ {
  @
      PUSH    {r0, lr}
  #ifdef TX_ENABLE_EXECUTION_CHANGE_NOTIFY
      BL      _tx_execution_isr_enter             @ Call the ISR enter function
  #endif
      BL      _tx_timer_interrupt
  #ifdef TX_ENABLE_EXECUTION_CHANGE_NOTIFY
      BL      _tx_execution_isr_exit              @ Call the ISR exit function
  #endif
      POP     {r0, lr}
      BX      LR
  @ }
  
  @ /* NMI, DBG handlers */
      .global  __tx_NMIHandler
      .thumb_func
  __tx_NMIHandler:
      B       __tx_NMIHandler
  
      .global  __tx_DBGHandler
      .thumb_func
  __tx_DBGHandler:
      B       __tx_DBGHandler
  
  

• 方案2修改内容如下（工程中用该文件tx_initialize_low_level.C替换tx_initialize_low_level.S文件）

  #include "stm32h7xx_hal.h"
  #include "tx_api.h"
  
  static const uint32_t SYSTEM_CLOCK      =   480000000;
  static const uint32_t SYSTICK_CYCLES    =   ((SYSTEM_CLOCK / 1000) -1);
  
  extern void  _tx_timer_interrupt(void);	/*in "tx_timer_interrupt.S" file*/
  
  void   _tx_initialize_low_level(void)
  {
      /* Disable interrupts during ThreadX initialization.  */
      __set_PRIMASK(1);
  
      /* Configure SysTick for 1000Hz clock, or 16384 cycles if no reference.  */
      SysTick_Config(SYSTICK_CYCLES);
  
      /* Configure handler priorities.  */
      HAL_NVIC_SetPriority(SVCall_IRQn, 15, 0);	/*Note: SVC must be lowest priority*/
      HAL_NVIC_EnableIRQ(SVCall_IRQn);
  
      HAL_NVIC_SetPriority(PendSV_IRQn, 15, 0);
      HAL_NVIC_EnableIRQ(PendSV_IRQn);			/*Note: PnSV must be lowest priority*/
  
      HAL_NVIC_SetPriority(SysTick_IRQn, 4, 0);
      HAL_NVIC_EnableIRQ(SysTick_IRQn);
  }
  
  /* System Tick timer interrupt handler */
  void SysTick_Handler (void)
  {
      /*BL      _tx_timer_interrupt*/
      _tx_timer_interrupt();
  }
  

通过上述修改文件可见ThreadX修改底层移植文件的内容并不多，移植还是比较方便。

最后将stm32h7xx_it.c文件中的PendSV_Handler和SysTick_Handler中断处理函数屏蔽（前者用于实现RTOS的任务调度，后者用于实现RTOS的心跳节拍）。

#ifndef ENABLE_RTOS
void PendSV_Handler(void)
{
}

void SysTick_Handler(void)
{
}
#endif

四、测试

经过上述步骤，工程编译已经没有错误，接下来就是创建任务测试ThreadX能否正常运行起来。

在threadx\ports\cortex_m7\ac6\example_build\sample_threadx下的sample_threadx.c文件中演示了任务的创建，依葫芦画瓢创建自己的任务即可。main.c文件内容如下：

#include "main.h"
#include "usart.h"
#include "gpio.h"
#include "tx_api.h"

#define DEMO_STACK_SIZE         (2 * 1024)
#define DEMO_BYTE_POOL_SIZE     (32 * 1024)

TX_BYTE_POOL            byte_pool_0;
UCHAR                   memory_area[DEMO_BYTE_POOL_SIZE];

TX_THREAD               thread_0;
TX_THREAD               thread_1;
TX_THREAD               thread_2;

void    thread_0_entry(ULONG thread_input);
void    thread_1_entry(ULONG thread_input);
void    thread_2_entry(ULONG thread_input);

int main(void)
{
    HAL_Init();
    SystemClock_Config();
    MX_GPIO_Init();
    MX_USART1_UART_Init();
    while (1)
    {
        tx_kernel_enter();
    }
}

void tx_application_define(void *first_unused_memory)
{
    CHAR    *pointer = TX_NULL;

    /* Create a byte memory pool from which to allocate the thread stacks.  */
    tx_byte_pool_create(&byte_pool_0, "byte pool 0", memory_area, DEMO_BYTE_POOL_SIZE);

    /* Allocate the stack for thread 0.  */
    tx_byte_allocate(&byte_pool_0, (VOID **) &pointer, DEMO_STACK_SIZE, TX_NO_WAIT);
    /* Create the main thread.  */
    tx_thread_create(&thread_0, "thread 0", thread_0_entry, 0,
                    pointer, DEMO_STACK_SIZE,
                    1, 1, TX_NO_TIME_SLICE, TX_AUTO_START);

    /* Allocate the stack for thread 1.  */
    tx_byte_allocate(&byte_pool_0, (VOID **) &pointer, DEMO_STACK_SIZE, TX_NO_WAIT);
    /* Create threads 1  */
    tx_thread_create(&thread_1, "thread 1", thread_1_entry, 0,
                    pointer, DEMO_STACK_SIZE,
                    2, 2, TX_NO_TIME_SLICE, TX_AUTO_START);

    /* Allocate the stack for thread 2.  */
    tx_byte_allocate(&byte_pool_0, (VOID **) &pointer, DEMO_STACK_SIZE, TX_NO_WAIT);
    /* Create threads 1  */
    tx_thread_create(&thread_2, "thread 2", thread_2_entry, 0,
                    pointer, DEMO_STACK_SIZE,
                    3, 3, TX_NO_TIME_SLICE, TX_AUTO_START);
}

void    thread_0_entry(ULONG thread_input)
{
    while(1)
    {
        HAL_GPIO_TogglePin(LED1_GPIO_Port,LED1_Pin);
        tx_thread_sleep(200);
    }
}

void    thread_1_entry(ULONG thread_input)
{
    while(1)
    {
        HAL_GPIO_TogglePin(LED2_GPIO_Port,LED2_Pin);
        tx_thread_sleep(200);
    }
}

void    thread_2_entry(ULONG thread_input)
{
    double a = 0.1, b = 1.0;

    while(1)
    {
        a += 0.00000000001;
        b -= 0.00000000001;
        printf("floating test:\ta = %.11f, b = %.11f\r\n", a, b);
        tx_thread_sleep(2000);
    }
}

到这里，任务就正常运行起来了。

补充

任务创建函数说明

• 参数：
  • thread_ptr：指向线程控制块的指针
  • name_ptr ：指向线程名称的指针
  • entry_function：指定用于线程执行的初始C函数。 当线程从此入口函数返回时，它将处于完成状态并无限期挂起。
  • entry_input：首次执行时传递给线程的入口函数的32位值。 此输入的使用完全由应用程序确定
  • stack_start：堆栈内存区域的起始地址
  • stack_size：堆栈内存区中的字节数
  • priority：线程的优先级。 有效值的范围是0 ~（TX_MAX_PRIORITES-1），其中0表示最高优先级
  • preempt_threshold：禁用的抢占的最高优先级。 只有高于此级别的优先级才可以抢占该线程，该值必须小于或等于指定的优先级，等于线程优先级的值将禁用抢占阈值
  • time_slice：在其他具有相同优先级的就绪线程有机会运行之前，允许此线程运行的时钟节拍数。请注意，使用抢占阈值将禁用时间片。合法的时间片值范围从1到0xffffff (包括)。TX_NO_TIME_SLICE (值为0)禁用此线程的时间片。（使用时间片会导致少量的系统开销。由于时间片仅在多个线程共享相同优先级的情况下有用，因此不应为具有唯一优先级的线程分配时间片）
  • auto_start：指定线程是立即启动还是处于暂停状态。指定选项是TX_AUTO_START (0x01)和 TX_DONT_START (0x00)。如果指定了TX_DONT_START，则应用程序必须调用 tx_thread_resume 才能使线程运行。
• 返回值
  • TX_SUCCESS (0x00)：线程创建成功
  • TX_THREAD_ERROR (0x0E)：无效的线程控制指针。指针为 NULL 或线程已创建
  • TX_PTR_ERROR (0x03)：入口点的起始地址无效或堆栈区域无效，通常为 NULL。
  • TX_SIZE_ERROR (0x05)：堆栈区域的大小无效。 线程必须至少具有TX_MINIMUM_STACK字节才能执行。
  • TX_PRIORITY_ERROR (0x0F)：无效的线程优先级，该值超出（0 ~（TX_MAX_PRIORITIES-1））的范围。
  • TX_THRESH_ERROR (0x18)：指定的抢占阈值无效。 该值的有效优先级必须小于或等于线程的初始优先级。
  • TX_START_ERROR (0x10)：自动启动选择无效
  • TX_CALLER_ERROR (0x13)：该服务的调用者无效

UINT tx_thread_create(
    TX_THREAD *thread_ptr,
    CHAR *name_ptr,
    VOID (*entry_function)(ULONG),
    ULONG entry_input,
    VOID *stack_start,
    ULONG stack_size,
    UINT priority,
    UINT preempt_threshold,
    ULONG time_slice,
    UINT auto_start);