.. _sys_build_and_flash:

Sysbuild and Flash
##################

Overview
********

Zephyr's Sysbuild (System build) is a higher-level build system that can be used to combine multiple other build systems together. (Refer to `Zephyr Sysbuild <https://docs.zephyrproject.org/latest/build/sysbuild/index.html>`_ for details)

This guide describes how to use sysbuild to build Atmosic multi-images with simplified commands.

Atmosic test items in the `sample.yaml` file are named using the pattern `<item_name_base>.atm`, where `<item_name_base>` is the sample folder path relative to the repository root.
For example, `samples.sysbuild.hello_world.atm`, as shown in the :doc:`sysbuild sample <../openair/samples/sysbuild/hello_world/README>`.

Naming conventions:

- Item names with `.mcuboot` indicate MCUboot support and require ``@mcuboot`` in the board specification.
- Item names without `.mcuboot` are non-MCUboot builds and use the standard ``//ns`` board specification.

Refer to the :doc:`sysbuild sample <../openair/samples/sysbuild/hello_world/README>` for usage details.


.. _build_with_sysbuild:

Building with Sysbuild
**********************

Use the `west build` command with different board specifications depending on whether MCUboot is used:

**For non-MCUboot builds:**

.. code-block:: bash

    west build -p always -b <BOARD>//ns <APP> --sysbuild -T <test_item>

**For MCUboot builds:**

.. code-block:: bash

    west build -p always -b <BOARD>@mcuboot//ns <APP> --sysbuild -T <test_item>

Where:

- ``BOARD``: Atmosic device. See :ref:`board <atmosic_evk>`.
- ``APP``: Sample folder path relative to the Zephyr project root.
- ``test_item``: Test item defined in `sample.yaml`, e.g., `samples.sysbuild.hello_world.atm`, `samples.sysbuild.hello_world.atm.mcuboot`.

**Board Specification Patterns:**

- **Non-MCUboot**: Use ``<BOARD>//ns`` format (e.g., ``ATMEVK-3430e-WQN-2//ns``)
- **MCUboot**: Use ``<BOARD>@mcuboot//ns`` format (e.g., ``ATMEVK-3430e-WQN-2@mcuboot//ns``)

The ``@mcuboot`` qualifier tells the build system to use MCUboot-specific board configurations and partitioning schemes.

**Examples:**

Non-MCUboot build:

.. code-block:: bash

    west build -p always -b ATMEVK-3430e-WQN-2//ns openair/samples/sysbuild/hello_world --sysbuild -T samples.sysbuild.hello_world.atm

MCUboot build:

.. code-block:: bash

    west build -p always -b ATMEVK-3430e-WQN-2@mcuboot//ns openair/samples/sysbuild/hello_world --sysbuild -T samples.sysbuild.hello_world.atm.mcuboot


.. _flash_with_sysbuild:

Flashing with Sysbuild
**********************

**To Flash the built images**:

.. code-block:: bash

    west flash --skip-rebuild --verify --device <DEVICE_ID> [--jlink] --fast_load [--erase_flash]

Where:

- ``DEVICE_ID``: Serial number of the interface device. See :ref:`serial <atmosic_evk>`.
- ``--jlink``: Add this option if using a J-Link interface.
  If omitted, FTDI interface is assumed.
- ``--erase_flash``: used to erase the entire RRAM and flash of the EVK before programming. If omitted, to do programming only

**To flash a single image only**:

.. code-block:: bash

    west flash --domain <image_name> --skip-rebuild --verify --device <DEVICE_ID> [--jlink] --fast_load [--erase_flash]

Where:

- ``image_name``: Image domain name, e.g., `hci_uart`, `spe`, or `mcuboot`.
- ``DEVICE_ID``: Serial number of the interface device. See :ref:`serial <atmosic_evk>`.
- ``--jlink``: Add this option if using a J-Link interface.
  If omitted, FTDI interface is assumed.
- ``--erase_flash``: used to erase the entire RRAM and flash of the EVK before programming. If omitted, to do programming only

.. note::
  * The default build directory is the `build` folder under the current directory.
  * If you specify a custom `-d build_dir` with `west build`, you must also specify the same `build_dir` with `west flash`.

Subpages
********

.. toctree::
   :maxdepth: 1

   atmosic_sysbuild_options.rst