diff --git a/docs/spec/blocks/aaru_metadata.adoc b/docs/spec/blocks/aaru_metadata.adoc
index fe210eb..e575a28 100644
--- a/docs/spec/blocks/aaru_metadata.adoc
+++ b/docs/spec/blocks/aaru_metadata.adoc
@@ -8,12 +8,11 @@ The contents of the JSON are preserved in their original form and are not parsed
[source,c]
#define METADATA_JSON_MAGIC 0x444D534A
/**Header for the Aaru Metadata JSON block */
-typedef struct AaruMetadataJsonBlock
+typedef struct AaruMetadataJsonBlockHeader
{
- /**Identifier, */
- uint32_t identifier;
- uint32_t length;
-} AaruMetadataJsonBlock;
+ uint32_t identifier; ///< Block identifier, must be BlockType::AaruMetadataJsonBlock.
+ uint32_t length; ///< Length in bytes of the Aaru metadata JSON payload that follows.
+} AaruMetadataJsonBlockHeader;
==== Field Descriptions
diff --git a/docs/spec/blocks/checksum.adoc b/docs/spec/blocks/checksum.adoc
index ae7c288..cd98915 100644
--- a/docs/spec/blocks/checksum.adoc
+++ b/docs/spec/blocks/checksum.adoc
@@ -15,12 +15,9 @@ If the image is modified, the checksum block is considered outdated and should b
* */
typedef struct ChecksumHeader
{
- /**Identifier, */
- uint32_t identifier;
- /**Length in uint8_ts of the block */
- uint32_t length;
- /**How many checksums follow */
- uint8_t entries;
+ uint32_t identifier; ///< Block identifier, must be BlockType::ChecksumBlock.
+ uint32_t length; ///< Length in bytes of the payload (all entries + their digest data, excluding this header).
+ uint8_t entries; ///< Number of checksum entries that follow in the payload.
} ChecksumHeader;
==== Field Descriptions
@@ -54,10 +51,8 @@ typedef struct ChecksumHeader
/**Checksum entry, followed by checksum data itself */
typedef struct ChecksumEntry
{
- /**Checksum algorithm */
- uint8_t type;
- /**Length in uint8_ts of checksum that follows this structure */
- uint32_t length;
+ uint8_t type; ///< Algorithm used (value from \ref ChecksumAlgorithm).
+ uint32_t length; ///< Length in bytes of the digest that immediately follows this structure.
} ChecksumEntry;
==== Field Descriptions
diff --git a/docs/spec/blocks/cicm.adoc b/docs/spec/blocks/cicm.adoc
index 223e450..23498ec 100644
--- a/docs/spec/blocks/cicm.adoc
+++ b/docs/spec/blocks/cicm.adoc
@@ -10,9 +10,8 @@ The contents of the XML are preserved in their original form and are not parsed,
/**Header for the CICM XML metadata block */
typedef struct CicmMetadataBlock
{
- /**Identifier, */
- uint32_t identifier;
- uint32_t length;
+ uint32_t identifier; ///< Block identifier, must be BlockType::CicmBlock.
+ uint32_t length; ///< Length in bytes of the CICM metadata payload that follows.
} CicmMetadataBlock;
==== Field Descriptions
diff --git a/docs/spec/blocks/data.adoc b/docs/spec/blocks/data.adoc
index ed0ecea..f2f7fdf 100644
--- a/docs/spec/blocks/data.adoc
+++ b/docs/spec/blocks/data.adoc
@@ -14,22 +14,14 @@ Conversely, if the block contains a single item (e.g., media tags), `sectorSize`
/**Block header, precedes block data */
typedef struct BlockHeader
{
- /**Identifier, */
- uint32_t identifier;
- /**Type of data contained by this block */
- uint16_t type;
- /**Compression algorithm used to compress the block */
- uint16_t compression;
- /**Size in uint8_ts of each sector contained in this block */
- uint32_t sectorSize;
- /**Compressed length for the block */
- uint32_t cmpLength;
- /**Uncompressed length for the block */
- uint32_t length;
- /**CRC64-ECMA of the compressed block */
- uint64_t cmpCrc64;
- /**CRC64-ECMA of the uncompressed block */
- uint64_t crc64;
+ uint32_t identifier; ///< Block identifier, must be BlockType::DataBlock.
+ uint16_t type; ///< Logical data classification (value from \ref DataType).
+ uint16_t compression; ///< Compression algorithm used (value from \ref CompressionType).
+ uint32_t sectorSize; ///< Size in bytes of each logical sector represented in this block.
+ uint32_t cmpLength; ///< Size in bytes of the compressed payload immediately following this header.
+ uint32_t length; ///< Size in bytes of the uncompressed payload resulting after decompression.
+ uint64_t cmpCrc64; ///< CRC64-ECMA of the compressed payload (cmpLength bytes).
+ uint64_t crc64; ///< CRC64-ECMA of the uncompressed payload (length bytes).
} BlockHeader;
==== Field Descriptions
diff --git a/docs/spec/blocks/ddt.adoc b/docs/spec/blocks/ddt.adoc
index 4072ca0..be14eb6 100644
--- a/docs/spec/blocks/ddt.adoc
+++ b/docs/spec/blocks/ddt.adoc
@@ -13,24 +13,15 @@ Every image must include at least one deduplication table of type `UserData`.
/**Header for a deduplication table. Table follows it */
typedef struct DdtHeader
{
- /**Identifier, */
- uint32_t identifier;
- /**Type of data pointed by this DDT */
- uint16_t type;
- /**Compression algorithm used to compress the DDT */
- uint16_t compression;
- /**Each entry is ((uint8_t offset in file) << shift) + (sector offset in block) */
- uint8_t shift;
- /**How many entries are in the table */
- uint64_t entries;
- /**Compressed length for the DDT */
- uint64_t cmpLength;
- /**Uncompressed length for the DDT */
- uint64_t length;
- /**CRC64-ECMA of the compressed DDT */
- uint64_t cmpCrc64;
- /**CRC64-ECMA of the uncompressed DDT */
- uint64_t crc64;
+ uint32_t identifier; ///< Block identifier, must be BlockType::DeDuplicationTable.
+ uint16_t type; ///< Data classification (\ref DataType) for sectors referenced by this table.
+ uint16_t compression; ///< Compression algorithm for the table body (\ref CompressionType).
+ uint8_t shift; ///< Left shift applied to per-entry file offset component forming logicalEntryValue.
+ uint64_t entries; ///< Number of deduplication entries contained in (uncompressed) table.
+ uint64_t cmpLength; ///< Size in bytes of compressed entries payload.
+ uint64_t length; ///< Size in bytes of uncompressed entries payload.
+ uint64_t cmpCrc64; ///< CRC64-ECMA of the compressed payload.
+ uint64_t crc64; ///< CRC64-ECMA of the uncompressed payload.
} DdtHeader;
==== Field Descriptions
diff --git a/docs/spec/blocks/ddt2.adoc b/docs/spec/blocks/ddt2.adoc
index 1ef45e6..353acb6 100644
--- a/docs/spec/blocks/ddt2.adoc
+++ b/docs/spec/blocks/ddt2.adoc
@@ -6,42 +6,26 @@ It starts with the following header.
[source,c]
typedef struct DdtHeader2
{
- /**Identifier, */
- uint32_t identifier;
- /**Type of data pointed by this DDT */
- uint16_t type;
- /**Compression algorithm used to compress the DDT */
- uint16_t compression;
- /**How many levels of subtables are present */
- uint8_t levels;
- /**Which level this table belongs to */
- uint8_t tableLevel;
- /**Pointer to absolute byte offset in file where the previous level table is located */
- uint64_t previousLevelOffset;
- /**Negative displacement of LBAs */
- uint16_t negative;
- /**Number of blocks in media */
- uint64_t blocks;
- /**Positive overflow displacement of LBAs */
- uint16_t overflow;
- /**First LBA contained in this table */
- uint64_t start;
- /**Block alignment boundaries */
- uint8_t blockAlignmentShift;
- /**Data shift */
- uint8_t dataShift;
- /**Table shift */
- uint8_t tableShift;
- /**Entries in this table */
- uint64_t entries;
- /**Compressed length for the DDT */
- uint64_t cmpLength;
- /**Uncompressed length for the DDT */
- uint64_t length;
- /**CRC64-ECMA of the compressed DDT */
- uint64_t cmpCrc64;
- /**CRC64-ECMA of the uncompressed DDT */
- uint64_t crc64;
+ uint32_t identifier; ///< Block identifier, must be BlockType::DeDuplicationTable2.
+ uint16_t type; ///< Data classification (\ref DataType) for sectors referenced by this table.
+ uint16_t compression; ///< Compression algorithm for this table body (\ref CompressionType).
+ uint8_t levels; ///< Total number of hierarchy levels (root depth); > 0.
+ uint8_t tableLevel; ///< Zero-based level index of this table (0 = root, increases downward).
+ uint64_t previousLevelOffset; ///< Absolute byte offset of the parent (previous) level table; 0 if root.
+ uint16_t negative; ///< Leading negative LBA count; added to external L to build internal index.
+ uint64_t blocks; ///< Total internal span (negative + usable + overflow) in logical sectors.
+ uint16_t overflow; ///< Trailing dumped sectors beyond user area (overflow range), still mapped with entries.
+ uint64_t
+ start; ///< Base internal index covered by this table (used for secondary tables; currently informational).
+ uint8_t blockAlignmentShift; ///< 2^blockAlignmentShift = block alignment boundary in bytes.
+ uint8_t dataShift; ///< 2^dataShift = sectors represented per increment in blockIndex field.
+ uint8_t tableShift; ///< 2^tableShift = number of logical sectors per primary entry (multi-level only; 0 for
+ ///< single-level or secondary tables).
+ uint64_t entries; ///< Number of entries contained in (uncompressed) table payload.
+ uint64_t cmpLength; ///< Compressed payload size in bytes.
+ uint64_t length; ///< Uncompressed payload size in bytes.
+ uint64_t cmpCrc64; ///< CRC64-ECMA of compressed table payload.
+ uint64_t crc64; ///< CRC64-ECMA of uncompressed table payload.
} DdtHeader2;
==== Field Descriptions
diff --git a/docs/spec/blocks/dumphw.adoc b/docs/spec/blocks/dumphw.adoc
index a54e911..af1a6c3 100644
--- a/docs/spec/blocks/dumphw.adoc
+++ b/docs/spec/blocks/dumphw.adoc
@@ -11,14 +11,10 @@ This structure allows implementations to trace data provenance and associate dum
/**Dump hardware block, contains a list of hardware used to dump the media on this image */
typedef struct DumpHardwareHeader
{
- /**Identifier, */
- uint32_t identifier;
- /**How many entries follow this header */
- uint16_t entries;
- /**Size of the whole block, not including this header, in uint8_ts */
- uint32_t length;
- /**CRC64-ECMA of the block */
- uint64_t crc64;
+ uint32_t identifier; ///< Block identifier, must be BlockType::DumpHardwareBlock.
+ uint16_t entries; ///< Number of DumpHardwareEntry records that follow.
+ uint32_t length; ///< Total payload bytes after this header (sum of entries, strings, and extents arrays).
+ uint64_t crc64; ///< CRC64-ECMA of the payload (byte-swapped for legacy v1 images, handled automatically).
} DumpHardwareHeader;
==== Field Descriptions
@@ -57,24 +53,15 @@ typedef struct DumpHardwareHeader
/**Dump hardware entry, contains length of strings that follow, in the same order as the length, this structure */
typedef struct DumpHardwareEntry
{
- /**Length of UTF-8 manufacturer string */
- uint32_t manufacturerLength;
- /**Length of UTF-8 model string */
- uint32_t modelLength;
- /**Length of UTF-8 revision string */
- uint32_t revisionLength;
- /**Length of UTF-8 firmware version string */
- uint32_t firmwareLength;
- /**Length of UTF-8 serial string */
- uint32_t serialLength;
- /**Length of UTF-8 software name string */
- uint32_t softwareNameLength;
- /**Length of UTF-8 software version string */
- uint32_t softwareVersionLength;
- /**Length of UTF-8 software operating system string */
- uint32_t softwareOperatingSystemLength;
- /**How many extents are after the strings */
- uint32_t extents;
+ uint32_t manufacturerLength; ///< Length in bytes of manufacturer UTF-8 string.
+ uint32_t modelLength; ///< Length in bytes of model UTF-8 string.
+ uint32_t revisionLength; ///< Length in bytes of revision / hardware revision string.
+ uint32_t firmwareLength; ///< Length in bytes of firmware version string.
+ uint32_t serialLength; ///< Length in bytes of device serial number string.
+ uint32_t softwareNameLength; ///< Length in bytes of dumping software name string.
+ uint32_t softwareVersionLength; ///< Length in bytes of dumping software version string.
+ uint32_t softwareOperatingSystemLength; ///< Length in bytes of host operating system string.
+ uint32_t extents; ///< Number of DumpExtent records following the strings (0 = none).
} DumpHardwareEntry;
==== Field Descriptions
@@ -136,13 +123,11 @@ typedef struct DumpHardwareEntry
[source,c]
/**Dump hardware extent, contains the start and end of the extent in the media */
-typedef struct DumpHardwareExtent
+typedef struct DumpExtent
{
- /**Start of the extent in the media */
- uint64_t start;
- /**End of the extent in the media */
- uint64_t end;
-} DumpHardwareExtent;
+ uint64_t start; ///< Starting LBA (inclusive).
+ uint64_t end; ///< Ending LBA (inclusive); >= start.
+} DumpExtent;
==== Field Descriptions
diff --git a/docs/spec/blocks/geom.adoc b/docs/spec/blocks/geom.adoc
index 54250c6..ae374dc 100644
--- a/docs/spec/blocks/geom.adoc
+++ b/docs/spec/blocks/geom.adoc
@@ -10,11 +10,10 @@ Instead, it typically represents the translation parameters active at the time t
/**Geometry block, contains physical geometry information */
typedef struct GeometryBlockHeader
{
- /**Identifier, */
- uint32_t identifier;
- uint32_t cylinders;
- uint32_t heads;
- uint32_t sectorsPerTrack;
+ uint32_t identifier; ///< Block identifier, must be BlockType::GeometryBlock.
+ uint32_t cylinders; ///< Number of cylinders.
+ uint32_t heads; ///< Number of heads (tracks per cylinder).
+ uint32_t sectorsPerTrack; ///< Number of sectors per track.
} GeometryBlockHeader;
==== Field Descriptions
diff --git a/docs/spec/blocks/header.adoc b/docs/spec/blocks/header.adoc
index 7d7262d..1c41124 100644
--- a/docs/spec/blocks/header.adoc
+++ b/docs/spec/blocks/header.adoc
@@ -12,40 +12,23 @@ All subsequent parsing and interpretation of the file depends on the contents of
/**Header, at start of file */
typedef struct AaruHeaderV2
{
- /**Header identifier, see AARU_MAGIC */
- uint64_t identifier;
- /**UTF-16LE name of the application that created the image */
- uint8_t application[HEADER_APP_NAME_LEN];
- /**Image format major version. A new major version means a possibly incompatible change of format */
- uint8_t imageMajorVersion;
- /**Image format minor version. A new minor version indicates a compatible change of format */
- uint8_t imageMinorVersion;
- /**Major version of the application that created the image */
- uint8_t applicationMajorVersion;
- /**Minor version of the application that created the image */
- uint8_t applicationMinorVersion;
- /**Type of media contained on image */
- uint32_t mediaType;
- /**Offset to index */
- uint64_t indexOffset;
- /**Windows filetime (100 nanoseconds since 1601/01/01 00:00:00 UTC) of image creation time */
- int64_t creationTime;
- /**Windows filetime (100 nanoseconds since 1601/01/01 00:00:00 UTC) of image last written time */
- int64_t lastWrittenTime;
- /**Unique identifier that allows children images to recognize and find this image */
- uint8_t guid[GUID_SIZE];
- /**Block alignment shift. All blocks in the image are aligned at 2 << blockAlignmentShift bytes */
- uint8_t blockAlignmentShift;
- /**Data shift. All data blocks in the image contain 2 << dataShift items at most */
- uint8_t dataShift;
- /**Table shift. All deduplication tables in the image use this shift to calculate the position of an item */
- uint8_t tableShift;
- /**Features used in this image that if unsupported are still compatible for reading and writing implementations */
- uint64_t featureCompatible;
- /**Features used in this image that if unsupported are still compatible for reading implementations but not for writing */
- uint64_t featureCompatibleRo;
- /**Features used in this image that if unsupported prevent reading or writing the image */
- uint64_t featureIncompatible;
+ uint64_t identifier; ///< File magic (AARU_MAGIC).
+ uint8_t application[AARU_HEADER_APP_NAME_LEN]; ///< UTF-8 creator application name (fixed 64 bytes).
+ uint8_t imageMajorVersion; ///< Container format major version.
+ uint8_t imageMinorVersion; ///< Container format minor version.
+ uint8_t applicationMajorVersion; ///< Creator application major version.
+ uint8_t applicationMinorVersion; ///< Creator application minor / patch version.
+ uint32_t mediaType; ///< Media type enumeration (value from \ref MediaType).
+ uint64_t indexOffset; ///< Absolute byte offset to primary index block (MUST be > 0; 0 => corrupt/unreadable).
+ int64_t creationTime; ///< Creation FILETIME (100 ns since 1601-01-01 UTC).
+ int64_t lastWrittenTime; ///< Last modification FILETIME (100 ns since 1601-01-01 UTC).
+ uint8_t guid[GUID_SIZE]; ///< 128-bit image GUID (binary, not text); stable across children.
+ uint8_t blockAlignmentShift; ///< log2 block alignment (block size alignment = 2^blockAlignmentShift bytes).
+ uint8_t dataShift; ///< log2 sectors/items per block-index increment in DDT entries (2^dataShift).
+ uint8_t tableShift; ///< log2 sectors spanned by each primary DDT entry (0 = single-level).
+ uint64_t featureCompatible; ///< Feature bits: unimplemented bits are ignorable (still R/W safe).
+ uint64_t featureCompatibleRo; ///< Feature bits: unimplemented -> degrade to read-only access.
+ uint64_t featureIncompatible; ///< Feature bits: any unimplemented -> abort (cannot open safely).
} AaruHeaderV2;
=== Field Descriptions
diff --git a/docs/spec/blocks/index.adoc b/docs/spec/blocks/index.adoc
index 9ec742d..8b67bca 100644
--- a/docs/spec/blocks/index.adoc
+++ b/docs/spec/blocks/index.adoc
@@ -14,12 +14,9 @@ Multiple index blocks may exist within a file to represent previous states or hi
/**Header for the index, followed by entries */
typedef struct IndexHeader
{
- /**Identifier, */
- uint32_t identifier;
- /**How many entries follow this header */
- uint16_t entries;
- /**CRC64-ECMA of the index */
- uint64_t crc64;
+ uint32_t identifier; ///< Block identifier (must be BlockType::IndexBlock).
+ uint16_t entries; ///< Number of \ref IndexEntry records that follow immediately.
+ uint64_t crc64; ///< CRC64-ECMA of the entries array (legacy byte-swapped for early images).
} IndexHeader;
==== Field Descriptions
@@ -53,12 +50,9 @@ typedef struct IndexHeader
/**Index entry */
typedef struct IndexEntry
{
- /**Type of item pointed by this entry */
- uint32_t blockType;
- /**Type of data contained by the block pointed by this entry */
- uint16_t dataType;
- /**Offset in file where item is stored */
- uint64_t offset;
+ uint32_t blockType; ///< Block identifier of the referenced block (value from \ref BlockType).
+ uint16_t dataType; ///< Data classification (value from \ref DataType) or unused for untyped blocks.
+ uint64_t offset; ///< Absolute byte offset in the image where the referenced block header begins.
} IndexEntry;
==== Field Descriptions
diff --git a/docs/spec/blocks/index2.adoc b/docs/spec/blocks/index2.adoc
index 72a64eb..07edd5c 100644
--- a/docs/spec/blocks/index2.adoc
+++ b/docs/spec/blocks/index2.adoc
@@ -12,13 +12,10 @@ Multiple index blocks may exist within a file to represent previous states or hi
/**Header for the index, followed by entries */
typedef struct IndexHeader2
{
- /**Identifier, */
- uint32_t identifier;
- /**How many entries follow this header */
- uint64_t entries;
- /**CRC64-ECMA of the index */
- uint64_t crc64;
-} IndexHeader;
+ uint32_t identifier; ///< Block identifier (must be BlockType::IndexBlock2).
+ uint64_t entries; ///< Number of \ref IndexEntry records that follow immediately.
+ uint64_t crc64; ///< CRC64-ECMA of the entries array (legacy byte-swapped rule still applies for old versions).
+} IndexHeader2;
==== Field Descriptions
@@ -51,12 +48,9 @@ typedef struct IndexHeader2
/**Index entry */
typedef struct IndexEntry
{
- /**Type of item pointed by this entry */
- uint32_t blockType;
- /**Type of data contained by the block pointed by this entry */
- uint16_t dataType;
- /**Offset in file where item is stored */
- uint64_t offset;
+ uint32_t blockType; ///< Block identifier of the referenced block (value from \ref BlockType).
+ uint16_t dataType; ///< Data classification (value from \ref DataType) or unused for untyped blocks.
+ uint64_t offset; ///< Absolute byte offset in the image where the referenced block header begins.
} IndexEntry;
==== Field Descriptions
diff --git a/docs/spec/blocks/index3.adoc b/docs/spec/blocks/index3.adoc
index ac3ee4d..423dd6c 100644
--- a/docs/spec/blocks/index3.adoc
+++ b/docs/spec/blocks/index3.adoc
@@ -18,14 +18,10 @@ Index entries can contain *at most* a single child index pointer.
/**Header for the index, followed by entries */
typedef struct IndexHeader3
{
- /**Identifier, */
- uint32_t identifier;
- /**How many entries follow this header */
- uint64_t entries;
- /**CRC64-ECMA of the index */
- uint64_t crc64;
- /**Pointer to the previous index header */
- uint64_t previous;
+ uint32_t identifier; ///< Block identifier (must be BlockType::IndexBlock3).
+ uint64_t entries; ///< Number of \ref IndexEntry records that follow in this (sub)index block.
+ uint64_t crc64; ///< CRC64-ECMA of the local entries array (does NOT cover subindexes or previous chains).
+ uint64_t previous; ///< File offset of a previous IndexBlock3 header (0 if none / root segment).
} IndexHeader3;
==== Field Descriptions
diff --git a/docs/spec/blocks/metadata.adoc b/docs/spec/blocks/metadata.adoc
index f5b5d2f..aba3dd2 100644
--- a/docs/spec/blocks/metadata.adoc
+++ b/docs/spec/blocks/metadata.adoc
@@ -10,62 +10,35 @@ All string values within this block are encoded as little-endian UTF-16 and term
/**Metadata block, contains metadata */
typedef struct MetadataBlockHeader
{
- /**Identifier, */
- uint32_t identifier;
- /**Size in uint8_ts of this whole metadata block */
- uint32_t blockSize;
- /**Sequence of media set this media belongs to */
- int32_t mediaSequence;
- /**Total number of media on the media set this media belongs to */
- int32_t lastMediaSequence;
- /**Offset to start of creator string from start of this block */
- uint32_t creatorOffset;
- /**Length in uint8_ts of the null-terminated UTF-16LE creator string */
- uint32_t creatorLength;
- /**Offset to start of creator string from start of this block */
- uint32_t commentsOffset;
- /**Length in uint8_ts of the null-terminated UTF-16LE creator string */
- uint32_t commentsLength;
- /**Offset to start of creator string from start of this block */
- uint32_t mediaTitleOffset;
- /**Length in uint8_ts of the null-terminated UTF-16LE creator string */
- uint32_t mediaTitleLength;
- /**Offset to start of creator string from start of this block */
- uint32_t mediaManufacturerOffset;
- /**Length in uint8_ts of the null-terminated UTF-16LE creator string */
- uint32_t mediaManufacturerLength;
- /**Offset to start of creator string from start of this block */
- uint32_t mediaModelOffset;
- /**Length in uint8_ts of the null-terminated UTF-16LE creator string */
- uint32_t mediaModelLength;
- /**Offset to start of creator string from start of this block */
- uint32_t mediaSerialNumberOffset;
- /**Length in uint8_ts of the null-terminated UTF-16LE creator string */
- uint32_t mediaSerialNumberLength;
- /**Offset to start of creator string from start of this block */
- uint32_t mediaBarcodeOffset;
- /**Length in uint8_ts of the null-terminated UTF-16LE creator string */
- uint32_t mediaBarcodeLength;
- /**Offset to start of creator string from start of this block */
- uint32_t mediaPartNumberOffset;
- /**Length in uint8_ts of the null-terminated UTF-16LE creator string */
- uint32_t mediaPartNumberLength;
- /**Offset to start of creator string from start of this block */
- uint32_t driveManufacturerOffset;
- /**Length in uint8_ts of the null-terminated UTF-16LE creator string */
- uint32_t driveManufacturerLength;
- /**Offset to start of creator string from start of this block */
- uint32_t driveModelOffset;
- /**Length in uint8_ts of the null-terminated UTF-16LE creator string */
- uint32_t driveModelLength;
- /**Offset to start of creator string from start of this block */
- uint32_t driveSerialNumberOffset;
- /**Length in uint8_ts of the null-terminated UTF-16LE creator string */
- uint32_t driveSerialNumberLength;
- /**Offset to start of creator string from start of this block */
- uint32_t driveFirmwareRevisionOffset;
- /**Length in uint8_ts of the null-terminated UTF-16LE creator string */
- uint32_t driveFirmwareRevisionLength;
+ uint32_t identifier; ///< Block identifier, must be BlockType::MetadataBlock.
+ uint32_t blockSize; ///< Total size in bytes of the entire metadata block (header + strings).
+ int32_t mediaSequence; ///< Sequence number within a multi-disc / multi-volume set (0-based or 1-based as
+ ///< producer defines).
+ int32_t lastMediaSequence; ///< Total number of media in the set; 0 or 1 if single item.
+ uint32_t creatorOffset; ///< Offset to UTF-16LE creator string (or undefined if creatorLength==0).
+ uint32_t creatorLength; ///< Length in bytes (including null) of creator string (0 if absent).
+ uint32_t commentsOffset; ///< Offset to UTF-16LE comments string.
+ uint32_t commentsLength; ///< Length in bytes (including null) of comments string.
+ uint32_t mediaTitleOffset; ///< Offset to UTF-16LE media title string.
+ uint32_t mediaTitleLength; ///< Length in bytes (including null) of media title string.
+ uint32_t mediaManufacturerOffset; ///< Offset to UTF-16LE media manufacturer string.
+ uint32_t mediaManufacturerLength; ///< Length in bytes (including null) of media manufacturer string.
+ uint32_t mediaModelOffset; ///< Offset to UTF-16LE media model string.
+ uint32_t mediaModelLength; ///< Length in bytes (including null) of media model string.
+ uint32_t mediaSerialNumberOffset; ///< Offset to UTF-16LE media serial number string.
+ uint32_t mediaSerialNumberLength; ///< Length in bytes (including null) of media serial number string.
+ uint32_t mediaBarcodeOffset; ///< Offset to UTF-16LE media barcode string.
+ uint32_t mediaBarcodeLength; ///< Length in bytes (including null) of media barcode string.
+ uint32_t mediaPartNumberOffset; ///< Offset to UTF-16LE media part number string.
+ uint32_t mediaPartNumberLength; ///< Length in bytes (including null) of media part number string.
+ uint32_t driveManufacturerOffset; ///< Offset to UTF-16LE drive manufacturer string.
+ uint32_t driveManufacturerLength; ///< Length in bytes (including null) of drive manufacturer string.
+ uint32_t driveModelOffset; ///< Offset to UTF-16LE drive model string.
+ uint32_t driveModelLength; ///< Length in bytes (including null) of drive model string.
+ uint32_t driveSerialNumberOffset; ///< Offset to UTF-16LE drive serial number string.
+ uint32_t driveSerialNumberLength; ///< Length in bytes (including null) of drive serial number string.
+ uint32_t driveFirmwareRevisionOffset; ///< Offset to UTF-16LE drive firmware revision string.
+ uint32_t driveFirmwareRevisionLength; ///< Length in bytes (including null) of drive firmware revision string.
} MetadataBlockHeader;
==== Field Descriptions
diff --git a/docs/spec/blocks/tape_file.adoc b/docs/spec/blocks/tape_file.adoc
index 150272c..e33e111 100644
--- a/docs/spec/blocks/tape_file.adoc
+++ b/docs/spec/blocks/tape_file.adoc
@@ -7,7 +7,17 @@ Tape files are separations written to media, usually digital tapes, and are mark
[source,c]
#define TAPE_FILE_MAGIC 0x454C4654
-/* TODO */
+typedef struct TapeFileHeader
+{
+ uint32_t identifier; ///< Block type identifier. Must be set to BlockType::TapeFileBlock. This magic value allows
+ ///< parsers to identify the block type.
+ uint32_t entries; ///< Number of file entries following this header. Specifies how many TapeFileEntry structures
+ ///< are in this block. Valid range: 0 to 2^32-1.
+ uint64_t length; ///< Size of entry data in bytes (excluding this header). Calculated as: entries ×
+ ///< sizeof(TapeFileEntry). This is the number of bytes following the header.
+ uint64_t crc64; ///< CRC64-ECMA checksum of the entry data. Computed over the array of TapeFileEntry structures
+ ///< only. Does NOT include this header. Used for integrity verification.
+} TapeFileHeader;
==== Field Descriptions
@@ -42,7 +52,18 @@ Tape files are separations written to media, usually digital tapes, and are mark
==== Tape file entries
[source,c]
-/* TODO */
+typedef struct TapeFileEntry
+{
+ uint32_t File; ///< File number (unique within the partition). Identifies this file among all files in the same
+ ///< partition. Numbering scheme is tape-format-dependent.
+ uint8_t Partition; ///< Partition number containing this file. References a partition defined in the
+ ///< TapePartitionHeader block. Valid range: 0-255.
+ uint64_t FirstBlock; ///< First block of the file (inclusive). This is the starting block address of the file data.
+ ///< Block addresses are 0-based within the partition.
+ uint64_t
+ LastBlock; ///< Last block of the file (inclusive). This is the ending block address of the file data. Must be
+ ///< ≥ FirstBlock. The file contains all blocks from FirstBlock through LastBlock inclusive.
+} TapeFileEntry;
==== Field Descriptions
diff --git a/docs/spec/blocks/tape_partition.adoc b/docs/spec/blocks/tape_partition.adoc
index bc298bd..e974fc2 100644
--- a/docs/spec/blocks/tape_partition.adoc
+++ b/docs/spec/blocks/tape_partition.adoc
@@ -9,7 +9,17 @@ A well-known example is the LTFS filesystem.
[source,c]
#define TAPE_PARTITION_MAGIC 0x54504254
-/* TODO */
+typedef struct TapePartitionHeader
+{
+ uint32_t identifier; ///< Block type identifier. Must be set to BlockType::TapePartitionBlock. This magic value
+ ///< allows parsers to identify the block type.
+ uint8_t entries; ///< Number of partition entries following this header. Specifies how many TapePartitionEntry
+ ///< structures are in this block. Valid range: 0-255. Most tapes have 1-4 partitions.
+ uint64_t length; ///< Size of entry data in bytes (excluding this header). Calculated as: entries ×
+ ///< sizeof(TapePartitionEntry). This is the number of bytes following the header.
+ uint64_t crc64; ///< CRC64-ECMA checksum of the entry data. Computed over the array of TapePartitionEntry
+ ///< structures only. Does NOT include this header. Used for integrity verification.
+} TapePartitionHeader;
==== Field Descriptions
@@ -44,7 +54,16 @@ A well-known example is the LTFS filesystem.
==== Tape partition entries
[source,c]
-/* TODO */
+typedef struct TapePartitionEntry
+{
+ uint8_t Number; ///< Partition number (unique identifier for this partition). Identifies this partition among all
+ ///< partitions on the tape. Valid range: 0-255, though most tapes use 0-3.
+ uint64_t FirstBlock; ///< First block in the partition (inclusive). Starting block address for this partition's
+ ///< address space. Often 0, but format-dependent.
+ uint64_t LastBlock; ///< Last block in the partition (inclusive). Ending block address for this partition's address
+ ///< space. Must be ≥ FirstBlock. The partition contains all blocks from FirstBlock through
+ ///< LastBlock inclusive.
+} TapePartitionEntry;
==== Field Descriptions
diff --git a/docs/spec/blocks/tracks.adoc b/docs/spec/blocks/tracks.adoc
index 4101bc7..22942b6 100644
--- a/docs/spec/blocks/tracks.adoc
+++ b/docs/spec/blocks/tracks.adoc
@@ -10,12 +10,9 @@ This format is common in optical media such as CDs, DVDs, and related disc-based
/**Contains list of optical disc tracks */
typedef struct TracksHeader
{
- /**Identifier, */
- uint32_t identifier;
- /**How many entries follow this header */
- uint16_t entries;
- /**CRC64-ECMA of the block */
- uint64_t crc64;
+ uint32_t identifier; ///< Block identifier (must be BlockType::TracksBlock).
+ uint16_t entries; ///< Number of TrackEntry records following this header.
+ uint64_t crc64; ///< CRC64-ECMA of the TrackEntry array (header excluded, legacy byte-swap for early versions).
} TracksHeader;
==== Field Descriptions
@@ -34,22 +31,14 @@ typedef struct TracksHeader
/**Optical disc track */
typedef struct TrackEntry
{
- /**Track sequence */
- uint8_t sequence;
- /**Track type */
- uint8_t type;
- /**Track starting LBA */
- int64_t start;
- /**Track last LBA */
- int64_t end;
- /**Track pregap in sectors */
- int64_t pregap;
- /**Track session */
- uint8_t session;
- /**Track's ISRC in ASCII */
- uint8_t isrc[13];
- /**Track flags */
- uint8_t flags;
+ uint8_t sequence; ///< Track number (1..99 typical for CD audio/data). 0 may indicate placeholder/non-standard.
+ uint8_t type; ///< Track type (value from \ref TrackType).
+ int64_t start; ///< Inclusive starting LBA of the track.
+ int64_t end; ///< Inclusive ending LBA of the track.
+ int64_t pregap; ///< Pre-gap length in sectors preceding track start (0 if none).
+ uint8_t session; ///< Session number (1-based). 1 for single-session discs.
+ uint8_t isrc[13]; ///< ISRC raw 13-byte code (no null terminator). All zeros if not present.
+ uint8_t flags; ///< Control / attribute bitfield (see file documentation for suggested bit mapping).
} TrackEntry;
==== Field Descriptions
diff --git a/include/aaruformat/structs/header.h b/include/aaruformat/structs/header.h
index 588279d..47a8108 100644
--- a/include/aaruformat/structs/header.h
+++ b/include/aaruformat/structs/header.h
@@ -106,7 +106,7 @@ typedef struct AaruHeader
typedef struct AaruHeaderV2
{
uint64_t identifier; ///< File magic (AARU_MAGIC).
- uint8_t application[AARU_HEADER_APP_NAME_LEN]; ///< UTF-16LE creator application name (fixed 64 bytes).
+ uint8_t application[AARU_HEADER_APP_NAME_LEN]; ///< UTF-8 creator application name (fixed 64 bytes).
uint8_t imageMajorVersion; ///< Container format major version.
uint8_t imageMinorVersion; ///< Container format minor version.
uint8_t applicationMajorVersion; ///< Creator application major version.