IAR Zephyr Example Application

This repository contains a Zephyr example application ready to use with IAR. The main purpose of this repository is to serve as a reference on how to structure Zephyr-based applications. Some of the features demonstrated in this example are:

• Basic multi-threaded Zephyr application skeleton
• Zephyr workspace applications
• Zephyr modules
• West T2 topology
• Custom boards
• Custom devicetree bindings
• Out-of-tree drivers
• Out-of-tree libraries
• Example CI configuration (using GitHub Actions)
• Custom west extension
• Custom Zephyr runner
• Doxygen and Sphinx documentation boilerplate

This repository uses the development branch of Zephyr and the manifest file points to main. It is possible to change the manifest file in your own application to point to a corresponding Zephyr tag. Note that Zephyr 4.1 was the first production-grade version providing support for the IAR toolchain for Arm. ¹

Getting Started

This guide assumes you already have a compatible IAR toolchain for Arm (v9.70.1+) installed and ready to use.

Before getting started, make sure you have a proper Zephyr development environment. Follow the official Zephyr Getting Started Guide.

Tip

When you reach the Install the Zephyr SDK section, you only need:

west sdk install --gnu-toolchains arm-zephyr-eabi

Doing this will prevent west from downloading gigabytes of unrelated toolchains, which would take time to download and would occupy significant storage space. Once you have reached that point, you can return to this guide.

Initialization

The first step is to initialize the workspace folder (my-workspace) where the zephyr-example-application and all Zephyr modules will be cloned. Run the following command:

# initialize my-workspace for the zephyr-example-application (main branch) 
west init -m https://github.com/iarsystems/zephyr-example-application --mr main my-workspace
# update Zephyr modules
cd my-workspace
west update

Building and running

For building with IAR, make sure you set ZEPHYR_TOOLCHAIN_VARIANT ² and IAR_TOOLCHAIN_PATH in your system and then run the following commands:

cd zephyr-example-application
west build -b $BOARD app

where $BOARD is the target board.

You can use the custom_aca board found in this repository. Note that Zephyr sample boards may be used if an appropriate overlay is provided (see app/boards). When switching boards, always perform a pristine build:

# pristine builds are obtained with -p or --pristine
west build -b $BOARD app -p

A sample debug configuration is also provided. To apply it, run the following command:

west build -b $BOARD app -- -DEXTRA_CONF_FILE=debug.conf

Once you have built the application, run the following command to flash it:

# with the IAR I-jet (default)
west flash
# or with the SEGGER J-Link
west flash --runner jlink

If you have set IAR_TOOLCHAIN_PATH to an instance of IAR Embedded Workbench, you can debug your application directly, with the IAR C-SPY Debugger for Arm:

# with the IAR I-jet (default)
west debug
# or with the SEGGER J-link
west debug --runner jlink

Testing

To execute Twister integration tests, run the following command:

west twister -T tests --integration

Documentation

A minimal documentation setup is provided for Doxygen and Sphinx. To build the documentation first change to the doc folder:

cd doc

Before continuing, check if you have Doxygen installed. It is recommended to use the same Doxygen version used in CI. To install Sphinx, make sure you have a Python installation in place and run:

pip install -r requirements.txt

API documentation (Doxygen) can be built using the following command:

doxygen

The output will be stored in the _build_doxygen folder. Similarly, the Sphinx documentation (HTML) can be built using the following command:

make html

The output will be stored in the _build_sphinx folder. You may check for other output formats other than HTML by running make help.

Footnotes

1. Zephyr RTOS 4.1 Now Available: Performance Improvements, Support for IAR Toolchain, and More ↩

2. Zephyr Docs/Developing with Zephyr/Toolchains/IAR toolchain for Arm ↩