This is an automated email from the git hooks/post-receive script. It was generated because a ref change was pushed to the repository containing the project "".
The branch, api-next has been updated via 7c629241f07aa7509d996c0560a20c5b0c7b371d (commit) from ee6fdca6b647d1c92ba6d07400c7d1e23c9e0ce3 (commit)
Those revisions listed above that are new to this repository have not appeared on any other notification email; so we list those revisions in full, below.
- Log ----------------------------------------------------------------- commit 7c629241f07aa7509d996c0560a20c5b0c7b371d Author: Balasubramanian Manoharan bala.manoharan@linaro.org Date: Tue Apr 24 20:09:37 2018 +0530
api: comp: compression specification
ODP Compression specification
Signed-off-by: Balasubramanian Manoharan bala.manoharan@linaro.org Signed-off-by: Shally Verma shally.verma@cavium.com Signed-off-by: Mahipal Challa mahipal.challa@cavium.com Reviewed-by: Petri Savolainen petri.savolainen@linaro.org Reviewed-by: Bogdan Pricope bogdan.pricope@linaro.org Signed-off-by: Maxim Uvarov maxim.uvarov@linaro.org
diff --git a/include/odp/api/abi-default/comp.h b/include/odp/api/abi-default/comp.h new file mode 100644 index 00000000..8a1145af --- /dev/null +++ b/include/odp/api/abi-default/comp.h @@ -0,0 +1,35 @@ +/* Copyright (c) 2018, Linaro Limited + * All rights reserved. + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +#ifndef ODP_ABI_COMP_H_ +#define ODP_ABI_COMP_H_ + +#ifdef __cplusplus +extern "C" { +#endif + +#include <stdint.h> + +/** @internal Dummy type for strong typing */ +typedef struct { char dummy; /**< @internal Dummy */ } _odp_abi_comp_session_t; + +/** @ingroup odp_compression + * @{ + */ + +typedef _odp_abi_comp_session_t *odp_comp_session_t; + +#define ODP_COMP_SESSION_INVALID ((odp_comp_session_t)0) + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/include/odp/api/spec/comp.h b/include/odp/api/spec/comp.h new file mode 100644 index 00000000..a5eb5a23 --- /dev/null +++ b/include/odp/api/spec/comp.h @@ -0,0 +1,613 @@ +/* Copyright (c) 2018, Linaro Limited + * All rights reserved. + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +/** + * @file + * + * ODP Compression + */ + +#ifndef ODP_API_COMP_H_ +#define ODP_API_COMP_H_ + +#include <odp/visibility_begin.h> +#include <odp/api/support.h> +#include <odp/api/packet.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/** @defgroup odp_compression ODP COMP + * Operations for Compression and Decompression API. + * Hash calculation may be combined with de-/compression operations + * + * @{ + */ + +/** + * @def ODP_COMP_SESSION_INVALID + * Invalid session handle + */ + +/** + * @typedef odp_comp_session_t + * Compression/Decompression session handle + */ + +/** + * Compression operation mode + */ +typedef enum { + /** Synchronous Compression operation + * + * Application uses synchronous operation, + * which outputs all results on function return. + * */ + ODP_COMP_OP_MODE_SYNC, + + /** Asynchronous Compression operation + * + * Application uses asynchronous operation, + * which return results via events. + * */ + ODP_COMP_OP_MODE_ASYNC +} odp_comp_op_mode_t; + +/** + * Compression operation type. + */ +typedef enum { + /** Operation type - Compress */ + ODP_COMP_OP_COMPRESS, + + /** Operation type - Decompress */ + ODP_COMP_OP_DECOMPRESS +} odp_comp_op_t; + +/** + * Compression hash algorithms + */ +typedef enum { + /** No hash algorithm selected. */ + ODP_COMP_HASH_ALG_NONE, + + /** SHA-1 hash algorithm. */ + ODP_COMP_HASH_ALG_SHA1, + + /** SHA-2 hash algorithm 256-bit digest length. */ + ODP_COMP_HASH_ALG_SHA256 +} odp_comp_hash_alg_t; + +/** + * Compression algorithms + * + */ +typedef enum { + /** No algorithm specified. Added for testing purpose. */ + ODP_COMP_ALG_NULL, + + /** DEFLATE - RFC1951 */ + ODP_COMP_ALG_DEFLATE, + + /** ZLIB - RFC1950 */ + ODP_COMP_ALG_ZLIB, + + /** LZS */ + ODP_COMP_ALG_LZS +} odp_comp_alg_t; + +/** + * Compression operation status codes + */ +typedef enum { + /** Operation completed successfully*/ + ODP_COMP_STATUS_SUCCESS, + + /** Operation terminated due to insufficient output buffer */ + ODP_COMP_STATUS_OUT_OF_SPACE_TERM, + + /** Operation failure */ + ODP_COMP_STATUS_FAILURE, +} odp_comp_status_t; + +/** + * Hash algorithms in a bit field structure + */ +typedef union odp_comp_hash_algos_t { + /** hash algorithms */ + struct { + /** ODP_COMP_HASH_ALG_NONE */ + uint32_t none : 1, + + /** ODP_COMP_HASH_ALG_SHA1 */ + uint32_t sha1 : 1; + + /** ODP_COMP_HASH_ALG_SHA256 */ + 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_hash_algos_t; + +/** + * Compression 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 comp_algos; + + /** Supported hash algorithms */ + odp_comp_hash_algos_t hash_algos; + + /** Synchronous compression mode support (ODP_COMP_OP_MODE_SYNC) */ + odp_support_t sync; + + /** Aynchronous compression mode support (ODP_COMP_OP_MODE_SSYNC) */ + odp_support_t async; +} odp_comp_capability_t; + +/** + * Hash algorithm capabilities + */ +typedef struct odp_comp_hash_alg_capability_t { + /** Digest length in bytes */ + uint32_t digest_len; +} odp_comp_hash_alg_capability_t; + +/** + * Compression algorithm capabilities + */ +typedef struct odp_comp_alg_capability_t { + + /** Maximum compression level supported by implementation of this + * algorithm. Indicates number of compression levels supported by + * implementation. Valid range from (1 ... max_level) + */ + uint32_t max_level; + + /** Supported hash algorithms */ + odp_comp_hash_algos_t hash_algo; + + /** Compression ratio + * Optimal compression operation ratio for this algorithm. + * This is an estimate of maximum compression operation output for this + * algorithm. It is expressed as a percentage of maximum expected + * output data size with respect to input data size. + * i.e a value of 200% denotes the output data is 2x times the input + * data size. This is an optimal/most case estimate and it is possible + * that the percentage of output data produced might be greater + * than this value. + * + * @see odp__percent_t + */ + odp_percent_t compression_ratio; +} odp_comp_alg_capability_t; + +/** + * Compression Huffman type. Used by DEFLATE algorithm + */ +typedef enum odp_comp_huffman_code { + /** Fixed Huffman code */ + ODP_COMP_HUFFMAN_FIXED, + + /** Dynamic Huffman code */ + ODP_COMP_HUFFMAN_DYNAMIC, + + /** Default huffman code selected by implementation */ + ODP_COMP_HUFFMAN_DEFAULT, +} odp_comp_huffman_code_t; + +/** + * Compression DEFLATEe algorithm parameters. + * Also initialized by other deflate based algorithms , ex. ZLIB + */ +typedef struct odp_comp_deflate_param { + /** + * Compression level + * + * Valid range is integer between (0 ... max_level) + * level supported by the implementation. + * + * where, + * 0 - implemention default + * + * 1 - fastest compression i.e. output produced at + * best possible speed at the expense of compression quality + * + * max_level - High quality compression + * + * @see 'max_level' in odp_comp_alg_capability_t + */ + uint32_t comp_level; + + /** huffman code to use */ + odp_comp_huffman_code_t huffman_code; +} odp_comp_deflate_param_t; + +/** + * Compression algorithm specific parameters + */ +typedef union odp_comp_alg_param_t { + /** deflate parameter */ + odp_comp_deflate_param_t deflate; + + /** Struct for defining zlib algorithm parameters */ + struct { + /** deflate algo params */ + odp_comp_deflate_param_t deflate; + } zlib; +} odp_comp_alg_param_t; + + /** + * Compression session creation parameters + */ +typedef struct odp_comp_session_param_t { + /** Compression operation type Compress vs Decompress */ + odp_comp_op_t op; + + /** Compression operation mode + * + * Operation mode Synchronous vs Asynchronous + * + * @see odp_comp_op(), odp_comp_op_enq() + */ + odp_comp_op_mode_t mode; + + /** Compression algorithm + * + * @see odp_comp_capability() + */ + odp_comp_alg_t comp_algo; + + /** Hash algorithm + * + * @see odp_comp_alg_capability() + */ + odp_comp_hash_alg_t hash_algo; + + /** parameters specific to compression */ + odp_comp_alg_param_t alg_param; + + /** Session packet enqueue ordering + * Boolean to indicate if packet enqueue ordering is required per + * session. Valid only for Asynchronous operation mode + * (ODP_COMP_OP_MODE_ASYNC). Packet order is always maintained for + * synchronous operation mode (ODP_COMP_OP_MODE_SYNC) + * + * true: packet session enqueue order maintained + * + * false: packet session enqueue order is not maintained + * + * @note: By disabling packet order requirement, performance oriented + * application can leverage HW offered parallelism to increase operation + * performance. + */ + odp_bool_t packet_order; + + /** Destination queue for compression operations result. + * Results are enqueued as ODP_EVENT_PACKET with subtype + * ODP_EVENT_PACKET_COMP + */ + odp_queue_t compl_queue; +} odp_comp_session_param_t; + +/** + * Compression packet operation result + */ +typedef struct odp_comp_packet_result_t { + /** Operation status code */ + odp_comp_status_t status; + + /** Input packet handle */ + odp_packet_t pkt_in; + + /** Output packet data range + * Specifies offset and length of data resulting from compression + * operation. When hashing is configured output_data_range.len equals + * length of output data + 'digest+len' + */ + odp_packet_data_range_t output_data_range; +} odp_comp_packet_result_t; + +/** + * Compression per packet operation parameters + */ +typedef struct odp_comp_packet_op_param_t { + /** Session handle */ + odp_comp_session_t session; + + /** Input data range to process. where, + * + * offset - starting offset + * length - length of data for compression operation + * */ + odp_packet_data_range_t in_data_range; + + /** Output packet data range. + * Indicates where processed packet will be written. where, + * + * offset - starting offset + * length - length of buffer available for output + * + * Output packet data is not modified outside of this provided data + * range. If output data length is not sufficient for compression + * operation ODP_COMP_STATUS_OUT_OF_SPACE_TERM error will occur + */ + odp_packet_data_range_t out_data_range; +} odp_comp_packet_op_param_t; + +/** + * Query compression capabilities + * + * Output compression 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 + * + * Output algorithm capabilities. + * + * @param comp Compression algorithm + * @param[out] capa Compression algorithm capability + * + * @retval 0 on success + * @retval <0 on failure + */ +int odp_comp_alg_capability(odp_comp_alg_t comp, + odp_comp_alg_capability_t *capa); + +/** + * Query supported hash algorithm capabilities + * + * Outputs all supported configuration options for the algorithm. + * + * @param hash Hash algorithm + * @param capa Hash algorithm capability + * + * @retval 0 on success + * @retval <0 on failure + */ +int odp_comp_hash_alg_capability(odp_comp_hash_alg_t hash, + odp_comp_hash_alg_capability_t *capa); + +/** + * Initialize compression 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 + * + * @retval Comp session handle + * @retval ODP_COMP_SESSION_INVALID on failure + */ +odp_comp_session_t +odp_comp_session_create(const odp_comp_session_param_t *param); + +/** + * Compression 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); + +/** + * 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. + * + * @param pkt_in Packets to be processed + * @param pkt_out Packet handle array for resulting packets + * @param num_pkt Number of packets to be processed + * @param param Operation parameters + * + * @return Number of input packets consumed (0 ... num_pkt) + * @retval <0 on failure + * + * @note The 'pkt_in','pkt_out'and 'param' arrays should be of same length, + * Results are undefined if otherwise. + + * @note Same packet handle cannot be used as input and output parameter. + * In-place compression operation is not supported + */ +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[]); + +/** + * 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. + * + * @param pkt_in Packets to be processed + * @param pkt_out Packet handle array for resulting packets + * @param num_pkt Number of packets to be processed + * @param param Operation parameters + * + * @return Number of input packets enqueued (0 ... num_pkt) + * @retval <0 on failure + * + * @note The 'pkt_in','pkt_out'and 'param' arrays should be of same length, + * Results are undefined if otherwise. + + * @note Same packet handle cannot be used as input and output parameter. + * In-place compression operation is not supported + + * @see odp_comp_op(), odp_comp_packet_result() + */ +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[]); + +/** + * 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. + * + * @param[out] result pointer to operation result for output + * @param packet compression processed packet (ODP_EVENT_PACKET_COMP) + * + * @retval 0 On success + * @retval <0 On failure + */ +int odp_comp_result(odp_comp_packet_result_t *result, odp_packet_t packet); + + /** + * 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(). + * + * @param event Event handle + * + * @return Valid Packet handle on success, + * @retval ODP_PACKET_INVALID on failure + * + * @see odp_event_subtype(), odp_comp_result() + * + */ +odp_packet_t odp_comp_packet_from_event(odp_event_t event); + + /** + * Convert processed packet handle to event + * + * The packet handle must be an output of a compression operation + * + * @param pkt Packet handle from compression operation + * @return Event handle + */ +odp_event_t odp_comp_packet_to_event(odp_packet_t pkt); + +/** + * 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); + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#include <odp/visibility_end.h> +#endif +
-----------------------------------------------------------------------
Summary of changes: include/odp/api/abi-default/{queue.h => comp.h} | 18 +- include/odp/api/spec/comp.h | 613 ++++++++++++++++++++++++ 2 files changed, 622 insertions(+), 9 deletions(-) copy include/odp/api/abi-default/{queue.h => comp.h} (52%) create mode 100644 include/odp/api/spec/comp.h
hooks/post-receive