Hardware Model v2 - Ability to extend an existing board

[tejlmand]

Hardware Model v2, https://github.com/zephyrproject-rtos/zephyr/issues/51831 introduces a new scheme for boards.

A board.yml is used to describe meta data of the board, for example:

board:
  name: plank
  vendor: Zephyr
  socs:
  - name: soc1
    variants:
    - name: foo

Such a board allows users to build for:

cmake -DBOARD=plank/soc1
cmake -DBOARD=plank/soc1/foo

The enhancement proposal is to allow extending such a board in another folder.

This would allow out-of-tree users to re-use an existing board but extend it with an extra build variant. A benefit is that it allows existing overlay's and config files to still be picked up for the new variant, but not having to change the core build variant.

One limitation of https://docs.zephyrproject.org/latest/hardware/porting/board_porting.html#board-extensions is the fact that once such an enhancement is added, it's not possible to build without the extension.

The enhancement issue provides the ability to extend the board with new variant, thus having the following benefit:

• Clear to users when building for the upstream board, or when building for the extended variant
• Applications can have overlays / conf files specific to the extra variant, while simultaneously reuse common overlays and conf files for the core board / SoC Note, https://github.com/zephyrproject-rtos/zephyr/pull/71149 remove the merging of overlay and conf files, meaning that a variant created as an extend is no longer merged with base files. Thus it must be possible to describe when a variant want to apply base variant overlay and conf files. It must also be made very clear in the docs that doing so can result in side-effects like #70445 and #70283 if dts nodes are removed in the variant. The current board extension feature suffers the same risk, but without highlighting the risk. However, as this is an opt-in feature, it becomes the responsibility of the board extend author to ensure proper compatibility with samples that the extended board is supposed to work with.

Design idea: Extend the board.yml with a new extend: <name> field, indicating the board which is being extended. This will tell list_boards.py that this is not a new board, but a board which should be merged with the existing board definition.

board:
  extend: plank
  variants:
  - name: bar
    soc: soc1

This defines a new bar board variant which applies to an existing soc soc1 definition in the plank board.

Another use-case is to allow boards to be defined in a tree of sub-folders.

An example of such use-case are the qemu boards. Those are individually defined in their own folder, thus they must each have a unique name, thus ending in situations like this:

-DBOARD=qemu_arc/qemu_arc_em
-DBOARD=qemu_nios2/qemu_nios2

where the arch is repeated for no apparent reason.

Supporting board extensibility will allow to keep qemu boards organized in sub-folders while at the same time present just a highlevel qemu board.

This will also make it easier to see all architectures supported with qemu, as those can now be listed as identifiers for the common board.

Design idea:

Highlevel qemu board:

# board.yml for qemu, no SoCs defined.
board:
  name: qemu

Extend the qemu board with SoCs:

# board.yml for qemu, no SoCs defined.
board:
  extends: qemu
  socs:
  - name: arc_em
  - name: arc_hs
    variants:
    - name: xip
  - name: arc_hs5x
  - name: arc_hs6x

and

board:
  extends: qemu
  socs:
  - name: nios2

Thus making it possible to build for:

-DBOARD=qemu/arc_em
-DBOARD=qemu/nios2

Note the difference between extending a board with a new SoC, and then extending the board with a variant related to a SoC defined in the core board definition.

Challenges:

• BOARD_DIR is not as uniform, which means Kconfig.<board>, Kconfig, and Kconfig.defconfig must be allowed to be sourced from multiple locations.

As part of this implementation, please also address: https://github.com/zephyrproject-rtos/zephyr/pull/70619#discussion_r1536594893

[nordicjm]

A requirement for this being reintroduced is checking for files that have typos in the name as has been seen in boards which were ported to hwmv2. To do this, python code can be created that globs all board.yml files together so a list of boards and soc names can be generated, then a glob of all .dts and _defconfig files in the boards directory can be generated and checked to ensure that all filenames are valid.

[nordicjm]

Issue raised here about board.yml wrongly being named board.yaml and not working, would make sense to have checks in CI for various filenames in board addition PRs: https://github.com/zephyrproject-rtos/zephyr/issues/71240

[cdwilson]

@tejlmand your comment in https://github.com/zephyrproject-rtos/zephyr/issues/71113 pointed me to this issue.

I recently learned about the existence of Snippets and I was wondering if you had considered whether the functionality described above could be achieved via Snippets (I have not used them yet, so I'm not sure of the answer to this).

The design idea you proposed above appears to be hierarchical whereas the Snippets design is composable (the comparison almost reminds me of something like inheritance vs. composition). It got me curious if Snippets could be used to implement this, and if so, whether they might provide more flexibility due to the fact that they are composable by design.

[tejlmand]

I recently learned about the existence of Snippets and I was wondering if you had considered whether the functionality described above could be achieved via Snippets

Some use-cases can be covered by snippets, but not all.

So snippets and board extensions covers different use-cases.