EB corbos Toolkit

Install the Docker container engine, if not done already. In Ubuntu you can use the docker.io package.

Adding the user to the docker group allows you to run the docker command without root privileges. To let the new group setting take effect, open a new terminal. Check the successful installation of Docker by running the "hello-world" container from the Docker Hub.

On successful installation, this results in a greeting from Docker.

Set environment variables for the URL of the EB corbos Toolkit’s delivery tarball and its extraction directory, so that you can reference them in subsequent commands. Make sure that the path of the extraction directory does not contain any spaces as these will lead to errors. On a Windows machine, avoid the use of a Windows partition for the extraction directory as this significantly slows down the EB corbos Toolkit.

Get the EB corbos Toolkit’s delivery tarball, if not done already.

Create the extraction directory, and extract the tarball into it.

After extraction, the directory contains, below a top-level directory

The workspace directory contains

In particular, the scripts directory contains

Load the development container’s image archive file from the delivery tarball.

You can use the docker image ls command to check that the image ghcr.io/elektrobit/eb-corbos-toolkit-devcontainer-amd64 is loaded.

Enter the development container by using the provided run.sh script. Pass the -d flag, so that the script runs the loaded development container rather than the default build container.

Within the development container, the bash shell runs as user developer and the current working directory is the workspace directory which is accessible as /workspace within the container.

Boot the prebuilt fastdev target image from the delivery tarball in a QEMU system emulation by using the provided qemu.sh script within the development container.

Setting the -d option of the qemu.sh script starts the QEMU system emulation booting the fastdev image from the prebuilt directory.

After booting, you are logged in as user root.

To stop the fastdev image, use

Alternatively, you can use the key sequence Ctrl-a x to exit the QEMU system emulation.

Rebuild the fastdev target image by using the recipe provided by the kas/public.yml Kas project configuration.

After a successful build, the target image and related artifacts can be found in the build/tmp/deploy/images/ebcl-qemuarm64 deployment directory of the workspace.

To boot the rebuilt fastdev target image in a QEMU system emulation, use the provided qemu.sh script without the -d option within the development container. By default, the qemu.sh script boots the image from the deployment directory.

Refer to the previous Run Prebuilt Target Image step on how to stop the fastdev image.

The delivery of the EB corbos Toolkit provides a prebuilt fastdev target image for the Raspberry Pi 4B. To rebuild it, use the additional rpi4b.yml Kas project configuration.

After a successful build, the fastdev-trixie-ebclfsa-rpi4b.wic target image and related artifacts can be found in the build/tmp/deploy/images/rpi4b deployment directory of the workspace.

To boot the image on a Raspberry Pi 4B, flash it to an SD card first. There are several options for this. If you are on a Windows machine, you can use a native tool such as Rufus to create a bootable SD card.

If you are on a Linux host with access to the SD card device file, you can use the dd command. First, set an environment variable for the device file so you can reference it in the following command.

To monitor the progress of the dd command, pipe it through the pv utility to display a progress bar.

Once the image is flashed to the SD card, you can boot it on a Raspberry Pi 4B.

The fastdev image uses the static IP address 192.168.7.2. If the Raspberry Pi 4B is reachable at this address from the development container, you can access it using the generated SSH keys and SSH client configuration already set up in the development container. Refer to Fast Development Image and Accessing Target Image With SSH Keys for further information.

After successful authentication, you are logged in as user root.

To use a different IP address, you can modify the following files:

You can inspect and also modify the network configuration of a running target image directly, in the file /etc/config/network.

In order to facilitate the development of graphical applications, the Linux kernel of the fastdev target image supports the "Direct Rendering Infrastructure" (DRI) for direct rendering on the framebuffer. To use the kernel DRI support, rebuilt the fastdev target image with the additional graphics.yml Kas project configuration. This adds the userspace interface to the kernelspace portion of the DRI, the mesa OpenGL graphics library and the kmscube demonstration program to the fastdev image.

Besides the basic graphics support added by the graphics.yaml Kas configuration, the kas/includes directory contains additional Kas configurations to add the weston compositor or a set of Qt libraries to the fastdev image. Refer to the Weston documentation and the Qt documentation pages for further information.

To view the graphical display provided by the VNC server of a QEMU system emulation, install a VNC viewer on the Linux host, if not done already. In Ubuntu you can use the tigervnc-viewer package.

Re-enter the development container. Use the -x option of the run.sh script to pass a docker option for publishing the port used by a VNC server in the development container, so that a VNC viewer running on the Linux host can connect to it.

Boot the rebuilt fastdev target image in a QEMU system emulation by using the provided qemu.sh script with the --display vnc option. This option starts the VNC server provided by the QEMU system emulation.

There are further display types available for the --display option, which pose additional requirements on your setup, but have improved display performance. Refer to Display options in the QEMU documentation for further information.

Start the graphical demonstration program in the running target image.

Open a new terminal on the Linux host and start the VNC viewer connected to the VNC server running in the development container.

The VNC viewer shows the spinning cube of the kmscube demo.

The EB corbos Toolkit offers VS Code support in order to use the development container of the delivery as an alternative to running the development container via the run.sh script.

Using VS Code with the EB corbos Toolkit’s development container requires the same prerequisites as running the development container as described in the Quick Start section up to loading the development container’s image archive file of the [_enter_the_development_container] step. Additional prerequisites specific to VS Code are:

The EB corbos Toolkit provides an eb-corbos-toolkit.code-workspace multi-root workspace file which, besides the workspace root, includes roots for the example application sub-directories in the appdev directory. Refer to What is a VS Code workspace for further information.

The workspace can be opened directly in VS Code or from a Linux Shell by using the code command as follows.

Opening the workspace in VS Code and selecting "Reopen in Container" (or accepting the corresponding prompt), starts the development container of the loaded container image, mounts the workspace directory as /workspace, and attaches its integrated terminal to the running development container. This way, the integrated terminal can be used to execute commands in the Dev Container Shell.

The workspace file also predefines several tasks related to application development. Refer to Develop Application Software Using VS Code for further information.

The Fast Dev Image is an image to facilitate the development and debugging of HI Applications and LI Applications for the EBcLfSA. HI Applications are elements of the Linux Userland executed in a supervised execution environment, whereas LI Applications are elements of the Linux Userland executed in an unsupervised execution environment.

The supervised execution environment of the EBcLfSA imposes certain constraints on HI Applications. In particular, not all of the system calls offered by the Linux kernel are allowed to be invoked by HI Applications. For example, the ioctl() system call is not allowed to HI Applications due to its flexibility which hinders the supervision of the Linux kernel when executing the system call.

The Fast Dev Image does not provide the supervised execution environment of the EBcLfSA. Instead, the Fast Dev Image rather monitors the system calls invoked by an HI Application, and reports the usage of disallowed system calls.

Figure 1, “Fast Dev Image” shows the components of the Fast Dev Image.

Table 1, “Components of the Fast Dev Image” gives short descriptions of the components of the Fast Dev Image.

On startup, the Linux kernel start the HI Init process. The HI Init process in its turn starts further HI Applications, including an executable /usr/bin/hi_app, if present, and then starts the Crinit init daemon as a LI Application. This startup sequence adheres to the assumption of use of the EBcLfSA, that a HI Application can only be started by another HI Application.

The Crinit init daemon starts the SSH server of the Fast Dev Image. The SSH client in the development container allows access to the Fast Dev Image without password using fastdev-qemuarm64 as the hostname of the Fast Dev Image. All required hostname and SSH client configuration entries are generated during development container start. The referenced SSH private key is taken from the prebuilt directory for the prebuilt Fast Dev Image, or generated at build-time when rebuilding the Fast Dev Image. In both cases, a matching SSH public key will be present in the `root’s home directory of the Fast Dev Image. Refer to Accessing Target Image With SSH Keys for further information.

This section describes the steps performed by the user for developing LI application software following the sequence shown in Figure 2, “Interaction for Developing Application Software”.

This section describes the development of HI application software according to the sequence shown in Figure 2, “Interaction for Developing Application Software”. The steps for importing the SDK root filesystem and for running the target image are identical to the corresponding steps for developing LI application software. Refer to Import SDK root filesystem and Run Target Image in the Developing HI Application Software section for instructional information.

The steps for creating source files for HI application software, building HI application software, and for deploying and running a HI application on startup, however, differ from the corresponding steps for developing LI application software. These steps are described in the following subsections.

This section describes the steps of a user for application development using the VS Code Support of the EB corbos Toolkit.

As prerequisites of this section, the workspace provided by the eb-corbos-toolkit.code-workspace workspace file is opened in VS Code, and the integrated terminal is attached to the running development container via "Reopen in Container".

The workspace file predefines tasks to build and deploy an application, and to run it on a target image by invoking the target.sh script. The predefined tasks refer to an "active build preset" corresponding to a CMake Presets file in the source directory of the application. Once a CMake Presets file is selected for either an LI Application or an HI Application, the steps of this section are identical for developing LI Application or HI Application software, except that running an application interactively is not admissible for an HI Application.

Create the layer directory structure following the BitBake naming convention, and add a configuration file in the layer’s conf subdirectory.

For the example application layer consider the appdev/meta-appdev directory. The directory contains a recipes-apps subdirectory for example application recipes and a conf subdirectory. The conf subdirectory contains the layer.conf configuration file of the layer.

The BitBake variables used in the configuration file are:

For further variables which may be used in a layer’s configuration file refer to Understanding and Creating Layers in the Yocto documentation.

Specify the location and possibly further properties of the BitBake layer in a Kas project configuration.

For the example application layer, the Kas project configuration is in the kas directory.

Refer to Configuration reference in the Kas documentation for further properties which can be specified in a Kas project configuration.

Run a Kas command with the additional project configuration included on the command line.

For the example application layer, and as an example Kas command, you can use the kas dump command to examine the merged project configuration with the additional example application layer.

The result is the merged Kas project configuration in YAML format with a meta-appdev list item under the repos key.

In this variant, the SSH keys are generated during the build of the target image, and the generated private key is deployed to the workspace of the development container.

In this variant, the user provides own SSH keys, and the public key is deployed to the target image during the build. No SSH keys are generated during the build, and no private key is deployed to the workspace.

The steps for running and accessing the target image are identical to the corresponding steps for using generated keys and are therefore omitted in this section.

This section describes the packaging of LI Application software according to the sequence shown in Figure 5, “Interaction for Packaging Application Software”.

This section describes the packaging of HI Application software according to the sequence shown in Figure 5, “Interaction for Packaging Application Software”. The generic descriptions of the steps for packaging HI Application software are identical to the descriptions of the steps for LI Application software in Packaging LI Application Software. This section describes only the differences between packaging HI Application and LI Application software related to the example HI Application.

Add the application package to the list of packages to be installed in the target image. The packages to be installed in a target image are determined by the IMAGE_INSTALL variable of an image recipe.

To add the hello-world package to the fastdev image recipe, copy the fastdev image recipe to a myfastdev image recipe in the example application layer, and append the hello-world package to the IMAGE_INSTALL variable.

You can inspect the extended IMAGE_INSTALL variable by using the bitbake-getvar tool.

On success, the IMAGE_INSTALL variable contains the hello-world package.

Build the target image with its extended recipe.

To build the myfastdev target image, include the Kas project configuration for the example application layer.

After a successful build, the myfastdev target image can be found in the build/tmp/deploy/images/ebcl-qemuarm64 deployment directory.

Run the target image with the integrated application in a QEMU system emulation.

For the myfastdev target image with the "Hello World" application, you can use the provided qemu.sh script.

On success, the qemu.log log file in the workspace directory shows the "Hello world" and "Hello again" messages on startup according to the hello.c source file shown in step Create Source Files for LI Application Software.

Create a YAML configuration file to generate a layer for the prebuilt package with the Reposync utility, including the name of the prebuilt package, its upstream Apt repository, and the priority of the layer.

For the "GNU Hello" example, consider the following configuration for a meta-example-prebuilt-packages layer.

There might be package recipes in the generated layer for which there is already a package recipe in the delivery of the EB corbos Toolkit with identical names but referring to different packages. Integrating the package of the newly generated recipe might therefore lead to the loss of the integrity of already integrated packages in a target image. To maintain the integrity of already integrated packages, the priority of the newly generated layer is chosen as "5" which is lower than the priority of the layers in the delivery of the EB corbos Toolkit.

To avoid a faulty installation of a new prebuilt package, ensure that the dependencies of this package are compatible with existing packages. This can be achieved by using a prebuilt package with no or only new runtime dependencies, or by using an upstream Apt repository for a prebuilt package for which the package has only compatible dependencies.

Use the Reposync utility to generate the layer for the prebuilt package based on its configuration.

For the "GNU Hello" example, create the meta-example-prebuilt-packages layer from its configuration of the previous step.

After successful generation, the meta-example-prebuilt-packages layer can be found in the appdev/meta-appdev directory and contains prebuilt package recipes for both the "hello" package and its runtime dependencies.

Create a Kas configuration to include the generated layer in the build of a target image.

For the "GNU Hello" example, you can use the following Kas configuration.

You can use the kas dump command to examine the merged project configuration with the additional meta-example-prebuilt-packages layer.

The result is the merged Kas configuration in YAML format with a meta-example-prebuilt-packages list item under the repos key.

Add the prebuilt package to the list of packages to be installed in a target image. The packages to be installed in a target image are determined by the IMAGE_INSTALL variable of the image recipe.

For the "GNU Hello" example, copy the fastdev image recipe to a myfastdev image recipe in the example application layer, and append the hello package to the IMAGE_INSTALL variable.

You can inspect the extended IMAGE_INSTALL variable of the myfastdev image recipe by using the bitbake-getvar tool.

On success, the IMAGE_INSTALL variable contains the hello package.

Build the target image with its extended recipe and the generated layer for the prebuilt package.

For the "GNU Hello" example, build the myfastdev target image with Kas configurations for both the example application layer and the generated meta-example-prebuilt-packages layer.

After a successful build, the myfastdev target image can be found in the build/tmp/deploy/images/ebcl-qemuarm64 deployment directory.

Run the target image with the prebuilt package in a QEMU system emulation.

For the "GNU Hello" example, run the myfastdev image built in the previous step with the qemu.sh script.

You can examine the functionality of the integrated package by invoking the "GNU Hello" program in the shell of the running target image.

On success, the "GNU Hello" program responds with "Hello, world!".

A build aborts early with a PermissionError while BitBake tries to disable network access for a task, for example:

Since Ubuntu 23.10, Canonical restricts the creation of unprivileged user namespaces via AppArmor for security reasons. BitBake relies on user namespaces (for example to write to /proc/self/uid_map when isolating a task from the network), so the restriction makes affected tasks fail.

This is a property of the host kernel and its AppArmor configuration. It therefore also affects BitBake running inside the development container.

The recommended fix adds a small AppArmor profile that grants the userns permission to the BitBake executable, leaving the restriction in place for all other programs.

The EB corbos Toolkit detects the described situation automatically on the host before the development container starts. It also offers to apply the recommended fix on your host for you after confirmation. Applying the fix requires sudo access.

In case you want to understand the automatic diagnosis and fixing better, take a look at check_userns_restriction.sh in the .devcontainer sub-directory.

In case you do not want to apply the fix automatically, you can do so manually as described below:

Run the following commands on your host and then restart the build: