libaaruformat 1.0 Aaru Data Preservation Suite - Format Library

Loading...
Searching...
No Matches
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().