lib/librte_jobstats/rte_jobstats.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright(c) 2015 Intel Corporation. All rights reserved.
   5  *   All rights reserved.
   6  *
   7  *   Redistribution and use in source and binary forms, with or without
   8  *   modification, are permitted provided that the following conditions
   9  *   are met:
  10  *
  11  *     * Redistributions of source code must retain the above copyright
  12  *       notice, this list of conditions and the following disclaimer.
  13  *     * Redistributions in binary form must reproduce the above copyright
  14  *       notice, this list of conditions and the following disclaimer in
  15  *       the documentation and/or other materials provided with the
  16  *       distribution.
  17  *     * Neither the name of Intel Corporation nor the names of its
  18  *       contributors may be used to endorse or promote products derived
  19  *       from this software without specific prior written permission.
  20  *
  21  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  24  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  25  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  26  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  27  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  31  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32  */
  33
  34 #ifndef JOBSTATS_H_
  35 #define JOBSTATS_H_
  36
  37 #include <stdint.h>
  38
  39 #include <rte_memory.h>
  40 #include <rte_memcpy.h>
  41
  42 #ifdef __cplusplus
  43 extern "C" {
  44 #endif
  45
  46 #define RTE_JOBSTATS_NAMESIZE 32
  47
  48 /* Forward declarations. */
  49 struct rte_jobstats_context;
  50 struct rte_jobstats;
  51
  52 /**
  53  * This function should calculate new period and set it using
  54  * rte_jobstats_set_period() function. Time spent in this function will be
  55  * added to job's runtime.
  56  *
  57  * @param job
  58  *  The job data structure handler.
  59  * @param job_result
  60  *  Result of calling job callback.
  61  */
  62 typedef void (*rte_job_update_period_cb_t)(struct rte_jobstats *job,
  63                 int64_t job_result);
  64
  65 struct rte_jobstats {
  66         uint64_t period;
  67         /**< Estimated period of execution. */
  68
  69         uint64_t min_period;
  70         /**< Minimum period. */
  71
  72         uint64_t max_period;
  73         /**< Maximum period. */
  74
  75         int64_t target;
  76         /**< Desired value for this job. */
  77
  78         rte_job_update_period_cb_t update_period_cb;
  79         /**< Period update callback. */
  80
  81         uint64_t exec_time;
  82         /**< Total time (sum) that this job was executing. */
  83
  84         uint64_t min_exec_time;
  85         /**< Minimum execute time. */
  86
  87         uint64_t max_exec_time;
  88         /**< Maximum execute time. */
  89
  90         uint64_t exec_cnt;
  91         /**< Execute count. */
  92
  93         char name[RTE_JOBSTATS_NAMESIZE];
  94         /**< Name of this job */
  95
  96         struct rte_jobstats_context *context;
  97         /**< Job stats context object that is executing this job. */
  98 } __rte_cache_aligned;
  99
 100 struct rte_jobstats_context {
 101         /** Variable holding time at different points:
 102          * -# loop start time if loop was started but no job executed yet.
 103          * -# job start time if job is currently executing.
 104          * -# job finish time if job finished its execution.
 105          * -# loop finish time if loop finished its execution. */
 106         uint64_t state_time;
 107
 108         uint64_t loop_executed_jobs;
 109         /**< Count of executed jobs in this loop. */
 110
 111         /* Statistics start. */
 112
 113         uint64_t exec_time;
 114         /**< Total time taken to execute jobs, not including management time. */
 115
 116         uint64_t min_exec_time;
 117         /**< Minimum loop execute time. */
 118
 119         uint64_t max_exec_time;
 120         /**< Maximum loop execute time. */
 121
 122         /**
 123          * Sum of time that is not the execute time (ex: from job finish to next
 124          * job start).
 125          *
 126          * This time might be considered as overhead of library + job scheduling.
 127          */
 128         uint64_t management_time;
 129
 130         uint64_t min_management_time;
 131         /**< Minimum management time */
 132
 133         uint64_t max_management_time;
 134         /**< Maximum management time */
 135
 136         uint64_t start_time;
 137         /**< Time since last reset stats. */
 138
 139         uint64_t job_exec_cnt;
 140         /**< Total count of executed jobs. */
 141
 142         uint64_t loop_cnt;
 143         /**< Total count of executed loops with at least one executed job. */
 144 } __rte_cache_aligned;
 145
 146 /**
 147  * Initialize given context object with default values.
 148  *
 149  * @param ctx
 150  *  Job stats context object to initialize.
 151  *
 152  * @return
 153  *  0 on success
 154  *  -EINVAL if *ctx* is NULL
 155  */
 156 int
 157 rte_jobstats_context_init(struct rte_jobstats_context *ctx);
 158
 159 /**
 160  * Mark that new set of jobs start executing.
 161  *
 162  * @param ctx
 163  *  Job stats context object.
 164  */
 165 void
 166 rte_jobstats_context_start(struct rte_jobstats_context *ctx);
 167
 168 /**
 169  * Mark that there is no more jobs ready to execute in this turn. Calculate
 170  * stats for this loop turn.
 171  *
 172  * @param ctx
 173  *  Job stats context.
 174  */
 175 void
 176 rte_jobstats_context_finish(struct rte_jobstats_context *ctx);
 177
 178 /**
 179  * Function resets job context statistics.
 180  *
 181  * @param ctx
 182  *  Job stats context which statistics will be reset.
 183  */
 184 void
 185 rte_jobstats_context_reset(struct rte_jobstats_context *ctx);
 186
 187 /**
 188  * Initialize given job stats object.
 189  *
 190  * @param job
 191  *  Job object.
 192  * @param name
 193  *  Optional job name.
 194  * @param min_period
 195  *  Minimum period that this job can accept.
 196  * @param max_period
 197  *  Maximum period that this job can accept.
 198  * @param initial_period
 199  *  Initial period. It will be checked against *min_period* and *max_period*.
 200  * @param target
 201  *  Target value that this job try to achieve.
 202  *
 203  * @return
 204  *  0 on success
 205  *  -EINVAL if *job* is NULL
 206  */
 207 int
 208 rte_jobstats_init(struct rte_jobstats *job, const char *name,
 209                 uint64_t min_period, uint64_t max_period, uint64_t initial_period,
 210                 int64_t target);
 211
 212 /**
 213  * Set job desired target value. Difference between target and job value
 214  * value must be used to properly adjust job execute period value.
 215  *
 216  * @param job
 217  *  The job object.
 218  * @param target
 219  *  New target.
 220  */
 221 void
 222 rte_jobstats_set_target(struct rte_jobstats *job, int64_t target);
 223
 224 /**
 225  * Mark that *job* is starting of its execution in context of *ctx* object.
 226  *
 227  * @param ctx
 228  *  Job stats context.
 229  * @param job
 230  *  Job object.
 231  * @return
 232  *  0 on success
 233  *  -EINVAL if *ctx* or *job* is NULL or *job* is executing in another context
 234  *  context already,
 235  */
 236 int
 237 rte_jobstats_start(struct rte_jobstats_context *ctx, struct rte_jobstats *job);
 238
 239 /**
 240  * Mark that *job* finished its execution, but time of this work will be skipped
 241  * and added to management time.
 242  *
 243  * @param job
 244  *  Job object.
 245  *
 246  * @return
 247  *  0 on success
 248  *  -EINVAL if job is NULL or job was not started (it have no context).
 249  */
 250 int
 251 rte_jobstats_abort(struct rte_jobstats *job);
 252
 253 /**
 254  * Mark that *job* finished its execution. Context in which it was executing
 255  * will receive stat update. After this function call *job* object is ready to
 256  * be executed in other context.
 257  *
 258  * @param job
 259  *  Job object.
 260  * @param job_value
 261  *  Job value. Job should pass in this parameter a value that it try to optimize
 262  *  for example the number of packets it processed.
 263  *
 264  * @return
 265  *  0 if job's period was not updated (job target equals *job_value*)
 266  *  1 if job's period was updated
 267  *  -EINVAL if job is NULL or job was not started (it have no context).
 268  */
 269 int
 270 rte_jobstats_finish(struct rte_jobstats *job, int64_t job_value);
 271
 272 /**
 273  * Set execute period of given job.
 274  *
 275  * @param job
 276  *  The job object.
 277  * @param period
 278  *  New period value.
 279  * @param saturate
 280  *  If zero, skip period saturation to min, max range.
 281  */
 282 void
 283 rte_jobstats_set_period(struct rte_jobstats *job, uint64_t period,
 284                 uint8_t saturate);
 285 /**
 286  * Set minimum execute period of given job. Current period will be checked
 287  * against new minimum value.
 288  *
 289  * @param job
 290  *  The job object.
 291  * @param period
 292  *  New minimum period value.
 293  */
 294 void
 295 rte_jobstats_set_min(struct rte_jobstats *job, uint64_t period);
 296 /**
 297  * Set maximum execute period of given job. Current period will be checked
 298  * against new maximum value.
 299  *
 300  * @param job
 301  *  The job object.
 302  * @param period
 303  *  New maximum period value.
 304  */
 305 void
 306 rte_jobstats_set_max(struct rte_jobstats *job, uint64_t period);
 307
 308 /**
 309  * Set update period callback that is invoked after job finish.
 310  *
 311  * If application wants to do more sophisticated calculations than default
 312  * it can provide this handler.
 313  *
 314  * @param job
 315  *  Job object.
 316  * @param update_period_cb
 317  *  Callback to set. If NULL restore default update function.
 318  */
 319 void
 320 rte_jobstats_set_update_period_function(struct rte_jobstats *job,
 321                 rte_job_update_period_cb_t update_period_cb);
 322
 323 /**
 324  * Function resets job statistics.
 325  *
 326  * @param job
 327  *  Job which statistics will be reset.
 328  */
 329 void
 330 rte_jobstats_reset(struct rte_jobstats *job);
 331
 332 #ifdef __cplusplus
 333 }
 334 #endif
 335
 336 #endif /* JOBSTATS_H_ */