Example of directory structure for Packages

Template:ArticleMainWriter Template:ReviewersList Template:ArticleApprovedVersion


1 Article purpose[edit]

This article aims at proposing a way to organize, on the host PC, the software packages of the different Packages (Starter, Developer and Distribution) for a given release of the STM32MPU Embedded Software distribution.

The main objective of the proposed organization is to keep together the software packages corresponding to a given release because there are links between them. For example:

  • Flashing the image from the Starter Package on the board is mandatory before modifying the source code from the Developer Package. Both the image and the source code must belong to the same software release.
  • The SDK (Developer Package) and the image (Starter Package) have both been generated from the Distribution Package. A software release thus guarantees that there is no misalignment between the different software packages.

An example of organization for tools is proposed here.

Info.png The objective of this article is to describe one organization among all the possible organizations. Feel free to organize the delivered Packages in any other way that would better match your way of working.
Info.png In practice, this article uses the STM32MPU Embedded Software distribution release issued on 03-July-2018 as an example to illustrate the proposed organization. If you are using a different release, the names of the directories and files might differ.


The directories are shown in green, while the files are in black.

2 Creating the structure[edit]

  • Create your <working directory> and assign a unique name to it (for example by including the release date):
PC $> mkdir STM32MPU-Release-18-07-03
PC $> cd STM32MPU-Release-18-07-03
  • Create the first-level directories that will host the software packages delivered through the STM32MPU Embedded Software distribution release note:
PC $> mkdir Starter-Package
PC $> mkdir Developer-Package
PC $> mkdir Distribution-Package
  • The resulting directory structure looks as follows:
STM32MPU-Release-18-07-03  STM32MPU Embedded Software release
├── Developer-Package          Developer Package installation directory
├── Distribution-Package       Distribution Package installation directory
└── Starter-Package            Starter Package installation directory

Once all software packages have been installed according to the instructions given in the STM32MPU Embedded Software distribution release note, the resulting directory structure looks as follows:

STM32MPU-Release-18-07-03                    STM32MPU Embedded Software release
├── Developer-Package                            Developer Package installation directory
│   ├── openstlinux-4.14-rocko-mp1-18-07-03  Linux kernel, U-Boot and TF-A source code (OpenSTLinux distribution)
│   ├── SDK                                  SDK for OpenSTLinux distribution
│   └── STM32Cube_FW_MP1_V0.4.0              STM32Cube MPU Package
├── Distribution-Package                         Distribution Package installation directory
│   └── openstlinux-4.14-rocko-mp1-18-07-03  OpenSTLinux distribution (full source code and OpenEmbedded-based build framework)
└── Starter-Package                              Starter Package installation directory
    └── openstlinux-4.14-rocko-mp1-18-07-03  Software image (binaries)

3 Focus on the Starter Package directory[edit]

The Starter-Package directory contains the software image for the STM32MPU Embedded Software distribution.

The trusted boot chain is the default solution delivered by STMicroelectronics. It includes the superset of features (for example, all Flash memory devices are supported). The basic boot chain is also upstreamed by STMicroelectronics, with a limited number of features (for example microSD card memory boot only). Refer to the Boot chains overview article for details.

Flash memory partitions (e.g. rootfs, bootfs...) are explained in the STM32MP15 Flash mapping article.


Starter-Package
└── openstlinux-4.14-rocko-mp1-18-07-03
    └── images
        └── stm32mp1
            ├── flashlayout_st-image-weston                                 Flash layout files (description of the partitions) for the supported Flash devices and boards
            │   ├── FlashLayout_emmc_stm32mp157c-ev1-trusted.tsv            Flash layout file for eMMC and trusted boot chain → STM32MP15 Evaluation boards
            │   ├── FlashLayout_nand-4-256_stm32mp157c-ev1-trusted.tsv      Flash layout file for NAND Flash and trusted boot chain → STM32MP15 Evaluation boards
            │   ├── FlashLayout_nor-emmc_stm32mp157c-ev1-trusted.tsv        Flash layout file for NOR Flash (and eMMC) and trusted boot chain → STM32MP15 Evaluation boards
            │   ├── FlashLayout_nor-nand-4-256_stm32mp157c-ev1-trusted.tsv  Flash layout file for NOR Flash (and NAND Flasdh) and trusted boot chain → STM32MP15 Evaluation boards
            │   ├── FlashLayout_nor-sdcard_stm32mp157c-ev1-trusted.tsv      Flash layout file for NOR Flash (and microSD card) and trusted boot chain → STM32MP15 Evaluation boards
            │   ├── FlashLayout_sdcard_stm32mp157c-dk2-basic.tsv            Flash layout file for microSD card and basic boot chain → STM32MP15 Discovery kits
            │   ├── FlashLayout_sdcard_stm32mp157c-dk2-trusted.tsv          Flash layout file for microSD card and trusted boot chain (recommended setup) → STM32MP15 Discovery kits
            │   ├── FlashLayout_sdcard_stm32mp157c-ev1-basic.tsv            Flash layout file for microSD card and basic boot chain → STM32MP15 Evaluation boards
            │   └── FlashLayout_sdcard_stm32mp157c-ev1-trusted.tsv          Flash layout file for microSD card and trusted boot chain (recommended setup) → STM32MP15 Evaluation boards
            ├── scripts
            │   └── create_sdcard_from_flashlayout.sh
            ├── splash.bin                                                  U-Boot splash screen picture (file in BMP format with a .bin extension) for NOR Flash
            ├── st-image-bootfs-openstlinux-weston-stm32mp1.ext4            Binary for bootfs partition
            ├── st-image-bootfs-openstlinux-weston-stm32mp1.manifest
            ├── st-image-userfs-openstlinux-weston-stm32mp1.ext4            Binary for userfs partition
            ├── st-image-userfs-openstlinux-weston-stm32mp1.manifest
            ├── st-image-weston-openstlinux-weston-stm32mp1.ext4            Binary for rootfs partition
            ├── st-image-weston-openstlinux-weston-stm32mp1.license
            ├── st-image-weston-openstlinux-weston-stm32mp1-license_content.html
            ├── st-image-weston-openstlinux-weston-stm32mp1.manifest
            ├── st-image-weston-openstlinux-weston-stm32mp1_nand_4_256_multivolume.ubi
            ├── tf-a-stm32mp157c-dk2-trusted.stm32                          TF-A binary for FSBL partition (trusted boot chain) → STM32MP15 Discovery kits
            ├── tf-a-stm32mp157c-ev1-trusted.stm32                          TF-A binary for FSBL partition (trusted boot chain) → STM32MP15 Evaluation boards
            ├── u-boot-spl.stm32-stm32mp157c-dk2-basic                      U-Boot binary for FSBL partition (basic boot chain) → STM32MP15 Discovery kits
            ├── u-boot-spl.stm32-stm32mp157c-ev1-basic                      U-Boot binary for FSBL partition (basic boot chain) → STM32MP15 Evaluation boards
            ├── u-boot-stm32mp157c-dk2-basic.img                            U-Boot binary for SSBL partition (basic boot chain) → STM32MP15 Discovery kits
            ├── u-boot-stm32mp157c-dk2-trusted.stm32                        U-Boot binary for SSBL partition (trusted boot chain) → STM32MP15 Discovery kits
            ├── u-boot-stm32mp157c-ev1-basic.img                            U-Boot binary for SSBL partition (basic boot chain) → STM32MP15 Evaluation boards
            └── u-boot-stm32mp157c-ev1-trusted.stm32                        U-Boot binary for SSBL partition (trusted boot chain) → STM32MP15 Evaluation boards

4 Focus on the Developer Package directory[edit]

The Developer-Package directory contains:

  • The source code for the following OpenSTLinux software packages (development for Arm® Cortex®-A processor):
    • TF-A
    • Linux kernel
    • U-Boot
  • The debug symbol files for Linux kernel, U-Boot and TF-A
  • The SDK (for cross-development on an host PC)
  • The STM32Cube MPU Package (developed for Arm® Cortex®-M processor)


Developer-Package
├── openstlinux-4.14-rocko-mp1-18-07-03  Source code for OpenSTLinux distribution
│   ├── images
│   │   └── stm32mp1                                Debug symbol files installation directory
│   │       ├── tf-a-bl2-trusted.elf                Debug symbol file for TF-A → trusted boot firmware stage
│   │       ├── tf-a-bl32-trusted.elf               Debug symbol file for TF-A → runtime software stage
│   │       ├── u-boot-stm32mp157c-dk2-trusted.elf  Debug symbol file for U-Boot → STM32MP15 Discovery kits
│   │       ├── u-boot-stm32mp157c-ev1-trusted.elf  Debug symbol file for U-Boot → STM32MP15 Evaluation boards
│   │       └── vmlinux                             Debug symbol file for Linux kernel
│   └── sources
│       └── arm-openstlinux_weston-linux-gnueabi
│           ├── linux-stm32mp-4.14-48     Linux kernel installation directory
│           │   ├── [*].patch             ST patches for Linux kernel
│           │   ├── fragment-[*].config   ST configuration fragments for Linux kernel
│           │   ├── linux-4.14.48         Linux kernel source code directory
│           │   ├── linux-4.14.48.tar.xz
│           │   ├── README.HOW_TO.txt     Helper file for Linux kernel management: reference for Linux kernel build
│           │   └── series
│           ├── tf-a-stm32mp-1.5-release.AUTOINC+ed8112606c             TF-A installation directory
│           │   ├── [*].patch                                           ST patches for TF-A
│           │   ├── git                                                 TF-A source code directory
│           │   ├── Makefile.sdk                                        Makefile for the TF-A compilation
│           │   ├── README.HOW_TO.txt                                   Helper file for TF-A management: reference for TF-A build
│           │   ├── series
│           │   └── tf-a-stm32mp-1.5-release.AUTOINC+ed8112606c.tar.gz
│           └── u-boot-trusted-stm32mp-2018.03-release.AUTOINC+f95ab1fb6e             U-Boot installation directory
│               ├── [*].patch                                                         ST patches for U-Boot
│               ├── git                                                               U-Boot source code directory
│               ├── Makefile.sdk                                                      Makefile for the U-Boot compilation
│               ├── README.HOW_TO.txt                                                 Helper file for U-Boot management: reference for U-Boot build
│               ├── series
│               └── u-boot-trusted-stm32mp-2018.03-release.AUTOINC+f95ab1fb6e.tar.gz
├── SDK                                                                           SDK for OpenSTLinux distribution: details in Standard SDK directory structure article
│   ├── environment-setup-cortexa7hf-neon-vfpv4-openstlinux_weston-linux-gnueabi  Environment setup script for Developer Package
│   ├── site-config-cortexa7hf-neon-vfpv4-openstlinux_weston-linux-gnueabi
│   ├── sysroots
│   │   ├── cortexa7hf-neon-vfpv4-openstlinux_weston-linux-gnueabi                Target sysroot (libraries, headers, and symbols)
│   │   │   └── [...]
│   │   └── x86_64-openstlinux_weston_sdk-linux                                   Native sysroot (libraries, headers, and symbols)
│   │       └── [...]
│   └── version-cortexa7hf-neon-vfpv4-openstlinux_weston-linux-gnueabi
└── STM32Cube_FW_MP1_V0.4.0                             STM32Cube MPU Package: details in STM32Cube MPU Package content article
    ├── COPYING
    ├── COPYING.BSD-3
    ├── Drivers
    │   ├── BSP                                         BSP drivers for the supported STM32MPU boards
    │   │   └── [...]
    │   ├── CMSIS
    │   │   └── [...]
    │   └── STM32MP1xx_HAL_Driver                       HAL drivers for the supported STM32MPU devices
    │       └── [...]
    ├── _htmresc
    │   └── [...]
    ├── LLA_evaluation_for_STM32MPU_17-12-06_plain.txt
    ├── Middlewares
    │   └── [...]
    ├── package.xml
    ├── Projects
    │   ├── STM32CubeProjectsList.html                  List of examples and applications for STM32Cube MP1 Package
    │   ├── STM32MP15_DISCO                             Set of examples and applications → STM32MP15 Discovery kits
    │   │   └── [...]
    │   └── STM32MP15_EVAL                              Set of examples and applications → STM32MP15 Evaluation boards
    │       └── [...]
    ├── Release_Notes.html                              Release note for STM32Cube MP1 Package
    └── Utilities
        └── [...]

Appendix A shows the structure of the Linux kernel, U-Boot and TF-A installation directories after these software packages have been built.

5 Focus on the Distribution Package directory[edit]

The Distribution-Package directory contains all the OpenEmbedded layers required to get the source code of any STM32MPU Embedded Software component, as well as a build framework based on OpenEmbedded.


Distribution-Package
└── openstlinux-4.14-rocko-mp1-18-07-03  OpenSTLinux distribution
    ├── meta-openembedded  Collection of layers for the OpenEmbedded-Core universe (OpenEmbedded standard)
    │   └── [...]
    ├── meta-qt5           QT5 layer for OpenEmbedded (standard)
    │   └── [...]
    ├── meta-st
    │   ├── meta-st-openstlinux                   STMicroelectronics layer that contains the settings of the frameworks and images for the OpenSTLinux distribution
    │   │   ├── recipes-samples
    │   │   │   └── images
    │   │   │       ├── st-example-image-qt.bb    ST example of image based on QT framework
    │   │   │       ├── st-example-image-x11.bb   ST example of image based on X11
    │   │   │       └── st-example-image-xfce.bb  ST example of image based on XFCE framework
    │   │   ├── recipes-st
    │   │   │   ├── images
    │   │   │   │   ├── st-image-core.bb          Core image for OpenSTLinux distribution
    │   │   │   │   ├── st-image.inc
    │   │   │   │   └── st-image-weston.bb        Weston image with basic Wayland support for OpenSTLinux distribution: recommended setupsetup
    │   │   │   └── packagegroups
    │   │   │       └── [...]
    │   │   └── [...]
    │   ├── meta-st-stm32mp                 STMicroelectronics layer that contains the description of the BSP for the STM32 MPU devices
    │   │   ├── recipes-bsp
    │   │   │   ├── alsa                    Recipes for ALSA control configuration
    │   │   │   │   └── [...]
    │   │   │   ├── drivers                 Recipes for Vivante GCNANO GPU kernel drivers
    │   │   │   │   └── [...]
    │   │   │   ├── trusted-firmware-a      Recipes for TF-A
    │   │   │   │   └── [...]
    │   │   │   └── u-boot                  Recipes for U-Boot
    │   │   │       └── [...]
    │   │   ├── recipes-extended
    │   │   │   ├── m4projects              Recipes for STM32Cube MPU Package within the OpenSTLinux distribution
    │   │   │   │   └── [...]
    │   │   │   ├── openocd                 Recipes for Open On-Chip Debugging (OpenOCD) on Cortex-A or Cortex-M
    │   │   │   │   └── [...]
    │   │   │   └── stlink                  Recipes for STLink
    │   │   │       └── [...]
    │   │   ├── recipes-graphics
    │   │   │   ├── gcnano-userland         Recipes for Vivante libraries OpenGL ES, OpenVG and EGL (multi backend)
    │   │   │   │   └── [...]
    │   │   │   └── [...]
    │   │   ├── recipes-kernel
    │   │   │   └── linux                   Recipes for Linux kernel
    │   │   │       └── [...]
    │   │   │   └── linux-firmware          Recipes for Linux firmwares (example, Bluetooth firmware)
    │   │   │       └── [...]
    │   │   ├── recipes-st
    │   │   │   └── images
    │   │   │       ├── st-image-bootfs.bb  Recipes for the bootfs partition binary
    │   │   │       └── st-image-userfs.bb  Recipes for the userfs partition binary
    │   │   └── [...]
    │   ├── meta-st-stm32mp-addons  STMicroelectronics layer that helps managing the STM32CubeMX integration
    │       └── [...]
    │   └── scripts
    │       ├── envsetup.sh  Environment setup script for Distribution Package
    │       └── [...]
    └── openembedded-core  Core metadata for current versions of OpenEmbedded (standard)
        └── [...]


Appendix B shows the structure of the build directory.

6 Appendix A: directory structure after build (Developer Package)[edit]

Provided you have followed the recommendations of the README.HOW_TO.txt helper files to build the Linux kernel, the U-Boot and the TF-A, then the following new directories and files contain the build outputs.


Developer-Package
├── openstlinux-4.14-rocko-mp1-18-07-03 Source code for OpenSTLinux distribution
│   └── sources
│       └── arm-openstlinux_weston-linux-gnueabi
│           ├── linux-stm32mp-4.14-48                 Linux kernel installation directory
│           │   ├── build                             Linux kernel build directory
│           │   │   ├── install_artifact
│           │   │   │   ├── lib
│           │   │   │   │   └── modules
│           │   │   │   │       └── 4.14.48
│           │   │   │   │           └── [...]         Kernel modules hierarchy (*.ko files)
│           │   │   │   └── boot
│           │   │   │       ├── stm32mp157c-d[*].dtb  Linux kernel device tree blob files for bootfs partition → STM32MP15 Discovery kits
│           │   │   │       ├── stm32mp157c-e[*].dtb  Linux kernel device tree blob files for bootfs partition → STM32MP15 Evaluation boards
│           │   │   │       ├── uImage                Linux kernel binary image file (with U-Boot wrapper) for bootfs partition
│           │   │   │       └── [...]
│           │   │   ├── vmlinux                       Debug symbol file for Linux kernel
│           │   │   └── [...]
│           │   └── [...]
│           ├── tf-a-stm32mp-1.5-release.AUTOINC+ed8112606c TF-A installation directory
│           │   ├── build                                   TF-A build directory
│           │   │   ├── tf-a-bl2-trusted.elf                Debug symbol file for TF-A → trusted boot firmware stage
│           │   │   ├── tf-a-bl32-trusted.elf               Debug symbol file for TF-A → trusted boot firmware stage
│           │   │   ├── tf-a-stm32mp157c-dk2-trusted.stm32  TF-A binary for FSBL partition (trusted boot chain) → STM32MP15 Discovery kits
│           │   │   ├── tf-a-stm32mp157c-ev1-trusted.stm32  TF-A binary for FSBL partition (trusted boot chain) → STM32MP15 Evaluation boards
│           │   │   └── [...]
│           │   └── [...]
│           └── u-boot-trusted-stm32mp-2018.03-release.AUTOINC+f95ab1fb6e U-Boot installation directory
│               ├── build-stm32mp15_trusted_defconfig                     U-Boot build directory
│               │   ├── u-boot-stm32mp157c-dk2-trusted.elf                Debug symbol file for U-Boot → STM32MP15 Discovery kits
│               │   ├── u-boot-stm32mp157c-dk2-trusted.stm32              U-Boot binary for SSBL partition (trusted boot chain) → STM32MP15 Discovery kits
│               │   ├── u-boot-stm32mp157c-ev1-trusted.elf                Debug symbol file for U-Boot → STM32MP15 Evaluation boards
│               │   ├── u-boot-stm32mp157c-ev1-trusted.stm32              U-Boot binary for SSBL partition (trusted boot chain) → STM32MP15 Evaluation boards
│               │   └── [...]
│               └── [...]

7 Appendix B: directory structure after build (Distribution Package)[edit]

Provided you have followed the build method explained in OpenSTLinux distribution, then the following new directories contain the build outputs.

As long as you did not modify the source code:

  • the Template:Purple are the same as the ones available in the Starter Package: flash layout, binaries for bootfs, userfs and rootfs partitions
  • the files in grey are the same as the ones available in the Starter and Developer Packages: binaries for FSBL and SSBL partitions
  • the files in orange are the same as the ones available in the Developer Package: Linux kernel image and device tree blobs
  • the Template:Rose are only available in the Distribution Package: they concern the OP-TEE (see How to populate and boot a board with OP-TEE)


Distribution-Package/openstlinux-4.14-rocko-mp1-18-07-03/build-openstlinuxweston-stm32mp1/tmp-glibc/deploy
└── images
|   └── stm32mp1
|       ├── Template:Purple                                 Flash layout files (description of the partitions) for the supported flash devices
|       │   ├── Template:Rose              Flash layout file for eMMC and OP-TEE → STM32MP15 Evaluation boards
|       │   ├── Template:Purple            Flash layout file for eMMC and trusted boot chain → STM32MP15 Evaluation boards
|       │   ├── Template:Rose        Flash layout file for NAND Flash and OP-TEE → STM32MP15 Evaluation boards
|       │   ├── Template:Purple      Flash layout file for NAND Flash and trusted boot chain → STM32MP15 Evaluation boards
|       │   ├── Template:Rose          Flash layout file for NOR Flash (and eMMC) and OP-TEE → STM32MP15 Evaluation boards
|       │   ├── Template:Purple        Flash layout file for NOR Flash (and eMMC) and trusted boot chain → STM32MP15 Evaluation boards
|       │   ├── Template:Rose    Flash layout file for NOR Flash (and NAND Flasdh) and OP-TEE → STM32MP15 Evaluation boards
|       │   ├── Template:Purple  Flash layout file for NOR Flash (and NAND Flasdh) and trusted boot chain → STM32MP15 Evaluation boards
|       │   ├── Template:Rose        Flash layout file for NOR Flash (and microSD card) and OP-TEE → STM32MP15 Evaluation boards
|       │   ├── Template:Purple      Flash layout file for NOR Flash (and microSD card) and trusted boot chain → STM32MP15 Evaluation boards
|       │   ├── Template:Purple            Flash layout file for microSD card and basic boot chain → STM32MP15 Discovery kits
|       │   ├── Template:Rose            Flash layout file for microSD card and OP-TEE → STM32MP15 Discovery kits
|       │   ├── Template:Purple          Flash layout file for microSD card and trusted boot chain (recommended setup) → STM32MP15 Discovery kits
|       │   ├── Template:Purple            Flash layout file for microSD card and basic boot chain → STM32MP15 Evaluation boards
|       │   ├── Template:Rose            Flash layout file for microSD card and OP-TEE → STM32MP15 Evaluation boards
|       │   └── Template:Purple          Flash layout file for microSD card and trusted boot chain (recommended setup) → STM32MP15 Evaluation boards
|       │   └── [...]
|       ├── Template:Purple
|       │   └── Template:Purple
|       ├── Template:Purple                                                  U-Boot splash screen picture (file in BMP format with a .bin extension) for NOR Flash
|       ├── Template:Purple            Binary for bootfs partition
|       ├── Template:Purple            Binary for userfs partition
|       ├── Template:Purple            Binary for rootfs partition
|       ├── stm32mp157c-d[*].dtb                                        Linux kernel device tree blob files for bootfs partition → STM32MP15 Discovery kits
|       ├── stm32mp157c-e[*].dtb                                        Linux kernel device tree blob files for bootfs partition → STM32MP15 Evaluation boards
|       ├── Template:Rose                                          Debug symbol file for TF-A and OP-TEE → trusted boot firmware stage
|       ├── tf-a-bl2-trusted.elf                                        Debug symbol file for TF-A → trusted boot firmware stage
|       ├── tf-a-bl32-trusted.elf                                       Debug symbol file for TF-A → trusted boot firmware stage
|       ├── Template:Rose                            TF-A binary for FSBL partition (OP-TEE) → STM32MP15 Discovery kits
|       ├── tf-a-stm32mp157c-dk2-trusted.stm32                          TF-A binary for FSBL partition (trusted boot chain) → STM32MP15 Discovery kits
|       ├── Template:Rose                            TF-A binary for FSBL partition (OP-TEE) → STM32MP15 Evaluation boards
|       ├── tf-a-stm32mp157c-ev1-trusted.stm32                          TF-A binary for FSBL partition (trusted boot chain) → STM32MP15 Evaluation boards
|       ├── Template:Purple                      U-Boot binary for FSBL partition (basic boot chain) → STM32MP15 Discovery kits
|       ├── Template:Purple                      U-Boot binary for FSBL partition (basic boot chain) → STM32MP15 Evaluation boards
|       ├── Template:Purple                            U-Boot binary for SSBL partition (basic boot chain) → STM32MP15 Discovery kits
|       ├── Template:Rose                          U-Boot binary for SSBL partition (OP-TEE) → STM32MP15 Discovery kits
|       ├── u-boot-stm32mp157c-dk2-trusted.stm32                        U-Boot binary for SSBL partition (trusted boot chain) → STM32MP15 Discovery kits
|       ├── Template:Purple                            U-Boot binary for SSBL partition (basic boot chain) → STM32MP15 Evaluation boards
|       ├── Template:Rose                          U-Boot binary for SSBL partition (OP-TEE) → STM32MP15 Evaluation boards
|       ├── u-boot-stm32mp157c-ev1-trusted.stm32                        U-Boot binary for SSBL partition (trusted boot chain) → STM32MP15 Evaluation boards
|       ├── uImage                                                      Linux kernel binary image file (with U-Boot wrapper) for bootfs partition
|       ├── vmlinux                                                     Debug symbol file for Linux kernel
|       └── [...]
└── [...]