NVMEM Cells and Byte Order: Decode Factory Data Without Treating a Blob as a C Struct

Treat an NVMEM cell as bytes with a documented consumer format. Validate the returned length and version, decode each field with explicit byte order and signedness, then check its meaning before use. Casting the buffer to a native C structure can accidentally depend on CPU byte order, alignment, and compiler layout.

This guide is pinned to Linux v6.12 NVMEM. It covers interpreting an already identified cell, not discovering variable-offset cells in a dynamic layout. Provider bindings and factory-format documents remain authoritative. The small format below is invented for software testing and is not calibration for any real device.

1. Define the bytes the consumer actually receives

The NVMEM framework documentation provides cell-based reads and also permits layouts with post-processing hooks. The v6.12 implementation can extract bit fields and invoke a cell’s post-processing callback before returning the consumer buffer. A raw device dump and the cell API result are therefore not always identical views.

Write a format sheet identifying the provider, cell name, binding revision, raw storage representation, transformations, returned length, field offsets, byte order, signedness, scale, reserved bits, and invalid-value rules. Name the owner of each transformation so two layers do not both swap or scale the same field.

If the provider already normalizes a MAC address or other field, test the consumer against that normalized contract. If it returns a device-specific byte sequence unchanged, decode that sequence explicitly. Do not infer either behavior solely from a familiar cell name.

2. Keep API success separate from format acceptance

In v6.12, nvmem_cell_read returns an error pointer or an allocated buffer, populates its length on success, and requires the consumer to free the buffer with kfree. Review these ownership and error paths in the pinned source. A failed read must not leave a previously used buffer looking like new valid factory data.

After a successful read, validate length before accessing fields. Reject truncated, unexpectedly extended, or unsupported-version records according to the documented format. Do not silently substitute zeroes for missing bytes. If the product permits a default, make that a separately approved behavior with an observable reason.

Be careful with convenience helpers. In v6.12, the fixed-width nvmem_cell_read_u32 path checks length and copies bytes into the destination; the explicitly named variable-length little-endian helper performs little-endian assembly. Neither name replaces a review of the actual provider and data format.

3. Avoid the native-structure shortcut

A structure declaration describes an in-memory representation for a particular compilation environment. It is not automatically a stable stored-data specification. Packing can change padding, but does not establish the intended byte order, field validity, or version semantics.

The Linux 6.12 unaligned-access guide explains why access through an improperly aligned typed pointer is not portable. Use the kernel’s appropriate unaligned and endian-aware access facilities, or explicit byte assembly, after bounds checks. Keep the decode result in an ordinary internal structure only after the byte format has been accepted.

Do not search permutations until a plausible value appears. A calibration coefficient can look reasonable under more than one interpretation. The oracle must be the documented manufacturing format and known reference fixtures, not the desired displayed value.

4. Create a small byte-level oracle

For illustration, define a six-byte test record: byte 0 is version 1; byte 1 must be 1; bytes 2–3 are a signed little-endian 16-bit offset; bytes 4–5 are an unsigned little-endian 16-bit gain constrained to 1–4,000. These names and limits have no hardware meaning.

def decode_fixture(raw):
    if len(raw) != 6:
        raise ValueError('length')
    if raw[0] != 1:
        raise ValueError('version')
    if raw[1] != 1:
        raise ValueError('flags')
    offset = int.from_bytes(raw[2:4], 'little', signed=True)
    gain = int.from_bytes(raw[4:6], 'little', signed=False)
    if not 1 <= gain <= 4000:
        raise ValueError('gain range')
    return offset, gain

This original Python decoder was executed on Python 3.12.14 with two valid and six invalid synthetic cases. It does not call NVMEM or execute kernel code. The offline evidence includes the complete runner, observed output, tool version, and limitations.

Synthetic bytes or change	Expected result
01 01 9c ff e8 03	Offset −100, gain 1,000.
01 01 34 12 01 08	Offset 4,660, gain 2,049.
Empty or five-byte input.	Reject length.
Version changed to 2.	Reject unsupported version.
Flags changed to 3.	Reject the reserved-bit combination.
Gain encoded as 0 or 4,001.	Reject the declared range.

The asymmetric byte patterns expose accidental swaps better than all-zero or repeated-byte fixtures. A real format may require a checksum, signature, unit binding, or additional validity checks. This deliberately small decoder supplies none of those and must not be presented as a complete factory-data verifier.

5. Test the integration boundary separately

1. Use a synthetic provider or controlled test cell with known bytes and no secrets.
2. Confirm the selected cell and returned length under the actual binding and provider revision.
3. Compare raw and returned bytes where permitted, documenting any bit extraction or post-processing.
4. Feed the accepted bytes through the production decoder and compare exact fields with the independent oracle.
5. Exercise read errors, missing cells, invalid lengths, and unsupported versions without publishing stale or defaulted values as validated data.
6. Run the production implementation on each supported architecture or suitable execution target; a Python test alone does not prove a C driver’s portability.

Keep this read-focused qualification separate from programming. Do not rewrite OTP, credentials, identity, or calibration to make a decoder test convenient. Use authorized synthetic storage and retain unit-specific data under the product’s access policy.

Hypothetical architecture change

A driver copied a two-byte cell into a native integer and passed tests on one CPU. A port to another byte order changes the decoded value while the stored bytes remain unchanged. The fix is to establish the provider’s returned format and decode it explicitly, then add asymmetric fixtures to the regression suite.

Release with a versioned format sheet, ownership rules, exact byte fixtures, and target integration evidence. A valid NVMEM read proves access to the cell; the decoder contract establishes whether its contents can be used.