Flashing configuration

Zephyr supports setting up configuration for flash runners (invoked from west flash) which allows for customising how commands are used when programming boards. This configuration is used for Sysbuild (System build) projects and allows for configuring when commands are ran for groups of board targets. As an example: a multi-core SoC might want to only allow the --erase argument to be used once for all of the cores in the SoC which would prevent multiple erase tasks running in a single west flash invocation, which could wrongly clear the memory which is used by the other images being programmed.

Priority

Flashing configuration is singular, it will only be read from a single location, this configuration can reside in the following files starting with the highest priority:

• soc.yml (in soc folder)

• board.yml (in board folder)

Configuration

Configuration is applied in the yml file by using a runners map with a single run_once child, this then contains a map of commands as they would be provided to the flash runner e.g. --reset followed by a list which specifies the settings for each of these commands (these are grouped by flash runner, and by qualifiers/boards). Commands have associated runners that they apply to using a runners list value, this can contain all if it applies to all runners, otherwise must contain each runner that it applies to using the runner-specific name. Groups of board targets can be specified using the groups key which has a list of board target sets. Board targets are regular expression matches, for soc.yml files each set of board targets must be in a qualifiers key (only regular expression matches for board qualifiers are allowed, board names must be omitted from these entries). For board.yml files each set of board targets must be in a boards key, these are lists containing the matches which form a singular group. A final parameter run can be set to first which means that the command will be ran once with the first image flashing process per set of board targets, or to last which will be ran once for the final image flash per set of board targets.

An example flashing configuration for a soc.yml is shown below in which the --recover command will only be used once for any board targets which used the nRF5340 SoC application or network CPU cores, and will only reset the network or application core after all images for the respective core have been flashed.

runners:
  run_once:
    '--recover':
      - run: first
        runners:
          - nrfjprog
        groups:
          - qualifiers:
              - nrf5340/cpunet
              - nrf5340/cpuapp
              - nrf5340/cpuapp/ns
    '--reset':
      - run: last
        runners:
          - nrfjprog
          - jlink
        groups:
          - qualifiers:
              - nrf5340/cpunet
          - qualifiers:
              - nrf5340/cpuapp
              - nrf5340/cpuapp/ns
      # Made up non-real world example to show how to specify different options for different
      # flash runners
      - run: first
        runners:
          - some_other_runner
        groups:
          - qualifiers:
              - nrf5340/cpunet
          - qualifiers:
              - nrf5340/cpuapp
              - nrf5340/cpuapp/ns

Usage

Commands that are supported by flash runners can be used as normal when flashing non-sysbuild applications, the run once configuration will not be used. When flashing a sysbuild project with multiple images, the flash runner run once configuration will be applied.

For example, building the SMP server sample for the nrf5340dk which will include MCUboot as a secondary image:

cmake -GNinja -Sshare/sysbuild/ -Bbuild -DBOARD=nrf5340dk/nrf5340/cpuapp -DAPP_DIR=samples/subsys/mgmt/mcumgr/smp_svr
cmake --build build

Once built with an nrf5340dk connected, the following command can be used to flash the board with both applications and will only perform a single device recovery operation when programming the first image:

west flash --recover

If the above was ran without the flashing configuration, the recovery process would be ran twice and the device would be unbootable.