Image Recovery Configuration, Build, and Usage Guide

Overview

The Image Recovery feature provides a minimal bootable recovery environment for AMD adaptive SoCs. Deployed in dedicated 20 MiB flash partitions, it enables system recovery, firmware updates, and platform restoration.

The system comprises a minimal linux-xlnx-small kernel (AArch64), image-recovery-tiny-initramfs rootfs, and xilinx-image-recovery distribution.

Builds support standalone mode (DISTRO = "xilinx-image-recovery") or multiconfig integration (BBMULTICONFIG) for parallel builds. Flash partitioning uses device tree overlays (imgrcvry-system-conf.dtsi for OSPI, imgrcvry-zynqmp-system-conf.dtsi for QSPI) with dual-bank A/B firmware update support.

Supported Platforms

Image Recovery supports the following AMD adaptive SoC platform families:

Supported Platform Families
Platform Family	Description
Versal	All Versal Adaptive SoC platforms (for example, VRK160, VEK280)
Versal Gen 2	All Versal Gen 2 (versal-2ve-2vm) platforms (for example, VEK385)
ZynqMP	Zynq UltraScale+ MPSoC platforms

Note

Kria system-on-modules (ZynqMP-based): For Kria platforms (KV/KR/KD), use the bare-metal-image-recovery.

Architecture

The Image Recovery system is a minimal, purpose-built recovery environment that provides essential tools and services for system recovery, firmware updates, and field maintenance. The architecture consists of the following key components:

Kernel - linux-xlnx-small: A minimal kernel configuration optimized for size, supporting AArch64 platforms only. This reduced configuration minimizes the flash footprint while providing essential drivers for recovery operations.
Distribution - xilinx-image-recovery: Custom distribution based on amd-edf-small, configured specifically for recovery scenarios with only essential packages included.
Bootloader - u-boot-xlnx-imgrcvry: Specialized U-Boot configuration with pre-configured recovery features and boot commands for Image Recovery operations.
Root Filesystem - image-recovery-tiny-initramfs: Minimal initramfs-based rootfs that includes:
- Network Access: Dropbear SSH server for remote access and management
- Flash Management: MTD utilities for flash device operations
- Firmware Update Tools: bmap-writer and libubootenv for image writing and U-Boot environment manipulation
- Recovery Utilities: Image recovery launcher, i2c-tools, ufs-utils, and system configuration tools
- Core System: packagegroup-core-boot, bash shell, and essential utilities
Image Type - imgrcvry: Custom image type that generates bootable *.bin files using bootgen with Boot Image Format (BIF) configuration.
Partition Layout: Device tree overlays defining dedicated flash partition schemes for QSPI (512 Mb) and OSPI (2 Gb) devices with separate partitions for Image Selector, Image Recovery, dual-bank firmware storage, and metadata.

Flash Partition Layout

Octal SPI Flash Layout (Versal/Versal Gen 2)

The Octal SPI (OSPI) flash layout for Image Recovery provides dedicated partitions:

OSPI Partition Layout
Partition Name	Offset	Size
Image Selector	`0x000000`	`0x60000` (384 KiB)
Image Selector Backup	`0x060000`	`0x60000` (384 KiB)
Image Selector Scratchpad	`0x0c0000`	`0x20000` (128 KiB)
Image Recovery	`0x0e0000`	`0x1400000` (20 MiB)
Image Recovery Scratchpad	`0x14e0000`	`0x20000` (128 KiB)
SystemReady-DT Update Metadata	`0x1500000`	`0x20000` (128 KiB)
SystemReady-DT Update Metadata Backup	`0x1520000`	`0x20000` (128 KiB)
U-Boot Variables	`0x1540000`	`0x20000` (128 KiB)
U-Boot Variables Backup	`0x1560000`	`0x20000` (128 KiB)
Bank A Space	`0x1580000`	`0x7200000` (114 MiB)
U-Boot Variables Bank A	`0x8780000`	`0x20000` (128 KiB)
U-Boot Variables Bank A Backup	`0x87a0000`	`0x20000` (128 KiB)
Bank B Space	`0x87c0000`	`0x7200000` (114 MiB)
U-Boot Variables Bank B	`0xf9c0000`	`0x20000` (128 KiB)
U-Boot Variables Bank B Backup	`0xf9e0000`	`0x20000` (128 KiB)
Custom Scratchpad	`0xfa00000`	`0x5e0000` (6016 KiB)

QSPI Flash Layout (ZynqMP)

The QSPI flash layout for Image Recovery (512 Mb flash):

QSPI Partition Layout
Partition Name	Offset	Size
Image Selector	`0x000000`	`0x60000` (384 KiB)
Image Selector Backup	`0x060000`	`0x60000` (384 KiB)
Image Selector Scratchpad	`0x0c0000`	`0x20000` (128 KiB)
Image Recovery	`0x0e0000`	`0x1400000` (20 MiB)
Image Recovery Scratchpad	`0x14e0000`	`0x20000` (128 KiB)
SystemReady-DT Update Metadata	`0x1500000`	`0x20000` (128 KiB)
SystemReady-DT Update Metadata Backup	`0x1520000`	`0x20000` (128 KiB)
U-Boot Variables	`0x1540000`	`0x20000` (128 KiB)
U-Boot Variables Backup	`0x1560000`	`0x20000` (128 KiB)
Bank A Space	`0x1580000`	`0x1000000` (16 MiB)
U-Boot Variables Bank A	`0x2580000`	`0x20000` (128 KiB)
U-Boot Variables Bank A Backup	`0x25a0000`	`0x20000` (128 KiB)
Bank B Space	`0x25c0000`	`0x1000000` (16 MiB)
U-Boot Variables Bank B	`0x35c0000`	`0x20000` (128 KiB)
U-Boot Variables Bank B Backup	`0x35e0000`	`0x20000` (128 KiB)
Custom Scratchpad	`0x3600000`	`0xa00000` (10240 KiB)

Configuration

There are two methods to configure and build Image Recovery:

Method 1: Direct Configuration

This method directly sets the distribution and builds the recovery image.

Step 1: Add meta-amd-imgrcvry Layer

Verify that the meta-amd-imgrcvry layer is included in your conf/bblayers.conf:

BBLAYERS ?= " \
    /path/to/poky/meta \
    /path/to/poky/meta-poky \
    /path/to/meta-openembedded/meta-oe \
    /path/to/meta-openembedded/meta-python \
    /path/to/meta-openembedded/meta-filesystems \
    /path/to/meta-openembedded/meta-networking \
    /path/to/meta-amd/meta-amd-core \
    /path/to/meta-amd/meta-amd-standalone \
    /path/to/meta-amd/meta-amd-standalone-sdt \
    /path/to/meta-amd/meta-amd-imgrcvry \
"

Step 2: Configure Machine and Distribution

In your conf/local.conf, set the machine and distribution:

# Set the target machine to a supported platform family

# Versal, Versal Gen 2, or ZynqMP family
# (update machine name as needed)
# MACHINE = "versal-2ve-2vm-vek385-multidomain"
# Set the Image Recovery distribution
DISTRO = "xilinx-image-recovery"

Step 3: Build the Image

Build the Image Recovery image:

$ bitbake image-recovery-tiny-initramfs

The build generates:

image-recovery-tiny-initramfs-<MACHINE>.imgrcvry.bin - The bootable recovery image
image-recovery-tiny-initramfs-<MACHINE>.cpio.lzma.u-boot - The compressed initramfs

Method 2: Multiconfig Build (Recommended)

This method uses Yocto’s multiconfig feature to build the recovery image alongside your main system image without changing your primary distribution.

Important

Even when using multiconfig, your main MACHINE setting must specify a platform that supports Image Recovery. The imgrcvry recipe has COMPATIBLE_MACHINE restrictions and skips the build if your machine lacks support.

Supported platform families:

Versal family & Versal Gen 2 - All Versal Adaptive SoC platforms (for example, versal-vek280-sdt, versal-2ve-2vm-vek385)
ZynqMP family

Note

For Kria ZynqMP platforms (KV/KR/KD), use bare-metal-image-recovery instead of the Linux-based Image Recovery.

Step 1: Set Compatible Machine

First, verify that your MACHINE in conf/local.conf specifies a supported platform family. Image Recovery supports both single-domain and multidomain machine configurations.

# Versal, Versal Gen 2, or ZynqMP family (update machine name as needed)
MACHINE = "versal-2ve-2vm-vek385-multidomain"

Step 2: Include Configuration File

In your machine configuration file or conf/local.conf, include the Image Recovery multiconfig enablement:

include conf/enable-amd-imgrcvry.conf

Or manually add to conf/local.conf:

BBMULTICONFIG += "xilinx-image-recovery"

IMGRCVRY_DEPENDS = ""
IMGRCVRY_MCDEPENDS = "mc::xilinx-image-recovery:image-recovery-tiny-initramfs:do_image_complete"
IMGRCVRY_DEPLOY_DIR = "${TMPDIR}-${MACHINE}-xilinx-image-recovery/deploy/images/${MACHINE}"
IMGRCVRY_IMAGE_NAME = "image-recovery-tiny-initramfs-${MACHINE}.imgrcvry"

Step 3: Build Using Multiconfig

Build the Image Recovery binary using the imgrcvry recipe:

$ bitbake imgrcvry

This:

Triggers a multiconfig build of image-recovery-tiny-initramfs
Copies the resulting binary into the default deploy directory
Makes it available as image-recovery-<MACHINE>.bin

Build Outputs

After a successful build, the following artifacts become available:

Main Image Files

Image Artifacts
File	Description
`image-recovery-tiny-initramfs-<MACHINE>.imgrcvry.bin`	Bootable Image Recovery binary (BIN format)
`image-recovery-tiny-initramfs-<MACHINE>.cpio.lzma.u-boot`	Compressed initramfs with U-Boot header
`imgrcvry.bif`	Boot Image Format file (build artifact)
`imgrcvry-version.txt`	Version information file

Included Packages

The image-recovery-tiny-initramfs includes:

Package Groups
Package/Group	Purpose
packagegroup-core-boot	Core system utilities
dropbear	SSH server for remote access
image-recovery-linux-dev	Recovery-specific device files and scripts
mtd-utils	Flash memory management utilities
i2c-tools	I2C bus utilities
libubootenv-bin	U-Boot environment manipulation
ufs-utils	UFS storage utilities
bmap-writer	Block map-based image writing
bash	Bash shell
fwenv-initramfs	Firmware environment configuration
address-config	Media access control address configuration
image-recovery-launcher	Recovery application launcher

Customization

Kernel Configuration

To customize the kernel configuration:

Create a .bbappend file in your layer:

$ mkdir -p meta-custom/recipes-kernel/linux
$ cat > meta-custom/recipes-kernel/linux/linux-xlnx-small_%.bbappend << 'EOF'
FILESEXTRAPATHS:prepend := "${THISDIR}/files:"

SRC_URI += "file://custom.cfg"
EOF

Add your kernel configuration fragment:

$ mkdir -p meta-custom/recipes-kernel/linux/files
$ cat > meta-custom/recipes-kernel/linux/files/custom.cfg << 'EOF'
CONFIG_CUSTOM_OPTION=y
EOF

Adding Custom Packages

To add packages to the Image Recovery rootfs, append to PACKAGE_INSTALL in your layer:

# In meta-custom/recipes-core/images/image-recovery-tiny-initramfs.bbappend
PACKAGE_INSTALL:append = " custom-package another-package"

Modifying Partition Layout

To modify the flash partition layout:

Create a custom device tree overlay:

$ mkdir -p meta-custom/recipes-bsp/device-tree/files
$ cp meta-amd/meta-amd-imgrcvry/recipes-bsp/device-tree/files/imgrcvry-system-conf.dtsi \
   meta-custom/recipes-bsp/device-tree/files/custom-imgrcvry-system-conf.dtsi

Edit the partition definitions as needed

Create a .bbappend to include your custom overlay:

# In meta-custom/recipes-bsp/device-tree/device-tree.bbappend
FILESEXTRAPATHS:prepend := "${THISDIR}/files:"

SRC_URI:append:imgrcvry = " file://custom-imgrcvry-system-conf.dtsi"

Customizing U-Boot

To customize U-Boot for Image Recovery:

Add custom U-Boot defconfig or configuration fragments
Create a .bbappend for u-boot-xlnx-imgrcvry

# In meta-custom/recipes-bsp/u-boot/u-boot-xlnx-imgrcvry_%.bbappend
FILESEXTRAPATHS:prepend := "${THISDIR}/files:"

SRC_URI += "file://custom_uboot.cfg"

Changing Image Format

The default image format is cpio.lzma.u-boot for the initramfs. To change it:

# In conf/local.conf or machine configuration
IMAGE_TYPEDEP:imgrcvry = "cpio.gz.u-boot"

Supported formats include: cpio.gz.u-boot, cpio.lzma.u-boot, cpio.lz4.u-boot

BIF Partition Customization

The Boot Image Format (BIF) file defines how Bootgen packages the Image Recovery components. You can customize partitions by setting variables:

# In conf/local.conf or custom .bbappend

# Add custom partition to IMGRCVRY_ATTR
IMGRCVRY_ATTR:append = " custom-partition"

# Define partition attributes
BIF_PARTITION_ATTR[custom-partition] = "type=raw, load=0x3000000"
BIF_PARTITION_IMAGE[custom-partition] = "${DEPLOY_DIR_IMAGE}/custom.bin"
BIF_PARTITION_ID[custom-partition] = "0x1d000000"