Zephyr RTOS dts and overlay Search Order

 

Zephyr RTOS dts and overlay Search Order

The build system (CMake + west build) determines which overlay files are picked up, and in what order, using a priority search scheme.






Various ways of adding overlay files to the build

Explicitly provided overlays

If you pass overlays on the command line or via CMake variables, these always take priority:

  • west build -b <board> -- -DDTC_OVERLAY_FILE="my.overlay;other.overlay"

  • Or in your CMakeLists.txt:

    set(DTC_OVERLAY_FILE "my.overlay")

These are applied first in the order you list them. Ex: my.overlay is applied first then other.overlay

If DTC_OVERLAY_FILE is passed as an argument, then automatic overlay discovery is stopped.


Board definition overlays from the Zephyr tree or modules

If your board (from Zephyr boards/ or a module) itself ships an overlay, it is applied unless overridden by your app’s overlays. Example:

  • ${ZEPHYR_BASE}/boards/arm/nucleo_h563zi/nucleo_h563zi.overlay


The overlay discovered in this method will be accumulated together, it is not just one overlay.

And they will also be accumulated again with. overlays files discovered in the application directory's boards/ overlays.

Application directory overlays

Inside your /app folder, Zephyr will look for board-specific and generic overlays:

  • ${APP_DIR}/boards/<BOARD>.overlay

  • ${APP_DIR}/boards/<BOARD>/<BOARD>.overlay

If your board is nucleo_h563zi, these would be:

  • /app/boards/nucleo_h563zi.overlay

  • /app/boards/nucleo_h563zi/nucleo_h563zi.overlay

 The overlay discovered in this method will be accumulated together plus the accumulated overlays found in the Zephyr tree and Modules previously.

Application-level BOARD.overlay

If there were no overlays found in zephyr tree, modules or the application directory's boards/ overlays then it will be looking for BOARD.overlay file. If this file exists, this overlay file will be used. If this file is also not present, then it will go to the next step. which is the Application-level default overlay.

Application-level default overlay

If present:

  • /app/app.overlay

If a there were no board or SOC specific overlays found to this point then app.overlay will be used.

Comments

Post a Comment