Overview
This application note explains how to use the Ubuntu Compatibility Layer in the Emcraft software distribution for the Renesas RZ/V2H SoC.
Understanding Ubuntu Compatibility Layer
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.
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:
meta-renesas-desktop/ ├── classes │ ├── nativeaptinstall.bbclass │ └── ubuntu-image.bbclass ├── conf │ ├── bblayers.conf.sample │ ├── conf-notes.txt │ ├── distro │ ├── layer.conf │ └── local.conf.sample ├── dynamic-layers │ ├── core │ ├── econsys │ ├── rz-common │ ├── rz-drpai │ ├── rz-emcraft │ └── rz-graphics ├── recipes-connectivity │ └── ubuntu-network-config ├── recipes-desktop │ ├── images │ ├── install-royale-runner │ └── ubuntu-base ├── recipes-devtools │ ├── pseudo │ └── qemu ├── recipes-ros │ └── ros-setup
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 asimage-ubuntu-desktop.recipes-devtools- this directory contains recipes forpseudoandqemuported 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
Using Ubuntu Compatibility Layer
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:
user@rzv2hevkalphaemc:~$ dpkg -l Desired=Unknown/Install/Remove/Purge/Hold | Status=Not/Inst/Conf-files/Unpacked/halF-conf/Half-inst/trig-aWait/Trig-pend |/ Err?=(none)/Reinst-required (Status,Err: uppercase=bad) ||/ Name Version Architecture Description +++-=================================================-=======================================-============-==============================================================================================================================================================================> ii accountsservice 22.07.5-2ubuntu1.4 arm64 query and manipulate user account information ii acl 2.3.1-1 arm64 access control list - utilities ii adduser 3.118ubuntu5 all add and remove users and groups ii adwaita-icon-theme 41.0-1ubuntu1 all default icon theme of GNOME (small subset) ii adwaita-icon-theme-full 41.0-1ubuntu1 all default icon theme of GNOME ii alsa-base 1.0.25+dfsg-0ubuntu7 all ALSA driver configuration files ...
For example, the pre-installed NetworkManager packager allows configuring Ethernet connections:
user@rzv2hevkalphaemc:~$
user@rzv2hevkalphaemc:~$ nmcli
eth0: connected to Wired connection 1
"eth0"
ethernet (dwc-eth-dwmac), BA:F4:39:68:DA:73, hw, mtu 1500
ip4 default
inet4 192.168.0.152/24
route4 192.168.0.0/24 metric 100
route4 default via 192.168.0.1 metric 100
inet6 fe80::e181:54eb:8517:c18b/64
route6 fe80::/64 metric 1024
docker0: connected (externally) to docker0
"docker0"
bridge, 02:42:2F:43:14:13, sw, mtu 1500
inet4 172.17.0.1/16
route4 172.17.0.0/16 metric 0
eth1: unavailable
"eth1"
ethernet (dwc-eth-dwmac), 2E:03:EC:12:57:EE, hw, mtu 1500
...
Another example is the systemd suite, which manages the services and Linux boot:
user@rzv2hevkalphaemc:~$ systemctl list-units --state=active *.service UNIT LOAD ACTIVE SUB DESCRIPTION alsa-restore.service loaded active exited Save/Restore Sound Card State apport.service loaded active exited LSB: automatic crash report generation avahi-daemon.service loaded active running Avahi mDNS/DNS-SD Stack chrony.service loaded active running chrony, an NTP client/server console-setup.service loaded active exited Set console font and keymap containerd.service loaded active running containerd container runtime dbus.service loaded active running D-Bus System Message Bus docker.service loaded active running Docker Application Container Engine getty@tty1.service loaded active running Getty on tty1 keyboard-setup.service loaded active exited Set the console keyboard layout kmod-static-nodes.service loaded active exited Create List of Static Device Nodes ModemManager.service loaded active running Modem Manager networkd-dispatcher.service loaded active running Dispatcher daemon for systemd-networkd NetworkManager-wait-online.service loaded active exited Network Manager Wait Online NetworkManager.service loaded active running Network Manager ...
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.
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:
user@rzv2hevkalphaemc:~$ sudo apt-get install nano Reading package lists... Done Building dependency tree... Done Reading state information... Done Suggested packages: hunspell The following NEW packages will be installed: nano 0 upgraded, 1 newly installed, 0 to remove and 3 not upgraded. Need to get 277 kB of archives. After this operation, 872 kB of additional disk space will be used. Get:1 http://ports.ubuntu.com/ubuntu-ports jammy/main arm64 nano arm64 6.2-1 [277 kB] Fetched 277 kB in 1s (267 kB/s) Selecting previously unselected package nano. (Reading database ... 160205 files and directories currently installed.) Preparing to unpack .../archives/nano_6.2-1_arm64.deb ... Unpacking nano (6.2-1) ... Setting up nano (6.2-1) ... update-alternatives: using /bin/nano to provide /usr/bin/editor (editor) in auto mode update-alternatives: warning: skip creation of /usr/share/man/man1/editor.1.gz because associated file /usr/share/man/man1/nano.1.gz (of link group editor) doesn't exist update-alternatives: using /bin/nano to provide /usr/bin/pico (pico) in auto mode update-alternatives: warning: skip creation of /usr/share/man/man1/pico.1.gz because associated file /usr/share/man/man1/nano.1.gz (of link group pico) doesn't exist Processing triggers for man-db (2.10.2-1) ... user@rzv2hevkalphaemc:~$ nano 1.txt ...
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.
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.
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.
user@(docker)$ bitbake-layers show-layers NOTE: Starting bitbake server... layer path priority ========================================================================== meta-gplv2 /opt/yocto/sources/poky/../meta-gplv2 1 meta /opt/yocto/sources/poky/../poky/meta 5 meta-poky /opt/yocto/sources/poky/../poky/meta-poky 5 meta-yocto-bsp /opt/yocto/sources/poky/../poky/meta-yocto-bsp 5 meta-rz-common /opt/yocto/sources/poky/../meta-renesas/meta-rz-common 15 meta-rzg2l /opt/yocto/sources/poky/../meta-renesas/meta-rzg2l 15 meta-rzv2 /opt/yocto/sources/poky/../meta-renesas/meta-rzv2 15 meta-oe /opt/yocto/sources/poky/../meta-openembedded/meta-oe 6 meta-python /opt/yocto/sources/poky/../meta-openembedded/meta-python 7 meta-multimedia /opt/yocto/sources/poky/../meta-openembedded/meta-multimedia 6 meta-filesystems /opt/yocto/sources/poky/../meta-openembedded/meta-filesystems 6 meta-networking /opt/yocto/sources/poky/../meta-openembedded/meta-networking 5 meta-rz-graphics /opt/yocto/sources/poky/../meta-rz-graphics 16 meta-rz-drpai /opt/yocto/sources/poky/../meta-rz-drpai 16 meta-rz-multi-os /opt/yocto/sources/poky/../meta-rz-multi-os 16 meta-econsys /opt/yocto/sources/poky/../meta-econsys 1 meta-virtualization /opt/yocto/sources/poky/../meta-virtualization 8 meta-renesas-desktop /opt/yocto/sources/poky/../meta-renesas-desktop 6 meta-rz-emcraft /opt/yocto/sources/poky/../meta-rz-emcraft 15 user@(docker)$ bitbake-layers remove-layer meta-renesas-desktop NOTE: Starting bitbake server... user@(docker)$ bitbake-layers show-layers NOTE: Starting bitbake server... layer path priority ========================================================================== meta-gplv2 /opt/yocto/sources/poky/../meta-gplv2 1 meta /opt/yocto/sources/poky/../poky/meta 5 meta-poky /opt/yocto/sources/poky/../poky/meta-poky 5 meta-yocto-bsp /opt/yocto/sources/poky/../poky/meta-yocto-bsp 5 meta-rz-common /opt/yocto/sources/poky/../meta-renesas/meta-rz-common 15 meta-rzg2l /opt/yocto/sources/poky/../meta-renesas/meta-rzg2l 15 meta-rzv2 /opt/yocto/sources/poky/../meta-renesas/meta-rzv2 15 meta-oe /opt/yocto/sources/poky/../meta-openembedded/meta-oe 6 meta-python /opt/yocto/sources/poky/../meta-openembedded/meta-python 7 meta-multimedia /opt/yocto/sources/poky/../meta-openembedded/meta-multimedia 6 meta-filesystems /opt/yocto/sources/poky/../meta-openembedded/meta-filesystems 6 meta-networking /opt/yocto/sources/poky/../meta-openembedded/meta-networking 5 meta-rz-graphics /opt/yocto/sources/poky/../meta-rz-graphics 16 meta-rz-drpai /opt/yocto/sources/poky/../meta-rz-drpai 16 meta-rz-multi-os /opt/yocto/sources/poky/../meta-rz-multi-os 16 meta-econsys /opt/yocto/sources/poky/../meta-econsys 1 meta-virtualization /opt/yocto/sources/poky/../meta-virtualization 8 meta-rz-emcraft /opt/yocto/sources/poky/../meta-rz-emcraft 15 user@(docker)$ bitbake-layers add-layer ../sources/meta-renesas-desktop NOTE: Starting bitbake server... user@(docker)$ bitbake-layers show-layers NOTE: Starting bitbake server... layer path priority ========================================================================== meta-gplv2 /opt/yocto/sources/poky/../meta-gplv2 1 meta /opt/yocto/sources/poky/../poky/meta 5 meta-poky /opt/yocto/sources/poky/../poky/meta-poky 5 meta-yocto-bsp /opt/yocto/sources/poky/../poky/meta-yocto-bsp 5 meta-rz-common /opt/yocto/sources/poky/../meta-renesas/meta-rz-common 15 meta-rzg2l /opt/yocto/sources/poky/../meta-renesas/meta-rzg2l 15 meta-rzv2 /opt/yocto/sources/poky/../meta-renesas/meta-rzv2 15 meta-oe /opt/yocto/sources/poky/../meta-openembedded/meta-oe 6 meta-python /opt/yocto/sources/poky/../meta-openembedded/meta-python 7 meta-multimedia /opt/yocto/sources/poky/../meta-openembedded/meta-multimedia 6 meta-filesystems /opt/yocto/sources/poky/../meta-openembedded/meta-filesystems 6 meta-networking /opt/yocto/sources/poky/../meta-openembedded/meta-networking 5 meta-rz-graphics /opt/yocto/sources/poky/../meta-rz-graphics 16 meta-rz-drpai /opt/yocto/sources/poky/../meta-rz-drpai 16 meta-rz-multi-os /opt/yocto/sources/poky/../meta-rz-multi-os 16 meta-econsys /opt/yocto/sources/poky/../meta-econsys 1 meta-virtualization /opt/yocto/sources/poky/../meta-virtualization 8 meta-rz-emcraft /opt/yocto/sources/poky/../meta-rz-emcraft 15 meta-renesas-desktop /opt/yocto/sources/meta-renesas-desktop 6 bdn@(docker)$
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.