1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2015 Intel Corporation 3 */ 4 5 #ifndef JOBSTATS_H_ 6 #define JOBSTATS_H_ 7 8 #include <stdint.h> 9 10 #include <rte_memory.h> 11 12 #ifdef __cplusplus 13 extern "C" { 14 #endif 15 16 #define RTE_JOBSTATS_NAMESIZE 32 17 18 /* Forward declarations. */ 19 struct rte_jobstats_context; 20 struct rte_jobstats; 21 22 /** 23 * This function should calculate new period and set it using 24 * rte_jobstats_set_period() function. Time spent in this function will be 25 * added to job's runtime. 26 * 27 * @param job 28 * The job data structure handler. 29 * @param job_result 30 * Result of calling job callback. 31 */ 32 typedef void (*rte_job_update_period_cb_t)(struct rte_jobstats *job, 33 int64_t job_result); 34 35 struct __rte_cache_aligned rte_jobstats { 36 uint64_t period; 37 /**< Estimated period of execution. */ 38 39 uint64_t min_period; 40 /**< Minimum period. */ 41 42 uint64_t max_period; 43 /**< Maximum period. */ 44 45 int64_t target; 46 /**< Desired value for this job. */ 47 48 rte_job_update_period_cb_t update_period_cb; 49 /**< Period update callback. */ 50 51 uint64_t exec_time; 52 /**< Total time (sum) that this job was executing. */ 53 54 uint64_t min_exec_time; 55 /**< Minimum execute time. */ 56 57 uint64_t max_exec_time; 58 /**< Maximum execute time. */ 59 60 uint64_t exec_cnt; 61 /**< Execute count. */ 62 63 char name[RTE_JOBSTATS_NAMESIZE]; 64 /**< Name of this job */ 65 66 struct rte_jobstats_context *context; 67 /**< Job stats context object that is executing this job. */ 68 }; 69 70 struct __rte_cache_aligned rte_jobstats_context { 71 /** Variable holding time at different points: 72 * -# loop start time if loop was started but no job executed yet. 73 * -# job start time if job is currently executing. 74 * -# job finish time if job finished its execution. 75 * -# loop finish time if loop finished its execution. */ 76 uint64_t state_time; 77 78 uint64_t loop_executed_jobs; 79 /**< Count of executed jobs in this loop. */ 80 81 /* Statistics start. */ 82 83 uint64_t exec_time; 84 /**< Total time taken to execute jobs, not including management time. */ 85 86 uint64_t min_exec_time; 87 /**< Minimum loop execute time. */ 88 89 uint64_t max_exec_time; 90 /**< Maximum loop execute time. */ 91 92 /** 93 * Sum of time that is not the execute time (ex: from job finish to next 94 * job start). 95 * 96 * This time might be considered as overhead of library + job scheduling. 97 */ 98 uint64_t management_time; 99 100 uint64_t min_management_time; 101 /**< Minimum management time */ 102 103 uint64_t max_management_time; 104 /**< Maximum management time */ 105 106 uint64_t start_time; 107 /**< Time since last reset stats. */ 108 109 uint64_t job_exec_cnt; 110 /**< Total count of executed jobs. */ 111 112 uint64_t loop_cnt; 113 /**< Total count of executed loops with at least one executed job. */ 114 }; 115 116 /** 117 * Initialize given context object with default values. 118 * 119 * @param ctx 120 * Job stats context object to initialize. 121 * 122 * @return 123 * 0 on success 124 * -EINVAL if *ctx* is NULL 125 */ 126 int 127 rte_jobstats_context_init(struct rte_jobstats_context *ctx); 128 129 /** 130 * Mark that new set of jobs start executing. 131 * 132 * @param ctx 133 * Job stats context object. 134 */ 135 void 136 rte_jobstats_context_start(struct rte_jobstats_context *ctx); 137 138 /** 139 * Mark that there is no more jobs ready to execute in this turn. Calculate 140 * stats for this loop turn. 141 * 142 * @param ctx 143 * Job stats context. 144 */ 145 void 146 rte_jobstats_context_finish(struct rte_jobstats_context *ctx); 147 148 /** 149 * Function resets job context statistics. 150 * 151 * @param ctx 152 * Job stats context which statistics will be reset. 153 */ 154 void 155 rte_jobstats_context_reset(struct rte_jobstats_context *ctx); 156 157 /** 158 * Initialize given job stats object. 159 * 160 * @param job 161 * Job object. 162 * @param name 163 * Optional job name. 164 * @param min_period 165 * Minimum period that this job can accept. 166 * @param max_period 167 * Maximum period that this job can accept. 168 * @param initial_period 169 * Initial period. It will be checked against *min_period* and *max_period*. 170 * @param target 171 * Target value that this job try to achieve. 172 * 173 * @return 174 * 0 on success 175 * -EINVAL if *job* is NULL 176 */ 177 int 178 rte_jobstats_init(struct rte_jobstats *job, const char *name, 179 uint64_t min_period, uint64_t max_period, uint64_t initial_period, 180 int64_t target); 181 182 /** 183 * Set job desired target value. Difference between target and job value 184 * value must be used to properly adjust job execute period value. 185 * 186 * @param job 187 * The job object. 188 * @param target 189 * New target. 190 */ 191 void 192 rte_jobstats_set_target(struct rte_jobstats *job, int64_t target); 193 194 /** 195 * Mark that *job* is starting of its execution in context of *ctx* object. 196 * 197 * @param ctx 198 * Job stats context. 199 * @param job 200 * Job object. 201 * @return 202 * 0 on success 203 * -EINVAL if *ctx* or *job* is NULL or *job* is executing in another context 204 * context already, 205 */ 206 int 207 rte_jobstats_start(struct rte_jobstats_context *ctx, struct rte_jobstats *job); 208 209 /** 210 * Mark that *job* finished its execution, but time of this work will be skipped 211 * and added to management time. 212 * 213 * @param job 214 * Job object. 215 * 216 * @return 217 * 0 on success 218 * -EINVAL if job is NULL or job was not started (it have no context). 219 */ 220 int 221 rte_jobstats_abort(struct rte_jobstats *job); 222 223 /** 224 * Mark that *job* finished its execution. Context in which it was executing 225 * will receive stat update. After this function call *job* object is ready to 226 * be executed in other context. 227 * 228 * @param job 229 * Job object. 230 * @param job_value 231 * Job value. Job should pass in this parameter a value that it try to optimize 232 * for example the number of packets it processed. 233 * 234 * @return 235 * 0 if job's period was not updated (job target equals *job_value*) 236 * 1 if job's period was updated 237 * -EINVAL if job is NULL or job was not started (it have no context). 238 */ 239 int 240 rte_jobstats_finish(struct rte_jobstats *job, int64_t job_value); 241 242 /** 243 * Set execute period of given job. 244 * 245 * @param job 246 * The job object. 247 * @param period 248 * New period value. 249 * @param saturate 250 * If zero, skip period saturation to min, max range. 251 */ 252 void 253 rte_jobstats_set_period(struct rte_jobstats *job, uint64_t period, 254 uint8_t saturate); 255 /** 256 * Set minimum execute period of given job. Current period will be checked 257 * against new minimum value. 258 * 259 * @param job 260 * The job object. 261 * @param period 262 * New minimum period value. 263 */ 264 void 265 rte_jobstats_set_min(struct rte_jobstats *job, uint64_t period); 266 /** 267 * Set maximum execute period of given job. Current period will be checked 268 * against new maximum value. 269 * 270 * @param job 271 * The job object. 272 * @param period 273 * New maximum period value. 274 */ 275 void 276 rte_jobstats_set_max(struct rte_jobstats *job, uint64_t period); 277 278 /** 279 * Set update period callback that is invoked after job finish. 280 * 281 * If application wants to do more sophisticated calculations than default 282 * it can provide this handler. 283 * 284 * @param job 285 * Job object. 286 * @param update_period_cb 287 * Callback to set. If NULL restore default update function. 288 */ 289 void 290 rte_jobstats_set_update_period_function(struct rte_jobstats *job, 291 rte_job_update_period_cb_t update_period_cb); 292 293 /** 294 * Function resets job statistics. 295 * 296 * @param job 297 * Job which statistics will be reset. 298 */ 299 void 300 rte_jobstats_reset(struct rte_jobstats *job); 301 302 #ifdef __cplusplus 303 } 304 #endif 305 306 #endif /* JOBSTATS_H_ */ 307