Commits on Aug 25, 2023

1. cmake: extensions: Add zephyr_topological_sort() …

   This function performs topological sorting of CMake targets. Its initial
   use case in Zephyr will be for implementing sysbuild image dependencies,
   i.e., specifying an image order for CMake configuration and flashing.
   
   Sourced from a comment on PR zephyrproject-rtos#57884 (anchor: #discussion_r1206807021)
   
   Authored-by: Torsten Rasmussen <Torsten.Rasmussen@nordicsemi.no>
   Signed-off-by: Grzegorz Swiderski <grzegorz.swiderski@nordicsemi.no>

   

   57300 committed Aug 25, 2023
   Copy the full SHA

   3843444 View commit details

   Browse the repository at this point in the history

2. sysbuild: Support relative ordering of images …

   Fixes zephyrproject-rtos#53650
   
   The existing solution for image ordering involves the `IMAGES` variable,
   which sysbuild originally provided to let users manually add a new image
   in a desired order. This isn't very flexible for the following reasons:
   
   * The order in which `IMAGES` is updated across multiple modules and
     `sysbuild.cmake` files is not well defined.
   * Having a single variable means that the same order is used for both
     configuration and flashing. Usually, there is no reason for the
     flashing order to be the same as the configuration order.
   
   Introduce the `sysbuild_add_dependencies()` function for more fine-tuned
   ordering of images. It makes one image depend on other images in either
   configuration or flashing order. Its usage is similar to the standard
   CMake function `add_dependencies()`, but with an extra parameter to
   distinguish between two types of dependencies:
   
    sysbuild_add_dependencies(CONFIGURE my_sample sample_a sample_b)
    sysbuild_add_dependencies(FLASH     my_sample sample_c sample_d)
   
   CONFIGURE dependencies determine the order in which sysbuild configures
   (runs CMake for) the individual images. This is useful if there is some
   information from one application's build which needs to be available to
   another application.
   
   FLASH dependencies control the sequence of images used by `west flash`.
   This could be used if a specific flashing order is required by an SoC,
   a runner, or something else. Note that these dependencies are not valid
   for images specified as `BUILD_ONLY`.
   
   The internal `sysbuild_images_order()` function is responsible for
   assembling two sorted lists of images based on the added dependencies,
   with the help of `topological_sort()`.
   
   Signed-off-by: Grzegorz Swiderski <grzegorz.swiderski@nordicsemi.no>

   

   57300 committed Aug 25, 2023
   Copy the full SHA

   dbaf74a View commit details

   Browse the repository at this point in the history

3. sysbuild: Remove IMAGES variable …

   This variable was originally provided for two indended purposes:
   
     * Let users manually add a new image in a desired order in the list.
     * Let users set build-only images, which are excluded from the list.
   
   Given the recent additions of the `sysbuild_add_dependencies()` function
   and the `BUILD_ONLY` parameter, `IMAGES` should be considered obsolete.
   
   Furthermore, the list of images added to sysbuild should be updated
   automatically when calling `ExternalZephyrProject_Add()`. This is now
   possible by using a GLOBAL property internal to sysbuild.
   
   With that, the `IMAGES` variable can be removed. Its existing usage for
   image ordering is replaced with `sysbuild_add_dependencies()` treewide.
   
   Signed-off-by: Grzegorz Swiderski <grzegorz.swiderski@nordicsemi.no>

   

   57300 committed Aug 25, 2023
   Copy the full SHA

   00bb3ad View commit details

   Browse the repository at this point in the history

4. sysbuild: Make the image processing order well-defined …

   Adjust the order in which image-specific `sysbuild.cmake` files are
   iteratively included by sysbuild.
   
   This is motivated by the introduction of `sysbuild_add_dependencies()`.
   In the following example:
   
     sysbuild_add_dependencies(CONFIGURE my_sample sample_a sample_b)
   
   the `my_sample` image is expected to be added before this function is
   called. Success depends not only on the placement of the call, but on
   the order in which new images are added, which itself is influenced by
   the order in which `sysbuild.cmake` files are included. This last order
   can be tweaked to make the "dependencies" feature more user-friendly.
   
   This is done by rewriting the internal `sysbuild.cmake` processing loop
   into a new, general purpose function - `sysbuild_add_subdirectory()` -
   which is a wrapper for `add_subdirectory(<source_dir>)` that recursively
   includes `sysbuild.cmake` files for all images found in `<source_dir>`.
   
   With the new function, all images that are expected to be found in a
   given `<source_dir>` are guaranteed to be added around the same time.
   This wasn't the case with the old processing loop, because the image-
   specific `sysbuild.cmake` files (where "sub-images" could be defined)
   were left to be processed at the very end.
   
   Below is the initial order in which sysbuild will add all images.
   Note: the order of Zephyr modules (from 1 to n) is well-defined.
   
     1. Main application (aka DEFAULT_IMAGE)
     2. MCUboot (optional)
     3. All images added via these directories:
        3.1. <module-1>.sysbuild-cmake
        3.2. <module-2>.sysbuild-cmake
        ...
        3.n. <module-n>.sysbuild-cmake
   
     4. All images added via these files:
        4.1. ${BOARD_DIR}/sysbuild.cmake
        4.2. ${APP_DIR}/sysbuild.cmake (aka sub-images of DEFAULT_IMAGE)
   
   These images are intended to be sorted for the users' convenience, from
   most to least important in the build system, or least to most dependent
   on other images for configuration (potentially).
   
   Finally, the use of `sysbuild_add_subdirectory()` requires updating the
   directory structure in sysbuild:
   
     ./images
       - All images should belong here. The `DEFAULT_IMAGE` should be the
         first and only image at the top level, so that it gets added first
         and its sub-images get added last.
   
     ./images/bootloader
       - Moved from ./bootloader.
   
     ./images/boards
       - Adds images from the board-specific `sysbuild.cmake` file.
   
   Signed-off-by: Grzegorz Swiderski <grzegorz.swiderski@nordicsemi.no>

   

   57300 committed Aug 25, 2023
   Copy the full SHA

   d771524 View commit details

   Browse the repository at this point in the history

5. doc: sysbuild: Add documentation for image ordering …

   Add a brief subsection to explain `sysbuild_add_dependencies()`.
   
   Signed-off-by: Grzegorz Swiderski <grzegorz.swiderski@nordicsemi.no>

   

   57300 committed Aug 25, 2023
   Copy the full SHA

   6b1e4f6 View commit details

   Browse the repository at this point in the history