The little-endian byte codec and the runtime sector-geometry reads. More...

#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_fs_fat_types_internal.h"

Include dependency graph for ra8_fs_fat_bytes_internal.h:

This graph shows which files directly or indirectly include this file:

Functions
uint8_t *	priv_sec_walk (void)
	The WALK-role sector buffer (directory scans and entry RMW).
uint8_t *	priv_sec_fat (void)
	The FAT-role sector buffer (priv_fat_get and the FAT setters).
uint8_t *	priv_sec_fat2 (void)
	The FAT2-role sector buffer (the FAT12 straddle's second sector).
uint8_t *	priv_sec_io (void)
	The IO-role sector buffer (leaf data / bitmap sector transfers).
void	priv_byte_fill (uint8_t *dst, uint8_t value, uint32_t n)
	Fill `n` bytes of `dst` with `value`.
uint16_t	priv_rd16 (const uint8_t *p)
	Decode a little-endian uint16_t from a byte buffer.
uint32_t	priv_rd32 (const uint8_t *p)
	Decode a little-endian uint32_t from a byte buffer.
uint64_t	priv_rd64 (const uint8_t *p)
	Decode a little-endian uint64_t from a byte buffer.
uint32_t	priv_bps (const ra8_fs_mount_t *m)
	One mounted volume's sector size in bytes.
uint32_t	priv_cluster_bytes (const ra8_fs_mount_t *m)
	One mounted volume's cluster size in bytes.
uint32_t	priv_dir_eps (const ra8_fs_mount_t *m)
	Directory entries per sector on one mounted volume.
void	priv_wr16 (uint8_t *p, uint16_t v)
	Encode a little-endian uint16_t into a byte buffer.
void	priv_wr32 (uint8_t *p, uint32_t v)
	Encode a little-endian uint32_t into a byte buffer.
void	priv_wr64 (uint8_t *p, uint64_t v)
	Encode a uint64_t into a byte buffer, little-endian.

Variables
const uint8_t	k_zero_sector [k_ra8_fs_sector_max]
	One whole sector of zero bytes, in read-only storage.

Detailed Description

The little-endian byte codec and the runtime sector-geometry reads.

Two small vocabularies every FAT/exFAT translation unit shares, split out of the alphabetical prototype headers when the 64-bit widening (#676, #683) pushed those against the source-size cap:

the little-endian field codec (priv_rd16/32/64, priv_wr16/32/64) the on-disk structures are read and written through;
the runtime geometry accessors (priv_bps, priv_cluster_bytes, priv_dir_eps) that replaced the old compile-time 512-byte-sector constants – the sector size is a property of the MEDIUM now.

Aggregated by the ra8_fs_fat_internal.h umbrella like every other themed sub-header.

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

Since: 0.1.0

Definition in file ra8_fs_fat_bytes_internal.h.

Function Documentation

◆ priv_bps()

uint32_t priv_bps ( const ra8_fs_mount_t * m )

One mounted volume's sector size in bytes.

The runtime m->bytes_per_sector, returned through one accessor so every arithmetic site reads the same way. A power of two in k_ra8_fs_sector_min..k_ra8_fs_sector_max on any mounted volume.

Parameters

[in] m Mounted volume.

Returns: Sector size in bytes.

Return values

512..4096 The volume's sector size.

Precondition: m is non-NULL and parsed (bytes_per_sector populated).; The mount validated the size against the backend's block size.

Postcondition: No state modified.; Result is a power of two.

Note: Pure read; trivially thread-safe.

Since: 0.1.0

Definition at line 84 of file ra8_fs_fat.c.

References ra8_fs_mount_t::bytes_per_sector.

Referenced by internal_compute_geometry(), internal_dir_cluster_init(), internal_dir_walk_init_root(), internal_exchk_bitmap_pass(), internal_exchk_set(), internal_exfat_bitmap_window(), internal_exfat_read_entry(), internal_exfat_slice_at(), internal_fat12_set_one(), internal_fat_dir_scan_sector(), internal_gpt_scan_entries(), internal_read_one_chunk(), internal_space_exfat_free(), internal_trunc_zero_span(), internal_write_stream(), priv_exfat_bitmap_clear(), priv_exfat_bitmap_mark(), priv_exfat_bitmap_test(), priv_exfat_next_entry(), priv_exfat_seal_cluster(), priv_exfat_write_dir_set(), priv_fat_get(), priv_fat_sector_read(), priv_fat_sector_wrote(), priv_fat_set(), and priv_gpt_locate_partition().

◆ priv_byte_fill()

void priv_byte_fill	(	uint8_t *	dst,
		uint8_t	value,
		uint32_t	n )

Fill n bytes of dst with value.

The store-side sibling of priv_byte_copy, for zeroing an arena-taken sector before constructing content in it (the arena hands back whatever the previous user left, where the old stack buffers arrived zero-initialised).

Parameters

[out]	dst	Destination buffer.
[in]	value	Byte value to store.
[in]	n	Number of bytes to fill.

Precondition: dst is non-NULL and holds at least n writable bytes.; n was bounds-checked by the caller.

Postcondition: dst[0..n) all equal value.; No other state is modified.

Note: Pure store; trivially thread-safe on distinct buffers.

Since: 0.1.0

Definition at line 102 of file ra8_fs_fat.c.

Referenced by internal_dir_cluster_init(), and priv_fmt_emit_volume().

◆ priv_cluster_bytes()

uint32_t priv_cluster_bytes ( const ra8_fs_mount_t * m )

One mounted volume's cluster size in bytes.

sectors_per_cluster * bytes_per_sector. Fits 32 bits on every legal volume: exFAT caps a cluster at 32 MiB, FAT at 64 sectors of 4096 bytes.

Parameters

[in] m Mounted volume.

Returns: Cluster size in bytes.

Return values

512..33554432 The volume's cluster size.

Precondition: m is non-NULL and parsed (geometry fields populated).; The volume's cluster geometry is legal for its type.

Postcondition: No state modified.; Result is a power of two.

Note: Pure read; trivially thread-safe.

Since: 0.1.0

Definition at line 90 of file ra8_fs_fat.c.

References ra8_fs_mount_t::bytes_per_sector, and ra8_fs_mount_t::sectors_per_cluster.

Referenced by internal_exchk_set_clusters(), internal_exchk_system_run(), internal_exfat_build_dir_set(), internal_exfat_slice_at(), internal_exfat_space_in_cluster(), internal_exfat_survey_alloc(), internal_exfat_trunc(), internal_fat_trunc(), internal_read_one_chunk(), internal_space_locked(), internal_write_stream(), priv_exfat_dir_from_set(), priv_exfat_free_clusters(), priv_exfat_grow_dir(), and priv_exfat_next_entry().

◆ priv_dir_eps()

uint32_t priv_dir_eps ( const ra8_fs_mount_t * m )

Directory entries per sector on one mounted volume.

bytes_per_sector / 32 – 16 on a 512-byte volume, 128 on 4Kn. Replaces the old compile-time constant, which baked 512 in.

Parameters

[in] m Mounted volume.

Returns: 32-byte directory entries per sector.

Return values

16..128 Entries per sector.

Precondition: m is non-NULL and parsed (bytes_per_sector populated).; bytes_per_sector is a multiple of 32.

Postcondition: No state modified.; Result times 32 equals the sector size.

Note: Pure read; trivially thread-safe.

Since: 0.1.0

Definition at line 96 of file ra8_fs_fat.c.

References ra8_fs_mount_t::bytes_per_sector, and k_ra8_fs_dir_entry_bytes.

Referenced by internal_dir_collect_chain(), internal_dir_find_long_sector(), internal_fat_find_free_root(), internal_fat_find_vol_id(), internal_fat_scan_fixed_root(), internal_fat_visit_sector(), internal_listdir_visit_sector(), internal_rmdir_scan_sector(), internal_slot_advance(), priv_dir_find(), and priv_dir_find_free_run().

◆ priv_rd16()

uint16_t priv_rd16 ( const uint8_t * p )

Decode a little-endian uint16_t from a byte buffer.

Trivial little-endian byte assembler. Avoids memcpy so clang-tidy's strict-alias check stays happy.

Parameters

[in] p Pointer to two bytes.

Returns: The decoded value.

Return values

0..UINT16_MAX Value assembled from p[0] and p[1].

Precondition: p is non-NULL and points to at least 2 readable bytes.; Caller has bounds-checked p.

Postcondition: No state modified.; Result equals p[0] | (p[1] << 8).

Note: Pure function; trivially thread-safe.

Since: 0.1.0

Definition at line 42 of file ra8_fs_fat.c.

References k_shift_byte.

Referenced by internal_exchk_extract_name(), internal_exchk_verify_set(), internal_exfat_gather_name(), internal_fat_fsinfo(), internal_fsinfo_locate(), internal_stat_fat_times(), priv_entry_first_cluster(), priv_exfat_name_chunk_eq(), priv_exfat_upcase_unit(), priv_fat_get(), and priv_parse_bpb_into_mount().

◆ priv_rd32()

uint32_t priv_rd32 ( const uint8_t * p )

Decode a little-endian uint32_t from a byte buffer.

Trivial little-endian byte assembler for 4 bytes.

Parameters

[in] p Pointer to four bytes.

Returns: The decoded value.

Return values

0..UINT32_MAX Value assembled from p[0..3].

Precondition: p is non-NULL and points to at least 4 readable bytes.; Caller has bounds-checked p.

Postcondition: No state modified.; Result equals p[0] | (p[1]<<8) | (p[2]<<16) | (p[3]<<24).

Note: Pure function; trivially thread-safe.

Since: 0.1.0

Definition at line 48 of file ra8_fs_fat.c.

References k_shift_byte, k_shift_three_bytes, and k_shift_two_bytes.

Referenced by internal_entry_to_stat(), internal_exchk_set_clusters(), internal_exchk_system_run(), internal_exfat_enter(), internal_exfat_open_found(), internal_exfat_parse(), internal_exfat_rmdir_locate(), internal_exfat_seed_read(), internal_fat32_set_one(), internal_fat_dir_scan_sector(), internal_fat_fsinfo(), internal_fsinfo_signatures_ok(), internal_gpt_read_geom(), internal_listdir_visit_sector(), internal_mbr_part0_lba(), internal_mbr_select_entry(), internal_open_existing(), internal_stat_exfat(), internal_stat_exfat_times(), priv_exfat_dir_from_set(), priv_exfat_find_bitmap(), priv_exfat_free_clusters(), priv_exfat_upcase_verify(), priv_fat_get(), priv_fsinfo_seed(), priv_parse_bpb_into_mount(), and priv_rd64().

◆ priv_rd64()

uint64_t priv_rd64 ( const uint8_t * p )

Decode a little-endian uint64_t from a byte buffer.

Trivial little-endian byte assembler for 8 bytes: the width of exFAT's DataLength / ValidDataLength and of a GPT entry's LBAs.

Parameters

[in] p Pointer to eight bytes.

Returns: The decoded value.

Return values

0..UINT64_MAX Value assembled from p[0..7].

Precondition: p is non-NULL and points to at least 8 readable bytes.; Caller has bounds-checked p.

Postcondition: No state modified.; Result equals the little-endian 64-bit value at p.

Note: Pure function; trivially thread-safe.

Since: 0.1.0

Definition at line 55 of file ra8_fs_fat.c.

References k_shift_word32, and priv_rd32().

Referenced by internal_exchk_set_clusters(), internal_exchk_system_run(), internal_exfat_list_emit(), internal_exfat_open_found(), internal_exfat_parse(), internal_exfat_seed_read(), internal_gpt_entry_first_lba(), internal_gpt_entry_select(), internal_gpt_read_geom(), internal_stat_exfat(), priv_exfat_dir_from_set(), and priv_exfat_free_clusters().

◆ priv_sec_fat()

uint8_t * priv_sec_fat ( void )

The FAT-role sector buffer (priv_fat_get and the FAT setters).

See the arena discipline above.

Returns: Pointer to the FAT-role sector buffer.

Return values

non-NULL Always.

Precondition: The caller holds the library lock (or none is installed).; No other FAT-role buffer is live in the current call chain.

Postcondition: The buffer contents are whatever the previous user left.; No other state is modified.

Note: Not thread-safe; the adapter is single-threaded by contract.

Since: 0.1.0

Definition at line 66 of file ra8_fs_fat_mount.c.

References k_fs_sec_role_fat, and s_sec_arena.

Referenced by internal_exfat_fat_set_one(), internal_fat12_set_one(), internal_fat16_set_one(), internal_fat32_set_one(), and priv_fat_get().

◆ priv_sec_fat2()

uint8_t * priv_sec_fat2 ( void )

The FAT2-role sector buffer (the FAT12 straddle's second sector).

See the arena discipline above.

Returns: Pointer to the FAT2-role sector buffer.

Return values

non-NULL Always.

Precondition: The caller holds the library lock (or none is installed).; Live only alongside the FAT-role buffer, in the straddle helpers.

Postcondition: The buffer contents are whatever the previous user left.; No other state is modified.

Note: Not thread-safe; the adapter is single-threaded by contract.

Since: 0.1.0

Definition at line 72 of file ra8_fs_fat_mount.c.

References k_fs_sec_role_fat2, and s_sec_arena.

Referenced by internal_fat12_set_one(), and priv_fat_get().

◆ priv_sec_io()

uint8_t * priv_sec_io ( void )

The IO-role sector buffer (leaf data / bitmap sector transfers).

See the arena discipline above.

Returns: Pointer to the IO-role sector buffer.

Return values

non-NULL Always.

Precondition: The caller holds the library lock (or none is installed).; No other IO-role buffer is live in the current call chain.

Postcondition: The buffer contents are whatever the previous user left.; No other state is modified.

Note: Not thread-safe; the adapter is single-threaded by contract.

Since: 0.1.0

Definition at line 78 of file ra8_fs_fat_mount.c.

References k_fs_sec_role_io, and s_sec_arena.

Referenced by internal_exchk_bitmap_pass(), internal_exfat_bitmap_window(), internal_exfat_read_entry(), internal_read_one_chunk(), internal_space_exfat_free(), internal_trunc_zero_span(), priv_exfat_bitmap_clear(), priv_exfat_bitmap_mark(), priv_exfat_bitmap_test(), priv_exfat_next_entry(), priv_exfat_seal_cluster(), priv_exfat_write_dir_set(), and priv_write_into_sector().

◆ priv_sec_walk()

uint8_t * priv_sec_walk ( void )

The WALK-role sector buffer (directory scans and entry RMW).

See the arena discipline above. The pointer is to static storage of k_ra8_fs_sector_max bytes, valid for the whole program; only LIVENESS is scoped, by the role rules.

Returns: Pointer to the walk-role sector buffer.

Return values

non-NULL Always.

Precondition: The caller holds the library lock (or none is installed).; No other walk-role buffer is live in the current call chain.

Postcondition: The buffer contents are whatever the previous user left.; No other state is modified.

Note: Not thread-safe; the adapter is single-threaded by contract.

Since: 0.1.0

Definition at line 60 of file ra8_fs_fat_mount.c.

References k_fs_sec_role_walk, and s_sec_arena.

Referenced by internal_close_stamp(), internal_dir_cluster_init(), internal_dir_collect_chain(), internal_dir_erase_positions(), internal_dir_is_empty(), internal_fat_boot_set_label(), internal_fat_del_entry(), internal_fat_dir_next(), internal_fat_find_free_root(), internal_fat_find_vol_id(), internal_fat_fsinfo(), internal_fat_put_vol_id(), internal_fat_scan_cluster_dir(), internal_fat_scan_fixed_root(), internal_fat_trunc_commit(), internal_fsinfo_locate(), internal_get_label_fat(), internal_setattr_fat(), internal_truncate_existing(), internal_utime_fat(), priv_dir_commit(), priv_dir_find(), priv_dir_find_free_run(), priv_dir_find_long(), priv_fmt_emit_volume(), priv_fsinfo_flush(), and priv_fsinfo_seed().

◆ priv_wr16()

void priv_wr16	(	uint8_t *	p,
		uint16_t	v )

Encode a little-endian uint16_t into a byte buffer.

Inverse of priv_rd16. Writes the low byte first.

Parameters

[out]	p	Pointer to two writable bytes.
[in]	v	Value to encode.

Precondition: p is non-NULL and points to at least 2 writable bytes.; Caller has bounds-checked p.

Postcondition: p[0] and p[1] reflect the little-endian encoding of v.; No other state modified.

Note: Trivially thread-safe; not reentrant against the same buffer.

Since: 0.1.0

Definition at line 61 of file ra8_fs_fat.c.

References k_byte_mask, and k_shift_byte.

Referenced by internal_exfat_build_dir_set(), internal_exfat_build_rename_set(), internal_exfat_build_set(), internal_exfat_build_vbr(), internal_exfat_dir_relen(), internal_exfat_write_mbr(), internal_fat16_set_one(), internal_fmt_build_bpb_f16(), internal_fmt_build_bpb_f32(), internal_fmt_seed_fats(), internal_fmt_write_totals(), internal_setattr_exfat(), internal_utime_exfat(), priv_entry_set_cluster_size(), priv_exfat_flush_set(), priv_fat_entry_set_times(), priv_fat_entry_stamp_access(), priv_fat_entry_stamp_create(), priv_fat_entry_stamp_write(), and priv_lfn_fill_slot().

◆ priv_wr32()

void priv_wr32	(	uint8_t *	p,
		uint32_t	v )

Encode a little-endian uint32_t into a byte buffer.

Inverse of priv_rd32. Writes lowest byte first.

Parameters

[out]	p	Pointer to four writable bytes.
[in]	v	Value to encode.

Precondition: p is non-NULL and points to at least 4 writable bytes.; Caller has bounds-checked p.

Postcondition: p[0..3] reflect the little-endian encoding of v.; No other state modified.

Note: Trivially thread-safe; not reentrant against the same buffer.

Since: 0.1.0

Definition at line 68 of file ra8_fs_fat.c.

References k_byte_mask, k_shift_byte, k_shift_three_bytes, and k_shift_two_bytes.

Referenced by internal_exfat_build_dir_set(), internal_exfat_build_vbr(), internal_exfat_fat_set_one(), internal_exfat_free_run(), internal_exfat_patch_stream(), internal_exfat_put32(), internal_exfat_write_boot_tail(), internal_exfat_write_mbr(), internal_exfat_write_root(), internal_fat32_set_one(), internal_fmt_build_bpb_f16(), internal_fmt_build_bpb_f32(), internal_fmt_seed_fats(), internal_fmt_write_fsinfo(), internal_fmt_write_totals(), priv_entry_set_cluster_size(), priv_exfat_file_set_times(), priv_exfat_file_stamp_access(), priv_exfat_file_stamp_create(), priv_exfat_file_stamp_write(), priv_fsinfo_flush(), and priv_wr64().

◆ priv_wr64()

void priv_wr64	(	uint8_t *	p,
		uint64_t	v )

Encode a uint64_t into a byte buffer, little-endian.

The 8-byte companion of priv_wr32, for exFAT's 64-bit DataLength / ValidDataLength fields and the formatter's PartitionOffset / VolumeLength.

Parameters

[out]	p	Pointer to eight writable bytes.
[in]	v	Value to store.

Precondition: p is non-NULL and points to at least 8 writable bytes.; Caller has bounds-checked p.

Postcondition: p[0..7] hold v little-endian.; No other state modified.

Note: Pure store; trivially thread-safe on distinct buffers.

Since: 0.1.0

Definition at line 77 of file ra8_fs_fat.c.

References k_shift_word32, and priv_wr32().

Referenced by internal_exfat_build_vbr(), internal_exfat_dir_relen(), internal_exfat_free_run(), and internal_exfat_patch_stream().

Variable Documentation

◆ k_zero_sector

const uint8_t k_zero_sector[k_ra8_fs_sector_max]

extern

One whole sector of zero bytes, in read-only storage.

The shared source for every zero-fill write (fresh directory clusters, cluster tails). Const, so it costs code memory rather than SRAM, and one copy serves every translation unit.

Note: Read-only; never cast away the const.

Warning: Writing through a cast pointer would corrupt every zero-fill.

Since: 0.1.0

One whole sector of zero bytes, in read-only storage.

Definition at line 57 of file ra8_fs_fat_mount.c.

Referenced by internal_dir_cluster_init(), internal_dir_grow(), internal_exfat_close_gap(), and priv_exfat_zero_cluster().

Functions

Variables

Detailed Description

Function Documentation

◆ priv_bps()

◆ priv_byte_fill()

◆ priv_cluster_bytes()

◆ priv_dir_eps()

◆ priv_rd16()

◆ priv_rd32()

◆ priv_rd64()

◆ priv_sec_fat()

◆ priv_sec_fat2()

◆ priv_sec_io()

◆ priv_sec_walk()

◆ priv_wr16()

◆ priv_wr32()

◆ priv_wr64()

Variable Documentation

◆ k_zero_sector