libaaruformat 1.0 Aaru Data Preservation Suite - Format Library

Loading...
Searching...
No Matches
ddt_v2.c File Reference
`#include <inttypes.h>`
`#include <stdint.h>`
`#include <stdio.h>`
`#include <stdlib.h>`
`#include "aaruformat.h"`
`#include "internal.h"`
`#include "log.h"`

Go to the source code of this file.

## Functions
int32_t | process_ddt_v2 (aaruformat_context *ctx, IndexEntry *entry, bool *found_user_data_ddt)
| Processes a DDT v2 block from the image stream.
int32_t | decode_ddt_entry_v2 (aaruformat_context *ctx, const uint64_t sector_address, bool negative, uint64_t *offset, uint64_t *block_offset, uint8_t *sector_status)
| Decodes a DDT v2 entry for a given sector address.
int32_t | decode_ddt_single_level_v2 (aaruformat_context *ctx, uint64_t sector_address, bool negative, uint64_t *offset, uint64_t *block_offset, uint8_t *sector_status)
| Decodes a single-level DDT v2 entry for a given sector address.
int32_t | decode_ddt_multi_level_v2 (aaruformat_context *ctx, uint64_t sector_address, bool negative, uint64_t *offset, uint64_t *block_offset, uint8_t *sector_status)
| Decodes a multi-level DDT v2 entry for a given sector address.
bool | set_ddt_entry_v2 (aaruformat_context *ctx, const uint64_t sector_address, bool negative, const uint64_t offset, const uint64_t block_offset, const uint8_t sector_status, uint64_t *ddt_entry)
| Sets a DDT v2 entry for a given sector address.
bool | set_ddt_single_level_v2 (aaruformat_context *ctx, uint64_t sector_address, const bool negative, const uint64_t offset, const uint64_t block_offset, const uint8_t sector_status, uint64_t *ddt_entry)
| Sets a single-level DDT v2 entry for a given sector address.
bool | set_ddt_multi_level_v2 (aaruformat_context *ctx, uint64_t sector_address, bool negative, uint64_t offset, uint64_t block_offset, uint8_t sector_status, uint64_t *ddt_entry)
| Sets a multi-level DDT v2 entry for a given sector address.
bool | set_ddt_tape (aaruformat_context *ctx, uint64_t sector_address, const uint64_t offset, const uint64_t block_offset, const uint8_t sector_status, uint64_t *ddt_entry)
| Sets a DDT entry for tape media using a hash-based lookup table.

## Function Documentation

## ◆ decode_ddt_entry_v2()

int32_t decode_ddt_entry_v2 | ( | aaruformat_context * | ctx,
|  | const uint64_t | sector_address,
|  | bool | negative,
|  | uint64_t * | offset,
|  | uint64_t * | block_offset,
|  | uint8_t * | sector_status )

Decodes a DDT v2 entry for a given sector address.

Determines the offset and block offset for a sector using the DDT v2 table(s). This function acts as a dispatcher that automatically selects between single-level and multi-level DDT decoding based on the tableShift parameter in the DDT header. It provides a unified interface for DDT v2 entry decoding regardless of the underlying table structure complexity.

Parameters

  ctx | Pointer to the aaruformat context containing the loaded DDT structures.
  sector_address | Logical sector address to decode (will be adjusted for negative sectors).
  negative | Indicates if the sector address is negative.
  offset | Pointer to store the resulting sector offset within the block.
  block_offset | Pointer to store the resulting block offset in the image.
  sector_status | Pointer to store the sector status (dumped, not dumped, etc.).

Returns
  Returns one of the following status codes:

Return values

  AARUF_STATUS_OK | (0) Successfully decoded the DDT entry. This is always returned when: The context and image stream are valid The appropriate decoding function (single-level or multi-level) completes successfully All output parameters are properly populated with decoded values
  AARUF_ERROR_NOT_AARUFORMAT | (-1) The context or image stream is invalid (NULL pointers). This is the only error condition that can occur at this dispatcher level.
  Other | error codes may be returned by the underlying decoding functions: From decode_ddt_single_level_v2(): AARUF_ERROR_CANNOT_READ_BLOCK (-7) From decode_ddt_multi_level_v2(): AARUF_ERROR_CANNOT_READ_BLOCK (-7), AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK (-17), AARUF_ERROR_INVALID_BLOCK_CRC (-18)

Note
  Function Selection:
  - If tableShift > 0: Uses multi-level DDT decoding (decode_ddt_multi_level_v2)
  - If tableShift = 0: Uses single-level DDT decoding (decode_ddt_single_level_v2)
  - The tableShift parameter is read from ctx->userDataDdtHeader.tableShift
  This function performs minimal validation and primarily acts as a dispatcher. Most error conditions and complex logic are handled by the underlying functions.

Warning
  The function assumes the DDT has been properly loaded by process_ddt_v2(). Calling this function with an uninitialized or corrupted DDT will result in undefined behavior from the underlying decoding functions.
  All output parameters must be valid pointers. No bounds checking is performed on the sector_address parameter at this level.

Definition at line 507 of file ddt_v2.c.

References AARUF_ERROR_NOT_AARUFORMAT, decode_ddt_multi_level_v2(), decode_ddt_single_level_v2(), FATAL, aaruformat_context::imageStream, DdtHeader2::tableShift, TRACE, and aaruformat_context::user_data_ddt_header.

Referenced by aaruf_read_sector().

## ◆ decode_ddt_multi_level_v2()

int32_t decode_ddt_multi_level_v2 | ( | aaruformat_context * | ctx,
|  | uint64_t | sector_address,
|  | bool | negative,
|  | uint64_t * | offset,
|  | uint64_t * | block_offset,
|  | uint8_t * | sector_status )

Decodes a multi-level DDT v2 entry for a given sector address.

Used when the DDT table uses multi-level indirection (tableShift > 0). This function handles the complex process of navigating a hierarchical DDT structure where the primary table points to secondary tables that contain the actual sector mappings. It includes caching mechanisms for secondary tables, supports both compressed and uncompressed secondary tables, and performs comprehensive validation including CRC verification.

Parameters

  ctx | Pointer to the aaruformat context containing the loaded primary DDT table.
  sector_address | Logical sector address to decode (adjusted for negative sectors).
  negative | Indicates if the sector address is negative.
  offset | Pointer to store the resulting sector offset within the block.
  block_offset | Pointer to store the resulting block offset in the image.
  sector_status | Pointer to store the sector status (dumped, not dumped, etc.).

Returns
  Returns one of the following status codes:

Return values

  AARUF_STATUS_OK | (0) Successfully decoded the DDT entry. This is returned when: The context and image stream are valid The tableShift validation passes (must be > 0) The DDT size type is recognized (SmallDdtSizeType or BigDdtSizeType) Secondary DDT table is successfully loaded (from cache or file) Secondary DDT decompression succeeds (if needed) Secondary DDT CRC validation passes The DDT entry is successfully extracted and decoded All output parameters are properly populated with decoded values Zero DDT entries are handled (indicates sector not dumped)
  AARUF_ERROR_NOT_AARUFORMAT | (-1) The context or image stream is invalid (NULL pointers).
  AARUF_ERROR_CANNOT_READ_BLOCK | (-7) Configuration, validation, or file access errors. This occurs when: The tableShift is zero (should use single-level decoding instead) The DDT size type is unknown/unsupported (not SmallDdtSizeType or BigDdtSizeType) Cannot read the secondary DDT header from the image stream Secondary DDT header validation fails (wrong identifier or type) Cannot read uncompressed secondary DDT data from the image stream CRC64 context initialization fails (internal error) Memory allocation fails for secondary DDT data (critical failure) Unknown compression type encountered in secondary DDT
  AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK | (-17) LZMA decompression failed for secondary DDT. This occurs when: Memory allocation fails for compressed data or decompression buffer Cannot read LZMA properties from the image stream Cannot read compressed secondary DDT data from the image stream The LZMA decoder returns a non-zero error code during decompression The decompressed data size doesn't match the expected secondary DDT length
  AARUF_ERROR_INVALID_BLOCK_CRC | (-18) CRC64 validation failed for secondary DDT. This occurs when: Calculated CRC64 doesn't match the expected CRC64 in the secondary DDT header Data corruption is detected in the secondary DDT data This applies to both compressed and uncompressed secondary DDT blocks

Note
  Multi-level DDT Navigation:
  - Uses tableShift to calculate items per DDT entry (2^tableShift)
  - Calculates DDT position by dividing sector address by items per entry
  - Retrieves secondary DDT offset from primary table at calculated position
  - Converts block offset to file offset using blockAlignmentShift
  Secondary DDT Caching:
  - Maintains a single cached secondary DDT in memory (ctx->cachedSecondaryDdtSmall/Big)
  - Compares requested offset with cached offset (ctx->cachedDdtOffset)
  - Only loads from disk if the requested secondary DDT is not currently cached
  - Caching improves performance for sequential sector access patterns
  Secondary DDT Processing:
  - Supports both LZMA compression and uncompressed formats
  - Performs full CRC64 validation of secondary DDT data
  - Same bit manipulation as single-level DDT for final entry decoding
  Error Handling Strategy:
  - Memory allocation failures for secondary DDT loading are treated as critical errors
  - File I/O errors and validation failures cause immediate function termination
  - Unknown compression types are treated as errors (unlike the processing functions)
  - All allocated memory is cleaned up on error conditions

Warning
  This function should only be called when tableShift > 0. Calling it with tableShift = 0 will result in AARUF_ERROR_CANNOT_READ_BLOCK.
  The function assumes the primary DDT table has been properly loaded and is accessible via ctx->userDataDdtMini or ctx->userDataDdtBig depending on size type.
  Secondary DDT caching means that memory usage can increase during operation. The cached secondary DDT is replaced when a different secondary table is needed.
  No bounds checking is performed on sector_address or calculated DDT positions. Accessing beyond table boundaries will result in undefined behavior.

Definition at line 724 of file ddt_v2.c.

References aaruf_crc64_final(), aaruf_crc64_init(), aaruf_crc64_update(), AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK, AARUF_ERROR_CANNOT_READ_BLOCK, AARUF_ERROR_INVALID_BLOCK_CRC, AARUF_ERROR_NOT_AARUFORMAT, aaruf_lzma_decode_buffer(), AARUF_STATUS_OK, DdtHeader2::blockAlignmentShift, aaruformat_context::cached_ddt_offset, aaruformat_context::cached_secondary_ddt2, DdtHeader2::cmpLength, DdtHeader2::compression, DdtHeader2::crc64, DdtHeader2::dataShift, DeDuplicationTableSecondary, FATAL, DdtHeader2::identifier, aaruformat_context::imageStream, DdtHeader2::length, Lzma, LZMA_PROPERTIES_LENGTH, DdtHeader2::negative, None, SectorStatusNotDumped, DdtHeader2::tableShift, TRACE, DdtHeader2::type, aaruformat_context::user_data_ddt2, aaruformat_context::user_data_ddt_header, and UserData.

Referenced by decode_ddt_entry_v2().

## ◆ decode_ddt_single_level_v2()

int32_t decode_ddt_single_level_v2 | ( | aaruformat_context * | ctx,
|  | uint64_t | sector_address,
|  | bool | negative,
|  | uint64_t * | offset,
|  | uint64_t * | block_offset,
|  | uint8_t * | sector_status )

Decodes a single-level DDT v2 entry for a given sector address.

Used when the DDT table does not use multi-level indirection (tableShift = 0). This function performs direct lookup in the primary DDT table to extract sector offset, block offset, and sector status information. It performs bit manipulation to decode the packed DDT entry values.

Parameters

  ctx | Pointer to the aaruformat context containing the loaded DDT table.
  sector_address | Logical sector address to decode (adjusted for negative sectors).
  negative | Indicates if the sector address is negative.
  offset | Pointer to store the resulting sector offset within the block.
  block_offset | Pointer to store the resulting block offset in the image.
  sector_status | Pointer to store the sector status (dumped, not dumped, etc.).

Returns
  Returns one of the following status codes:

Return values

  AARUF_STATUS_OK | (0) Successfully decoded the DDT entry. This is always returned when: The context and image stream are valid The tableShift validation passes (must be 0) The DDT size type is recognized (SmallDdtSizeType or BigDdtSizeType) The DDT entry is successfully extracted and decoded All output parameters are properly populated with decoded values Zero DDT entries are handled (indicates sector not dumped)
  AARUF_ERROR_NOT_AARUFORMAT | (-1) The context or image stream is invalid (NULL pointers).
  AARUF_ERROR_CANNOT_READ_BLOCK | (-7) Configuration or validation errors. This occurs when: The tableShift is not zero (should use multi-level decoding instead) The DDT size type is unknown/unsupported (not SmallDdtSizeType or BigDdtSizeType) Internal consistency checks fail

Note
  DDT Entry Decoding
  - Bits 63-61: Sector status (4 bits)
  - Bits 60-0: Combined offset and block index (60 bits)
  - Offset mask: Derived from dataShift parameter
  - Block offset: Calculated using blockAlignmentShift parameter
  Negative Sector Handling:
  - Sector address is automatically adjusted by adding ctx->userDataDdtHeader.negative
  - This allows proper indexing into the DDT table for negative sector addresses
  Zero Entry Handling:
  - A zero DDT entry indicates the sector was not dumped
  - Sets sector_status to SectorStatusNotDumped and zeros offset/block_offset
  - This is a normal condition and not an error

Warning
  The function assumes the DDT table has been properly loaded and is accessible via ctx->userDataDdtMini or ctx->userDataDdtBig depending on size type.
  No bounds checking is performed on sector_address. Accessing beyond the DDT table boundaries will result in undefined behavior.
  This function should only be called when tableShift is 0. Calling it with tableShift > 0 will result in AARUF_ERROR_CANNOT_READ_BLOCK.

Definition at line 581 of file ddt_v2.c.

References AARUF_ERROR_CANNOT_READ_BLOCK, AARUF_ERROR_NOT_AARUFORMAT, AARUF_STATUS_OK, DdtHeader2::blockAlignmentShift, DdtHeader2::dataShift, FATAL, aaruformat_context::imageStream, DdtHeader2::negative, SectorStatusNotDumped, DdtHeader2::tableShift, TRACE, aaruformat_context::user_data_ddt2, and aaruformat_context::user_data_ddt_header.

Referenced by decode_ddt_entry_v2().

## ◆ process_ddt_v2()

int32_t process_ddt_v2 | ( | aaruformat_context * | ctx,
|  | IndexEntry * | entry,
|  | bool * | found_user_data_ddt )

Processes a DDT v2 block from the image stream.

Reads and decompresses (if needed) a DDT v2 block, verifies its CRC, and loads it into memory. This function handles both user data DDT blocks and CD sector prefix/suffix corrected DDT blocks, supporting both LZMA compression and uncompressed formats. It performs CRC64 validation and stores the processed DDT data in the appropriate context fields based on size type (small/big).

Parameters

  ctx | Pointer to the aaruformat context.
  entry | Pointer to the index entry describing the DDT block.
  found_user_data_ddt | Pointer to a boolean that will be set to true if a user data DDT was found and loaded.

Returns
  Returns one of the following status codes:

Return values

  AARUF_STATUS_OK | (0) Successfully processed the DDT block. This is returned when: The DDT block is successfully read, decompressed (if needed), and loaded into memory CRC64 validation passes for the DDT data User data DDT blocks are processed and context is properly updated CD sector prefix/suffix corrected DDT blocks are processed successfully Memory allocation failures occur for non-critical operations (processing continues) File reading errors occur for compressed data or LZMA properties (processing continues) Unknown compression types are encountered (block is skipped)
  AARUF_ERROR_NOT_AARUFORMAT | (-1) The context or image stream is invalid (NULL pointers).
  AARUF_ERROR_CANNOT_READ_BLOCK | (-7) Failed to access the DDT block in the image stream. This occurs when: fseek() fails to position at the DDT block offset The file position doesn't match the expected offset after seeking Failed to read the DDT header from the image stream The number of bytes read for the DDT header is insufficient CRC64 context initialization fails (internal error)
  AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK | (-17) LZMA decompression failed. This can happen when: The LZMA decoder returns a non-zero error code during decompression The decompressed data size doesn't match the expected DDT block length This error causes immediate function termination and memory cleanup
  AARUF_ERROR_INVALID_BLOCK_CRC | (-18) CRC64 validation failed. This occurs when: Calculated CRC64 doesn't match the expected CRC64 in the DDT header Data corruption is detected in the DDT block This applies to both compressed and uncompressed DDT blocks

Note
  Error Handling Strategy:
  - Critical errors (seek failures, header read failures, decompression failures, CRC failures) cause immediate return
  - Non-critical errors (memory allocation failures, unknown compression types) allow processing to continue
  - The found_user_data_ddt flag is updated to reflect the success of user data DDT loading
  DDT v2 Features:
  - Handles multi-level DDT hierarchies with tableShift parameter
  - Updates context with sector counts, DDT version, and primary DDT offset
  - Stores DDT data in size-appropriate context fields (userDataDdtMini/Big, sectorPrefixDdt, etc.)
  Memory Management:
  - Allocated DDT data is stored in the context and becomes part of the context lifecycle
  - Memory is automatically cleaned up on decompression or CRC validation errors
  - Buffer memory is reused for the final DDT data storage (no double allocation)
  CRC Validation:
  - All DDT blocks undergo CRC64 validation regardless of compression type
  - CRC is calculated on the final decompressed data
  - Uses standard CRC64 calculation (no version-specific endianness conversion like v1)

Warning
  The function modifies context state including sector count, DDT version, and primary DDT offset. Ensure proper context cleanup when the function completes.
  Memory allocated for DDT data becomes part of the context and should not be freed separately. The context cleanup functions will handle DDT memory deallocation.

Definition at line 96 of file ddt_v2.c.

References aaruf_crc64_final(), aaruf_crc64_init(), aaruf_crc64_update(), AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK, AARUF_ERROR_CANNOT_READ_BLOCK, AARUF_ERROR_INVALID_BLOCK_CRC, AARUF_ERROR_NOT_AARUFORMAT, aaruf_lzma_decode_buffer(), AARUF_STATUS_OK, DdtHeader2::blocks, CdSectorPrefix, CdSectorSuffix, DdtHeader2::cmpLength, DdtHeader2::compression, DdtHeader2::crc64, IndexEntry::dataType, aaruformat_context::ddt_version, FATAL, aaruformat_context::image_info, ImageInfo::ImageSize, aaruformat_context::imageStream, aaruformat_context::in_memory_ddt, DdtHeader2::length, Lzma, LZMA_PROPERTIES_LENGTH, DdtHeader2::negative, None, IndexEntry::offset, DdtHeader2::overflow, aaruformat_context::primary_ddt_offset, aaruformat_context::sector_prefix_ddt2, aaruformat_context::sector_suffix_ddt2, ImageInfo::Sectors, TRACE, aaruformat_context::user_data_ddt2, aaruformat_context::user_data_ddt_header, and UserData.

Referenced by aaruf_open().

## ◆ set_ddt_entry_v2()

bool set_ddt_entry_v2 | ( | aaruformat_context * | ctx,
|  | const uint64_t | sector_address,
|  | bool | negative,
|  | const uint64_t | offset,
|  | const uint64_t | block_offset,
|  | const uint8_t | sector_status,
|  | uint64_t * | ddt_entry )

Sets a DDT v2 entry for a given sector address.

Updates the DDT v2 table(s) with the specified offset, block offset, and sector status for a sector.

Parameters

  ctx | Pointer to the aaruformat context.
  sector_address | Logical sector address to set.
  negative | Indicates if the sector address is negative.
  offset | Offset to set for the sector.
  block_offset | Block offset to set for the sector.
  sector_status | Status to set for the sector.
  ddt_entry | Existing DDT entry or 0 to create a new one. If 0, a new entry is returned.

Returns
  Returns one of the following status codes:

Return values

  true | if the entry was set successfully, false otherwise.

Definition at line 988 of file ddt_v2.c.

References FATAL, aaruformat_context::imageStream, set_ddt_multi_level_v2(), set_ddt_single_level_v2(), DdtHeader2::tableShift, TRACE, and aaruformat_context::user_data_ddt_header.

Referenced by aaruf_write_sector().

## ◆ set_ddt_multi_level_v2()

bool set_ddt_multi_level_v2 | ( | aaruformat_context * | ctx,
|  | uint64_t | sector_address,
|  | bool | negative,
|  | uint64_t | offset,
|  | uint64_t | block_offset,
|  | uint8_t | sector_status,
|  | uint64_t * | ddt_entry )

Sets a multi-level DDT v2 entry for a given sector address.

Used when the DDT table uses multi-level indirection (tableShift > 0).

Parameters

  ctx | Pointer to the aaruformat context.
  sector_address | Logical sector address to set.
  negative | Indicates if the sector address is negative.
  offset | Offset to set for the sector.
  block_offset | Block offset to set for the sector.
  sector_status | Status to set for the sector.
  ddt_entry | Existing DDT entry or 0 to create a new one. If 0, a new entry is returned.

Returns
  Returns one of the following status codes:

Return values

  true | if the entry was set successfully, false otherwise.

Definition at line 1092 of file ddt_v2.c.

References aaruf_close_current_block(), aaruf_crc64_data(), aaruf_crc64_final(), aaruf_crc64_init(), aaruf_crc64_update(), AARUF_ERROR_NOT_ENOUGH_MEMORY, aaruf_lzma_encode_buffer(), DdtHeader2::blockAlignmentShift, DdtHeader2::blocks, IndexEntry::blockType, aaruformat_context::cached_ddt_offset, aaruformat_context::cached_ddt_position, aaruformat_context::cached_secondary_ddt2, DdtHeader2::cmpCrc64, DdtHeader2::cmpLength, DdtHeader2::compression, aaruformat_context::compression_enabled, DdtHeader2::crc64, DdtHeader2::dataShift, IndexEntry::dataType, DeDuplicationTable2, DeDuplicationTableSecondary, DdtHeader2::entries, FATAL, DdtHeader2::identifier, aaruformat_context::imageStream, aaruformat_context::index_entries, DdtHeader2::length, DdtHeader2::levels, Lzma, aaruformat_context::lzma_dict_size, LZMA_PROPERTIES_LENGTH, DdtHeader2::negative, aaruformat_context::next_block_position, None, IndexEntry::offset, DdtHeader2::overflow, DdtHeader2::previousLevelOffset, aaruformat_context::primary_ddt_offset, DdtHeader2::start, DdtHeader2::tableLevel, DdtHeader2::tableShift, TRACE, DdtHeader2::type, aaruformat_context::user_data_ddt2, aaruformat_context::user_data_ddt_header, UserData, and aaruformat_context::writing_buffer.

Referenced by set_ddt_entry_v2().

## ◆ set_ddt_single_level_v2()

bool set_ddt_single_level_v2 | ( | aaruformat_context * | ctx,
|  | uint64_t | sector_address,
|  | const bool | negative,
|  | const uint64_t | offset,
|  | const uint64_t | block_offset,
|  | const uint8_t | sector_status,
|  | uint64_t * | ddt_entry )

Sets a single-level DDT v2 entry for a given sector address.

Used when the DDT table does not use multi-level indirection.

Parameters

  ctx | Pointer to the aaruformat context.
  sector_address | Logical sector address to set.
  negative | Indicates if the sector address is negative.
  offset | Offset to set for the sector.
  block_offset | Block offset to set for the sector.
  sector_status | Status to set for the sector.
  ddt_entry | Existing DDT entry or 0 to create a new one. If 0, a new entry is returned.

Returns
  Returns one of the following status codes:

Return values

  true | if the entry was set successfully, false otherwise.

Definition at line 1023 of file ddt_v2.c.

References DdtHeader2::blockAlignmentShift, DdtHeader2::dataShift, FATAL, aaruformat_context::imageStream, DdtHeader2::negative, DdtHeader2::tableShift, TRACE, aaruformat_context::user_data_ddt2, and aaruformat_context::user_data_ddt_header.

Referenced by set_ddt_entry_v2().

## ◆ set_ddt_tape()

bool set_ddt_tape | ( | aaruformat_context * | ctx,
|  | uint64_t | sector_address,
|  | const uint64_t | offset,
|  | const uint64_t | block_offset,
|  | const uint8_t | sector_status,
|  | uint64_t * | ddt_entry )

Sets a DDT entry for tape media using a hash-based lookup table.

This function is specifically designed for tape media images where sectors are accessed non-sequentially and the traditional DDT array structure is inefficient. Instead of using a large contiguous array, it uses a hash table (UTHASH) to store only the sectors that have been written, providing sparse storage for tape media.

The function performs the following operations:

1. Validates the context and verifies it's a tape image
2. Constructs a DDT entry encoding offset, block alignment, and sector status
3. Creates a hash table entry with the sector address as the key
4. Inserts or replaces the entry in the tape DDT hash table

DDT Entry Format: The DDT entry is a 64-bit value with the following bit layout:

Bits 0-(dataShift-1): Sector offset within block (masked by dataShift)
Bits dataShift-27: Block index (block_offset >> blockAlignmentShift)
Bits 28-31: Sector status (4 bits for status flags)
Bits 32-63: Unused (reserved for future use)

Hash Table Management: Uses HASH_REPLACE macro from UTHASH library which:

- Adds new entries if the key (sector_address) doesn't exist
- Replaces existing entries if the key is found (automatically frees old entry)
- Maintains O(1) average lookup time for sector address resolution

Overflow Detection: The function checks if the constructed DDT entry exceeds 28 bits (0xFFFFFFF). This limit ensures the sector status can fit in the upper 4 bits while leaving room for future extensions in the upper 32 bits.

Parameters

  ctx | Pointer to the aaruformat context. Must not be NULL. The context must have a valid imageStream and is_tape must be true. The ctx->tapeDdt hash table will be updated with the new entry. The ctx->userDataDdtHeader contains alignment and shift parameters.
  sector_address | Logical sector address on the tape to set. This serves as the unique key in the hash table. Multiple calls with the same sector_address will replace the previous entry.
  offset | Byte offset within the aligned block where the sector data begins. This value is masked by (1 << dataShift) - 1 to extract only the lower bits representing the offset within the block.
  block_offset | Absolute byte offset in the image file where the data block starts. This is right-shifted by blockAlignmentShift to get the block index, which is stored in the DDT entry's middle bits.
  sector_status | Status flags for the sector (4 bits). Common values include: 0x0 (SectorStatusNotDumped): Sector not yet acquired during image dumping 0x1 (SectorStatusDumped): Sector successfully dumped without error 0x2 (SectorStatusErrored): Error during dumping; data may be incomplete or corrupt 0x3 (SectorStatusMode1Correct): Valid MODE 1 data with regenerable suffix/prefix 0x4 (SectorStatusMode2Form1Ok): Suffix verified/regenerable for MODE 2 Form 1 0x5 (SectorStatusMode2Form2Ok): Suffix matches MODE 2 Form 2 with valid CRC 0x6 (SectorStatusMode2Form2NoCrc): Suffix matches MODE 2 Form 2 but CRC empty/missing 0x7 (SectorStatusTwin): Pointer references a twin sector table 0x8 (SectorStatusUnrecorded): Sector physically unrecorded; repeated reads non-deterministic 0x9 (SectorStatusEncrypted): Content encrypted and stored encrypted in image 0xA (SectorStatusUnencrypted): Content originally encrypted but stored decrypted in image See SectorStatus enum for complete list of defined values
  ddt_entry | Pointer to a 64-bit value that will receive the constructed DDT entry. If *ddt_entry is 0: A new entry is constructed from the provided parameters If *ddt_entry is non-zero: The existing value is used directly The constructed or provided value is stored in the hash table.

Returns
  Returns one of the following status codes:

Return values

  true | Successfully created and inserted the DDT entry. This occurs when: The context and image stream are valid The image is confirmed to be a tape image (is_tape == true) The DDT entry fits within the 28-bit limit (< 0xFFFFFFF) Memory allocation for the hash entry succeeds The entry is successfully inserted or replaced in the hash table
  false | Failed to set the DDT entry. This can happen when: ctx is NULL or ctx->imageStream is NULL (invalid context) ctx->is_tape is false (wrong function called for non-tape media) The DDT entry exceeds 0xFFFFFFF (media too large for big DDT) Memory allocation fails for the new hash table entry (out of memory)

Note
  This function is only for tape images. For disk images, use set_ddt_single_level_v2() or set_ddt_multi_level_v2() instead, which use array-based DDT structures.
  Memory Management:
  - Allocates a new TapeDdtHashEntry for each sector
  - HASH_REPLACE automatically frees replaced entries
  - All hash entries remain in context until cleanup
  - The tapeDdt hash table must be freed during context destruction
  Tape Media Characteristics:
  - Tape sectors are typically accessed sequentially during streaming
  - File marks and partition boundaries create sparse address spaces
  - Hash table provides efficient storage for sparse sector maps
  - Supports variable block sizes common in tape formats
  Error Handling:
  - All errors are logged with FATAL level messages
  - Function returns false immediately on any error condition
  - TRACE logging marks entry/exit points for debugging
  - No partial state changes occur on failure

Warning
  The DDT entry overflow check at 0xFFFFFFF (28 bits) is critical. Exceeding this limit indicates the media is too large to fit in the current DDT format, and continuing would cause data corruption.
  This function modifies the shared tapeDdt hash table. In multi-threaded environments, external synchronization is required to prevent race conditions.

See also
  TapeDdtHashEntry for the hash table entry structure
  set_ddt_entry_v2() for the main DDT entry point that dispatches to this function
  get_ddt_tape() for retrieving tape DDT entries from the hash table

Definition at line 1768 of file ddt_v2.c.

References DdtHeader2::blockAlignmentShift, DdtHeader2::dataShift, FATAL, aaruformat_context::imageStream, aaruformat_context::is_tape, TapeDdtHashEntry::key, aaruformat_context::tape_ddt, TRACE, aaruformat_context::user_data_ddt_header, and TapeDdtHashEntry::value.