Hsu.Formats.Trace 2026.7.13

Hsu.Formats.Trace

Trace-log and Ethernet-capture support for the Hsu.Formats library.

Supported Formats

Features

• AOT-compatible (IsAotCompatible=true on net8.0+)
• AscModel, BlfModel, TrcModel, MdfModel, KmeModel, PcapModel, and PcapngModel implement IFormatModel
• All parsers implement IAsyncFormatParser
• Mixed ordered event support through:
  • ITraceEvent
  • ITraceEventLog
  • ITraceEthernetFrame
  • TraceEventKind
• Streaming parser surfaces:
  • IAsyncStreamingTraceParser / TraceParseSession for frame-oriented readers
  • IAsyncStreamingEventParser / EventParseSession for mixed CAN + Ethernet event streams
  • IAsyncStreamingEthernetParser / EthernetParseSession for capture-style packet streams
• Official-format ASC Ethernet output via AscWriter
• BLF Ethernet support for official object types such as ETHERNET_FRAME_EX and ETHERNET_FRAME_FORWARDED
• PCAP/PCAPNG parsing with little/big-endian and microsecond/nanosecond timestamp handling
• Incremental file writers:
  • AscFileWriter
  • BlfFileWriter
  • TrcFileWriter

Mixed Event Model

ASC and BLF are not treated as CAN-only containers anymore.

They can preserve ordered mixed-event streams containing:

• CAN / CAN FD frames
• Ethernet packet events
• selected status / statistics / meta events

This is what powers:

• mixed CAN + Ethernet desktop viewers
• official-format ASC/BLF Ethernet exports
• replay planning over trace logs that contain both CAN and Ethernet data

Quick Start

Parse a Vector ASC log

using Hsu.Formats.Asc;

using var stream = File.OpenRead("log.asc");
var model = (AscModel)new AscParser().Parse(stream);

Console.WriteLine($"Frames: {model.Frames.Count}");
Console.WriteLine($"Ethernet events: {model.EthernetFrames.Count}");

Parse a PCAP capture

using Hsu.Formats.Pcap;

using var stream = File.OpenRead("capture.pcap");
var model = (PcapModel)new PcapParser().Parse(stream);

Console.WriteLine($"LinkType: {model.FileInfo.Network}");
Console.WriteLine($"Packets: {model.Packets.Count}");

Stream mixed events from ASC or BLF

using Hsu.Formats.Asc;
using Hsu.Formats.Trace;

var parser = new AscParser();
using var stream = File.OpenRead("log.asc");

EventParseSession session = parser.ParseEventsAsync(stream);
var model = (ITraceEventLog)session.Model;

await foreach (var traceEvent in session.Events)
    Console.WriteLine($"{traceEvent.EventKind} @ {traceEvent.Timestamp}");

Stream Ethernet packets from PCAP

using Hsu.Formats.Ethernet;
using Hsu.Formats.Pcap;

var parser = new PcapParser();
using var stream = File.OpenRead("capture.pcap");

EthernetParseSession session = parser.ParsePacketsAsync(stream);
var model = (PcapModel)session.Model;

await foreach (var packet in session.Packets)
    Console.WriteLine($"{packet.Timestamp.TotalSeconds:F6}s  {packet.Data.Length} bytes");

Conversion Notes

Trace/capture conversions live in Hsu.Formats.Converters.Trace, but a few behavior boundaries are important:

• ASC/BLF -> PCAP/PCAPNG export Ethernet event subsets as capture packets
• PCAP/PCAPNG -> ASC/BLF restore packets as Ethernet events in the official target-format syntax
• PCAP/PCAPNG -> ASC/BLF are Ethernet-oriented conversions, not CAN decoding
• Some capture-specific metadata may be normalized when converting into trace-log formats that do not have direct fields for every source concept
• PCAPNG -> PCAP necessarily flattens a richer multi-interface model into PCAP’s single-interface file model

Writer Notes

• AscWriter emits official Vector Ethernet packet lines only
• PcapWriter always emits little-endian output
• PcapngWriter always emits little-endian SHB/IDB/EPB blocks
• PcapngWriter preserves RawTimestamp when present and reconstructs it from Timestamp only when needed

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.