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_cy_sym_dp.h 12 * 13 * @defgroup cpaCySymDp Symmetric cryptographic Data Plane API 14 * 15 * @ingroup cpaCySym 16 * 17 * @description 18 * These data structures and functions specify the Data Plane API 19 * for symmetric cipher, hash, and combined cipher and hash 20 * operations. 21 * 22 * This API is recommended for data plane applications, in which the 23 * cost of offload - that is, the cycles consumed by the driver in 24 * sending requests to the hardware, and processing responses - needs 25 * to be minimized. In particular, use of this API is recommended 26 * if the following constraints are acceptable to your application: 27 * 28 * - Thread safety is not guaranteed. Each software thread should 29 * have access to its own unique instance (CpaInstanceHandle) to 30 * avoid contention. 31 * - Polling is used, rather than interrupts (which are expensive). 32 * Implementations of this API will provide a function (not 33 * defined as part of this API) to read responses from the hardware 34 * response queue and dispatch callback functions, as specified on 35 * this API. 36 * - Buffers and buffer lists are passed using physical addresses, 37 * to avoid virtual to physical address translation costs. 38 * - For GCM and CCM modes of AES, when performing decryption and 39 * verification, if verification fails, then the message buffer 40 * will NOT be zeroed. (This is a consequence of using physical 41 * addresses for the buffers.) 42 * - The ability to enqueue one or more requests without submitting 43 * them to the hardware allows for certain costs to be amortized 44 * across multiple requests. 45 * - Only asynchronous invocation is supported. 46 * - There is no support for partial packets. 47 * - Implementations may provide certain features as optional at 48 * build time, such as atomic counters. 49 * - The "default" instance (@ref CPA_INSTANCE_HANDLE_SINGLE) is not 50 * supported on this API. The specific handle should be obtained 51 * using the instance discovery functions (@ref cpaCyGetNumInstances, 52 * @ref cpaCyGetInstances). 53 * 54 * @note Performance Trade-Offs 55 * Different implementations of this API may have different performance 56 * trade-offs; please refer to the documentation for your implementation 57 * for details. However, the following concepts informed the definition 58 * of this API. 59 * 60 * The API distinguishes between <i>enqueuing</i> a request and actually 61 * <i>submitting</i> that request to the cryptographic acceleration 62 * engine to be performed. This allows multiple requests to be enqueued 63 * (either individually or in batch), and then for all enqueued requests 64 * to be submitted in a single operation. The rationale is that in some 65 * (especially hardware-based) implementations, the submit operation 66 * is expensive; for example, it may incur an MMIO instruction. The 67 * API allows this cost to be amortized over a number of requests. The 68 * precise number of such requests can be tuned for optimal 69 * performance. 70 * 71 * Specifically: 72 * 73 * - The function @ref cpaCySymDpEnqueueOp allows one request to be 74 * enqueued, and optionally for that request (and all previously 75 * enqueued requests) to be submitted. 76 * - The function @ref cpaCySymDpEnqueueOpBatch allows multiple 77 * requests to be enqueued, and optionally for those requests (and all 78 * previously enqueued requests) to be submitted. 79 * - The function @ref cpaCySymDpPerformOpNow enqueues no requests, but 80 * submits all previously enqueued requests. 81 *****************************************************************************/ 82 83 #ifndef CPA_CY_SYM_DP_H 84 #define CPA_CY_SYM_DP_H 85 86 #ifdef __cplusplus 87 extern "C" { 88 #endif 89 90 #include "cpa_cy_common.h" 91 #include "cpa_cy_sym.h" 92 93 /** 94 ***************************************************************************** 95 * @ingroup cpaCySymDp 96 * Cryptographic component symmetric session context handle for the 97 * data plane API. 98 * @description 99 * Handle to a cryptographic data plane session context. The memory for 100 * this handle is allocated by the client. The size of the memory that 101 * the client needs to allocate is determined by a call to the @ref 102 * cpaCySymDpSessionCtxGetSize or @ref cpaCySymDpSessionCtxGetDynamicSize 103 * functions. The session context memory is initialized with a call to 104 * the @ref cpaCySymInitSession function. 105 * This memory MUST not be freed until a call to @ref 106 * cpaCySymDpRemoveSession has completed successfully. 107 * 108 *****************************************************************************/ 109 typedef void * CpaCySymDpSessionCtx; 110 111 /** 112 ***************************************************************************** 113 * @ingroup cpaCySymDp 114 * Operation Data for cryptographic data plane API. 115 * 116 * @description 117 * This structure contains data relating to a request to perform 118 * symmetric cryptographic processing on one or more data buffers. 119 * 120 * The physical memory to which this structure points needs to be 121 * at least 8-byte aligned. 122 * 123 * All reserved fields SHOULD NOT be written or read by the 124 * calling code. 125 * 126 * @see 127 * cpaCySymDpEnqueueOp, cpaCySymDpEnqueueOpBatch 128 ****************************************************************************/ 129 typedef struct _CpaCySymDpOpData { 130 Cpa64U reserved0; 131 /**< Reserved for internal usage. */ 132 Cpa32U cryptoStartSrcOffsetInBytes; 133 /**< Starting point for cipher processing, specified as number of bytes 134 * from start of data in the source buffer. The result of the cipher 135 * operation will be written back into the buffer starting at this 136 * location in the destination buffer. 137 */ 138 Cpa32U messageLenToCipherInBytes; 139 /**< The message length, in bytes, of the source buffer on which the 140 * cryptographic operation will be computed. This must be a multiple of 141 * the block size if a block cipher is being used. This is also the 142 * same as the result length. 143 * 144 * @note In the case of CCM (@ref CPA_CY_SYM_HASH_AES_CCM), this value 145 * should not include the length of the padding or the length of the 146 * MAC; the driver will compute the actual number of bytes over which 147 * the encryption will occur, which will include these values. 148 * 149 * @note For AES-GMAC (@ref CPA_CY_SYM_HASH_AES_GMAC), this field 150 * should be set to 0. 151 * 152 * @note On some implementations, this length may be limited to a 16-bit 153 * value (65535 bytes). 154 */ 155 CpaPhysicalAddr iv; 156 /**< Initialization Vector or Counter. Specifically, this is the 157 * physical address of one of the following: 158 * 159 * - For block ciphers in CBC mode, or for Kasumi in F8 mode, or for 160 * SNOW3G in UEA2 mode, this is the Initialization Vector (IV) 161 * value. 162 * - For ARC4, this is reserved for internal usage. 163 * - For block ciphers in CTR mode, this is the counter. 164 * - For GCM mode, this is either the IV (if the length is 96 bits) or J0 165 * (for other sizes), where J0 is as defined by NIST SP800-38D. 166 * Regardless of the IV length, a full 16 bytes needs to be allocated. 167 * - For CCM mode, the first byte is reserved, and the nonce should be 168 * written starting at &pIv[1] (to allow space for the implementation 169 * to write in the flags in the first byte). Note that a full 16 bytes 170 * should be allocated, even though the ivLenInBytes field will have 171 * a value less than this. 172 * The macro @ref CPA_CY_SYM_CCM_SET_NONCE may be used here. 173 */ 174 Cpa64U reserved1; 175 /**< Reserved for internal usage. */ 176 Cpa32U hashStartSrcOffsetInBytes; 177 /**< Starting point for hash processing, specified as number of bytes 178 * from start of packet in source buffer. 179 * 180 * @note For CCM and GCM modes of operation, this value in this field 181 * is ignored, and the field is reserved for internal usage. 182 * The fields @ref additionalAuthData and @ref pAdditionalAuthData 183 * should be set instead. 184 * 185 * @note For AES-GMAC (@ref CPA_CY_SYM_HASH_AES_GMAC) mode of 186 * operation, this field specifies the start of the AAD data in 187 * the source buffer. 188 */ 189 Cpa32U messageLenToHashInBytes; 190 /**< The message length, in bytes, of the source buffer that the hash 191 * will be computed on. 192 * 193 * @note For CCM and GCM modes of operation, this value in this field 194 * is ignored, and the field is reserved for internal usage. 195 * The fields @ref additionalAuthData and @ref pAdditionalAuthData 196 * should be set instead. 197 * 198 * @note For AES-GMAC (@ref CPA_CY_SYM_HASH_AES_GMAC) mode of 199 * operation, this field specifies the length of the AAD data in the 200 * source buffer. 201 * 202 * @note On some implementations, this length may be limited to a 16-bit 203 * value (65535 bytes). 204 */ 205 CpaPhysicalAddr additionalAuthData; 206 /**< Physical address of the Additional Authenticated Data (AAD), 207 * which is needed for authenticated cipher mechanisms (CCM and 208 * GCM), and to the IV for SNOW3G authentication (@ref 209 * CPA_CY_SYM_HASH_SNOW3G_UIA2). For other authentication 210 * mechanisms, this value is ignored, and the field is reserved for 211 * internal usage. 212 * 213 * The length of the data pointed to by this field is set up for 214 * the session in the @ref CpaCySymHashAuthModeSetupData structure 215 * as part of the @ref cpaCySymDpInitSession function call. This length 216 * must not exceed 240 bytes. 217 218 * If AAD is not used, this address must be set to zero. 219 * 220 * Specifically for CCM (@ref CPA_CY_SYM_HASH_AES_CCM) and GCM (@ref 221 * CPA_CY_SYM_HASH_AES_GCM), the caller should be setup as described in 222 * the same way as the corresponding field, pAdditionalAuthData, on the 223 * "traditional" API (see the @ref CpaCySymOpData). 224 * 225 * @note For AES-GMAC (@ref CPA_CY_SYM_HASH_AES_GMAC) mode of 226 * operation, this field is not used and should be set to 0. Instead 227 * the AAD data should be placed in the source buffer. 228 * 229 */ 230 CpaPhysicalAddr digestResult; 231 /**< If the digestIsAppended member of the @ref CpaCySymSessionSetupData 232 * structure is NOT set then this is the physical address of the location 233 * where the digest result should be inserted (in the case of digest 234 * generation) or where the purported digest exists (in the case of digest 235 * verification). 236 * 237 * At session registration time, the client specified the digest result 238 * length with the digestResultLenInBytes member of the @ref 239 * CpaCySymHashSetupData structure. The client must allocate at least 240 * digestResultLenInBytes of physically contiguous memory at this location. 241 * 242 * For digest generation, the digest result will overwrite any data 243 * at this location. 244 * 245 * @note For GCM (@ref CPA_CY_SYM_HASH_AES_GCM), for "digest result" 246 * read "authentication tag T". 247 * 248 * If the digestIsAppended member of the @ref CpaCySymSessionSetupData 249 * structure is set then this value is ignored and the digest result 250 * is understood to be in the destination buffer for digest generation, 251 * and in the source buffer for digest verification. The location of the 252 * digest result in this case is immediately following the region over 253 * which the digest is computed. 254 */ 255 256 CpaInstanceHandle instanceHandle; 257 /**< Instance to which the request is to be enqueued. 258 * @note A callback function must have been registered on the instance 259 * using @ref cpaCySymDpRegCbFunc. 260 */ 261 CpaCySymDpSessionCtx sessionCtx; 262 /**< Session context specifying the cryptographic parameters for this 263 * request. 264 * @note The session must have been created using @ref 265 * cpaCySymDpInitSession. 266 */ 267 Cpa32U ivLenInBytes; 268 /**< Length of valid IV data pointed to by the pIv parameter. 269 * 270 * - For block ciphers in CBC mode, or for Kasumi in F8 mode, or for 271 * SNOW3G in UEA2 mode, this is the length of the IV (which 272 * must be the same as the block length of the cipher). 273 * - For block ciphers in CTR mode, this is the length of the counter 274 * (which must be the same as the block length of the cipher). 275 * - For GCM mode, this is either 12 (for 96-bit IVs) or 16, in which 276 * case pIv points to J0. 277 * - For CCM mode, this is the length of the nonce, which can be in the 278 * range 7 to 13 inclusive. 279 */ 280 CpaPhysicalAddr srcBuffer; 281 /**< Physical address of the source buffer on which to operate. 282 * This is either: 283 * 284 * - The location of the data, of length srcBufferLen; or, 285 * - If srcBufferLen has the special value @ref CPA_DP_BUFLIST, then 286 * srcBuffer contains the location where a @ref CpaPhysBufferList is 287 * stored. In this case, the CpaPhysBufferList MUST be aligned 288 * on an 8-byte boundary. 289 * - For optimum performance, the buffer should only contain the data 290 * region that the cryptographic operation(s) must be performed on. 291 * Any additional data in the source buffer may be copied to the 292 * destination buffer and this copy may degrade performance. 293 */ 294 Cpa32U srcBufferLen; 295 /**< Length of source buffer, or @ref CPA_DP_BUFLIST. */ 296 CpaPhysicalAddr dstBuffer; 297 /**< Physical address of the destination buffer on which to operate. 298 * This is either: 299 * 300 * - The location of the data, of length srcBufferLen; or, 301 * - If srcBufferLen has the special value @ref CPA_DP_BUFLIST, then 302 * srcBuffer contains the location where a @ref CpaPhysBufferList is 303 * stored. In this case, the CpaPhysBufferList MUST be aligned 304 * on an 8-byte boundary. 305 * 306 * For "in-place" operation, the dstBuffer may be identical to the 307 * srcBuffer. 308 */ 309 Cpa32U dstBufferLen; 310 /**< Length of destination buffer, or @ref CPA_DP_BUFLIST. */ 311 312 CpaPhysicalAddr thisPhys; 313 /**< Physical address of this data structure */ 314 315 Cpa8U* pIv; 316 /**< Pointer to (and therefore, the virtual address of) the IV field 317 * above. 318 * Needed here because the driver in some cases writes to this field, 319 * in addition to sending it to the accelerator. 320 */ 321 Cpa8U *pAdditionalAuthData; 322 /**< Pointer to (and therefore, the virtual address of) the 323 * additionalAuthData field above. 324 * Needed here because the driver in some cases writes to this field, 325 * in addition to sending it to the accelerator. 326 */ 327 void* pCallbackTag; 328 /**< Opaque data that will be returned to the client in the function 329 * completion callback. 330 * 331 * This opaque data is not used by the implementation of the API, 332 * but is simply returned as part of the asynchronous response. 333 * It may be used to store information that might be useful when 334 * processing the response later. 335 */ 336 } CpaCySymDpOpData; 337 338 /** 339 ***************************************************************************** 340 * @ingroup cpaCySymDp 341 * Definition of callback function for cryptographic data plane API. 342 * 343 * @description 344 * This is the callback function prototype. The callback function is 345 * registered by the application using the @ref cpaCySymDpRegCbFunc 346 * function call, and called back on completion of asynchronous 347 * requests made via calls to @ref cpaCySymDpEnqueueOp or @ref 348 * cpaCySymDpEnqueueOpBatch. 349 * 350 * @context 351 * This callback function can be executed in a context that DOES NOT 352 * permit sleeping to occur. 353 * @assumptions 354 * None 355 * @sideEffects 356 * None 357 * @reentrant 358 * No 359 * @threadSafe 360 * No 361 * 362 * @param[in] pOpData Pointer to the CpaCySymDpOpData object which 363 * was supplied as part of the original request. 364 * @param[in] status Status of the operation. Valid values are 365 * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and 366 * CPA_STATUS_UNSUPPORTED. 367 * @param[in] verifyResult This parameter is valid when the verifyDigest 368 * option is set in the CpaCySymSessionSetupData 369 * structure. A value of CPA_TRUE indicates that 370 * the compare succeeded. A value of CPA_FALSE 371 * indicates that the compare failed. 372 * 373 * @return 374 * None 375 * @pre 376 * Component has been initialized. 377 * Callback has been registered with @ref cpaCySymDpRegCbFunc. 378 * @post 379 * None 380 * @note 381 * None 382 * @see 383 * cpaCySymDpRegCbFunc 384 *****************************************************************************/ 385 typedef void (*CpaCySymDpCbFunc)(CpaCySymDpOpData *pOpData, 386 CpaStatus status, 387 CpaBoolean verifyResult); 388 389 390 /** 391 ***************************************************************************** 392 * @ingroup cpaCySymDp 393 * Registration of the operation completion callback function. 394 * 395 * @description 396 * This function allows a completion callback function to be registered. 397 * The registered callback function is invoked on completion of 398 * asynchronous requests made via calls to @ref cpaCySymDpEnqueueOp 399 * or @ref cpaCySymDpEnqueueOpBatch. 400 * 401 * If a callback function was previously registered, it is overwritten. 402 * 403 * @context 404 * This is a synchronous function and it cannot sleep. It can be 405 * executed in a context that does not permit sleeping. 406 * @assumptions 407 * None 408 * @sideEffects 409 * None 410 * @reentrant 411 * No 412 * @threadSafe 413 * No 414 * 415 * @param[in] instanceHandle Instance on which the callback function is to be 416 * registered. 417 * @param[in] pSymNewCb Callback function for this instance. 418 419 * @retval CPA_STATUS_SUCCESS Function executed successfully. 420 * @retval CPA_STATUS_FAIL Function failed. 421 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 422 * the request. 423 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 424 * 425 * @pre 426 * Component has been initialized. 427 * @post 428 * None 429 * @note 430 * None 431 * @see 432 * CpaCySymDpCbFunc 433 *****************************************************************************/ 434 CpaStatus cpaCySymDpRegCbFunc(const CpaInstanceHandle instanceHandle, 435 const CpaCySymDpCbFunc pSymNewCb); 436 437 /** 438 ***************************************************************************** 439 * @ingroup cpaCySymDp 440 * Gets the size required to store a session context for the data plane 441 * API. 442 * 443 * @description 444 * This function is used by the client to determine the size of the memory 445 * it must allocate in order to store the session context. This MUST be 446 * called before the client allocates the memory for the session context 447 * and before the client calls the @ref cpaCySymDpInitSession function. 448 * 449 * For a given implementation of this API, it is safe to assume that 450 * cpaCySymDpSessionCtxGetSize() will always return the same size and that 451 * the size will not be different for different setup data parameters. 452 * However, it should be noted that the size may change: 453 * (1) between different implementations of the API (e.g. between software 454 * and hardware implementations or between different hardware 455 * implementations) 456 * (2) between different releases of the same API implementation. 457 * 458 * The size returned by this function is the smallest size needed to 459 * support all possible combinations of setup data parameters. Some 460 * setup data parameter combinations may fit within a smaller session 461 * context size. The alternate cpaCySymDpSessionCtxGetDynamicSize() 462 * function will return the smallest size needed to fit the 463 * provided setup data parameters. 464 * 465 * @context 466 * This is a synchronous function that cannot sleep. It can be 467 * executed in a context that does not permit sleeping. 468 * @assumptions 469 * None 470 * @sideEffects 471 * None 472 * @blocking 473 * No 474 * @reentrant 475 * No 476 * @threadSafe 477 * Yes 478 * 479 * @param[in] instanceHandle Instance handle. 480 * @param[in] pSessionSetupData Pointer to session setup data which 481 * contains parameters which are static 482 * for a given cryptographic session such 483 * as operation type, mechanisms, and keys 484 * for cipher and/or hash operations. 485 * @param[out] pSessionCtxSizeInBytes The amount of memory in bytes required 486 * to hold the Session Context. 487 * 488 * @retval CPA_STATUS_SUCCESS Function executed successfully. 489 * @retval CPA_STATUS_FAIL Function failed. 490 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 491 * @retval CPA_STATUS_RESOURCE Error related to system resources. 492 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 493 * 494 * @pre 495 * The component has been initialized. 496 * @post 497 * None 498 * @note 499 * This is a synchronous function and has no completion callback 500 * associated with it. 501 * @see 502 * CpaCySymSessionSetupData 503 * cpaCySymDpSessionCtxGetDynamicSize() 504 * cpaCySymDpInitSession() 505 *****************************************************************************/ 506 CpaStatus 507 cpaCySymDpSessionCtxGetSize(const CpaInstanceHandle instanceHandle, 508 const CpaCySymSessionSetupData *pSessionSetupData, 509 Cpa32U *pSessionCtxSizeInBytes); 510 511 /** 512 ***************************************************************************** 513 * @ingroup cpaCySymDp 514 * Gets the minimum size required to store a session context for the data 515 * plane API. 516 * 517 * @description 518 * This function is used by the client to determine the smallest size of 519 * the memory it must allocate in order to store the session context. 520 * This MUST be called before the client allocates the memory for the 521 * session context and before the client calls the 522 * @ref cpaCySymDpInitSession function. 523 * 524 * This function is an alternate to cpaCySymDpSessionGetSize(). 525 * cpaCySymDpSessionCtxGetSize() will return a fixed size which is the 526 * minimum memory size needed to support all possible setup data parameter 527 * combinations. cpaCySymDpSessionCtxGetDynamicSize() will return the 528 * minimum memory size needed to support the specific session setup 529 * data parameters provided. This size may be different for different setup 530 * data parameters. 531 * 532 * @context 533 * This is a synchronous function that cannot sleep. It can be 534 * executed in a context that does not permit sleeping. 535 * @assumptions 536 * None 537 * @sideEffects 538 * None 539 * @blocking 540 * No 541 * @reentrant 542 * No 543 * @threadSafe 544 * Yes 545 * 546 * @param[in] instanceHandle Instance handle. 547 * @param[in] pSessionSetupData Pointer to session setup data which 548 * contains parameters which are static 549 * for a given cryptographic session such 550 * as operation type, mechanisms, and keys 551 * for cipher and/or hash operations. 552 * @param[out] pSessionCtxSizeInBytes The amount of memory in bytes required 553 * to hold the Session Context. 554 * 555 * @retval CPA_STATUS_SUCCESS Function executed successfully. 556 * @retval CPA_STATUS_FAIL Function failed. 557 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 558 * @retval CPA_STATUS_RESOURCE Error related to system resources. 559 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 560 * 561 * @pre 562 * The component has been initialized. 563 * @post 564 * None 565 * @note 566 * This is a synchronous function and has no completion callback 567 * associated with it. 568 * @see 569 * CpaCySymSessionSetupData 570 * cpaCySymDpSessionCtxGetSize() 571 * cpaCySymDpInitSession() 572 *****************************************************************************/ 573 CpaStatus 574 cpaCySymDpSessionCtxGetDynamicSize(const CpaInstanceHandle instanceHandle, 575 const CpaCySymSessionSetupData *pSessionSetupData, 576 Cpa32U *pSessionCtxSizeInBytes); 577 578 /** 579 ***************************************************************************** 580 * @ingroup cpaCySymDp 581 * Initialize a session for the symmetric cryptographic data plane API. 582 * 583 * @description 584 * This function is used by the client to initialize an asynchronous 585 * session context for symmetric cryptographic data plane operations. 586 * The returned session context is the handle to the session and needs to 587 * be passed when requesting cryptographic operations to be performed. 588 * 589 * Only sessions created using this function may be used when 590 * invoking functions on this API 591 * 592 * The session can be removed using @ref cpaCySymDpRemoveSession. 593 * 594 * @context 595 * This is a synchronous function and it cannot sleep. It can be 596 * executed in a context that does not permit sleeping. 597 * @assumptions 598 * None 599 * @sideEffects 600 * None 601 * @blocking 602 * No 603 * @reentrant 604 * No 605 * @threadSafe 606 * No 607 * 608 * @param[in] instanceHandle Instance to which the requests will be 609 * submitted. 610 * @param[in] pSessionSetupData Pointer to session setup data which 611 * contains parameters that are static 612 * for a given cryptographic session such 613 * as operation type, algorithm, and keys 614 * for cipher and/or hash operations. 615 * @param[out] sessionCtx Pointer to the memory allocated by the 616 * client to store the session context. This 617 * memory must be physically contiguous, and 618 * its length (in bytes) must be at least as 619 * big as specified by a call to @ref 620 * cpaCySymDpSessionCtxGetSize. This memory 621 * will be initialized with this function. This 622 * value needs to be passed to subsequent 623 * processing calls. 624 * 625 * @retval CPA_STATUS_SUCCESS Function executed successfully. 626 * @retval CPA_STATUS_FAIL Function failed. 627 * @retval CPA_STATUS_RETRY Resubmit the request. 628 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 629 * @retval CPA_STATUS_RESOURCE Error related to system resources. 630 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 631 * the request. 632 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 633 * 634 * @pre 635 * The component has been initialized. 636 * @post 637 * None 638 * @note 639 * This is a synchronous function and has no completion callback 640 * associated with it. 641 * @see 642 * cpaCySymDpSessionCtxGetSize, cpaCySymDpRemoveSession 643 *****************************************************************************/ 644 CpaStatus 645 cpaCySymDpInitSession(CpaInstanceHandle instanceHandle, 646 const CpaCySymSessionSetupData *pSessionSetupData, 647 CpaCySymDpSessionCtx sessionCtx); 648 649 /** 650 ***************************************************************************** 651 * @ingroup cpaCySymDp 652 * Remove (delete) a symmetric cryptographic session for the data plane 653 * API. 654 * 655 * @description 656 * This function will remove a previously initialized session context 657 * and the installed callback handler function. Removal will fail if 658 * outstanding calls still exist for the initialized session handle. 659 * The client needs to retry the remove function at a later time. 660 * The memory for the session context MUST not be freed until this call 661 * has completed successfully. 662 * 663 * @context 664 * This is a synchronous function that cannot sleep. It can be 665 * executed in a context that does not permit sleeping. 666 * @assumptions 667 * None 668 * @sideEffects 669 * None 670 * @blocking 671 * No 672 * @reentrant 673 * No 674 * @threadSafe 675 * No 676 * 677 * @param[in] instanceHandle Instance handle. 678 * @param[in,out] sessionCtx Session context to be removed. 679 * 680 * @retval CPA_STATUS_SUCCESS Function executed successfully. 681 * @retval CPA_STATUS_FAIL Function failed. 682 * @retval CPA_STATUS_RETRY Resubmit the request. 683 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 684 * @retval CPA_STATUS_RESOURCE Error related to system resources. 685 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 686 * the request. 687 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 688 * 689 * @pre 690 * The component has been initialized. 691 * @post 692 * None 693 * @note 694 * Note that this is a synchronous function and has no completion callback 695 * associated with it. 696 * 697 * @see 698 * CpaCySymDpSessionCtx, 699 * cpaCySymDpInitSession() 700 * 701 *****************************************************************************/ 702 CpaStatus 703 cpaCySymDpRemoveSession(const CpaInstanceHandle instanceHandle, 704 CpaCySymDpSessionCtx sessionCtx); 705 706 707 /** 708 ***************************************************************************** 709 * @ingroup cpaCySymDp 710 * Enqueue a single symmetric cryptographic request. 711 * 712 * @description 713 * This function enqueues a single request to perform a cipher, 714 * hash or combined (cipher and hash) operation. Optionally, the 715 * request is also submitted to the cryptographic engine to be 716 * performed. 717 * 718 * See note about performance trade-offs on the @ref cpaCySymDp API. 719 * 720 * The function is asynchronous; control is returned to the user once 721 * the request has been submitted. On completion of the request, the 722 * application may poll for responses, which will cause a callback 723 * function (registered via @ref cpaCySymDpRegCbFunc) to be invoked. 724 * Callbacks within a session are guaranteed to be in the same order 725 * in which they were submitted. 726 * 727 * The following restrictions apply to the pOpData parameter: 728 * 729 * - The memory MUST be aligned on an 8-byte boundary. 730 * - The structure MUST reside in physically contiguous memory. 731 * - The reserved fields of the structure SHOULD NOT be written 732 * or read by the calling code. 733 * 734 * @context 735 * This function will not sleep, and hence can be executed in a context 736 * that does not permit sleeping. 737 * 738 * @sideEffects 739 * None 740 * @blocking 741 * No 742 * @reentrant 743 * No 744 * @threadSafe 745 * No 746 * 747 * @param[in] pOpData Pointer to a structure containing the 748 * request parameters. The client code allocates 749 * the memory for this structure. This component 750 * takes ownership of the memory until it is 751 * returned in the callback, which was registered 752 * on the instance via @ref cpaCySymDpRegCbFunc. 753 * See the above Description for restrictions 754 * that apply to this parameter. 755 * @param[in] performOpNow Flag to specify whether the operation should be 756 * performed immediately (CPA_TRUE), or simply 757 * enqueued to be performed later (CPA_FALSE). 758 * In the latter case, the request is submitted 759 * to be performed either by calling this function 760 * again with this flag set to CPA_TRUE, or by 761 * invoking the function @ref 762 * cpaCySymDpPerformOpNow. 763 * 764 * @retval CPA_STATUS_SUCCESS Function executed successfully. 765 * @retval CPA_STATUS_FAIL Function failed. 766 * @retval CPA_STATUS_RETRY Resubmit the request. 767 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 768 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 769 * the request. 770 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 771 * 772 * @pre 773 * The session identified by pOpData->sessionCtx was setup using 774 * @ref cpaCySymDpInitSession. 775 * The instance identified by pOpData->instanceHandle has had a 776 * callback function registered via @ref cpaCySymDpRegCbFunc. 777 * 778 * @post 779 * None 780 * 781 * @note 782 * A callback of type @ref CpaCySymDpCbFunc is generated in response to 783 * this function call. Any errors generated during processing are 784 * reported as part of the callback status code. 785 * 786 * @see 787 * cpaCySymDpInitSession, 788 * cpaCySymDpPerformOpNow 789 *****************************************************************************/ 790 CpaStatus 791 cpaCySymDpEnqueueOp(CpaCySymDpOpData *pOpData, 792 const CpaBoolean performOpNow); 793 794 795 /** 796 ***************************************************************************** 797 * @ingroup cpaCySymDp 798 * Enqueue multiple requests to the symmetric cryptographic data plane 799 * API. 800 * 801 * @description 802 * This function enqueues multiple requests to perform cipher, hash 803 * or combined (cipher and hash) operations. 804 805 * See note about performance trade-offs on the @ref cpaCySymDp API. 806 * 807 * The function is asynchronous; control is returned to the user once 808 * the request has been submitted. On completion of the request, the 809 * application may poll for responses, which will cause a callback 810 * function (registered via @ref cpaCySymDpRegCbFunc) to be invoked. 811 * Separate callbacks will be invoked for each request. 812 * Callbacks within a session are guaranteed to be in the same order 813 * in which they were submitted. 814 * 815 * The following restrictions apply to each element of the pOpData 816 * array: 817 * 818 * - The memory MUST be aligned on an 8-byte boundary. 819 * - The structure MUST reside in physically contiguous memory. 820 * - The reserved fields of the structure SHOULD NOT be 821 * written or read by the calling code. 822 * 823 * @context 824 * This function will not sleep, and hence can be executed in a context 825 * that does not permit sleeping. 826 * 827 * @assumptions 828 * Client MUST allocate the request parameters to 8 byte alignment. 829 * Reserved elements of the CpaCySymDpOpData structure MUST be 0. 830 * The CpaCySymDpOpData structure MUST reside in physically 831 * contiguous memory. 832 * 833 * @sideEffects 834 * None 835 * @blocking 836 * No 837 * @reentrant 838 * No 839 * @threadSafe 840 * No 841 * 842 * @param[in] numberRequests The number of requests in the array of 843 * CpaCySymDpOpData structures. 844 * @param[in] pOpData An array of pointers to CpaCySymDpOpData 845 * structures. Each of the CpaCySymDpOpData 846 * structure contains the request parameters for 847 * that request. The client code allocates the 848 * memory for this structure. This component takes 849 * ownership of the memory until it is returned in 850 * the callback, which was registered on the 851 * instance via @ref cpaCySymDpRegCbFunc. 852 * See the above Description for restrictions 853 * that apply to this parameter. 854 * @param[in] performOpNow Flag to specify whether the operation should be 855 * performed immediately (CPA_TRUE), or simply 856 * enqueued to be performed later (CPA_FALSE). 857 * In the latter case, the request is submitted 858 * to be performed either by calling this function 859 * again with this flag set to CPA_TRUE, or by 860 * invoking the function @ref 861 * cpaCySymDpPerformOpNow. 862 * 863 * @retval CPA_STATUS_SUCCESS Function executed successfully. 864 * @retval CPA_STATUS_FAIL Function failed. 865 * @retval CPA_STATUS_RETRY Resubmit the request. 866 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 867 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 868 * the request. 869 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 870 * 871 * @pre 872 * The session identified by pOpData[i]->sessionCtx was setup using 873 * @ref cpaCySymDpInitSession. 874 * The instance identified by pOpData->instanceHandle[i] has had a 875 * callback function registered via @ref cpaCySymDpRegCbFunc. 876 * 877 * @post 878 * None 879 * 880 * @note 881 * Multiple callbacks of type @ref CpaCySymDpCbFunc are generated in 882 * response to this function call (one per request). Any errors 883 * generated during processing are reported as part of the callback 884 * status code. 885 * 886 * @see 887 * cpaCySymDpInitSession, 888 * cpaCySymDpEnqueueOp 889 *****************************************************************************/ 890 CpaStatus 891 cpaCySymDpEnqueueOpBatch(const Cpa32U numberRequests, 892 CpaCySymDpOpData *pOpData[], 893 const CpaBoolean performOpNow); 894 895 896 /** 897 ***************************************************************************** 898 * @ingroup cpaCySymDp 899 * Submit any previously enqueued requests to be performed now on the 900 * symmetric cryptographic data plane API. 901 * 902 * @description 903 * If any requests/operations were enqueued via calls to @ref 904 * cpaCySymDpEnqueueOp and/or @ref cpaCySymDpEnqueueOpBatch, but with 905 * the flag performOpNow set to @ref CPA_FALSE, then these operations 906 * will now be submitted to the accelerator to be performed. 907 * 908 * See note about performance trade-offs on the @ref cpaCySymDp API. 909 * 910 * @context 911 * Will not sleep. It can be executed in a context that does not 912 * permit sleeping. 913 * 914 * @sideEffects 915 * None 916 * @blocking 917 * No 918 * @reentrant 919 * No 920 * @threadSafe 921 * No 922 * 923 * @param[in] instanceHandle Instance to which the requests will be 924 * submitted. 925 * 926 * @retval CPA_STATUS_SUCCESS Function executed successfully. 927 * @retval CPA_STATUS_FAIL Function failed. 928 * @retval CPA_STATUS_RETRY Resubmit the request. 929 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 930 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 931 * the request. 932 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 933 * 934 * @pre 935 * The component has been initialized. 936 * A cryptographic session has been previously setup using the 937 * @ref cpaCySymDpInitSession function call. 938 * 939 * @post 940 * None 941 * 942 * @see 943 * cpaCySymDpEnqueueOp, cpaCySymDpEnqueueOpBatch 944 *****************************************************************************/ 945 CpaStatus 946 cpaCySymDpPerformOpNow(CpaInstanceHandle instanceHandle); 947 948 949 #ifdef __cplusplus 950 } /* close the extern "C" { */ 951 #endif 952 953 #endif /* CPA_CY_SYM_DP_H */ 954