ORCA Project

Through this project i aim to solidify my understanding and mastering of the Yocto project and Bitbake specifically.

This project delivers a customizable linux distribution with different image flavors. The result is ran and tested on the STM32MP135F-DK board but it aims to be hardware independant for DISTRO and IMAGE components and applications.

Key Goals

• Portability: Make the distribution hardware-independant and portable to different platforms
• Security: Enhance security through enabling CVE-Checks, security flags and exploring secure boot
• Reproducibilty: KAS file describes thouroughly all the dependencies and the required layers to reproduce the image for the mentioned board
• Isolation: All required python packages are installed in a python virtual environment and all builds are produced within a KAS container
• Abstraction: Image flavors can be tuned through some variables. Also, a setup bash script as a wrapper to the KAS container to control few project specific requirements.
• Leightweight: Customizing the image and optimizing the kernel to reduce ressources consumption and make the image as specific to the application requirements as possible

Notes

This project was developed over the scarthgap release of Yocto Project and its corresponding 2.8 bitbake release.

The KAS version used in this project is kas 5.1.

Rearranging the project structure may cause some problems with the setup script, so avoid changing the layout of the project.

As mentionned above, this project should be portable and you should be able to run it on different hardware as a Raspberry-pi just by updating a kas file and the layers file.

Build the project

To build the project for the first time you can follow these steps, start by changing to the desired directory:

user@hostname:~$ cd dir

Clone the project:

user@hostname:~/dir$ git clone --single-branch --branch main git@github.com:AKhadhraoui47/Orca_Project.git

We will start by setting up the environment, directories and installing the different requirements (e.g KAS) by running the setup script:

user@hostname:~/dir/Orca_Project$ cd Orca_Project
user@hostname:~/dir/Orca_Project$ ./scripts/setuporca prepare

Now you can launch the build process:

user@hostname:~/dir/orca$ ./scripts/setuporca build kas/kas-core.yml

Now you're all set to launch your STM32MP135F-DK board. To populate the image to your sd card, please refer to the official STM32MP Wiki. If you're flashing using the USB DFU refer to the Stm32Programmer.

Setuporca Script

The setuporca script is a wrapper over KAS container and provides some abstraction to the environment setup process, configurations and container usage.

The script can be executed anywhere from your filesystem, so it would be useful to add its path the PATH environment variable:

user@hostname:~/dir$ export PATH=$PATH:/path/to/setuporca 

Setup Prepare

user@hostname:~/dir$ setuporca prepare dir/to/share/

• This command must be run the first time you clone the project. To prepare the project environment, run the setuporca with the prepare plugin, optionally you can provide the path to a specific directory (absolute or relative) where shared downloads and sstate-cache are available. If ignored a shared directory YoctoShare/ will be automatically at the same level where the project was cloned. Note that the provided directory if not ignored must provide downloads and sstate-cache sub-directories.

• This plugin reponsible for setting the python virtual environment where KAS will be installed isolated from your host system.

• Determines a set of ressources limiting variables for Bitbake and Make, as it sets BB_NUMBER_THREADS and PARALELL_MAKE to half the number of available logical cores. You can manually change the values after running the prepare command in local.yml.

• If for any reason you changed the path to the shared directories where downloads and sstate-cache files are available you need to rerun the command, so the the shared volume between the host and KAS container is updated.

Setup Shell

user@hostname:~/dir$ setuporca shell dir/to/kas-file.yml

• Launches KAS container shell that can be exploited debugging or inspecting the values of some variables, based on the configuration files in the KAS directory

Setup Build

user@hostname:~/dir$ setuporca build dir/to/kas-file.yml

• Launches the build based on the configuration of the KAS files.

Setup Clean

user@hostname:~/dir$ setuporca clean dir/to/kas-file.yml

• Removes the artifacts directory build/tmp/.

About the Distribution

The theme for this project is based these core elements:

• Shell: Bash
• Base-Utils: Core-utils
• Init Manager: Systemd or Sysvinit, defined according to the variable MNGR_SLCT in orca.conf file
• C Library: Glibc
• Graphics: No graphics (for now)

About the Image

Different image flavors are provided serving different purposes. You can choose which to use through CALF_TYPE variable in Image Recipe.

• calfdev: Providing development tools, libraries, compiler, make, debugging tools as gdb, and profiling tools ... (root access with empty-password).
• calfprod: Production image with builtin main application and limited user permissions. (ongoing developement)
• calfcore: Basic image that is just able to boot, with user login: calf, passwd: linux.

About the Machine

Two machines are presented in project, where one derives from other:

• tilikum: The main machine which kernel was very well optimized removing all unnecessary drivers for different devices, unneeded communication stacks, debugging features, ... Resulting a minimal kernel of 15MB
• tilikum-extended: Derives from tilikum, enabling all the debugging features of the kernel resulting a much larger kernel.

Note that machines and images have compatibility constraints as follows (calfdev - tilikum-extended) and (calfprod/calfcore - tilikum) determined by the COMPATIBLE_MACHINE variable. The different combinations are put in seperate KAS files kas-core - kas-dev - kas-prod.

References

• Techleef Yocto Tutorial: This serie is highly recommended, the content provided by the channel is an absolute gem. Special thanks to Eng. Talel Belhaj SALEM.
• Official Yocto Documentation, Official Bitbake User Manual: Do not skip documentation, it is the best and most solid way to learn and advance with complex systems as Yocto and Bitbake.
• Official KAS Documentation: Both Kas and KAS container are available through this link.
• STM32MP Wiki: Official documentation about the STM32MP series from software tools to guides to deep dives in interesting topics as Secure Boot, TEE ...