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