[XWOS-STM32]2.新建工程指南

选择合适的模板

STM32的工程比较多，可以选择其中一个来作为模板进行修改：

• 电路板文件夹位于XWOS/xwbd内部：
  • WeActMiniStm32H750
    • WeAct Studio STM32H750 开发板
    • MCU：STM32H750VBT6
    • 电路板文件夹：XWOS/xwbd/WeActMiniStm32H750
      • 代码仓库：git clone --recursive https://gitee.com/xwos/WeActMiniStm32H750.git
    • Bootloader电路板文件夹：XWOS/xwbd/WeActMiniStm32H750Bootloader
      • 代码仓库：git clone --recursive https://gitee.com/xwos/WeActMiniStm32H750Bootloader.git
  • EmbedFireStm32H743
    • 野火 STM32H743 开发板
    • MCU：STM32H743XIH6
    • 代码仓库：git clone --recursive https://gitee.com/xwos/EmbedFireStm32H743.git
    • 电路板文件夹：XWOS/xwbd/EmbedFireStm32H743
  • FK429M1
    • 反客 STM32F429 开发板
    • MCU：STM32F429BIT6
    • 代码仓库：git clone --recursive https://gitee.com/xwos/FK429M1.git
    • 电路板文件夹：XWOS/xwbd/FK429M1
  • ATKStm32H743
    • 正点原子 STM32H743 开发板
    • MCU：STM32H743IIT6
    • 代码仓库：git clone --recursive https://gitee.com/xwos/ATKStm32H743.git
    • 电路板文件夹：XWOS/xwbd/ATKStm32H743
  • ATKStm32F407Core
    • 正点原子 STM32F407 核心板
    • MCU：STM32F407ZET6
    • 代码仓库：git clone --recursive https://gitee.com/xwos/ATKStm32F407Core.git
    • 电路板文件夹：XWOS/xwbd/ATKStm32F407Core
  • ATKStm32F103Core
    • 正点原子 STM32F103 核心板
    • MCU：STM32F103ZET6
    • 代码仓库：git clone --recursive https://gitee.com/xwos/ATKStm32F103Core.git
    • 电路板文件夹：XWOS/xwbd/ATKStm32F103Core
  • Stm32F103HiXWOS
    • STM32F103的模板空工程
    • MCU：STM32F103C8T6
    • 电路板文件夹：XWOS/xwbd/Stm32F103HiXWOS
  • Stm32F072HiXWOS
    • STM32F072的模板空工程
    • MCU：STM32F072C8T6
    • 电路板文件夹：XWOS/xwbd/Stm32F072HiXWOS
• 电路板文件夹位于XWOS外部：
  • FK750M1
    • 反客 STM32H750 开发板
    • MCU：STM32H750VBT6
    • 代码仓库：git clone --recursive https://gitee.com/xwos/FK750M1.git
    • bootloader代码仓库：git clone --recursive https://gitee.com/xwos/FK750M1Bootloader.git
    • 电路板文件夹：brd
  • FK750M3
    • 反客 STM32H750 开发板
    • MCU：STM32H750VBT6
    • 代码仓库：git clone --recursive https://gitee.com/xwos/FK750M3.git
    • bootloader代码仓库：git clone --recursive https://gitee.com/xwos/FK750M3Bootloader.git
    • 电路板文件夹：brd

修改工程配置

工程总配置

• 配置文件：电路板文件夹内的cfg/XuanWuOS.h
• XuanWuOS_CFG_SUBARCH：CPU的子架构
  • v7m：ARMv7-M
  • v6m：ARMv6-M
• XuanWuOS_CFG_COMPILER：编译器
  • gcc：gcc/g++
  • llvm：clang/clang++
• XuanWuOS_CFG_LDSCRIPT：配置链接脚本的路径，此路径相对于电路板文件夹
• XuanWuOS_CFG_CPU：CPU型号
  • m0：Cortex M0
  • m0p：Cortex M0 Plus
  • m3：Cortex M3
  • m4：Cortex M4
  • m7：Cortex M7
• XuanWuOS_CFG_BOARD：电路板文件夹的名称
  • 若工程位于XWOS/xwbd内部，则此名称需要和文件夹名称一致，并且区分大小写。
• XuanWuOS_CFG_CORE：单核还是多核
  • mp：使用多核内核
  • up：使用单核内核
• XuanWuOS_CFG_XWCD：是否启用XWOS/xwcd/内的玄武模块
  • 1：是
  • 0：否
• XuanWuOS_CFG_XWMD：是否启用XWOS/xwmd内的玄武模块
  • 1：是
  • 0：否
• XuanWuOS_CFG_XWEM：是否启用XWOS/xwem内的玄武模块
  • 1：是
  • 0：否
• XuanWuOS_CFG_XWAM：是否启用XWOS/xwam内的玄武模块
  • 1：是
  • 0：否
• XuanWuOS_CFG_OEMPATH：配置OEM文件夹路径
  • 此路径通常配置为相对路径，相对于电路板文件夹；
  • 此路径也可以是绝对路径；
  • 此路径可以是任意路径，并不一定要在XWOS内部；

修改链接脚本

链接脚本由配置XuanWuOS_CFG_LDSCRIPT指定，通常为cfg/XuanWuOS.lds

STM32的链接脚本是按照可复用的方式设计的，分为两部分：

• SDL中的链接脚本：描述各个段(SECTIONS)如何分布在镜像文件中
  • STM32F0：xwcd/soc/arm/v7m/gcc/m0/stm32/f0.lds
  • STM32G0：xwcd/soc/arm/v7m/gcc/m0p/stm32/g0.lds
  • STM32F1：xwcd/soc/arm/v7m/gcc/m3/stm32/f1.lds
  • STM32L1：xwcd/soc/arm/v7m/gcc/m3/stm32/l1.lds
  • STM32F4：xwcd/soc/arm/v7m/gcc/m4/stm32/f4.lds
  • STM32L4：xwcd/soc/arm/v7m/gcc/m4/stm32/l4.lds
  • STM32F7：xwcd/soc/arm/v7m/gcc/m7/stm32/f7.lds
  • STM32H7：xwcd/soc/arm/v7m/gcc/m7/stm32/h7.lds
• BDL中的链接脚本：只描述内存区域MEMORY

ivt_lmr& ivt_vmr

XWOS的中断向量表区域，其中LMR表示中断向量的加载地址区域，
也即是中断向量在Flash中的存储位置，VMR表示中断向量的运行地址区域，
也即是上电运行时的中断向量的地址。

• 如果LMR与VMR都指向Flash，且起始地址(org)与大小(len)完全一致，表示加载地址
  就是运行地址，XWOS在初始化阶段不会对中断向量执行拷贝操作；
• 如果VMR指向RAM的某个地址，XWOS会在初始化阶段把Flash中的中断向量表拷贝到
  VMR指定的RAM内，并设置ARM的VTOR寄存器；
• 需要注意ARM的VTOR寄存器低7位(0~6)必须保持为0，因此VMR的起始地址也必须满足
  此规则。

image_description_mr

此段中包含镜像文件的一些基本信息，例如起始位置，结尾标志位置等，可用在升级固件功能中。

code_mr

存放代码和常量的地方。

xwos_data_mr

存放xwos全局数据的地方，这些变量在定义时带有修饰符：__xwos_data，此段可以
不存在，若不存在，需要在SDL中的链接脚本中将此段的数据放到data_mr中。

data_mr

存放全局变量的地方。当连接器ld安排完全局变量后，剩余的部分会交给XWOS
的默认的内核内存分配器进行管理，用于为动态创建内核对象的API提供动态内存申请的接口。

xwos_stk_mr

XWOS内核的栈内存，XWOS内核处理中断时会使用此内存作为函数的栈。

集成STM32CubeMx生成的代码

STM32的时钟、外设驱动需要在STM32CubeMx中配置，并生成代码，再交由XWOS调用。
STM32CubeMx生成的代码采用玄武模块的方式集成：

• 路径：电路板文件夹内的bm/stm32cube
• 编译开关：配置cfg/board.h内的BMCFG_stm32cube
• STM32CubeMX配置文件：stm32cube/cubemx/XXX.ioc
• STM32CubeMX源码目录：stm32cube/cubemx
• 中断向量表：stm32cube/cubemx/IVT
  • 中断向量表是使用命令自动生成：XWOS/xwbs/util/el/stm32ivt/stm32ivt.el stm32cube的路径

stm32cube/xwac

其中包括适配XWOS的源码：

• stm32cube/xwac/xwos/hook.c
  • 定义Hook函数stm32cube_systick_hook()，并在其中调用HAL_IncTick();，
    再由board_xwskd_syshwt_hook()调用stm32cube_systick_hook()；
  • 函数board_xwskd_syshwt_hook()定义在电路板文件夹内的bdl/xwac/xwskd_hook.c，
    当cfg/board.h内的配置BRDCFG_XWSKD_SYSHWT_HOOK为1时，
    由XWOS内核在滴答时钟中断函数内调用此函数。
• stm32cube/xwac/fatfs：文件系统XWOS/xwem/fs/fatfs底层适配代码，
  STM32CubeMX生成的的硬件读写代码由此处调用，若不需要文件系统，可删除。
• stm32cube/xwac/lua：Lua语言XWOS/xwem/vm/lua底层适配代码，若不需要Lua，可删除。
• stm32cube/xwac/newlib：C标准库的底层适配代码，若不使用，可删除。
• stm32cube/xwac/xwds：C标准库的底层适配代码，若不使用，可删除。
• stm32cube/xwac/xwlib：XWOS的通用库的底层适配代码，其中定义了log如何输出，CRC算法的硬件支持等，
  若MCU不提供支持，可删除。

stm32cube/mif.c与stm32cube/mif.h

其中定义了模块对外的接口，其中有两个接口在启动流程中被调用：

• stm32cube_lowlevel_init()：由board_lowlevel_init()调用；
• stm32cube_init()：由board_init()调用。

xwmo.mk

由于STM32CubeMX生成多少.c文件不确定，因此需要从STM32CubeMX生成的Makefile中获取
此信息，为此可使用脚本XWOS/xwbs/util/el/makefile-grep-variable.el，具体可参考已有
工程中的xwmo.mk

配置STM32CubeMX

需要将Project Manager中的Toolchain/IDE设置为Makefile。

中断优先级

• XWOS对中断优先级的要求：

切换上下文的中断 <= 滴答定时器的中断 < 调度器服务中断
切换上下文的中断 < 其他中断 < 调度器服务中断

• NVIC设置
  • 设置3个抢占优先级位和1个子优先级位
  • SVC中断设置成最高优先级，即Preemption Priority为0；
  • PendSV中断设置成最低优先级，即Preemption Priority为7；
  • Systick中断设置成最低优先级，即Preemption Priority为7；
  • 系统Fault的优先级设置为0；
  • 其他中断的优先级只可在1~6之间。。

建立入口函数

XWOS启动流程结束后的入口函数是xwos_main()，可以通过一个玄武模块定义，例如bm/main，
简单的应用也可以定义在bdl/的某个.c文件内。

使用STM32CubeIDE

新建工程

在STM32CubeIDE的workspace目录新建一个文件夹，将stm32cube/cubemx/XXX.ioc、源码放在一起：

.
├── XXX.ioc
└── XWOS

在STM32CubeIDE中打开
菜单File --> New --> STM32 Project from an Exsiting STM32CubeMX Configuration File(.ioc)，
选择XXX.ioc。

将生成的代码Core/、Drivers/、*.ld删除，在XWOS中用不到。

设置编译环境

• 打开菜单**“Project --> Properties --> C/C++ Build --> Environment”**；
• 点击**“Restore Defaults”**；
• 修改Debug配置的环境变量：
  • WKSPC:../../../${ConfigName}
  • ~D:1
  • ~V:1

• 修改Release配置的环境变量：
  • WKSPC:../../../${ConfigName}
  • ~D:0
  • ~V:1

环境变量PATH设置

• 修改Debug和Release两个配置的PATH环境变量
  • 将STM32CubeIDE自带的工具链路径从PATH环境变量中删除；
  • 将xwtool工具链的路径放置到PATH环境变量中。

• 注意，STM32CubeIDE自带的工具链在windows可能会导致编译失败，
  需将STM32CubeIDE自带的工具链路径从PATH环境变量中删除，
  并使用xwtool工具链：

make (e=3): 系统找不到指定的路径。
make (e=3): The system cannot find the file specified.

调试配置

打开菜单Run --> Debug Configurations…，根据仿真器类型，选择调试配置：

• WeActMiniStm32H750：gdb + STLink GDB Server + STLink调试器；

• 设置外部QSPI Flash的下载算法需要拷贝到STM32CubeIDE的安装目录： plugins/com.st.stm32cube.ide.mcu.externaltools.cubeprogrammer.<版本号>/tools/bin/ExternalLoader；