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