Use official STM32 SDK for stm32 builds instead of libopencm3

AtomVM now supports the following STM32 families:
- stm32f2xx
- stm32f4xx (was supported by libopencm3)
- stm32f7xx (was supported by libopencm3)
- stm32g0xx
- stm32g4xx
- stm32h5xx
- stm32h7xx
- stm32l4xx
- stm32l5xx
- stm32u3xx
- stm32wbxx

Signed-off-by: Paul Guyot <pguyot@kallisys.net>

Author: pguyot

.github/workflows/stm32-build.yaml

@@ -14,13 +14,15 @@ on:
       - 'CMakeModules/**'
       - 'src/platforms/stm32/**'
       - 'src/libAtomVM/**'
+      - 'libs/**'
   pull_request:
     paths:
       - '.github/workflows/stm32-build.yaml'
       - 'CMakeLists.txt'
       - 'CMakeModules/**'
       - 'src/platforms/stm32/**'
       - 'src/libAtomVM/**'
+      - 'libs/**'
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/main' && github.ref || github.run_id }}
@@ -34,17 +36,63 @@ jobs:
       contents: read
       security-events: write
 
-    steps:
-    - uses: actions/cache@v4
-      id: builddeps-cache
-      with:
-        path: |
-              /home/runner/libopencm3
-        key: ${{ runner.os }}-build-deps
+    strategy:
+      fail-fast: false
+      matrix:
+        device:
+          - stm32f411ceu6
+          - stm32h743vit6
+          - stm32u585ait6q
+          - stm32wb55rg
+          - stm32h562rgt6
+          - stm32f746zgt6
+          - stm32g474ret6
+          - stm32l476rgt6
+          - stm32l562qei6
+          - stm32f207zgt6
+          - stm32u375rgt6
+          - stm32g0b1ret6
+        include:
+          - device: stm32f411ceu6
+            max_size: 393216
+            renode_platform: stm32f4.repl
+            avm_address: "0x08060000"
+          - device: stm32h743vit6
+            max_size: 524288
+            renode_platform: stm32h743.repl
+            avm_address: "0x08080000"
+          - device: stm32u585ait6q
+            max_size: 524288
+          - device: stm32wb55rg
+            max_size: 524288
+          - device: stm32h562rgt6
+            max_size: 524288
+          - device: stm32f746zgt6
+            max_size: 524288
+            renode_platform: stm32f746.repl
+            avm_address: "0x08080000"
+          - device: stm32g474ret6
+            max_size: 393216
+          - device: stm32l476rgt6
+            max_size: 524288
+          - device: stm32l562qei6
+            max_size: 393216
+            renode_platform: stm32l562.repl
+            avm_address: "0x08060000"
+          - device: stm32f207zgt6
+            max_size: 524288
+          - device: stm32u375rgt6
+            max_size: 524288
+          - device: stm32g0b1ret6
+            max_size: 393216
+            renode_platform: stm32g0b1.repl
+            avm_address: "0x08060000"
 
+    steps:
     - uses: erlef/setup-beam@v1
       with:
-        otp-version: "27"
+        otp-version: "28"
+        rebar3-version: "3.25.1"
         hexpm-mirrors: |
           https://builds.hex.pm
           https://repo.hex.pm
@@ -54,42 +102,91 @@ jobs:
       run: sudo apt update
 
     - name: "Install deps"
-      run: sudo apt install -y cmake gperf gcc-arm-none-eabi
+      run: sudo apt install -y cmake ninja-build gperf python3-pip && pip3 install meson
 
-    - name: Checkout and build libopencm3
-      if: ${{ steps.builddeps-cache.outputs.cache-hit != 'true' }}
-      working-directory: /home/runner
+    - name: "Install ARM GNU Toolchain"
       run: |
-        set -euo pipefail
-        cd /home/runner
-        test -d libopencm3 && rm -fr libopencm3
-        git clone https://github.com/libopencm3/libopencm3.git -b v0.8.0
-        cd libopencm3
-        make
+        wget -q https://developer.arm.com/-/media/Files/downloads/gnu/15.2.rel1/binrel/arm-gnu-toolchain-15.2.rel1-x86_64-arm-none-eabi.tar.xz
+        tar xJf arm-gnu-toolchain-15.2.rel1-x86_64-arm-none-eabi.tar.xz -C /opt
+        echo "/opt/arm-gnu-toolchain-15.2.rel1-x86_64-arm-none-eabi/bin" >> $GITHUB_PATH
 
     - name: Checkout repo
       uses: actions/checkout@v4
 
-    - name: "Git config safe.directory for codeql"
-      run: git config --global --add safe.directory /__w/AtomVM/AtomVM
-
-    - name: "Initialize CodeQL"
-      uses: github/codeql-action/init@v4
-      with:
-        languages: 'cpp'
-        build-mode: manual
-        queries: +./code-queries/term-to-non-term-func.ql,./code-queries/non-term-to-term-func.ql,./code-queries/mismatched-atom-string-length.ql,./code-queries/mismatched-free-type.ql,./code-queries/term-use-after-gc.ql
-
-    - name: Build
+    - name: "Build for ${{ matrix.device }}"
       shell: bash
       working-directory: ./src/platforms/stm32/
       run: |
         set -euo pipefail
         mkdir build
         cd build
-        # -DAVM_WARNINGS_ARE_ERRORS=ON
-        cmake .. -DCMAKE_TOOLCHAIN_FILE=cmake/arm-toolchain.cmake -DLIBOPENCM3_DIR=/home/runner/libopencm3
-        make -j
+        cmake .. -G Ninja -DCMAKE_TOOLCHAIN_FILE=cmake/arm-toolchain.cmake -DDEVICE=${{ matrix.device }}
+        cmake --build .
+
+    - name: "Check firmware size for ${{ matrix.device }}"
+      shell: bash
+      working-directory: ./src/platforms/stm32/build
+      run: |
+        set -euo pipefail
+        ELF="AtomVM-${{ matrix.device }}.elf"
+        SIZES=$(arm-none-eabi-size "$ELF" | tail -1)
+        TEXT=$(echo "$SIZES" | awk '{print $1}')
+        DATA=$(echo "$SIZES" | awk '{print $2}')
+        FLASH_USED=$((TEXT + DATA))
+        MAX=${{ matrix.max_size }}
+        echo "Firmware flash usage: ${FLASH_USED} bytes ($(( FLASH_USED / 1024 )) KB)"
+        echo "Flash limit: ${MAX} bytes ($(( MAX / 1024 )) KB)"
+        if [ "$FLASH_USED" -gt "$MAX" ]; then
+          echo "::error::Firmware too large: ${FLASH_USED} bytes exceeds ${MAX} byte limit for ${{ matrix.device }}"
+          exit 1
+        fi
+        echo "OK: ${FLASH_USED} / ${MAX} bytes ($(( FLASH_USED * 100 / MAX ))% used)"
+
+    - name: Build host AtomVM and test AVMs
+      if: matrix.renode_platform
+      run: |
+        set -euo pipefail
+        mkdir build-host
+        cd build-host
+        cmake .. -G Ninja
+        cmake --build . -t stm32_boot_test stm32_gpio_test
+
+    - name: Install Renode
+      if: matrix.renode_platform
+      run: |
+        set -euo pipefail
+        mkdir -p renode-portable
+        wget -qO- https://builds.renode.io/renode-latest.linux-portable.tar.gz \
+          | tar -xzf - -C renode-portable --strip-components=1
+        echo "$PWD/renode-portable" >> $GITHUB_PATH
+        pip install -r renode-portable/tests/requirements.txt
 
-    - name: "Perform CodeQL Analysis"
-      uses: github/codeql-action/analyze@v4
+    - name: Run Renode boot test
+      if: matrix.renode_platform
+      run: |
+        LOCAL_REPL="src/platforms/stm32/tests/renode/${{ matrix.renode_platform }}"
+        if [ -f "$LOCAL_REPL" ]; then
+          PLATFORM="@$PWD/$LOCAL_REPL"
+        else
+          PLATFORM="@platforms/cpus/${{ matrix.renode_platform }}"
+        fi
+        renode-test src/platforms/stm32/tests/renode/stm32_boot_test.robot \
+          --variable ELF:@$PWD/src/platforms/stm32/build/AtomVM-${{ matrix.device }}.elf \
+          --variable AVM:@$PWD/build-host/src/platforms/stm32/tests/test_erl_sources/stm32_boot_test.avm \
+          --variable AVM_ADDRESS:${{ matrix.avm_address }} \
+          --variable PLATFORM:$PLATFORM
+
+    - name: Run Renode GPIO test
+      if: matrix.renode_platform
+      run: |
+        LOCAL_REPL="src/platforms/stm32/tests/renode/${{ matrix.renode_platform }}"
+        if [ -f "$LOCAL_REPL" ]; then
+          PLATFORM="@$PWD/$LOCAL_REPL"
+        else
+          PLATFORM="@platforms/cpus/${{ matrix.renode_platform }}"
+        fi
+        renode-test src/platforms/stm32/tests/renode/stm32_gpio_test.robot \
+          --variable ELF:@$PWD/src/platforms/stm32/build/AtomVM-${{ matrix.device }}.elf \
+          --variable AVM:@$PWD/build-host/src/platforms/stm32/tests/test_erl_sources/stm32_gpio_test.avm \
+          --variable AVM_ADDRESS:${{ matrix.avm_address }} \
+          --variable PLATFORM:$PLATFORM

CHANGELOG.md

@@ -70,6 +70,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added initial support for ESP32C5 and ESP32C61
 - Added `Range:size/1`
 - Added missing `ledc` functions for esp32 platform
+- Added support for 10 new STM32 families by switching to STM32 official SDK
 
 ### Changed
 

CMakeLists.txt

@@ -86,6 +86,7 @@ add_subdirectory(tools/uf2tool)
 if (NOT "${CMAKE_GENERATOR}" MATCHES "Xcode")
     add_custom_target(dialyzer COMMENT "Run dialyzer")
     add_subdirectory(libs)
+    add_subdirectory(src/platforms/stm32/tests/test_erl_sources)
     if(NOT AVM_BUILD_RUNTIME_ONLY)
         add_subdirectory(examples)
         add_subdirectory(doc)

README.Md

@@ -17,7 +17,7 @@ Supported Platforms
 
 * Linux, macOS, FreeBSD, DragonFly ([generic_unix](https://doc.atomvm.org/main/getting-started-guide.html#getting-started-on-the-generic-unix-platform))
 * ESP32 SoC (with IDF/FreeRTOS, see [esp32](https://doc.atomvm.org/main/getting-started-guide.html#getting-started-on-the-esp32-platform))
-* STM32 MCUs (with LibOpenCM3, see [stm32](https://doc.atomvm.org/main/getting-started-guide.html#getting-started-on-the-stm32-platform))
+* STM32 MCUs (with official ST HAL/LL SDK, see [stm32](https://doc.atomvm.org/main/getting-started-guide.html#getting-started-on-the-stm32-platform))
 * Raspberry Pi Pico and Pico 2 (see [rp2](https://doc.atomvm.org/main/getting-started-guide.html#getting-started-on-the-raspberry-pi-pico-platform))
 * Browsers and NodeJS with WebAssembly (see [emscripten](https://doc.atomvm.org/main/getting-started-guide.html#getting-started-with-atomvm-webassembly))
 

doc/src/build-instructions.md

@@ -707,39 +707,21 @@ To add support for a new peripheral or protocol using an AtomVM port, you need t
 
 ## Building for STM32
 
+This section describes building AtomVM using the official ST HAL/LL SDK, which is downloaded automatically via CMake FetchContent. This platform supports STM32F2, STM32F4, STM32F7, STM32G0, STM32G4, STM32H5, STM32H7, STM32L4, STM32L5, STM32U3, STM32U5, and STM32WB families.
+
 ### STM32 Prerequisites
 
 The following software is required to build AtomVM for the STM32 platform:
 
-* [11.3 ARM toolchain](https://developer.arm.com/-/media/Files/downloads/gnu/11.3.rel1/binrel/arm-gnu-toolchain-11.3.rel1-x86_64-arm-none-eabi.tar.xz) (or compatible with your system)
-* [libopencm3](https://github.com/libopencm3/libopencm3.git) version 0.8.0
-* `cmake`
-* `make`
+* ARM toolchain (`arm-none-eabi-gcc`, e.g. 11.3 or later)
+* `cmake` (3.13 or later)
+* `meson`
+* `ninja`
 * `git`
-* `python`
 * Erlang/OTP `escript`
 
 ```{note}
-AtomVM tests this build on the latest Ubuntu github runner.
-```
-
-### Setup libopencm3
-
-Before building for the first time you need to have a compiled clone of the libopencm3 libraries, from inside the AtomVM/src/platforms/stm32 directory:
-
-```shell
-$ git clone -b v0.8.0 https://github.com/libopencm3/libopencm3.git
-$ cd libopencm3 && make -j4 && cd ..
-```
-
-```{tip}
-You can put libopencm3 wherever you want on your PC as long as you update LIBOPENCM3_DIR to point to it. This
-example assumes it has been cloned into /opt/libopencm3 and built. From inside the AtomVM/src/platforms/stm32
-directory:
-
-    $ cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/arm-toolchain.cmake \
-    -DLIBOPENCM3_DIR=/opt/libopencm3 ..
-
+No external SDK download is required. The STM32 HAL/LL drivers and CMSIS headers are fetched automatically by CMake during the build. AtomVM is built with `picolibc` which is also downloaded as part of the build and requires `meson` and `ninja`.
 ```
 
 ### Build AtomVM with cmake toolchain file
@@ -749,14 +731,32 @@ $ cd <atomvm-source-tree-root>
 $ cd src/platforms/stm32
 $ mkdir build
 $ cd build
-$ cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/arm-toolchain.cmake ..
-$ make
+$ cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=../cmake/arm-toolchain.cmake -DDEVICE=stm32f411ceu6 ..
+$ ninja
 ```
 
 ### Changing the target device
 
-The default build is based on the STM32F4Discovery board chip (`stm32f407vgt6`). If you want to target a different
-chip, pass the `-DDEVICE` flag when invoking cmake. For example, to use the BlackPill V2.0, pass `-DDEVICE=stm32f411ceu6`. At this time any `STM32F4` or `STM32F7` device with 512KB or more of on package flash should work with AtomVM. If an unsupported device is passed with the `DEVICE` parameter the configuration will fail. For devices with either 512KB or 768KB of flash the available application flash space will be limited to 128KB. Devices with only 512KB of flash may also suffer from slightly reduced performance because the compiler must optimize for size rather than performance.
+The default build targets the BlackPill (`stm32f411ceu6`). Pass the `-DDEVICE` flag to select a different device. Supported families and example devices:
+
+| Family | Example Devices | Max Clock |
+|--------|----------------|-----------|
+| STM32F2 | `stm32f205rgt6`, `stm32f207zgt6` | 120 MHz |
+| STM32F4 | `stm32f411ceu6`, `stm32f401ceu6`, `stm32f407vgt6`, `stm32f429zit6` | 84-180 MHz |
+| STM32F7 | `stm32f746zgt6`, `stm32f767zit6` | 216 MHz |
+| STM32G0 | `stm32g0b1ret6` | 64 MHz |
+| STM32G4 | `stm32g474ret6`, `stm32g491ret6` | 170 MHz |
+| STM32H5 | `stm32h562rgt6` | 250 MHz |
+| STM32H7 | `stm32h743vit6` | 480 MHz |
+| STM32L4 | `stm32l476rgt6`, `stm32l4r5zit6` | 80-120 MHz |
+| STM32L5 | `stm32l552ret6` | 110 MHz |
+| STM32U3 | `stm32u375rgt6`, `stm32u385rgt6` | 96 MHz |
+| STM32U5 | `stm32u585ait6q` | 160 MHz |
+| STM32WB | `stm32wb55rg` | 64 MHz |
+
+If an unsupported device is passed with the `DEVICE` parameter the configuration will fail.
+
+For devices with 512KB or less of flash, application flash space will be limited and the compiler optimizes for size rather than performance.
 
 ```{attention}
 For devices with only 512KB of flash the application address is different and must be adjusted when flashing your
@@ -766,7 +766,9 @@ devices is `0x8060000`.
 
 ### Configuring the Console
 
-The default build for any `DEVICE` will use `USART2` and output will be on `PA2`. This default will work well for most `Discovery` and generic boards that do not have an on-board TTL to USB-COM support (including the `stm32f411ceu6` A.K.A. `BlackPill V2.0`). For `Nucleo` boards that do have on board UART to USB-COM support you may pass the `cmake` parameter `-DBOARD=nucleo` to have the correct USART and TX pins configured automatically. The `Nucleo-144` series use `USART3` and `PD8`, while the supported `Nucleo-64` boards use `USART2`, but passing the `BOARD` parameter along with `DEVICE` will configure the correct `USART` for your model. If any other boards are discovered to have on board USB UART support pull requests, or opening issues with the details, are more than welcome.
+By default, stdout and stderr are printed on the configured console USART. Baudrate is 115200 and serial transmission is 8N1 with no flow control.
+
+The default console is `USART1` on `PA9`. For `Nucleo` boards, pass `-DBOARD=nucleo` to automatically select the correct USART for your board.
 
 Example to configure a `NUCLEO-F429ZI`:
 
@@ -777,16 +779,44 @@ $ cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/arm-toolchain.cmake -DDEVICE=stm32f429zi
 
 The AtomVM system console `USART` may also be configured to a specific uart peripheral. Pass one of the parameters from the chart below with the `cmake` option `-DAVM_CFG_CONSOLE=CONSOLE_#`, using the desired console parameter in place of `CONSOLE_#`. Not all UARTs are available on every supported board, but most will have several options that are not already used by other on board peripherals. Consult your data sheets for your device to select an appropriate console.
 
-| Parameter | USART | TX Pin | AtomVM Default | Nucleo-144 | Nucleo-64 |
-|-----------|-------|--------|----------------|------------|-----------|
-| `CONSOLE_1` | `USART1` | `PA9` |   |   |   |
-| `CONSOLE_2` | `USART2` | `PA2` | ✅ |   | ✅ |
+| Parameter | USART | TX Pin | Default | Nucleo-144 | Nucleo-64 |
+|-----------|-------|--------|---------|------------|-----------|
+| `CONSOLE_1` | `USART1` | `PA9` | ✅ |   |   |
+| `CONSOLE_2` | `USART2` | `PA2` |   |   | ✅ |
 | `CONSOLE_3` | `USART3` | `PD8` |   | ✅ |   |
 | `CONSOLE_4` | `UART4` | `PC10` |   |   |   |
 | `CONSOLE_5` | `UART5` | `PC12` |   |   |   |
 | `CONSOLE_6` | `USART6` | `PC6` |   |   |   |
-| `CONSOLE_7` | `UART7` | `PF7` |   |   |   |
-| `CONSOLE_8` | `UART8` | `PJ8` |   |   |   |
+
+### Configuring the HSE frequency
+
+The external oscillator (HSE) frequency varies between boards. Set it at build time with `-DAVM_HSE_VALUE=<freq_hz>`:
+
+```shell
+$ cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/arm-toolchain.cmake -DDEVICE=stm32f407vgt6 \
+  -DAVM_HSE_VALUE=8000000 ..
+```
+
+Default HSE values per family (set in the family HAL configuration header):
+
+| Family | Default HSE | Typical Boards |
+|--------|-------------|----------------|
+| STM32F2 | 8 MHz | Nucleo boards |
+| STM32F4 | 25 MHz | BlackPill boards |
+| STM32F7 | 8 MHz | Nucleo boards (ST-Link MCO bypass) |
+| STM32G0 | 8 MHz | |
+| STM32G4 | 8 MHz | Nucleo boards |
+| STM32H5 | 8 MHz | Nucleo boards (ST-Link MCO bypass), WeAct Studio H562 |
+| STM32H7 | 8 MHz | Nucleo boards (ST-Link MCO bypass), WeAct Studio H743 (25 MHz) |
+| STM32L4 | 8 MHz | Nucleo boards |
+| STM32L5 | N/A (uses MSI) | Nucleo boards |
+| STM32U3 | 16 MHz | Nucleo boards |
+| STM32U5 | 16 MHz | Nucleo-U585AI-Q, WeAct Studio U585 (25 MHz) |
+| STM32WB | 32 MHz | Nucleo-WB55, WeAct Studio WB55 (required for BLE radio) |
+
+```{note}
+Not all STM32 families have been tested on hardware. The F4, H5, H7, U5, and WB families have been tested on actual boards. The F2, F7, G0, G4, L4, L5, and U3 families are supported in the build system but have not yet been validated on hardware. If you encounter issues with an untested family, please open an [issue on GitHub](https://github.com/atomvm/AtomVM/issues).
+```
 
 ### Configure STM32 logging with `cmake`
 
@@ -803,19 +833,6 @@ For log entries colorized by log level pass `-DAVM_ENABLE_LOG_COLOR=on` to cmake
 
 By default only `ERROR` messages contain file and line number information. This can be included with all log entries by passing `-DAVM_ENABLE_LOG_LINES=on` to cmake, but it does incur a significant performance penalty and is only suggested for debugging during development.
 
-### Console Printing on STM32
-
-AtomVM is built with standard `newlib` to support `long long` integers (`signed` and `unsigned`). If you are building for a device with extremely limited flash space the `nano` version of `newlib` can be used instead. This may be done by passing `-DAVM_NEWLIB_NANO=on`. If the `nano newlib` is used logs will be automatically disabled, this is because many of the VM low level log messages will include `%ull` formatting and will cause buffer overflows and crash the VM if logging is not disabled for `nano newlib` builds. The total flash savings of using `nano newlib` and disabling logs is just under 40kB.
-
-By default, stdout and stderr are printed on USART2. On the STM32F4Discovery board, you can see them
-using a TTL-USB with the TX pin connected to board's pin PA2 (USART2 RX). Baudrate is 115200 and serial transmission
-is 8N1 with no flow control.
-
-```{seealso}
-If building for a different target USART may be configure as explained above in
-[Configuring the Console](#configuring-the-console).
-```
-
 ### Configuring deployment builds for STM32
 
 After your application has been tested (_and debugged_) and is ready to put into active use you may want to tune the build of AtomVM.  For instance disabling logging with `-DAVM_LOG_DISABLE=on` as a `cmake` configuration option may result in slightly better performance. This will have no affect on the console output of your application, just disable low level log messages from the AtomVM system. You may also want to enabling automatic reboot in the case that your application ever exits with a return other than `ok`. This can be enabled with the `cmake` option `-DAVM_CONFIG_REBOOT_ON_NOT_OK=on`.