EDF Disk Image Layout
This page is the canonical reference for the partition layout of the
EDF Linux common disk image (edf-linux-disk-image,
edf-platform-disk-image, and the Kria variants). It documents the
partition map produced by the Yocto Project wic image generation, the
role of each partition, mount points, filesystem types, and sizes.
Other pages in this documentation that show partition output or describe the layout cross-reference this page rather than duplicate the content.
Overview
The EDF disk image is produced by the Yocto Project from a
wic kickstart
file in meta-amd-edf/meta-amd-edf-core/files/wic/. The kickstart used
for your board, and the resulting partition layout, depend on whether the
machine config sets efi in COMBINED_FEATURES.
Your board uses edf-disk-single-rootfs-efi.wks: a
GPT-hybrid layout that boots through EFI with
systemd-boot.
Your board uses edf-disk-single-rootfs.wks: an MBR layout
that boots through U-Boot distro_bootcmd and boot.scr.
Both kickstarts produce three partitions with the same conceptual roles; only the partition table format and the first-partition contents differ. Use the board selector at the top of the page to switch the rest of this page between the two layouts.
Partition Layout
The EFI boot layout uses a GPT-hybrid partition table.
Num |
Mount point |
Size |
Filesystem |
Role |
Purpose |
|---|---|---|---|---|---|
1 |
|
1 GiB |
|
Holds |
|
2 |
|
2 GiB |
|
User-writable storage |
Mounted with |
3 |
|
grown to fill disk |
|
Linux rootfs |
General-purpose Linux user-space rootfs built by the Yocto
Project. |
The wks selects the table format with bootloader --ptable
gpt-hybrid. The ESP is marked active, and the
partition-type GPT GUIDs come from
ESP_PART_TYPE and ROOTFS_PART_TYPE. These follow the
Discoverable Partitions Specification
and are set in meta-amd-edf/meta-amd-edf-core/conf/distro/amd-edf.conf.
On a booted EDF system the ESP contains:
/efi/
├── BOOTAA64.EFI # systemd-boot loader (EFI default)
├── boot.bin # SoC first-stage boot image (added post-build)
├── boot.bin.manifest.json # boot.bin component manifest (builds with boot.bin on disk)
├── boot-version.txt # boot firmware version (Versal builds with boot.bin on disk)
├── edf-version.txt # EDF release, machine, architecture
├── image.manifest # rootfs package list
├── Image # Linux kernel image
├── xen.efi # Xen hypervisor (EDF Xen menu entry)
├── xen.cfg # Xen command line
├── EFI/
│ └── UpdateCapsule/ # UEFI capsule update drop directory
└── loader/
├── loader.conf # systemd-boot defaults
└── entries/
├── edf-linux.conf # default Linux entry
└── edf-xen.conf # Xen Dom0 entry
Each menu entry’s kernel command line lives in the matching
loader/entries/*.conf file. See
systemd-boot for boot manager details
and Root Partition Identification (PARTUUID) for the root
partition identification scheme.
The metadata files are described in Image Metadata Files on the Boot Partition.
The distroboot layout uses an MBR partition table and
applies when efi is not in COMBINED_FEATURES.
Num |
Mount point |
Size |
Filesystem |
Role |
Purpose |
|---|---|---|---|---|---|
1 |
|
1 GiB |
|
First-vfat boot placeholder |
Marked active and not used for EFI boot; mirrors the
EFI layout for consistent partition numbering and
can hold |
2 |
|
2 GiB |
|
User-writable storage |
Mounted with |
3 |
|
grown to fill disk |
|
Linux rootfs |
General-purpose Linux user-space rootfs built by the Yocto
Project. |
Image Metadata Files on the Boot Partition
The image build writes metadata files to the first vfat partition,
so any host can identify a card without booting the board or reading
the ext4 rootfs.
File |
Present on |
Contents |
|---|---|---|
|
Every disk image |
EDF release, machine, and architecture. |
|
Every disk image |
Rootfs package list. |
|
Builds with |
Branch and source revision of each |
|
Versal builds with |
Boot firmware version string. Zynq 7000 and ZynqMP embed a hex
header instead, so read their version from
|
Common disk images ship without boot.bin and carry the first two
files only. edf-version.txt reads:
AMD Embedded Development Framework
Release: 26.11+release-<build-id>
Machine: amd-cortexa78-mali-common
Architecture: aarch64
The build id is the build stamp on an image AMD publishes, and the metadata revision on one you build yourself.
Mount the first partition of the card to read them. On Windows it appears as a drive letter.
Root Partition Identification (PARTUUID)
EDF identifies the root filesystem with root=PARTUUID=... on
the kernel command line rather than a device path such as
/dev/mmcblk0p3. This makes the same image bootable from any media
(SD, USB, UFS).
Warning
Booting two media that share the same root filesystem PARTUUID produces undefined behavior. U-Boot and Linux can enumerate the devices in different orders, and the kernel mounts the first partition with the matching PARTUUID. The PARTUUID is generated per build, so different builds on different media coexist correctly; identical copies of the same build still collide.
The wks sets the PARTUUID with --uuid="${ROOTFS_PART_UUID}" on the
rootfs partition.
systemd-boot reads the PARTUUID from the
loader/entries/edf-linux.conf options line.
U-Boot distro_bootcmd passes the PARTUUID on the kernel command
line built by boot.scr.
Inspecting and Modifying the wic Image
List the partitions of a wic image:
$ oe-run-native wic-native wic ls tmp/deploy/images/<machine>/edf-linux-disk-image-<machine>.rootfs.wic
Num Start End Size Fstype
1 32768 1073774591 1073741824 fat32
2 1073774592 3221258239 2147483648 fat32
3 3221258240 8589967359 5368709120 ext4
List the contents of an individual partition (here the ESP):
$ oe-run-native wic-native wic ls tmp/deploy/images/<machine>/edf-linux-disk-image-<machine>.rootfs.wic:1
Copy boot.bin into the ESP of an existing wic image
(for SD/USB single-stage boot):
$ oe-run-native wic-native wic cp tmp/deploy/images/<bootbin-machine>/boot.bin \
tmp/deploy/images/<common-machine>/edf-linux-disk-image-<common-machine>.rootfs.wic:1
Note
For the UFS image variant (.wic.ufs) the underlying
device uses 4 KiB sectors, so wic cp requires
--sector-size 4096:
$ oe-run-native wic-native wic cp --sector-size 4096 boot.bin <image-name>.rootfs.wic.ufs:1
To edit the kernel command line in a built image, copy
loader/entries/edf-linux.conf out of the ESP, edit it, then
copy it back:
$ oe-run-native wic-native wic cp <image>.wic:1/loader/entries/edf-linux.conf .
$ # edit edf-linux.conf
$ oe-run-native wic-native wic cp edf-linux.conf <image>.wic:1/loader/entries/
Flash Memory Layouts
The QSPI and OSPI boot flash partition tables (used for two-stage boot on Versal evaluation boards) are documented separately from the disk image layout. See OSPI/QSPI Memory Layout - Common Specification for the common OSPI / QSPI memory map and UEFI Variables SPI Partition Layout (AMD Versal OSPI / QSPI) for the UEFI variables partition layout.