1. Overview

This application note explains how to use the Ubuntu Compatibility Layer in the Emcraft software distribution for the Renesas RZ/V2H SoC.

2. Understanding Ubuntu Compatibility Layer

2.1. Purpose of the Ubuntu Compatibility Layer

The Ubuntu Compatibility Layer allows certain packages from the Renesas RZ/V2H EVK BSP to be co-installed with packages from the ARM64 port of Ubuntu Desktop operating system, combining those packages into a single image. This allows users to build images that can combine the vast functionality coming from Ubuntu Desktop packages, and other compatible distributions such as the ROS2 distribution, with the lower-level hardware and basic OS support provided by the Renesas RZ/V2H EVK BSP.

2.2. Structure of the Ubuntu Compatibility Layer

The Ubuntu Compatibility Layer is integrated into the Emcraft software distribution as the meta-renesas-desktop Yocto layer with the following layout:

The layer is based on the https://github.com/nxp-imx/meta-nxp-desktop with appropriate adaptations required to support the Renesas RZ/V2H BSP.

Metadata classes: /classes

• nativeaptinstall.bbclass - this class contains the main functionality behind the Ubuntu Distribution installation on top of the Yocto-provided root file system.

• ubuntu-image.bbclass - this class contains the common functionality shared by recipes for Ubuntu-based images.

Metadata Configuration: /conf

• bblayers.conf.sample - a sample set of layers to build the Emcraft Software distribution for the RZ/V2H EVK.

• conf-notes.txt - a build environment prompt.

• local.conf.sample - a sample build environment configuration to build the Emcraft Software distribution for the RZ/V2H EVK.

• layer.conf - the layer configuration.

• distro - a set of configuration files common to the Ubuntu Desktop distribution.

Dynamic layers metadata: /dynamic-layers.This directory contains the recipe appends corresponding to the core Yocto distribution and various Renesas BSP Yocto layers. The appends are required to adapt the recipes for building for the Ubuntu Desktop environment and file system directory layout which is slightly different from the one used in Yocto.

Layer-specific recipes: /recipes-...

• recipes-connectivity - this directory contains recipes ,which provide the default network configuration for the board.

• recipes-desktop - this directory provides recipes for building Ubuntu Desktop images such as image-ubuntu-desktop.

• recipes-devtools - this directory contains recipes for pseudo and qemu ported from the https://github.com/nxp-imx/meta-nxp-desktop to perform installations of the ARM64 packages in the emulated execution environment.

• recipes-ros - this directory contains recipes for the default out-of-box setup for the ROS2 execution environment

3. Using Ubuntu Compatibility Layer

3.1. Using Ubuntu Compatibility Layer to Run Pre-installed Ubuntu Packages

The Compatibility layer pre-installs many Ubuntu packages onto the Emcraft release image, which can be used out of the box once the image has been flashed and booted on the target:

For example, the pre-installed NetworkManager packager allows configuring Ethernet connections:

Another example is the systemd suite, which manages the services and Linux boot:

The set of the pre-installed Ubuntu packages can be specified in the image recipe image-ubuntu-desktop.bb using the APTGET_EXTRA_PACKAGES and APTGET_EXTRA_PACKAGES_LAST variables. The mechanics of these variables and relevant information is documented in the nativeaptinstall.bbclass.

3.2. Using Ubuntu Compatibility Layer to Add Ubuntu Packages from Internet

The Compatibility layer allows adding and removing Ubuntu packages from the Internet at run-time. Packages can be added either from the official Ubuntu archive or private package archives.

In the example below the simple nano editor is being installed from the Ubuntu archive on the system and then used to edit a file:

4. Understanding Caveats of Using Ubuntu Compatibility Layer

Though the Ubuntu Compatibility Layer allows for the Yocto packages to co-exist with the Ubuntu packages on the same file system, there are certain limitations, which can result in an ultimate mis-function of the resulting software distribution.

4.1. Possible Conflicts Between Renesas Packages and Ubuntu Compatibility Layer

There are two main constituents into the possibility of conflicts between the Renesas BSP packages and the Ubuntu packages installed onto the same target image.

The first constituent comes from the fact that the file system is formed in two phases. The first phase is where the Renesas BSP packages are installed. Then the second phase installs the Ubuntu packages on top of that.

The first phase uses the RPM package management system, thus these packages are not taken into account by the second phase where the Ubuntu DEB package management system is used. This results in a situation where the files installed via unpacking of the Renesas BSP packages may then be overwritten by the Ubuntu packages. If this is the case, some precautions must be explicitly taken to save the needed files after the first phase and to restore them after the second one. In the Ubuntu Compatibility layer image recipes which are based on the ubuntu-image.bbclass can define specific functions which do the save and restore logic and add the function names to the UBUNTU_APTGET_PREFUNCS and/or UBUNTU_APTGET_POSTFUNCS variables respectively. This would allow calling these functions right before and after the second phase.

The second constituent comes from the fact that the code base of the Renesas BSP packages and the Ubuntu packages may be incompatible with each other. For example, if versions of some BSP package and a counterpart Ubuntu package differ significantly, this might result in inability to use the packages simultaneously due to API inconsistencies. This only can be mitigated by individually porting of the affected Renesas BSP packages to the code base versions compatible with the counterpart Ubuntu packages.

Emcraft has taken precautions to address all Yocto vs Ubuntu incompatibility issues we have come across. If you run into a related issue, please contact Emcraft.

4.2. Configuring Ubuntu Compatibility Layer in the Build

The Ubuntu Compatibility layer can be added and removed by directly editing the bblayers.conf. Alternatively, the meta-renesas-desktop layer can be added or removed from the build using the bitbake-layers command.

In the example below, the bitbake-layers command is used to show, remove the Ubuntu Compatibility layer from the build, and then add it back. The example assumes that the layer contents coexist with the rest Yocto layers participating in the build.

NOTE: The meta-renesas-desktop layer defines the ubuntu-desktop distribution configuration, which is implied when building the Ubuntu-compatible images. Make sure to change the DISTRO variable in the local.conf when either removing or adding the Ubuntu Compatibility layer from the build.