GPT partition-table parsing for the ra8_fs mount path. More...

#include <stddef.h>
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_fs.h"
#include "ra8_fs_fat_internal.h"

Include dependency graph for ra8_fs_fat_gpt.c:

Functions
static uint64_t	internal_gpt_entry_first_lba (const uint8_t *entry)
	Extract a usable first-LBA from one GPT partition entry.
static uint32_t	internal_gpt_entry_is_basic_data (const uint8_t *entry)
	Test whether a GPT entry's type GUID is Microsoft Basic Data.
static void	internal_gpt_note_entry (const uint8_t entry, uint64_t basic_lba, uint64_t *any_lba)
	Fold one GPT entry into the candidate base-LBA bookkeeping.
static ra8_err_t	internal_gpt_scan_entries (const ra8_fs_mount_t m, uint64_t entry_lba, uint32_t count, uint64_t out_base)
	Read the GPT entry array sector-by-sector and pick a base LBA.
static ra8_err_t	internal_gpt_read_geom (const ra8_fs_mount_t m, uint64_t out_entry_lba, uint32_t *out_count)
	Read and validate the GPT header, returning the entry-array geometry.
ra8_err_t	priv_gpt_locate_volume (const ra8_fs_mount_t m, uint64_t out_base)
	Locate the first mountable partition on a GPT disk (auto-select).
static ra8_err_t	internal_gpt_entry_select (const uint8_t entry, uint64_t out_base)
	Extract the first LBA of one explicitly selected GPT entry.
ra8_err_t	priv_gpt_locate_partition (const ra8_fs_mount_t m, uint8_t index, uint64_t out_base)
	Locate a GPT partition chosen by entry-array index.

Variables
static const uint8_t	s_gpt_signature [k_gpt_sig_len]
	GPT header signature ("EFI PART", UEFI spec 2.10 table 5.5).
static const uint8_t	s_gpt_guid_basic_data [k_gpt_guid_len]
	Microsoft Basic Data type GUID, on-disk byte order (EBD0A0A2-B9E5-4433-87C0-68B6B72699C7).

Detailed Description

GPT partition-table parsing for the ra8_fs mount path.

The GUID Partition Table half of volume location (UEFI spec 2.10 ch 5), split out of ra8_fs_fat_mount.c when 64-bit LBAs (#683) pushed that file past the source-size cap: header validation, the bounded entry-array walk, Basic-Data preference, and the two locate entry points the mount path calls – auto-select (priv_gpt_locate_volume) and by explicit index (priv_gpt_locate_partition). Entry-array and entry LBAs are read as the full 64-bit fields they are, so partitions past 2 TiB select and mount.

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since: 0.1.0

Definition in file ra8_fs_fat_gpt.c.

Function Documentation

◆ internal_gpt_entry_first_lba()

uint64_t internal_gpt_entry_first_lba ( const uint8_t * entry )

static

Extract a usable first-LBA from one GPT partition entry.

An entry is usable when its type GUID is non-zero (the slot is allocated) and its first LBA is non-zero. The LBA is the entry's full 64-bit field: partitions past the 32-bit-LBA reach (2 TiB at 512-byte sectors) are addressable now that the backend interface is 64-bit (#683).

Parameters

[in] entry One 128-byte partition entry.

Returns: The entry's first LBA, or 0 when the entry is unusable.

Return values

0	Unused slot or zero first-LBA.

Precondition: entry is non-NULL and holds k_gpt_entry_bytes bytes.; entry came from the GPT partition entry array.

Postcondition: No state modified.; entry is unmodified.

Note: Pure function.

Since: 0.1.0

Definition at line 78 of file ra8_fs_fat_gpt.c.

References k_gpt_entry_off_first_lba, k_gpt_guid_len, and priv_rd64().

Referenced by internal_gpt_note_entry().

◆ internal_gpt_entry_is_basic_data()

uint32_t internal_gpt_entry_is_basic_data ( const uint8_t * entry )

static

Test whether a GPT entry's type GUID is Microsoft Basic Data.

Basic Data is where FAT/exFAT user volumes live on a GPT disk; other common entries (EFI System Partition, Microsoft Reserved) do not carry the volume this layer should mount.

Parameters

[in] entry One 128-byte partition entry.

Returns: 1 when the type GUID matches, else 0.

Return values

1	The entry is a Basic Data partition.

Precondition: entry is non-NULL and holds k_gpt_entry_bytes bytes.; entry came from the GPT partition entry array.

Postcondition: No state modified.; entry is unmodified.

Note: Pure function.

Since: 0.1.0

Definition at line 110 of file ra8_fs_fat_gpt.c.

References k_gpt_guid_len, and s_gpt_guid_basic_data.

Referenced by internal_gpt_note_entry().

◆ internal_gpt_entry_select()

ra8_err_t internal_gpt_entry_select	(	const uint8_t *	entry,
		uint64_t *	out_base )

static

Extract the first LBA of one explicitly selected GPT entry.

The indexed counterpart of ::priv_gpt_entry_first_lba: rather than skipping an unusable entry it reports why. An all-zero type GUID is an empty slot; a zero first LBA is a malformed allocated entry. The full 64-bit LBA is honoured – entries past 2 TiB select cleanly now that the backend addresses 64-bit LBAs (#683).

Parameters

[in]	entry	One 128-byte partition entry.
[out]	out_base	Receives the entry's first LBA on success.

Returns: Error code.

Return values

k_ra8_ok	`out_base` holds the entry's first LBA.
k_ra8_err_not_found	The entry is an empty (zero-GUID) slot.
k_ra8_err_validation_failed	Allocated entry with a zero first LBA.

Precondition: entry is non-NULL and holds k_gpt_entry_bytes bytes.; out_base is non-NULL.

Postcondition: No state modified.; entry is unmodified.

Note: Pure function.

Since: 0.1.0

Definition at line 297 of file ra8_fs_fat_gpt.c.

References k_gpt_entry_off_first_lba, k_gpt_guid_len, k_ra8_err_not_found, k_ra8_err_validation_failed, k_ra8_ok, and priv_rd64().

Referenced by priv_gpt_locate_partition().

◆ internal_gpt_note_entry()

void internal_gpt_note_entry	(	const uint8_t *	entry,
		uint64_t *	basic_lba,
		uint64_t *	any_lba )

static

Fold one GPT entry into the candidate base-LBA bookkeeping.

Prefers the first Microsoft Basic Data entry (the conventional home of FAT/exFAT volumes); the first allocated entry of any other type is kept as a fallback. Unusable entries (see ::priv_gpt_entry_first_lba) are ignored.

Parameters

[in]	entry	One 128-byte partition entry.
[in,out]	basic_lba	First Basic Data candidate (0 = none yet).
[in,out]	any_lba	First allocated-entry candidate (0 = none yet).

Precondition: entry is non-NULL and holds k_gpt_entry_bytes bytes.; basic_lba and any_lba are non-NULL.

Postcondition: Candidates are updated only from 0 (first match wins).; entry is unmodified.

Note: Pure bookkeeping; no I/O.

Since: 0.1.0

Definition at line 139 of file ra8_fs_fat_gpt.c.

References internal_gpt_entry_first_lba(), and internal_gpt_entry_is_basic_data().

Referenced by internal_gpt_scan_entries().

◆ internal_gpt_read_geom()

ra8_err_t internal_gpt_read_geom	(	const ra8_fs_mount_t *	m,
		uint64_t *	out_entry_lba,
		uint32_t *	out_count )

static

Read and validate the GPT header, returning the entry-array geometry.

Reads the "EFI PART" header at LBA 1, checks the signature, rejects an entry-array LBA above 32 bits or a non-standard entry size, and clamps the entry count to the bounded scan cap. Shared by the auto locator (priv_gpt_locate_volume) and the indexed one (priv_gpt_locate_partition) so the two agree byte-for-byte on what a usable GPT is.

Parameters

[in]	m	Mount whose backend supplies the sectors.
[out]	out_entry_lba	First LBA of the partition entry array.
[out]	out_count	Entry count, clamped to k_gpt_entry_scan_max.

Returns: Error code.

Return values

k_ra8_ok	Geometry read and validated.
k_ra8_err_validation_failed	No "EFI PART" header, or entry_lba is 0.
k_ra8_err_not_supported	Non-standard entry size or 64-bit array LBA.
k_ra8_err_*	Backend read failure.

Precondition: m->partition_base_lba is still 0 (reads are absolute).; out_entry_lba and out_count are non-NULL.

Postcondition: On k_ra8_ok both outputs are set; g_fs_scratch holds the GPT header.; On failure the outputs are unchanged.

Note: Not thread-safe – uses module-level scratch.

Since: 0.1.0

Definition at line 234 of file ra8_fs_fat_gpt.c.

References g_fs_scratch, k_gpt_entry_bytes, k_gpt_entry_scan_max, k_gpt_header_lba, k_gpt_off_entry_count, k_gpt_off_entry_lba, k_gpt_off_entry_size, k_gpt_sig_len, k_ra8_err_not_supported, k_ra8_err_validation_failed, k_ra8_ok, priv_rd32(), priv_rd64(), priv_read_sector(), and s_gpt_signature.

Referenced by priv_gpt_locate_partition(), and priv_gpt_locate_volume().

◆ internal_gpt_scan_entries()

ra8_err_t internal_gpt_scan_entries	(	const ra8_fs_mount_t *	m,
		uint64_t	entry_lba,
		uint32_t	count,
		uint64_t *	out_base )

static

Read the GPT entry array sector-by-sector and pick a base LBA.

Reads each entry sector once and feeds every 128-byte entry to ::priv_gpt_note_entry; the Basic Data candidate wins over the first allocated entry of any other type.

Parameters

[in]	m	Mount whose backend supplies the sectors.
[in]	entry_lba	First LBA of the partition entry array.
[in]	count	Number of entries to scan (already clamped).
[out]	out_base	Receives the chosen partition's first LBA.

Returns: Error code.

Return values

k_ra8_ok	A candidate partition was found.
k_ra8_err_not_found	No allocated entry was usable.
k_ra8_err_*	Backend read failure.

Precondition: m->partition_base_lba is still 0 (reads are absolute).; out_base is non-NULL.

Postcondition: On k_ra8_ok out_base holds a non-zero LBA.; g_fs_scratch holds the last entry sector read.

Note: Not thread-safe – uses module-level scratch.

Since: 0.1.0

Definition at line 178 of file ra8_fs_fat_gpt.c.

References g_fs_scratch, internal_gpt_note_entry(), k_gpt_entry_bytes, k_ra8_err_not_found, k_ra8_ok, priv_bps(), and priv_read_sector().

Referenced by priv_gpt_locate_volume().

◆ priv_gpt_locate_partition()

ra8_err_t priv_gpt_locate_partition	(	const ra8_fs_mount_t *	m,
		uint8_t	index,
		uint64_t *	out_base )

Locate a GPT partition chosen by entry-array index.

Reads the header geometry via ::priv_gpt_read_geom, bounds-checks index against the (clamped) entry count, reads the sector holding that entry, and validates it via ::priv_gpt_entry_select.

Parameters

[in,out]	m	Mount whose backend supplies the sectors.
[in]	index	Zero-based GPT entry-array index.
[out]	out_base	Receives the selected partition's first LBA.

Returns: Error code.

Return values

k_ra8_ok	`out_base` holds the volume base.
k_ra8_err_out_of_range	`index` is past the entry count.
k_ra8_err_not_found	The selected entry is empty.
k_ra8_err_not_supported	Entry-array geometry, or an entry LBA, this backend cannot address.
k_ra8_err_validation_failed	No header, or a malformed entry.
k_ra8_err_*	Backend read failure.

Precondition: m->partition_base_lba is still 0 (reads are absolute).; out_base is non-NULL.

Postcondition: On k_ra8_ok out_base holds a non-zero LBA.; g_fs_scratch is overwritten (callers must re-read their sector).

Note: Not thread-safe – uses module-level scratch.

Since: 0.1.0

Definition at line 317 of file ra8_fs_fat_gpt.c.

References g_fs_scratch, internal_gpt_entry_select(), internal_gpt_read_geom(), k_gpt_entry_bytes, k_ra8_err_out_of_range, k_ra8_ok, priv_bps(), and priv_read_sector().

Referenced by internal_locate_indexed().

◆ priv_gpt_locate_volume()

ra8_err_t priv_gpt_locate_volume	(	const ra8_fs_mount_t *	m,
		uint64_t *	out_base )

Locate the first mountable partition on a GPT disk (auto-select).

Reads the header geometry via ::priv_gpt_read_geom, then scans the entries via ::priv_gpt_scan_entries (Microsoft Basic Data preferred, else the first allocated entry of any type).

Parameters

[in,out]	m	Mount whose backend supplies the sectors.
[out]	out_base	Receives the chosen partition's first LBA.

Returns: Error code.

Return values

k_ra8_ok	`out_base` holds the volume base.
k_ra8_err_validation_failed	No "EFI PART" header at LBA 1.
k_ra8_err_not_supported	Non-standard entry size or array LBA.
k_ra8_err_*	Backend read failure or no entry found.

Precondition: m->partition_base_lba is still 0 (reads are absolute).; out_base is non-NULL.

Postcondition: On k_ra8_ok out_base holds a non-zero LBA.; g_fs_scratch is overwritten (callers must re-read their sector).

Note: Not thread-safe – uses module-level scratch.

Since: 0.1.0

Definition at line 263 of file ra8_fs_fat_gpt.c.

References internal_gpt_read_geom(), internal_gpt_scan_entries(), and k_ra8_ok.

Referenced by internal_read_boot_sector().

Variable Documentation

◆ s_gpt_guid_basic_data

const uint8_t s_gpt_guid_basic_data[k_gpt_guid_len]

static

Initial value:

                                           = {
  0xA2U,
  0xA0U,
  0xD0U,
  0xEBU,
  0xE5U,
  0xB9U,
  0x33U,
  0x44U,
  0x87U,
  0xC0U,
  0x68U,
  0xB6U,
  0xB7U,
  0x26U,
  0x99U,
  0xC7U,
}

Microsoft Basic Data type GUID, on-disk byte order (EBD0A0A2-B9E5-4433-87C0-68B6B72699C7).

Definition at line 40 of file ra8_fs_fat_gpt.c.

Referenced by internal_gpt_entry_is_basic_data().

◆ s_gpt_signature

const uint8_t s_gpt_signature[k_gpt_sig_len]

static

Initial value:

                                     = {
  0x45U,
  0x46U,
  0x49U,
  0x20U,
  0x50U,
  0x41U,
  0x52U,
  0x54U,
}

GPT header signature ("EFI PART", UEFI spec 2.10 table 5.5).

Definition at line 27 of file ra8_fs_fat_gpt.c.

Referenced by internal_gpt_read_geom().

Functions

Variables

Detailed Description

Function Documentation

◆ internal_gpt_entry_first_lba()

◆ internal_gpt_entry_is_basic_data()

◆ internal_gpt_entry_select()

◆ internal_gpt_note_entry()

◆ internal_gpt_read_geom()

◆ internal_gpt_scan_entries()

◆ priv_gpt_locate_partition()

◆ priv_gpt_locate_volume()

Variable Documentation

◆ s_gpt_guid_basic_data

◆ s_gpt_signature