DiagKit.FlashFiles 1.1.0-preview.2

DiagKit.FlashFiles

An automotive diagnostic flash file parsing library, supporting Intel MCS-86 HEX (.hex) and Motorola S-Record (.s19/.s28/.s37) formats for ECU reflashing, UDS download flows, and flash data verification.

Installation

dotnet add package DiagKit.FlashFiles

Quick Start

using DiagKit.FlashFiles;
using DiagKit.FlashFiles.Define.Enumerates;

// Load from file path — auto-detects .hex/.s19/.s28/.s37 by extension
using var doc = FlashDocument.Load("firmware.hex", dataSize: 2);

// Load from Stream — format must be specified
using var fromStream = FlashDocument.Load(stream, FlashFileType.Intel_MCS_86, dataSize: 2);

// Load from in-memory bytes — format must be specified
using var fromBytes = FlashDocument.Load(data, FlashFileType.Motorola_S_Record, dataSize: 1);

Strict and Lenient Parsing

Parsing is strict by default. Checksums, Intel EOF records, Motorola termination records, record type lengths, non-data record address rules, S-Record header/count rules, and DataSize alignment are validated unless explicitly relaxed.

// Same behavior as the default constructor and existing Load overloads.
var strict = FlashLoadOptions.Strict(dataSize: 2);

// Field diagnostics: tolerate common format noise, but still validate checksums and DataSize alignment.
var lenient = FlashLoadOptions.Lenient(dataSize: 2);

// Supplier compatibility: continue after EOF/termination and pad unaligned data records.
// Checksum validation remains enabled by default.
var supplierCompatible = FlashLoadOptions.SupplierCompatible(dataSize: 2);

using var supplier = FlashDocument.Load("supplier.hex", supplierCompatible);

Advanced callers can still tune individual parser behaviors:

var options = FlashLoadOptions.SupplierCompatible(dataSize: 2);
options.ValidateChecksums = false; // Use only for field diagnostics or trusted supplier recovery.
options.DataRecordPaddingValue = 0xFF;

using var lenientDocument = FlashDocument.Load("supplier.hex", options);

RecordsAfterEndOfFileBehavior.Reject preserves the default standard behavior, Ignore stops at the first EOF/termination record, and Parse continues reading valid records after it.

Data Ownership

FlashDocument, FlashBlock, and FlashPage use pooled memory and implement IDisposable. Spans and ReadOnlyMemory<byte> views are only valid while the owning object is alive. Use DTO export when data needs to cross service/UI boundaries or outlive the document:

using var doc = FlashDocument.Load("firmware.hex", dataSize: 2);

IReadOnlyList<FlashBlockDto> ownedBlocks = doc.ToBlockDtos();
byte[] firstBlockData = ownedBlocks[0].Data;

Each FlashBlockDto owns a copied byte[] and does not need to be disposed.

Core API

doc.StartAddress   // Start address
doc.EndAddress     // End address
doc.ByteCount      // Total bytes (ulong)
doc.AddressCount   // Total addresses (ulong)
doc.DataSize       // Bytes per address
doc.Blocks         // IReadOnlyList<FlashBlock>

// O(log n) address lookup
var exists = doc.ContainsAddress(0x003E8500);
var word = doc.ReadAt(0x003E8500);
var range = doc.ReadRange(0x003E8500, 0x003E850F);

// Modify data
doc.WriteAt(0x003E8500, new byte[] { 0xAA, 0xBB });
doc.WriteRange(0x003E8500, 0x003E8501, new byte[] { 0xAA, 0xBB, 0xCC, 0xDD });

// UDS DTO export. Blocks own copied data and do not require Dispose.
var udsBlocks = doc.ToUdsBlockDtos(new FlashUdsExportOptions(maxBlockByteCount: 0x400)
{
    PaddingValue = 0xFF,
    FillGaps = true,
    SkipBlankBlocks = true,
    RequireUInt32Address = true,
});

// Low-level UDS page filling
using var page = new FlashPage(addressCount: 0x100, dataSize: 2);
var hasData = doc.TryFillPage(page, doc.StartAddress);

// Enumerate pages — caller is responsible for disposing each FlashPage
foreach (var item in doc.EnumeratePages(0x100, doc.StartAddress, doc.EndAddress))
{
    using (item)
    {
        // Process item.Data
    }
}

// Filter blank pages
var pages = doc.EnumeratePages(0x100, doc.StartAddress, doc.EndAddress).ToList();
var filtered = FlashDocument.FilterPages(pages, skipLeadingBlank: true, skipMiddleBlank: true, skipTrailingBlank: true);

Save as Intel HEX

Intel MCS-86 HEX output is currently supported. Motorola S-Record writing is not yet implemented.

using var output = File.Create("firmware.hex");
doc.Save(output, FlashFileType.Intel_MCS_86);

doc.SaveToFile("firmware.hex");

CRC-32

using DiagKit.FlashFiles.Common.Utilities;

uint mpeg2 = UdsCrc32.Mpeg2.Compute(data);
uint standard = UdsCrc32.Standard.Compute(data);
uint posix = UdsCrc32.Posix.Compute(data);
uint autosar = UdsCrc32.AutoSar.Compute(data);

Build & Test

dotnet build .\src\DiagKit.FlashFiles\DiagKit.FlashFiles.csproj
dotnet test .\tests\DiagKit.FlashFiles.Tests\DiagKit.FlashFiles.Tests.csproj
dotnet pack .\src\DiagKit.FlashFiles\DiagKit.FlashFiles.csproj -c Release

Project Info

• Target frameworks: net8.0, net10.0
• License: MIT
• Package ID: DiagKit.FlashFiles
• Dependencies: none