1/* SPDX-License-Identifier: BSD-3-Clause */
2/* Copyright(c) 2007-2022 Intel Corporation */
3
4/**
5 ***************************************************************************
6 * @file lac_sym_stats.h
7 *
8 * @defgroup LacSymCommon Symmetric Common
9 *
10 * @ingroup LacSym
11 *
12 * Symetric Common consists of common statistics, buffer and partial packet
13 * functionality.
14 *
15 ***************************************************************************/
16
17/**
18 ***************************************************************************
19 * @defgroup LacSymStats Statistics
20 *
21 * @ingroup LacSymCommon
22 *
23 * definitions and prototypes for LAC symmetric statistics.
24 *
25 * @lld_start
26 *      In the LAC API the stats fields are defined as Cpa32U but
27 *      QatUtilsAtomic is the type that the atomic API supports. Therefore we
28 *      need to define a structure internally with the same fields as the API
29 *      stats structure, but each field must be of type QatUtilsAtomic.
30 *
31 *      - <b>Incrementing Statistics:</b>\n
32 *      Atomically increment the statistic on the internal stats structure.
33 *
34 *      - <b>Providing a copy of the stats back to the user:</b>\n
35 *      Use atomicGet to read the atomic variable for each stat field in the
36 *      local internal stat structure. These values are saved in structure
37 *      (as defined by the LAC API) that the client will provide a pointer
38 *      to as a parameter.
39 *
40 *      - <b>Stats Show:</b>\n
41 *      Use atomicGet to read the atomic variables for each field in the local
42 *      internal stat structure and print to the screen
43 *
44 *      - <b>Stats Array:</b>\n
45 *      A macro is used to get the offset off the stat in the structure. This
46 *      offset is passed to a function which uses it to increment the stat
47 *      at that offset.
48 *
49 * @lld_end
50 *
51 ***************************************************************************/
52
53/***************************************************************************/
54
55#ifndef LAC_SYM_STATS_H
56#define LAC_SYM_STATS_H
57
58/*
59******************************************************************************
60* Include public/global header files
61******************************************************************************
62*/
63
64#include "cpa.h"
65#include "cpa_cy_sym.h"
66#include "cpa_cy_common.h"
67
68/*
69*******************************************************************************
70* Include private header files
71*******************************************************************************
72*/
73
74/**
75*******************************************************************************
76* @ingroup LacSymStats
77*      increment a symmetric statistic
78*
79* @description
80*      Increment the statistics
81*
82* @param statistic  IN The field in the symmetric statistics structure to be
83*                      incremented
84* @param instanceHandle  IN engine Id Number
85*
86* @retval None
87*
88*****************************************************************************/
89#define LAC_SYM_STAT_INC(statistic, instanceHandle)                            \
90	LacSym_StatsInc(offsetof(CpaCySymStats64, statistic), instanceHandle)
91
92/**
93*******************************************************************************
94* @ingroup LacSymStats
95*      initialises the symmetric stats
96*
97* @description
98*      This function allocates and initialises the stats array to 0
99*
100* @param instanceHandle    Instance Handle
101*
102* @retval CPA_STATUS_SUCCESS   initialisation successful
103* @retval CPA_STATUS_RESOURCE  array allocation failed
104*
105*****************************************************************************/
106CpaStatus LacSym_StatsInit(CpaInstanceHandle instanceHandle);
107
108/**
109*******************************************************************************
110* @ingroup LacSymStats
111*      Frees the symmetric stats
112*
113* @description
114*      This function frees the stats array
115*
116* @param instanceHandle    Instance Handle
117*
118* @retval None
119*
120*****************************************************************************/
121void LacSym_StatsFree(CpaInstanceHandle instanceHandle);
122
123/**
124*******************************************************************************
125* @ingroup LacSymStats
126*      Inrement a stat
127*
128* @description
129*      This function incrementes a stat for a specific engine.
130*
131* @param offset     IN  offset of stat field in structure
132* @param instanceHandle  IN  qat Handle
133*
134* @retval None
135*
136*****************************************************************************/
137void LacSym_StatsInc(Cpa32U offset, CpaInstanceHandle instanceHandle);
138
139/**
140*******************************************************************************
141* @ingroup LacSymStats
142*      Copy the contents of the statistics structure for an engine
143*
144* @description
145*      This function copies the 32bit symmetric statistics structure for
146*      a specific engine into an address supplied as a parameter.
147*
148* @param instanceHandle  IN     engine Id Number
149* @param pSymStats  OUT stats structure to copy the stats for the into
150*
151* @retval None
152*
153*****************************************************************************/
154void LacSym_Stats32CopyGet(CpaInstanceHandle instanceHandle,
155			   struct _CpaCySymStats *const pSymStats);
156
157/**
158*******************************************************************************
159* @ingroup LacSymStats
160*      Copy the contents of the statistics structure for an engine
161*
162* @description
163*      This function copies the 64bit symmetric statistics structure for
164*      a specific engine into an address supplied as a parameter.
165*
166* @param instanceHandle  IN     engine Id Number
167* @param pSymStats  OUT stats structure to copy the stats for the into
168*
169* @retval None
170*
171*****************************************************************************/
172void LacSym_Stats64CopyGet(CpaInstanceHandle instanceHandle,
173			   CpaCySymStats64 *const pSymStats);
174
175/**
176*******************************************************************************
177* @ingroup LacSymStats
178*      print the symmetric stats to standard output
179*
180* @description
181*      The statistics for symmetric are printed to standard output.
182*
183* @retval None
184*
185* @see LacSym_StatsCopyGet()
186*
187*****************************************************************************/
188void LacSym_StatsShow(CpaInstanceHandle instanceHandle);
189
190#endif /*LAC_SYM_STATS_H_*/
191