On this page: |
Eric Lee
version 1.0a, 10/25/2024
This document describes how Embedian builds a customized version of NXP’s i.MX8Q Max/Plus (8QM/8QP) official Yocto Mickledore Desktop (Ubuntu 22.04) BSP release for Embedian's SMARC-iMX8QM product platform. The approach is to pull from Embedian's public facing GIT repository and build that using bitbake. The reason why we use this approach is that it allows co-development. The build output is comprised of binary images, feed packages, and an SDK for SMARC-iMX8QM specific development. Once it's done, user can use Ubuntu apt-get install
command to add additional packages.
NXP makes their i.MX series official bsp build scripts available via the following GIT repository:
|
It is this repository that actually pulls in the meta-imx/meta-bsp project to perform the Linux BSP builds for NXP's i.MX8QM Plus ARM Cortext-A72 plus Cortex-A53 chips.
We recommend you use SSH keys to establish a secure connection between your computer and Embedian Gitlab server. The steps below will walk you through generating an SSH key and then adding the public key to our Gitlab account.
First, we need to check for existing ssh keys on your computer. Open up Git Bash and run:
$ cd ~/.ssh $ ls # Lists the files in your .ssh directory |
Check the directory listing to see if you have a file named either id_rsa.pub
or id_dsa.pub
. If you don't have either of those files go to step 2. Otherwise, you already have an existing keypair, and you can skip to step 3.
To generate a new SSH key, enter the code below. We want the default settings so when asked to enter a file in which to save the key, just press enter.
$ ssh-keygen -t ed25519 -C "your_email@example.com" Generating public/private ed25519 key pair. Enter file in which to save the key (/home/eric/.ssh/id_ed25519): Enter passphrase (empty for no passphrase): Enter same passphrase again: Your identification has been saved in /home/eric/.ssh/id_ed25519 Your public key has been saved in /home/eric/.ssh/id_ed25519.pub The key fingerprint is: SHA256:SS9opo/QHxT2cCwlX+ulhn3ZUVdhdG88vvliOVHJ/6c your_email@example.com The key's randomart image is: +--[ED25519 256]--+ | . . . .+B| | = . . .o+| | = = . . o.=| | . O * o o.=o| | = S * o .o.| | . = o . . +| | . o . =.| | . + . = +| | . o .E+o| +----[SHA256]-----+ |
Copy the key to your clipboard.
$ cat ~/.ssh/id_ed25519 ssh-rsa AAAAB3NzaC1yc2EAAABDAQABAAABAQDQUEnh8uGpfxaZVU6+uE4bsDrs/tEE5/BPW7jMAxak 6qgOh6nUrQGBWS+VxMM2un3KzwvLRJSj8G4TnTK2CSmlBvR+X8ZeXNTyAdaDxULs/StVhH+QRtFEGy4o iMIzvIlTyORY89jzhIsgZzwr01nqoSeWWASd+59JWtFjVy0nwVNVtbek7NfuIGGAPaijO5Wnshr2uChB Pk8ScGjQ3z4VqNXP6CWhCXTqIk7EQl7yX2GKd6FgEFrzae+5Jf63Xm8g6abbE3ytCrMT/jYy5OOj2XSg 6jlxSFnKcONAcfMTWkTXeG/OgeGeG5kZdtqryRtOlGmOeuQe1dd3I+Zz3JyT your_email@example.c om |
Go to Embedian Git Server. At Profile Setting --> SSH Keys --> Add SSH Key
Paste your public key and press "Add Key" and your are done.
The supplied meta-embedian Yocto compliant layer has the following organization:
|
Notes on meta-embedian layer content
conf/machine/*
This folder contains the machine definitions for all Embedian's platform and backup repository in Embedian. These select the associated kernel, kernel config, u-boot, u-boot config, and tar.bz2 image settings.
recipes-bsp/u-boot/*
This folder contains recipes used to build DAS U-boot for all Embedian's platform.
recipes-bsp/imx-atf/*
This folder contains recipes used to enable console port for Embedian's i.MX8MP platform.
recipes-bsp/imx-sc-firmware/*
This folder contains system control firmware binary for Embedian's i.MX8QM platform.
recipes-bsp/alsa-state/*
This folder contains sgtl5000 sound chip default state for all Embedian's platform.
recipes-bsp/imx-mkimage/*
This folder contains imx-mkimage tool for Embedian's i.MX8MQ, i.MX8MM, i.MX8QM, i.MX8MP platform.
recipes-core/busybox/*
This folder remove telnetd from bysybox for all Embedian's platform.
recipes-core/psplash/*
This folder customized Yocto boot psplash for all Embedian's platform.
recipes-kernel/linux/*
Contains the recipes needed to build for all Embedian's platform Linux kernels.
To build the latest NXP i.MX8QM meta-bsp, you first need an Ubuntu 20.04 or 22.04 LTS installation. Since bitbake does not accept building images using root privileges, please do not login as a root user when performing the instructions in this section.
Once you have Ubuntu 20.04 or 22.04 LTS running, install the additional required support packages using the following console command:
|
|
To get the BSP you need to have 'repo' installed and use it as:
Install the 'repo' utility:
|
$
|
|
Choose "y" to accept EULA.
This script will create and bring you to ~/mickledore_desktop/build-desktop directory.
|
|
Once it done, you can find all required images under ~/<build directory>/tmp/deploy/images/<machine name>/
You may want to build programs that aren’t installed into a root file system so you can make them available via a feed site (described below.) To do this you can build the package directly and then build the package named package-index to add the new package to the feed site.
Once the build(s) are completed you’ll find the resulting images, rpm and licenses in folder ~/mickledore_desktop/
<build directory>/tmp/deploy
.
deploy/images/<machine name>/*
This folder contains the binary images for the root file system and the Embedian SMARC-iMX8QM specific version of the boot file, Image and device tree file. Specifically the images are:
deploy/images/
<machine name>/imx-boot-<machine name>-sd.bin-flash_evk
This is boot file binary for SMARC-iMX8QM
deploy/images/<machine name>/Image
The kernel Image for SMARC-iMX8QM.
deploy/images/<machine name>/<device tee file>
Selecting display configuration is a matter of selecting an appropriate DTB file under deploy/images/<machine name>/<device tee file>
All available DTB files are listed in the table below.
DTB File Name | Description |
---|---|
imx8qm-smarc.dtb | Device tree blob for no display configuration. |
imx8qm-smarc-hdmi.dtb | Device tree blob for HDMI display configuration. |
imx8qm-smarc-dp.dtb | Device tree blob for Display Port (DP) display configuration. |
imx8qm-smarc-edp.dtb | Device tree blob for embedded Display Port (eDP) display configuration. |
imx8qm-smarc-lvds.dtb | Device tree blob for LVDS display configuration. |
imx8qm-smarc-rpmsg.dtb | Device tree blob for Cortex-M4 configuration. |
deploy/images/<machine name>/imx-image-desktop-<machine name>.*
Embedian Ubuntu 22.04 root file system images for software development on Embedian’s SMARC-iMX8QM platforms.
deploy/rpm/*
This folder contains all the packages used to construct the root file system images. They are in rpm format and can be dynamically installed on the target platform via apt-get install command on the device.
deploy/licenses/*
For these instruction, we are assuming: DISK=/dev/mmcblk0, "lsblk" is very useful for determining the device id.
$ export DISK=/dev/mmcblk0 |
Erase SD card:
$ |
Create Partition Layout: Leave 1MB offset for boot file.
With util-linux v2.26, sfdisk was rewritten and is now based on libfdisk.
$ sudo sfdisk --version sfdisk from util-linux 2.34 |
Create Partitions:
|
Format Partitions:
for : DISK=/dev/mmcblk0 $ sudo mkfs.vfat -F 16 ${DISK}p1 -n boot $ sudo mkfs.ext4 ${DISK}p2 -L rootfs for : DISK=/dev/sdX $ sudo mkfs.vfat -F 16 ${DISK} 1 -n boot $ sudo mkfs.ext4 ${DISK} 2 -L rootfs |
Mount Partitions:
On some systems, these partitions may be auto-mounted...
$ sudo mkdir -p /media/boot/ $ sudo mkdir -p /media/rootfs/ for : DISK=/dev/mmcblk0 $ sudo mount ${DISK}p1 /media/boot/ $ sudo mount ${DISK}p2 /media/rootfs/ for : DISK=/dev/sdX $ sudo mount ${DISK} 1 /media/boot/ $ sudo mount ${DISK} 2 /media/rootfs/ |
imx-boot-<machine name>-sd.bin-flash_linux_m4
or imx-boot-<machine name>-sd.bin-flash_spl
)Boot file is factory default flashed at on-module eMMC flash.
If on-module eMMC Flash is empty
In some cases, when eMMC flash is erased or the u-boot is under development, we need a way to boot from SD card first. Users need to shunt cross the TEST# pin to ground. In this way, SMARC-iMX8QM will always boot up from SD card.
Fuse flash.bin to the SD card.
$ sudo dd if=<boot file> of=${DISK} bs=1024 seek=32 |
If on-module eMMC Flash is not empty
The <boot file> is pre-installed in on-module eMMC flash at factory default. SMARC-iMX8QM is designed to always boot up from on-module eMMC flash and to load Image, device tree blob and root file systems based on the setting of BOOT_SEL. If users need to fuse your own flash.bin or perform u-boot upgrade. This section will instruct you how to do that.
Copy <boot file> to the second partition home directory of your SD card and boot into SD card. Go to home directory and you should see flash.bin file.
$ sudo cp -v <boot file> /media/rootfs/home/root/ |
Fuse <boot file> to the on-module eMMC flash. (The eMMC flash is emulated as /dev/mmcblk0
in SMARC-iMX8QM)
|
|
Create "uEnv.txt" boot script: ($ vim uEnv.txt)
|
Copy uEnv.txt to the boot partition:
$ sudo cp -v ~/uEnv.txt /media/boot/ |
Copy Image to the boot partition:
$ sudo cp -v Image /media/boot |
$ sudo cp -v <device tree file> /media/boot/dtbs/imx8qm-smarc.dtb |
All available DTB files are listed in the table below.
DTB File Name | Description |
---|---|
imx8qm-smarc.dtb | Device tree blob for no display configuration. |
imx8qm-smarc-hdmi.dtb | Device tree blob for HDMI display configuration. |
imx8qm-smarc-dp.dtb | Device tree blob for Display Port (DP) display configuration. |
imx8qm-smarc-edp.dtb | Device tree blob for embedded Display Port (eDP) display configuration. |
imx8qm-smarc-lvds.dtb | Device tree blob for LVDS display configuration. |
imx8qm-smarc-rpmsg.dtb | Device tree blob for Cortex-M4 configuration. |
The device tree name in your SD card has be to |
Yocto Built Rootfs:
$ sudo tar jxvf <filename.tar.bz2> -C /media/rootfs |
|
Remove SD card:
$ sync $ sudo umount /media/boot $ sudo umount /media/rootfs |
This section tells you how to set up an SD card automatically. It mainly uses a script to do all the steps in the above section.
|
Shunt cross TEST# pin to ground and set the BOOT_SEL to ON OFF OFF. The module will boot up from SD card.
In order to package your application and include it in the root filesystem image, you must write a BitBake recipe for it.
When starting from scratch, it is easiest to learn by example from existing recipes.
For software that uses autotools (./configure; make; make install), writing recipes can be very simple:
DESCRIPTION = "Hello World Recipe using autotools" HOMEPAGE = "http://www.embedian.com/" SECTION = "console/utils" PRIORITY = "optional" LICENSE = "GPL" PR = "r0" S = "${WORKDIR}/git" inherit autotools |
SRC_URI
specifies the location to download the source from. It can take the form of any standard URL using http://, ftp://, etc. It can also fetch from SCM systems, such as git in the example above.
PR
is the package revision variable. Any time a recipe is updated that should require the package to be rebuilt, this variable should be incremented.
inherit autotools
brings in support for the package to be built using autotools, and thus no other instructions on how to compile and install the software are needed unless something needs to be customized.
S
is the source directory variable. This specifies where the source code will exist after it is fetched from SRC_URI and unpacked. The default value is ${WORKDIR}/${PN}-${PV}
, where PN
is the package name and PV
is the package version. Both PN
and PV
are set by default using the filename of the recipe, where the filename has the format PN_PV.bb
.
This example shows a simple case of building a helloworld.c file directly using the default compiler (gcc). Since it isn’t using autotools or make, we have to tell BitBake how to build it explicitly.
DESCRIPTION = "HelloWorld" SECTION = "examples" LICENSE = "GPL" SRC_URI = "file://helloworld.c" S = "${WORKDIR}" do_compile() { ${CC} ${CFLAGS} ${LDFLAGS} helloworld.c -o helloworld } do_install() { install -d ${D}${bindir} install -m 0755 helloworld ${D}${bindir} } |
In this case, SRC_URI
specifies a file that must exist locally with the recipe. Since there is no code to download and unpack, we set S
to WORKDIR
since that is where helloworld.c will be copied to before it is built.
WORKDIR
is located at ${OETREE}/<build directory>/tmp/work/armv8a-fsl-linux/<package name and version>
for most packages. If the package is machine-specific (rather than generic for the armv8a architecture), it may be located in the smarcimx8qm4g-fsl-linux subdirectory depending on your hardware (this applies to kernel packages, images, etc).
do_compile
defines how to compile the source. In this case, we just call gcc directly. If it isn’t defined, do_compile
runs make
in the source directory by default.
do_install
defines how to install the application. This example runs install
to create a bin directory where the application will be copied to and then copies the application there with permissions set to 755.
D
is the destination directory where the application is installed to before it is packaged.
${bindir}
is the directory where most binary applications are installed, typically /usr/bin
.
For a more in-depth explanation of BitBake recipes, syntax, and variables, see the Recipe Chapter of the OpenEmbedded User Manual.
Setting up eMMC usually is the last step at development stage after the development work is done at your SD card or NFS environments. From software point of view, eMMC is nothing but a non-removable SD card on board. For SMARC-iMX8QM, the SD card is always emulated as /dev/mmcblk1 and on-module eMMC is always emulated as /dev/mmcblk0. Setting up eMMC now is nothing but changing the device descriptor.
This section gives a step-by-step procedure to setup eMMC flash. Users can write a shell script your own at production to simplify the steps.
First, we need to backup the final firmware from your SD card or NFS.
Insert SD card into your Linux PC. For these instructions, we are assuming: DISK=/dev/mmcblk0, "lsblk" is very useful for determining the device id.
For these instruction, we are assuming: DISK=/dev/mmcblk0, "lsblk" is very useful for determining the device id.
$ export DISK=/dev/mmcblk0 |
Mount Partitions:
On some systems, these partitions may be auto-mounted...
$ sudo mkdir -p /media/boot/ $ sudo mkdir -p /media/rootfs/ for : DISK=/dev/mmcblk0 $ sudo mount ${DISK}p1 /media/boot/ $ sudo mount ${DISK}p2 /media/rootfs/ for : DISK=/dev/sdX $ sudo mount ${DISK} 1 /media/boot/ $ sudo mount ${DISK} 2 /media/rootfs/ |
Copy Image to rootfs partition:
$ sudo cp -v Image /media/rootfs/home/root |
Copy uEnv.txt to rootfs partition:
Copy and paste the following contents to /media/rootfs/home/root ($ sudo vim /media/rootfs/home/root/uEnv.txt)
|
Copy device tree blob to rootfs partition:
|
Copy boot file to rootfs partition:
|
Copy real rootfs to rootfs partition:
|
Remove SD card:
$ sync $ sudo umount /media/boot $ sudo umount /media/rootfs |
Insert this SD card into your SMARC-iMX8QM device.
Now it will be almost the same as you did when setup your SD card, but the eMMC device descriptor is /dev/mmcblk0 now. Booting up the device.
$ export DISK=/dev/mmcblk0 |
Erase eMMC:
$ |
Create Partition Layout:
$ sudo sfdisk ${DISK} <<-__EOF__
50M,,, __EOF__ |
Format Partitions:
$ sudo mkfs.vfat -F 16 ${DISK}p1 -n boot $ sudo mkfs.ext4 ${DISK}p2 -L rootfs |
Mount Partitions:
$ sudo mkdir -p /media/boot/ $ sudo mkdir -p /media/rootfs/ $ sudo mount ${DISK}p1 /media/boot/ $ sudo mount ${DISK}p2 /media/rootfs/ |
Copy uEnv.txt/Image/*.dtb to the boot partition
$ sudo cp -v Image uEnv.txt /media/boot/ |
$ sudo mkdir -p /media/boot/dtbs $ sudo cp -v imx8qm-smarc.dtb /media/boot/dtbs/ |
$ sudo tar -zxvf smarcimx8qm-emmc-rootfs.tar.gz -C /media/rootfs |
Unmount eMMC:
$ sync $ sudo umount /media/boot $ sudo umount /media/rootfs |
Flash boot file
$ sudo dd if=flash.bin of=${DISK} bs=1024 seek=32 |
Switch your Boot Select to eMMC (OFF ON ON) and you will be able to boot up from eMMC now.
Boot up the module from SD card and run the following script. The Yocto images will be written into on-module eMMC.
|
Shutdown the device. Set TEST# pin floating and set the BOOT_SEL to OFF ON ON. The module will boot up from on-module eMMC.
The default Yocto desktop (ubuntu 22.04) build will create the account "user" with the password "user" for desktop evaluation, In order to change the account or password, uncomment and update APTGET_ADD_USERS in <build_dir>/conf/local.conf.
version 1.0a, 10/25/2024
Last updated 2025-10-24