FitImage

03 03, 2026 11:14

FitImage on i.MX 8M Plus

Starting with the BSP-Yocto-NXP-i.MX8MP-PD24.1.0 release, the Kernel, Device Tree and Device Tree Overlays are now stored and loaded in a fitImage Container. This represents a significant architectural change in how PHYTEC's i.MX 8M Plus BSP handles boot images.

Image Types

When to use each

fitImage

You don't directly interact with it - it's automatically created and used during the build and boot process. Starting from PD24.1.0, your kernel and device tree are packaged this way.

WIC Image

Used for initial SD/eMMC setup and if you need precise control over partition layout. It can be flashed from U-Boot with mmc write.

host:~$xz -dc phytec-qt5demo-image-phyboard-pollux-imx8mp-2.wic.xz | sudo dd of=/dev/sdX bs=8192 conv=fsync

host:~$ sudo bmaptool copy phytec-qt5demo-image-phyboard-pollux-imx8mp-2.wic.xz /dev/sdX

For detailed information about *wic image flashing visit BSP Manual (L-1017e.A2) - Flash e.MMC from SD card.

Partup

Quick and easy eMMC flashing from Linux. Also automatic partition optimization is present and it is perfect for production programming scenarios. You can also remote flash it via ssh.

target:~$ partup install phytec-qt5demo-image-phyboard-pollux-imx8mp-2.rootfs.partup /dev/mmcblk2

host:~$ ssh root@<target-ip> "partup install phytec-qt5demo-image-phyboard-pollux-imx8mp-2.rootfs.partup /dev/mmcblk2"

You can find a detailed description at BSP Manual (L.1017e.A2) - Flash e.MMC from SD card in Linux on Target.

fitImage Build Example

To add a fitImage recipe in your BSP layer (e.g., recipes-images/fitimage/), you can reference example recipes in the meta-yogurt/meta-ampliphy layers, including phytec-simple-fitimage.bb for a fitImage with kernel and device tree, or phytec-secureboot-ramdisk-fitimage.bb for fitImage with kernel, device tree, and ramdisk with file encryption support.

To create a fitImage during the build process you need to inherit the fitImage class in your build configuration and specify variables like FITIMAGE_SLOTS.

fitImage Build Example for i.MX8MP Pollux

Hardware: phyBOARD-Pollux i.MX 8M Plus

BSP: BSP-Yocto-NXP-i.MX8MP-PD24.1.0

U-Boot: v2024-2.0.0-phy7

Linux: NXP Vendor Kernel v6.6.23-2.0.0-phy10

Yocto: 5.0.4 (Scathgap)

Hostsystem: Ubuntu 20.04 64-bit

Get the BSP

Visit the BSP Manual (L-1017e.A2) - phyLinux documentation and follow the instructions.

Create a fitImage Recipe

First, add a FIT-Image recipe in your BSP layer (e.g., recipes-images/fitimage/). You can find example recipes in the meta-yogurt layer at yocto/source/meta-yogurt/recipes-images/fitimage/, including phytec-simple-fitimage.bb for a fit-image with kernel and device tree.

Basic fitImage Recipe Structure

Create a file recipes-images/fitimage/my-fitimage.bb:

# Basic FitImage recipe for phyBOARD-Pollux i.MX8MP
SUMMARY = "FitImage recipe for phyBOARD-Pollux i.MX8MP"
LICENSE = "MIT"

# Inherit the FitImage class
inherit fitimage

# Specify the target machine
COMPATIBLE_MACHINE = "phyboard-pollux-imx8mp-2"

# Define FitImage slots (kernel and device tree)
FITIMAGE_SLOTS = "kernel fdt"

# Specify which recipes provide the artifacts
FITIMAGE_SLOT_kernel = "virtual/kernel"
FITIMAGE_SLOT_kernel[type] = "kernel"

FITIMAGE_SLOT_fdt = "virtual/kernel"
FITIMAGE_SLOT_fdt[type] = "fdt"

Build configuration

To create a fitImage during the build process you need to inherit the fitImage class in your build configuration.

Add to your conf/local.conf:

# Enable FitImage build
MACHINE = "phyboard-pollux-imx8mp-2"

# Optional: Specify FitImage variables
FITIMAGE_SLOTS = "kernel fdt"

Build fitImage

Initialize your build environment and build:

# Navigate to your BSP directory
cd ~/BSP-Yocto-NXP-i.MX8MP-PD24.1.0

# Source the environment
source sources/poky/oe-init-build-env

# Set your machine if not already set
echo 'MACHINE = "phyboard-pollux-imx8mp-2"' >> conf/local.conf

# Build your custom FitImage
bitbake my-fitimage

# Or build the default image which includes FitImage
bitbake phytec-qt5demo-image

Key Variables for fitImage Creation

Use FITIMAGE_SLOTS to list all slot classes for which the fitImage should contain images. A value of "kernel fdt", for example, will create a manifest with images for two slot classes - kernel and devicetree. For each slot class, set FITIMAGE_SLOT_<slotclass> to the image (recipe) name which builds the artifact, and FITIMAGE_SLOT_<slotclass>[type] to the type of image you intend to place in this slot.

Deployment

All images generated by Bitbake are deployed to ~/yocto/build/deploy/images/phyboard-pollux-imx8mp-2/.

Your fitImage will be available in the deployment directory along with other boot artifacts.

Create a fitImage at kernel 

You can also create a fitImage without a Yocto recipe. This shows how to create a fitImage with a standalone kernel: BSP-Yocto-NXP-i.MX8MP-PD24.1.0 - Kernel standalone build

Benefit of the fitImage

Advantage of fitImage

• Flexibility
  • Several hardware configurations can be build together 
•  Security
  • Signature for all components
• Structured metadata
  • Save metadata for all components
• Standardization
  
  • Distributions and tools such as Yocto and U-Boot rely on this format

When not to use

• The system is extremely simple  

  • a single kernel, one DTB, no overlays, no secure boot

• The bootloader or the existing boot ROM setup does not support fitImage

• The available boot flash (e.g., a small SPI‑NOR) is too limited to hold the fitImage

  • multiple FDTs, overlays, and signatures within the FIT container