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