API Description

Data compression and decompression.

Hash calculation may be combined with de-/compression operations.

Data Structures
union	odp_comp_hash_algos_t
	Hash algorithms in a bit field structure. More...

union	odp_comp_algos_t
	Compression algorithms in a bit field structure. More...

struct	odp_comp_capability_t
	Compression Interface Capabilities. More...

struct	odp_comp_hash_alg_capability_t
	Hash algorithm capabilities. More...

struct	odp_comp_alg_capability_t
	Compression algorithm capabilities. More...

struct	odp_comp_deflate_param
	Compression DEFLATEe algorithm parameters. More...

union	odp_comp_alg_param_t
	Compression algorithm specific parameters. More...

struct	odp_comp_session_param_t
	Compression session creation parameters. More...

struct	odp_comp_packet_result_t
	Compression packet operation result. More...

struct	odp_comp_packet_op_param_t
	Compression per packet operation parameters. More...

Macros
#define	ODP_COMP_SESSION_INVALID ((odp_comp_session_t)0)
	Invalid session handle.

Typedefs
typedef _odp_abi_comp_session_t *	odp_comp_session_t
	Compression/Decompression session handle.

typedef union odp_comp_hash_algos_t	odp_comp_hash_algos_t
	Hash algorithms in a bit field structure.

typedef union odp_comp_algos_t	odp_comp_algos_t
	Compression algorithms in a bit field structure.

typedef struct odp_comp_capability_t	odp_comp_capability_t
	Compression Interface Capabilities.

typedef struct odp_comp_hash_alg_capability_t	odp_comp_hash_alg_capability_t
	Hash algorithm capabilities.

typedef struct odp_comp_alg_capability_t	odp_comp_alg_capability_t
	Compression algorithm capabilities.

typedef enum odp_comp_huffman_code	odp_comp_huffman_code_t
	Compression Huffman type. More...

typedef struct odp_comp_deflate_param	odp_comp_deflate_param_t
	Compression DEFLATEe algorithm parameters. More...

typedef union odp_comp_alg_param_t	odp_comp_alg_param_t
	Compression algorithm specific parameters.

typedef struct odp_comp_session_param_t	odp_comp_session_param_t
	Compression session creation parameters.

typedef struct odp_comp_packet_result_t	odp_comp_packet_result_t
	Compression packet operation result.

typedef struct odp_comp_packet_op_param_t	odp_comp_packet_op_param_t
	Compression per packet operation parameters.

Enumerations
enum	odp_comp_op_mode_t { ODP_COMP_OP_MODE_SYNC , ODP_COMP_OP_MODE_ASYNC }
	Compression operation mode. More...

enum	odp_comp_op_t { ODP_COMP_OP_COMPRESS , ODP_COMP_OP_DECOMPRESS }
	Compression operation type. More...

enum	odp_comp_hash_alg_t { ODP_COMP_HASH_ALG_NONE , ODP_COMP_HASH_ALG_SHA1 , ODP_COMP_HASH_ALG_SHA256 }
	Compression hash algorithms. More...

enum	odp_comp_alg_t { ODP_COMP_ALG_NULL , ODP_COMP_ALG_DEFLATE , ODP_COMP_ALG_ZLIB , ODP_COMP_ALG_LZS }
	Compression algorithms. More...

enum	odp_comp_status_t { ODP_COMP_STATUS_SUCCESS , ODP_COMP_STATUS_OUT_OF_SPACE_TERM , ODP_COMP_STATUS_FAILURE }
	Compression operation status codes. More...

enum	odp_comp_huffman_code { ODP_COMP_HUFFMAN_FIXED , ODP_COMP_HUFFMAN_DYNAMIC , ODP_COMP_HUFFMAN_DEFAULT }
	Compression Huffman type. More...

Functions
int	odp_comp_capability (odp_comp_capability_t *capa)
	Query compression capabilities. More...

int	odp_comp_alg_capability (odp_comp_alg_t comp, odp_comp_alg_capability_t *capa)
	Query supported compression algorithm capabilities. More...

int	odp_comp_hash_alg_capability (odp_comp_hash_alg_t hash, odp_comp_hash_alg_capability_t *capa)
	Query supported hash algorithm capabilities. More...

void	odp_comp_session_param_init (odp_comp_session_param_t *param)
	Initialize compression session parameters. More...

odp_comp_session_t	odp_comp_session_create (const odp_comp_session_param_t *param)
	Compression session creation. More...

int	odp_comp_session_destroy (odp_comp_session_t session)
	Compression session destroy. More...

int	odp_comp_op (const odp_packet_t pkt_in[], odp_packet_t pkt_out[], int num_pkt, const odp_comp_packet_op_param_t param[])
	Synchronous packet compression operation. More...

int	odp_comp_op_enq (const odp_packet_t pkt_in[], odp_packet_t pkt_out[], int num_pkt, const odp_comp_packet_op_param_t param[])
	Asynchronous packet compression operation. More...

int	odp_comp_result (odp_comp_packet_result_t *result, odp_packet_t packet)
	Get compression operation results from processed packet. More...

odp_packet_t	odp_comp_packet_from_event (odp_event_t event)
	Convert compression processed packet event to packet handle. More...

odp_event_t	odp_comp_packet_to_event (odp_packet_t pkt)
	Convert processed packet handle to event. More...

uint64_t	odp_comp_session_to_u64 (odp_comp_session_t hdl)
	Get printable value for an odp_comp_session_t. More...

Typedef Documentation

◆ odp_comp_huffman_code_t

typedef enum odp_comp_huffman_code odp_comp_huffman_code_t

Compression Huffman type.

Used by DEFLATE algorithm

◆ odp_comp_deflate_param_t

typedef struct odp_comp_deflate_param odp_comp_deflate_param_t

Compression DEFLATEe algorithm parameters.

Also initialized by other deflate based algorithms , ex. ZLIB

Enumeration Type Documentation

◆ odp_comp_op_mode_t

enum odp_comp_op_mode_t

Compression operation mode.

Enumerator

ODP_COMP_OP_MODE_SYNC

Synchronous Compression operation.

Application uses synchronous operation, which outputs all results on function return.

ODP_COMP_OP_MODE_ASYNC

Asynchronous Compression operation.

Application uses asynchronous operation, which return results via events.

Definition at line 45 of file api/spec/comp.h.

◆ odp_comp_op_t

enum odp_comp_op_t

Compression operation type.

Enumerator
ODP_COMP_OP_COMPRESS	Operation type - Compress.
ODP_COMP_OP_DECOMPRESS	Operation type - Decompress.

Definition at line 64 of file api/spec/comp.h.

◆ odp_comp_hash_alg_t

enum odp_comp_hash_alg_t

Compression hash algorithms.

Enumerator
ODP_COMP_HASH_ALG_NONE	No hash algorithm selected.
ODP_COMP_HASH_ALG_SHA1	SHA-1 hash algorithm.
ODP_COMP_HASH_ALG_SHA256	SHA-2 hash algorithm 256-bit digest length.

Definition at line 75 of file api/spec/comp.h.

◆ odp_comp_alg_t

enum odp_comp_alg_t

Compression algorithms.

Enumerator
ODP_COMP_ALG_NULL	No algorithm specified. Added for testing purpose.
ODP_COMP_ALG_DEFLATE	DEFLATE - RFC1951.
ODP_COMP_ALG_ZLIB	ZLIB - RFC1950.
ODP_COMP_ALG_LZS	LZS.

Definition at line 90 of file api/spec/comp.h.

◆ odp_comp_status_t

enum odp_comp_status_t

Compression operation status codes.

Enumerator
ODP_COMP_STATUS_SUCCESS	Operation completed successfully.
ODP_COMP_STATUS_OUT_OF_SPACE_TERM	Operation terminated due to insufficient output buffer.
ODP_COMP_STATUS_FAILURE	Operation failure.

Definition at line 107 of file api/spec/comp.h.

◆ odp_comp_huffman_code

enum odp_comp_huffman_code

Compression Huffman type.

Used by DEFLATE algorithm

Enumerator
ODP_COMP_HUFFMAN_FIXED	Fixed Huffman code.
ODP_COMP_HUFFMAN_DYNAMIC	Dynamic Huffman code.
ODP_COMP_HUFFMAN_DEFAULT	Default huffman code selected by implementation.

Definition at line 228 of file api/spec/comp.h.

Function Documentation

◆ odp_comp_capability()

int odp_comp_capability ( odp_comp_capability_t * capa )

Query compression capabilities.

Output compression capabilities on success.

Parameters

[out] capa Pointer to capability structure for output

Return values

0	on success
<0	on failure

Examples: odp_sysinfo.c.

◆ odp_comp_alg_capability()

int odp_comp_alg_capability	(	odp_comp_alg_t	comp,
		odp_comp_alg_capability_t *	capa
	)

Query supported compression algorithm capabilities.

Output algorithm capabilities.

Parameters

	comp	Compression algorithm
[out]	capa	Compression algorithm capability

Return values

0	on success
<0	on failure

◆ odp_comp_hash_alg_capability()

int odp_comp_hash_alg_capability	(	odp_comp_hash_alg_t	hash,
		odp_comp_hash_alg_capability_t *	capa
	)

Query supported hash algorithm capabilities.

Outputs all supported configuration options for the algorithm.

Parameters

hash	Hash algorithm
capa	Hash algorithm capability

Return values

0	on success
<0	on failure

◆ odp_comp_session_param_init()

void odp_comp_session_param_init ( odp_comp_session_param_t * param )

Initialize compression session parameters.

Initialize an odp_comp_session_param_t to its default values for all fields.

Parameters

param Pointer to odp_comp_session_param_t to be initialized

◆ odp_comp_session_create()

odp_comp_session_t odp_comp_session_create ( const odp_comp_session_param_t * param )

Compression session creation.

Create a comp session according to the session parameters. Use odp_comp_session_param_init() to initialize parameters into their default values.

Parameters

param Session parameters

Return values

Comp	session handle
ODP_COMP_SESSION_INVALID	on failure

◆ odp_comp_session_destroy()

int odp_comp_session_destroy ( odp_comp_session_t session )

Compression session destroy.

Destroy an unused session. Result is undefined if session is being used (i.e. asynchronous operation is in progress).

Parameters

session Session handle

Return values

0	on success
<0	on failure

◆ odp_comp_op()

int odp_comp_op	(	const odp_packet_t	pkt_in[],
		odp_packet_t	pkt_out[],
		int	num_pkt,
		const odp_comp_packet_op_param_t	param[]
	)

Synchronous packet compression operation.

This operation does packet compression in synchronous mode. A successful operation returns the number of successfully processed input packets and updates the results in the corresponding output packets. Outputted packets contain compression results metadata (odp_comp_packet_result_t), which should be checked for operation status. Length of outputted data can be got from output_data_range.len.

When hashing is configured along with compression operation the result is appended at the end of the output data, output_data_range.len equals length of output data + 'digest_len'. Processed data length can be computed by subtracting 'digest_len' from output_data_range.len where 'digest_len' can be queried from odp_comp_hash_alg_capability(). Hash is always performed on plain text. Hash validation in decompression is performed by the application. For every input packet entry in 'pkt_in' array, application should pass corresponding valid output packet handle. If any error occurs during processing of packets, the API returns with number of entries successfully processed. Output packet metadatas like length or data pointer will not be updated.

Parameters

pkt_in	Packets to be processed
pkt_out	Packet handle array for resulting packets
num_pkt	Number of packets to be processed
param	Operation parameters

Returns: Number of input packets consumed (0 ... num_pkt)

Return values

<0	on failure

Note: The 'pkt_in','pkt_out'and 'param' arrays should be of same length, Results are undefined if otherwise.; Same packet handle cannot be used as input and output parameter. In-place compression operation is not supported

◆ odp_comp_op_enq()

int odp_comp_op_enq	(	const odp_packet_t	pkt_in[],
		odp_packet_t	pkt_out[],
		int	num_pkt,
		const odp_comp_packet_op_param_t	param[]
	)

Asynchronous packet compression operation.

This operation does packet compression in asynchronous mode. It processes packets otherwise identical to odp_comp_op(), but the resulting packets are enqueued to 'compl_queue' configured during session (odp_comp_session_t) creation. For every input packet entry in in_pkt array, user should pass corresponding valid output packet handle. On return, API returns with number of entries successfully submitted for operation.

When hashing is configured along with compression operation the result is appended at the end of the output data, output_data_range.len equals length of output data + 'digest_len'. Processed data length can be computed by subtracting 'digest_len' from output_data_range.len where 'digest_len' can be queried from odp_comp_hash_alg_capability(). Hash is always performed on plain text. Hash validation in decompression is performed by the application.

In case of partially accepted array i.e. when number of packets returned < num_pkt, application may attempt to resubmit subsequent entries via calling any of the operation API.

All the packets successfully enqueued will be submitted to 'compl_queue' after compression operation, Application should check 'status' of the operation in odp_comp_packet_result_t. Output packet metadatas like length or data pointer will not be updated.

Please note it is always recommended that application using async mode, provide sufficiently large buffer size to avoid ODP_COMP_STATUS_OUT_OF_SPACE_TERM.

Parameters

pkt_in	Packets to be processed
pkt_out	Packet handle array for resulting packets
num_pkt	Number of packets to be processed
param	Operation parameters

Returns: Number of input packets enqueued (0 ... num_pkt)

Return values

<0	on failure

Note: The 'pkt_in','pkt_out'and 'param' arrays should be of same length, Results are undefined if otherwise.; Same packet handle cannot be used as input and output parameter. In-place compression operation is not supported

See also: odp_comp_op(), odp_comp_packet_result()

◆ odp_comp_result()

int odp_comp_result	(	odp_comp_packet_result_t *	result,
		odp_packet_t	packet
	)

Get compression operation results from processed packet.

Successful compression operations of all modes (ODP_COMP_OP_MODE_SYNC and ODP_COMP_OP_MODE_ASYNC) produce packets which contain compression result metadata. This function copies operation results from compression processed packet. Event subtype of this packet is ODP_EVENT_PACKET_COMP. Results are undefined if non-compression processed packet is passed as input.

Parameters

[out]	result	pointer to operation result for output
	packet	compression processed packet (ODP_EVENT_PACKET_COMP)

Return values

0	On success
<0	On failure

◆ odp_comp_packet_from_event()

odp_packet_t odp_comp_packet_from_event ( odp_event_t event )

Convert compression processed packet event to packet handle.

Get packet handle corresponding to processed packet event. Event subtype must be ODP_EVENT_PACKET_COMP. Compression operation results can be examined with odp_comp_result().

Parameters

event Event handle

Returns: Valid Packet handle on success,

Return values

ODP_PACKET_INVALID on failure

See also: odp_event_subtype(), odp_comp_result()

◆ odp_comp_packet_to_event()

odp_event_t odp_comp_packet_to_event ( odp_packet_t pkt )

Convert processed packet handle to event.

The packet handle must be an output of a compression operation

Parameters

pkt	Packet handle from compression operation

Returns: Event handle

◆ odp_comp_session_to_u64()

uint64_t odp_comp_session_to_u64 ( odp_comp_session_t hdl )

Get printable value for an odp_comp_session_t.

Parameters

hdl	odp_comp_session_t handle to be printed

Returns: uint64_t value that can be used to print/display this handle

Note: This routine is intended to be used for diagnostic purposes to enable applications to generate a printable value that represents an odp_comp_session_t handle.

API Description

Data Structures

Macros

Typedefs

Enumerations

Functions

Typedef Documentation

◆ odp_comp_huffman_code_t

◆ odp_comp_deflate_param_t

Enumeration Type Documentation

◆ odp_comp_op_mode_t

◆ odp_comp_op_t

◆ odp_comp_hash_alg_t

◆ odp_comp_alg_t

◆ odp_comp_status_t

◆ odp_comp_huffman_code

Function Documentation

◆ odp_comp_capability()

◆ odp_comp_alg_capability()

◆ odp_comp_hash_alg_capability()

◆ odp_comp_session_param_init()

◆ odp_comp_session_create()

◆ odp_comp_session_destroy()

◆ odp_comp_op()

◆ odp_comp_op_enq()

◆ odp_comp_result()

◆ odp_comp_packet_from_event()

◆ odp_comp_packet_to_event()

◆ odp_comp_session_to_u64()