mirror of
https://github.com/aaru-dps/libaaruformat.git
synced 2026-09-16 11:54:18 +00:00
102 lines
4.0 KiB
Plaintext
102 lines
4.0 KiB
Plaintext
== 📓 Definitions
|
||
|
||
=== 🧩 Types
|
||
|
||
All binary types used in this specification are stored as little-endian values on the file.
|
||
This specification follows the C syntax to denote hexadecimal values, and requires the reader have some knowledge on programming.
|
||
|
||
=== 🔄 Endianness
|
||
|
||
Unless otherwise specified, all fields in this specification are considered to be in __Little-Endian__ format, that is the hexadecimal number `0x12345678` is stored in disk as the following sequence of bytes: `0x78 0x56 0x34 0x12`.
|
||
|
||
=== 🏷️ Header identifiers
|
||
|
||
Header identifiers are 4 `ASCII` characters stored as a sequence of bytes inside a single 32 bits pack.
|
||
They are shown in this specification enclosed in single quotes.
|
||
For example, the header identifier `AARU` should be stored on disk as `0x41 0x41 0x52 0x55`.
|
||
|
||
=== 🔢 Integers
|
||
|
||
Integer values are designated in this specification if unsigned (U) and no letter for signed, continuing with `int`, the number of bits able to be stored in them, and finishing with `_t`.
|
||
|
||
That so, the signed integers should be: `int8_t`, `int16_t`, `int32_t`, `int64_t` and `int128_t`.
|
||
|
||
And the unsigned integers should be: `uint8_t`, `uint16_t`, `uint32_t`, `uint64_t` , `uint128_t`.
|
||
|
||
=== 📝 Strings
|
||
|
||
The default string encoding for the metadata block is `UTF-16` little endian, null-terminated with `0x0000`.
|
||
|
||
Other blocks use different encodings as noted in their respective specifications:
|
||
|
||
[cols="3,2,3",options="header"]
|
||
|===
|
||
|Location |Encoding |Notes
|
||
|
||
|Metadata block (creator, comments, media/drive info)
|
||
|UTF-16LE
|
||
|Null-terminated (`0x0000`). Lengths include the terminator.
|
||
|
||
|Header `application` field (V1)
|
||
|UTF-16LE
|
||
|Fixed 64-byte buffer (32 UTF-16 code units).
|
||
|
||
|Header `application` field (V2+)
|
||
|UTF-8
|
||
|Fixed 64-byte buffer, null-padded.
|
||
|
||
|Dump hardware strings (manufacturer, model, etc.)
|
||
|UTF-8
|
||
|Length-prefixed, not null-terminated on disk.
|
||
|
||
|CICM XML block
|
||
|UTF-8
|
||
|Length from block header, not null-terminated.
|
||
|
||
|Aaru JSON metadata block
|
||
|UTF-8
|
||
|Length from block header, not null-terminated.
|
||
|===
|
||
|
||
`String8` values mean the string is stored in Unicode’s `UTF-8` encoding and terminated and filled with `NULL` (`0x00`) bytes.
|
||
|
||
`StringA` values mean the string is stored in `ASCII` encoding and terminated and filled with `NULL` (`0x00`) bytes.
|
||
|
||
=== ⏰ Timestamp
|
||
|
||
All timestamps used in this specification are stored as a signed 64bit integer (`int64_t`) counting the number of nanoseconds in the UTC timezone after/before the epoch of 1st January 1601 at 00:00 of the Gregorian Calendar.
|
||
This epoch is chosen because it is when the leap-year scheme was adopted.
|
||
|
||
=== 💿 Media tag
|
||
|
||
A media tag is a piece of data that is physically present in the media but it’s not part of the user data.
|
||
It can be the table of contents, some manufacturing information, sector replacement tables, etc.
|
||
|
||
=== 🏷️ Sector tag
|
||
|
||
A sector tag is a piece of data that is physically present in the media, once per each sector, but it’s not part of the user data.
|
||
It can be addressing information, error detection or correction information, encryption metadata, etc.
|
||
|
||
=== ∅ NULL
|
||
|
||
NULLs are `0x00` bytes.
|
||
|
||
=== 🔐 CRC64 and Version 1 Compatibility
|
||
|
||
All CRC64 checksums in this specification use the CRC64-ECMA algorithm.
|
||
|
||
Images with `imageMajorVersion` = 1 store CRC64 values in byte-swapped order due to a quirk in the original C# writer.
|
||
When verifying a V1 image, implementations MUST byte-swap the computed CRC64 before comparing it against the stored value:
|
||
|
||
----
|
||
computed_crc64 = CRC64_ECMA(data)
|
||
if imageMajorVersion <= 1:
|
||
computed_crc64 = bswap64(computed_crc64)
|
||
compare computed_crc64 against stored crc64
|
||
----
|
||
|
||
Where `bswap64` reverses the byte order of a 64-bit value (e.g., `0x0123456789ABCDEF` becomes `0xEFCDAB8967452301`).
|
||
|
||
This applies to **all** CRC64 fields across all block types: data blocks, deduplication tables, index blocks, tracks, dump hardware, and any other block carrying a `crc64` or `cmpCrc64` field.
|
||
|
||
Images with `imageMajorVersion` >= 2 store CRC64 values in native (little-endian) order and require no byte-swap. |