Partition Layout and Boot Sequence¶

Partitions¶

This is the reference and default partition layout in Welma:

┌─────────────────┐ ┌───────────┐
│ bootloader/UEFI │ │ bootflags │
└─────────────────┘ └───────────┘

┌─ boot.vfat (BOOT A) ─────┐ ┌─ boot.vfat (BOOT B)──────┐
│                          │ │                          │
│ ┌─ FIT image ───────┐    │ │ ┌─ FIT image ───────┐    │<-------┐
│ │                   │    │ │ │                   │    │        | 
│ │ kernel            │    │ │ │ kernel            │    │ For U-Boot based 
│ │ initramfs (/init) │    │ │ │ initramfs (/init) │    │   machines only
│ │ dtb               │    │ │ │ dtb               │    │        | 
│ └───────────────────┘    │ │ └───────────────────┘    │<-------┘
│                          │ │                          |
│           OR             │ │           OR             │
│                          │ │                          │
│ ┌─ UEFI Comboapp ───┐    │ │ ┌─ UEFI Comboapp ───┐    │<-------┐ 
│ │                   │    │ │ │                   │    │        |
│ │ UEFI Stub         │    │ │ │ UEFI Stub         │    │        |
│ │ kernel            │    │ │ │ kernel            │    │ For UEFI based
│ │ cmdline.txt       │    │ │ │ cmdline.txt       │    │  machines only
│ │ intel microcode   │    │ │ │ intel microcode   │    │        |
│ │ initramfs (/init) │    │ │ │ initramfs (/init) │    │        |
│ └───────────────────┘    │ │ └───────────────────┘    │<-------┘
└──────────────────────────┘ └──────────────────────────┘

┌─ sysro.ext4 (SYSRO A) ───┐ ┌─ sysro.ext4 (SYSRO B) ───┐
│                          │ │                          │
│ /sbin/init               │ │ /sbin/init               │
│                          │ │                          │
│                          │ │                          │
└──────────────────────────┘ └──────────────────────────┘
┌─ appro.ext4 (APPRO A) ───┐ ┌─ appro.ext4 (APPRRO B) ──┐
│                          │ │                          │
│                          │ │                          │
└──────────────────────────┘ └──────────────────────────┘
┌─ sysrw.ext4 (SYSRW)───────────────────────────────────┐
│                                                       │
│                                                       │
└───────────────────────────────────────────────────────┘

Mount points of active partitions:

• BOOT: /boot
• SYSRO: /
• APPRO: /app
• SYSRW: /var

Besides, /var/home is mounted on /home, which enables storage of cache data and speeds up the boot sequence.

Notes:

• Partitions may differ for some machines that have 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 suffixed with .verity (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)

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

UEFI based machines:¶

• UEFI (Power On Self Test)
• UEFI Boot Sequence
  • UEFI: selects the first Boot Partition in the UEFI BootOrder variable
  • UEFI: Loads the Comboapp (Intel microcode, 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 enable the bootloader and userspace programs to communicate about updated software partitions.

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

/etc/welma-partitions.conf¶

This file maps BOOT, SYSRO, APPRO to Linux devices.

Example:

# NAME   MOUNTPOINT   DEVICE A    DEVICE B    OPTIONS
boot     /boot        /dev/vda2   /dev/vda3
sysro    /            /dev/vda5   /dev/vda6
appro    /app         /dev/vda7   /dev/vda8
var      /var         /dev/vda9

Since the enumeration of peripherals in the kernel is not demerministic, 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    OPTIONS
boot     /boot        2           3
sysro    /            5           6
appro    /app         7           8
var      /var         9

Options can be:

• verity: the partition contains a .verity envelop
• boot: Mark the boot partitions (mandatory for UEFI based machines, ignored for U-Boot based machines)

Yocto Build¶

SD card image (wic)¶

When building Welma, a SD card image is generated (by wic, with extensions .wic or .wic.gz), with the whole partitioning and suitable for installation on the machine (eMMC or SD card).

How to Customize Partitions Sizes¶

You probably want 2 things:

• Have enough space in your read-write partitions (SYSRW) to store operational data

To reserve space in your read-write partitions (SYSRW), you need to set IMAGE_SYSRW_EXTRA_SPACE in your image recipe:

Example:

# Extra space for /var in 1024-byte blocks
IMAGE_SYSRW_EXTRA_SPACE = "390000"

• Have partitions of BOOT, SYSRO and APPRO large enough to host future versions

To set the size of your partition, if using wic, you need to update the wic description (WKS_FILE). See OpenEmbedded Kickstart Reference.

In branch scarthgap, Welma uses these variables: PARTITION_SIZE_APPRO, PARTITION_SIZE_BOOT, PARTITION_SIZE_SYSRO, PARTITION_SIZE_SYSRW (defined in the image recipe, and used in the wic description).

How to Customize Partitions Numbers¶

The mapping is defined in the file given by WELMA_PARTITIONS and is installed in /etc/welma-partitions.conf.

Eg:

WELMA_PARTITIONS = "partitions-${MACHINE}.conf"

This file is searched under files/${WELMA_PARTITIONS} in BBPATH.

In this file:

• You may change the paths under DEVICE A/B
• You may NOT change NAME nor MOUNTPOINT

This files is used:

• at build time for setting up static (ie: non A/B) partitions in /etc/fstab
• at runtime for mounting A/B partitions

If using wic, you need to update the wic description (WKS_FILE) as well. See OpenEmbedded Kickstart Reference.

How to Relocate Bootflags¶

For U-Boot based machines, the bootflags are stored as a raw memory segment that must be accessible by both the bootloader and Linux userspace programs (read and write).

For UEFI based machines, the bootflags are stored in a separate partition on the device (disk). this partition must not contain any file system (raw data) and must be accessible by the Linux userspace programs (read and write).

The following parameters can be modified in your global configuration (local.conf or ${MACHINE}.conf):

• BOOTFLAGS_PATH: path in Linux userspace context. Note that if the path pointed to by BOOTFLAGS_PATH does not exist, Welma will create it and point it to the partition named bootflags (this option offers flexibility so that bootlfags can be used on the boot disk without necessarily knowing how the kernel will enumerate it). In this case, this parameter must be set to a path under /dev/disk (e.g /dev/disk/bootflags).
• BOOTFLAGS_OFFSET: address of the main bootflags segment (in bytes) within BOOTFLAGS_PATH
• BOOTFLAGS_OFFSET_COPY: address of the duplicate (in bytes) within BOOTFLAGS_PATH
• BOOTFLAGS_DEFAULT_SLOTS: default slots for bootflags initialization (e.g 2:4:6). Required for UEFI based machine.

The _OFFSET addresses should point at the beginning of a block (eg. if the eMMC block size is 512, then the addresses must be multiple of 512), in order to minimize chances of corruption in case of any hard reset.

Example:

BOOTFLAGS_PATH ?= "/dev/mmcblk0"
BOOTFLAGS_OFFSET ?= "0x100000"
BOOTFLAGS_OFFSET_COPY ?= "0x100200"

U-Boot¶

When using U-Boot, you should also provide a configuration aligned with the above:

• CONFIG_BOOTFLAGS_OFFSET and _COPY:

Example:

CONFIG_CMD_BOOTFLAGS=y
CONFIG_BOOTFLAGS_INTERFACE="mmc"
CONFIG_BOOTFLAGS_DEVICE=0
CONFIG_BOOTFLAGS_OFFSET=0x100000
CONFIG_BOOTFLAGS_OFFSET_COPY=0x100200

Bootloader U-Boot¶

The custom U-Boot environment is defined in an external file specified by:

CONFIG_ENV_SOURCE_FILE="distro-bootcmd"

This is where the kernel A/B selection is done.

At boot time, if the bootflags are not initialized (or are corrupted), they are initialized with a default value. Eg:

...
bf_default_boot_partitions=0x12 /* active partitions 2:5 */
...