kaspar/RIOT
1
0
Fork 0
mirror of https://github.com/RIOT-OS/RIOT.git synced 2025-12-14 17:13:50 +01:00
Code Releases Activity

doc/guides/porting-boards: add section about creating common boards

Browse Source
This commit is contained in:
crasbe 2025-10-07 14:20:52 +02:00
parent 658d8d8095
commit ad1eab6e4d
1 changed files with 74 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
doc/guides/advanced_tutorials/porting_boards.md
View File

@ -304,7 +304,9 @@ Then answer a few questions about the driver:
Other global information (author name, email, organization) should be retrieved Other global information (author name, email, organization) should be retrieved
automatically from your git configuration. 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 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 `boards/common`. e.g. `BOARD`s based on the same cpu (`boards/common/nrf52`) or
@ -336,6 +338,77 @@ static const timer_conf_t timer_config[] = {
/** @} */ /** @} */
``` ```
### 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 ## Boards Outside of RIOTBASE
All `BOARD`s in RIOT reside in `RIOTBOARD` (`RIOTBOARD` being a make variable All `BOARD`s in RIOT reside in `RIOTBOARD` (`RIOTBOARD` being a make variable