lib/librte_jobstats/rte_jobstats.h

   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_ */