Decompression API

CCSDS Section 5.3: Packet decompression. More...

Data Structures
struct	ccsds124_decompressor
	Decompressor state structure. More...

Functions
int	ccsds124_decompressor_init (ccsds124_decompressor_t *decomp, size_t F, const bitvector_t *initial_mask, uint8_t robustness)
	Initialize decompressor state.
void	ccsds124_decompressor_reset (ccsds124_decompressor_t *decomp)
	Reset decompressor to initial state.
int	ccsds124_decompressor_notify_packet_loss (ccsds124_decompressor_t *decomp, uint32_t lost_count)
	Notify decompressor of packet loss.
int	ccsds124_decompress_packet (ccsds124_decompressor_t *decomp, bitreader_t *reader, bitvector_t *output)
	Decompress a single compressed packet.
int	ccsds124_decompress_packet_checked (ccsds124_decompressor_t *decomp, const uint8_t *data, size_t num_bits, bitvector_t *output, ccsds124_decompress_result_t *result)
	Decompress a single packet with accuracy guarantee checking.
int	ccsds124_discover_packet_length (const uint8_t *data, size_t num_bits, uint32_t *packet_length)
	Discover packet length (F) from a compressed packet.
int	ccsds124_decompress (ccsds124_decompressor_t *decomp, const uint8_t *input_data, size_t input_size, uint8_t *output_buffer, size_t output_buffer_size, size_t *output_size)
	Decompress entire compressed data stream.

Detailed Description

CCSDS Section 5.3: Packet decompression.

High-level decompression interface for processing compressed packets.

Function Documentation

ccsds124_decompress()

int ccsds124_decompress	(	ccsds124_decompressor_t *	decomp,
		const uint8_t *	input_data,
		size_t	input_size,
		uint8_t *	output_buffer,
		size_t	output_buffer_size,
		size_t *	output_size
	)

Decompress entire compressed data stream.

High-level API that handles:

• Sequential packet decompression
• Byte boundary alignment between packets
• Output accumulation

Parameters

[in,out]	decomp	Decompressor state (must be initialized)
[in]	input_data	Compressed input byte array
[in]	input_size	Input size in bytes
[out]	output_buffer	Output buffer (caller-allocated)
[in]	output_buffer_size	Size of output buffer
[out]	output_size	Actual bytes written

Returns

CCSDS124_OK on success, error code otherwise

Definition at line 1083 of file decompress.c.

References bitreader_align_byte(), bitreader_init(), bitreader_remaining(), bitvector_to_bytes(), ccsds124_decompress_packet(), ccsds124_decompressor_reset(), CCSDS124_ERROR_INVALID_ARG, CCSDS124_ERROR_OVERFLOW, CCSDS124_OK, and ccsds124_decompressor::F.

Referenced by do_decompress().

ccsds124_decompress_packet()

int ccsds124_decompress_packet	(	ccsds124_decompressor_t *	decomp,
		bitreader_t *	reader,
		bitvector_t *	output
	)

Decompress a single compressed packet.

Decompresses one packet according to CCSDS 124.0-B-1 Section 5.3. Updates decompressor state for next packet.

Parameters

[in,out]	decomp	Decompressor state (updated in place)
[in,out]	reader	Bit reader positioned at packet start
[out]	output	Decompressed output packet (length F)

Returns

CCSDS124_OK on success, error code otherwise

Definition at line 740 of file decompress.c.

References ccsds124_decompress_packet_internal().

Referenced by ccsds124_decompress().

ccsds124_decompress_packet_checked()

int ccsds124_decompress_packet_checked	(	ccsds124_decompressor_t *	decomp,
		const uint8_t *	data,
		size_t	num_bits,
		bitvector_t *	output,
		ccsds124_decompress_result_t *	result
	)

Decompress a single packet with accuracy guarantee checking.

Like ccsds124_decompress_packet() but additionally tracks mask synchronization and evaluates the accuracy guarantee decision tree per CCSDS 124.0-B-1.

If the output is not accuracy-guaranteed, the decompressor state is restored to its pre-call value (except for count_f_mismatch cases where the mask was resynchronized via ft=1).

Parameters

[in,out]	decomp	Decompressor state (updated in place)
[in]	data	Compressed packet bytes
[in]	num_bits	Number of valid bits in data
[out]	output	Decompressed output packet (length F)
[out]	result	Optional result details (NULL to skip)

Returns

CCSDS124_OK if guaranteed, CCSDS124_STATUS_UNGUARANTEED if not, or negative error code on failure

Definition at line 749 of file decompress.c.

References bitreader_init(), bitreader_remaining(), ccsds124_decompress_packet_internal(), CCSDS124_ERROR_INVALID_ARG, CCSDS124_ERROR_OVERFLOW, CCSDS124_MAX_VT_HISTORY, CCSDS124_OK, CCSDS124_STATUS_UNGUARANTEED, ccsds124_decompressor::count_f_mismatch, ccsds124_decompress_result_t::ft, ccsds124_decompress_flags_t::ft, ccsds124_decompressor::mask_inconsistent, ccsds124_decompressor::mask_synced, ccsds124_decompressor::received_status_count, ccsds124_decompressor::received_status_index, ccsds124_decompressor::received_status_ring, ccsds124_decompress_result_t::rt, ccsds124_decompress_flags_t::rt, ccsds124_decompress_result_t::status, ccsds124_decompress_result_t::Vt, and ccsds124_decompress_flags_t::Vt.

ccsds124_decompressor_init()

int ccsds124_decompressor_init	(	ccsds124_decompressor_t *	decomp,
		size_t	F,
		const bitvector_t *	initial_mask,
		uint8_t	robustness
	)

Initialize decompressor state.

Sets up the decompressor for a new decompression session.

Parameters

[out]	decomp	Decompressor to initialize (caller-allocated)
[in]	F	Output vector length in bits
[in]	initial_mask	M₀ initial mask (NULL = all zeros)
[in]	robustness	Rₜ base robustness level (0-7)

Returns

CCSDS124_OK on success, error code otherwise

Definition at line 335 of file decompress.c.

References bitvector_copy(), bitvector_init(), bitvector_zero(), ccsds124_decompressor_reset(), CCSDS124_ERROR_INVALID_ARG, CCSDS124_MAX_PACKET_LENGTH, CCSDS124_MAX_ROBUSTNESS, CCSDS124_OK, ccsds124_decompressor::count_f_mismatch, ccsds124_decompressor::F, ccsds124_decompressor::initial_mask, ccsds124_decompressor::mask, ccsds124_decompressor::mask_inconsistent, ccsds124_decompressor::mask_synced, ccsds124_decompressor::prev_output, ccsds124_decompressor::received_status_count, ccsds124_decompressor::received_status_index, ccsds124_decompressor::received_status_ring, ccsds124_decompressor::robustness, and ccsds124_decompressor::Xt.

Referenced by do_decompress().

ccsds124_decompressor_notify_packet_loss()

int ccsds124_decompressor_notify_packet_loss	(	ccsds124_decompressor_t *	decomp,
		uint32_t	lost_count
	)

Notify decompressor of packet loss.

Informs the decompressor that one or more packets were lost. The decompressor advances its internal time index and prepares for recovery using the next received packet's robustness info.

Per CCSDS 124.0-B-1 Section 2.2: "The Recommended Standard does not provide a mechanism for identifying the number of sequential output binary vectors that were lost. Such mechanisms are assumed to be mission specific." This function provides that mechanism.

Recovery behavior:

• If lost_count <= effective robustness (Vt), the next packet's Xt window contains all mask changes, enabling mask recovery.
• For full data recovery, the next packet should have rt=1 (uncompressed) to provide a valid prediction base.

Parameters

[in,out]	decomp	Decompressor state (updated in place)
[in]	lost_count	Number of consecutive packets lost (1+)

Returns

CCSDS124_OK on success, error code otherwise

Definition at line 409 of file decompress.c.

References CCSDS124_ERROR_INVALID_ARG, CCSDS124_MAX_VT_HISTORY, CCSDS124_OK, ccsds124_decompressor::mask_synced, ccsds124_decompressor::received_status_count, ccsds124_decompressor::received_status_index, ccsds124_decompressor::received_status_ring, and ccsds124_decompressor::t.

ccsds124_decompressor_reset()

void ccsds124_decompressor_reset

(

ccsds124_decompressor_t *

decomp

)

Reset decompressor to initial state.

Resets time index to 0 and clears all state while preserving configuration (F, robustness).

Parameters

[out]

decomp

Decompressor to reset

Definition at line 389 of file decompress.c.

References bitvector_copy(), bitvector_zero(), ccsds124_decompressor::count_f_mismatch, ccsds124_decompressor::initial_mask, ccsds124_decompressor::mask, ccsds124_decompressor::mask_inconsistent, ccsds124_decompressor::mask_synced, ccsds124_decompressor::prev_output, ccsds124_decompressor::received_status_count, ccsds124_decompressor::received_status_index, ccsds124_decompressor::received_status_ring, ccsds124_decompressor::t, and ccsds124_decompressor::Xt.

Referenced by ccsds124_decompress(), and ccsds124_decompressor_init().

ccsds124_discover_packet_length()

int ccsds124_discover_packet_length	(	const uint8_t *	data,
		size_t	num_bits,
		uint32_t *	packet_length
	)

Discover packet length (F) from a compressed packet.

Parses the self-delimiting bitstream structure of a compressed packet to discover the packet length F from reference packets (rt=1) that contain COUNT(F). Non-reference packets cannot reveal F.

This is useful when receiving compressed data without out-of-band metadata about the original packet size.

Parameters

[in]	data	Compressed packet bytes
[in]	num_bits	Number of valid bits in data
[out]	packet_length	Discovered F value (0 if not discoverable)

Returns

CCSDS124_OK on success (check packet_length for result), CCSDS124_ERROR_INVALID_ARG for NULL pointers or zero bits

Definition at line 954 of file decompress.c.

References bitreader_init(), bitreader_read_bit(), bitreader_read_bits(), bitreader_remaining(), ccsds124_count_decode(), CCSDS124_ERROR_INVALID_ARG, CCSDS124_OK, CCSDS124_STATUS_TRUNCATED_LENGTH, and skip_rle_sequence_span().