Debian Build Release Stage
This page is using the default release mx8m-debian-bullseye-5.4-2.1.x-v1.4.
To view this page for a specific Variscite SoM and software release, please follow these steps:
- Visit variwiki.com
- Select your SoM
- Select the software release
Overview
This page describes how to build and install Debian Bullseye on Variscite boards with DART-MX8M.
Please note that the build script is based on debootstrap. As described in the following instructions, it's kindly suggested to create the build folder on the main Ubuntu volume on your host PC rather than an external media.
Using an external media, although automatically mounted, will cause debootstrap to complain about access rights (even when running the script with sudo).
Setup Development Environment
Please refer to the page Debian Development Environment to learn how to set up a suitable development environment.
Installing required packages
Please make sure your host PC, running a suitable Ubuntu, is up to date:
$ sudo apt-get update && sudo apt-get dist-upgrade
Then, install the following packages:
$ sudo apt-get install binfmt-support qemu qemu-user-static debootstrap kpartx \ lvm2 dosfstools gpart binutils bison git lib32ncurses5-dev libssl-dev python-m2crypto gawk wget \ git-core diffstat unzip texinfo gcc-multilib build-essential chrpath socat libsdl1.2-dev \ autoconf libtool libglib2.0-dev libarchive-dev python-git xterm sed cvs subversion \ kmod coreutils texi2html bc docbook-utils python-pysqlite2 help2man make gcc g++ \ desktop-file-utils libgl1-mesa-dev libglu1-mesa-dev mercurial automake groff curl \ lzop asciidoc u-boot-tools mtd-utils device-tree-compiler flex cmake
While installing the packages, using Ubuntu 20.04, users may receive the warning
Package python-git is not available, ...
Since the package is only available in up to Ubuntu 18.04, just ignore it and run:
$ sudo apt-get install python3-git python3-m2crypto
Note: If you are using Ubuntu 20.04 the QEMU package must be updated to latest version (>= 1:4.2-3ubuntu6.19).
To check the currently installed version of the qemu-user-static package on Ubuntu 20.04 LTS, use the below command:
$ apt list qemu-user-static
Reference documentation
Documentation is available from https://www.debian.org/doc/
Download Debian build script
As of March 31, 2023, all codeaurora.org repositories have been migrated to other platforms, and the project has been shut down.
For more information, please visit: https://bye.codeaurora.org/
In this context, errors may occur when deploying the Debian sources, such as:
fatal: unable to look up source.codeaurora.org (port 9418) (No address associated with hostname)
Variscite has updated all relevant software repositories. Please refer to the patch(es):
Download archive containing the build script and support files for building Debian Bullseye for this board.
$ mkdir ~/debian_imx8mq-var-dart_debian_bullseye $ cd ~/debian_imx8mq-var-dart_debian_bullseye
Now, choose between downloading a release tag, and downloading the latest revision (recommended) and follow only one of the next two bullet sections, accordingly:
- Download the latest revision:
$ git clone https://github.com/varigit/debian-var.git -b debian_bullseye_var01
or
- Download a release tag:
Each release in https://github.com/varigit/debian-var/releases corresponds to a tag.
One can find a list of all available tags in https://github.com/varigit/debian-var/tags.
To target a specific release/tag, run the following:
$ git clone https://github.com/varigit/debian-var.git -b refs/tags/<TAG_NAME> For example: $ git clone https://github.com/varigit/debian-var.git -b refs/tags/mx8m-debian-bullseye-5.4-2.1.x-v1.4
Setup and build Debian
Distro features
The build script supports the configuration of some distro featues (pre-defined package groups), such like:
| Feature | build script variable |
|---|---|
| Full graphics and GPU SDK | G_DEBIAN_DISTRO_FEATURE_GRAPHICS |
| Multimedia | G_DEBIAN_DISTRO_FEATURE_MM |
| Machine learning | G_DEBIAN_DISTRO_FEATURE_ML |
Each feature can be controlled by its associated configuration variable, which can be found in the machine-specific file ~/debian_imx8mq-var-dart_debian_bullseye/variscite/imx8m-var-dart/imx8m-var-dart.sh.
By default, all features are enabled.
Deploy sources
Download all necessary resources required for the Debian build using the script command -c deploy.
$ cd ~/debian_imx8mq-var-dart_debian_bullseye $ MACHINE=imx8mq-var-dart ./var_make_debian.sh -c deploy
This will download the toolchain, bootloader, kernel, firmware blobs, and so on, to the folder ~/debian_imx8mq-var-dart_debian_bullseye/src and in case of the toolchain to ~/debian_imx8mq-var-dart_debian_bullseye/toolchain.
If you want to re-deploy the source(s), delete the entire folder ~/debian_imx8mq-var-dart_debian_bullseye/src or just delete the desired subfolder, and reinvoke the deploy command.
Build all
$ cd ~/debian_imx8mq-var-dart_debian_bullseye $ sudo MACHINE=imx8mq-var-dart ./var_make_debian.sh -c all |& tee build.log
Build by parts
Build bootloader
$ cd ~/debian_imx8mq-var-dart_debian_bullseye $ sudo MACHINE=imx8mq-var-dart ./var_make_debian.sh -c bootloader
Build kernel, dtb files and kernel modules
$ cd ~/debian_imx8mq-var-dart_debian_bullseye $ sudo MACHINE=imx8mq-var-dart ./var_make_debian.sh -c kernel $ sudo MACHINE=imx8mq-var-dart ./var_make_debian.sh -c kernelheaders $ sudo MACHINE=imx8mq-var-dart ./var_make_debian.sh -c modules
-c kernel) also includes the build of the device tree blobs.Build freertos-variscite
$ cd ~/debian_imx8mq-var-dart_debian_bullseye $ sudo MACHINE=imx8mq-var-dart ./var_make_debian.sh -c freertosvariscite
Please refer to MCUXpresso Developers Guide to learn more about the MCUXpresso SDK for the Cortex-M, and how to use it.
Build rootfs
$ cd ~/debian_imx8mq-var-dart_debian_bullseye $ sudo MACHINE=imx8mq-var-dart ./var_make_debian.sh -c rootfs
To create the root file system archive (rootfs.tar.gz), run the following commands:
$ sudo MACHINE=imx8mq-var-dart ./var_make_debian.sh -c rtar
Build Results
The resulted images are located in ~/debian_imx8mq-var-dart_debian_bullseye/output/.
| Image name |
How to use |
|---|---|
| rootfs.tar.gz | Root filesystem tarball used for installation on SD card and eMMC |
| Image.gz | Linux kernel image |
| imx-boot-sd.bin | U-Boot built for SD card and eMMC |
| imx-boot-sd-dp.bin | U-Boot built for SD card and eMMC with DP firmware |
| kernel-headers | kernel headers folder for package creation |
| Device Tree name |
Details |
| imx8mq-var-dart-dt8mcustomboard-sd-hdmi.dtb | DTB for DART-MX8M on DT8MCustomBoard V2.x with SD card and HDMI display. |
| imx8mq-var-dart-dt8mcustomboard-sd-lvds.dtb | DTB for DART-MX8M on DT8MCustomBoard V2.x with SD card and LVDS display. |
| imx8mq-var-dart-dt8mcustomboard-sd-lvds-hdmi.dtb | DTB for DART-MX8M on DT8MCustomBoard V2.x with SD card and dual LVDS+HDMI display. |
| imx8mq-var-dart-dt8mcustomboard-wifi-hdmi.dtb | DTB for DART-MX8M on DT8MCustomBoard V2.x with WIFI and HDMI display. |
| imx8mq-var-dart-dt8mcustomboard-wifi-lvds.dtb | DTB for DART-MX8M on DT8MCustomBoard V2.x with WIFI and LVDS display. |
| imx8mq-var-dart-dt8mcustomboard-wifi-lvds-hdmi.dtb | DTB for DART-MX8M on DT8MCustomBoard V2.x with WIFI and dual LVDS+HDMI display. |
| imx8mq-var-dart-dt8mcustomboard-m4-sd-hdmi.dtb | DTB for DART-MX8M on DT8MCustomBoard V2.x with M4, SD card and HDMI display. |
| imx8mq-var-dart-dt8mcustomboard-m4-sd-lvds.dtb | DTB for DART-MX8M on DT8MCustomBoard V2.x with M4, SD card and LVDS display. |
| imx8mq-var-dart-dt8mcustomboard-m4-sd-lvds-hdmi.dtb | DTB for DART-MX8M on DT8MCustomBoard V2.x with M4, SD card and dual LVDS+HDMI display. |
| imx8mq-var-dart-dt8mcustomboard-m4-wifi-hdmi.dtb | DTB for DART-MX8M on DT8MCustomBoard V2.x with M4, WIFI and HDMI display. |
| imx8mq-var-dart-dt8mcustomboard-m4-wifi-lvds.dtb | DTB for DART-MX8M on DT8MCustomBoard V2.x with M4, WIFI and LVDS display. |
| imx8mq-var-dart-dt8mcustomboard-m4-wifi-lvds-hdmi.dtb | DTB for DART-MX8M on DT8MCustomBoard V2.x with M4, WIFI and dual LVDS+HDMI display. |
| imx8mq-var-dart-dt8mcustomboard-sd-dp.dtb | DTB for DART-MX8M on DT8MCustomBoard V1.3/V1.4 with SD card and DP display. |
| imx8mq-var-dart-dt8mcustomboard-sd-hdmi.dtb | DTB for DART-MX8M on DT8MCustomBoard V1.3/V1.4 with SD card and HDMI display. |
| imx8mq-var-dart-dt8mcustomboard-sd-lvds.dtb | DTB for DART-MX8M on DT8MCustomBoard V1.3/V1.4 with SD card and LVDS display. |
| imx8mq-var-dart-dt8mcustomboard-sd-lvds-dp.dtb | DTB for DART-MX8M on DT8MCustomBoard V1.3/V1.4 with SD card and dual LVDS+DP display. |
| imx8mq-var-dart-dt8mcustomboard-sd-lvds-hdmi.dtb | DTB for DART-MX8M on DT8MCustomBoard V1.3/V1.4 with SD card and dual LVDS+HDMI display. |
| imx8mq-var-dart-dt8mcustomboard-wifi-dp.dtb | DTB for DART-MX8M on DT8MCustomBoard V1.3/V1.4 with WIFI and DP display. |
| imx8mq-var-dart-dt8mcustomboard-wifi-hdmi.dtb | DTB for DART-MX8M on DT8MCustomBoard V1.3/V1.4 with WIFI and HDMI display. |
| imx8mq-var-dart-dt8mcustomboard-wifi-lvds.dtb | DTB for DART-MX8M on DT8MCustomBoard V1.3/V1.4 with WIFI and LVDS display. |
| imx8mq-var-dart-dt8mcustomboard-wifi-lvds-dp.dtb | DTB for DART-MX8M on DT8MCustomBoard V1.3/V1.4 with WIFI and dual LVDS+DP display. |
| imx8mq-var-dart-dt8mcustomboard-wifi-lvds-hdmi.dtb | DTB for DART-MX8M on DT8MCustomBoard V1.3/V1.4 with WIFI and dual LVDS+HDMI display. |
| imx8mq-var-dart-dt8mcustomboard-m4-sd-dp.dtb | DTB for DART-MX8M on DT8MCustomBoard V1.3/V1.4 with M4, SD card and DP display. |
| imx8mq-var-dart-dt8mcustomboard-m4-sd-hdmi.dtb | DTB for DART-MX8M on DT8MCustomBoard V1.3/V1.4 with M4, SD card and HDMI display. |
| imx8mq-var-dart-dt8mcustomboard-m4-sd-lvds.dtb | DTB for DART-MX8M on DT8MCustomBoard V1.3/V1.4 with M4, SD card and LVDS display. |
| imx8mq-var-dart-dt8mcustomboard-m4-sd-lvds-dp.dtb | DTB for DART-MX8M on DT8MCustomBoard V1.3/V1.4 with M4, SD card and dual LVDS+DP display. |
| imx8mq-var-dart-dt8mcustomboard-m4-sd-lvds-hdmi.dtb | DTB for DART-MX8M on DT8MCustomBoard V1.3/V1.4 with M4, SD card and dual LVDS+HDMI display. |
| imx8mq-var-dart-dt8mcustomboard-m4-wifi-dp.dtb | DTB for DART-MX8M on DT8MCustomBoard V1.3/V1.4 with M4, WIFI and DP display. |
| imx8mq-var-dart-dt8mcustomboard-m4-wifi-hdmi.dtb | DTB for DART-MX8M on DT8MCustomBoard V1.3/V1.4 with M4, WIFI and HDMI display. |
| imx8mq-var-dart-dt8mcustomboard-m4-wifi-lvds.dtb | DTB for DART-MX8M on DT8MCustomBoard V1.3/V1.4 with M4, WIFI and LVDS display. |
| imx8mq-var-dart-dt8mcustomboard-m4-wifi-lvds-dp.dtb | DTB for DART-MX8M on DT8MCustomBoard V1.3/V1.4 with M4, WIFI and dual LVDS+DP display. |
| imx8mq-var-dart-dt8mcustomboard-m4-wifi-lvds-hdmi.dtb | DTB for DART-MX8M on DT8MCustomBoard V1.3/V1.4 with M4, WIFI and dual LVDS+HDMI display. |
Create a bootable SD card
SD card structure
This is the structure of our Recovery/Extended SD card:
The SD card is divided into 2 sections, as shown in the picture above:
- The first unallocated 8MiB section is reserved for U-Boot. It can be replaced using the dd command as described in the Yocto Build U-Boot section.
- The first partition is an ext4 partition that contains the complete root filesystem (including kernel image and device tree files under /boot).
The last unallocated area is not used. It is there so that the rootfs will fit on any 4GB SD card, as not all 4GB SD cards are really the same size. If you want, you can use a program such as GParted to resize the roofs partition and make it end at the end of your specific SD card (of course, you can also use SD cards with much bigger capacity than 4GB, and then it makes more sense to resize the partition).
Create a Debian bootable SD card
- Follow the above steps for make rootfs, kernel, bootloader;
- Insert the SD card to card reader connected to a host system;
- Run the following commands:
$ cd ~/debian_imx8mq-var-dart_debian_bullseye $ sudo MACHINE=imx8mq-var-dart ./var_make_debian.sh -c sdcard -d /dev/sdX
where '/dev/sdX' path to the block SD device in your system.
Create a Debian bootable SD card image using a loop device
It is also possible to use the "MACHINE=imx8mq-var-dart ./var_make_debian.sh" script to create a boot SD card image while using a loop device instead of attaching a real physical SD card.
Create an empty file using the following command:
$ dd if=/dev/zero of=imx8m-var-dart-debian-sd.img bs=1M count=3720
The above command creates a 3720MiB file representing the SD card.
Attach the first available loop device to this file:
$ sudo losetup -Pf imx8m-var-dart-debian-sd.img
To find the actual loop device being used, run:
$ losetup -a | grep imx8m-var-dart-debian-sd.img
Write the content to the loop device to generate the SD card image:
$ sudo MACHINE=imx8mq-var-dart ./var_make_debian.sh -c sdcard -d /dev/loopX
(Replace /dev/loopX with your actual loop device, e.g. /dev/loop0)
Detach the loop device from the file:
$ sudo losetup -d /dev/loopX
To compress the SD card image file use the following command:
$ gzip -9 imx8m-var-dart-debian-sd.img
This will create a gz archive imx8m-var-dart-debian-sd.img.gz of the SD card image.
Clone a Debian bootable SD card image
To write the SD card image to a real SD card device, use the following command:
$ zcat imx8m-var-dart-debian-sd.img.gz | sudo dd of=/dev/sdX bs=1M && sync
where '/dev/sdX' path to the block SD device in your system.
Please refer also to Debian Recovery SD Card - Write the image to an SD Card.
Boot the board with a bootable SD card
Note: The WiFi is not operational when booting from SD card, as the WiFi and SD card are using the same SDIO interface.
A typical use-case is to boot from an SD card, flash the eMMC, and re-boot from the eMMC to have the WiFi operational.
Setting the Boot Mode
Make sure the BOOT SELECT DIP switch on the carrier board is set correctly before you power on the board.
SW7 0 : Boot from SD card 1 : Boot from eMMC
Automatic device tree selection in U-Boot
As shown in the Build Results table above, we have different kernel device trees, corresponding to our different H/W configurations (sometimes they are renamed without the "zImage-" prefix).
We implemented a script in U-Boot's environment, which sets the fdt_file environment variable based on the detected hardware.
Enable/Disable Automatic Device Tree selection
To enable the automatic device tree selection in U-Boot (already enabled by default):
$ setenv fdt_file undefined $ saveenv
To disable the automatic device tree selection in U-Boot, set the device tree file manually:
$ setenv fdt_file YOUR_DTB_FILE $ saveenv
Linux console access
| User name | User password | User descriptor |
|---|---|---|
| root | root | system administrator |
| user | user | local user |
| x_user | used for X session access |
Please note: Vivante libraies for this release do not support X11, only weston backend is provided
Flash images to eMMC
To install Debian to the on-SOM eMMC, run the following command as root:
# install_debian.sh -d <lvds|hdmi|dp|dual-display>
where the "-d" option set display type, default is lvds. The above script is located in /usr/sbin in the rootfs of the SD card used to boot Debian.