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_chain.h 12 * 13 * @defgroup cpaDcChain Data Compression Chaining API 14 * 15 * @ingroup cpaDc 16 * 17 * @description 18 * These functions specify the API for Data Compression Chaining operations. 19 * 20 * @remarks 21 * 22 * 23 *****************************************************************************/ 24 25 #ifndef CPA_DC_CHAIN_H 26 #define CPA_DC_CHAIN_H 27 28 #ifdef __cplusplus 29 extern"C" { 30 #endif 31 32 #include "cpa_dc.h" 33 #include "cpa_cy_sym.h" 34 35 36 /** 37 ***************************************************************************** 38 * @ingroup cpaDcChain 39 * Supported operations for compression chaining 40 * 41 * @description 42 * This enumeration lists the supported operations for compression chaining 43 * 44 *****************************************************************************/ 45 typedef enum _CpaDcChainOperations 46 { 47 CPA_DC_CHAIN_COMPRESS_THEN_HASH = 0, 48 /**< 2 operations for chaining: 49 * 1st operation is to perform compression on plain text 50 * 2nd operation is to perform hash on compressed text 51 **< 2 entries in CpaDcChainSessionSetupData array: 52 * 1st entry is for compression setup data 53 * 2nd entry is for hash setup data*/ 54 CPA_DC_CHAIN_COMPRESS_THEN_ENCRYPT = 1, 55 /**< 2 operations for chaining: 56 * 1st operation is to perform compression on plain text 57 * 2nd operation is to perform encryption on compressed text 58 **< 2 entries in CpaDcChainSessionSetupData array: 59 * 1st entry is for compression setup data 60 * 2nd entry is for encryption setup data*/ 61 CPA_DC_CHAIN_COMPRESS_THEN_HASH_ENCRYPT = 2, 62 /**< 2 operations for chaining: 63 * 1st operation is to perform compression on plain text 64 * 2nd operation is to perform hash on compressed text and 65 * encryption on compressed text 66 **< 2 entries in CpaDcChainSessionSetupData array: 67 * 1st entry is for compression setup data 68 * 2nd entry is for hash and encryption setup data*/ 69 CPA_DC_CHAIN_COMPRESS_THEN_ENCRYPT_HASH = 3, 70 /**< 2 operations for chaining: 71 * 1st operation is to perform compression on plain text 72 * 2nd operation is to perform encryption on compressed text and 73 * hash on compressed & encrypted text 74 **< 2 entries in CpaDcChainSessionSetupData array: 75 * 1st entry is for compression setup data 76 * 2nd entry is for encryption and hash setup data*/ 77 CPA_DC_CHAIN_COMPRESS_THEN_AEAD = 4, 78 /**< 2 operations for chaining: 79 * 1st operation is to perform compression on plain text 80 * 2nd operation is to perform AEAD encryption on compressed text 81 **< 2 entries in CpaDcChainSessionSetupData array: 82 * 1st entry is for compression setup data 83 * 2nd entry is for AEAD encryption setup data*/ 84 CPA_DC_CHAIN_HASH_THEN_COMPRESS = 5, 85 /**< 2 operations for chaining: 86 * 1st operation is to perform hash on plain text 87 * 2nd operation is to perform compression on plain text 88 **< 2 entries in CpaDcChainSessionSetupData array: 89 * 1st entry is for hash setup data 90 * 2nd entry is for compression setup data*/ 91 CPA_DC_CHAIN_HASH_VERIFY_THEN_DECOMPRESS = 6, 92 /**< 2 operations for chaining: 93 * 1st operation is to perform hash verify on compressed text 94 * 2nd operation is to perform decompression on compressed text 95 **< 2 entries in CpaDcChainSessionSetupData array: 96 * 1st entry is for hash setup data 97 * 2nd entry is for decompression setup data*/ 98 CPA_DC_CHAIN_DECRYPT_THEN_DECOMPRESS = 7, 99 /**< 2 operations for chaining: 100 * 1st operation is to perform decryption on compressed & encrypted text 101 * 2nd operation is to perform decompression on compressed text 102 **< 2 entries in CpaDcChainSessionSetupData array: 103 * 1st entry is for decryption setup data 104 * 2nd entry is for decompression setup data*/ 105 CPA_DC_CHAIN_HASH_VERIFY_DECRYPT_THEN_DECOMPRESS = 8, 106 /**< 2 operations for chaining: 107 * 1st operation is to perform hash verify on compressed & encrypted text 108 * and decryption on compressed & encrypted text 109 * 2nd operation is to perform decompression on compressed text 110 **< 2 entries in CpaDcChainSessionSetupData array: 111 * 1st entry is for hash and decryption setup data 112 * 2nd entry is for decompression setup data*/ 113 CPA_DC_CHAIN_DECRYPT_HASH_VERIFY_THEN_DECOMPRESS = 9, 114 /**< 2 operations for chaining: 115 * 1st operation is to perform decryption on compressed & encrypted text 116 * and hash verify on compressed text 117 * 2nd operation is to perform decompression on compressed text 118 **< 2 entries in CpaDcChainSessionSetupData array: 119 * 1st entry is for decryption and hash setup data 120 * 2nd entry is for decompression setup data*/ 121 CPA_DC_CHAIN_AEAD_THEN_DECOMPRESS = 10, 122 /**< 2 operations for chaining: 123 * 1st operation is to perform AEAD decryption on compressed & encrypted text 124 * 2nd operation is to perform decompression on compressed text 125 **< 2 entries in CpaDcChainSessionSetupData array: 126 * 1st entry is for AEAD decryption setup data 127 * 2nd entry is for decompression setup data*/ 128 CPA_DC_CHAIN_DECOMPRESS_THEN_HASH_VERIFY = 11, 129 /**< 2 operations for chaining: 130 * 1st operation is to perform decompression on compressed text 131 * 2nd operation is to perform hash verify on plain text 132 **< 2 entries in CpaDcChainSessionSetupData array: 133 * 1st entry is for decompression setup data 134 * 2nd entry is for hash setup data*/ 135 CPA_DC_CHAIN_COMPRESS_THEN_AEAD_THEN_HASH = 12, 136 /**< 3 operations for chaining: 137 * 1st operation is to perform compression on plain text 138 * 2nd operation is to perform AEAD encryption on compressed text 139 * 3rd operation is to perform hash on compressed & encrypted text 140 **< 3 entries in CpaDcChainSessionSetupData array: 141 * 1st entry is for compression setup data 142 * 2nd entry is for AEAD encryption setup data 143 * 3rd entry is for hash setup data*/ 144 } CpaDcChainOperations; 145 146 /** 147 ***************************************************************************** 148 * @ingroup cpaDcChain 149 * Supported session types for data compression chaining. 150 * 151 * @description 152 * This enumeration lists the supported session types 153 * for data compression chaining. 154 *****************************************************************************/ 155 typedef enum _CpaDcChainSessionType 156 { 157 CPA_DC_CHAIN_COMPRESS_DECOMPRESS = 0, 158 /**< Indicate the session is for compression or decompression */ 159 CPA_DC_CHAIN_SYMMETRIC_CRYPTO 160 /**< Indicate the session is for symmetric crypto */ 161 } CpaDcChainSessionType; 162 163 /** 164 ***************************************************************************** 165 * @ingroup cpaDcChain 166 * Chaining Session Setup Data. 167 * @description 168 * This structure contains data relating to set up chaining sessions. The 169 * client needs to complete the information in this structure in order to 170 * setup chaining sessions. 171 * 172 ****************************************************************************/ 173 typedef struct _CpaDcChainSessionSetupData { 174 CpaDcChainSessionType sessType; 175 /**Indicate the type for this session */ 176 union { 177 CpaDcSessionSetupData *pDcSetupData; 178 /**< Pointer to compression session setup data */ 179 CpaCySymSessionSetupData *pCySetupData; 180 /**< Pointer to symmetric crypto session setup data */ 181 }; 182 } CpaDcChainSessionSetupData; 183 184 /** 185 ***************************************************************************** 186 * @ingroup cpaDcChain 187 * Compression chaining request input parameters. 188 * @description 189 * This structure contains the request information to use with 190 * compression chaining operations. 191 * 192 ****************************************************************************/ 193 typedef struct _CpaDcChainOpData { 194 CpaDcChainSessionType opType; 195 /**< Indicate the type for this operation */ 196 union { 197 CpaDcOpData *pDcOp; 198 /**< Pointer to compression operation data */ 199 CpaCySymOpData *pCySymOp; 200 /**< Pointer to symmetric crypto operation data */ 201 }; 202 } CpaDcChainOpData; 203 204 /** 205 ***************************************************************************** 206 * @ingroup cpaDcChain 207 * Chaining request results data 208 * @description 209 * This structure contains the request results. 210 * 211 ****************************************************************************/ 212 typedef struct _CpaDcChainRqResults { 213 CpaDcReqStatus dcStatus; 214 /**< Additional status details from compression accelerator */ 215 CpaStatus cyStatus; 216 /**< Additional status details from symmetric crypto accelerator */ 217 CpaBoolean verifyResult; 218 /**< This parameter is valid when the verifyDigest option is set in the 219 * CpaCySymSessionSetupData structure. A value of CPA_TRUE indicates 220 * that the compare succeeded. A value of CPA_FALSE indicates that the 221 * compare failed */ 222 Cpa32U produced; 223 /**< Octets produced to the output buffer */ 224 Cpa32U consumed; 225 /**< Octets consumed from the input buffer */ 226 Cpa32U crc32; 227 /**< crc32 checksum produced by chaining operations */ 228 Cpa32U adler32; 229 /**< Adler32 checksum produced by chaining operations */ 230 }CpaDcChainRqResults; 231 232 /** 233 ***************************************************************************** 234 * @ingroup cpaDcChain 235 * Get the size of the memory required to hold the chaining sessions 236 * information. 237 * 238 * @description 239 * The client of the Data Compression API is responsible for 240 * allocating sufficient memory to hold chaining sessions information. 241 * This function provides a way for determining the size of chaining 242 * sessions. 243 * 244 * @context 245 * No restrictions 246 * @assumptions 247 * None 248 * @sideEffects 249 * None 250 * @blocking 251 * No 252 * @reentrant 253 * No 254 * @threadSafe 255 * Yes 256 * 257 * @param[in] dcInstance Instance handle. 258 * @param[in] operation The operation for chaining 259 * @param[in] numSessions Number of sessions for the chaining 260 * @param[in] pSessionData Pointer to an array of 261 * CpaDcChainSessionSetupData structures. 262 * There should be numSessions entries in 263 * the array. 264 * @param[out] pSessionSize On return, this parameter will be the size 265 * of the memory that will be required by 266 * cpaDcChainInitSession() for session data. 267 * 268 * @retval CPA_STATUS_SUCCESS Function executed successfully. 269 * @retval CPA_STATUS_FAIL Function failed. 270 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 271 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 272 * 273 * @pre 274 * None 275 * @post 276 * None 277 * @note 278 * Only a synchronous version of this function is provided. 279 * 280 * @see 281 * cpaDcChainInitSession() 282 * 283 *****************************************************************************/ 284 CpaStatus 285 cpaDcChainGetSessionSize(CpaInstanceHandle dcInstance, 286 CpaDcChainOperations operation, 287 Cpa8U numSessions, 288 CpaDcChainSessionSetupData *pSessionData, 289 Cpa32U* pSessionSize); 290 291 /** 292 ***************************************************************************** 293 * @ingroup cpaDcChain 294 * Initialize data compression chaining session 295 * 296 * @description 297 * This function is used to initialize compression/decompression chaining 298 * sessions. 299 * This function returns a unique session handle each time this function 300 * is invoked. 301 * If the session has been configured with a callback function, then 302 * the order of the callbacks are guaranteed to be in the same order the 303 * compression or decompression requests were submitted for each session, 304 * so long as a single thread of execution is used for job submission. 305 * 306 * @context 307 * This is a synchronous function and it cannot sleep. It can be executed 308 * in a context that does not permit sleeping. 309 * @assumptions 310 * None 311 * @sideEffects 312 * None 313 * @blocking 314 * No 315 * @reentrant 316 * No 317 * @threadSafe 318 * Yes 319 * 320 * @param[in] dcInstance Instance handle derived from discovery 321 * functions. 322 * @param[in,out] pSessionHandle Pointer to a session handle. 323 * @param[in] operation The operations for chaining 324 * @param[in] numSessions Number of sessions for chaining 325 * @param[in,out] pSessionData Pointer to an array of 326 * CpaDcChainSessionSetupData structures. 327 * There should be numSessions entries in 328 * the array. 329 * @param[in] callbackFn For synchronous operation this callback 330 * shall be a null pointer. 331 * 332 * @retval CPA_STATUS_SUCCESS Function executed successfully. 333 * @retval CPA_STATUS_FAIL Function failed. 334 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 335 * @retval CPA_STATUS_RESOURCE Error related to system resources. 336 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 337 * 338 * @pre 339 * dcInstance has been started using cpaDcStartInstance. 340 * @post 341 * None 342 * @note 343 * Only a synchronous version of this function is provided. 344 * 345 * pSessionData Setup Rules 346 * -# Each element in CpaDcChainSessionSetupData structure array provides 347 * (de)compression or a symmetric crypto session setup data. 348 * 349 * -# The supported chaining operations are listed in CpaDcChainOperations. 350 * This enum indicates the number of operations in a chain and the order 351 * in which they are performed. 352 * 353 * -# The order of entries in pSessionData[] should be consistent with the 354 * CpaDcChainOperations perform order. 355 * As an example, for CPA_DC_CHAIN_COMPRESS_THEN_ENCRYPT, pSessionData[0] 356 * holds the compression setup data and pSessionData[1] holds the 357 * encryption setup data.. 358 * 359 * -# The numSessions for each chaining operation are provided in 360 * the comments of enum CpaDcChainOperations. 361 * 362 * -# For a (de)compression session, the corresponding 363 * pSessionData[]->sessType should be set to 364 * CPA_DC_CHAIN_COMPRESS_DECOMPRESS and pSessionData[]->pDcSetupData 365 * should point to a CpaDcSessionSetupData structure. 366 * 367 * -# For a symmetric crypto session, the corresponding 368 * pSessionData[]->sessType should be set to CPA_DC_CHAIN_SYMMETRIC_CRYPTO 369 * and pSessionData[]->pCySetupData should point to a 370 * CpaCySymSessionSetupData structure. 371 * 372 * -# Combined compression sessions are not supported for chaining. 373 * 374 * -# Stateful compression is not supported for chaining. 375 * 376 * -# Both CRC32 and Adler32 over the input data are supported for chaining. 377 * 378 * @see 379 * None 380 * 381 *****************************************************************************/ 382 CpaStatus 383 cpaDcChainInitSession(CpaInstanceHandle dcInstance, 384 CpaDcSessionHandle pSessionHandle, 385 CpaDcChainOperations operation, 386 Cpa8U numSessions, 387 CpaDcChainSessionSetupData *pSessionData, 388 CpaDcCallbackFn callbackFn); 389 390 /** 391 ***************************************************************************** 392 * @ingroup cpaDcChain 393 * Reset a compression chaining session. 394 * 395 * @description 396 * This function will reset a previously initialized session handle. 397 * Reset will fail if outstanding calls still exist for the initialized 398 * session handle. 399 * The client needs to retry the reset function at a later time. 400 * 401 * @context 402 * This is a synchronous function that cannot sleep. It can be 403 * executed in a context that does not permit sleeping. 404 * @assumptions 405 * None 406 * @sideEffects 407 * None 408 * @blocking 409 * No. 410 * @reentrant 411 * No 412 * @threadSafe 413 * Yes 414 * 415 * @param[in] dcInstance Instance handle. 416 * @param[in,out] pSessionHandle Session handle. 417 * 418 * @retval CPA_STATUS_SUCCESS Function executed successfully. 419 * @retval CPA_STATUS_FAIL Function failed. 420 * @retval CPA_STATUS_RETRY Resubmit the request. 421 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 422 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 423 * 424 * @pre 425 * The component has been initialized via cpaDcStartInstance function. 426 * The session has been initialized via cpaDcChainInitSession function. 427 * @post 428 * None 429 * @note 430 * This is a synchronous function and has no completion callback 431 * associated with it. 432 * 433 * @see 434 * cpaDcChainInitSession() 435 * 436 *****************************************************************************/ 437 CpaStatus 438 cpaDcChainResetSession(const CpaInstanceHandle dcInstance, 439 CpaDcSessionHandle pSessionHandle); 440 441 442 /** 443 ***************************************************************************** 444 * @ingroup cpaDcChain 445 * Remove a compression chaining session. 446 * 447 * @description 448 * This function will remove a previously initialized session handle 449 * and the installed callback handler function. Removal will fail if 450 * outstanding calls still exist for the initialized session handle. 451 * The client needs to retry the remove function at a later time. 452 * The memory for the session handle MUST not be freed until this call 453 * has completed successfully. 454 * 455 * @context 456 * This is a synchronous function that cannot sleep. It can be executed 457 * in a context that does not permit sleeping. 458 * @assumptions 459 * None 460 * @sideEffects 461 * None 462 * @blocking 463 * No. 464 * @reentrant 465 * No 466 * @threadSafe 467 * Yes 468 * 469 * @param[in] dcInstance Instance handle. 470 * @param[in,out] pSessionHandle Session handle. 471 * 472 * @retval CPA_STATUS_SUCCESS Function executed successfully. 473 * @retval CPA_STATUS_FAIL Function failed. 474 * @retval CPA_STATUS_RETRY Resubmit the request. 475 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 476 * @retval CPA_STATUS_RESOURCE Error related to system resources. 477 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 478 * the request. 479 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 480 * 481 * @pre 482 * The component has been initialized via cpaDcStartInstance function. 483 * @post 484 * None 485 * @note 486 * This is a synchronous function and has no completion callback 487 * associated with it. 488 * 489 * @see 490 * cpaDcChainInitSession() 491 * 492 *****************************************************************************/ 493 CpaStatus 494 cpaDcChainRemoveSession(const CpaInstanceHandle dcInstance, 495 CpaDcSessionHandle pSessionHandle); 496 497 /** 498 ***************************************************************************** 499 * @ingroup cpaDcChain 500 * Submit a request to perform chaining operations. 501 * 502 * @description 503 * This function is used to perform chaining operations over data from 504 * the source buffer. 505 * 506 * @context 507 * When called as an asynchronous function it cannot sleep. It can be 508 * executed in a context that does not permit sleeping. 509 * When called as a synchronous function it may sleep. It MUST NOT be 510 * executed in a context that DOES NOT permit sleeping. 511 * @assumptions 512 * None 513 * @sideEffects 514 * None 515 * @blocking 516 * Yes when configured to operate in synchronous mode. 517 * @reentrant 518 * No 519 * @threadSafe 520 * Yes 521 * 522 * @param[in] dcInstance Target service instance. 523 * @param[in,out] pSessionHandle Session handle. 524 * @param[in] pSrcBuff Pointer to input data buffer. 525 * @param[out] pDestBuff Pointer to output data buffer. 526 * @param[in] operation Operation for the chaining request 527 * @param[in] numOpDatas The entries size CpaDcChainOpData array 528 * @param[in] pChainOpData Pointer to an array of CpaDcChainOpData 529 * structures. There should be numOpDatas 530 * entries in the array. 531 * @param[in,out] pResults Pointer to CpaDcChainRqResults 532 * @param[in] callbackTag User supplied value to help correlate 533 * the callback with its associated request. 534 * 535 * @retval CPA_STATUS_SUCCESS Function executed successfully. 536 * @retval CPA_STATUS_FAIL Function failed. 537 * @retval CPA_STATUS_RETRY Resubmit the request. 538 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 539 * @retval CPA_STATUS_RESOURCE Error related to system resources. 540 * @retval CPA_DC_BAD_DATA The input data was not properly formed. 541 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 542 * the request. 543 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 544 * 545 * @pre 546 * pSessionHandle has been setup using cpaDcChainInitSession() 547 * @post 548 * pSessionHandle has session related state information 549 * @note 550 * This function passes control to the compression service for chaining 551 * processing, the supported chaining operations are described in 552 * CpaDcChainOperations. 553 * 554 * pChainOpData Setup Rules 555 * -# Each element in CpaDcChainOpData structure array holds either a 556 * (de)compression or a symmetric crypto operation data. 557 * 558 * -# The order of entries in pChainOpData[] must be consistent with the 559 * order of operations described for the chaining operation in 560 * CpaDcChainOperations. 561 * As an example, for CPA_DC_CHAIN_HASH_THEN_COMPRESS, pChainOpData[0] 562 * must contain the hash operation data and pChainOpData[1] must 563 * contain the compress operation data. 564 * 565 * -# The numOpDatas for each chaining operation are specified in the 566 * comments for the operation in CpaDcChainOperations. 567 * 568 * -# For a (de)compression operation, the corresponding 569 * pChainOpData[]->opType should be set to 570 * CPA_DC_CHAIN_COMPRESS_DECOMPRESS and pChainOpData[]->pDcOp should 571 * point to a CpaDcOpData structure. 572 * 573 * -# For a symmetric crypto operation, the corresponding 574 * pChainOpData[]->opType should be set to 575 * CPA_DC_CHAIN_SYMMETRIC_CRYPTO and pChainOpData[]->pCySymOp should 576 * point to a CpaCySymOpData structure. 577 * 578 * -# Partial packet processing is not supported. 579 * 580 * This function has identical buffer processing rules as 581 * cpaDcCompressData(). 582 * 583 * This function has identical checksum processing rules as 584 * cpaDcCompressData(), except: 585 * -# pResults->crc32 is available to application if 586 * CpaDcSessionSetupData->checksum is set to CPA_DC_CRC32 587 * 588 * -# pResults->adler32 is available to application if 589 * CpaDcSessionSetupData->checksum is set to CPA_DC_ADLER32 590 * 591 * -# Both pResults->crc32 and pResults->adler32 are available if 592 * CpaDcSessionSetupData->checksum is set to CPA_DC_CRC32_ADLER32 593 * 594 * Synchronous or asynchronous operation of the API is determined by 595 * the value of the callbackFn parameter passed to cpaDcChainInitSession() 596 * when the sessionHandle was setup. If a non-NULL value was specified 597 * then the supplied callback function will be invoked asynchronously 598 * with the response of this request. 599 * 600 * This function has identical response ordering rules as 601 * cpaDcCompressData(). 602 * 603 * @see 604 * cpaDcCompressData 605 * 606 *****************************************************************************/ 607 CpaStatus 608 cpaDcChainPerformOp(CpaInstanceHandle dcInstance, 609 CpaDcSessionHandle pSessionHandle, 610 CpaBufferList *pSrcBuff, 611 CpaBufferList *pDestBuff, 612 CpaDcChainOperations operation, 613 Cpa8U numOpDatas, 614 CpaDcChainOpData *pChainOpData, 615 CpaDcChainRqResults *pResults, 616 void *callbackTag ); 617 618 #ifdef __cplusplus 619 } /* close the extern "C" { */ 620 #endif 621 622 #endif /* CPA_DC_CHAIN_H */ 623