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

Data structures for flux transition capture support in Aaru disk images. More...

`#include <stdint.h>`

Go to the source code of this file.

## Data Structures

struct | FluxHeader
| Header structure for a FluxDataBlock containing flux capture metadata. More...
struct | FluxEntry
| Metadata entry describing a single flux capture in the FluxDataBlock. More...
struct | FluxCaptureMeta
| Metadata structure returned by aaruf_get_flux_captures(). More...
struct | DataStreamPayloadHeader
| Header structure for a DataStreamPayloadBlock containing data stream payload. More...
struct | FluxCaptureRecord
| Internal structure for storing flux capture data during write mode. More...
struct | FluxCaptureKey
| Key structure for flux capture lookup map. More...

## Typedefs

typedef struct FluxHeader | FluxHeader
typedef struct FluxEntry | FluxEntry
typedef struct FluxCaptureMeta | FluxCaptureMeta
typedef struct DataStreamPayloadHeader | DataStreamPayloadHeader
typedef struct FluxCaptureRecord | FluxCaptureRecord
typedef struct FluxCaptureKey | FluxCaptureKey

## Detailed Description

Data structures for flux transition capture support in Aaru disk images.

This header defines structures used to represent flux transition data captured from magnetic media. Flux transitions are the raw analog signals read from magnetic storage devices (such as floppy disks, hard drives, and tape) before they are interpreted into digital data.

Flux Capture Overview: Certain hardware devices, such as Kryoflux, Pauline, and Applesauce, read magnetic media at the flux transition level rather than at the sector level. This provides a more complete representation of the analog properties of the media, allowing for advanced recovery techniques and preservation of media characteristics that would be lost in sector-level imaging.

Block Structure: Flux data is stored in two block types:

- FluxDataBlock: Contains metadata entries describing all flux captures in the image. Each entry includes location information (head, track, subtrack), capture index, resolution data, and file offsets to the payload blocks.
- DataStreamPayloadBlock: Contains the actual flux data and index buffers for a single capture. Payload blocks may be compressed using LZMA compression.

Data Organization: Each flux capture includes two data streams:

- Data buffer: Raw flux transition timing data, represented as an array of uint8_t bytes where each byte stores the tick count since the last flux transition. The value 0xFF indicates no transition within the byte range.
- Index buffer: Index structure mapping logical positions to offsets within the data buffer, enabling efficient access to specific regions of the flux data.

Capture Identification: Flux captures are uniquely identified by a tuple of (head, track, subtrack, captureIndex). This allows multiple captures for the same physical location, which is useful for capturing multiple revolutions of a floppy disk track or different read attempts.

Resolution: Each capture specifies two resolution values:

- dataResolution: The sampling resolution in picoseconds for the data stream
- indexResolution: The sampling resolution in picoseconds for the index stream

These resolutions determine the precision of the timing measurements and are hardware-dependent.

Storage Efficiency: Payload blocks support LZMA compression to reduce storage requirements. The compression is transparent to the API user - aaruf_read_flux_capture() handles decompression automatically.

Use Cases:

- Preservation of magnetic media at the lowest level possible
- Recovery of data from damaged or degraded media
- Analysis of media characteristics and timing variations
- Emulation and accurate reproduction of original media behavior
- Forensic imaging where complete bit-level accuracy is required

Note
  All structures in this file use packed alignment (#pragma pack(push, 1)) to ensure consistent on-disk layout across different compilers and platforms.

See also
  BlockType for the identifier constants used in FluxHeader and DataStreamPayloadHeader
  aaruf_get_flux_captures() to retrieve metadata for all captures
  aaruf_read_flux_capture() to read actual flux data
  aaruf_write_flux_capture() to add flux captures during write mode

Definition in file flux.h.

## Typedef Documentation

## DataStreamPayloadHeader

typedef struct DataStreamPayloadHeader DataStreamPayloadHeader

## FluxCaptureKey

typedef struct FluxCaptureKey FluxCaptureKey

## FluxCaptureMeta

typedef struct FluxCaptureMeta FluxCaptureMeta

## FluxCaptureRecord

typedef struct FluxCaptureRecord FluxCaptureRecord

## FluxEntry

typedef struct FluxEntry FluxEntry

## FluxHeader

typedef struct FluxHeader FluxHeader