mirror of
https://github.com/aaru-dps/libaaruformat.git
synced 2025-12-16 19:24:40 +00:00
Enhance documentation for various structures with detailed descriptions and formatting improvements
This commit is contained in:
@@ -19,42 +19,109 @@
|
||||
#ifndef LIBAARUFORMAT_DUMP_H
|
||||
#define LIBAARUFORMAT_DUMP_H
|
||||
|
||||
#include <stdint.h> /* Fixed-width integer types for on‑disk packed structures */
|
||||
|
||||
#pragma pack(push, 1)
|
||||
|
||||
/**Dump hardware block, contains a list of hardware used to dump the media on this image */
|
||||
typedef struct DumpHardwareHeader {
|
||||
/**Identifier, <see cref="BlockType.DumpHardwareBlock" /> */
|
||||
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;
|
||||
/** \file aaruformat/structs/dump.h
|
||||
* \brief Packed on-disk structures describing hardware and software used during image acquisition.
|
||||
*
|
||||
* A Dump Hardware block (identifier = BlockType::DumpHardwareBlock) records one or more dump "environments" –
|
||||
* typically combinations of a physical device (drive, controller, adapter) and the software stack that
|
||||
* performed the read operation. Each environment is represented by a \ref DumpHardwareEntry followed by a
|
||||
* sequence of UTF‑8 strings and an optional array of extent ranges (\ref DumpExtent, defined in context.h) that
|
||||
* delimit portions of the medium this environment contributed to.
|
||||
*
|
||||
* Binary layout (little-endian, packed, all multi-byte integers LE):
|
||||
*
|
||||
* DumpHardwareHeader (sizeof = 16 bytes)
|
||||
* identifier (4) -> BlockType::DumpHardwareBlock
|
||||
* entries (2) -> number of following hardware entries
|
||||
* length (4) -> total bytes of payload that follow this header
|
||||
* crc64 (8) -> CRC64-ECMA of the payload bytes
|
||||
*
|
||||
* Repeated for i in [0, entries):
|
||||
* DumpHardwareEntry (36 bytes)
|
||||
* manufacturerLength (4)
|
||||
* modelLength (4)
|
||||
* revisionLength (4)
|
||||
* firmwareLength (4)
|
||||
* serialLength (4)
|
||||
* softwareNameLength (4)
|
||||
* softwareVersionLength (4)
|
||||
* softwareOperatingSystemLength (4)
|
||||
* extents (4) -> number of DumpExtent structs after the strings
|
||||
*
|
||||
* Variable-length UTF-8 strings (not NUL-terminated on disk) appear immediately after the entry, in the
|
||||
* exact order of the length fields above; each string is present only if its length > 0. The reader allocates
|
||||
* an extra byte to append '\0' for in-memory convenience.
|
||||
*
|
||||
* Array of 'extents' DumpExtent structures (each 16 bytes: start, end) follows the strings if extents > 0.
|
||||
* The semantic of each extent is an inclusive [start, end] logical sector (or unit) range contributed by
|
||||
* this hardware/software combination.
|
||||
*
|
||||
* CRC semantics:
|
||||
* - crc64 covers exactly 'length' bytes immediately following the header.
|
||||
* - For legacy images with header.imageMajorVersion <= AARUF_VERSION_V1 the original C# writer produced a
|
||||
* byte-swapped CRC; the library compensates internally (see process_dumphw_block()).
|
||||
*
|
||||
* Invariants / validation recommendations:
|
||||
* - identifier == BlockType::DumpHardwareBlock
|
||||
* - Accumulated size of all (entry + strings + extents arrays) == length
|
||||
* - All length fields are trusted only after bounds checking against remaining payload bytes
|
||||
* - Strings are raw UTF-8 data with no implicit terminator
|
||||
* - extents * sizeof(DumpExtent) fits inside remaining payload
|
||||
*
|
||||
* Memory management notes (runtime library):
|
||||
* - Each string is malloc'ed with +1 byte for terminator during processing.
|
||||
* - Extents array is malloc'ed per entry when extents > 0.
|
||||
* - See aaruformatContext::dumpHardwareEntriesWithData for owning pointers.
|
||||
*
|
||||
* \warning Structures are packed; never rely on natural alignment when mapping from a byte buffer.
|
||||
* \see DumpHardwareHeader
|
||||
* \see DumpHardwareEntry
|
||||
* \see DumpExtent (in context.h)
|
||||
* \see BlockType
|
||||
*/
|
||||
|
||||
/** \struct DumpHardwareHeader
|
||||
* \brief Header that precedes a sequence of dump hardware entries and their variable-length payload.
|
||||
*/
|
||||
typedef struct DumpHardwareHeader
|
||||
{
|
||||
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;
|
||||
|
||||
/**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;
|
||||
/** \struct DumpHardwareEntry
|
||||
* \brief Per-environment length table describing subsequent UTF-8 strings and optional extent array.
|
||||
*
|
||||
* Immediately after this structure the variable-length UTF‑8 strings appear in the documented order, each
|
||||
* present only if its corresponding length is non-zero. No padding is present between strings. When all
|
||||
* strings are consumed, an array of \ref DumpExtent follows if \ref extents > 0.
|
||||
*
|
||||
* All length fields measure bytes (not characters) and exclude any in-memory NUL terminator added by the reader.
|
||||
*
|
||||
* Typical semantics:
|
||||
* - manufacturer/model/revision/firmware/serial identify the hardware device.
|
||||
* - softwareName/softwareVersion/softwareOperatingSystem identify the acquisition software environment.
|
||||
* - extents list which logical ranges this environment actually dumped (useful for multi-device composites).
|
||||
*/
|
||||
typedef struct DumpHardwareEntry
|
||||
{
|
||||
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;
|
||||
|
||||
#pragma pack(pop)
|
||||
|
||||
#endif //LIBAARUFORMAT_DUMP_H
|
||||
#endif // LIBAARUFORMAT_DUMP_H
|
||||
|
||||
Reference in New Issue
Block a user