Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 9 Next »

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 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

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.

  • No labels