Conformance

Logb is a format, so the question that matters is not "does the reference library work?" but "does the reader you wrote agree with the specification?" This page collects the things you can check that against.

The bit-numbering vectors are normative

Specification §6.2 carries a table of bit-extraction vectors, and that table — not the prose around it — is the specification of bit numbering. An implementation that reproduces it has the rule right; one that does not, does not.

This is deliberate. MDF4 and DBC do not disagree about bit numbering because anyone was careless; they disagree because the rule is genuinely hard to state in English, and every prose statement of it that has ever been written — including earlier drafts of that section — has been ambiguous or wrong. Vectors do not have that failure mode.

The row to check first is the big-endian, unaligned, byte-crossing field:

That is the case with no defined meaning in MDF4, and the one every CAN tool carries scar tissue from. If your extractor produces `0x91A` there, and reproduces the rest of the table in §6.2, the hard part is done. The reasoning behind the rule, with diagrams, is in the CAN note.

The golden file

`testdata/can-example.logb` in the reference repository is a conformance artifact rather than a convenience. It is byte-reproducible: regenerating it must produce identical bytes, so if the bytes change, the format changed. It exercises multiple segments, mixed byte orders, variable-length fields and compression in one file.

Two things to try with it, corresponding to two of the six design rules:

• Rule 3, cut anywhere. Hand your reader the file starting from an arbitrary

offset — not a frame boundary. It should scan forward to the next SYNC frame and decode every subsequent record with full schema. Records before the cut are gone; nothing after it should be.

• Rule 2, truncation. Truncate the file at an arbitrary byte. It should read

as a valid file containing every record up to the last intact frame, and report that it was truncated rather than erroring. A truncated file is not a damaged file that needs repair; it is a shorter file.

A checklist for a new reader

• Multi-byte integers in the format's own structures are always little-endian,

regardless of what any record field declares (§2).

• Strings are UTF-8 and `u32` length-prefixed — not NUL-terminated (§2).
• `crc32c` is CRC-32 with the Castagnoli polynomial `0x1EDC6F41` (§2).
• Unknown frame types are skipped by length and cost nothing. Unknown

codecs or filters cost that frame. An unknown axis mode costs that stream. Nothing unknown should ever produce a value (§4.2).

• `stream_id` is segment-scoped. Do not treat it as a file-wide identifier, or

concatenated files will alias. Identity across segments and files is `stream_uuid` (§6.6).

• The INDEX and END frames are optional. A reader that requires them fails on

every file that lost power, which is the case the format exists to handle (§9).

• Signed fields are two's complement and sign-extended on decode at their

declared width, not at 8/16/32/64 (§6.3).

Reporting a disagreement

If your implementation and the reference implementation disagree, one of three things is true: the specification is ambiguous, the reference implementation is wrong, or your reader is. The first two are worth an issue on the repository — the specification has already been corrected several times by exactly this route, and those corrections are listed on the status page.