Zephyr: West Manifest For Application Development

• RTOS
• Software Development
• Compilers

Introduction

I recently had an opportunity to work with Woody Creek (https://www.woodycreek.io/) in developing a network stack using The Zephyr Project. In the next few blog posts, I will share Zephyr features and systems I had an opportunity to leverage and learn more about during this project work.

In a previous blog post (https://www.embeddedrelated.com/showarticle/1505.p...), I demonstrated one technique to create a custom West manifest. The technique assumes that we have a fork of The Zephyr Project and want to use our fork in our application instead of the upstream version. The technique takes a naive approach by modifying the upstream West manifest (the example uses Nordic’s West manifest) in the following manner:

• It adds a new “remote” to point to our fork
• It modifies the appropriate entry in the West manifest to point to our fork.

The naive approach was proposed if we wanted to add a custom board, SoC, or driver to Zephyr and we can’t use the upstream repository, either because Zephyr doesn’t immediately support the board, SoC, or driver or we can’t share our customizations due to contractual restrictions. However, the demonstrated approach has two problems:

• It duplicates the entire West manifest, which is unnecessary.
• It keeps our application separate from other repositories, which results in additional steps to retrieve the entire code base. The method can also contribute to general disorganization.
  

In this blog post, I will demonstrate a more streamlined approach that doesn’t duplicate the West manifest. With this new approach, we can use the upstream repositories and leverage Zephyr’s support for “out-of-tree” boards, SoC, and drivers.

Additionally, this new approach makes our repositories better organized, and we can retrieve them using a single command. We will be using the sample “Hello World” application and targeting the STM32 B-L475 development board (https://www.st.com/en/evaluation-tools/b-l475e-iot...) in this blog post. You can follow along by referencing the repository here: https://github.com/mabembedded/zephyr-custom-west.

Strategy

Similar to the previous blog post, the strategy is twofold. First, we can create our custom West manifest, which is shown below and only contains the needed repositories:

manifest:
  defaults:
    remote: upstream

  remotes:
    - name: upstream
      url-base: https://github.com/zephyrproject-rtos

  projects:
    - name: zephyr
      revision: v3.7.0
      import:
        name-allowlist:
          - zephyr
          - hal_stm32
          - cmsis

  self:
    path: zephyr-custom-west

The following are relevant portions of the West manifest:

• defaults: This entry specifies the defaults that the rest of the West manifest should use. We specify a default remote, which we call upstream.
• remotes: This keyword specifies the details of each remote repository we reference in the rest of the West manifest. In this case, we have only one remote repository, called upstream, which points to the upstream Zephyr repository.
• projects: This entry defines all the repositories we wish to retrieve.
  • The final URL of each project is url-base/name.git, where url-base is retrieved from the remote section and name is retrieved from the project section.
  • The revision entry for each project determines the exact commit (or branch) that should be used to check out the repository.
• import: This keyword instructs West to pull and use the West manifest from the specified project. In this instance, we use the West manifest from the upstream Zephyr repository. However, to avoid pulling all of the repositories used in Zephyr, since we don't need them, we can use the name-allowlist key to pull only specific repositories. Since we're targeting an STM32 board, only need the hal_stm32 and cmsis repositories.
• self: This entry provides options to control the manifest repository itself. Specifically, the path key specifies where the repository should be cloned.

The advantage of using the above West manifest is that our application and the needed repositories can be retrieved with the following single command (instead of the multiple commands that needed to be executed using the previous method):

$> west init -m https://github.com/mabembedded/zephyr-custom-west.git --mr main

After executing the above command, the following directories are present:

• modules/hal/stm32: This directory contains the repository referenced by the hal_stm32 entry in the West manifest above.
• modules/hal/cmsis: This directory contains the repository referenced by the cmsis entry in the West manifest above.
• zephyr: This directory contains the principal Zephyr repository.
• zephyr-custom-west: This directory contains our custom repository with our out-of-tree "Hello World" application.

We can navigate to the zephyr-custom-west directory and build our out-of-tree "Hello World" application for the STM32 BL475 development board by executing the following command:

$ > west build -p -b disco_l475_iot1 app/

We have successfully built our application!

If we compare the West manifest file above to the one from the previous blog post, we can see that it is much simpler.

Now that we have a baseline West manifest, we can add customizations to Zephyr by using "Zephyr modules". A module contains a module.yaml file inside the zephyr directory of the baseline repository. A module allows us to add out-of-tree board or SoC definitions, custom DTS bindings, or drivers. Our zephyr/module.yaml contains the following, which provides additional instructions to the West build system:

build:
  cmake: .
  kconfig: Kconfig
  settings:
    board_root: .
    dts_root: .
    soc_root: .
    arch_root: .

• The cmake entry instructs West that an additional CMakeLists.txt file is in the base zephyr-custom-west directory. This file, which is reproduced below, instructs West that the drivers directory is also a cmake project:

add_subdirectory(drivers)

• The kconfig key informs West that there is a Kconfig file in the base directory, which includes our out-of-tree drivers. The Kconfig file contains the following, instructing the West build system that another Kconfig file exists in the drivers directory.

rsource "drivers/Kconfig"

• drivers/Kconfig contains the following, which lists the "Drivers" Kconfig menu. We can add Kconfig options specific to our out-of-tree driver, including the base option to compile the driver, to this option.

menu "Drivers"
endmenu

• The settings entry can define directories that the West build system can use for additional boards, Devicetrees, SoC, and architectures. For example, if we wanted to add an out-of-tree board, we could place it in its directory under the boards directory of our base repository.

Conclusion

In this blog post, I showed a technique to create a custom West manifest that is simpler and more streamlined than the technique shown in a previous blog post. This technique allows us to pull in only the needed repositories instead of all Zephyr repositories. The method shown in this blog post also allows us to incorporate out-of-tree board and SoC definitions and include custom drivers without waiting for them to be incorporated into Zephyr.

Sign in