U-Boot Partition UUIDs: Avoid Confusing Disk GUIDs with Partition Identifiers

A Buildroot product can load its kernel successfully and still select
the wrong root partition after storage provisioning changes. One cause
is a namespace mistake: a disk GUID, a partition’s unique GUID and its
type GUID look alike in a log. They answer different questions. This
article follows U-Boot v2025.01 GPT handling into Linux v6.12 early
block-device lookup. It does not cover initramfs-specific filesystem
discovery or DOS partition identifiers.

Identify the field
before copying the string

U-Boot exposes separate commands for separate identifiers.
gpt guid reports the disk GUID. part uuid
obtains a partition identifier. part type reports the
partition type identifier where that support is enabled. The command
names are useful, but the implementation makes the distinction explicit.
GPT
command reference, partition
command reference.

In the GPT reader, get_disk_guid() converts the header’s
disk_guid. By contrast, part_get_info_efi()
fills the partition UUID from that entry’s
unique_partition_guid when partition UUID support is
enabled. Its type-GUID support reads partition_type_guid,
another field in the same entry. A matching type identifies a partition
category; it cannot distinguish two instances of that category. Tagged
GPT implementation.

Consequently, a provisioning record should label these values rather
than store an unexplained column called “UUID.” For each root slot,
record the physical storage role, partition entry, unique partition GUID
and expected contents. Keep the disk GUID in a separate disk-level
record. A type GUID belongs with the partition’s format or role
requirements.

Follow the value through
the handoff

do_part_uuid() first resolves the interface and
device-partition selector. It then prints info.uuid or
writes it to the requested environment variable. That is the field to
trace when generating a GPT-based root=PARTUUID=...
argument. Obtaining it from a device number does not prove that the
selected device has the intended product role; verify that mapping
before accepting the resulting identifier. Partition
command implementation.

Linux v6.12 routes the PARTUUID= prefix to
devt_from_partuuid(). That function searches partition
metadata, not filesystem UUIDs, and returns the first matching
partition. This article considers a complete partition GUID without the
optional relative-partition suffix. Linux
early block-device lookup.

The distinction creates a useful diagnostic boundary. If the command
line contains the disk GUID or type GUID, fix its construction. If it
contains the intended partition GUID but no matching partition becomes
available, investigate storage discovery and partition parsing. If
several devices advertise that same partition GUID, the identifier no
longer uniquely expresses the intended target.

Cloning changes the
uniqueness question

Consider a hypothetical manufacturing workflow that duplicates a
complete disk image onto both soldered storage and removable service
media. If it preserves the partition GUIDs, both devices can advertise
the same root identifier. A string that once selected a single partition
now describes multiple candidates. The first-match lookup provides no
product-specific preference for the soldered device.

Changing only the disk GUID does not alter the entry’s unique
partition GUID. Conversely, changing the partition GUID without updating
its boot reference breaks the intended relationship even when the
filesystem contents remain unchanged. These are consequences of separate
fields and consumers, not results measured on a board.

Make GUID preservation or regeneration an explicit provisioning
decision. When identifiers change, update every boot path that refers to
them, including a recovery policy that might construct its own command
line. When identifiers are intentionally shared across mutually
exclusive images, qualify the assumption that those images cannot be
visible together.

Inspect a controlled
identity matrix

A focused qualification uses disposable images with deliberately
different disk GUIDs, partition GUIDs and type GUIDs. First verify that
U-Boot’s three queries return the expected fields. Then inspect the
final Linux command line, rather than only the variable used to build
it. Finally, introduce a duplicate partition GUID on a second visible
test device and treat ambiguity as a failed identity contract,
regardless of which device happens to win.

This procedure does not require rewriting production partition
tables. Its purpose is to establish that the root reference names the
intended partition instance. No GUID generation, disk modification or
boot test was performed for this article.