From: Shally Verma <shally.ve...@cavium.com> Signed-off-by:shally.ve...@cavium.com Signed-off-by:mahipal.cha...@cavium.com Cc prasadathreya.naray...@cavium.com --- /** Email created from pull request 102 (1234sv:api-next) ** https://github.com/Linaro/odp/pull/102 ** Patch: https://github.com/Linaro/odp/pull/102.patch ** Base sha: 8390f890d4bd2babb63a24f7b15d2f4763e44050 ** Merge commit sha: 5a3875bda93ff56c76538aa76f8a943651e0919a **/ include/odp/api/spec/comp.h | 427 +++++++++++++++++++++++--------------------- 1 file changed, 226 insertions(+), 201 deletions(-)
diff --git a/include/odp/api/spec/comp.h b/include/odp/api/spec/comp.h index 2956094c..21a3bdb1 100644 --- a/include/odp/api/spec/comp.h +++ b/include/odp/api/spec/comp.h @@ -1,4 +1,4 @@ -/* Copyright (c) 2013, Linaro Limited +/* Copyright (c) 2017, Linaro Limited * All rights reserved. * * SPDX-License-Identifier: BSD-3-Clause @@ -14,24 +14,23 @@ #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 -#include <odp/api/support.h> -#include <odp/api/packet.h> - /** @defgroup odp_compression ODP COMP - * ODP Compression defines API set to compress/decompress along with hash + * ODP Compression is an API set to do compression+hash or decompression+hash * operations on data. Hash is calculated on plaintext. * - * if opcode = ODP_COMP_COMPRESS, then it will Compress and apply hash, - * if opcode = ODP_COMP_DECOMPRESS, then it will Decompress and apply + * if opcode = ODP_COMP_COMPRESS, then it will apply hash and then compress, + * if opcode = ODP_COMP_DECOMPRESS, then it will decompress and then apply * hash. * Independent hash-only operations are not supported. Implementation should * perform hash along with valid compression algo. - * Macros, enums, types and operations to utilize compression. + * Macros, enums, types and operations to utilize compression interface. * @{ */ @@ -60,7 +59,7 @@ typedef enum { * */ typedef enum { - /** Compress */ + /** Compress */ ODP_COMP_OP_COMPRESS, /** Decompress */ ODP_COMP_OP_DECOMPRESS @@ -71,11 +70,13 @@ typedef enum { * */ typedef enum { - /** ODP_COMP_HASH_ALG_NONE*/ + /** ODP_COMP_HASH_ALG_NONE - No hash algorithm selected. */ ODP_COMP_HASH_ALG_NONE, - /** ODP_COMP_HASH_ALG_SHA1*/ + /** ODP_COMP_HASH_ALG_SHA1 - SHA-1 hash algorithm. */ ODP_COMP_HASH_ALG_SHA1, - /** ODP_COMP_HASH_ALG_SHA256*/ + /** ODP_COMP_HASH_ALG_SHA256 - SHA-2 hash algorithm + * 256-bit digest length. + */ ODP_COMP_HASH_ALG_SHA256 } odp_comp_hash_alg_t; @@ -195,10 +196,10 @@ typedef enum { typedef union odp_comp_hash_algos_t { /** hash algorithms */ struct { - /** SHA-1 */ + /** ODP_COMP_HASH_ALG_SHA1 */ uint32_t sha1 : 1; - /** SHA with 256 bits of Message Digest */ + /** ODP_COMP_HASH_ALG_SHA256 */ uint32_t sha256 : 1; } bit; @@ -247,14 +248,10 @@ typedef struct odp_comp_capability_t { uint32_t max_sessions; /** Supported compression algorithms */ - odp_comp_algos_t comp_algs; + odp_comp_algos_t comp_algos; /** Supported hash algorithms. */ - odp_comp_hash_algos_t hash_algs; - - /* sync/async mode of operation support. - * Implementation should support atleast one of the mode. - */ + odp_comp_hash_algos_t hash_algos; /** Support type for synchronous operation mode (ODP_COMP_SYNC). * User should set odp_comp_session_param_t:mode based on @@ -282,7 +279,7 @@ typedef struct odp_comp_hash_alg_capability_t { * Compression algorithm capabilities structure for each algorithm. * */ -typedef struct odp_comp_alg_capability_t { +typedef struct odp_comp_algo_capability_t { /** Enumeration indicating alg support for dictionary load */ odp_support_t support_dict; @@ -322,15 +319,16 @@ typedef struct odp_comp_alg_capability_t { uint32_t max_level; /* Supported hash algorithms */ - odp_comp_hash_algos_t hash_alg; -} odp_comp_alg_capability_t; + odp_comp_hash_algos_t hash_algo; +} odp_comp_algo_capability_t; /** * Comp API dictionary type - * + * Consists of pointer to byte buffer. length of dictionary + * indicated by length parameter. */ typedef struct odp_comp_dict_t { - /** pointer to character array */ + /** pointer to byte array */ uint8_t *buf; /** length of the dictionary. */ uint32_t len; @@ -340,7 +338,10 @@ typedef struct odp_comp_dict_t { * Comp API algorithm specific parameters * */ -typedef struct odp_comp_alg_param_t { +typedef struct odp_comp_algo_param_t { + /** struct for defining deflate algorithm parameters. + * Also initialized by other deflate based algorithms , ex. ZLIB + */ struct comp_alg_def_param { /** compression level where * ODP_COMP_LEVEL_MIN <= level <= ODP_COMP_LEVEL_MAX @@ -349,25 +350,14 @@ typedef struct odp_comp_alg_param_t { /** huffman code to use */ odp_comp_huffman_code_t comp_code; } deflate; + + /** struct for defining zlib algorithm parameters. + */ struct comp_alg_zlib_param { /** deflate algo params */ struct comp_alg_def_param def; } zlib; -} odp_comp_alg_param_t; - -/** - * Comp API data range specifier - * - */ -typedef union odp_comp_data_t { - struct { - /** packet */ - odp_packet_t packet; - - /** packet data range to operate on */ - odp_packet_data_range_t data_range; - } pkt; -} odp_comp_data_t; +} odp_comp_algo_param_t; /** * Comp API session creation parameters @@ -377,13 +367,13 @@ typedef struct odp_comp_session_param_t { /** Compress vs. Decompress operation */ odp_comp_op_t op; - /** Sync vs Async + /** Sync vs Async mode * - * When mode = ODP_COMP_SYNC, odp_comp_compress()/odp_comp_decomp() + * When mode = ODP_COMP_SYNC, odp_comp_xxx() * should be called. * - * When mode = ODP_COMP_ASYNC, odp_comp_compress_enq()/ - * odp_comp_decomp_enq() should be called. + * When mode = ODP_COMP_ASYNC, odp_comp_xxx_enq() + * should be called. * * Use odp_comp_capability() for supported mode. * @@ -394,7 +384,7 @@ typedef struct odp_comp_session_param_t { * * Use odp_comp_capability() for supported algorithms. */ - odp_comp_alg_t comp_alg; + odp_comp_alg_t comp_algo; /** Hash algorithm * @@ -404,10 +394,10 @@ typedef struct odp_comp_session_param_t { * data + hash. * */ - odp_comp_hash_alg_t hash_alg; + odp_comp_hash_alg_t hash_algo; /** parameters specific to compression */ - odp_comp_alg_param_t alg_param; + odp_comp_algo_param_t alg_param; /** Async mode completion event queue * @@ -428,17 +418,21 @@ typedef struct odp_comp_session_param_t { } odp_comp_session_param_t; /** - * Comp API operation parameters. - * Called to process each data unit. + * Comp API per packet operation result * */ -typedef struct odp_comp_op_param_t { +typedef struct odp_comp_packet_result_t { + /** Operation Return Code */ + odp_comp_err_t err; +} odp_comp_packet_result_t; + +/** + * Comp packet API per packet operation parameters + */ +typedef struct odp_comp_packet_op_param_t { /** Session handle from creation */ odp_comp_session_t session; - /** User context */ - void *ctx; - /** Boolean indicating End of data, where * * true : last chunk @@ -446,60 +440,26 @@ typedef struct odp_comp_op_param_t { * false: more to follow * * If set to true, indicates this is the last chunk of - * data. After processing of last chunk of data is complete i.e. - * call returned with any error code except ODP_COMP_ERR_OUT_OF_SPACE, + * data which was being processed in stateful mode. After processing + * of last chunk of data is complete (i.e.call return with any + * error code except ODP_COMP_ERR_OUT_OF_SPACE), * implementation should move algorithm to stateless mode * for next of batch of operation i.e. reset history, - * insert 'End of Block' marker into compressed data stream(if - * supported by algo).See deflate/zlib for interpretation of - * stateless/stateful. + * insert 'End of Block' marker into compressed data stream, if + * supported by algo.(See deflate/zlib for interpretation of + * stateless/stateful). * * For stateless compressions (ex ipcomp), last should be set to 'true' * for every input packet processing call. * * For compression + hash, digest will be available after - * last chunk is processed completely. In case of - * ODP_COMP_ERR_OUT_OF_SPACE, application should keep on calling - * odp_comp_xxx() API with more output buffer unless call returns - * with ODP_COMP_ERR_NONE or other failure code except - * ODP_COMP_ERR_OUT_OF_SPACE. + * last chunk is processed completely. */ odp_bool_t last; - /** Input data */ - odp_comp_data_t input; - - /** placeholder for output data. - * - * For Compression/Decompression+hash session, - * output will store both data and digest(with digest appended at - * end-of-data). User should pass packet of sufficiently large size - * to store digest. - * - */ - odp_comp_data_t output; -} 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.Valid when odp_comp_err_t is - * ODP_COMP_ERR_NONE or ODP_COMP_ERR_OUT_OF_SPACE - * - * Contain data after compression/decompression operation, - * or data + digest for compression/decompression + hash operation. - * - */ - odp_comp_data_t output; -} odp_comp_op_result_t; + /** Valid Data range */ + odp_packet_data_range_t data_range; +} odp_comp_packet_op_param_t; /** * Query comp capabilities @@ -611,123 +571,209 @@ int odp_comp_set_dict(odp_comp_session_t session, odp_comp_dict_t *dict); /** - * Comp compress data in synchronous mode + * Comp packet operation synchronous * - * If session is created in ODP_COMP_SYNC mode, this call wait for operation - * to complete and update result at output + * Performs the SYNC compression/decompression operations on the packets. * - * If session is created in ODP_COMP_ASYNC mode, this call fails and update - * status code ODP_COMP_ERR_NOT_SUPPORTED. + * If session is created in ODP_COMP_SYNC mode, this call wait for operation + * to complete. * - * 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 status code except ODP_COMP_ERR_OUT_OF_SPACE. + * If session is created in ODP_COMP_ASYNC mode, behavior is undefined. * * for compression + hash, call returns with hash appended to the end of * last processed chunk of data. + * * User should compute processed data len = total output len - digest_len, where * digest_len queried through odp_comp_hash_alg_capability(). * - * @param param[in] Operation parameters. - * @param result[out] Result of operation. + * Caller should initialize pkt_out with valid output + * packet handles. All arrays should be of num_pkt size. * - * @retval 0 on success + * In case of partially processed array i.e. when + * number of packets returned < num_pkt, application should call + * odp_comp_result() on 1st failed packet (i.e. n+1th packet where + * n=number of packets returned) to ensure if error code is + * ODP_COMP_ERR_OUT_OF_SPACE. + * + * In case of ODP_COMP_ERR_OUT_OF_SPACE, application should keep on calling + * odp_comp_op() API with more output buffer until call returns + * with num_pkt or with result as ODP_COMP_ERR_NONE or any other + * failure code. + * + * @param pkt_in Packets to be processed + * @param[in,out] pkt_out Packet handle array specifying resulting packets + * @param param Operation parameters array + * @param num_pkt Number of packets to be processed + * + * @return Number of input packets consumed (0 ... num_pkt) * @retval <0 on failure */ -int odp_comp_compress(odp_comp_op_param_t *param, - odp_comp_op_result_t *result); +int odp_comp_compress(const odp_packet_t pkt_in[], + odp_packet_t pkt_out[], + odp_comp_packet_op_param_t param[], + int num_pkt); /** - * Comp compress data in asynchronous mode. + * Comp packet operation synchronous * + * Performs the SYNC decompression operations on the packets. + * + * If session is created in ODP_COMP_SYNC mode, this call wait for operation + * to complete and update result at output + * + * If session is created in ODP_COMP_ASYNC mode, behavior of this call + * is undefined. + * + * For decompression + hash, call returns with hash appended to the end of + * last processed chunk of data.User should compute processed data len = + * total output len - digest_len, where digest_len queried through + * odp_comp_hash_alg_capability(). + * + * Caller should initialize pkt_out with valid output + * packet handles. All arrays should be of num_pkt size. + * In case of partially processed array i.e. when + * number of packets returned < num_pkt, application should call + * odp_comp_result() on 1st failed packet (i.e. n+1th packet where + * n=number of packets returned) to ensure if error code is + * ODP_COMP_ERR_OUT_OF_SPACE. + * + * In case of ODP_COMP_ERR_OUT_OF_SPACE, application should keep on calling + * odp_comp_op() API with more output buffer until call returns + * with num_pkt or with result as ODP_COMP_ERR_NONE or any other + * failure code. + * + * @param pkt_in Packets to be processed + * @param[in,out] pkt_out Packet handle array specifying resulting packets + * @param param Operation parameters array + * @param num_pkt Number of packets to be processed + * + * @return Number of input packets consumed (0 ... num_pkt) + * @retval <0 on failure + */ +int odp_comp_decompress(const odp_packet_t pkt_in[], + odp_packet_t pkt_out[], + odp_comp_packet_op_param_t param[], + int num_pkt); + +/** + * Comp packet operation asynchronous + * + * Performs the ASYNC compression operations on the packets. * If session is created in ODP_COMP_ASYNC mode, event will be queued * to completion queue. Application should monitor ODP_EVENT_PACKET with * subtype ODP_EVENT_PACKET_COMP on queue. * - * If session is created in ODP_COMP_SYNC mode, call fails with status - * code ODP_COMP_ERR_NOT_SUPPORTED. + * If session is created in ODP_COMP_SYNC mode, behavior is undefined. + * + * Caller should initialize pkt_out with valid output + * packet handles.All arrays should be of num_pkt size. Resulting packets + * are returned through events. + * + * In case of partially processed array i.e. when + * number of packets returned < num_pkt, application should call + * odp_comp_result() on 1st failed packet (i.e. n+1th packet where + * n=number of packets returned) to ensure if error code is + * ODP_COMP_ERR_OUT_OF_SPACE. + * + * In case of ODP_COMP_ERR_OUT_OF_SPACE, application should keep on calling + * odp_comp_op() API with more output buffer until call returns + * with num_pkt or with result as ODP_COMP_ERR_NONE or any other + * failure code. * * For compression + hash, call returns with hash appended to the end of * last processed chunk of data. + * * User should compute processed data len = total output len - digest_len, where * digest_len queried through odp_comp_hash_alg_capability(). * - * If operation updates result structure with status - * 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. * Please note it is always recommended that application using async mode, * provide sufficiently large buffer size to avoid ODP_COMP_ERR_OUT_OF_SPACE. * Else it is recommended that application maintain relevant context * with respect to each input processing request to correctly identify * its corresponding enqueued event. * - * @param param[in] Operation parameters. * - * @retval 0 on success + * @param pkt_in Packets to be processed + * @param pkt_out Packet handle array specifying resulting packets + * @param param Operation parameters array + * @param num_pkt Number of packets to be processed + * + * @return Number of input packets consumed (0 ... num_pkt) + * @retval <0 on failure + */ +int odp_comp_compress_enq(const odp_packet_t pkt_in[], + const odp_packet_t pkt_out[], + const odp_crypto_packet_op_param_t param[], + int num_pkt); + +/** + * Comp packet operation + * + * Performs the ASYNC decompression operations on the packet array. + * + * If session is created in ODP_COMP_ASYNC mode, result will be queued + * to completion queue. Application should monitor ODP_EVENT_PACKET + * with subtype ODP_EVENT_PACKET_COMP on queue. + * + * If session is created in ODP_COMP_SYNC mode, behavior is undefined. + * + * for decompression+hash, call returns with hash appended to the end of + * last processed chunk of data. + * + * User should compute processed data len = total output length - digest_len, + * where digest_len queried through odp_comp_hash_alg_capability(). + * + * Caller should initialize pkt_out with valid output + * packet handles.All arrays should be of num_pkt size. Resulting packets + * are returned through events. + * In case of partially processed array i.e. when + * number of packets returned < num_pkt, application should call + * odp_comp_result() on 1st failed packet (i.e. n+1th packet where + * n=number of packets returned) to ensure if error code is + * ODP_COMP_ERR_OUT_OF_SPACE. + * In case of ODP_COMP_ERR_OUT_OF_SPACE, application should keep on calling + * odp_comp_op() API with more output buffer until call returns + * with num_pkt or with result as ODP_COMP_ERR_NONE or any other + * failure code. + * + * Please note it is always recommended that application using async mode, + * provide sufficiently large buffer size to avoid ODP_COMP_ERR_OUT_OF_SPACE. + * Else it is recommended that application maintain required context + * to associate event to its respective input. + * + * @param pkt_in Packets to be processed + * @param pkt_out Packet handle array specifying resulting packets + * @param param Operation parameters array + * @param num_pkt Number of packets to be processed + * + * @return Number of input packets consumed (0 ... num_pkt) * @retval <0 on failure */ -int odp_comp_compress_enq(odp_comp_op_param_t *param); - - /** - * Comp decompress data in synchronous mode - * - * If session is created in ODP_COMP_SYNC mode, this call wait for operation - * to complete and update result at output - * - * If session is created in ODP_COMP_ASYNC mode, this call fails and update - * status code ODP_COMP_ERR_NOT_SUPPORTED. - * - * 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 status code except ODP_COMP_ERR_OUT_OF_SPACE. - * - * for decompression + hash, call returns with hash appended to the end of - * last processed chunk of data.User should compute processed data len = - * total output len - digest_len, where digest_len queried through - * odp_comp_hash_alg_capability(). - * - * @param param[in] Operation parameters. - * @param result[out] Result of operation. - * - * @retval 0 on success - * @retval <0 on failure - */ -int odp_comp_decomp(odp_comp_op_param_t *param, - odp_comp_op_result_t *result); +int odp_comp_decompress_enq(const odp_packet_t pkt_in[], + const odp_packet_t pkt_out[], + const odp_crypto_packet_op_param_t param[], + int num_pkt); /** - * Comp decompress data in asynchronous mode. - * - * If session is created in ODP_COMP_ASYNC mode, result will be queued - * to completion queue. Application should monitor ODP_EVENT_PACKET - * with subtype ODP_EVENT_PACKET_COMP on queue. - * - * If session is created in ODP_COMP_SYNC mode, call fails with status - * code ODP_COMP_ERR_NOT_SUPPORTED. - * - * for decompression+hash, call returns with hash appended to the end of - * last processed chunk of data. - * - * User should compute processed data len = total output length - digest_len, - * where digest_len queried through odp_comp_hash_alg_capability(). - * - * If operation updates result structure with status - * 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. - * - * Please note it is always recommended that application using async mode, - * provide sufficiently large buffer size to avoid ODP_COMP_ERR_OUT_OF_SPACE. - * Else it is recommended that application maintain required context - * to associate event to its respective input. - * - * @param param[in] Operation parameters. - * - * @retval 0 on success - * @retval <0 on failure - */ -int odp_comp_decomp_enq(odp_comp_op_param_t *param); + * Get compression/decompression operation results from an processed packet. + * + * Successful compression/decompression operations produce + * packets which contain operation result metadata. This function copies the + * operation results from an processed packet. Event subtype of this kind + * of packet is ODP_EVENT_PACKET_COMP. Results are undefined if input packet + * has not be processed by compression/decompression call. + * + * @param[out] result Pointer to operation result for output + * @param packet An processed packet (ODP_EVENT_PACKET_COMP) + * + * @retval 0 On success + * @retval <0 On failure + * + * @see odp_comp_compress_enq(), odp_comp_decompress_enq(), + * odp_comp_packet_from_event() + */ +int odp_comp_result(odp_comp_packet_result_t *result, + odp_packet_t packet); /** * Convert processed packet event to packet handle @@ -750,7 +796,7 @@ int odp_comp_decomp_enq(odp_comp_op_param_t *param); * if(subtype == ODP_PACKET_EVENT_COMP) { * pkt = odp_comp_packet_from_event(ev); * odp_comp_op_result_t res; - * odp_comp_result(packet, &res); + * odp_comp_result(&res, packet); * } * } */ @@ -769,27 +815,6 @@ odp_packet_t odp_comp_packet_from_event(odp_event_t event); */ odp_event_t odp_comp_packet_to_event(odp_packet_t pkt); - /** - * Get compression/decompression operation results from an processed packet. - * - * Successful compression/decompression operations produce - * packets which contain operation result metadata. This function copies the - * operation results from an processed packet. Event subtype of this kind - * of packet is ODP_EVENT_PACKET_COMP. Results are undefined if input packet - * has not be processed by compression/decompression call. - * - * @param[out] result Pointer to operation result for output - * @param packet An processed packet (ODP_EVENT_PACKET_COMP) - * - * @retval 0 On success - * @retval <0 On failure - * - * @see odp_comp_compress_enq(), odp_comp_decomp_enq(), - * odp_comp_packet_from_event() - */ -int odp_comp_result(odp_packet_t packet, - odp_comp_op_result_t *result); - /** * Get printable value for an odp_comp_session_t *