1.. _flashing-soc-board-config:
2
3Flashing configuration
4######################
5
6Zephyr supports setting up configuration for flash runners (invoked from
7:ref:`west flash<west-flashing>`) which allows for customising how commands are used when
8programming boards. This configuration is used for :ref:`sysbuild` projects and allows for
9configuring when commands are ran for groups of board targets. As an example: a multi-core SoC
10might want to only allow the ``--erase`` argument to be used once for all of the cores in the SoC
11which would prevent multiple erase tasks running in a single ``west flash`` invocation, which
12could wrongly clear the memory which is used by the other images being programmed.
13
14Priority
15********
16
17Flashing configuration is singular, it will only be read from a single location, this
18configuration can reside in the following files starting with the highest priority:
19
20 * ``soc.yml`` (in soc folder)
21 * ``board.yml`` (in board folder)
22
23Configuration
24*************
25
26Configuration is applied in the yml file by using a ``runners`` map with a single ``run_once``
27child, this then contains a map of commands as they would be provided to the flash runner e.g.
28``--reset`` followed by a list which specifies the settings for each of these commands (these
29are grouped by flash runner, and by qualifiers/boards). Commands have associated runners that
30they apply to using a ``runners`` list value, this can contain ``all`` if it applies to all
31runners, otherwise must contain each runner that it applies to using the runner-specific name.
32Groups of board targets can be specified using the ``groups`` key which has a list of board
33target sets. Board targets are regular expression matches, for ``soc.yml`` files each set of
34board targets must be in a ``qualifiers`` key (only regular expression matches for board
35qualifiers are allowed, board names must be omitted from these entries). For ``board.yml``
36files each set of board targets must be in a ``boards`` key, these are lists containing the
37matches which form a singular group. A final parameter ``run`` can be set to ``first`` which
38means that the command will be ran once with the first image flashing process per set of board
39targets, or to ``last`` which will be ran once for the final image flash per set of board targets.
40
41An example flashing configuration for a ``soc.yml`` is shown below in which the ``--recover``
42command will only be used once for any board targets which used the nRF5340 SoC application or
43network CPU cores, and will only reset the network or application core after all images for the
44respective core have been flashed.
45
46.. code-block:: yaml
47
48  runners:
49    run_once:
50      '--recover':
51        - run: first
52          runners:
53            - nrfjprog
54          groups:
55            - qualifiers:
56                - nrf5340/cpunet
57                - nrf5340/cpuapp
58                - nrf5340/cpuapp/ns
59      '--reset':
60        - run: last
61          runners:
62            - nrfjprog
63            - jlink
64          groups:
65            - qualifiers:
66                - nrf5340/cpunet
67            - qualifiers:
68                - nrf5340/cpuapp
69                - nrf5340/cpuapp/ns
70        # Made up non-real world example to show how to specify different options for different
71        # flash runners
72        - run: first
73          runners:
74            - some_other_runner
75          groups:
76            - qualifiers:
77                - nrf5340/cpunet
78            - qualifiers:
79                - nrf5340/cpuapp
80                - nrf5340/cpuapp/ns
81
82Usage
83*****
84
85Commands that are supported by flash runners can be used as normal when flashing non-sysbuild
86applications, the run once configuration will not be used. When flashing a sysbuild project with
87multiple images, the flash runner run once configuration will be applied.
88
89For example, building the :zephyr:code-sample:`smp-svr` sample for the nrf5340dk which will
90include MCUboot as a secondary image:
91
92.. code-block:: console
93
94   cmake -GNinja -Sshare/sysbuild/ -Bbuild -DBOARD=nrf5340dk/nrf5340/cpuapp -DAPP_DIR=samples/subsys/mgmt/mcumgr/smp_svr
95   cmake --build build
96
97Once built with an nrf5340dk connected, the following command can be used to flash the board with
98both applications and will only perform a single device recovery operation when programming the
99first image:
100
101.. code-block:: console
102
103   west flash --recover
104
105If the above was ran without the flashing configuration, the recovery process would be ran twice
106and the device would be unbootable.
107