From e2f3323a046f14e622a5cf8a275072af744a5d06 Mon Sep 17 00:00:00 2001 From: Natalia Portillo Date: Sat, 11 Oct 2025 13:17:26 +0100 Subject: [PATCH] Sync specification with code. --- docs/spec/blocks/aaru_metadata.adoc | 9 ++- docs/spec/blocks/checksum.adoc | 15 ++--- docs/spec/blocks/cicm.adoc | 5 +- docs/spec/blocks/data.adoc | 24 +++----- docs/spec/blocks/ddt.adoc | 27 +++------ docs/spec/blocks/ddt2.adoc | 56 +++++++----------- docs/spec/blocks/dumphw.adoc | 49 ++++++---------- docs/spec/blocks/geom.adoc | 9 ++- docs/spec/blocks/header.adoc | 51 ++++++----------- docs/spec/blocks/index.adoc | 18 ++---- docs/spec/blocks/index2.adoc | 20 +++---- docs/spec/blocks/index3.adoc | 12 ++-- docs/spec/blocks/metadata.adoc | 85 ++++++++++------------------ docs/spec/blocks/tape_file.adoc | 25 +++++++- docs/spec/blocks/tape_partition.adoc | 23 +++++++- docs/spec/blocks/tracks.adoc | 33 ++++------- include/aaruformat/structs/header.h | 2 +- 17 files changed, 188 insertions(+), 275 deletions(-) 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.