#include <stdint.h>
#include <stdlib.h>
#include "aaruformat.h"
#include "internal.h"
#include "log.h"

Macros
#define	COPY_STRING_FIELD(field)

Functions
static void	free_dump_hardware_entries (DumpHardwareEntriesWithData *entries, uint32_t count)
int32_t	aaruf_get_dumphw (void context, uint8_t buffer, size_t *length)
	Retrieves the dump hardware block containing acquisition environment information.
int32_t	aaruf_set_dumphw (void context, uint8_t data, size_t length)
	Sets the dump hardware block for the image during creation.

Macro Definition Documentation

◆ COPY_STRING_FIELD

#define COPY_STRING_FIELD ( field )

Value:

    do                                                                              \
    {                                                                               \
        const size_t field##_length = copy[e].entry.field##Length;                  \
        if(field##_length > 0)                                                      \
        {                                                                           \
            if(field##_length > length - pos) goto invalid_data;                    \
            /* Allocate only field##_length bytes, since input is NUL-terminated */ \
            copy[e].field = (uint8_t *)calloc(1, field##_length);                   \
            if(copy[e].field == NULL) goto free_copy_and_error;                     \
            memcpy(copy[e].field, data + pos, field##_length);                      \
            /* Ensure NUL-termination in case input is malformed */                 \
            copy[e].field[field##_length - 1] = '\0';                               \
            pos += field##_length;                                                  \
        }                                                                           \
    } while(0)

Referenced by aaruf_set_dumphw().

Function Documentation

◆ aaruf_get_dumphw()

int32_t aaruf_get_dumphw	(	void *	context,
		uint8_t *	buffer,
		size_t *	length )

Retrieves the dump hardware block containing acquisition environment information.

Extracts the complete DumpHardwareBlock from the image, which documents the hardware and software environments used to create the image. A dump hardware block records one or more "dump environments" – typically combinations of physical devices (drives, controllers, adapters) and the software stacks that performed the read operations. This metadata is essential for understanding the imaging context, validating acquisition integrity, reproducing imaging conditions, and supporting forensic or archival documentation requirements.

Each environment entry includes hardware identification (manufacturer, model, revision, firmware, serial number), software identification (name, version, operating system), and optional extent ranges that specify which logical sectors or units were contributed by that particular environment. This structure supports complex imaging scenarios where multiple devices or software configurations were used to create a composite image.

The function reconstructs the complete on-disk binary representation of the dump hardware block, including the DumpHardwareHeader followed by all entries with their variable-length UTF-8 strings and extent arrays. The reconstructed block includes a calculated CRC64 checksum over the payload data for integrity verification.

This function supports a two-call pattern for buffer size determination:

First call with insufficient buffer (or NULL) returns AARUF_ERROR_BUFFER_TOO_SMALL and sets *length to the required size (sizeof(DumpHardwareHeader) + total payload length)
Second call with properly sized buffer retrieves the complete block data

Alternatively, if the caller already knows the buffer is large enough, a single call will succeed and populate the buffer with the complete dump hardware block.

Parameters

context	Pointer to the aaruformat context (must be a valid, opened image context).
buffer	Pointer to a buffer that will receive the dump hardware block data. Must be large enough to hold the complete block (at least *length bytes on input). May be NULL to query the required buffer size. The buffer will contain the DumpHardwareHeader followed by serialized entries, strings, and extent arrays on success.
length	Pointer to a size_t that serves dual purpose: On input: size of the provided buffer in bytes (ignored if buffer is NULL) On output: actual size required/used for the dump hardware block in bytes If the function returns AARUF_ERROR_BUFFER_TOO_SMALL, this will be updated to contain the required buffer size for a subsequent successful call.

Returns: Returns one of the following status codes:

Return values

AARUF_STATUS_OK	(0) Successfully retrieved dump hardware block. This is returned when: The context is valid and properly initialized The dump hardware block is present (identifier == DumpHardwareBlock) The provided buffer is large enough (>= required length) All hardware entries with their strings and extents are copied to the buffer The DumpHardwareHeader is written with calculated CRC64 at buffer offset 0 The *length parameter is set to the actual block size
AARUF_ERROR_NOT_AARUFORMAT	(-1) The context is invalid. This occurs when: The context parameter is NULL The context magic number doesn't match AARU_MAGIC (invalid context type) The context was not properly initialized by aaruf_open() or aaruf_create()
AARUF_ERROR_CANNOT_READ_BLOCK	(-6) The dump hardware block is not present. This occurs when: The image was created without dump hardware information ctx->dumpHardwareEntriesWithData is NULL (no data loaded) ctx->dumpHardwareHeader.entries == 0 (no hardware entries) ctx->dumpHardwareHeader.identifier doesn't equal DumpHardwareBlock The dump hardware block was not found during image opening
AARUF_ERROR_BUFFER_TOO_SMALL	(-12) The provided buffer is insufficient. This occurs when: buffer is NULL (size query mode) The input length is less than sizeof(DumpHardwareHeader) + payload length The length parameter is updated to contain the required buffer size No data is copied to the buffer The caller should allocate a larger buffer and call again Also returned if calculated entry size exceeds buffer during iteration (sanity check)

Note

Dump Hardware Block Structure:

DumpHardwareHeader (16 bytes): identifier, entries count, payload length, CRC64
For each entry (variable size):
- DumpHardwareEntry (36 bytes): length fields for all strings and extent count
- Variable-length UTF-8 strings (in order): manufacturer, model, revision, firmware, serial, software name, software version, software operating system
- Array of DumpExtent structures (16 bytes each) if extent count > 0
All strings are UTF-8 encoded and NOT null-terminated in the serialized block
String lengths are in bytes, not character counts

Dump Hardware Environments:

Each entry represents one hardware/software combination used during imaging
Multiple entries support scenarios where different devices contributed different sectors
Extent arrays specify which logical sector ranges each environment contributed
Empty extent arrays (extents == 0) indicate the environment dumped the entire medium
Overlapping extents between entries may indicate verification passes or redundancy

Hardware Identification Fields:

manufacturer: Device manufacturer (e.g., "Plextor", "Sony", "Samsung")
model: Device model number (e.g., "PX-716A", "DRU-820A")
revision: Hardware revision identifier
firmware: Firmware version (e.g., "1.11", "KY08")
serial: Device serial number for unique identification

Software Identification Fields:

softwareName: Dumping software name (e.g., "Aaru", "ddrescue", "IsoBuster")
softwareVersion: Software version (e.g., "5.3.0", "1.25")
softwareOperatingSystem: Host OS (e.g., "Linux 5.10.0", "Windows 10", "macOS 12.0")

CRC64 Calculation:

The function calculates CRC64-ECMA over the payload (everything after the header)
The calculated CRC64 is stored in the returned DumpHardwareHeader
This allows verification of the serialized block integrity
The CRC64 is computed from buffer data, not from the original context

Buffer Layout After Successful Call:

Offset 0: DumpHardwareHeader with calculated CRC64
Offset 16: First DumpHardwareEntry
Followed by: First entry's UTF-8 strings (in documented order)
Followed by: First entry's DumpExtent array (if extents > 0)
Repeated for all remaining entries

Use Cases:

Forensic documentation requiring complete equipment chain of custody
Archival metadata for long-term preservation requirements
Reproducing imaging conditions for verification or re-imaging
Identifying firmware-specific issues or drive-specific behaviors
Multi-device imaging scenario documentation
Correlating imaging artifacts with specific hardware/software combinations

Warning: This function reads from the in-memory dump hardware data loaded during aaruf_open(). It does not perform file I/O operations. The data is reconstructed from the parsed context structures into the on-disk binary format.; The buffer must be valid and large enough to hold the entire dump hardware block. Passing a buffer smaller than required will result in AARUF_ERROR_BUFFER_TOO_SMALL.; String data in the serialized block is NOT null-terminated. Applications parsing the buffer must use the length fields in DumpHardwareEntry to determine string boundaries. The library adds null terminators only for in-memory convenience.; The function performs bounds checking during serialization. If calculated entry sizes exceed the buffer length, AARUF_ERROR_BUFFER_TOO_SMALL is returned even after the initial size check. This should not occur with properly sized buffers but protects against data corruption.

See also: DumpHardwareHeader for the block header structure definition.; DumpHardwareEntry for the per-environment entry structure definition.; DumpExtent for the extent range structure definition.; process_dumphw_block() for the loading process during image opening.

Definition at line 186 of file dump.c.

◆ aaruf_set_dumphw()

int32_t aaruf_set_dumphw	(	void *	context,
		uint8_t *	data,
		size_t	length )

Sets the dump hardware block for the image during creation.

Embeds dump hardware information into the image being created. The dump hardware block documents the hardware and software environments used to create the image, recording one or more "dump environments" – typically combinations of physical devices (drives, controllers, adapters) and the software stacks that performed the read operations. This metadata is essential for understanding the imaging context, validating acquisition integrity, reproducing imaging conditions, and supporting forensic or archival documentation requirements.

Each environment entry includes hardware identification (manufacturer, model, revision, firmware, serial number), software identification (name, version, operating system), and optional extent ranges that specify which logical sectors or units were contributed by that particular environment. This structure supports complex imaging scenarios where multiple devices or software configurations were used to create a composite image.

The function accepts a complete, pre-serialized DumpHardwareBlock in the on-disk binary format (as returned by aaruf_get_dumphw() or manually constructed). The block is validated for correct identifier, length consistency, and CRC64 integrity before being parsed and stored in the context. The function deserializes the binary block, extracts all entries with their variable-length UTF-8 strings and extent arrays, and creates null-terminated in-memory copies for internal use.

Validation performed:

Context validation (non-NULL, correct magic, write mode)
Data buffer validation (non-NULL, non-zero length)
Block identifier validation (must be DumpHardwareBlock)
Length consistency (buffer length must equal sizeof(DumpHardwareHeader) + header.length)
CRC64 integrity verification (calculated CRC64 must match header.crc64)

Parsing process:

Read and validate the DumpHardwareHeader from the buffer
Allocate array for all dump hardware entries
For each entry:
- Read the DumpHardwareEntry structure (36 bytes)
- Allocate and copy each non-empty UTF-8 string with +1 byte for null terminator
- Allocate and copy the DumpExtent array if extents > 0
Free any previously set dump hardware data
Store the new parsed data in ctx->dumpHardwareEntriesWithData
Store the header in ctx->dumpHardwareHeader

Memory management: If any memory allocation fails during parsing, all previously allocated memory for the new data is freed via the free_copy_and_error label, and AARUF_ERROR_NOT_ENOUGH_MEMORY is returned. Any existing dump hardware data in the context is freed before storing new data, ensuring no memory leaks when replacing dump hardware information.

Parameters

context	Pointer to the aaruformat context (must be a valid, write-enabled image context).
data	Pointer to the dump hardware block data in on-disk binary format. Must contain a complete DumpHardwareBlock starting with DumpHardwareHeader followed by all entries, strings, and extent arrays. Must not be NULL.
length	Length of the dump hardware block data in bytes. Must equal sizeof(DumpHardwareHeader) + header.length for validation to succeed.

Returns: Returns one of the following status codes:

Return values

AARUF_STATUS_OK	(0) Successfully set dump hardware block. This is returned when: The context is valid and properly initialized The context is opened in write mode (ctx->isWriting is true) The data buffer contains a valid DumpHardwareBlock The block identifier is DumpHardwareBlock The length is consistent (buffer length == header size + payload length) The CRC64 checksum is valid All memory allocations succeeded All entries with strings and extents are parsed and stored Any previous dump hardware data is freed ctx->dumpHardwareEntriesWithData is populated with parsed entries ctx->dumpHardwareHeader is updated with the new header
AARUF_ERROR_NOT_AARUFORMAT	(-1) The context is invalid. This occurs when: The context parameter is NULL The context magic number doesn't match AARU_MAGIC (invalid context type) The context was not properly initialized by aaruf_create()
AARUF_READ_ONLY	(-13) The context is not opened for writing. This occurs when: The image was opened with aaruf_open() instead of aaruf_create() The context's isWriting flag is false Attempting to modify a read-only image
AARUF_ERROR_CANNOT_READ_BLOCK	(-6) Invalid block identifier. This occurs when: The identifier field in the DumpHardwareHeader doesn't equal DumpHardwareBlock The data buffer doesn't contain a valid dump hardware block The block type is incorrect or corrupted
AARUF_ERROR_INCORRECT_DATA_SIZE	(-11) Invalid data or length. This occurs when: The data parameter is NULL The length parameter is 0 (empty block) The buffer length doesn't match sizeof(DumpHardwareHeader) + header.length Length inconsistency indicates corrupted or incomplete block data
AARUF_ERROR_INVALID_BLOCK_CRC	(-10) CRC64 checksum mismatch. This occurs when: The calculated CRC64 over the payload doesn't match header.crc64 Block data is corrupted or tampered with Block was not properly constructed or serialized
AARUF_ERROR_NOT_ENOUGH_MEMORY	(-8) Memory allocation failed. This occurs when: calloc() or malloc() failed to allocate memory for entries array Failed to allocate memory for any string field (manufacturer, model, etc.) Failed to allocate memory for extent arrays System is out of memory or memory is severely fragmented All partially allocated memory is freed before returning

Note

Dump Hardware Block Format:

The data buffer must contain a complete serialized DumpHardwareBlock
Format: DumpHardwareHeader + repeated entries with strings and extents
All strings are UTF-8 encoded and NOT null-terminated in the buffer
The function adds null terminators when copying strings to internal storage
String lengths are in bytes, not character counts

Creating Block Data:

Use aaruf_get_dumphw() to retrieve a block from an existing image
Manually construct by serializing DumpHardwareHeader, entries, strings, and extents
Calculate CRC64-ECMA over the payload (everything after the header)
Ensure all length fields accurately reflect the data sizes
Ensure total buffer size equals sizeof(DumpHardwareHeader) + payload length

Hardware Identification Fields:

manufacturer: Device manufacturer (e.g., "Plextor", "Sony", "Samsung")
model: Device model number (e.g., "PX-716A", "DRU-820A")
revision: Hardware revision identifier
firmware: Firmware version (e.g., "1.11", "KY08")
serial: Device serial number for unique identification

Software Identification Fields:

softwareName: Dumping software name (e.g., "Aaru", "ddrescue", "IsoBuster")
softwareVersion: Software version (e.g., "5.3.0", "1.25")
softwareOperatingSystem: Host OS (e.g., "Linux 5.10.0", "Windows 10", "macOS 12.0")

Extent Arrays:

Each DumpExtent specifies a [start, end] logical sector range
Extents indicate which sectors this environment contributed
Empty extent arrays (extents == 0) mean the environment dumped entire medium
Extents are stored in the order provided in the input buffer

Memory Ownership:

The function creates internal copies of all data
The caller retains ownership of the input data buffer
The caller may free the input buffer immediately after this function returns
Internal copies are freed during aaruf_close() or when replaced by another call

Replacing Existing Data:

Calling this function multiple times replaces previous dump hardware data
All previous entries, strings, and extents are freed before storing new data
No memory leaks occur when updating dump hardware information

Warning: The dump hardware block is only written to the image file during aaruf_close(). Changes made by this function are not immediately persisted to disk.; CRC64 validation protects against corrupted blocks, but construction errors in the input buffer (incorrect lengths, misaligned data) may cause parsing to fail or produce incorrect results even with a valid checksum.; The function assumes the input buffer is properly formatted and packed according to the DumpHardwareBlock specification. Malformed input may cause crashes or memory corruption.

See also: DumpHardwareHeader for the block header structure definition.; DumpHardwareEntry for the per-environment entry structure definition.; DumpExtent for the extent range structure definition.; aaruf_get_dumphw() for retrieving dump hardware from opened images.; write_dumphw_block() for the serialization process during image closing.

Definition at line 531 of file dump.c.

References AARU_CALL, AARU_EXPORT, AARU_MAGIC, aaruf_crc64_data(), AARUF_ERROR_CANNOT_READ_BLOCK, AARUF_ERROR_INCORRECT_DATA_SIZE, AARUF_ERROR_INVALID_BLOCK_CRC, AARUF_ERROR_NOT_AARUFORMAT, AARUF_ERROR_NOT_ENOUGH_MEMORY, AARUF_READ_ONLY, AARUF_STATUS_OK, compare_extents(), COPY_STRING_FIELD, DumpHardwareHeader::crc64, aaruformat_context::dirty_dumphw_block, aaruformat_context::dump_hardware_entries_with_data, aaruformat_context::dump_hardware_header, DumpHardwareBlock, DumpHardwareHeader::entries, DumpHardwareEntriesWithData::entry, DumpHardwareEntriesWithData::extents, DumpHardwareEntry::extents, FATAL, free_dump_hardware_entries(), DumpHardwareHeader::identifier, aaruformat_context::is_writing, DumpHardwareHeader::length, aaruformat_context::magic, and TRACE.

◆ free_dump_hardware_entries()

void free_dump_hardware_entries	(	DumpHardwareEntriesWithData *	entries,
		uint32_t	count )

static

Definition at line 26 of file dump.c.