Mistake on this page? Email us

Mbed Linux OS BSP porting guide

This document details how to port an existing Arm Cortex-A board support package (BSP) to Mbed Linux OS (MBL), enabling the platform's software stack for security, connection to Pelion Device Management and firmware update.

Porting a BSP centers on configuring the secure boot software components, so the correct artifacts appear on the right flash partitions for update:

  • Trusted Firmware for Cortex-A (TF-A): Use Trusted Firmware in v7A AArch32 and v8A AArch64 secure boot processes. TF-A artifacts include the second-stage bootloader BL2 and the Firmware Image Package (FIP) containing third-stage bootloaders BL3x and certificates.
  • Open Platform Trusted Execution Environment (OP-TEE): This is the OS with trusted applications running in the TrustZone secure world and is packaged as BL32 in the FIP image.
  • U-Boot: U-Boot is the Normal world bootloader for loading a Rich OS. This is packaged as BL33 inside the FIP image.
  • Linux kernel: The Linux kernel is the Normal world Rich OS kernel. The kernel image is packaged with the device tree binaries and initial RAM file system in a Flattened Image Tree (FIT) image.

This document's structure follows the work process:

  • This section introduces this guide, including an overview, porting prerequisites and glossary.
  • System architecture describes the relevant system architecture of AArch32 and AArch64 secure boot flows, partitioning build artifacts between BL2, FIP and FIT images and the flash partition layout for updating firmware.
  • Overview of MBL Yocto layers provides a top-down overview of the Yocto layers in an MBL workspace for BSP development, including a software stack diagram showing how recipes from different layers collaborate.
  • BSP recipe relationships provides an overview of ${MACHINE}.conf, ATF, OP-TEE, U-Boot and linux recipe relationships using a UML diagram.
  • Machine configuration files discusses, in detail, the MBL ${MACHINE}.conf and community ${machine}.conf machine configuration files.
  • u-boot* discusses the u-boot*.bb base recipe and MBL u-boot*.bbappend customization.
  • linux* discusses the linux*.bb base recipe and MBL linux*.bbappend customization.
  • atf-${MACHINE}.bb discusses the atf-${MACHINE}.bb recipe for building Arm Trusted Firmware.
  • Example: imx7s-warp-mbl BSP recipe/package relationships provides a concrete example for the WaRP7 target of the ${MACHINE}.conf, ATF, OP-TEE, U-Boot and linux recipe inter-relationships using a UML diagram.
  • Summary of BSP porting tasks summarizes porting tasks.
  • References links to supporting references to this document.


MBL uses Yocto, BitBake, openembedded-core and third-party layers to compose the development and build workspace.

We recommend reading Embedded Linux Systems with the Yocto Project first, then the Yocto Mega Manual, as well as the Yocto Project Board Support Package (BSP) Developer's Guide.

To port ATF to your target platform, please consult the ATF porting guide.

To port OP-TEE to your target platform, please consult the OP-TEE documentation.


This section defines terminology used throughout this document.

Table 1.2: Acronyms and terminology

  • REF1: Term is defined in TF-A fiptool documentation and source code.
  • REF2: Term is defined in TrustZone documentation.
Term Definition
AP Application processor
ATF Arm Trusted Firmware
BL Bootloader
BL1 First-stage bootloader
BL2 Second-stage bootloader. This is based on TF-A running at EL3 when the Memory Management Unit (MMU) is switched off. BL2 loads the FIP image and authenticates FIP content.
BL31 Third-stage bootloader, part one. For example, Secure Monitor running in EL1-SW. This stage enables the MMU.
BL32 Third-stage bootloader, part two. For example, OP-TEE, the secure world OS. This typically switches to Normal world.
BL33 Third-stage bootloader, part three. For example, U-Boot, the Normal world bootloader. Also referred to as Nontrusted world firmware (NT-FW).
DTB Device tree binary
EL Execution level
FIP Firmware image package. This is a "simple file system" for managing signed bootchain components.
FIT Flattened Image Tree. This is a Linux kernel image container for holding the kernel, kernel DTB and initramfs.
Linux The runtime Normal world kernel.
MBL Mbed Linux OS
MMU Memory Management Unit
Normal world The nonsecurity operating mode as defined in Arm reference documentation.
NT Nontrusted
NT-FW Nontrusted Firmware binary (REF1). For example, BL33 U-Boot. Runs at EL2-NW.
NT-FW-CERT Nontrusted Firmware certificate (REF1). For example, U-Boot content certificate.
NT-FW-KEY-CERT Nontrusted Firmware certificate (REF1)
NW Normal world (REF2)
OP-TEE Open Platform Trusted Execution Environment
Secure world The high security operating mode as defined in Arm reference document.
SW Secure world (REF2)
SOC-FW System-On-Chip Firmware binary (REF1)
SOC-FW-CERT System-On-Chip Firmware certificate (REF1)
SOC-FW-KEY-CERT System-On-Chip Firmware key certificate (REF1)
ROT Root of Trust
ROTPK Root of Trust public key
ROTPrvK Root of Trust private key
TBBR Trusted Board boot requirements
TBBR-CLIENT TBBR specification document
TB-FW Trusted Board Firmware binary (REF1)
TB-FW-CERT Trusted Board Firmware certificate (REF1)
TB-FW-KEY-CERT Trusted Board Firmware key certificate (REF1)
TF-A Trusted Firmware for Cortex-A
TOS-FW Trusted OS Firmware binary (REF1)
TOS-FW-CERT Trusted OS Firmware certificate (REF1)
TOS-FW-EXTRA1 Trusted OS Firmware Extra-1 binary (REF1)
TOS-FW-EXTRA2 Trusted OS Firmware Extra-2 binary (REF1)
TOS-FW-KEY-CERT Trusted OS firmware key certificate (REF1)
TRUSTED-KEY-CERT Trusted Key Certificate. Contains the trusted world public key and nontrusted world public key.
WIC Openembedded Image Creator application.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.