/// The all-zero GUID, which marks an unused entry.

pub const NIL: Guid = Guid([0u8; 16]);

/// Build a GUID from the five groups of its canonical spelling —

/// `Guid::from_fields(0xC12A7328, 0xF81F, 0x11D2, 0xBA4B, 0x00A0C93EC93B)`

/// is the EFI system partition — applying GPT's mixed endianness.

pub const fn from_fields(a: u32, b: u16, c: u16, d: u16, e: u64) -> Guid {

let a = a.to_le_bytes();

let b = b.to_le_bytes();

let c = c.to_le_bytes();

let d = d.to_be_bytes();

let e = e.to_be_bytes();

Guid([

a[0], a[1], a[2], a[3], b[0], b[1], c[0], c[1], d[0], d[1], e[2], e[3], e[4], e[5],

e[6], e[7],

])

}

/// Whether this is the all-zero GUID.

pub fn is_nil(&self) -> bool {

self.0 == [0u8; 16]

}

/// A version-4 (random) GUID made from `bytes`, which should come from

/// whatever random source the platform has: the version and variant

/// bits are set, everything else is taken as given.

pub const fn random_v4(mut bytes: [u8; 16]) -> Guid {

// Byte 7 holds the version nibble (the third group is stored

// little-endian), byte 8 the variant bits.

bytes[7] = (bytes[7] & 0x0F) | 0x40;

bytes[8] = (bytes[8] & 0x3F) | 0x80;

Guid(bytes)

}

/// The LBA this header was read from, as the header itself records it.

pub my_lba: u64,

/// Where the other copy of the header lives.

pub alternate_lba: u64,

/// First and last sector a partition may occupy.

pub first_usable_lba: u64,

pub last_usable_lba: u64,

/// The disk's own GUID.

pub disk_guid: Guid,

/// First sector of the partition entry array.

pub entries_lba: u64,

/// Entries the array holds, and the size of each.

pub entry_count: u32,

pub entry_size: u32,

/// CRC-32 the header records for the entry array. A caller that wants to

/// verify the array itself can compute it with

/// [`crate::crc::crc32_small`] over every entry in order — this reader

/// does not, since that means reading the whole array twice.

pub entries_crc32: u32,

/// Decode a header out of the sector it lives in, verifying its CRC.

///

/// `None` when this is not a GPT header, is a revision this reader does

/// not understand, fails its checksum, or describes an array it could not

/// walk.

pub fn decode(sector: &[u8]) -> Option<Header> {

if sector.len() < MIN_HEADER_SIZE as usize || &sector[0..8] != SIGNATURE {

return None;

}

if le32(sector, 8) != REVISION {

return None;

}

let header_size = le32(sector, 12);

if header_size < MIN_HEADER_SIZE || header_size as usize > sector.len() {

return None;

}

// The CRC covers `header_size` bytes with its own field zeroed. It is

// computed a piece at a time so that no copy of the sector is needed.

let stored = le32(sector, 16);

// `crc32_small`, not `crc32`: the table-driven one would pull 8 KiB

// of lookup tables into a firmware image to checksum 92 bytes.

let crc = crate::crc::crc32_small_append(

crate::crc::crc32_small_append(

crate::crc::crc32_small_append(0, &sector[..16]),

&[0, 0, 0, 0],

),

&sector[20..header_size as usize],

);

if stored != crc {

return None;

}

let entry_size = le32(sector, 84);

if entry_size < MIN_ENTRY_SIZE {

return None;

}

let mut guid = [0u8; 16];

guid.copy_from_slice(&sector[56..72]);

Some(Header {

my_lba: le64(sector, 24),

alternate_lba: le64(sector, 32),

first_usable_lba: le64(sector, 40),

last_usable_lba: le64(sector, 48),

disk_guid: Guid(guid),

entries_lba: le64(sector, 72),

entry_count: le32(sector, 80),

entry_size,

entries_crc32: le32(sector, 88),

})

}

/// Entries this reader will walk: what the header claims, bounded by

/// [`MAX_ENTRIES`].

pub fn entries(&self) -> u32 {

self.entry_count.min(MAX_ENTRIES)

}

/// Where entry `index` lives: its sector, and its offset within it.

///

/// `None` when the entry would fall outside the array or the arithmetic

/// would overflow — which a header from an untrusted medium can ask for.

pub fn entry_position(&self, index: u32, sector_size: u32) -> Option<(u64, usize)> {

if index >= self.entries() || sector_size == 0 {

return None;

}

let off = (index as u64).checked_mul(self.entry_size as u64)?;

let lba = self.entries_lba.checked_add(off / sector_size as u64)?;

let at = (off % sector_size as u64) as usize;

// An entry never straddles two sectors: the entry size is a power of

// two of at least 128 and sectors are at least 512.

if at + MIN_ENTRY_SIZE as usize > sector_size as usize {

return None;

}

Some((lba, at))

}

/// 0-based slot in the entry array.

pub index: u32,

/// What the partition holds, as a type GUID.

pub type_guid: Guid,

/// The partition's own GUID.

pub guid: Guid,

/// First and last sector it occupies, both inclusive.

pub start_lba: u64,

pub end_lba: u64,

/// Attribute flags — bit 0 is "required", bit 60 read-only.

pub attributes: u64,

/// Decode one entry of the array. `None` for an unused slot — a nil type

/// GUID — or one whose extent makes no sense.

pub fn decode(entry: &[u8], index: u32) -> Option<Partition> {

if entry.len() < MIN_ENTRY_SIZE as usize {

return None;

}

let mut type_guid = [0u8; 16];

type_guid.copy_from_slice(&entry[0..16]);

let type_guid = Guid(type_guid);

if type_guid.is_nil() {

return None;

}

let mut guid = [0u8; 16];

guid.copy_from_slice(&entry[16..32]);

let start_lba = le64(entry, 32);

let end_lba = le64(entry, 40);

if end_lba < start_lba {

return None;

}

Some(Partition {

index,

type_guid,

guid: Guid(guid),

start_lba,

end_lba,

attributes: le64(entry, 48),

})

}

/// Sectors the partition spans.

///

/// Both bounds are inclusive, so this is one more than their difference —

/// saturating, because an entry off untrusted media can name the whole

/// 64-bit range and the count would then not fit in it.

pub fn sectors(&self) -> u64 {

(self.end_lba - self.start_lba).saturating_add(1)

}

/// Whether the type GUID is the one FAT, exFAT and NTFS volumes carry.

pub fn is_basic_data(&self) -> bool {

self.type_guid == BASIC_DATA

}

/// Whether the type GUID is the EFI system partition's, which is FAT.

pub fn is_efi_system(&self) -> bool {

self.type_guid == EFI_SYSTEM

}

/// Whether the type GUID is one a FAT or exFAT volume is normally found

/// under. A volume is still mounted by reading its boot sector, never by

/// trusting this.

pub fn looks_like_fat_family(&self) -> bool {

self.is_basic_data() || self.is_efi_system()

}

/// Whether the read-only attribute (bit 60) is set.

pub fn is_read_only(&self) -> bool {

self.attributes & (1 << 60) != 0

}

/// The partition's name, as UTF-16 code units, into `out`. Returns how

/// many were written; names are at most 36 units and usually empty.

pub fn name_from(entry: &[u8], out: &mut [u16]) -> usize {

let mut n = 0;

for i in 0..36 {

let at = 56 + i * 2;

if at + 2 > entry.len() || n >= out.len() {

break;

}

let unit = le16(entry, at);

if unit == 0 {

break;

}

out[n] = unit;

n += 1;

}

n

}

/// The header this table was read from.

pub header: Header,

/// Whether it came from the backup at the end of the medium rather than

/// the primary at LBA 1.

pub from_backup: bool,

/// Read the table's header from `dev`, primary first and then the backup.

///

/// `scratch` must be at least one sector long; the sector it holds

/// afterwards is not defined. Returns `Ok(None)` when the medium carries

/// no readable GPT — which is not an error, just an answer.

pub fn read<D: SectorDriver>(

dev: &mut D,

scratch: &mut [u8],

) -> Result<Option<Table>, D::Error> {

let ss = dev.sector_size() as usize;

if scratch.len() < ss || ss == 0 || dev.sector_count() < 2 {

return Ok(None);

}

let buf = &mut scratch[..ss];

// The primary header sits at LBA 1, immediately after the protective

// MBR.

dev.read_sectors(1, buf)?;

if let Some(header) = Header::decode(buf) {

return Ok(Some(Table {

header,

from_backup: false,

}));

}

// The backup lives in the last sector. Two copies is the format's

// answer to a torn write, so a reader that never looks at the second

// one has thrown that away.

let last = dev.sector_count() - 1;

dev.read_sectors(last, buf)?;

match Header::decode(buf) {

Some(header) => Ok(Some(Table {

header,

from_backup: true,

})),

None => Ok(None),

}

}

/// Entries this table holds.

pub fn entries(&self) -> u32 {

self.header.entries()

}

/// Read entry `index`. `Ok(None)` for an unused slot, or an index past

/// the end of the array.

///

/// `scratch` must be at least one sector long and is used for the read.

pub fn entry<D: SectorDriver>(

&self,

dev: &mut D,

scratch: &mut [u8],

index: u32,

) -> Result<Option<Partition>, D::Error> {

let ss = dev.sector_size();

let Some((lba, at)) = self.header.entry_position(index, ss) else {

return Ok(None);

};

if scratch.len() < ss as usize || lba >= dev.sector_count() {

return Ok(None);

}

let buf = &mut scratch[..ss as usize];

dev.read_sectors(lba, buf)?;

Ok(Partition::decode(&buf[at..], index))

}

/// What it holds — [`BASIC_DATA`] for FAT and exFAT, [`LINUX_FS`], ….

pub type_guid: Guid,

/// The partition's own GUID. Must not be nil.

pub guid: Guid,

/// First sector.

pub start_lba: u64,

/// Last sector, inclusive.

pub end_lba: u64,

/// Attribute flags — bit 0 "required", bit 60 read-only, ….

pub attributes: u64,

/// Name, up to [`MAX_NAME_UNITS`] UTF-16 code units.

pub name: &'a str,

/// A partition of `type_guid` covering `sectors` sectors from

/// `start_lba`, unnamed and with no attributes.

pub fn new(type_guid: Guid, guid: Guid, start_lba: u64, sectors: u64) -> Self {

Self {

type_guid,

guid,

start_lba,

end_lba: start_lba.saturating_add(sectors).saturating_sub(1),

attributes: 0,

name: "",

}

}

/// The 128-byte entry for this partition, validated.

fn encode(&self, out: &mut [u8]) -> Result<(), Invalid> {

if self.type_guid.is_nil() || self.guid.is_nil() || self.end_lba < self.start_lba {

return Err(Invalid::Entry);

}

out[..ENTRY_SIZE as usize].fill(0);

out[0..16].copy_from_slice(&self.type_guid.0);

out[16..32].copy_from_slice(&self.guid.0);

out[32..40].copy_from_slice(&self.start_lba.to_le_bytes());

out[40..48].copy_from_slice(&self.end_lba.to_le_bytes());

out[48..56].copy_from_slice(&self.attributes.to_le_bytes());

for (n, unit) in self.name.encode_utf16().enumerate() {

if n == MAX_NAME_UNITS {

return Err(Invalid::Name);

}

out[56 + n * 2..58 + n * 2].copy_from_slice(&unit.to_le_bytes());

}

Ok(())

}

/// Sectors each copy of the entry array takes.

pub array_sectors: u64,

/// First sector a partition may use: after the protective MBR, the

/// primary header and its array.

pub first_usable_lba: u64,

/// Last sector a partition may use: before the backup array and header.

pub last_usable_lba: u64,

/// First sector of the backup array.

pub backup_array_lba: u64,

/// The backup header: the medium's last sector.

pub backup_lba: u64,

/// The layout of a [`ENTRY_COUNT`]-entry table on `sector_count` sectors

/// of `sector_size` bytes, or `None` when that leaves no room for a

/// partition.

pub fn new(sector_count: u64, sector_size: u32) -> Option<Layout> {

if sector_size < 512 {

return None;

}

let array_sectors = ((ENTRY_COUNT * ENTRY_SIZE) as u64).div_ceil(sector_size as u64);

let first_usable_lba = 2 + array_sectors;

let backup_lba = sector_count.checked_sub(1)?;

let backup_array_lba = backup_lba.checked_sub(array_sectors)?;

let last_usable_lba = backup_array_lba.checked_sub(1)?;

(last_usable_lba >= first_usable_lba).then_some(Layout {

array_sectors,

first_usable_lba,

last_usable_lba,

backup_array_lba,

backup_lba,

})

}

/// The first usable sector on a 1 MiB boundary — where partitioning

/// tools start the first partition, aligned with flash erase blocks and

/// Advanced Format sectors alike.

pub fn first_aligned_lba(&self, sector_size: u32) -> u64 {

let align = ((1u64 << 20) / sector_size.max(1) as u64).max(1);

self.first_usable_lba.div_ceil(align) * align

}

/// The device failed.

Io(E),

/// The scratch buffer is shorter than a sector, or sectors are smaller

/// than 512 bytes.

ScratchTooSmall,

/// The medium is too small for a table and a partition.

MediumTooSmall,

/// More partitions than the array holds, or an index past it.

NoSuchSlot,

/// The entry at this index has a nil type or partition GUID, or ends

/// before it starts.

InvalidEntry(u32),

/// The entry at this index has a name longer than [`MAX_NAME_UNITS`].

NameTooLong(u32),

/// The entry at this index lies outside the usable sectors.

OutsideUsable(u32),

/// The entries at these indices share sectors.

Overlap(u32, u32),

/// [`set_entry`] found no valid table to change.

NoTable,

/// [`set_entry`] found a table laid out in a way it does not rewrite:

/// more than [`MAX_ENTRIES`] entries, entries that are not a whole

/// fraction of a sector, or an array overlapping the usable sectors.

UnsupportedLayout,

fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {

match self {

WriteError::Io(e) => write!(f, "device error: {e}"),

WriteError::ScratchTooSmall => f.write_str("scratch buffer smaller than a sector"),

WriteError::MediumTooSmall => f.write_str("medium too small for a GPT"),

WriteError::NoSuchSlot => f.write_str("no such GPT entry"),

WriteError::InvalidEntry(i) => write!(f, "GPT entry {i} is invalid"),

WriteError::NameTooLong(i) => write!(f, "GPT entry {i} has a name over 36 units"),

WriteError::OutsideUsable(i) => {

write!(f, "GPT entry {i} lies outside the usable sectors")

}

WriteError::Overlap(a, b) => write!(f, "GPT entries {a} and {b} overlap"),

WriteError::NoTable => f.write_str("no GPT to change"),

WriteError::UnsupportedLayout => f.write_str("GPT layout not supported for rewriting"),

}

}

fn at<E>(self, index: u32) -> WriteError<E> {

match self {

Invalid::Entry => WriteError::InvalidEntry(index),

Invalid::Name => WriteError::NameTooLong(index),

}

}

disk_guid: Guid,

first_usable_lba: u64,

last_usable_lba: u64,

primary_array_lba: u64,

backup_array_lba: u64,

backup_lba: u64,

entry_count: u32,

entry_size: u32,

dev: &mut D,

scratch: &mut [u8],

disk_guid: Guid,

parts: &[NewPartition<'_>],

) -> Result<(), WriteError<D::Error>> {

let ss = check_scratch(dev, scratch)?;

let layout = Layout::new(dev.sector_count(), ss).ok_or(WriteError::MediumTooSmall)?;

if parts.len() > ENTRY_COUNT as usize {

return Err(WriteError::NoSuchSlot);

}

let mut entry = [0u8; ENTRY_SIZE as usize];

for (i, p) in parts.iter().enumerate() {

let i = i as u32;

p.encode(&mut entry).map_err(|e| e.at(i))?;

if p.start_lba < layout.first_usable_lba || p.end_lba > layout.last_usable_lba {

return Err(WriteError::OutsideUsable(i));

}

for (j, q) in parts.iter().enumerate().skip(i as usize + 1) {

if p.start_lba <= q.end_lba && q.start_lba <= p.end_lba {

return Err(WriteError::Overlap(i, j as u32));

}

}

}

let shape = Shape {

disk_guid,

first_usable_lba: layout.first_usable_lba,

last_usable_lba: layout.last_usable_lba,

primary_array_lba: 2,

backup_array_lba: layout.backup_array_lba,

backup_lba: layout.backup_lba,

entry_count: ENTRY_COUNT,

entry_size: ENTRY_SIZE,

};

commit(dev, scratch, &shape, |_, first, sector| {

for (k, out) in sector

.as_chunks_mut::<{ ENTRY_SIZE as usize }>()

.0

.iter_mut()

.enumerate()

{

match parts.get(first as usize + k) {

// Already validated above.

Some(p) => {

let _ = p.encode(out);

}

None => out.fill(0),

}

}

Ok(())

})?;

protective_mbr(dev, scratch, ss)

dev: &mut D,

scratch: &mut [u8],

index: u32,

part: Option<NewPartition<'_>>,

) -> Result<(), WriteError<D::Error>> {

let ss = check_scratch(dev, scratch)?;

let table = Table::read(dev, scratch)

.map_err(WriteError::Io)?

.ok_or(WriteError::NoTable)?;

let h = table.header;

let count = dev.sector_count();

if h.entry_count > MAX_ENTRIES

|| !h.entry_size.is_power_of_two()

|| h.entry_size > ss

|| count < 2

{

return Err(WriteError::UnsupportedLayout);

}

if index >= h.entry_count {

return Err(WriteError::NoSuchSlot);

}

let array_sectors = (h.entry_count as u64 * h.entry_size as u64).div_ceil(ss as u64);

let backup_lba = count - 1;

let backup_array_lba = backup_lba

.checked_sub(array_sectors)

.ok_or(WriteError::UnsupportedLayout)?;

if h.first_usable_lba < 2 + array_sectors || h.last_usable_lba >= backup_array_lba {

return Err(WriteError::UnsupportedLayout);

}

// Validate against every other live entry before touching the medium.

let mut entry = [0u8; ENTRY_SIZE as usize];

if let Some(p) = &part {

p.encode(&mut entry).map_err(|e| e.at(index))?;

if p.start_lba < h.first_usable_lba || p.end_lba > h.last_usable_lba {

return Err(WriteError::OutsideUsable(index));

}

for j in 0..h.entry_count {

if j == index {

continue;

}

if let Some(q) = table.entry(dev, scratch, j).map_err(WriteError::Io)?

&& p.start_lba <= q.end_lba

&& q.start_lba <= p.end_lba

{

return Err(WriteError::Overlap(index, j));

}

}

}

let source = h.entries_lba;

// The array the header points at has to be on the medium to be read

// back — a header off untrusted media can point anywhere.

if source

.checked_add(array_sectors)

.is_none_or(|end| end > count)

{

return Err(WriteError::UnsupportedLayout);

}

// Regenerating a copy over itself is safe sector by sector; over a range

// that only partly overlaps its source (a backup array on a medium that

// has since grown by less than the array) it is not.

let partly_overlaps = |dest: u64| {

dest != source && dest < source + array_sectors && source < dest + array_sectors

};

if partly_overlaps(2) || partly_overlaps(backup_array_lba) {

return Err(WriteError::UnsupportedLayout);

}

let per_sector = ss / h.entry_size;

let entry_size = h.entry_size as usize;

let shape = Shape {

disk_guid: h.disk_guid,

first_usable_lba: h.first_usable_lba,

last_usable_lba: h.last_usable_lba,

primary_array_lba: 2,

backup_array_lba,

backup_lba,

entry_count: h.entry_count,

entry_size: h.entry_size,

};

// The array is regenerated from the copy the header was read from, a

// sector at a time, with the one entry patched in on the way. Each

// source sector is read before its destination is written, so

// rewriting a copy over itself is safe, and patching a sector that

// already carries the change is harmless.

commit(dev, scratch, &shape, |dev, first, sector| {

let lba = source + (first / per_sector) as u64;

if lba < count {

dev.read_sectors(lba, sector)?;

} else {

sector.fill(0);

}

if (first..first + per_sector).contains(&index) {

let at = (index - first) as usize * entry_size;

let slot = &mut sector[at..at + entry_size];

match &part {

// Already validated above.

Some(p) => {

let _ = p.encode(slot);

}

None => slot.fill(0),

}

}

Ok(())

})?;

// A table whose protective MBR is already there (or is a hybrid one a

// tool put there on purpose) keeps it.

Ok(())

let ss = check_scratch(dev, scratch)? as usize;

let count = dev.sector_count();

if count < 2 {

return Ok(());

}

let buf = &mut scratch[..ss];

buf.fill(0);

dev.write_sectors(1, buf).map_err(WriteError::Io)?;

dev.write_sectors(count - 1, buf).map_err(WriteError::Io)?;

dev.flush().map_err(WriteError::Io)

let ss = dev.sector_size();

if ss < 512 || !ss.is_power_of_two() || scratch.len() < ss as usize {

return Err(WriteError::ScratchTooSmall);

}

Ok(ss)

dev: &mut D,

scratch: &mut [u8],

shape: &Shape,

mut fill: impl FnMut(&mut D, u32, &mut [u8]) -> Result<(), D::Error>,

) -> Result<(), WriteError<D::Error>> {

let ss = dev.sector_size() as usize;

let buf = &mut scratch[..ss];

let per_sector = ss as u32 / shape.entry_size;

let array_bytes = shape.entry_count as u64 * shape.entry_size as u64;

let sectors = array_bytes.div_ceil(ss as u64);

let mut crc = 0;

for (copy, (array_lba, my_lba, alternate_lba)) in [

(shape.backup_array_lba, shape.backup_lba, 1),

(shape.primary_array_lba, 1, shape.backup_lba),

]

.into_iter()

.enumerate()

{

let mut running = 0;

for k in 0..sectors {

fill(dev, k as u32 * per_sector, buf).map_err(WriteError::Io)?;

// Past the last entry the sector is padding, and not part of the

// array the CRC covers.

let used = (array_bytes - k * ss as u64).min(ss as u64) as usize;

buf[used..].fill(0);

running = crate::crc::crc32_small_append(running, &buf[..used]);

dev.write_sectors(array_lba + k, buf)

.map_err(WriteError::Io)?;

}

if copy == 0 {

crc = running;

}

header(buf, shape, my_lba, alternate_lba, array_lba, crc);

dev.write_sectors(my_lba, buf).map_err(WriteError::Io)?;

}

dev.flush().map_err(WriteError::Io)

sector.fill(0);

sector[0..8].copy_from_slice(SIGNATURE);

sector[8..12].copy_from_slice(&REVISION.to_le_bytes());

sector[12..16].copy_from_slice(&MIN_HEADER_SIZE.to_le_bytes());

sector[24..32].copy_from_slice(&my.to_le_bytes());

sector[32..40].copy_from_slice(&alternate.to_le_bytes());

sector[40..48].copy_from_slice(&shape.first_usable_lba.to_le_bytes());

sector[48..56].copy_from_slice(&shape.last_usable_lba.to_le_bytes());

sector[56..72].copy_from_slice(&shape.disk_guid.0);

sector[72..80].copy_from_slice(&array.to_le_bytes());

sector[80..84].copy_from_slice(&shape.entry_count.to_le_bytes());

sector[84..88].copy_from_slice(&shape.entry_size.to_le_bytes());

sector[88..92].copy_from_slice(&crc.to_le_bytes());

let own = crate::crc::crc32_small(&sector[..MIN_HEADER_SIZE as usize]);

sector[16..20].copy_from_slice(&own.to_le_bytes());

dev: &mut D,

scratch: &mut [u8],

ss: u32,

) -> Result<(), WriteError<D::Error>> {

let buf = &mut scratch[..ss as usize];