Hsu.Formats.Firmware 2026.5.7

Hsu.Formats.Firmware

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

Supported Formats

Features

• AOT-compatible (IsAotCompatible=true on net8.0+)
• HexModel, S19Model, MotModel, BinModel, ElfModel, VbfModel all implement IMemoryImage
• Each format ships a dedicated *Parser (all implement IAsyncFormatParser) and *Writer
• HexModel.StartLinearAddress preserves the execution start address through conversions
• S19Model / MotModel carry address-width metadata (16 / 24 / 32-bit)
• MemorySegment boundaries are preserved — adjacent segments are never silently merged
• PartitionTransferHelper — splits firmware images into fixed-size TransferBlock objects for UDS (ISO 14229 RequestDownload/TransferData) or CCP/XCP transmission workflows; supports address-range filtering, fill-byte padding, and re-assembly via MergePartitions

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");

Console.WriteLine($"Start linear address: 0x{model.StartLinearAddress:X8}");

Parse a Motorola S-record file

using Hsu.Formats.S19;

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

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

Write Intel HEX

using Hsu.Formats.Hex;

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

Write raw binary (gaps filled with 0xFF)

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");

Split firmware into UDS transfer blocks

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

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

// Split the entire image into 1 KB transfer blocks (0xFF-filled padding on last block)
var blocks = PartitionTransferHelper.SplitImage(model, blockSize: 1024);

foreach (var block in blocks)
{
    Console.WriteLine(
        $"  Block {block.BlockIndex + 1}/{block.TotalBlocks}  " +
        $"addr=0x{block.Address:X8}  len={block.Data.Length}");
    // → send block.Data via UDS RequestDownload / TransferData
}

Select specific partitions and split

// Select only the application partition (0x08008000–0x080FFFFF)
var partitions = PartitionTransferHelper.SelectPartitions(
    model,
    [(0x0800_8000L, 0x0810_0000L)]);

foreach (var seg in partitions)
{
    var blocks = PartitionTransferHelper.SplitPartition(seg, blockSize: 512);
    // transmit blocks …
}

Reassemble transfer blocks after download

// Receive blocks back from the ECU and verify
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 and support cancellable, non-blocking parsing. Text-based formats (HEX, S19, MOT) use ReadLineAsync for line-by-line async I/O; binary formats (ELF, VBF, BIN) offload parsing to the thread pool via Task.Run.

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

// Intel HEX — async line-by-line I/O
using var stream = File.OpenRead("firmware.hex");
var model = (HexModel)await new HexParser().ParseAsync(stream);

// S-record — async line-by-line I/O (CancellationToken supported)
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
using var s19Stream = File.OpenRead("firmware.s19");
var s19Model = (S19Model)await new S19Parser().ParseAsync(s19Stream, cts.Token);

// ELF — offloads to thread pool
using var elfStream = File.OpenRead("firmware.elf");
var elfModel = (ElfModel)await new ElfParser().ParseAsync(elfStream);