Build and Install Debian 12 Bookworm

---

The Embedian Debian Linux SDK combines community‑supported Debian software with NXP‑specific components to deliver a convenient development solution on ARM64 platforms. Using Flexbuild, developers can generate BSP firmware (ATF, U‑Boot, OP‑TEE, kernel, DTB, peripheral firmware, initramfs), as well as Debian desktop and server RootFS images. Hardware‑accelerated modules for GPU, NPU, VPU, ISP, security, Wi‑Fi/Bluetooth, and audio are compiled against Debian runtime dependencies.

Flexbuild enables flexible builds of RootFS, kernel, BSP, and user applications across graphics, multimedia, networking, connectivity, security, and AI/ML use cases, supporting streamlined customization and CI/CD. With flex‑installer, distributions can be easily deployed to SD/eMMC or USB/SATA/NVMe storage. Embedian provides both source packages and prebuilt demo images to simplify evaluation and development.

Development Board

EVK-STD-CARRIER-S20 (universal carrier board for all SMARC 2.0 modules) from Embedian

Release Note

The Debian Linux SDK 25.06 release has the following new features:

• Flexbuild upgraded to 2.18.2506.
• Debian 12.9 (base, desktop, server) RootFS with update.
• Linux kernel upgraded to LTS 6.6.52.
• GPU driver upgraded to imx-gpu-viv-6.4.11.p2.10-aarch64 (compiled based on Debian 12 runtime dependency).
• VPU driver upgraded to imx-vpu-hantro-vc-1.10.1 (based on Debian 12).
• Supports eIQ AI/ML and GoPoint Demos.
• DPDK L2FWD and L3FWD applications.
• GStreamer 1.24.7 and various plugins for i.MX.

• Debian 12.9 Desktop by default, Weston Desktop supported alternatively
• Desktop GUI with GPU acceleration
• Multimedia video playback with VPU codec
• Web browsers (Chromium, Firefox)
• Qt6 application support
• Wi-Fi + Bluetooth
• eIQ TensorFlow Lite support
• Gstreamer support
• DPDK for networking acceleration
• GoPoint Demos support in both GUI and TUI mode

---

Building Debian Images with Flexbuild

---

Flexbuild is a component-oriented lightweight build system and integration platform with capabilities of flexible, ease-to-use, scalable system building, and Distro deployment, developed by NXP.

Flexbuild provides a set of scripts, tools, and make files to compile NXP board-specific driver components, create board-specific BSP composite firmware, boot image, and custom Debian (base, desktop, server) RootFS image. It provides an easy way to create a full-fledged Debian Distro with hardware-accelerated components for NXP platforms, using a single command. Once the image is built, users can directly deploy it onto an SD card.

Host prerequisites to build the Debian Distro:

Debian 12, Ubuntu 22.04, or Ubuntu 24.04 with Docker installed.

Perform the following steps to install the Docker:

---

---

Users must have the sudo permission for Docker commands or be added to the Docker group as follows.
Change the current group to ”docker”, and add the account to it and restart the Docker service.

---

---

Run the following command to clone the repository:

---

---

The following is the source tree of the Flexbuild repository structure.

├── LICENSE-Flexbuild-BSD-3-CLAUSE.txt
├── LICENSE_SDK.txt
├── README.md
├── SCR.txt
├── build_lsdk2506
│   ├── apps
│   ├── bsp
│   ├── images
│   ├── linux
│   └── rfs
├── components_lsdk2506
│   ├── apps
│   └── linux
├── configs
│   ├── board
│   ├── buildroot
│   ├── debian
│   ├── linux
│   ├── ml.yml
│   ├── poky
│   ├── sdk-emb.yml
│   └── sdk.yml
├── docker
│   ├── debian
│   └── ubuntu
├── docs
│   ├── FAQ-add-new-package-and-board.md
│   ├── FAQ-docker-setup.md
│   ├── build_and_deploy_distro.md
│   ├── flexbuild_usage.md
│   ├── flexbuild_workflow.txt
│   ├── host_requirement.md
│   ├── memory_layout.txt
│   ├── nxp_linux_sdk.md
│   └── proxy.md
├── include
│   ├── repo.mk
│   └── repo_update.inc
├── logs
├── patch
│   ├── apitrace
│   ├── atf
│   ├── cheese
│   ├── clutter_gst
│   ├── cogl
│   ├── cryptodev_linux
│   ├── gst_plugins_bad
│   ├── gst_plugins_base
│   ├── gst_plugins_good
│   ├── gstreamer
│   ├── gtec_demo_framework
│   ├── imx_demo_experience
│   ├── imx_demos_list
│   ├── imx_firmware
│   ├── imx_gst_plugin
│   ├── imx_mkimage
│   ├── imx_smart_kitchen
│   ├── imx_voiceplayer
│   ├── linux
│   ├── nnstreamer
│   ├── openssl
│   ├── optee_os
│   ├── uboot
│   ├── vkmark
│   ├── vpp
│   ├── wayland
│   └── weston
├── setup.env
├── src
│   ├── Makefile
│   ├── apps
│   ├── bsp
│   ├── linux
│   └── system
└── tools
├── bld -> flex-builder
├── chroot.sh
├── clean_components
├── create_bootpartition
├── create_composite_firmware
├── distro_buildroot
├── distro_debian
├── distro_poky
├── flash_images
├── flex-builder
├── flex-installer
├── getvariable
├── make_emmc
├── parse_yaml
├── repo_update
├── resizerfs
└── secure_sign_image

Building Debian images in Flexbuild

---

 Run the following commands for the first time to set up the build environment.

---

---

Flexbuild usage:

---

---

---

Automatically build BSP composite firmware + kernel + iMX-specific driver
components + Debian RootFS

---

---

Most used example with separate build:

Setup SD Card

---

When the building is successfully completed, the generated image is located in the directory
build_lsdk2506/images/.

Use the following command to flash the SD card.

---

---

---

flex-installer command options

---

When all development work is completed, you can use the following command to back up the software from each partition to the third partition of the SD card. This backup will be used later when flashing the on-module eMMC.

---

---

Remove SD card from host computer and insert into your device SD connector. Shunt cross TEST# pin to GND (SD boot) and set BOOT_SET to ON OFF OFF. You can see Debian bookworm desktop boot up from SER3.

---

Setup eMMC

---

Shunt the cross TEST# pin to ground and set BOOT_SEL to ON OFF OFF, then boot from your SD card. Run the following command as the root user.”

---

---

---

Shutting down device. Remove TEST# pin jumper block and set BOOT_SEL to OFF ON ON. The device now boot up from on-module eMMC.

---

FAQs

---

Note: You must have successfully compiled a complete machine previously. Otherwise, the source directories do not exist. This means that you should have run a command similar to: $ bld -m imx8mq-smarc-4g.

• Kernel and kernel modules related source code is located in: <flexbuild dir>/components_lsdk2506/linux/.
• BSP (including U-Boot, ATF, RCW, etc.) related code is located in: <flexbuild dir>/components_lsdk2506/bsp.
• Applications related code is categorized into graphics, multimedia, machine learning, and other relevant categories, and is stored in their respective subdirectories within: <flexbuild dir>/components_lsdk2506/apps/.

---

• To modify the Linux or Device Tree Blob (DTB):
  1. Navigate to the Linux source directory:
     $ cd components_lsdk2506/linux/
  2. Update your source code or DTB files.
  3. Go back to the previous directory:
     $ cd –
  4. Compile the Linux kernel (using the i.MX platform as an example):
     $ LOG_LEVEL=0 bld linux -p IMX
  5. The compiled output is in the build_lsdk2506/linux/linux/arm64/IMX directory. Copy the necessary image or DTB files to your target board for use.
     Note: To use the flex-installer tool to flash the newly generated kernel image or DTB, run the following command to generate the boot image boot_IMX_arm64_lts_6.6.52.tar.zst:
     $ LOG_LEVEL=0 bld boot -p IMX

• To modify the U-Boot or ATF Code:
  1. Navigate to the U-Boot or ATF source directory:
     $ cd components_lsdk2506/bsp/uboot/ or components_lsdk2506/bsp/atf/
  2. Update the source code.
  3. Compile U-Boot (replacing with your specific machine name):
     $ LOG_LEVEL=0 bld uboot -m imx8mq-smarc-4g
  4. The compiled results is in build_lsdk2506/bsp/u-boot/.

Note: Typically, U-Boot or ATF files alone cannot be used independently. You need to generate a boot image using the following command:
$ bld bsp -m imx8mq-smarc-4g

The result is located at build_lsdk2506/images/firmware_imx8mq-smarc-4g_sdboot.img. This file can be installed using flex-installer.

• To modify and Use the Application Source Code:
  1. Navigate to the application module’s directory (using imx_lib as an example):
     $ cd components_lsdk2506/apps/multimedia/imx_lib/
  2. Modify the relevant code. Go back to the previous directory:
     $ cd –
  3. Compile the application module
     $ bld imx_lib -m imx8mq-smarc-4g
  4. The compiled code is located under build_lsdk2506/apps/apps_arm64_debian_<distro_type>/. Usually, the compiled output of a single component consists of multiple files, making them inconvenient for standalone use. In such cases, perform the following steps:
     • Merge applications into the target root filesystem:
       $ bld merge-apps -r debian:<variant>
     • Repackage to generate a new root filesystem:
       $ bld packrfs -r debian:<variant>

The new root filesystem is located at build_lsdk2506/images/rootfs_lsdk2506_debian_<variant>_arm64.tar.zst, which can then be installed using flex-installer.

---

You can modify code using patches in two scenarios, depending on whether a patch directory already exists for the component you want to change.

• If a patch directory already exists for the component:
  If there is already a patch/<component> directory for your component, perform the following steps:
  1. Place your new patch:
     Copy your generated patch file into the patch/<components> directory, alongside with any existing patches.
  2. Delete the component’s source directory:
     This ensures that during your recompilation, the system applies all patches, including the new one. Take imx_lib as an example:
     $ rm -rf components_lsdk2506/apps/multimedia/imx_lib/
  3. Recompile the source code. The new patch is then automatically applied during this process.

• If no patch directory exists for the component:
  If there is no existing patch/ directory for your component, create one and add the patch application logic:
  1. Create the component’s patch directory:
     $ mkdir patch/<component>
  2. Copy your patch:
     Place your patch file into the new patch/<component> directory.
  3. Modify the component’s source code to apply the patch:
     Add the code to the component’s build script (or a similar location) that applies the patches.
     See the GStreamer patch application snippet as an example:
     ————————————————————————————————————————————
     if [ ! -f .patchdone ]; then \
     git am $(FBDIR)/patch/gstreamer/*.patch $(LOG_MUTE) && touch .patchdone;
     \
     fi && \
     ———————————————————————————————————————————–
     This snippet checks if the patches have been applied (.patchdone file). If not, it applies all .patch files from the $(FBDIR)/patch/gstreamer/ directory using git am, and then creates a .patchdone file to mark the completion.
  4. Recompile the source code. The new patch is then automatically incorporated.

---

To add a new component called hello_world, perform the following steps:

1. Set the relevant URL and tag/commit information for the new component.
   You can edit configs/sdk-emb.yml to set the repository URL with a tag or commit for the hello_world Git tree if needed.
2. Create a makefile src/apps//hello_world.mk to add the build object for this component. According to the various types of the build system (e.g., make, cmake, meson) in the new component, refer to the following examples to add the hello_world.mk file.
   • For building with make, refer to src/apps/utils/imx_test.mk.
   • For building with cmake, refer to src/apps/graphics/gputop.mk.
   • For building with meson, refer to src/apps/multimedia/cheese.mk.
3. Build the new component based on the target ARM64 Debian RootFS.
   $ bld <component> [ -r <distro_type:distro_variant>]
   e.g.
   $ bld hello_world
   (Add ’-r debian:server’ for server version, ’-r debian:desktop’ can be omitted by default)
4. Merger the new component into the target Debian RootFS.
   $ bld merge-apps
   (Add ’-r debian:server’ for server version, ’-r debian:desktop’ can be omitted by default)
5. Pack the target Debian RootFS.
   $ bld packrfs
   (Add ’-r debian:server’ for server version, ’-r debian:desktop’ can be omitted by default)

---

version 1.0a, 10/28/2024

Last updated 2024-10-28