Create FAT32 image files through native streaming assembly #9

Open
opened 2026-10-24 13:14:31 +02:00 by erikinkinen · 1 comment
Owner

Problem and motivation

ESP creation still depends on external FAT formatting and file-copy utilities. EriX needs an image-file path it can build and run itself, alongside the existing GPT assembly.

Proposed behavior and scope

Add deterministic FAT32 image creation to Boot-tool from explicit directory and file entries. Stream boot records, both FATs and directories through bounded scratch, then reuse the existing checked payload reads and single output publication. Support long UTF-16 names, collision-safe short aliases, explicit geometry, labels, volume IDs and timestamps.

Migrate the product disk recipe, appliance runtime boot volume and raw ESP scenario route in Integration. Preserve their existing metadata tail and payload contracts. Specialized corruption fixtures and independent inspection tools remain separate consumers.

Authority, security and reliability

Use the existing selected READ and output-publication capabilities. No raw block, mount, directory discovery, clock or randomness authority is needed. Validate the complete plan before grants or output effects. Preserve each original operand occurrence, first error, partial output state and independent once-only input/output retirement. A late input failure must preserve the previous published image.

Acceptance criteria

  • Implement checked FAT32 geometry, mirrored metadata, deterministic allocation, complete name/alias handling and caller-selected storage limits without a volume-sized buffer or fixed file-count cap.
  • Integrate the CLI and closed metadata stream into both host and native assembly, preserving exact source length, digest, EOF and cleanup behavior.
  • Add meaningful format, Unicode, capacity and failure controls, plus an independent Fatd reader round trip.
  • Migrate all three Integration routes and their explicit tool/source provenance; remove formatting/copy dependencies from those routes.
  • Update component documentation and the technical manual; retain matching-image boot and cross-backend acceptance as explicit requirements.

Alternatives and tradeoffs

Whole-image and whole-FAT buffers grow with volume size. An arbitrary output-generator callback would widen the assembly interface. Closed metadata ranges keep generation within the prepared format plan and existing publication owners. Reuse the shared filesystem-name policy instead of adding another Unicode table.

Tracking and rollout

Extends GPT image initialization and partition payload assembly, with Integration adoption tracked by full build and image assembly. The Phase 6 checklist retains the complete guest build requirements. Format references are Microsoft's FAT specification and the UEFI filesystem contract; no third-party implementation is imported.

## Problem and motivation ESP creation still depends on external FAT formatting and file-copy utilities. EriX needs an image-file path it can build and run itself, alongside the existing GPT assembly. ## Proposed behavior and scope Add deterministic FAT32 image creation to Boot-tool from explicit directory and file entries. Stream boot records, both FATs and directories through bounded scratch, then reuse the existing checked payload reads and single output publication. Support long UTF-16 names, collision-safe short aliases, explicit geometry, labels, volume IDs and timestamps. Migrate the product disk recipe, appliance runtime boot volume and raw ESP scenario route in Integration. Preserve their existing metadata tail and payload contracts. Specialized corruption fixtures and independent inspection tools remain separate consumers. ## Authority, security and reliability Use the existing selected READ and output-publication capabilities. No raw block, mount, directory discovery, clock or randomness authority is needed. Validate the complete plan before grants or output effects. Preserve each original operand occurrence, first error, partial output state and independent once-only input/output retirement. A late input failure must preserve the previous published image. ## Acceptance criteria - [ ] Implement checked FAT32 geometry, mirrored metadata, deterministic allocation, complete name/alias handling and caller-selected storage limits without a volume-sized buffer or fixed file-count cap. - [ ] Integrate the CLI and closed metadata stream into both host and native assembly, preserving exact source length, digest, EOF and cleanup behavior. - [ ] Add meaningful format, Unicode, capacity and failure controls, plus an independent Fatd reader round trip. - [ ] Migrate all three Integration routes and their explicit tool/source provenance; remove formatting/copy dependencies from those routes. - [ ] Update component documentation and the technical manual; retain matching-image boot and cross-backend acceptance as explicit requirements. ## Alternatives and tradeoffs Whole-image and whole-FAT buffers grow with volume size. An arbitrary output-generator callback would widen the assembly interface. Closed metadata ranges keep generation within the prepared format plan and existing publication owners. Reuse the shared filesystem-name policy instead of adding another Unicode table. ## Tracking and rollout Extends [GPT image initialization](https://git.erikinkinen.fi/erix/boot-tool/issues/7) and [partition payload assembly](https://git.erikinkinen.fi/erix/boot-tool/issues/8), with Integration adoption tracked by [full build and image assembly](https://git.erikinkinen.fi/erix/integration/issues/8). The [Phase 6 checklist](https://git.erikinkinen.fi/erix/integration/issues/65) retains the complete guest build requirements. Format references are Microsoft's FAT specification and the UEFI filesystem contract; no third-party implementation is imported.
Author
Owner

Implemented locally in signed checkpoints: Boot-tool 97fc50a4, Integration
c2aff569, Fatd 6d799054 and manual e273014e.

The encoder prepares deterministic FAT32 metadata and allocation runs from
explicit entries, then streams sectors and exact file contents through the
shared publication driver. Product ESP, empty runtime boot and raw ESP recipes
use the same selected image-tool artifact and source closure. Specialized
malformed-media fixtures keep their separate tools.

Coherent publication and guest execution remain open.

Implemented locally in signed checkpoints: Boot-tool `97fc50a4`, Integration `c2aff569`, Fatd `6d799054` and manual `e273014e`. The encoder prepares deterministic FAT32 metadata and allocation runs from explicit entries, then streams sectors and exact file contents through the shared publication driver. Product ESP, empty runtime boot and raw ESP recipes use the same selected image-tool artifact and source closure. Specialized malformed-media fixtures keep their separate tools. Coherent publication and guest execution remain open.
erikinkinen added this to the Alpha 1 milestone 2026-10-30 09:33:34 +01:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
erix/boot-tool#9
No description provided.