Module iso

ISO Storage Management

Manages large ISO files that exceed the FAT32 4GB file size limit by splitting them across multiple “chunk” partitions. Each chunk is stored as a single file on a dedicated FAT32 partition.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        GPT Disk Layout                          │
├────────┬────────┬────────┬────────┬────────┬────────┬──────────┤
│  ESP   │ Chunk  │ Chunk  │ Chunk  │ Chunk  │ Chunk  │   Free   │
│ (EFI)  │   0    │   1    │   2    │   3    │   4    │  Space   │
│ ~512MB │ ~4GB   │ ~4GB   │ ~4GB   │ ~4GB   │ <4GB   │          │
└────────┴────────┴────────┴────────┴────────┴────────┴──────────┘

Manifest Format

Each ISO set has a manifest file stored on the ESP at /.iso/<name>.manifest:

MORPHEUS_ISO_MANIFEST_V1
name: ubuntu-24.04-desktop-amd64.iso
size: 6234567890
chunks: 3
sha256: <hash>
chunk_0: <partition_uuid> 4294967296
chunk_1: <partition_uuid> 4294967296
chunk_2: <partition_uuid> 1939600298

Usage

// Writing an ISO (during download)
let mut writer = ChunkWriter::new(block_io, &manifest)?;
writer.write_chunk_data(data_slice)?;
writer.finalize()?;

// Reading an ISO (during boot)
let reader = ChunkReader::new(block_io, &manifest)?;
let data = reader.read_range(offset, length)?;

Constraints

• Maximum chunk size: 4GB - 1 byte (FAT32 limit)
• Maximum chunks per ISO: 16 (fixed array)
• Chunk partition type: Linux filesystem GUID (for now)
• Each chunk partition is formatted as FAT32 with single file

Modules

• adapter 🔒
  Block I/O Adapter for Chunked ISO Storage
• chunk 🔒
  Chunk information structures
• error 🔒
  ISO storage error types
• iso9660_bridge 🔒
  ISO9660 Integration
• manifest 🔒
  ISO Manifest Format
• reader 🔒
  Chunk Reader
• storage 🔒
  ISO Storage Manager
• writer 🔒
  Chunk Writer

Structs

• ChunkInfo
  Information about a single chunk partition
• ChunkReader
  Chunk reader for streaming ISO data
• ChunkSet
  Collection of chunks for a single ISO
• ChunkWriter
  Streaming chunk writer
• ChunkedBlockIo
  Block I/O adapter for chunked ISO storage
• ChunkedIso
  High-level helper to boot from a chunked ISO
• ChunkedReader
  Simpler read interface for when you just need byte-level access
• IsoBlockIoAdapter
  Block I/O adapter that implements gpt_disk_io::BlockIo
• IsoEntry
  ISO storage entry (metadata only, no chunk data)
• IsoManifest
  ISO manifest structure
• IsoReadContext
  Read context for passing to boot/kernel loader
• IsoStorageManager
  ISO storage manager
• PartitionRequest
  Partition allocation request

Enums

• IsoError
  Errors that can occur during ISO chunk operations
• WriterState
  Chunk writer state

Constants

• DEFAULT_CHUNK_SIZE
  Default chunk size (slightly under 4GB to allow for FAT32 overhead)
• FAT32_MAX_FILE_SIZE
  Maximum file size that FAT32 supports (4GB - 1 byte)
• MANIFEST_DIR
  Manifest directory path on ESP
• MANIFEST_MAGIC
  Magic number for manifest files: “MXISO\x01\x00\x00”
• MAX_CHUNKS
  Maximum number of chunks per ISO (16 * 4GB = 64GB max ISO size)
• MAX_ISOS
  Maximum number of ISOs that can be tracked
• MAX_MANIFEST_SIZE
  Maximum manifest size (header + 16 chunks)

Traits

• VirtualBlockIo
  Trait for block I/O operations (matches gpt_disk_io::BlockIo pattern)

Functions

• chunks_needed
  Calculate number of chunks needed for a given ISO size
• disk_space_needed
  Calculate total disk space needed for an ISO (with FAT32 overhead)