LEC-MTK-1200 Ubuntu Build Guide

Overview

This guide provides step-by-step instructions for deploying Ubuntu Desktop on the LEC-MTK-1200 platform. MediaTek supplies official Ubuntu images only for their EVK (Evaluation Kit) through their partnership with Canonical. Therefore, deploying Ubuntu on the ADLINK LEC-MTK-1200 requires a hybrid approach: the system boots using the EVK Ubuntu image, and specific firmware components are then replaced with custom-built binaries generated from Yocto.

The build process is carried out in two stages:

  1. Build the Yocto image on the host machine and flash it onto the module.
  2. Build the Ubuntu kernel on the host machine and install it on the module.

Prerequisites

Hardware Requirements

  • I-Pi SMARC 1200 development kit(Carrier, Module and etc.)
  • Ubuntu 20.04 host pc
  • Stable internet connection for downloading images and flashing tools

Software Requirements

  • Yocto build environment configured for LECM-MTK-1200.

1. Building Custom Firmware with Yocto

1.1 Configure Yocto Build Environment

Follow this build guide for building Yocto for LEC-MTK-1200.

1.2 Build Yocto Image

Execute the Yocto build process. Once the build is completed, locate the build output directory

build-directory/tmp/deploy/images/<MACHINE\>/

For reference purposes, we’ll call this directory {BOOT_FIRMWARE}.

1.3 Verify Required Firmware Files

Ensure the following binary files are present in the build output:

  • bl2.img
  • bootassets.vfat
  • fip.bin
  • lk.bin
  • u-boot-initial-env
  • firmware.vfat
  • partition.json

If firmware.vfat is not present, generate it by building the firmware partition using the following

bitbake -c cleanall firmware-part ; bitbake firmware-part

2. Preparing the Ubuntu Base Image

2.1 Download MTK Genio Ubuntu Image

Download the Ubuntu base image from ADLINK server by clicking_here.

2.2 Copy the Downloaded Ubuntu Image

Create a new directory called UBUNTU_IMAGE, navigate into it, and copy the downloaded Ubuntu image into the directory

mkdir UBUNTU_IMAGE
cd UBUNTU_IMAGE/
cp <path_to_downloaded_Ubuntu_image>/ubuntu.img .

2.3 Integrate Custom Firmware

Copy the previously Yocto built firmware files into the Ubuntu image directory:

cp {BOOT_FIRMWARE}/bl2.img {BOOT_FIRMWARE}/bootassets.vfat {BOOT_FIRMWARE}/fip.bin {BOOT_FIRMWARE}/lk.bin {BOOT_FIRMWARE}/u-boot-initial-env {BOOT_FIRMWARE}/firmware.vfat {BOOT_FIRMWARE}/partition.json {UBUNTU_IMAGE}/

2.4 Modify Environment and JSON File

Modify the environment configuration file (u-boot-initial-env) by updating specific boot parameters and command.

diff --git a/u-boot-initial-env b/u-boot-initial-env
index 126607f..8849782 100644
--- a/u-boot-initial-env
+++ b/u-boot-initial-env
-boot_net_usb_start=usb start
-boot_targets=embedded
+boot_targets=scsi2
-bootcmd_embedded=bootembedded
-bootcmd_usb0=devnum=0; run usb_boot
-distro_bootcmd=scsi_need_init=; for target in ${boot_targets}; do run bootcmd_${target}; done
-efi_dtb_prefixes=/ /dtb/ /dtb/current/
+distro_bootcmd=scsi_need_init=; for target in ${boot_targets}; do if test "${target}" != "embedded"; then dtbprobe ${storage} ${storage_dev} /FIRMWARE/mediatek/lec-mtk-i1200-ufs/; fi; run bootcmd_${target}; done
+
+fdt_resize=10240
-load_efi_dtb=load ${devtype} ${devnum}:${distro_bootpart} ${fdt_addr_r} ${prefix}${efi_fdtfile}
+load_efi_dtb=load ${devtype} ${devnum}:3 ${fdt_addr_r} /FIRMWARE/mediatek/lec-mtk-i1200-ufs/${fdtfile}
-scan_dev_for_efi=setenv efi_fdtfile ${fdtfile}; for prefix in ${efi_dtb_prefixes}; do if test -e ${devtype} ${devnum}:${distro_bootpart} ${prefix}${efi_fdtfile}; then run load_efi_dtb; fi;done;run boot_efi_bootmgr;if test -e ${devtype} ${devnum}:${distro_bootpart} efi/boot/bootaa64.efi; then echo Found EFI removable media binary efi/boot/bootaa64.efi; run boot_efi_binary; echo EFI LOAD FAILED: continuing...; fi; setenv efi_fdtfile
+scan_dev_for_efi=setenv efi_fdtfile ${fdtfile};run load_efi_dtb;run load_efi_overlays;run boot_efi_bootmgr;if test -e ${devtype} ${devnum}:${distro_bootpart} efi/boot/bootaa64.efi; then echo Found EFI removable media binary efi/boot/bootaa64.efi; run boot_efi_binary; echo EFI LOAD FAILED: continuing...; fi; setenv efi_fdtfile
+load_efi_overlays=for overlay in ${list_dtbo}; do if test -e ${devtype} ${devnum}:3 FIRMWARE/mediatek/lec-mtk-i1200-ufs/$overlay; then echo Applying overlay $overlay...; load ${devtype} ${devnum}:3 ${fdtoverlay_addr_r} FIRMWARE/mediatek/lec-mtk-i1200-ufs/$overlay; fdt addr ${fdt_addr_r}; fdt resize 10240; fdt apply ${fdtoverlay_addr_r}; fi; done
-dtb_path=/FIRMWARE/mediatek/lec-mtk-i1200-ufs/
-efi_dtb_prefixes=${dtb_path} / /dtb/ /dtb/current/
-boot_targets=embedded
-distro_bootcmd=for target in ${boot_targets}; do if test "${target}" != "embedded"; then dtbprobe ${storage} ${storage_dev} ${dtb_path}; fi; run bootcmd_${target}; done
-scan_dev_for_efi=run boot_efi_bootmgr;if test -e ${devtype} ${devnum}:${distro_bootpart} efi/boot/bootaa64.efi; then echo Found EFI removable media binary efi/boot/bootaa64.efi; run boot_efi_binary; echo EFI LOAD FAILED: continuing...; fi

You will also need to configure the ubuntu.json file to handle partitioning, environment variables, and bootloader settings.

  • In the working directory, create a new file named ubuntu.json

    touch {UBUNTU_IMAGE}/ubuntu.json

  • Open the ubuntu.json file and add the following JSON configuration:

    {
      "ubuntu-env": {
        "edition": "Ubuntu classic/core images",
        "codename": "jammy",
        "version": "22.04"
      },
      "uboot-env": {
        "env-redund-support": false
      },
      "genio-tools": {
        "min-version": "1.3.dev2"
      },
      "partitions": {
        "mmc0": "ubuntu.img",
        "mmc0boot0": "bl2.img",
        "mmc0boot1": "u-boot-env.bin",
        "bootloaders": "fip.bin",
        "bootloaders_b": "fip.bin",
        "firmware": "firmware.vfat",
        "firmware_b": "firmware.vfat",
        "dramk": null,
        "misc": null,
        "capsule": "capsule.vfat",
        "bootassets": "bootassets.vfat"
      },
      "groups": {
        "all": {
          "erase": [
            "mmc0",
            "mmc0boot0",
            "mmc0boot1",
            "bootloaders",
            "bootloaders_b",
            "firmware",
            "firmware_b",
            "bootassets"
          ],
          "flash": [
            "mmc0",
            "mmc0boot0",
            "mmc0boot1",
            "bootloaders",
            "bootloaders_b",
            "firmware",
            "firmware_b",
            "bootassets"
          ]
        },
        "bootloaders": {
          "flash": ["bootloaders"]
        },
        "erase-emmc": {
          "erase": ["mmc0", "mmc0boot0", "mmc0boot1"]
        },
        "board-assets": {
          "flash": [
            "mmc0boot0",
            "mmc0boot1",
            "bootloaders",
            "bootloaders_b",
            "firmware",
            "firmware_b",
            "bootassets"
          ]
        }
      }
    }

2.5 Verify Image Directory Contents

The resulting directory should contain at minimum:

$ls
bl2.img
bootassets.vfat
fip.bin
firmware.vfat
lk.bin
u-boot-initial-env
ubuntu.img
ubuntu.json
partition.json

2.6 Flash Image In Target Module

Setup the environment for genio-tool and its dependencies. This tool used to flash Ubuntu images to the LEC-MTKI1200.

Set Target boot switch to 1001,connect the USB cable from the host device to the target device and Turn on the target device,

Type the following command to flash the image on the UFS.

$ genio-flash

Now, the host device ready to find the target device as a fastboot device.

Press reset key on the target device to make it as fastboot device.

Once the targeted device is detected as a fastboot device it will automatically start to flash the Ubuntu image.

Login to the system,

  • Username: ubuntu
  • Password: ubuntu

The target module is now booted using the EVK kernel, which is the default kernel provided in the Ubuntu image. Continue with the following steps to update the kernel.

3. Modify Ubuntu Linux Kernel

3.1 Build Requirement

  • Ubuntu 20.04 host pc

3.2 Build Environment Setup

On your build host, install the following packages:

$ echo "deb-src http://archive.ubuntu.com/ubuntu jammy main" | sudo tee -a /etc/apt/sources.list.d/jammy.list
$ sudo apt-get update
$ sudo apt-get build-dep linux
$ sudo apt-get install git fakeroot libncurses-dev gcc-aarch64-linux-gnu

3.3 Get the kernel source

Clone the Source and checkout the tag :

$ git clone https://git.launchpad.net/~canonical-kernel/ubuntu/+source/linux-mtk/+git/jammy
$ cd jammy
$ git checkout Ubuntu-mtk-5.15.0-1041.49

3.4 Set Cross Compilation Environment Variables

$ export ARCH=arm64
$ export $(dpkg-architecture -aarm64)
$ export CROSS_COMPILE=aarch64-linux-gnu-

3.5 Apply Kernel Patches

Extract the ADLINK patch zip file.click here

Copy the extracted patch directory to the current working directory of the source repository.

Apply the patches using the following command:

unzip lec-mtk-1200-ubuntu-kernel-patch.zip
git am lec-mtk-1200-ubuntu-kernel-patch/*.patch
cp lec-mtk-1200-ubuntu-kernel-patch/defconfig arch/arm64/configs/

3.6 Modify the Kernel Configuration

Due to Ubuntu kernel policy restrictions, any configuration added to the defconfig file must also be declared in the Ubuntu kernel policy file.

Open the Ubuntu policy file and append the required configuration entries at the end of the file, then save the changes:

vi debian.mtk/config/annotations

CONFIG_ADLINK_SKU_PCB_INFO                      policy<{'arm64': 'y'}>
CONFIG_ARCH_ADLINKTECH                          policy<{'arm64': 'y'}>
CONFIG_DEBUG_INFO_BTF_MODULES                   policy<{'arm64': 'n'}>
CONFIG_MWIFI_PCIE_8997                          policy<{'arm64': 'n'}>
CONFIG_TCG_TIS_I2C                              policy<{'arm64': 'y'}>

3.7 Update the Kernel Policy

Run the following command to update the kernel policy:

$ fakeroot debian/rules editconfigs
Do you want to edit configs for arm64-mtk? [Y/n] n

After the command completes, the policy will be updated.
An error message such as the one below may be displayed, which is expected behavior and can be safely ignored:

make: *** [debian/rules.d/1-maintainer.mk:44: editconfigs] Error 1

3.8 Build the kernel

$ fakeroot debian/rules clean
$ fakeroot debian/rules binary

The building system will produce Debian packages in the upper-level directory. For example,

$ cd ..
$ ls -1 *.deb
linux-buildinfo-5.15.0-1041-mtk_5.15.0-1041.49_arm64.deb
linux-headers-5.15.0-1041-mtk_5.15.0-1041.49_arm64.deb
linux-image-5.15.0-1041-mtk_5.15.0-1041.49_arm64.deb
linux-modules-5.15.0-1041-mtk_5.15.0-1041.49_arm64.deb
linux-mtk-headers-5.15.0-1041_5.15.0-1041.49_all.deb

We will install the newly built kernel on the module that is currently booted with the EVK kernel.

4. Update the Kernel

Compress the output Debian packages using the following command.
Use the exact file name shown below, as the setup script depends on it.

zip lec_mtk_i1200_ufs-updates.zip *.deb

Ensure that both the script file and the compressed package are placed in the same directory.
Copy the compressed file to the target module using a USB drive or SCP, along with the setup script also click here

Connect the USB drive to the LEC-MTK-I1200 Target module and execute the following commands:

$ mkdir /home/Images
$ cp {USB_DRIVE}/lec_mtk_i1200_ufs-updates.zip /home/Images
$ cp {USB_DRIVE}/lec-mtk-ubuntu-setup.zip /home/Images

$ cd /home/Images
# unzip lec-mtk-ubuntu-setup.zip
$ sudo chmod +x lec-mtk-ubuntu-setup.sh
$ sudo ./lec-mtk-ubuntu-setup.sh

After a successful reboot, the updated Ubuntu image will boot on the LEC-MTK-I1200.