fzm_format.h File Reference

FZM binary file format definitions — structs, enums, and helpers. More...

#include <cstdint>
#include <cstring>
#include <stdexcept>
#include <string>

Go to the source code of this file.

Classes
struct	fz::FZMStageInfo
	Per-stage metadata record written into the FZM header (256 bytes). More...
struct	fz::FZMBufferEntry
	Per-buffer metadata record written into the FZM header (256 bytes). More...
struct	fz::FZMHeaderCore
	Fixed-size FZM file header core (80 bytes). More...

Enumerations
enum class	fz::StageType : uint16_t
	Stage type identifiers written into the FZM header. More...
enum class	fz::DataType : uint8_t { }
	Element data type identifiers used in buffer and stage descriptors. More...

Functions
constexpr uint8_t	fz::fzmVersionMajor (uint16_t v)
constexpr uint8_t	fz::fzmVersionMinor (uint16_t v)
size_t	fz::getDataTypeSize (DataType type)
std::string	fz::dataTypeToString (DataType type)
std::string	fz::stageTypeToString (StageType type)

Variables
constexpr uint32_t	fz::FZM_MAGIC = 0x464D5A32
constexpr uint8_t	fz::FZM_VERSION_MAJOR = 3
constexpr size_t	fz::FZM_LEGACY_HEADER_CORE_SIZE = 72
constexpr uint16_t	fz::FZM_FLAG_HAS_DATA_CHECKSUM = 0x0001u
	data_checksum field is valid
constexpr uint16_t	fz::FZM_FLAG_HAS_HEADER_CHECKSUM = 0x0002u
	header_checksum field is valid
constexpr size_t	fz::FZM_MAX_BUFFERS = 32
	Maximum pipeline output buffers per file.
constexpr size_t	fz::FZM_MAX_NAME_LEN = 64
	Maximum output port name length (bytes, null-terminated)
constexpr size_t	fz::FZM_STAGE_CONFIG_SIZE = 128
	Per-stage serialized config slot (bytes)
constexpr size_t	fz::FZM_MAX_SOURCES = 4
	Maximum source stages per pipeline.

Detailed Description

FZM binary file format definitions — structs, enums, and helpers.

On-disk layout:

[FZMHeaderCore]                     (80 bytes)
[FZMStageInfo × num_stages]         (256 × num_stages bytes)
[FZMBufferEntry × num_buffers]      (256 × num_buffers bytes)
[compressed data payload]           (compressed_size bytes)

Version history:

• v3.0: initial versioned format (FZMHeaderCore = 72 bytes)
• v3.1: added flags, data_checksum, header_checksum (FZMHeaderCore = 80 bytes)

Enumeration Type Documentation

StageType

enum class fz::StageType : uint16_t

strong

Stage type identifiers written into the FZM header.

Each concrete Stage subclass reports one of these values via getStageTypeId(). Used by StageFactory::createStage() to reconstruct the pipeline during decompression.

DataType

enum class fz::DataType : uint8_t

strong

Element data type identifiers used in buffer and stage descriptors.

Returned by Stage::getOutputDataType() and Stage::getInputDataType(). UNKNOWN is returned by byte-transparent stages (Bitshuffle, RZE) to opt out of Pipeline::finalize() type-compatibility checking.

Enumerator
UNKNOWN	Byte-transparent stages: skip type checking at finalize()

Function Documentation

fzmVersionMajor()

constexpr uint8_t fz::fzmVersionMajor ( uint16_t  v )

constexpr

Extract major version from a raw on-disk version field. Pre-split files stored small integers (e.g. 3); values ≤ 0xFF are treated as (major=value, minor=0).

fzmVersionMinor()

constexpr uint8_t fz::fzmVersionMinor ( uint16_t  v )

constexpr

Extract minor version from a raw on-disk version field (see fzmVersionMajor).

getDataTypeSize()

size_t fz::getDataTypeSize ( DataType  type )

inline

Returns the size in bytes of the given DataType. Throws for DataType::UNKNOWN.

dataTypeToString()

std::string fz::dataTypeToString ( DataType  type )

inline

Returns a human-readable string for the given DataType (e.g. "float32").

stageTypeToString()

std::string fz::stageTypeToString ( StageType  type )

inline

Returns a human-readable string for the given StageType (e.g. "LorenzoQuant").

Variable Documentation

FZM_MAGIC

constexpr uint32_t fz::FZM_MAGIC = 0x464D5A32

constexpr

FZM magic number ("FZM2" in little-endian).

FZM_VERSION_MAJOR

constexpr uint8_t fz::FZM_VERSION_MAJOR = 3

constexpr

Version encoding: high byte = major, low byte = minor.

Major mismatch → throw. Minor mismatch → warn and continue. Pre-split files stored a bare integer (e.g. 3); those are treated as major = value, minor = 0, so FZM_VERSION = 0x0300 is backward-compatible.

v3.0 → v3.1: FZMHeaderCore grew from 72 to 80 bytes; added flags, data_checksum, and header_checksum fields.

FZM_LEGACY_HEADER_CORE_SIZE

constexpr size_t fz::FZM_LEGACY_HEADER_CORE_SIZE = 72

constexpr

FZMHeaderCore size for v3.0 files (before checksums). Used by readHeader() to avoid overrunning the stage array.