1 /**************************************************************************** 2 * 3 * BSD LICENSE 4 * 5 * Copyright(c) 2007-2023 Intel Corporation. All rights reserved. 6 * All rights reserved. 7 * 8 * Redistribution and use in source and binary forms, with or without 9 * modification, are permitted provided that the following conditions 10 * are met: 11 * 12 * * Redistributions of source code must retain the above copyright 13 * notice, this list of conditions and the following disclaimer. 14 * * Redistributions in binary form must reproduce the above copyright 15 * notice, this list of conditions and the following disclaimer in 16 * the documentation and/or other materials provided with the 17 * distribution. 18 * * Neither the name of Intel Corporation nor the names of its 19 * contributors may be used to endorse or promote products derived 20 * from this software without specific prior written permission. 21 * 22 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 23 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 24 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 25 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 26 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 27 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 28 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 29 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 30 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 31 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 32 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 33 * 34 * 35 ***************************************************************************/ 36 37 /* 38 ***************************************************************************** 39 * Doxygen group definitions 40 ****************************************************************************/ 41 42 /** 43 ***************************************************************************** 44 * @file cpa_dc_bp.h 45 * 46 * @defgroup cpaDcBp Data Compression Batch and Pack API 47 * 48 * @ingroup cpaDc 49 * 50 * @description 51 * These functions specify the API for Data Compression operations related 52 * to the 'Batch and Pack' mode of operation. 53 * 54 * @remarks 55 * 56 * 57 *****************************************************************************/ 58 59 #ifndef CPA_DC_BP_H 60 #define CPA_DC_BP_H 61 62 #ifdef __cplusplus 63 extern"C" { 64 #endif 65 66 67 #include "cpa_dc.h" 68 69 /** 70 ***************************************************************************** 71 * @ingroup cpaDcBp 72 * Batch request input parameters. 73 * @description 74 * This structure contains the request information for use with batched 75 * compression operations. 76 * 77 * 78 ****************************************************************************/ 79 typedef struct _CpaDcBatchOpData { 80 CpaDcOpData opData; 81 /**< Compression input parameters */ 82 CpaBufferList *pSrcBuff; 83 /**< Input buffer list containing the data to be compressed. */ 84 CpaBoolean resetSessionState; 85 /**< Reset the session state at the beginning of this request within 86 * the batch. Only applies to stateful sessions. When this flag is 87 * set, the history from previous requests in this session will not be 88 * used when compressing the input data for this request in the batch. 89 * */ 90 } CpaDcBatchOpData ; 91 92 /** 93 ***************************************************************************** 94 * @ingroup cpaDcBp 95 * Submit a batch of requests to compress a batch of input buffers into 96 * a common output buffer. The same output buffer is used for each request 97 * in the batch. This is termed 'batch and pack'. 98 * 99 * @description 100 * This API consumes data from the input buffer and generates compressed 101 * data in the output buffer. 102 * This API compresses a batch of input buffers and concatenates the 103 * compressed data into the output buffer. A results structure is also 104 * generated for each request in the batch. 105 * 106 * @context 107 * When called as an asynchronous funnction it cannot sleep. It can be 108 * executed in a context that does not permit sleeping. 109 * When called as a synchronous function it may sleep. It MUST NOT be 110 * executed in a context that DOES NOT permit sleeping. 111 * @assumptions 112 * None 113 * @sideEffects 114 * None 115 * @blocking 116 * Yes when configured to operate in synchronous mode. 117 * @reentrant 118 * No 119 * @threadSafe 120 * Yes 121 * 122 * @param[in] dcInstance Target service instance. 123 * @param[in,out] pSessionHandle Session handle. 124 * @param[in] numRequests Number of requests in the batch. 125 * @param[in] pBatchOpData Pointer to an array of CpaDcBatchOpData 126 * structures which contain the input buffers 127 * and parameters for each request in the 128 * batch. There should be numRequests entries 129 * in the array. 130 * @param[in] pDestBuff Pointer to buffer space for data after 131 * compression. 132 * @param[in,out] pResults Pointer to an array of results structures. 133 * There should be numRequests entries in the 134 * array. 135 * @param[in] callbackTag User supplied value to help correlate 136 * the callback with its associated 137 * request. 138 * 139 * @retval CPA_STATUS_SUCCESS Function executed successfully. 140 * @retval CPA_STATUS_FAIL Function failed. 141 * @retval CPA_STATUS_RETRY Resubmit the request. 142 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 143 * @retval CPA_STATUS_RESOURCE Error related to system resources. 144 * @retval CPA_DC_BAD_DATA The input data was not properly formed. 145 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 146 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 147 * the request. 148 * 149 * @pre 150 * pSessionHandle has been setup using cpaDcInitSession() 151 * Session must be setup as a stateless session. 152 * @note 153 * This function passes control to the compression service for processing 154 * 155 * In synchronous mode the function returns the error status returned from the 156 * service. In asynchronous mode the status is returned by the callback 157 * function. 158 * 159 * This function may be called repetitively with input until all of the input 160 * has been consumed by the compression service and all the output has been 161 * produced. 162 * 163 * When this function returns, it may be that all of the available buffers in 164 * the input list has not been compressed. This situation will occur when 165 * there is insufficient space in the output buffer. The calling application 166 * should note the amount of buffers processed, and then submit the request 167 * again, with a new output buffer and with the input buffer list containing 168 * the buffers that were not previously compressed. 169 * 170 * Relationship between input buffers and results buffers. 171 * -# Implementations of this API must not modify the individual 172 * flat buffers of the input buffer list. 173 * -# The implementation communicates the number of buffers 174 * consumed from the source buffer list via pResults->consumed arg. 175 * -# The implementation communicates the amount of data in the 176 * destination buffer list via pResults->produced arg. 177 * 178 * Source Buffer Setup Rules 179 * -# The buffer list must have the correct number of flat buffers. This 180 * is specified by the numBuffers element of the CpaBufferList. 181 * -# Each flat buffer must have a pointer to contiguous memory that has 182 * been allocated by the calling application. The number of octets to be 183 * compressed or decompressed must be stored in the dataLenInBytes element 184 * of the flat buffer. 185 * -# It is permissible to have one or more flat buffers with a zero length 186 * data store. This function will process all flat buffers until the 187 * destination buffer is full or all source data has been processed. 188 * If a buffer has zero length, then no data will be processed from 189 * that buffer. 190 * 191 * Source Buffer Processing Rules. 192 * -# The buffer list is processed in index order - SrcBuff->pBuffers[0] 193 * will be completely processed before SrcBuff->pBuffers[1] begins to 194 * be processed. 195 * -# The application must drain the destination buffers. 196 * If the source data was not completely consumed, the application 197 * must resubmit the request. 198 * -# On return, the pResults->consumed will indicate the number of buffers 199 * consumed from the input buffer list. 200 * 201 * Destination Buffer Setup Rules 202 * -# The destination buffer list must have storage for processed data and 203 * for the packed header information. 204 * This means that least two flat buffer must exist in the buffer list. 205 * The first buffer entry will be used for the header information. 206 * Subsequent entries will be used for the compressed data. 207 * -# For each flat buffer in the buffer list, the dataLenInBytes element 208 * must be set to the size of the buffer space. 209 * -# It is permissible to have one or more flat buffers with a zero length 210 * data store. 211 * If a buffer has zero length, then no data will be added to 212 * that buffer. 213 * 214 * Destination Buffer Processing Rules. 215 * -# The buffer list is processed in index order. 216 * -# On return, the pResults->produced will indicate the number of bytes 217 * of compressed data written to the output buffers. Note that this 218 * will not include the header information buffer. 219 * -# If processing has not been completed, the application must drain the 220 * destination buffers and resubmit the request. The application must reset 221 * the dataLenInBytes for each flat buffer in the destination buffer list. 222 * 223 * Synchronous or Asynchronous operation of the API is determined by 224 * the value of the callbackFn parameter passed to cpaDcInitSession() 225 * when the sessionHandle was setup. If a non-NULL value was specified 226 * then the supplied callback function will be invoked asynchronously 227 * with the response of this request. 228 * 229 * Response ordering: 230 * For each session, the implementation must maintain the order of 231 * responses. That is, if in asynchronous mode, the order of the callback 232 * functions must match the order of jobs submitted by this function. 233 * In a simple synchronous mode implementation, the practice of submitting 234 * a request and blocking on its completion ensure ordering is preserved. 235 * 236 * This limitation does not apply if the application employs multiple 237 * threads to service a single session. 238 * 239 * If this API is invoked asynchronous, the return code represents 240 * the success or not of asynchronously scheduling the request. 241 * The results of the operation, along with the amount of data consumed 242 * and produced become available when the callback function is invoked. 243 * As such, pResults->consumed and pResults->produced are available 244 * only when the operation is complete. 245 * 246 * The application must not use either the source or destination buffers 247 * until the callback has completed. 248 * 249 * @see 250 * None 251 * 252 *****************************************************************************/ 253 CpaStatus 254 cpaDcBPCompressData( CpaInstanceHandle dcInstance, 255 CpaDcSessionHandle pSessionHandle, 256 const Cpa32U numRequests, 257 CpaDcBatchOpData *pBatchOpData, 258 CpaBufferList *pDestBuff, 259 CpaDcRqResults *pResults, 260 void *callbackTag ); 261 262 /** 263 ***************************************************************************** 264 * @ingroup cpaDcBp 265 * Function to return the size of the memory which must be allocated for 266 * the pPrivateMetaData member of CpaBufferList contained within 267 * CpaDcBatchOpData. 268 * 269 * @description 270 * This function is used to obtain the size (in bytes) required to allocate 271 * a buffer descriptor for the pPrivateMetaData member in the 272 * CpaBufferList structure when Batch and Pack API are used. 273 * Should the function return zero then no meta data is required for the 274 * buffer list. 275 * 276 * @context 277 * This function may be called from any context. 278 * @assumptions 279 * None 280 * @sideEffects 281 * None 282 * @blocking 283 * No 284 * @reentrant 285 * No 286 * @threadSafe 287 * Yes 288 * 289 * @param[in] instanceHandle Handle to an instance of this API. 290 * @param[in] numJobs The number of jobs defined in the CpaDcBatchOpData 291 * table. 292 * @param[out] pSizeInBytes Pointer to the size in bytes of memory to be 293 * allocated when the client wishes to allocate 294 * a cpaFlatBuffer and the Batch and Pack OP data. 295 * 296 * @retval CPA_STATUS_SUCCESS Function executed successfully. 297 * @retval CPA_STATUS_FAIL Function failed. 298 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 299 * 300 * @pre 301 * None 302 * @post 303 * None 304 * @note 305 * None 306 * @see 307 * cpaDcBPCompressData() 308 * 309 *****************************************************************************/ 310 CpaStatus 311 cpaDcBnpBufferListGetMetaSize(const CpaInstanceHandle instanceHandle, 312 Cpa32U numJobs, 313 Cpa32U *pSizeInBytes); 314 315 316 #ifdef __cplusplus 317 } /* close the extern "C" { */ 318 #endif 319 320 #endif /* CPA_DC_BP_H */ 321