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 *****************************************************************************/ 106 CpaStatus 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 *****************************************************************************/ 121 void 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 *****************************************************************************/ 137 void 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 *****************************************************************************/ 154 void 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 *****************************************************************************/ 172 void 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 *****************************************************************************/ 188 void LacSym_StatsShow(CpaInstanceHandle instanceHandle); 189 190 #endif /*LAC_SYM_STATS_H_*/ 191