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.h
45 *
46 * @defgroup cpa CPA API
47 *
48 * @description
49 *      This is the top level API definition for Intel(R) QuickAssist Technology.
50 *		It contains structures, data types and definitions that are common
51 *		across the interface.
52 *
53 *****************************************************************************/
54
55/**
56 *****************************************************************************
57 * @defgroup cpa_BaseDataTypes Base Data Types
58 * @file cpa.h
59 *
60 * @ingroup cpa
61 *
62 * @description
63 *      The base data types for the Intel CPA API.
64 *
65 *****************************************************************************/
66
67#ifndef CPA_H
68#define CPA_H
69
70#ifdef __cplusplus
71extern "C" {
72#endif
73
74#include "cpa_types.h"
75
76/**
77 *****************************************************************************
78 * @ingroup cpa_BaseDataTypes
79 *      Instance handle type.
80 *
81 * @description
82 *      Handle used to uniquely identify an instance.
83 *
84 * @note
85 *      Where only a single instantiation exists this field may be set to
86 *      @ref CPA_INSTANCE_HANDLE_SINGLE.
87 *
88 *****************************************************************************/
89typedef void * CpaInstanceHandle;
90
91/**
92 *****************************************************************************
93 * @ingroup cpa_BaseDataTypes
94 *      Default instantiation handle value where there is only a single instance
95 *
96 * @description
97 *      Used as an instance handle value where only one instance exists.
98 *
99 *****************************************************************************/
100#define CPA_INSTANCE_HANDLE_SINGLE ((CpaInstanceHandle)0)
101
102/**
103 *****************************************************************************
104 * @ingroup cpa_BaseDataTypes
105 *      Physical memory address.
106 * @description
107 *      Type for physical memory addresses.
108 *****************************************************************************/
109typedef Cpa64U CpaPhysicalAddr;
110
111/**
112 *****************************************************************************
113 * @ingroup cpa_BaseDataTypes
114 *      Virtual to physical address conversion routine.
115 *
116 * @description
117 *      This function is used to convert virtual addresses to physical
118 *      addresses.
119 *
120 * @context
121 *      The function shall not be called in an interrupt context.
122 * @assumptions
123 *      None
124 * @sideEffects
125 *      None
126 * @blocking
127 *      This function is synchronous and blocking.
128 * @reentrant
129 *      No
130 * @threadSafe
131 *      Yes
132 *
133 * @param[in] pVirtualAddr           Virtual address to be converted.
134 *
135 * @return
136 * 		Returns the corresponding physical address.
137 *      On error, the value NULL is returned.
138 *
139 * @post
140 *      None
141 * @see
142 *      None
143 *
144 *****************************************************************************/
145typedef CpaPhysicalAddr (*CpaVirtualToPhysical)(void * pVirtualAddr);
146
147
148/**
149 *****************************************************************************
150 * @ingroup cpa_BaseDataTypes
151 *      Flat buffer structure containing a pointer and length member.
152 *
153 * @description
154 *      A flat buffer structure. The data pointer, pData, is a virtual address.
155 *      An API instance may require the actual data to be in contiguous
156 *      physical memory as determined by @ref CpaInstanceInfo2.
157 *
158 *****************************************************************************/
159typedef struct _CpaFlatBuffer {
160    Cpa32U dataLenInBytes;
161    /**< Data length specified in bytes.
162     * When used as an input parameter to a function, the length specifies
163     * the current length of the buffer.
164     * When used as an output parameter to a function, the length passed in
165     * specifies the maximum length of the buffer on return (i.e. the allocated
166     * length).  The implementation will not write past this length.  On return,
167     * the length is always unchanged. */
168  Cpa8U *pData;
169    /**< The data pointer is a virtual address, however the actual data pointed
170     * to is required to be in contiguous physical memory unless the field
171     requiresPhysicallyContiguousMemory in CpaInstanceInfo2 is false. */
172} CpaFlatBuffer;
173
174/**
175 *****************************************************************************
176 * @ingroup cpa_BaseDataTypes
177 *      Scatter/Gather buffer list containing an array of flat buffers.
178 *
179 * @description
180 *      A scatter/gather buffer list structure.  This buffer structure is
181 *      typically used to represent a region of memory which is not
182 *      physically contiguous, by describing it as a collection of
183 *      buffers, each of which is physically contiguous.
184 *
185 * @note
186 *      The memory for the pPrivateMetaData member must be allocated
187 *      by the client as physically contiguous memory.  When allocating
188 *      memory for pPrivateMetaData, a call to the corresponding
189 *      BufferListGetMetaSize function (e.g. cpaCyBufferListGetMetaSize)
190 *      MUST be made to determine the size of the Meta Data Buffer.  The
191 *      returned size (in bytes) may then be passed in a memory allocation
192 *      routine to allocate the pPrivateMetaData memory.
193 *****************************************************************************/
194typedef struct _CpaBufferList {
195    Cpa32U numBuffers;
196    /**< Number of buffers in the list */
197    CpaFlatBuffer *pBuffers;
198    /**< Pointer to an unbounded array containing the number of CpaFlatBuffers
199     * defined by numBuffers
200     */
201    void *pUserData;
202    /**< This is an opaque field that is not read or modified internally. */
203    void *pPrivateMetaData;
204    /**< Private representation of this buffer list.  The memory for this
205     * buffer needs to be allocated by the client as contiguous data.
206     * The amount of memory required is returned with a call to
207     * the corresponding BufferListGetMetaSize function. If that function
208     * returns a size of zero then no memory needs to be allocated, and this
209     * parameter can be NULL.
210     */
211} CpaBufferList;
212
213/**
214 *****************************************************************************
215 * @ingroup cpa_BaseDataTypes
216 *      Flat buffer structure with physical address.
217 *
218 * @description
219 *      Functions taking this structure do not need to do any virtual to
220 *      physical address translation before writing the buffer to hardware.
221 *****************************************************************************/
222typedef struct _CpaPhysFlatBuffer {
223    Cpa32U dataLenInBytes;
224    /**< Data length specified in bytes.
225     * When used as an input parameter to a function, the length specifies
226     * the current length of the buffer.
227     * When used as an output parameter to a function, the length passed in
228     * specifies the maximum length of the buffer on return (i.e. the allocated
229     * length).  The implementation will not write past this length.  On return,
230     * the length is always unchanged.
231     */
232    Cpa32U reserved;
233    /**< Reserved for alignment */
234    CpaPhysicalAddr bufferPhysAddr;
235    /**< The physical address at which the data resides.  The data pointed
236     * to is required to be in contiguous physical memory.
237     */
238} CpaPhysFlatBuffer;
239
240/**
241 *****************************************************************************
242 * @ingroup cpa_BaseDataTypes
243 *      Scatter/gather list containing an array of flat buffers with
244 *      physical addresses.
245 *
246 * @description
247 *      Similar to @ref CpaBufferList, this buffer structure is typically
248 *      used to represent a region of memory which is not physically
249 *      contiguous, by describing it as a collection of buffers, each of
250 *      which is physically contiguous.  The difference is that, in this
251 *      case, the individual "flat" buffers are represented using
252 *      physical, rather than virtual, addresses.
253 *****************************************************************************/
254typedef struct _CpaPhysBufferList {
255    Cpa64U reserved0;
256    /**< Reserved for internal usage */
257    Cpa32U numBuffers;
258    /**< Number of buffers in the list */
259    Cpa32U reserved1;
260    /**< Reserved for alignment */
261    CpaPhysFlatBuffer flatBuffers[];
262    /**< Array of flat buffer structures, of size numBuffers */
263} CpaPhysBufferList;
264
265
266/**
267 *****************************************************************************
268 * @ingroup cpa_BaseDataTypes
269 *      Special value which can be taken by length fields on some of the
270 *      "data plane" APIs to indicate that the buffer in question is of
271 *      type CpaPhysBufferList, rather than simply an array of bytes.
272 ****************************************************************************/
273#define CPA_DP_BUFLIST ((Cpa32U)0xFFFFFFFF)
274
275
276/**
277 *****************************************************************************
278 * @ingroup cpa_BaseDataTypes
279 *      API status value type definition
280 *
281 * @description
282 *      This type definition is used for the return values used in all the
283 *      API functions.  Common values are defined, for example see
284 *      @ref CPA_STATUS_SUCCESS, @ref CPA_STATUS_FAIL, etc.
285 *****************************************************************************/
286typedef Cpa32S CpaStatus;
287
288#define CPA_STATUS_SUCCESS (0)
289/**<
290 *  @ingroup cpa_BaseDataTypes
291 *   Success status value. */
292#define CPA_STATUS_FAIL (-1)
293/**<
294 *  @ingroup cpa_BaseDataTypes
295 *   Fail status value. */
296#define CPA_STATUS_RETRY (-2)
297/**<
298 *  @ingroup cpa_BaseDataTypes
299 *  Retry status value. */
300#define CPA_STATUS_RESOURCE (-3)
301/**<
302 *  @ingroup cpa_BaseDataTypes
303 *  The resource that has been requested is unavailable. Refer
304 *  to relevant sections of the API for specifics on what the suggested
305 *  course of action is. */
306#define CPA_STATUS_INVALID_PARAM (-4)
307/**<
308 *  @ingroup cpa_BaseDataTypes
309 *  Invalid parameter has been passed in. */
310#define CPA_STATUS_FATAL (-5)
311/**<
312 *  @ingroup cpa_BaseDataTypes
313 *  A serious error has occurred. Recommended course of action
314 *  is to shutdown and restart the component. */
315#define CPA_STATUS_UNSUPPORTED (-6)
316/**<
317 *  @ingroup cpa_BaseDataTypes
318 *  The function is not supported, at least not with the specific
319 *  parameters supplied.  This may be because a particular
320 *  capability is not supported by the current implementation. */
321#define CPA_STATUS_RESTARTING (-7)
322/**<
323 *  @ingroup cpa_BaseDataTypes
324 *  The API implementation is restarting. This may be reported if, for example,
325 *  a hardware implementation is undergoing a reset. Recommended course of
326 *  action is to retry the request. */
327
328/**
329 *****************************************************************************
330 * @ingroup cpa_BaseDataTypes
331 *      API status string type definition
332 * @description
333 *      This type definition is used for the generic status text strings
334 *      provided by cpaXxGetStatusText API functions.  Common values are
335 *      defined, for example see @ref CPA_STATUS_STR_SUCCESS,
336 *      @ref CPA_STATUS_FAIL, etc., as well as the maximum size
337 *      @ref CPA_STATUS_MAX_STR_LENGTH_IN_BYTES.
338 *****************************************************************************/
339#define CPA_STATUS_MAX_STR_LENGTH_IN_BYTES (255)
340/**<
341 *  @ingroup cpa_BaseDataTypes
342 *   Maximum length of the Overall Status String (including generic and specific
343 *   strings returned by calls to cpaXxGetStatusText) */
344
345#define CPA_STATUS_STR_SUCCESS       ("Operation was successful:")
346/**<
347 *  @ingroup cpa_BaseDataTypes
348 *   Status string for @ref CPA_STATUS_SUCCESS. */
349#define CPA_STATUS_STR_FAIL          ("General or unspecified error occurred:")
350/**<
351 *  @ingroup cpa_BaseDataTypes
352 *   Status string for @ref CPA_STATUS_FAIL. */
353#define CPA_STATUS_STR_RETRY         ("Recoverable error occurred:")
354/**<
355 *  @ingroup cpa_BaseDataTypes
356 *   Status string for @ref CPA_STATUS_RETRY. */
357#define CPA_STATUS_STR_RESOURCE      ("Required resource unavailable:")
358/**<
359 *  @ingroup cpa_BaseDataTypes
360 *   Status string for @ref CPA_STATUS_RESOURCE. */
361#define CPA_STATUS_STR_INVALID_PARAM ("Invalid parameter supplied:")
362/**<
363 *  @ingroup cpa_BaseDataTypes
364 *   Status string for @ref CPA_STATUS_INVALID_PARAM. */
365#define CPA_STATUS_STR_FATAL         ("Fatal error has occurred:")
366/**<
367 *  @ingroup cpa_BaseDataTypes
368 *   Status string for @ref CPA_STATUS_FATAL. */
369#define CPA_STATUS_STR_UNSUPPORTED   ("Operation not supported:")
370/**<
371 *  @ingroup cpa_BaseDataTypes
372 *   Status string for @ref CPA_STATUS_UNSUPPORTED. */
373
374/**
375 *****************************************************************************
376 * @ingroup cpa_BaseDataTypes
377 *      Instance Types
378 *
379 * @deprecated
380 * 		As of v1.3 of the Crypto API, this enum has been deprecated,
381 * 		replaced by @ref CpaAccelerationServiceType.
382 *
383 * @description
384 *      Enumeration of the different instance types.
385 *
386 *****************************************************************************/
387typedef enum _CpaInstanceType
388{
389    CPA_INSTANCE_TYPE_CRYPTO = 0,
390    /**< Cryptographic instance type */
391    CPA_INSTANCE_TYPE_DATA_COMPRESSION,
392    /**< Data compression instance type */
393    CPA_INSTANCE_TYPE_RAID,
394    /**< RAID instance type */
395    CPA_INSTANCE_TYPE_XML,
396    /**< XML instance type */
397    CPA_INSTANCE_TYPE_REGEX
398    /**< Regular Expression instance type */
399} CpaInstanceType CPA_DEPRECATED;
400
401/**
402 *****************************************************************************
403 * @ingroup cpa_BaseDataTypes
404 *      Service Type
405 * @description
406 *      Enumeration of the different service types.
407 *
408 *****************************************************************************/
409typedef enum _CpaAccelerationServiceType
410{
411    CPA_ACC_SVC_TYPE_CRYPTO = CPA_INSTANCE_TYPE_CRYPTO,
412    /**< Cryptography */
413    CPA_ACC_SVC_TYPE_DATA_COMPRESSION = CPA_INSTANCE_TYPE_DATA_COMPRESSION,
414    /**< Data Compression */
415    CPA_ACC_SVC_TYPE_PATTERN_MATCH = CPA_INSTANCE_TYPE_REGEX,
416    /**< Pattern Match */
417    CPA_ACC_SVC_TYPE_RAID = CPA_INSTANCE_TYPE_RAID,
418    /**< RAID */
419    CPA_ACC_SVC_TYPE_XML = CPA_INSTANCE_TYPE_XML,
420    /**< XML */
421    CPA_ACC_SVC_TYPE_VIDEO_ANALYTICS,
422    /**< Video Analytics */
423    CPA_ACC_SVC_TYPE_CRYPTO_ASYM,
424    /**< Cryptography - Asymmetric service */
425    CPA_ACC_SVC_TYPE_CRYPTO_SYM
426    /**< Cryptography - Symmetric service */
427} CpaAccelerationServiceType;
428
429/**
430 *****************************************************************************
431 * @ingroup cpa_BaseDataTypes
432 *      Instance State
433 *
434 * @deprecated
435 *      As of v1.3 of the Crypto API, this enum has been deprecated,
436 *      replaced by @ref CpaOperationalState.
437 *
438 * @description
439 *      Enumeration of the different instance states that are possible.
440 *
441 *****************************************************************************/
442typedef enum _CpaInstanceState
443{
444    CPA_INSTANCE_STATE_INITIALISED = 0,
445    /**< Instance is in the initialized state and ready for use. */
446    CPA_INSTANCE_STATE_SHUTDOWN
447    /**< Instance is in the shutdown state and not available for use. */
448} CpaInstanceState CPA_DEPRECATED;
449
450/**
451 *****************************************************************************
452 * @ingroup cpa_BaseDataTypes
453 *      Instance operational state
454 * @description
455 *      Enumeration of the different operational states that are possible.
456 *
457 *****************************************************************************/
458typedef enum _CpaOperationalState
459{
460    CPA_OPER_STATE_DOWN= 0,
461    /**< Instance is not available for use. May not yet be initialized,
462     * or stopped. */
463    CPA_OPER_STATE_UP
464    /**< Instance is available for use. Has been initialized and started. */
465} CpaOperationalState;
466
467#define CPA_INSTANCE_MAX_NAME_SIZE_IN_BYTES 64
468/**<
469 *  @ingroup cpa_BaseDataTypes
470 *  Maximum instance info name string length in bytes */
471#define CPA_INSTANCE_MAX_ID_SIZE_IN_BYTES 128
472/**<
473 *  @ingroup cpa_BaseDataTypes
474 *  Maximum instance info id string length in bytes */
475#define CPA_INSTANCE_MAX_VERSION_SIZE_IN_BYTES 64
476/**<
477 *  @ingroup cpa_BaseDataTypes
478 * Maximum instance info version string length in bytes */
479
480/**
481 *****************************************************************************
482 * @ingroup cpa_BaseDataTypes
483 *      Instance Info Structure
484 *
485 * @deprecated
486 * 		As of v1.3 of the Crypto API, this structure has been deprecated,
487 * 		replaced by CpaInstanceInfo2.
488 *
489 * @description
490 *      Structure that contains the information to describe the instance.
491 *
492 *****************************************************************************/
493typedef struct _CpaInstanceInfo {
494    enum _CpaInstanceType type;
495    /**< Type definition for this instance. */
496    enum _CpaInstanceState state;
497    /**< Operational state of the instance. */
498    Cpa8U name[CPA_INSTANCE_MAX_NAME_SIZE_IN_BYTES];
499    /**< Simple text string identifier for the instance. */
500    Cpa8U version[CPA_INSTANCE_MAX_VERSION_SIZE_IN_BYTES];
501    /**< Version string. There may be multiple versions of the same type of
502     * instance accessible through a particular library. */
503} CpaInstanceInfo CPA_DEPRECATED;
504
505/**
506 *****************************************************************************
507 * @ingroup cpa_BaseDataTypes
508 *      Physical Instance ID
509 * @description
510 *      Identifies the physical instance of an accelerator execution
511 *      engine.
512 *
513 *      Accelerators grouped into "packages".  Each accelerator can in
514 *      turn contain one or more execution engines.  Implementations of
515 *      this API will define the packageId, acceleratorId,
516 *      executionEngineId and busAddress as appropriate for the
517 *      implementation.  For example, for hardware-based accelerators,
518 *      the packageId might identify the chip, which might contain
519 *      multiple accelerators, each of which might contain multiple
520 *      execution engines. The combination of packageId, acceleratorId
521 *      and executionEngineId uniquely identifies the instance.
522 *
523 *      Hardware based accelerators implementing this API may also provide
524 *      information on the location of the accelerator in the busAddress
525 *      field. This field will be defined as appropriate for the
526 *      implementation. For example, for PCIe attached accelerators,
527 *      the busAddress may contain the PCIe bus, device and function
528 *      number of the accelerators.
529 *
530 *****************************************************************************/
531typedef struct _CpaPhysicalInstanceId {
532    Cpa16U packageId;
533    /**< Identifies the package within which the accelerator is
534     * contained. */
535    Cpa16U acceleratorId;
536    /**< Identifies the specific accelerator within the package. */
537    Cpa16U executionEngineId;
538    /**< Identifies the specific execution engine within the
539     * accelerator. */
540    Cpa16U busAddress;
541    /**< Identifies the bus address associated with the accelerator
542     * execution engine. */
543    Cpa32U kptAcHandle;
544    /**< Identifies the achandle of the accelerator. */
545} CpaPhysicalInstanceId;
546
547/**
548 *****************************************************************************
549 * @ingroup cpa_BaseDataTypes
550 *      Instance Info Structure, version 2
551 * @description
552 *      Structure that contains the information to describe the instance.
553 *
554 *****************************************************************************/
555typedef struct _CpaInstanceInfo2 {
556    CpaAccelerationServiceType accelerationServiceType;
557    /**< Type of service provided by this instance. */
558#define CPA_INST_VENDOR_NAME_SIZE CPA_INSTANCE_MAX_NAME_SIZE_IN_BYTES
559    /**< Maximum length of the vendor name. */
560    Cpa8U vendorName[CPA_INST_VENDOR_NAME_SIZE];
561    /**< String identifying the vendor of the accelerator. */
562
563#define CPA_INST_PART_NAME_SIZE CPA_INSTANCE_MAX_NAME_SIZE_IN_BYTES
564    /**< Maximum length of the part name. */
565    Cpa8U partName[CPA_INST_PART_NAME_SIZE];
566    /**< String identifying the part (name and/or number). */
567
568#define CPA_INST_SW_VERSION_SIZE CPA_INSTANCE_MAX_VERSION_SIZE_IN_BYTES
569    /**< Maximum length of the software version string. */
570    Cpa8U swVersion[CPA_INST_SW_VERSION_SIZE];
571    /**< String identifying the version of the software associated with
572     * the instance.  For hardware-based implementations of the API,
573     * this should be the driver version.  For software-based
574     * implementations of the API, this should be the version of the
575     * library.
576     *
577     * Note that this should NOT be used to store the version of the
578     * API, nor should it be used to report the hardware revision
579     * (which can be captured as part of the @ref partName, if required). */
580
581#define CPA_INST_NAME_SIZE CPA_INSTANCE_MAX_NAME_SIZE_IN_BYTES
582    /**< Maximum length of the instance name. */
583    Cpa8U instName[CPA_INST_NAME_SIZE];
584    /**< String identifying the name of the instance. */
585
586#define CPA_INST_ID_SIZE CPA_INSTANCE_MAX_ID_SIZE_IN_BYTES
587    Cpa8U instID[CPA_INST_ID_SIZE];
588    /**< String containing a unique identifier for the instance */
589
590    CpaPhysicalInstanceId physInstId;
591    /**< Identifies the "physical instance" of the accelerator. */
592
593#define CPA_MAX_CORES 4096
594    /**< Maximum number of cores to support in the coreAffinity bitmap. */
595    CPA_BITMAP(coreAffinity, CPA_MAX_CORES);
596    /**< A bitmap identifying the core or cores to which the instance
597     * is affinitized in an SMP operating system.
598     *
599     * The term core here is used to mean a "logical" core - for example,
600     * in a dual-processor, quad-core system with hyperthreading (two
601     * threads per core), there would be 16 such cores (2 processors x
602     * 4 cores/processor x 2 threads/core).  The numbering of these cores
603     * and the corresponding bit positions is OS-specific.  Note that Linux
604     * refers to this as "processor affinity" or "CPU affinity", and refers
605     * to the bitmap as a "cpumask".
606     *
607     * The term "affinity" is used to mean that this is the core on which
608     * the callback function will be invoked when using the asynchronous
609     * mode of the API.  In a hardware-based implementation of the API,
610     * this might be the core to which the interrupt is affinitized.
611     * In a software-based implementation, this might be the core to which
612     * the process running the algorithm is affinitized.  Where there is
613     * no affinity, the bitmap can be set to all zeroes.
614     *
615     * This bitmap should be manipulated using the macros @ref
616     * CPA_BITMAP_BIT_SET, @ref CPA_BITMAP_BIT_CLEAR and @ref
617     * CPA_BITMAP_BIT_TEST. */
618
619    Cpa32U nodeAffinity;
620    /**< Identifies the processor complex, or node, to which the accelerator
621     * is physically connected, to help identify locality in NUMA systems.
622     *
623     * The values taken by this attribute will typically be in the range
624     * 0..n-1, where n is the number of nodes (processor complexes) in the
625     * system.  For example, in a dual-processor configuration, n=2.  The
626     * precise values and their interpretation are OS-specific. */
627
628    CpaOperationalState operState;
629    /**< Operational state of the instance. */
630    CpaBoolean requiresPhysicallyContiguousMemory;
631    /**< Specifies whether the data pointed to by flat buffers
632     * (CpaFlatBuffer::pData) supplied to this instance must be in
633     * physically contiguous memory. */
634    CpaBoolean isPolled;
635    /**< Specifies whether the instance must be polled, or is event driven.
636     * For hardware accelerators, the alternative to polling would be
637     * interrupts. */
638    CpaBoolean isOffloaded;
639    /**< Identifies whether the instance uses hardware offload, or is a
640     * software-only implementation. */
641} CpaInstanceInfo2;
642
643/**
644 *****************************************************************************
645 * @ingroup cpa_BaseDataTypes
646 *      Instance Events
647 * @description
648 *      Enumeration of the different events that will cause the registered
649 *  Instance notification callback function to be invoked.
650 *
651 *****************************************************************************/
652typedef enum _CpaInstanceEvent
653{
654    CPA_INSTANCE_EVENT_RESTARTING = 0,
655    /**< Event type that triggers the registered instance notification callback
656     * function when and instance is restarting. The reason why an instance is
657     * restarting is implementation specific. For example a hardware
658     * implementation may send this event if the hardware device is about to
659     * be reset.
660     */
661    CPA_INSTANCE_EVENT_RESTARTED,
662    /**< Event type that triggers the registered instance notification callback
663     * function when and instance has restarted. The reason why an instance has
664     * restarted is implementation specific. For example a hardware
665     * implementation may send this event after the hardware device has
666     * been reset.
667     */
668    CPA_INSTANCE_EVENT_FATAL_ERROR
669    /**< Event type that triggers the registered instance notification callback
670     * function when an error has been detected that requires the device
671     * to be reset.
672     * This event will be sent by all instances using the device, both on the
673     * host and guests.
674     */
675} CpaInstanceEvent;
676
677/*****************************************************************************/
678/* CPA Instance Management Functions                                         */
679/*****************************************************************************/
680/**
681 *****************************************************************************
682 * @file cpa.h
683 * @ingroup cpa
684 *      Get the number of Acceleration Service instances that are supported by
685 *      the API implementation.
686 *
687 * @description
688 *     This function will get the number of instances that are supported
689 *     for the required Acceleration Service by an implementation of the CPA
690 *     API. This number is then used to determine the size of the array that
691 *     must be passed to @ref cpaGetInstances().
692 *
693 * @context
694 *      This function MUST NOT be called from an interrupt context as it MAY
695 *      sleep.
696 * @assumptions
697 *      None
698 * @sideEffects
699 *      None
700 * @blocking
701 *      This function is synchronous and blocking.
702 * @reentrant
703 *      No
704 * @threadSafe
705 *      Yes
706 *
707 * @param[in]  accelerationServiceType    Acceleration Service required
708 * @param[out] pNumInstances              Pointer to where the number of
709 *                                        instances will be written.
710 *
711 * @retval CPA_STATUS_SUCCESS        Function executed successfully.
712 * @retval CPA_STATUS_FAIL           Function failed.
713 * @retval CPA_STATUS_INVALID_PARAM  Invalid parameter passed in.
714 * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
715 *
716 * @pre
717 *      None
718 * @post
719 *      None
720 * @note
721 *      This function operates in a synchronous manner and no asynchronous
722 *      callback will be generated
723 *
724 * @see
725 *      cpaGetInstances
726 *
727 *****************************************************************************/
728CpaStatus
729cpaGetNumInstances(
730        const CpaAccelerationServiceType accelerationServiceType,
731        Cpa16U *pNumInstances);
732
733/**
734 *****************************************************************************
735 * @file cpa.h
736 * @ingroup cpa
737 *      Get the handles to the required Acceleration Service instances that are
738 *      supported by the API implementation.
739 *
740 * @description
741 *      This function will return handles to the required Acceleration Service
742 *      instances that are supported by an implementation of the CPA API. These
743 *      instance handles can then be used as input parameters with other
744 *      API functions.
745 *
746 *      This function will populate an array that has been allocated by the
747 *      caller. The size of this array will have been determined by the
748 *      cpaGetNumInstances() function.
749 *
750 * @context
751 *      This function MUST NOT be called from an interrupt context as it MAY
752 *      sleep.
753 * @assumptions
754 *      None
755 * @sideEffects
756 *      None
757 * @blocking
758 *      This function is synchronous and blocking.
759 * @reentrant
760 *      No
761 * @threadSafe
762 *      Yes
763 *
764 * @param[in]  accelerationServiceType   Acceleration Service requested
765 * @param[in]  numInstances              Size of the array. If the value is
766 *                                       greater than the number of instances
767 *                                       supported, then an error (@ref
768 *                                       CPA_STATUS_INVALID_PARAM) is returned.
769 * @param[in,out] cpaInstances           Pointer to where the instance
770 *                                       handles will be written.
771 *
772 * @retval CPA_STATUS_SUCCESS        Function executed successfully.
773 * @retval CPA_STATUS_FAIL           Function failed.
774 * @retval CPA_STATUS_INVALID_PARAM  Invalid parameter passed in.
775 * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
776 *
777 * @pre
778 *      None
779 * @post
780 *      None
781 * @note
782 *      This function operates in a synchronous manner and no asynchronous
783 *      callback will be generated
784 *
785 * @see
786 *      cpaGetNumInstances
787 *
788 *****************************************************************************/
789CpaStatus
790cpaGetInstances(
791        const CpaAccelerationServiceType accelerationServiceType,
792        Cpa16U numInstances,
793        CpaInstanceHandle *cpaInstances);
794
795#ifdef __cplusplus
796} /* close the extern "C" { */
797#endif
798
799#endif /* CPA_H */
800