Moreover, if both modes need to be added it is better to follow IPSEC APIs approach instead of crypto APIs, where SYNC and ASYNC APIs are different and user explicitly control mode of operation based on capabilities.
Regards Nikhil -----Original Message----- From: lng-odp [mailto:[email protected]] On Behalf Of Bala Manoharan Sent: Tuesday, March 21, 2017 4:18 PM To: Mahipal Challa <[email protected]> Cc: [email protected]; [email protected]; Mahipal Challa <[email protected]>; [email protected]; lng-odp-forward <[email protected]> Subject: Re: [lng-odp] [RFC, API-NEXT v1 1/1] comp:compression interface Hi, This proposal supports both sync and async compression offload in a single API following the crypto model, IMO We can separate SYNC and ASYNC compression offload as two different APIs and only add ASYNC compression offload in the first version and if required we can add SYNC compression mode as a later enhancement. By following this approach we can simplify the module and will be easier to adapt. Regards, Bala On 17 March 2017 at 17:50, Mahipal Challa <[email protected]> wrote: > From: Shally Verma <[email protected]> > > An API set to add compression/decompression support in ODP interface. > > Signed-off-by: Shally Verma <[email protected]> > Signed-off-by: Mahipal Challa <[email protected]> > --- > include/odp/api/spec/comp.h | 668 ++++++++++++++++++++++++++++++ > ++++++++++++++ > 1 file changed, 668 insertions(+) > > diff --git a/include/odp/api/spec/comp.h b/include/odp/api/spec/comp.h > new file mode 100644 index 0000000..d8f6c68 > --- /dev/null > +++ b/include/odp/api/spec/comp.h > @@ -0,0 +1,668 @@ > +/* Copyright (c) 2017, 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> > + > +#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 event */ > + ODP_COMP_ASYNC, > +} odp_comp_op_mode_t; > + > +/** > + * Comp API operation type > + */ > +typedef enum { > + /** Compress and/or Compute ICV */ > + ODP_COMP_OP_COMPRESS, > + /** Decompress and/or Compute ICV */ > + ODP_COMP_OP_DECOMPRESS, > +} odp_comp_op_t; > + > +/** > + * Comp API compression algorithm > + * > + * Enum listing support Compression algo. Currently one > + * Compressor corresponds to 1 compliant decompressor. > + * > + */ > +typedef enum { > + /** No algorithm specified */ > + ODP_COMP_ALG_NULL, > + /** DEFLATE - > + * > + * implicit Inflate in case of decode operation > + * > + */ > + ODP_COMP_ALG_DEFLATE, > + /** ZLIB */ > + ODP_COMP_ALG_ZLIB, > + /** LZS*/ > + ODP_COMP_ALG_LZS, > + /** SHA1 > + * > + * When given, imply Authentication ONLY operation > + * > + */ > + ODP_COMP_ALG_SHA1, > + /** SHA256 > + * > + * When given, imply Authentication ONLY operation > + * > + */ > + ODP_COMP_ALG_SHA256, > + /** DEFLATE+SHA1 */ > + ODP_COMP_ALG_DEFLATE_SHA1, > + /** DEFLATE+SHA256 */ > + ODP_COMP_ALG_DEFLATE_SHA256, > + /** ZLIB+SHA */ > + ODP_COMP_ALG_ZLIB_SHA1, > + /** ZLIB+SHA256 */ > + ODP_COMP_ALG_ZLIB_SHA256, > + /** LZS+SHA1 */ > + ODP_COMP_ALG_LZS_SHA1, > + /** LZS+SHA256 */ > + ODP_COMP_ALG_LZS_SHA256 > +} 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,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 Algo fail error */ > + ODP_COMP_ERR_COMP_FAIL, > + /** Error detected during DMA of data */ > + ODP_COMP_ERR_DMA, > + /** Operation failed due to insufficient output buffer */ > + ODP_COMP_ERR_OUT_OF_SPACE, > +} 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, > + /** 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, > + /** use fixed huffman codes */ > + ODP_COMP_CODE_FIX_HUFFMAN, > + /** use dynamic huffman coding */ > + ODP_COMP_CODE_DYN_HUFFMAN, > +} odp_comp_code_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; > + > + /** ODP_COMP_ALG_SHA1 */ > + uint32_t sha1 :1; > + > + /** ODP_COMP_ALG_SHA256 */ > + uint32_t sha256 :1; > + > + /** ODP_COMP_ALG_DEFLATE_SHA1 */ > + uint32_t deflate_sha1:1; > + > + /** ODP_COMP_ALG_DEFLATE_SHA256 */ > + uint32_t deflate_sha256:1; > + > + /** ODP_COMP_ALG_ZLIB_SHA1 */ > + uint32_t zlib_sha1:1; > + > + /** ODP_COMP_ALG_ZLIB_SHA256 */ > + uint32_t zlib_sha256:1; > + > + /** ODP_COMP_ALG_LZS */ > + uint32_t lzs_sha1:1; > + > + /** ODP_COMP_ALG_LZS */ > + uint32_t lzs_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_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; > + > +} odp_comp_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 allowed length. In such case, implementation keep > responsibility > + * to update user discarded dictionary length. > + * > + */ > + uint32_t dict_len; > + /** key size in bytes for hash */ > + uint32_t key_size; > + > + /** Digest length in bytes for hash */ > + uint32_t digest_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 data pointer */ > + 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 data */ > + uint8_t *data; > + > + /** 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; > + > + /** Preferred sync vs. async > + * > + * Indicate user preferred mode of operartion. > + * Implementation may still choose sync or async depending > + * upon which one gives better performance in a particular > + * operational environment > + * > + */ > + odp_comp_op_mode_t pref_mode; > + > + /** force the requested op_mode. > + * > + * Indicates user request to enforce requested > + * operation mode. > + */ > + odp_bool_t force_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; > + > + /** auth parameters during session creation > + * These will remain valid till session life duration. > + * > + */ > + odp_comp_auth_key_t auth_key; > + > + /** Async mode completion event queue > + * > + * When odp_comp_operation() returns result with 'posted' set > + to > 'true', > + * the completion queue is > + * used to return the completion status of the operation to the > + * application. > + */ > + 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 > + * Data unit can be packet type/buffer type > + * determined based on pool used by app > + * > + */ > +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 > + * > + */ > + 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 both processed and hashed output (for Auth and > + Comp+Auth > algo) > + * > + * User is expected to pass a valid output packet in > + * current version of API set. > + * > + * In case of output packet is ODP_PACKET_INVALID, then > + * Auto-allocation and/or in-place support for output packet > + * to be considered later. > + * > + */ > + odp_packet_t out_data; > + > + /** output data range w.r.t out_data. > + * length at input specifies length of available output buffer, > + * offset marks beginning of output buffer. > + * This may be updated after operation completion. > + * > + */ > + odp_comp_data_range_t out_data_range; > + > + /** dictionary - Optional Pointer to dictionary as passed by > user.*/ > + void *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 { > + /** Indicate state of packet operation. Must be checked > + * at the return of odp_comp_operation() > + * > + * TRUE- Submitted but not completed (typical async op) > + * FALSE - Completed > + * > + */ > + odp_bool_t posted; > + > + /** User context from request */ > + void *ctx; > + > + /** Operation Return Code */ > + odp_comp_err_t err; > + > + /** pointer to output buffer. > + * Contains both processed output and hash for > + * Authentication and Compression+Authentication > + * Operations. > + * Valid when odp_comp_err_t is ODP_COMP_ERR_NONE > + */ > + odp_packet_t out_data; > + > + /** length of processed data */ > + odp_comp_data_range_t out_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. > + * > + * After every API call , if result parameter has 'posted' set to > + 'false', > + * means operation is complete and results are immediately available > + in > + * odp_comp_op_result_t. > + * > + * If 'posted' set to 'true' , means operation request has been > + submitted > but > + * not completed. operation result will be delivered by completion queue. > + * > + * Application should always check 'posted' regardless of operation > + mode > type > + * (sync/async) as some implementation may do some operation > synchornously even > + * for async requests. > + * > + * if operation returns ODP_COMP_ERR_OUT_OF_SPACE, then application > should call > + * API again with valid output buffer to continue processing of last > + input > + * request. > + * > + * @param param[in] Operation parameters. > + * @param result[out] Results of operation. Successful and Completed > + * call returns length of processed data in > result > + * > + * @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 > + * > + * Note: any invalid parameters will cause undefined behavior and > + may > cause > + * the application to abort or crash. > + * > + * @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 event > + * > + * @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); > + * > + * // do some work.. after it is completed > + * > + * ev = odp_queue_deq(ev_queue); > + * > + * compl=odp_comp_compl_from_event(ev); > + * > + * odp_comp_compl_result(compl,&result); > + * > + * > + */ > +void odp_comp_compl_result(odp_comp_compl_t event, > + odp_comp_op_result_t *result); > + > + /** > + * Convert comp completion handle to event handle > + * > + * @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 > + * > + * @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 > >
