Rogue File Data Format

The default on-disk record format used by StreamWriter and consumed by StreamReader is documented here.

Default Framed Mode

In default mode (raw disabled), each frame is written as one record:

record := headerA (4 bytes) + headerB (4 bytes) + payload (N bytes)

Both headers are 32-bit little-endian words.

Record Layout Diagram

Byte-level layout of one record on disk:

Offset  Size  Field
------  ----  --------------------------------------------
0x00    4     headerA (uint32, little-endian)
0x04    4     headerB (uint32, little-endian)
0x08    N     payload bytes (exact frame payload)

Visualized as contiguous bytes:

+--------------------+--------------------+------------------------...------+
| headerA[31:0] LE   | headerB[31:0] LE   | payload[0] ... payload[N-1]    |
+--------------------+--------------------+------------------------...------+

Header field layout:

headerA:
    31:0  = (payload_bytes + 4)
            // payload size plus the 4-byte headerB word

headerB:
   31:24  = Channel ID passed to writeFile(channel, frame)
   23:16  = Frame error field (frame->getError())
    15:0  = Lower 16 bits of frame flags (frame->getFlags())

Bit-level view of headerB:

31            24 23            16 15                             0
+----------------+----------------+-------------------------------+
|   Channel ID   |  Frame Error   |      Frame Flags[15:0]       |
+----------------+----------------+-------------------------------+

Concrete Example

If a frame has:

  • Payload length = 0x20 bytes

  • Channel = 0x03

  • Error = 0x00

  • Flags (low 16) = 0x00A5

Then:

  • headerA = payload + 4 = 0x00000024

  • headerB = 0x030000A5

On disk (little-endian bytes):

headerA: 24 00 00 00
headerB: A5 00 00 03
payload: <32 payload bytes follow>

Notes:

  • Payload bytes are written exactly as they appear in the source frame buffers.

  • The lower 16 bits of Frame.flags are persisted in the file.

Metadata Semantics

Frame.flags is a 16-bit metadata field. In many AXI-Stream/SSI flows, it is used to carry TUSER sideband information:

  • Bits [7:0] often represent first-tuser (SOF-side metadata)

  • Bits [15:8] often represent last-tuser (EOF-side metadata)

The exact interpretation is protocol-dependent. StreamWriter stores this value without modification so downstream software can decode it in the correct protocol context.

Frame.error is an 8-bit status field stored in headerB[23:16]. Rogue typically treats non-zero values as errored frames, but specific bit meanings or enumerations are producer/protocol specific.