libaaruformat 1.0 Aaru Data Preservation Suite - Format Library

Loading...
Searching...
No Matches
dump.h File Reference

Packed on-disk structures describing hardware and software used during image acquisition. More...

`#include <stdint.h>`

Go to the source code of this file.

## Data Structures
struct | DumpHardwareHeader
| Header that precedes a sequence of dump hardware entries and their variable-length payload. More...
struct | DumpHardwareEntry
| Per-environment length table describing subsequent UTF-8 strings and optional extent array. More...

## Typedefs
typedef struct DumpHardwareHeader | DumpHardwareHeader
typedef struct DumpHardwareEntry | DumpHardwareEntry

## Detailed Description

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 DumpHardwareEntry followed by a sequence of UTF‑8 strings and an optional array of extent ranges (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 also
  DumpHardwareHeader
  DumpHardwareEntry
  DumpExtent (in context.h)
  BlockType

Definition in file dump.h.

## Typedef Documentation

## ◆ DumpHardwareEntry

typedef struct DumpHardwareEntry DumpHardwareEntry

## ◆ DumpHardwareHeader

typedef struct DumpHardwareHeader DumpHardwareHeader