Reference Partition Layout and Boot Sequence¶

Welma comes with a reference (default) partition layout, on which are based the boot sequence, the software update and secure boot mechanisms.

This page describes this reference layout. To customize partitions, see the page Generic Partitioning.

Partitions¶

Reference partition layout in Welma:

┌──────────────────────────┐ ┌───────────┐
│ bootloader/UEFI firmware │ │ bootflags │
└──────────────────────────┘ └───────────┘
┌─ boot.vfat (BOOT A) ─────┐ ┌─ boot.vfat (BOOT B)──────┐
│                          │ │                          │
│ ┌─ Kernel image ────┐    │ │ ┌─ Kernel image ────┐    │
│ │ Linux kernel      │    │ │ │ Linux kernel      │    │
│ │ initramfs (/init) │    │ │ │ initramfs (/init) │    │
│ │ extra (see below) │    │ │ │ extra (see below) │    │
│ └───────────────────┘    │ │ └───────────────────┘    │
└──────────────────────────┘ └──────────────────────────┘
┌─ sysro.ext4 (SYSRO A) ───┐ ┌─ sysro.ext4 (SYSRO B) ───┐
│                          │ │                          │
│ /sbin/init               │ │ /sbin/init               │
│                          │ │                          │
│                          │ │                          │
└──────────────────────────┘ └──────────────────────────┘
┌─ appro.ext4 (APPRO A) ───┐ ┌─ appro.ext4 (APPRRO B) ──┐
│                          │ │                          │
│                          │ │                          │
└──────────────────────────┘ └──────────────────────────┘
┌─ sysrw.ext4 (SYSRW)───────────────────────────────────┐
│                                                       │
│                                                       │
└───────────────────────────────────────────────────────┘

The Kernel image has 2 possible formats:

For Arm-based machines, using U-Boot, it is in FIT format and also contains:
- devices trees (dtb)
For Intel-base machines, it is a UEFI application (Comboapp) and also has:
- UEFI Stub
- cmdline.txt

Mount points at runtime:

Mount point	Description
`/boot`	Active BOOT partition
`/`	Active SYSRO partition
`/app`	Active APPRO partition
`/var`	SYSRW partition
`/home`	Mounted from `/var/home` (enables storage of cached data)

Notes:

On some machines, the bootloader is split into additional partitions.
A/B Partitions are duplicated (A and B) in order to resist to any hardware reset during software updates.
When secure boot is enabled, SYSRO and APPRO partitions are in .verity format (see Secure Boot Overview)

Boot Sequence¶

This section details the boot sequence for the different machines supported by Welma. These machines fall into two main categories: U-Boot based machines (used for arm machines) and UEFI based machines (without any bootloader, for intel x86-64 machines)

Arm/U-Boot based machines:¶

ROM Code (depends on the machine)
Bootloader (depends on the machine)
- Machine-specific sequence (not detailed here)
- U-Boot: Reads bootflags
- U-Boot: Selects the active BOOT partition (see page Software Update)
- U-Boot: Loads the FIT image (kernel, dtb, initramfs)
- U-Boot: Starts the Linux kernel
Linux kernel: Initializes userspace
Initramfs
- /init script
- Mounts active partitions SYSRO and APPRO (depending on bootflags and on /etc/welma-partitions.conf)
- Hands over control to /sbin/init of SYSRO
SYSRO
- Standard boot sequence with systemd
APPRO
- Starts project-specific applications

The U-Boot sequence is defined in by a script of the default environment. At build time, this script is defined in an external file specified by:

CONFIG_ENV_SOURCE_FILE="distro-bootcmd"

UEFI based machines:¶

UEFI (Power On Self Test)
UEFI Boot Sequence
- UEFI: Selects the active BOOT partition according to the UEFI BootOrder variable
- UEFI: Loads the Comboapp (kernel, initrd, cmdline.txt)
- UEFI: Starts the Linux kernel with the content of cmdline.txt as arguments
Linux kernel: Initializes userspace
Initramfs
- /init script
- Check/update UEFI environment. A reboot may occur in this step to update the UEFI environment.
- Mounts active partitions SYSRO and APPRO (depending on bootflags and on /etc/welma-partitions.conf)
- Hands over control to /sbin/init of SYSRO
SYSRO
- Standard boot sequence with systemd
APPRO
- Starts project-specific applications

Bootflags¶

The bootflags are used:

by U-Boot to select which kernel to boot
by initramfs to select which filesystems to mount
by the software update daemon to write which partitions are being updated

The bootflags hold the following information:

test mode, boolean:
- yes: the device shall try booting on A/B partitions marked as under test
- no: the device shall boot on normal A/B partitions
normal slots: normal A/B partitions, known as operational
test slots: A/B partitions under test, that just got installed and have not been confirmed as valid yet
test count: number of consecutive attempts of booting in test mode

The bootflags are duplicated in 2 NVM sectors, in order to resist to an unexpected hardware reset.

Normal and Test Slots¶

The value is a bit field. Each bit refers to a partition: the first bit refers to partition 1, bit 2 refers to partition 2, and so on.

Values:

0: the partition is either inactive or non A/B
1: the partition is active

Initialization¶

This section explains how the bootflags get initialized when they are not initialized (typically on the very first boot) or are found to be corrupted.

On U-Boot-based machines, the system selects the first Kernel image, configured by CONFIG_BOOTFLAGS_FIRST_ACTIVE_PARTITION.

Then, for all machines, the initramfs proceeds with the initialization of the bootflags using the default configuration (/etc/default/bootflags).

`/etc/welma-partitions.conf`¶

At runtime, this file is used by the system to map partitions to physical storage.

Example using the reference partition layout:

# NAME   MOUNTPNT DEVICE-A       DEVICE-B       FLAGS                          OPTIONS
boot     /boot/   /dev/mmcblk2p1 /dev/mmcblk2p2 boot,update=ab                 ro
sysro    /        /dev/mmcblk2p3 /dev/mmcblk2p4 verity,update=ab               ro
appro    /app/    /dev/mmcblk2p5 /dev/mmcblk2p6 verity,update=ab               ro
sysrw    /var/    /dev/mmcblk2p7 -              -                              defaults,noexec
bootldr  -        /dev/mmcblk2   -              devoffset=32768,update=single  -

Since the enumeration order of peripherals in the kernel is not deterministic, Welma offers flexibility for x86 machines, making it possible to map the BOOT, SYSRO and APPRO partitions to the partition numbers directly.

In this case, the partition numbers listed will automatically be taken from the device on which welma starts.

Example (For x86 machines only):

# NAME  MOUNTPOINT      DEVICE-A        DEVICE-B        FLAGS   OPTIONS
boot    /boot/          2               3               boot    ro
appro   /app/           6               7               -       ro
sysrw   /var/           8               -               -       defaults,noexec
sysro   /               4               5               -       ro

FLAGS can be:

boot: These are the boot partitions, i.e. with the Linux kernel (mandatory for UEFI based machines, ignored for U-Boot based machines)
devoffset: Offset where the partition starts (in bytes)
devtype: Type block (default) or flash
size: Size of the partition (in bytes)
update=: This describes how the partition can be updated. Possible values: no (default), ab, single
verity: The partition contains a .verity envelop

OPTIONS are mounting options.

Yocto Build¶

Building a Welma image recipe will:

Build /etc/welma-partitions.conf and add it in the initramfs and in sysro

Append a line in /etc/fstab in sysro:

/var/home   /home   none    defaults,bind   0   0

Generate an SD card image (with extensions .wic or .wic.*), with all the partitions and suitable for installation on the machine (eMMC or SD card).

Generate software update modules in ${DEPLOY_DIR_IMAGE}. Eg:

demo-image-headless-stm32mp25-disco-welma.appro.swu
demo-image-headless-stm32mp25-disco-welma.boot.swu
demo-image-headless-stm32mp25-disco-welma.fip.swu
demo-image-headless-stm32mp25-disco-welma.fsbl1.swu
demo-image-headless-stm32mp25-disco-welma.sysro.swu

These are automatically generated during the image build process, based on the information provided in the .part and .split files. For more details, please refer to Generic Partitioning page.