Crate apitrace

Crate apitrace 

Source
Expand description

Apitrace binary trace file reader/writer

This module implements parsing for apitrace trace files according to the FORMAT.markdown specification from the apitrace project.

§File Format Overview (per FORMAT.markdown)

§Compression

Trace files use custom compression (Snappy by default):

  • Snappy: 'a' 't' header + chunks (compressed_length:uint32 + compressed_data)
  • Also supports gzip and Brotli

§Structure (after decompression)

trace = header event*
header = version_no semantic_version_no properties  // version >= 6
       | version_no                                 // version < 6
event = enter_call | leave_call

§Version History

  • Version 0: Initial implementation
  • Version 1: OpenGL user arrays as blobs
  • Version 2: malloc/free memory calls
  • Version 3: Enum signatures with full name/value pairs
  • Version 4: Call enter events include thread number
  • Version 5: Call backtrace support
  • Version 6: Unicode strings, semantic version, properties, fake flag

§Key Concepts

  • Variable-length unsigned integers (uint) for space efficiency
  • Signature-based type system: First occurrence includes definition, later uses reference by ID
  • Applies to: call signatures, enum signatures, bitmask signatures, struct signatures, frame signatures

§Current Implementation Status

  • ✓ Basic parsing of version 5-6 traces
  • ✓ Call signatures and interleaved enter/leave events
  • ✓ Call details with proper terminator handling
  • ✓ Backtrace frame parsing with detail terminators
  • ✓ Enum signature parsing (sint values, both version >= 3 and < 3)
  • ✓ Wide string parsing (uint* not bytes)
  • ✓ Bitmask signature parsing (uint values)
  • ✓ Struct signature parsing
  • ✓ Value skipping for extracting call names

§Key Implementation Details

  • Enum, bitmask, and struct signatures share the same ID space in the file format, but must be tracked in separate namespaces to avoid signature type collisions
  • Backtrace frame signatures are cached to avoid re-reading frame details

§Known Limitations

  • Version < 5 header support (version 5+ traces work fully)
  • File offset tracking for signature reuse (affects seeking/rewinding scenarios)
  • Some complex edge cases in deeply nested structures

Modules§

call_flags
compression
Compression support for apitrace trace files
dump
gc
Garbage collection for apitrace trace files
write
Writing support for apitrace trace files

Structs§

Apitrace
Context type for apitrace binary format parsing
Bitmask
BitmaskFlag
A single flag in a bitmask signature Per FORMAT.markdown: bitmask_sig contains (name, uint) pairs
BitmaskSig
Bitmask signature defining flag names and values Per FORMAT.markdown: bitmask_sig = id count (name uint)+
Call
CallIterator
Iterator for parsing calls from an apitrace trace file
CallSig
CallSigBody
EnumSig
Header
Property
StructSig
TraceReader
Reader for apitrace trace files

Enums§

CallDetail
Call detail types that can appear in enter/leave events Per FORMAT.markdown Calls section: call_detail = 0x00 // terminator | 0x01 arg_no value // argument value | 0x02 value // return value | 0x03 thread_no // thread number (version_no < 4) | 0x04 count frame* // stack backtrace | 0x05 uint // flag
EnumVal
Value

Functions§

repack