Software Overview

As a collaboration between Canonical and MediaTek, Ubuntu on Genio is designed to run Ubuntu Server and Ubuntu Desktop on MediaTek Genio EVK.

The current version is Ubuntu 22.04.2 LTS (Jammy Jellyfish). It incorporates an Ubuntu derivative kernel officially maintained by Canonical.

Ubuntu on Genio is also designed to have a standardized EBBR (Embedded Base Boot Requirements) boot flow, so Genio board vendors have the option to become Ubuntu Certified.

This page explains the overall software architecture for this collaboration, along with the maintenance responsibilities between Canonical, MediaTek, and potentially board and solution vendors using Genio SoC.

Software Architecture

Conceptually Ubuntu on Genio consists of the following components:

• Boot firmware, including bootloader, board configuration settings and other bootloader resources such as boot logo.

• Ubuntu images which contain system packages defined by different Ubuntu releases, such as Server and Desktop.

• Ubuntu Kernel with drivers for MediaTek Genio SoC and Genio EVK boards

• The Ubuntu archive is a Debian-style pooled package repository with further packages available for download.

• The Ubuntu on Genio hardware support packages are installable packages in Debian archive (dpkg, .deb) format. These packages are provided by MediaTek under proprietary licensing terms to provide support for advanced Genio SoC features, such as:

  • Hardware video codec

  • AI/ML hardware accelerator

Canonical maintains the following components:

• Ubuntu kernel,

• Ubuntu images,

• Ubuntu archive,

while MediaTek maintains the following components:

• Boot firmware,

• Genio hardware support packages.

This can be depicted in the following diagram:

In detail:

• MediaTek provides the bootloaders that boot into the Ubuntu kernel.

• Canonical provides and maintains the Ubuntu kernel and Ubuntu archive.

• The kernel drivers in the Ubuntu kernel are maintained by Canonical, with technical support and patches from MediaTek for the Genio SoC driver and board hardware.

• The Ubuntu archive and Ubuntu OS images are maintained and released by Canonical.

• The Genio support packages are maintained and released by MediaTek. Some packages are access-controlled.

A “flash-able” Ubuntu on Genio image for Genio EVK consists of 2 archives:

1. A disk image archive that contains Ubuntu kernel and the rootfs, with packages defined by the Ubuntu release type, such as Server or Desktop. This image archive is released by Canonical and is compatible with multiple Genio EVK boards.

2. One boot firmware archive for each Genio EVK. Unlike the disk image, the boot firmware is only compatible with its designated Genio board. The archive name looks like this: ubuntu-boot-firmware-genio-1200-evk-v23.1.3.tar.gz.

You need both archives to flash the Ubuntu system to a Genio EVK board. Please visit Get Started with Ubuntu on Genio to know how to set up the tooling environment and flash the board.

Boot Flow

The bootloaders provided by MediaTek for Ubuntu on Genio are based on Embedded Base Boot Requirements (EBBR), which is a subset of the UEFI specification.

The implementation of the bootloader follows ARM boot architecture and can be divided into several stages:

• BL2: initializes system DRAM and storage. It is implemented with Trusted-Firmware-A (TF-A).

• BL31: initializes important platform firmware and infrastructure functions. This is also implemented with TF-A.

• BL32: initializes secure world. It is implemented with OP-TEE.

• BL33: provides most of the bootloader functions and is responsible for supporting the EBBR boot flow. This is implemented with U-Boot.

The bootloader actually shares most of the implementation with IoT Yocto, so details of the boot flow could be found in the online documentation of IoT Yocto: https://mediatek.gitlab.io/aiot/doc/aiot-dev-guide/master/sw/yocto/boot.html.

The major difference here is that IoT Yocto does not adopt the EBBR boot flow, which is required by Ubuntu on Genio. As of v23.1, IoT Yocto adopts FIT boot flow, which is the default flow of U-Boot.

Most of the support of EBBR boot flow is implemented with U-Boot. In U-Boot, most of the boot flow could be controlled by a boot script. The implementation of the IoT Yocto and Ubuntu on Genio actually allows switching between the FIT boot and EBBR boot by simply modifying the U-Boot boot script stored as an environment variable boot_targets.

Note

Because the bootloader implementation is based on IoT Yocto, you need to build the boot firmware for your boards using IoT Yocto. The steps are described in Modify Bootloader.

Device Tree and EFI System Loader

After U-Boot initializes, it searches for the proper device tree binary (dtb) files from the U-Boot environment variable. The variables are stored on the EMMC boot1 partition for all Genio EVK boards using Ubuntu on Genio.

The EBBR specification mandates the bootloader to search for bootable EFI system loaders on the EFI System Partition, which have a specific partition GUID C12A7328-F81F-11D2-BA4B-00A0C93EC93B according to UEFI Specification. U-Boot then passes the device tree binary and other mandatory EFI system information to the system loader.

The Ubuntu image archive provides the EFI system loaders. On Ubuntu Classic (Server & Desktop), the system loader bootstraps into the GRUB loader, and eventually boots into the Ubuntu kernel.

Unlike generic Ubuntu installable ISO images, the Ubuntu on Genio for Genio EVKs use a single storage device, usually, EMMC, stores both the bootloader and the Ubuntu OS partitions.

Therefore, Canonical and MediaTek have to settle on a pre-defined partition layout to accommodate both the bootloader and the Ubuntu OS partition on the same storage device.

Note

Because the partition layout is determined by the disk image archive (ubuntu.img) and is therefore controlled by Canonical. Board and solution vendors will have to contact Canonical if a different partition layout is required.

OS Image and Boot Firmware

For each board, two image archives are required to boot the board into Ubuntu:

1. An Ubuntu image released by Canonical.

2. A boot firmware for each Genio EVK board, which contains these key components:

   • Bootloaders for specific MediaTek Genio EVK. Each asset is board-specific.

   • Binary device tree files describing the EVK hardwares are also included in the boot firmware. The bootloader would then pass the corresponding device tree binary to Linux kernel during bootup.

Please visit the download page and download both packages according to the model of the Genio EVK board you’re currently evaluating.

To flash the Ubuntu image onto Genio EVK board, extract both the Ubuntu image archive and boot firmware archive, and then run genio-flash to flash the image to the Genio EVK board storage.

The Get Started with Ubuntu on Genio page provides detailed steps for each Genio EVK.

The following diagram illustrates this process:

Partition Layout

In the layout scheme defined in the previous section, a partition is always one of these two categories:

• A “firmware” defined partition is controlled by the board firmware(bootloader) vendors.

• An “OS” defined partition is controlled by the Ubuntu release.

The following table describes the partition scheme for Genio EVK boards, which use EMMC storage:

Partition Layout for Ubuntu on Genionio on Genio EVK boards

Category	Partition Label	Size	Partition Image	Remark
OS	writable	OS dependent	ubuntu.img	rootfs managed by Ubuntu
OS	ubuntu-boot	OS dependent	ubuntu.img	Ubuntu EFI system loaders
Firmware	bootassets	32MB	bootassets.vfat	Static bootloader data such as boot logos
Firmware	misc	1MB	N/A	Support A/B firmware update feature
Firmware	dramk	512KB	N/A	One-time programming for per-board DRAM calibration data
Firmware	firmware_b	32MB	firmware.vfat	The content in firmware and firmware_b should be the same initially
Firmware	firmware	32MB	firmware.vfat	Containing following per-board assets: dtb + dtbo Other firmware blobs
Firmware	bootloaders_b	4MB	fip.bin	The content in bootloaders and bootloaders_b should be the same initially
Firmware	bootloaders	4MB	fip.bin	Containing fip.bin, which consists of BL3* loaders (BL31, BL32, BL33)
Firmware	mmc0boot1	HW dependent	u-boot-env.bin	Runtime generated by genio-flash tool based on u-boot-initial-env plain text file and additional configurations
Firmware	mmc0boot0	HW dependent	bl2.img	2nd stage bootloader based on Trusted-Firmware-A

Hardware Customization

Hardware vendors could refer to Customization to enable new boards and modules for classic Ubuntu images, including Ubuntu Server and Ubuntu Desktop.

For Ubuntu Core, the process is a bit different. Please refer to the board enablement guide for Ubuntu Core or contact Canonical for engineering services.