Build an atomic FAT16 font image through bounded filesystem streaming. More...

#include <stdint.h>
#include <string.h>
#include "mkfontimg_internal.h"
#include "ra8_attributes.h"
#include "ra8_fs.h"

Include dependency graph for mkfontimg.c:

Enumerations
enum	mkfontimg_constant_t : uint32_t { k_block_size = 512U , k_blocks_fat16 = 8U * 1024U , k_byte_lo_mask = 0xFFU , k_byte_shift = 8U , k_font_min_bytes = 16U , k_font_cap = 4U * 1024U * 1024U , k_bpb_off_bytspersec = 11U , k_bpb_off_secperclus = 13U , k_bpb_off_rsvdseccnt = 14U , k_bpb_off_numfats = 16U , k_bpb_off_rootentcnt = 17U , k_bpb_off_totsec16 = 19U , k_bpb_off_secfat = 22U , k_bpb_secperclus = 1U , k_bpb_rsvdseccnt = 1U , k_bpb_numfats = 2U , k_bpb_rootentcnt = 16U , k_bpb_fatsz16 = 32U , k_bpb_sig_off_a = 510U , k_bpb_sig_off_b = 511U , k_bpb_sig_a = 0x55U , k_bpb_sig_b = 0xAAU }
	FAT16 geometry, BPB fields, and accepted font limits. More...

Functions
static void	internal_put16 (uint8_t *sector, uint32_t offset, uint16_t value)
	Store one little-endian 16-bit BPB field.
static void	internal_build_fat16 (uint8_t sector[k_block_size])
	Build the legacy-compatible minimal FAT16 boot sector.
static bool	internal_mount_image (const char image_out, mkfontimg_host_t host, ra8_fs_mount_t **mount)
	Create, seed, and mount one unpublished FAT16 image.
static bool	internal_finish_image (mkfontimg_host_t host, ra8_fs_mount_t mount)
	Finish filesystem state and publish the image atomically.
static int	internal_run_blank (const char *image_out)
	Generate and publish a formatted empty FAT16 image.
static int	internal_run_font (const char font_in, const char image_out, const char *card_name)
	Generate a FAT16 image containing one verified streamed font.
int	main (int argc, char **argv)
	Parse CLI mode and delegate to blank or font image generation.

Detailed Description

Build an atomic FAT16 font image through bounded filesystem streaming.

Creates the same 4 MiB FAT16 superfloppy used by the firmware and emulator, but binds ra8_fs to a sparse sibling temporary rather than a resident disk buffer. Font mode streams and readback-verifies one stable host input; blank mode publishes the identical formatted empty image. Publication occurs only after filesystem close/unmount, file sync, atomic rename, and directory sync.

Usage: mkfontimg <font-in> <image-out> [dest-name] mkfontimg --blank <image-out>

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

Since: 0.1.0

Definition in file mkfontimg.c.

Enumeration Type Documentation

◆ mkfontimg_constant_t

enum mkfontimg_constant_t : uint32_t

FAT16 geometry, BPB fields, and accepted font limits.

Enumerator
k_block_size	Bytes per sector.
k_blocks_fat16	Sectors in the image.
k_byte_lo_mask	Low-byte mask.
k_byte_shift	One-byte bit shift.
k_font_min_bytes	Minimum accepted font bytes.
k_font_cap	Maximum accepted font bytes.
k_bpb_off_bytspersec	BPB bytes/sector offset.
k_bpb_off_secperclus	BPB sectors/cluster offset.
k_bpb_off_rsvdseccnt	BPB reserved-sector offset.
k_bpb_off_numfats	BPB FAT-count offset.
k_bpb_off_rootentcnt	BPB root-entry offset.
k_bpb_off_totsec16	BPB total-sector offset.
k_bpb_off_secfat	BPB FAT-size offset.
k_bpb_secperclus	Sectors per cluster.
k_bpb_rsvdseccnt	Reserved sectors.
k_bpb_numfats	FAT copy count.
k_bpb_rootentcnt	Fixed root entries.
k_bpb_fatsz16	Sectors per FAT.
k_bpb_sig_off_a	Signature low offset.
k_bpb_sig_off_b	Signature high offset.
k_bpb_sig_a	Signature low byte.
k_bpb_sig_b	Signature high byte.

Definition at line 28 of file mkfontimg.c.

Function Documentation

◆ internal_build_fat16()

void internal_build_fat16 ( uint8_t sector[k_block_size] )

static

Build the legacy-compatible minimal FAT16 boot sector.

Writes only fixed geometry fields and the required trailing signature.

Parameters

[out] sector Zeroed 512-byte boot-sector buffer.

Precondition: sector is non-NULL and zero-initialized.; The enum geometry remains consistent with the legacy generator.

Postcondition: The BPB mounts as the exact 4 MiB FAT16 layout expected by ra8_fs.; Bytes outside named fields and the signature remain zero.

Note: Pure apart from sector; thread-safe.

Since: 0.1.0

Definition at line 83 of file mkfontimg.c.

References internal_put16(), k_block_size, k_blocks_fat16, k_bpb_fatsz16, k_bpb_numfats, k_bpb_off_bytspersec, k_bpb_off_numfats, k_bpb_off_rootentcnt, k_bpb_off_rsvdseccnt, k_bpb_off_secfat, k_bpb_off_secperclus, k_bpb_off_totsec16, k_bpb_rootentcnt, k_bpb_rsvdseccnt, k_bpb_secperclus, k_bpb_sig_a, k_bpb_sig_b, k_bpb_sig_off_a, k_bpb_sig_off_b, and RA8_INTERNAL.

Referenced by internal_mount_image().

◆ internal_finish_image()

bool internal_finish_image	(	mkfontimg_host_t *	host,
		ra8_fs_mount_t *	mount )

static

Finish filesystem state and publish the image atomically.

Refuses publication after unmount or sticky backend I/O failure.

Parameters

[in,out]	host	Hosted temporary state.
[in,out]	mount	Mounted FAT16 volume.

Returns: true when unmount and durable publication both succeed.

Return values

true	Final path atomically names the complete image.
false	Temporary was removed or durability is unconfirmed.

Precondition: No card file remains open.; mount was returned by internal_mount_image.

Postcondition: No temporary descriptor remains owned.; Before rename, any failure preserves an existing destination.

Note: Not thread-safe through global ra8_fs mount slots.

Since: 0.1.0

Definition at line 143 of file mkfontimg.c.

References mkfontimg_host_t::disk, mkfontimg_disk_t::io_failed, k_ra8_ok, priv_mkfontimg_host_abort(), priv_mkfontimg_host_commit(), ra8_fs_unmount(), and RA8_INTERNAL.

Referenced by internal_run_blank(), and internal_run_font().

◆ internal_mount_image()

bool internal_mount_image	(	const char *	image_out,
		mkfontimg_host_t *	host,
		ra8_fs_mount_t **	mount )

static

Create, seed, and mount one unpublished FAT16 image.

Keeps all mutations in a private sibling until final publication.

Parameters

[in]	image_out	Requested final path.
[out]	host	Receives hosted backend/publication state.
[out]	mount	Receives mounted filesystem.

Returns: true only when the fresh image mounts successfully.

Return values

true	Caller owns `host` and must unmount `mount`.
false	No descriptor or temporary remains owned.

Precondition: All arguments are non-NULL.; image_out is NUL-terminated.

Postcondition: On true the legacy-compatible BPB is present at sector zero.; On false any sibling temporary is removed.

Note: Not thread-safe through global ra8_fs mount slots.

Since: 0.1.0

Definition at line 113 of file mkfontimg.c.

References mkfontimg_host_t::backend, internal_build_fat16(), k_block_size, k_blocks_fat16, k_ra8_ok, priv_mkfontimg_host_abort(), priv_mkfontimg_host_begin(), priv_mkfontimg_host_seed(), and ra8_fs_mount().

Referenced by internal_run_blank(), and internal_run_font().

◆ internal_put16()

void internal_put16	(	uint8_t *	sector,
		uint32_t	offset,
		uint16_t	value )

static

Store one little-endian 16-bit BPB field.

Encodes directly into the caller-owned deterministic boot sector.

Parameters

[out]	sector	Boot-sector buffer.
[in]	offset	Field byte offset.
[in]	value	Value to encode.

Precondition: sector has at least k_block_size writable bytes.; offset leaves room for two bytes.

Postcondition: Exactly two bytes hold value low byte first.; All other bytes remain unchanged.

Note: Pure apart from sector; thread-safe.

Since: 0.1.0

Definition at line 66 of file mkfontimg.c.

References k_byte_lo_mask, k_byte_shift, and RA8_INTERNAL.

Referenced by internal_build_fat16().

◆ internal_run_blank()

int internal_run_blank ( const char * image_out )

static

Generate and publish a formatted empty FAT16 image.

Runs the same transaction path as font images without creating a file.

Parameters

[in] image_out Final output path.

Returns: Process status.

Return values

0	Blank image was published.
1	Build, unmount, or publication failed.

Precondition: image_out is non-NULL and NUL-terminated.; The destination parent directory exists.

Postcondition: On success output bytes match the legacy blank generator.; On failure before rename an existing destination is preserved.

Note: Not thread-safe through global ra8_fs slots.

Since: 0.1.0

Definition at line 166 of file mkfontimg.c.

References internal_finish_image(), internal_mount_image(), priv_mkfontimg_diag(), and RA8_INTERNAL.

Referenced by main().

◆ internal_run_font()

int internal_run_font	(	const char *	font_in,
		const char *	image_out,
		const char *	card_name )

static

Generate a FAT16 image containing one verified streamed font.

Requires stable metadata and a byte-for-byte second pass before rename.

Parameters

[in]	font_in	Host font path.
[in]	image_out	Final output path.
[in]	card_name	Destination name on the FAT volume.

Returns: Process status.

Return values

0	Font image was published.
1	Input, filesystem, verification, or publication failed.

Precondition: All strings are non-NULL and NUL-terminated.; card_name satisfies the ra8_fs filename contract.

Postcondition: On success card bytes exactly match one stable host-input snapshot.; On failure before rename an existing destination is preserved.

Note: Not thread-safe through global ra8_fs slots.

Since: 0.1.0

Definition at line 197 of file mkfontimg.c.

References internal_finish_image(), internal_mount_image(), k_font_cap, k_font_min_bytes, priv_mkfontimg_diag(), priv_mkfontimg_diag_u64(), priv_mkfontimg_host_abort(), priv_mkfontimg_host_copy(), and ra8_fs_unmount().

Referenced by main().

◆ main()

int main	(	int	argc,
		char **	argv )

Parse CLI mode and delegate to blank or font image generation.

Parameters

[in]	argc	Argument count.
[in]	argv	Argument vector.

Returns: Process status: zero success, one runtime failure, two usage error.

Return values

0	A complete verified image was published.
1	Generation failed.
2	Command-line shape was invalid.

Precondition: Hosted runtime supplies argc entries in argv.; Argument strings are NUL-terminated.

Postcondition: No temporary descriptor remains open.; Usage errors never touch the destination.

Note: Not thread-safe through global ra8_fs slots.

Since: 0.1.0

Definition at line 250 of file mkfontimg.c.

References internal_run_blank(), internal_run_font(), priv_mkfontimg_diag(), and strcmp().

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ mkfontimg_constant_t

Function Documentation

◆ internal_build_fat16()

◆ internal_finish_image()

◆ internal_mount_image()

◆ internal_put16()

◆ internal_run_blank()

◆ internal_run_font()

◆ main()