[FEATURE] Encode GPT image metadata without device authority #3

Open
opened 2026-10-24 09:37:42 +02:00 by erikinkinen · 1 comment
Owner

Problem and motivation

Building disk images inside EriX needs GPT metadata generation without a host partitioning program or device administration. The maintained partition crate parses GPT, while the product image recipe still invokes sgdisk. Its Python GPT helper is a fixed fixture generator.

Proposed behavior and scope

Add an allocation-free, no_std GPT metadata writer to lib-partition. Borrow explicit LBA geometry, GUIDs and optional partition slots, plus caller-owned output and index buffers. Return the protective MBR, primary and backup headers, one shared partition array and their destination spans; do not allocate an entire disk image or perform I/O.

Add an explicit backup-header parser through the shared validator, keeping the existing primary parser primary-only.

Use the current UEFI GPT format, preserving the existing parser's legacy compatibility. Support caller-selected block sizes and entry capacity, checked layout arithmetic, UTF-16 names, reserved-byte clearing and exact CRC extents. The raw-image geometry has no CHS mapping; document the protective MBR's saturated ending field rather than inventing device geometry.

Authority, security and reliability

The writer receives only borrowed values and buffers. It has no device, file, environment, entropy, callback or allocator authority. The caller supplies GUID identity policy and performs writes through its existing output owner. Validate geometry, partition ranges, overlaps, duplicate GUIDs, names, buffer extents and workspace before changing any output buffer. Invalid inputs preserve all four metadata outputs; index scratch may change during preflight.

Keep unused slots and caller entry order. Use caller-owned indices for allocation-free O(n log n) overlap and GUID checks, with no fixed disk or partition maximum. A valid encoding detects format errors and corruption; it does not authenticate contents or prove an image booted.

Acceptance criteria

  • Add complete documented geometry, partition and encoding APIs without changing existing parser acceptance.
  • Produce the protective MBR, both checked headers and shared reserved/padded partition table with exact write spans and CRC coverage.
  • Preserve outputs on malformed geometry, arithmetic overflow, invalid partitions/names and insufficient output or index storage.
  • Cover literal format bytes, independent CRC expectations, unused slots, overlaps, duplicate identities, non-512 blocks, large LBAs and extended entry/header storage.
  • Keep the implementation allocation-free, authority-free and below 1,000 lines per file; enforce rustdoc and missing_docs policy.
  • Update crate architecture, README, roadmap and the technical manual; keep actual image-recipe adoption and guest builds explicit followups.

Alternatives and tradeoffs

Keeping sgdisk as the only producer preserves an external runtime dependency. Extending the fixture helper would leave native callers without a reusable Rust implementation. A pure metadata encoder can serve image-file builders without acquiring their output authority; filesystem assembly and recipe migration remain separate work.

Tracking and rollout

Continue the image/build work and Integration review. Add the reusable writer first, then adopt it through explicit image-file output ownership before claiming the external partitioning dependency has been removed.

## Problem and motivation Building disk images inside EriX needs GPT metadata generation without a host partitioning program or device administration. The maintained partition crate parses GPT, while the product image recipe still invokes sgdisk. Its Python GPT helper is a fixed fixture generator. ## Proposed behavior and scope Add an allocation-free, no_std GPT metadata writer to lib-partition. Borrow explicit LBA geometry, GUIDs and optional partition slots, plus caller-owned output and index buffers. Return the protective MBR, primary and backup headers, one shared partition array and their destination spans; do not allocate an entire disk image or perform I/O. Add an explicit backup-header parser through the shared validator, keeping the existing primary parser primary-only. Use the current [UEFI GPT format](https://uefi.org/specs/UEFI/2.11/05_GUID_Partition_Table_Format.html), preserving the existing parser's legacy compatibility. Support caller-selected block sizes and entry capacity, checked layout arithmetic, UTF-16 names, reserved-byte clearing and exact CRC extents. The raw-image geometry has no CHS mapping; document the protective MBR's saturated ending field rather than inventing device geometry. ## Authority, security and reliability The writer receives only borrowed values and buffers. It has no device, file, environment, entropy, callback or allocator authority. The caller supplies GUID identity policy and performs writes through its existing output owner. Validate geometry, partition ranges, overlaps, duplicate GUIDs, names, buffer extents and workspace before changing any output buffer. Invalid inputs preserve all four metadata outputs; index scratch may change during preflight. Keep unused slots and caller entry order. Use caller-owned indices for allocation-free O(n log n) overlap and GUID checks, with no fixed disk or partition maximum. A valid encoding detects format errors and corruption; it does not authenticate contents or prove an image booted. ## Acceptance criteria - [x] Add complete documented geometry, partition and encoding APIs without changing existing parser acceptance. - [x] Produce the protective MBR, both checked headers and shared reserved/padded partition table with exact write spans and CRC coverage. - [x] Preserve outputs on malformed geometry, arithmetic overflow, invalid partitions/names and insufficient output or index storage. - [x] Cover literal format bytes, independent CRC expectations, unused slots, overlaps, duplicate identities, non-512 blocks, large LBAs and extended entry/header storage. - [x] Keep the implementation allocation-free, authority-free and below 1,000 lines per file; enforce rustdoc and missing_docs policy. - [ ] Update crate architecture, README, roadmap and the technical manual; keep actual image-recipe adoption and guest builds explicit followups. ## Alternatives and tradeoffs Keeping sgdisk as the only producer preserves an external runtime dependency. Extending the fixture helper would leave native callers without a reusable Rust implementation. A pure metadata encoder can serve image-file builders without acquiring their output authority; filesystem assembly and recipe migration remain separate work. ## Tracking and rollout Continue the [image/build work](https://git.erikinkinen.fi/erix/integration/issues/8) and [Integration review](https://git.erikinkinen.fi/erix/integration/pulls/12). Add the reusable writer first, then adopt it through explicit image-file output ownership before claiming the external partitioning dependency has been removed.
Author
Owner

The GPT encoder and explicit backup-header validator are now available on feature/posix-compat in 357cafd1. Callers provide the geometry, GUIDs, scratch and output buffers; refused inputs preserve all metadata outputs. The technical manual update is prepared and awaits publication. Boot-tool #7 tracks the native image-file command and recipe adoption.

The GPT encoder and explicit backup-header validator are now available on `feature/posix-compat` in [357cafd1](https://git.erikinkinen.fi/erix/lib-partition/commit/357cafd16fce9ed2de8c67c2184cfcd159318659). Callers provide the geometry, GUIDs, scratch and output buffers; refused inputs preserve all metadata outputs. The technical manual update is prepared and awaits publication. [Boot-tool #7](https://git.erikinkinen.fi/erix/boot-tool/issues/7) tracks the native image-file command and recipe adoption.
erikinkinen added this to the Alpha 1 milestone 2026-10-30 09:34:49 +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/lib-partition#3
No description provided.