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