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