An API set to add compression/decompression support in ODP
interface.
Signed-off-by: Shally Verma <sve...@cavium.com>
Signed-off-by: Mahipal Challa <mcha...@cavium.com>
---
include/odp/api/spec/comp.h | 748 ++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 748 insertions(+)
diff --git a/include/odp/api/spec/comp.h b/include/odp/api/spec/comp.h
new file mode 100644
index 0000000..65feacf
--- /dev/null
+++ b/include/odp/api/spec/comp.h
@@ -0,0 +1,748 @@
+/*
+ */
+
+/**
+ * @file
+ *
+ * ODP Compression
+ */
+
+#ifndef ODP_API_COMP_H_
+#define ODP_API_COMP_H_
+#include <odp/visibility_begin.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** @defgroup odp_compression ODP COMP
+ * ODP Compression defines interface to compress/decompress and authenticate
+ * data.
+ *
+ * Compression here implicilty refer to both compression and decompression.
+ * Example, compression algo 'deflate' mean both 'deflate' and 'inflate'.
+ *
+ * if opcode = ODP_COMP_COMPRESS, then it will Compress,
+ * if opcode = ODP_COMP_DECOMPRESS, then it will Decompress.
+ *
+ * Current version of Interface allow Compression ONLY,Authentication ONLY or
+ * both Compression + Auth ONLY sessions.
+ *
+ * Macros, enums, types and operations to utilise compression.
+ * @{
+ */
+
+/**
+ * @def ODP_COMP_SESSION_INVALID
+ * Invalid session handle
+ */
+
+/**
+ * @typedef odp_comp_session_t (platform dependent)
+ * Comp API opaque session handle
+ */
+
+/**
+ * @typedef odp_comp_compl_t
+* Compression API completion event (platform dependent)
+*/
+
+/**
+ * Compression API operation mode
+ */
+typedef enum {
+ /** Synchronous, return results immediately */
+ ODP_COMP_SYNC,
+ /** Asynchronous, return results via queue event */
+ ODP_COMP_ASYNC,
+} odp_comp_op_mode_t;
+
+/**
+ * Comp API operation type.
+ * Ignored for Authentication ONLY.
+ *
+ */
+typedef enum {
+ /** Compress and/or Compute digest */
+ ODP_COMP_OP_COMPRESS,
+ /** Decompress and/or Compute digest */
+ ODP_COMP_OP_DECOMPRESS,
+} odp_comp_op_t;
+
+/**
+ * Comp API authentication algorithm
+ *
+ */
+typedef enum {
+ /** No authentication algorithm specified */
+ ODP_COMP_AUTH_ALG_NULL,
+ /** ODP_COMP_AUTH_ALG_SHA1*/
+ ODP_COMP_AUTH_ALG_SHA1,
+ /** ODP_COMP_AUTH_ALG_SHA256*/
+ ODP_COMP_AUTH_ALG_SHA256
+} odp_comp_auth_alg_t;
+
+/**
+ * Comp API compression algorithm
+ *
+ */
+typedef enum {
+ /** No algorithm specified.
+ * Means no compression, no output provided.
+ */
+ ODP_COMP_ALG_NULL,
+ /** DEFLATE -
+ * implicit Inflate in case of decode operation.
+ */
+ ODP_COMP_ALG_DEFLATE,
+ /** ZLIB-RFC1950 */
+ ODP_COMP_ALG_ZLIB,
+ /** LZS*/
+ ODP_COMP_ALG_LZS,
+} odp_comp_alg_t;
+
+/**
+ * Comp API session creation return code
+ *
+ */
+typedef enum {
+ /** Session created */
+ ODP_COMP_SES_CREATE_ERR_NONE,
+ /** Creation failed, no resources */
+ ODP_COMP_SES_CREATE_ERR_ENOMEM,
+ /** Creation failed, bad compression params */
+ ODP_COMP_SES_CREATE_ERR_INV_COMP,
+ /** Creation failed, bad auth params */
+ ODP_COMP_SES_CREATE_ERR_INV_AUTH,
+ /** Creation failed,requested configuration not supported*/
+ ODP_COMP_SES_CREATE_ERR_NOT_SUPPORTED
+} odp_comp_ses_create_err_t;
+
+/**
+ * Comp API operation return codes
+ *
+ */
+typedef enum {
+ /** Operation completed successfully*/
+ ODP_COMP_ERR_NONE,
+ /** Invalid user data pointers*/
+ ODP_COMP_ERR_DATA_PTR,
+ /** Invalid input data size*/
+ ODP_COMP_ERR_DATA_SIZE,
+ /** Compression and/or Auth Algo failure*/
+ ODP_COMP_ERR_ALGO_FAIL,
+ /** Error detected during DMA of data*/
+ ODP_COMP_ERR_DMA,
+ /** Operation paused due to insufficient output buffer
+ *
+ * This is not an error condition. On seeing this error, caller
+ * should call odp_comp_operation() again with valid output buffer
+ * with no-more input or altercation to other input
+ * operation parameters.
+ *
+ * for applications, considering this an error condition should destroy
+ * and re-create session to start afresh.
+ *
+ * Implementation should maintain context in this condition.
+ */
+ ODP_COMP_ERR_OUT_OF_SPACE,
+ /** Error if operation has been requested in an invalid state */
+ ODP_COMP_ERR_INV_STATE
+} odp_comp_err_t;
+
+/**
+* Comp API enumeration for preferred compression level/speed.
+*
+* trade-off between speed and compression ratio.
+*
+* Please note this enumeration is only a peferential selection
+* but may not guarantee operation to committed level depending
+* on implementation support. Ex. SPEED_FASTEST and SPEED_FAST may
+* give same result on some platforms.
+*
+*/
+typedef enum {
+ /* Use implementaion default between ratio and speed */
+ ODP_COMP_SPEED_DEFAULT = 0,
+ /** fastest speed, lowest compression */
+ ODP_COMP_SPEED_FASTEST,
+ /** fast speed, lower compression */
+ ODP_COMP_SPEED_FAST,
+ /** medium speed, medium compression */
+ ODP_COMP_SPEED_MED,
+ /** slowest speed, maximum compression */
+ ODP_COMP_SPEED_SLOWEST,
+
+} odp_comp_speed_t;
+
+/**
+ * Comp API enumeration for encoding type
+ *
+ */
+typedef enum {
+ /** use implementation default to choose between compression codes */
+ ODP_COMP_CODE_DEFAULT = 0,
+ /** use fixed huffman codes */
+ ODP_COMP_CODE_FIX_HUFFMAN,
+ /** use dynamic huffman coding */
+ ODP_COMP_CODE_DYN_HUFFMAN,
+} odp_comp_code_t;
+
+/**
+ * Authentication algorithms in a bit field structure
+ *
+ */
+typedef union odp_comp_auth_algos_t {
+ /** Authentication algorithms*/
+ struct {
+ /** ODP_AUTH_ALG_NULL*/
+ uint32_t null : 1;
+
+ /** SHA-1*/
+ uint32_t sha1 : 1;
+
+ /** SHA-2 with 256 bits of Message Digest*/
+ uint32_t sha256 : 1;
+
+ } bit;
+
+ /** All bits of the bit field structure
+ *
+ * This field can be used to set/clear all flags, or bitwise
+ * operations over the entire structure.
+ */
+ uint32_t all_bits;
+} odp_comp_auth_algos_t;
+
+/**
+ * Comp algorithms in a bit field structure
+ *
+ */
+typedef union odp_comp_algos_t {
+ /** Compression algorithms */
+ struct {
+ /** ODP_COMP_ALG_NULL */
+ uint32_t null : 1;
+
+ /** ODP_COMP_ALG_DEFLATE */
+ uint32_t deflate : 1;
+
+ /** ODP_COMP_ALG_ZLIB */
+ uint32_t zlib : 1;
+
+ /** ODP_COMP_ALG_LZS */
+ uint32_t lzs :1;
+ } bit;
+
+ /** All bits of the bit field structure
+ *
+ * This field can be used to set/clear all flags, or bitwise
+ * operations over the entire structure. */
+ uint32_t all_bits;
+} odp_comp_algos_t;
+
+/**
+ * Compression Interface Capabilities
+ *
+ */
+typedef struct odp_comp_capability_t {
+ /** Maximum number of sessions*/
+ uint32_t max_sessions;
+
+ /** Supported compression algorithms*/
+ odp_comp_algos_t comps;
+
+ /** Supported authentication algorithms*/
+ odp_comp_auth_algos_t auths;
+
+ /** Support level for synchrnous operation mode (ODP_COMP_SYNC)
+ * User should set odp_comp_session_param_t:mode based on
+ * support level as indicated by this param.
+ * true - mode supported,
+ * false - mode not supported
+ */
+ odp_bool_t sync;
+
+ /** Support level for asynchrnous operation mode (ODP_COMP_ASYNC)
+ * User should set odp_comp_session_param_t:mode param based on
+ * support level as indicated by this param.
+ * true - mode supported,
+ * false - mode not supported
+ *
+ */
+ odp_bool_t async;
+} odp_comp_capability_t;
+
+/**
+ * Authentication algorithm capabilities
+ *
+ */
+typedef struct odp_comp_auth_alg_capability_t {
+ /** key size in bytes */
+ uint32_t key_size;
+
+ /** Digest length in bytes */
+ uint32_t digest_len;
+
+ /** Optional NULL-terminated string description
+ * message (platform-dependent).
+ */
+ void *description;
+
+ /** Optional Null-terminated string
+ * identifier of the algo (platform-dependent)
+ */
+ void *name;
+} odp_comp_auth_alg_capability_t;
+
+/**
+ * Compression algorithm capabilities
+ * structure for each algorithm.
+ *
+ */
+typedef struct odp_comp_alg_capability_t {
+ /** Boolean indicating alg support dictionary load
+ *
+ * true: yes
+ * false : no
+ *
+ */
+ odp_bool_t support_dict;
+
+ /** Optional Maximum length of dictionary supported
+ * by implementation of the algorithm.
+ *
+ * Invalid if support_dict == false.
+ *
+ * Implementation not supporting this may still allow a dictionary
+ * load during odp_comp_operation() where Implementation may
+ * use either of user input or maximum allowed, whichever is less.
+ * In such case, implementation keep responsibility to update user
+ * used dictionary length.
+ *
+ */
+ uint32_t dict_len;
+
+ /** NULL-terminated Optional identifier of the algo (platform-dependent)
+ */
+ void *name;
+
+ /** NULL-terminated optional description message (platform-dependent) */
+ void *description;
+} odp_comp_alg_capability_t;
+
+/**
+ * Comp API data range specifier
+ *
+ */
+typedef struct odp_comp_data_range_t {
+ /** Offset from beginning of input */
+ uint32_t offset;
+
+ /** Length of data to operate on */
+ uint32_t length;
+} odp_comp_data_range_t;
+
+/**
+ * Comp API key structure
+ *
+ */
+typedef struct odp_comp_auth_key_t {
+ /** Key */
+ uint8_t *key;
+
+ /** Key length in bytes */
+ uint32_t length;
+} odp_comp_auth_key_t;
+
+ /**
+ * Comp API session creation parameters
+ *
+ */
+typedef struct odp_comp_session_param_t {
+ /** Compress vs. Decompress operation */
+ odp_comp_op_t op;
+
+ /** Sync vs Async
+ *
+ * When mode = ODP_COMP_SYNC, odp_comp_operation() behaves
+ * synchronously. Operation results will be available as the call
+ * returns.
+ *
+ * When mode = ODP_COMP_ASYNC, odp_comp_operation() behaves
+ * asynchronously. Operation results will be notified via
+ * ODP_COMP_COMPL_EVENT enqueued into completion queue.
+ *
+ * Before passing, User should ensure given
+ * mode is supported by implementation via call to
+ * odp_comp_capability_query().
+ *
+ * Set mode to ODP_COMP_ASYNC, if
+ * odp_comp_capability_t:async is set to true
+ *
+ *
+ * Set mode to ODP_COMP_SYNC, if
+ * odp_comp_capability_t:sync is set to true
+ *
+ */
+ odp_comp_op_mode_t mode;
+
+ /** Compression algorithm
+ *
+ * Use odp_comp_capability() for supported algorithms.
+ */
+ odp_comp_alg_t comp_alg;
+
+ /** Compression preferred encoding mode
+ *
+ */
+ odp_comp_code_t comp_code;
+
+ /** Compression preferred speed
+ *
+ */
+ odp_comp_speed_t comp_speed;
+
+ /** Authentication algorithm.
+ *
+ * if enabled along with non-null compression algo, follows a fixed
+ * ordering. it will be applied on plaintext i.e.
+ * before data is compressed for compression session, and
+ * after it is decompressed for decompression session.
+ *
+ * This may later be enhanced to allow re-ordering subject to
+ * explicitly defined use-case.
+ */
+ odp_comp_auth_alg_t auth_alg;
+
+ /** auth parameters during session creation*/
+ odp_comp_auth_key_t auth_key;
+
+ /** Async mode completion event queue
+ *
+ * When mode = ODP_COMP_ASYNC, User should wait on ODP_COMP_COMPL_EVENT
+ * on this queue.
+ *
+ * By default, implementation enques completion events in-order-of
+ * request submission and thus queue is considered ordered.
+ *
+ * Please note, behavior could be changed or enhanced
+ * to queue event in-order-of their completion to enable
+ * performance-oriented application to leverage hw offered parallelism.
+ * However, This will be subject to application requirement and more
+ * explicit defined use-case.
+ *
+ */
+ odp_queue_t compl_queue;
+
+ /** Pool used by user for input/output data
+ *
+ * used by implementation to have user pool information.
+ * Helps to map input/output data pointer to appropriate type
+ * and other pool related operations.
+ *
+ */
+ odp_pool_t pool;
+} odp_comp_session_param_t;
+
+/**
+ * Comp API operation parameters.
+ * Called to process each data unit.
+ *
+ */
+typedef struct odp_comp_op_param_t {
+ /** Session handle from creation */
+ odp_comp_session_t session;
+
+ /** User context */
+ void *ctx;
+
+ /** Boolean indicating End of data
+ * for stateless compressions (ex ipcomp), it should always be 'true'
+ *
+ * true : last chunk
+ * false: more to follow
+ *
+ * for compression+authentication, digest will be available after
+ * last chunk is processed completely.
+ */
+ odp_bool_t last;
+
+ /** Input packet*/
+ odp_packet_t in_data;
+
+ /** input data range w.r.t in_data*/
+ odp_comp_data_range_t in_data_range;
+
+ /** Output packet.
+ * Stores processed output.
+ *
+ * For Compression+Authentication session,
+ * output buffer will store both data and digest(with digest appended at
+ * end-of-data). User should pass packet of sufficiently large size
+ * to store digest.
+ *
+ * Auto-allocation of output buffer( i.e. when out_data set to
+ * ODP_PACKET_INVALID) and/or in-place operation support
+ * to be considered later based on explicit defined use-case.
+ *
+ */
+ odp_packet_t out_data;
+
+ /** output data range w.r.t out_data, where
+ *
+ * At input, length specifies length of available output buffer, and
+ * offset marks beginning of output buffer.
+ *
+ * At output, length is updated to length of data written in output, and
+ * offset marks start of the data.
+ *
+ * For Compression+Authentication session, Both data and digest are
+ * written to same output buffer (with digest written at the end of
+ * data), so data length = out_data_range.len-digest_size.
+ *
+ */
+ odp_comp_data_range_t out_data_range;
+
+ /** dictionary - Optional Pointer to dictionary as passed by user.
+ * User should pass dictionary when interface is in idle state i.e.
+ * no operation is in progress.
+ */
+ uint8_t *dict;
+
+ /** Length of dictionary */
+ uint32_t dict_len;
+
+} odp_comp_op_param_t;
+
+/**
+ * Comp API per operation result
+ *
+ */
+typedef struct odp_comp_op_result_t {
+ /** User context from request */
+ void *ctx;
+
+ /** Operation Return Code */
+ odp_comp_err_t err;
+
+ /** pointer to output buffer. Valid when odp_comp_err_t is
+ * ODP_COMP_ERR_NONE
+ *
+ * Contains digest for authentication ONLY operations,
+ * processed output for compression/decompression operations, and
+ * both data and digest for Compression+Authentication Operations.
+ *
+ */
+ odp_packet_t out_data;
+
+ /** length of data written to output packet.
+ * include both data+digest_len, for compression+authentication
+ * session
+ */
+ odp_comp_data_range_t data_range;
+} odp_comp_op_result_t;
+
+/**
+ * Query comp capabilities
+ *
+ * Outputs comp capabilities on success.
+ *
+ * @param[out] capa Pointer to capability structure for output
+ *
+ * @retval 0 on success
+ * @retval <0 on failure
+ */
+int odp_comp_capability(odp_comp_capability_t *capa);
+
+/**
+ * Query supported compression algorithm capabilities
+ *
+ * Outputs all supported configuration options for the algorithm.
+ *
+ * @param comp Compression algorithm
+ * @param[out] capa Array of capability structures for output
+ * @param num Maximum number of capability structures to output
+ *
+ * @return Number of capability structures for the algorithm. If this is larger
+ * than 'num', only 'num' first structures were output and application
+ * may call the function again with a larger value of 'num'.
+ * @retval <0 on failure
+ */
+int odp_comp_alg_capability(odp_comp_alg_t comp,
+ odp_comp_alg_capability_t capa[], int num);
+
+ /**
+ * Initialize comp session parameters
+ *
+ * Initialize an odp_comp_session_param_t to its default values for
+ * all fields.
+ *
+ * @param param Pointer to odp_comp_session_param_t to be initialized
+ */
+void odp_comp_session_param_init(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.
+ *
+ * @param param Session parameters
+ * @param session Created session else ODP_COMP_SESSION_INVALID
+ * @param status Failure code if unsuccessful
+ *
+ * @retval 0 on success
+ * @retval <0 on failure
+ */
+int odp_comp_session_create(odp_comp_session_param_t *param,
+ odp_comp_session_t *session,
+ odp_comp_ses_create_err_t *status);
+
+ /**
+ * Comp session destroy
+ *
+ * Destroy an unused session. Result is undefined if session is being used
+ * (i.e. asynchronous operation is in progress).
+ *
+ * @param session Session handle
+ *
+ * @retval 0 on success
+ * @retval <0 on failure
+ */
+int odp_comp_session_destroy(odp_comp_session_t session);
+
+ /**
+ * Compression operation
+ *
+ * Each data operation call will route data
+ * through each components set up in engine. For example if
+ * user created Compression+Authentication(example, zlib & sha1) session, then
+ * data will be passed to both compression and authentication
+ * block.
+ *
+ * If session is created in synchronous mode, results are immediately
+ * available in odp_comp_op_result_t after call returns.
+ *
+ * If session is created in async mode, result will be delivered through
+ * completion queue. application should monitor ODP_COMP_COMPL_EVENT on
+ * queue.
+ *
+ * If operation returns ODP_COMP_ERR_OUT_OF_SPACE, then application should call
+ * API again with valid output buffer (and no-more input) until call completes
+ * with any other error code.
+ *
+ * @param param[in] Operation parameters.
+ * @param result[out] Results of operation. Mandatory for sync mode,
+ * ignored for async mode
+ *
+ * @retval 0 on success
+ * @retval <0 on failure
+ */
+int odp_comp_operation(odp_comp_op_param_t *param,
+ odp_comp_op_result_t *result);
+
+ /**
+ * Return Compression completion handle that is associated with event. Valid
+ * for an async mode.
+ *
+ * @param ev ODP_EVENT_COMP_COMPL Event Handle
+ *
+ * @return Compression Completion Handle
+ *
+ */
+odp_comp_compl_t odp_comp_compl_from_event(odp_event_t ev);
+
+ /**
+ * Query result from completion handle. Valid for async mode.
+ *
+ * @param completion_event Event containing operation results
+ * @param result[out] Pointer to result structure
+ *
+ * Example usecase by user
+ *
+ * odp_event_t ev;
+ *
+ * odp_comp_op_result_t result;
+ *
+ * odp_comp_compl_t compl;
+ *
+ * odp_queue_t ev_queue;
+ *
+ * odp_queue_param_t qparam;
+ *
+ * qparam.type = ODP_QUEUE_TYPE_PLAIN;
+ *
+ * ev_queue = odp_queue_create("comp-out", &qparam);
+ *
+ * //initialise and create session..
+ *
+ * //initialize op_params
+ *
+ * odp_comp_operation(&op_param,NULL);
+ *
+ * ev = odp_queue_deq(ev_queue);
+ *
+ * compl=odp_comp_compl_from_event(ev);
+ *
+ * odp_comp_compl_result(compl,&result);
+ *
+ * odp_comp_compl_free(compl);
+ *
+ */
+void odp_comp_compl_result(odp_comp_compl_t event,
+ odp_comp_op_result_t *result);
+
+ /**
+ * Convert comp completion handle to event handle. Valid for async mode
+ *
+ * @param completion_event Completion event to convert to generic event
+ *
+ * @return Event handle
+ */
+odp_event_t odp_comp_compl_to_event(odp_comp_compl_t completion_event);
+
+ /**
+ * Release comp completion event. valid for async mode
+ *
+ * @param completion_event Completion event we are done accessing
+ */
+void odp_comp_compl_free(odp_comp_compl_t completion_event);
+
+/**
+ * Get printable value for an odp_comp_session_t
+ *
+ * @param hdl odp_comp_session_t handle to be printed
+ * @return 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.
+ */
+uint64_t odp_comp_session_to_u64(odp_comp_session_t hdl);
+
+/**
+ * Get printable value for an odp_comp_compl_t
+ *
+ * @param hdl odp_comp_compl_t handle to be printed
+ * @return 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_compl_t handle.
+ */
+uint64_t odp_comp_compl_to_u64(odp_comp_compl_t hdl);
+
+/**
+ * @}
+ */
+
+#ifdef __cplusplus
+}
+#endif
+
+#include <odp/visibility_end.h>
+#endif
--
1.9.1
