Hsu.Formats.Firmware 2026.7.13

Hsu.Formats.Firmware

Firmware and memory-image format support for the Hsu.Formats library.

Supported Formats

Features

• AOT-compatible (IsAotCompatible=true on net8.0+)
• All primary models implement IMemoryImage
• Dedicated parser/writer pairs per format
• HexModel.StartLinearAddress preserves execution start address metadata
• S19Model and MotModel preserve address-width intent (16 / 24 / 32-bit)
• MemorySegment address arithmetic uses 64-bit (long) addressing through the shared abstractions
• PartitionTransferHelper supports firmware splitting/merging workflows for UDS / CCP / XCP style transfer scenarios

Quick Start

Parse an Intel HEX file

using Hsu.Formats.Hex;

using var stream = File.OpenRead("firmware.hex");
var model = (HexModel)new HexParser().Parse(stream);

foreach (var seg in model.Segments)
    Console.WriteLine($"0x{seg.Address:X8}  {seg.Data.Length} bytes");

Parse a Motorola S-record file

using Hsu.Formats.S19;

using var stream = File.OpenRead("firmware.s19");
var model = (S19Model)new S19Parser().Parse(stream);

Write Intel HEX

using Hsu.Formats.Hex;

using var writer = new StreamWriter("out.hex");
new HexWriter().Write(model, writer);

Write raw binary with gap fill

using Hsu.Formats.Bin;

using var stream = File.Create("out.bin");
new BinWriter(fillByte: 0xFF).Write(model, stream);

Parse an ELF binary

using Hsu.Formats.Elf;

using var stream = File.OpenRead("firmware.elf");
var model = (ElfModel)new ElfParser().Parse(stream);

foreach (var seg in model.Segments)
    Console.WriteLine($"0x{seg.Address:X8}  {seg.Data.Length} bytes");

Partition Transfer Helpers

PartitionTransferHelper supports slicing memory images into fixed-size transfer blocks and reassembling them later.

Typical use cases:

• UDS RequestDownload / TransferData
• CCP / XCP style segmented download flows
• offline chunking for updater pipelines

Split a firmware image into transfer blocks

using Hsu.Formats.Hex;
using Hsu.Formats;

using var stream = File.OpenRead("firmware.hex");
var model = (HexModel)new HexParser().Parse(stream);

var blocks = PartitionTransferHelper.SplitImage(model, blockSize: 1024);

foreach (var block in blocks)
    Console.WriteLine($"Block {block.BlockIndex + 1}/{block.TotalBlocks} @ 0x{block.Address:X8}");

Reassemble transfer blocks

var reconstructed = PartitionTransferHelper.MergePartitions(receivedBlocks);

foreach (var seg in reconstructed)
    Console.WriteLine($"0x{seg.Address:X8}  {seg.Data.Length} bytes");

Async Parsing

All firmware parsers implement IAsyncFormatParser.

• Text-based formats such as HEX/S19/MOT use async line-oriented parsing patterns
• Binary formats such as ELF/VBF/BIN expose async entry points for callers and offload CPU-oriented work appropriately

using Hsu.Formats.Hex;
using Hsu.Formats.Elf;

using var hexStream = File.OpenRead("firmware.hex");
var hexModel = (HexModel)await new HexParser().ParseAsync(hexStream);

using var elfStream = File.OpenRead("firmware.elf");
var elfModel = (ElfModel)await new ElfParser().ParseAsync(elfStream);

Documentation

• Standard format specifications, when present, are documented in the project repository.
• Project-level architecture and feature design notes are documented in the project repository.