consts.h File Reference

Core public constants and compile‑time limits for the Aaru container format implementation. More...

Go to the source code of this file.

Macros
#define	DIC_MAGIC   0x544D52464D434944ULL
	Magic identifier for legacy DiscImageChef container (ASCII "DICMFRMT").
#define	AARU_MAGIC   0x544D524655524141ULL
	Magic identifier for AaruFormat container (ASCII "AARUFRMT").
#define	AARUF_VERSION   2
	Current image format major version (incompatible changes bump this).
#define	AARUF_VERSION_V1   1
	First on‑disk version (C# implementation).
#define	AARUF_VERSION_V2   2
	Second on‑disk version (C implementation).
#define	MAX_CACHE_SIZE   536870912ULL
	Maximum read cache size (bytes).
#define	LZMA_PROPERTIES_LENGTH   5
	Size in bytes of the fixed LZMA properties header (lc/lp/pb + dictionary size).
#define	MAX_DDT_ENTRY_CACHE   16000000
	Maximum number of cached DDT entry descriptors retained in memory for fast duplicate detection.
#define	SAMPLES_PER_SECTOR   588
	Red Book (CD‑DA) PCM samples per 2352‑byte sector: 44,100 Hz / 75 sectors per second = 588 samples.
#define	MAX_FLAKE_BLOCK   4608
	FLAC maximum block size used for encoding audio sectors.
#define	MIN_FLAKE_BLOCK   256
	FLAC minimum block size.
#define	CD_XFIX_MASK   0xFF000000U
	Mask for extracting correction / fix flags in Compact Disc suffix/prefix DDT entries.
#define	CD_DFIX_MASK   0x00FFFFFFU
	Mask for extracting positional index (lower 24 bits) in Compact Disc suffix/prefix deduplicated block entries.

Detailed Description

Core public constants and compile‑time limits for the Aaru container format implementation.

This header exposes magic identifiers, format version selectors, resource limits, codec parameter bounds, and bit masks used across libaaruformat. All values are immutable interface contracts; changing them breaks backward compatibility unless a new format version is declared.

Summary:

• Magic numbers (DIC_MAGIC, AARU_MAGIC) identify container families (legacy DiscImageChef vs AaruFormat).
• Version macros distinguish format generations (V1 C# / legacy CRC endianness, V2 current C implementation).
• Cache and table size limits provide protective upper bounds against runaway memory consumption.
• Audio constants (SAMPLES_PER_SECTOR, MIN/MAX_FLAKE_BLOCK) align with Red Book (CD‑DA) and FLAC encoding best practices.
• CD_* masks assist with extracting flags / positional subfields in deduplicated Compact Disc sector tables.
• CRC64 constants implement ECMA‑182 polynomial and standard seed, enabling deterministic end‑to‑end block integrity.

Notes:

• Magic values are stored little‑endian on disk when written as 64‑bit integers; when inspecting raw bytes make sure to account for host endianness.
• AARUF_VERSION must be incremented only when an incompatible on‑disk layout change is introduced.
• MAX_DDT_ENTRY_CACHE is a soft upper bound sized to balance deduplication hit rate vs RAM; tune in future builds via configuration if adaptive heuristics are introduced.
• The LZMA properties length (5) derives from the standard LZMA header (lc/lp/pb + dict size) and is constant for raw LZMA streams used here.
• FLAC sample block guidance: empirical evaluation shows >4608 samples per block does not yield meaningful ratio gains for typical optical audio captures while increasing decode buffer size.

Thread safety: All macros are compile‑time constants; no synchronization required. Portability: Constants chosen to fit within 64‑bit targets; arithmetic assumes two's complement.

Definition in file consts.h.

Macro Definition Documentation

AARU_MAGIC

#define AARU_MAGIC   0x544D524655524141ULL

Magic identifier for AaruFormat container (ASCII "AARUFRMT").

Used in the primary header to assert correct file type.

Definition at line 64 of file consts.h.

Referenced by aaruf_clear_comments(), aaruf_clear_creator(), aaruf_clear_drive_firmware_revision(), aaruf_clear_drive_manufacturer(), aaruf_clear_drive_model(), aaruf_clear_drive_serial_number(), aaruf_clear_media_barcode(), aaruf_clear_media_manufacturer(), aaruf_clear_media_model(), aaruf_clear_media_part_number(), aaruf_clear_media_sequence(), aaruf_clear_media_serial_number(), aaruf_clear_media_title(), aaruf_close(), aaruf_close_current_block(), aaruf_create(), aaruf_get_aaru_json_metadata(), aaruf_get_all_tape_files(), aaruf_get_all_tape_partitions(), aaruf_get_cicm_metadata(), aaruf_get_comments(), aaruf_get_creator(), aaruf_get_drive_firmware_revision(), aaruf_get_drive_manufacturer(), aaruf_get_drive_model(), aaruf_get_drive_serial_number(), aaruf_get_dumphw(), aaruf_get_geometry(), aaruf_get_image_info(), aaruf_get_media_barcode(), aaruf_get_media_manufacturer(), aaruf_get_media_model(), aaruf_get_media_part_number(), aaruf_get_media_sequence(), aaruf_get_media_serial_number(), aaruf_get_media_title(), aaruf_get_negative_sectors(), aaruf_get_overflow_sectors(), aaruf_get_readable_media_tags(), aaruf_get_readable_sector_tags(), aaruf_get_tape_file(), aaruf_get_tape_partition(), aaruf_get_tracks(), aaruf_get_user_sectors(), aaruf_identify_stream(), aaruf_open(), aaruf_read_media_tag(), aaruf_read_sector(), aaruf_read_sector_long(), aaruf_read_sector_tag(), aaruf_read_track_sector(), aaruf_set_aaru_json_metadata(), aaruf_set_comments(), aaruf_set_creator(), aaruf_set_drive_firmware_revision(), aaruf_set_drive_manufacturer(), aaruf_set_drive_model(), aaruf_set_drive_serial_number(), aaruf_set_dumphw(), aaruf_set_geometry(), aaruf_set_media_barcode(), aaruf_set_media_manufacturer(), aaruf_set_media_model(), aaruf_set_media_part_number(), aaruf_set_media_sequence(), aaruf_set_media_serial_number(), aaruf_set_media_title(), aaruf_set_tape_file(), aaruf_set_tape_partition(), aaruf_set_tracks(), aaruf_verify_image(), aaruf_write_media_tag(), aaruf_write_sector(), aaruf_write_sector_long(), and aaruf_write_sector_tag().

AARUF_VERSION

#define AARUF_VERSION   2

Current image format major version (incompatible changes bump this).

Readers should reject headers with a higher number unless explicitly forward compatible.

Definition at line 68 of file consts.h.

Referenced by aaruf_identify_stream(), and aaruf_open().

AARUF_VERSION_V1

#define AARUF_VERSION_V1   1

First on‑disk version (C# implementation).

Quirk: CRC64 values were stored byte‑swapped relative to ECMA‑182 canonical output.

Definition at line 71 of file consts.h.

Referenced by aaruf_verify_image(), process_data_block(), process_dumphw_block(), process_tracks_block(), verify_index_v1(), verify_index_v2(), and verify_index_v3().

AARUF_VERSION_V2

#define AARUF_VERSION_V2   2

Second on‑disk version (C implementation).

Introduced: extended header (GUID, feature bitmaps), hierarchical DDT v2, improved index (v2/v3), multi‑codec compression, refined metadata blocks.

Definition at line 75 of file consts.h.

Referenced by aaruf_create(), and aaruf_open().

CD_DFIX_MASK

#define CD_DFIX_MASK   0x00FFFFFFU

Mask for extracting positional index (lower 24 bits) in Compact Disc suffix/prefix deduplicated block entries.

Definition at line 102 of file consts.h.

Referenced by aaruf_read_sector_long().

CD_XFIX_MASK

#define CD_XFIX_MASK   0xFF000000U

Mask for extracting correction / fix flags in Compact Disc suffix/prefix DDT entries.

High 8 bits store status (see SectorStatus / CdFixFlags relationships).

Definition at line 100 of file consts.h.

Referenced by aaruf_read_sector_long().

DIC_MAGIC

#define DIC_MAGIC   0x544D52464D434944ULL

Magic identifier for legacy DiscImageChef container (ASCII "DICMFRMT").

Retained for backward compatibility / migration tooling.

Definition at line 61 of file consts.h.

Referenced by aaruf_identify_stream(), and aaruf_open().

LZMA_PROPERTIES_LENGTH

#define LZMA_PROPERTIES_LENGTH   5

Size in bytes of the fixed LZMA properties header (lc/lp/pb + dictionary size).

Definition at line 82 of file consts.h.

Referenced by aaruf_close_current_block(), aaruf_read_sector(), decode_ddt_multi_level_v2(), process_data_block(), process_ddt_v1(), process_ddt_v2(), set_ddt_multi_level_v2(), write_cached_secondary_ddt(), write_dvd_long_sector_blocks(), write_dvd_title_key_decrypted_block(), write_media_tags(), write_mode2_subheaders_block(), write_sector_prefix(), write_sector_prefix_ddt(), write_sector_subchannel(), write_sector_suffix(), write_sector_suffix_ddt(), and write_single_level_ddt().

MAX_CACHE_SIZE

#define MAX_CACHE_SIZE   536870912ULL

Maximum read cache size (bytes).

512 MiB chosen to prevent excessive resident memory while still enabling efficient sequential and moderate random access patterns.

Definition at line 79 of file consts.h.

Referenced by aaruf_create(), and aaruf_open().

MAX_DDT_ENTRY_CACHE

#define MAX_DDT_ENTRY_CACHE   16000000

Maximum number of cached DDT entry descriptors retained in memory for fast duplicate detection.

At 16,000,000 entries with a compact structure, this caps hash_map overhead while covering large images. (Approx memory just for lookup bookkeeping: ~16 bytes * N ≈ 256 MB worst case; typical effective <50% of cap.)

Definition at line 87 of file consts.h.

MAX_FLAKE_BLOCK

#define MAX_FLAKE_BLOCK   4608

FLAC maximum block size used for encoding audio sectors.

Empirically >4608 samples yields diminishing compression returns and higher decode latency.

Definition at line 94 of file consts.h.

Referenced by aaruf_close_current_block().

MIN_FLAKE_BLOCK

#define MIN_FLAKE_BLOCK   256

FLAC minimum block size.

CUETools.Codecs.FLAKE does not accept blocks smaller than 256 samples.

Definition at line 96 of file consts.h.

Referenced by aaruf_close_current_block().

SAMPLES_PER_SECTOR

#define SAMPLES_PER_SECTOR   588

Red Book (CD‑DA) PCM samples per 2352‑byte sector: 44,100 Hz / 75 sectors per second = 588 samples.

Definition at line 90 of file consts.h.

Referenced by aaruf_close_current_block().