Introduction⌗

Today, the CI test verifying that my OOT Zephyr board still builds against the main branch suddenly failed.

The error originated from twister, and wasn’t entirely unexpected:

ERROR   - platform_filter - unrecognized platform - otterpill

Recently, work has gone into the Hardware Model v2 HWMv2, a redesign of the way Zephyr models boards and SOCs. Thus, i have been waiting for something to break here, which it finally did as HWMv2 just got merged.

I hadn’t looked into the actual changes in HWMv2 before, but from what i gathered board names are now <board>/<soc> to support multi-soc boards? This would explain the failure in finding my OOT board. Looking at the recent commits, there also seem to be aliases for the old (deprecated) names of in-tree boards.

I have also heard about some new (yaml?) description file for boards, which my OOT board must still be missing.

Fortunately, the Board Porting Guide has been updated already to HWMv2.

Bug Fixing⌗

The updated board porting guide states:

A / is used as separator between the board name and the following: SoC, CPU cluster, and variant identifiers.

And:

If a board contains only a single core SoC, then the SoC can be omitted when building.

At first i thought this was referring to the deprecated names i already discovered, but this is not the case. The deprecated names are those where previously, multiple “boards” were used for a single board containing multiple SOCs, or variants of boards. The guide specifies that going forward, the specific SOC on a multi-soc board can be addressed as <board>/<soc>, and to address a specific “cpu cluster” within that SOC, or to specify a board variant, a /<cluster> or /<variant> is further appended.

To migrate my board, I configured a west workspace with the latest zephyr version and my OOT board. Trying to build an example application for the board failed:

west build --board otterpill --pristine=always zephyr/samples/hello_world

[...]

No board named 'otterpill' found.

Please choose one of the following boards:
[...]

west boards also doesn’t list the board, so i took to the board porting guide for updated requirements. I do already have a otterpill.yaml file in my board directory which contains metadata for running tests, but apparently another file board.yml is needed.

THe porting guide shows a lot of possible configuration in this file, but looking at some other boards a minimal configuration seems to be

board:
  name: otterpill
  vendor: Jana-Marie
  socs:
    - name: stm32f072x8

This had some effect, in particular that west boards now showed this error:

ERROR: SoC 'stm32f072x8' is not found, please ensure that the SoC exists and that soc-root containing 'stm32f072x8' has been correctly defined.

I added the stm32f072x8 variant of the STM32F072 to zephyr some time ago for this particular board, and i assume it has just been overlooked in the migration, perhaps because no in-tree board uses it. I quickly located soc/st/stm32/soc.yml where i could add the appropriate entry.

diff --git a/soc/st/stm32/soc.yml b/soc/st/stm32/soc.yml
index 304ab56acf..a3ef60c1dc 100644
--- a/soc/st/stm32/soc.yml
+++ b/soc/st/stm32/soc.yml
@@ -14,6 +14,7 @@ family:
     - name: stm32f051x8
     - name: stm32f070xb
     - name: stm32f072xb
+    - name: stm32f072x8
     - name: stm32f091xc
     - name: stm32f098xx
   - name: stm32f1x

With this change, west boards showed the custom board again! Onwards to building the hello-world example!

Which now went further than before, until stopping with a Kconfig error:

error: SOC_SERIES_STM32F0X (defined at soc/st/stm32/stm32f0x/Kconfig.soc:6,
soc/st/stm32/stm32f0x/Kconfig:6) is assigned in a configuration file, but is not directly user-
configurable (has no prompt). It gets its value indirectly from other symbols. See
http://docs.zephyrproject.org/latest/kconfig.html#CONFIG_SOC_SERIES_STM32F0X and/or look up
SOC_SERIES_STM32F0X in the menuconfig/guiconfig interface. The Application Development Primer,
Setting Configuration Values, and Kconfig - Tips and Best Practices sections of the manual might be
helpful too.

Following other boards and the guide, the Kconfig.board file needs to be changed like this:

diff --git a/boards/arm/otterpill/Kconfig.otterpill b/boards/arm/otterpill/Kconfig.otterpill
index 378f81c..6a23697 100644
--- a/boards/arm/otterpill/Kconfig.otterpill
+++ b/boards/arm/otterpill/Kconfig.otterpill
@@ -2,5 +2,4 @@
 # SPDX-License-Identifier: Apache-2.0
 
 config BOARD_OTTERPILL
-       bool "OtterPill Board"
-       depends on SOC_STM32F072X8
+       select SOC_STM32F072X8

This was however not enough to resolve the Kconfig error, i also had to remove some now unnecessary options from otterpill_defconfig:

diff --git a/boards/arm/otterpill/otterpill_defconfig b/boards/arm/otterpill/otterpill_defconfig
index 68f78f5..87f95de 100644
--- a/boards/arm/otterpill/otterpill_defconfig
+++ b/boards/arm/otterpill/otterpill_defconfig
@@ -1,11 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
 
-# Zephyr Kernel Configuration
-CONFIG_SOC_SERIES_STM32F0X=y
-
-# Platform Configuration
-CONFIG_SOC_STM32F072X8=y
-
 # Serial Drivers
 CONFIG_SERIAL=y
 CONFIG_UART_INTERRUPT_DRIVEN=y

And completely removed Kconfig.defconfig, which only contained the following:

if BOARD_OTTERPILL
config BOARD
	default "otterpill"
endif # BOARD_OTTERPILL

This resolved all the Kconfig errors and allowed the example to build!

TLDR: How to Port a Simple OOT Board⌗

  • Create a file board.yml specifying at least the board name, vendor and SOC (see above for an example)
  • Rename Kconfig.board to Kconfig.<board name>, and change depends on SOC_... to select SOC_...
  • Remove all CONFIG_SOC_... selections from <board name>_defconfig
  • Remove the BOARD config from Kconfig.defconfig