Mistake on this page? Email us

1.0 Mbed Linux OS BSP porting guide

1.1 Overview

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 boot loader BL2, and the Firmware Image Package (FIP) containing third-stage boot loaders 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 boot loader 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:

  • Section 1 introduces this guide, including an overview, porting prerequisites, and glossary.

  • Section 2 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.

  • Section 3 provides a top-down overview of the Yocto meta-layers in an MBL workspace for BSP development, including a software stack diagram showing how recipes from different layers collaborate.

  • Section 4 provides an overview of ${MACHINE}.conf, ATF, OP-TEE, U-Boot and linux recipe relationships using a UML diagram.

  • Section 5 discusses, in detail, the MBL ${MACHINE}.conf and community ${machine}.conf machine configuration files.

  • Section 6 discusses the u-boot*.bb base recipe and MBL u-boot*.bbappend customization.

  • Section 7 discusses the linux*.bb base recipe and the MBL linux*.bbappend customization.

  • Section 8 discusses the atf-${MACHINE}.bb recipe for building ARM Trusted Firmware.

  • Section 9 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.

  • Section 10 summarizes porting tasks.

  • Section 11 links to supporting references to this document.

1.2 Prerequisites

MBL uses Yocto, BitBake, openembedded-core and third-party meta-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.

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

For porting OP-TEE to your target platform, please consult the OP-TEE documentation.

1.3 Terminology

This section defines terminology used throughout this document.

Table 1.3: 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 Non-Trusted world firmware (NT-FW).
DTB                 Device tree binary
EL                  Execution level
FIP                 Firmware image package. This is a "simple filesystem" 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 non-security operating mode as defined in Arm reference documentation.
NT                  Non-Trusted
NT-FW               Non-Trusted Firmware binary (REF1)
                      - For example, BL33 U-Boot. Runs at EL2-NW.
NT-FW-CERT          Non-Trusted Firmware certificate (REF1)
                      - For example, U-Boot content certificate.
NT-FW-KEY-CERT      Non-Trusted 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.
                      - Contains the non-trusted 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.