STM32 Porting Guide

Introduction

Since ST’s official STM32CubeMX can automatically generate chip initialization code, the Architecture Description Layer (ADL), CPU Description Layer (CDL), and SoC Description Layer (SDL) code for STM32 in XWOS is almost identical. The only difference is the linker script.

Linker Script

STM32 linker scripts are also designed for reusability, divided into two parts:

• Linker script in the SDL: Describes how various sections are distributed in the image file
  • STM32F0: XWOS/xwcd/soc/arm/v7m/m0/stm32/f0.lds
  • STM32G0: XWOS/xwcd/soc/arm/v7m/m0p/stm32/g0.lds
  • STM32F1: XWOS/xwcd/soc/arm/v7m/m3/stm32/f1.lds
  • STM32L1: XWOS/xwcd/soc/arm/v7m/m3/stm32/l1.lds
  • STM32F4: XWOS/xwcd/soc/arm/v7m/m4/stm32/f4.lds
  • STM32L4: XWOS/xwcd/soc/arm/v7m/m4/stm32/l4.lds
  • STM32F7: XWOS/xwcd/soc/arm/v7m/m7/stm32/f7.lds
  • STM32H7: XWOS/xwcd/soc/arm/v7m/m7/stm32/h7.lds
  • Other SoCs are continuously being added…
• Linker script in the board directory: Only describes memory regions
• WeActMiniStm32H750 project: XWOS/xwbd/WeActMiniStm32H750/cfg/brd.lds
• WeActMiniStm32H750Bootloader project: XWOS/xwbd/WeActMiniStm32H750Bootloader/cfg/brd.lds
• Other boards are continuously being added…

Different board projects only differ in the Memory regions in the Board linker script.

Basic lds Syntax

Defining Memory Regions

name (attributes): org = xxx, len = xxx

• o, org, ORIGIN: Defines the starting address of the memory region
• l, len, LENGTH: Defines the length of the memory region
• ORIGIN(x): Returns the starting address of memory region x
• LENGTH(x): Returns the length of memory region x
• Attributes: r for read, w for write, a for allocatable, x for executable

xxx_ivt_lmr & xxx_ivt_vmr

XWOS’s interrupt vector table region. LMR indicates the load address region of the interrupt vector, i.e., the storage location of the interrupt vector in Flash. VMR indicates the virtual address region of the interrupt vector, i.e., the address of the interrupt vector at runtime upon power-on.

• If both LMR and VMR point to Flash, and the starting address (org) and size (len) are exactly the same, it means the load address is the same as the runtime address, and XWOS will not perform a copy operation on the interrupt vector during the initialization phase;
• If VMR points to an address in RAM, XWOS will copy the interrupt vector table from Flash to the RAM specified by VMR during the initialization phase, and set the ARM VTOR register;
• Note that the lower 7 bits (0-6) of the ARM VTOR register must be kept at 0, so the starting address of VMR must also satisfy this rule.

firmware_info_mr

This section contains some basic information about the image file, such as the start position, end flag position, etc., which can be used in firmware upgrade functionality.

code_mr

Where code and constants are stored.

xwos_data_mr

Where XWOS global data is stored. These variables are defined with the modifier: __xwos_data. This section may not exist. If it does not exist, data in this section needs to be placed in data_mr in the SDL linker script.

data_mr

Where global variables are stored. After the linker ld arranges the global variables, the remaining portion is managed by XWOS’s default kernel memory allocator, providing a dynamic memory allocation interface for APIs that dynamically create kernel objects.

xwos_stk_mr

XWOS kernel stack memory. This memory is used as the function stack when the XWOS kernel handles interrupts.

SoC Initialization

The initialization code generated by STM32CubeMX is executed by stm32cube_lowlevel_init() and stm32cube_init() respectively. These two functions are called by xows_preinit and xwos_postinit() respectively in the Boot Flow.

STM32CubeMX

The STM32CubeMX project is integrated as a board module within an XWOS module. For details, refer to the Build System.

The STM32CubeMX projects for various projects are as follows (can be opened in STM32CubeMX):

• WeActMiniStm32H750 project: XWOS/xwbd/WeActMiniStm32H750/bm/stm32cube/WeActMiniStm32H750.ioc
• WeActMiniStm32H750Bootloader project: XWOS/xwbd/WeActMiniStm32H750Bootloader/bm/stm32cube/WeActMiniStm32H750Bootloader.ioc

Interrupt Priority

• XWOS interrupt priority requirements:

The context switching interrupt is the lowest priority interrupt in the system
Context switching interrupt <= Tick timer interrupt <= Scheduler service interrupt

• NVIC settings:
  • Set 3 preemption priority bits and 1 sub-priority bit;
  • SVC interrupt set to highest priority, i.e., Preemption Priority is 0;
  • PendSV interrupt set to lowest priority, i.e., Preemption Priority is 7;
  • Systick interrupt set to lowest priority, i.e., Preemption Priority is 7;
  • System Fault priority set to 0;
  • Other interrupt priorities can only be between 1~6.

Interrupt Vector Table

The interrupt vector table in the code generated by STM32CubeMX is placed in startup.s. XWOS does not use this file, so an additional interrupt vector table needs to be added. There are too many STM32 models to edit one by one, but observing the STM32 register definition header file (e.g., stm32h750xx.h), you can find the IRQn_Type enum type, which lists all interrupt numbers. Therefore, a script can be used to automatically generate the interrupt vector table code.

This project provides an Emacs-Lisp script XWOS/xwbd/WeActMiniStm32H750/bm/stm32cube/Tools/stm32ivt/stm32ivt.el to accomplish this task. Usage:

cd XWOS/xwbd/WeActMiniStm32H750/bm/stm32cube
stm32ivt/stm32ivt.el

• After the script finishes executing, Core/Src/ivt.c will be generated.

xwac

The board module xwac contains adaptation code, serving as the link between the BSP and XWOS. The ac in the folder name stands for Adaptation Code.

• fatfs: fatfs low-level device driver
• lua: lua memory pool
• newlib: Provides low-level support for the standard C library newlib
  • mem.c: Memory pool for the malloc() family of functions
  • stdio.c: Defines the input device for stdin, and output devices for stdout and stderr
• picolibc: Provides low-level support for the standard C library picolibc
  • mem.c: Memory pool for the malloc() family of functions
  • stdio.c: Defines the input device for stdin, and output devices for stdout and stderr
• xwds: STM32 device stack
• xwlib: Provides low-level hardware support for the XWOS common library, such as using hardware CRC module to accelerate CRC calculations, defining Log output devices, etc.
• xwos: XWOS kernel Hook functions
• xwrust: Rust memory pool