- C 99.5%
- Assembly 0.2%
- CMake 0.2%
- Linker Script 0.1%
The configuration header is project setup, not conversion history: it is where the HAL module switches and clock constants live, and how every driver reaches them. README is the setup guide; CONVERT keeps the conversion and hardware-check notes. |
||
|---|---|---|
| .vscode | ||
| cmake | ||
| Drivers | ||
| inc | ||
| linker | ||
| src | ||
| startup | ||
| .clangd | ||
| .gitignore | ||
| CMakeLists.txt | ||
| CMakePresets.json | ||
| CONVERT.md | ||
| README.md | ||
XL32F001 — minimum VS Code + CMake template
A minimal, free-toolchain starting point for XL32F001 firmware
(Cortex-M0+, 24 MHz, 24 KiB Flash / 3 KiB RAM), built with
VS Code + CMake + Ninja + arm-none-eabi-gcc + OpenOCD +
Cortex-Debug. No Keil, no PlatformIO, no STM32CubeIDE.
The template is deliberately small: it builds one working bring-up image
that initialises the HAL, sets the clock, initialises the LED pin and
USART1, prints hello at 115200 baud on USART1 TX (PB4), then sits in an
empty loop. That hello is the first hardware test: if it arrives, the
clock, USART pins, baud calculation, startup file and linker script are
all basically right.
What this template aims to be:
- Free tools only. Every part of the build and debug path is open source.
- Minimal, but honest. One working bring-up, not a HAL rewrite. The vendor code is carried over unchanged so you can see what the chip actually does.
- Vendor code stays vendor code.
Drivers/is the PY32F002B CMSIS and HAL exactly as it came from the original project; the template does not patch it. - One convention for your code. Every user
.cfile lives insrc/and every user.hfile lives ininc/. Vendor headers are the only exception. - Plain CMake. No generated build system and no hidden magic: the
source list, flags and linker script are all readable in
CMakeLists.txt. - Known limits are written down. The build is verified, but the chip behaviour is inherited from PY32F002B and has not been validated on XL32F001 hardware here. The exact assumptions to check are in CONVERT.md.
Requirements
arm-none-eabi-gcc(for example Ubuntu:sudo apt install gcc-arm-none-eabi)- CMake 3.22 or newer, and Ninja
- OpenOCD and an SWD probe (ST-Link, DAPLink, or J-Link) for flashing
- VS Code extensions: CMake Tools, clangd, Cortex-Debug (VS Code
suggests them from
.vscode/extensions.json)
Build and flash
From VS Code
- Open this folder in VS Code.
- CMake Tools asks for a kit/preset: pick the debug preset.
- Build with the CMake Tools build button, or the task CMake: configure + build.
- Flash with the task Flash: OpenOCD + ST-Link (try stm32f0x target first). Before the first flash, run Flash: OpenOCD, probe only (check the chip answers before flashing) first.
- Open a serial terminal at 115200 baud, 8N1, on USART1 TX (PB4).
You should see:
hello
From a terminal
cmake --preset debug
cmake --build --preset debug
To flash:
openocd -f interface/stlink.cfg -f target/stm32f0x.cfg \
-c "program build/xl32f001.elf verify reset exit"
To only check that the probe and target answer:
openocd -f interface/stlink.cfg -f target/stm32f0x.cfg \
-c "init; halt; flash probe 0; exit"
Build outputs
Everything lands in build/:
xl32f001.elf— the debug/flash imagexl32f001.bin,xl32f001.hex— generated next to the.elfxl32f001.map— linker mapcompile_commands.json— used by clangd for IntelliSense
build/ is gitignored; it is safe to delete and rebuild.
Project layout
src/ all user C sources (main, user modules, PY32 project files)
inc/ all user headers, plus py32f002b_hal_conf.h (HAL config)
Drivers/ vendor CMSIS + PY32F002B HAL, verbatim — do not edit
startup/ GCC startup file and vector table
linker/ xl32f001_flash.ld (24 KiB Flash / 3 KiB RAM)
cmake/ arm-none-eabi toolchain file
.vscode/ build/flash tasks, Cortex-Debug launch, clangd settings
CMakeLists.txt, CMakePresets.json
The rule for adding code is simply:
- a new
.cfile goes insrc/and is added to theadd_executablelist inCMakeLists.txt; - a new
.hfile goes ininc/, which is already on the include path.
The HAL configuration header
inc/py32f002b_hal_conf.h is not application code. It is the HAL's
configuration header (the PY32F002B equivalent of ST's
stm32f0xx_hal_conf.h), and it must keep that exact name and stay on the
include path; inc/ is already there.
Every HAL driver reaches it through the umbrella header, and py32f0xx.h
includes that umbrella because USE_HAL_DRIVER is defined in
CMakeLists.txt:
py32f0xx_hal.h -> py32f002b_hal_conf.h -> the enabled py32f002b_hal_*.h
The HAL_<X>_MODULE_ENABLED switches near the top choose which peripheral
drivers are pulled in. The rest of the file holds the clock constants
(HSE_VALUE, HSI_VALUE, ...) and USE_FULL_ASSERT.
To disable a module, comment out its switch and remove its driver
.c from CMakeLists.txt: the driver gets its types from the umbrella
and will not compile once its header is no longer included.
The #include "py32f002b_hal_*.h" lines at the bottom are module
selection, not direct dependencies of this file. Because they are
side-effect includes, clangd's unused-include check is disabled for this
file in .clangd; deleting them, as its warning suggests, would break
the HAL.
Tooling notes
- IntelliSense comes from clangd, reading
build/compile_commands.json. The Microsoft C/C++ extension's IntelliSense is disabled in.vscode/settings.json, because the two engines fight over the same files. Keep it disabled. - The CMake preset is called
debugand uses Ninja pluscmake/arm-none-eabi.cmake. To configure by hand, pass-DCMAKE_TOOLCHAIN_FILE=cmake/arm-none-eabi.cmake. - The build uses
-Og -g3 -Wall -Wextrawith-ffunction-sections -fdata-sectionsand--gc-sections, so unused HAL functions are dropped at link time. .binand.hexare produced by a post-build step, so they always match the.elf.
Troubleshooting
- Build fails with "arm-none-eabi-gcc not found": install the
toolchain and make sure it is on
PATHbefore opening VS Code, or CMake Tools will cache a host compiler. - Linker error "section will not fit": your code outgrew 24 KiB Flash / 3 KiB RAM, or your chip is smaller than the linker script assumes. Check the memory-size item under CHECK in CONVERT.md before editing the script.
- Warnings about
_close,_fstat,_isatty,_lseek,_readnot implemented: expected. They come fromnosys.specsand only matter if you use file I/O beyondprintf(which uses_write(), implemented insrc/User_USART1.c). The vendor HAL also emits a few unused-parameter warnings; they are in the original code and are harmless. - Build succeeds, but the board stays silent or prints garbage: that is a hardware assumption, not a build problem. See the bring-up section of CONVERT.md.
Background and hardware caveats
The template was converted from a Keil project that targeted a PY32F002B-class part; no XL32F001 datasheet was available. The build is verified, but the chip's trim addresses, pinout, clock tree, register map, flash algorithm and option bytes are still assumptions.
CONVERT.md records:
- what the original project did and what was removed (the 433 receiver);
- how to restore the 433 receiver later;
- the original pin map and clock setup;
- where every file came from, and what was translated rather than copied;
- the CHECK list — every XL32F001 assumption you should verify against your datasheet and board;
- hardware bring-up troubleshooting;
- the build verification snapshot.