Merge pull request #21764 from crasbe/pr/guides_common_boards

doc/guides: Add Section about Creating a Common Board Directory
2026-01-01 01:41:18 +01:00 · 2025-10-07 14:50:01 +00:00 · 2025-10-07 14:50:01 +00:00 · 7de0d1b89a
commit 7de0d1b89a
parent 6604a97b18 0d578f80fc
1 changed files with 123 additions and 2 deletions
--- a/doc/guides/advanced_tutorials/porting_boards.md
+++ b/doc/guides/advanced_tutorials/porting_boards.md
@ -304,7 +304,9 @@ Then answer a few questions about the driver:
 Other global information (author name, email, organization) should be retrieved
 automatically from your git configuration.

-## Using Common Code
+## Common Board Directories
+
+### Using Common Code

 To avoid code duplication, common code across boards has been grouped in
 `boards/common`. e.g. `BOARD`s based on the same cpu (`boards/common/nrf52`) or
@ -336,6 +338,125 @@ static const timer_conf_t timer_config[] = {
 /** @} */
 ```

+#### New Style Common Code
+
+The common board definitions of RIOT are currently being reworked to make the
+usage of common code easier and less error prone. For example, if you want
+to use the common code for the Adafruit nRF52 Bootloader that is used
+by many of the nRF52 based boards from Adafruit, you simply have to add the
+following line to the `Makefile.dep` of your board. Everything else
+will be automatically included by the build system.
+
+```makefile
+USEMODULE += boards_common_adafruit-nrf52-bootloader
+```
+
+Not all common code is migrated to the new style yet, so if you are unsure
+whether it is or not, you can check if the `boards/Makefile` already
+includes a reference to the common code you want to use. If you are still
+unsure, you can still use the Old Style Common Code or ask the
+community.
+
+#### Old Style Common Code
+
+If you want to use common makefiles, include them at the end of the specific
+`Makefile`, e.g. for a `Makefile.features`:
+
+```makefile
+CPU = foo
+CPU_MODEL = foobar
+# Put defined MCU peripherals here (in alphabetical order)
+FEATURES_PROVIDED += periph_i2c
+FEATURES_PROVIDED += periph_spi
+FEATURES_PROVIDED += periph_uart
+include $(RIOTBOARD)/common/foo_common/Makefile.features
+```
+
+If the common code includes source files, it might be necessary
+to explicitly include the directory in your `Makefile` so the Make system
+finds all the necessary files:
+
+```makefile
+MODULE = board
+
+DIRS += $(RIOTBOARD)/common/myCommonFolder
+
+include $(RIOTBASE)/Makefile.base
+```
+
+If possible, you should use the New Style Common Code though.
+
+### Moving Common Code to a Dedicated Folder
+
+If you port a board that is very similar to an already existing board, it might
+make sense to move the shared code to a common directory located in
+`boards/common` to use it as described in the previous section.
+
+The directory structure of a common folder is very similar to the board
+folder structure and not all files and folders have to be present except for
+the main `Makefile`.
+
+```
+RIOT
+└── boards
+    └── common
+        └── adafruit-nrf52-bootloader
+            ├── board.c
+            ├── doc.md
+            ├── include
+            │   ├── periph_conf.h
+            │   ├── board.h
+            │   └── gpio_params.h
+            ├── Makefile
+            ├── Makefile.dep
+            ├── Makefile.features
+            └── Makefile.include
+```
+
+The main `Makefile` defines the module name for the common board module and
+should follow the general naming scheme of `boards_common_awesome-common-stuff`.
+
+```makefile
+MODULE = boards_common_adafruit-nrf52-bootloader
+
+include $(RIOTBASE)/Makefile.base
+```
+
+The `Makefile.dep`, `Makefile.features` and `Makefile.include` are optional
+and work the same way as their normal board pendants.
+
+To inform the build system about the common folders and Makefiles, the
+`boards/Makefile`, `boards/Makefile.dep`, `boards/Makefile.features` and
+`boards/Makefile.include` files have to be modified.
+
+The `boards/Makefile` contains the directory entries for the common files.
+The entries should check if the common module is used and conditionally add
+the directory to the `DIRS` variable.
+Please note that the entries should be sorted alphabetically.
+```makefile
+# SORT THIS ALPHABETICALLY BY COMMON BOARD NAME!
+...
+ifneq (,$(filter boards_common_adafruit-nrf52-bootloader,$(USEMODULE)))
+  DIRS += $(RIOTBOARD)/common/adafruit-nrf52-bootloader
+endif
+...
+```
+
+The `boards/Makefile.dep`, `boards/Makefile.features` and
+`boards/Makefile.include` just include their common counterparts. As an
+example, an entry of the `boards/Makefile.dep` is shown:
+```makefile
+# SORT THIS ALPHABETICALLY BY COMMON BOARD NAME!
+...
+ifneq (,$(filter boards_common_adafruit-nrf52-bootloader,$(USEMODULE)))
+  include $(RIOTBOARD)/common/adafruit-nrf52-bootloader/Makefile.dep
+endif
+...
+```
+
+You only have to add entries to the `board/Makefile`s if your common code
+actually has the regarding Makefile-type.
+
 ## Boards Outside of RIOTBASE

 All `BOARD`s in RIOT reside in `RIOTBOARD` (`RIOTBOARD` being a make variable
@ -433,5 +554,5 @@ Some scripts and tools available to ease `BOARD` porting and testing:
 - [In her blog](https://blog.martine-lenders.eu/riot-board-en.html), Martine Lenders documented her approach of
  porting the [Adafruit Feather nRF52840 Express](https://doc.riot-os.org/group__boards__adafruit-feather-nrf52840-express.html)
  in February 2020.
- [Over at HackMD][https://hackmd.io/njFHwQ33SNS3sQKAkLkNtQ], Akshai M documented his approach of
+- [Over at HackMD](https://hackmd.io/njFHwQ33SNS3sQKAkLkNtQ), Akshai M documented his approach of
  porting the [Silicon Labs SLSTK3400A starter kit](https://doc.riot-os.org/group__boards__slstk3400a.html) in July 2020.