4 * Copyright(c) 2015 Intel Corporation. All rights reserved.
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
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
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.
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.
39 #include <rte_memory.h>
40 #include <rte_memcpy.h>
46 #define RTE_JOBSTATS_NAMESIZE 32
48 /* Forward declarations. */
49 struct rte_jobstats_context;
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.
58 * The job data structure handler.
60 * Result of calling job callback.
62 typedef void (*rte_job_update_period_cb_t)(struct rte_jobstats *job,
67 /**< Estimated period of execution. */
70 /**< Minimum period. */
73 /**< Maximum period. */
76 /**< Desired value for this job. */
78 rte_job_update_period_cb_t update_period_cb;
79 /**< Period update callback. */
82 /**< Total time (sum) that this job was executing. */
84 uint64_t min_exec_time;
85 /**< Minimum execute time. */
87 uint64_t max_exec_time;
88 /**< Minimum execute time. */
91 /**< Execute count. */
93 char name[RTE_JOBSTATS_NAMESIZE];
94 /**< Name of this job */
96 struct rte_jobstats_context *context;
97 /**< Job stats context object that is executing this job. */
98 } __rte_cache_aligned;
100 struct rte_jobstats_context {
101 /** Viariable 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. */
108 uint64_t loop_executed_jobs;
109 /**< Count of executed jobs in this loop. */
111 /* Statistics start. */
114 /**< Total time taken to execute jobs, not including management time. */
116 uint64_t min_exec_time;
117 /**< Minimum loop execute time. */
119 uint64_t max_exec_time;
120 /**< Minimum loop execute time. */
123 * Sum of time that is not the execute time (ex: from job finish to next
126 * This time might be considered as overhead of library + job scheduling.
128 uint64_t management_time;
130 uint64_t min_management_time;
131 /**< Minimum management time */
133 uint64_t max_management_time;
134 /**< Maximum management time */
137 /**< Time since last reset stats. */
139 uint64_t job_exec_cnt;
140 /**< Total count of executed jobs. */
143 /**< Total count of executed loops with at least one executed job. */
144 } __rte_cache_aligned;
147 * Initialize given context object with default values.
150 * Job stats context object to initialize.
154 * -EINVAL if *ctx* is NULL
157 rte_jobstats_context_init(struct rte_jobstats_context *ctx);
160 * Mark that new set of jobs start executing.
163 * Job stats context object.
166 rte_jobstats_context_start(struct rte_jobstats_context *ctx);
169 * Mark that there is no more jobs ready to execute in this turn. Calculate
170 * stats for this loop turn.
176 rte_jobstats_context_finish(struct rte_jobstats_context *ctx);
179 * Function resets job context statistics.
182 * Job stats context which statistics will be reset.
185 rte_jobstats_context_reset(struct rte_jobstats_context *ctx);
188 * Initialize given job stats object.
195 * Minimum period that this job can accept.
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*.
201 * Target value that this job try to achieve.
205 * -EINVAL if *job* is NULL
208 rte_jobstats_init(struct rte_jobstats *job, const char *name,
209 uint64_t min_period, uint64_t max_period, uint64_t initial_period,
213 * Set job desired target value. Difference between target and job value
214 * value must be used to properly adjust job execute period value.
222 rte_jobstats_set_target(struct rte_jobstats *job, int64_t target);
225 * Mark that *job* is starting of its execution in context of *ctx* object.
233 * -EINVAL if *ctx* or *job* is NULL or *job* is executing in another context
237 rte_jobstats_start(struct rte_jobstats_context *ctx, struct rte_jobstats *job);
240 * Mark that *job* finished its execution. Context in which it was executing
241 * will receive stat update. After this function call *job* object is ready to
242 * be executed in other context.
247 * Job value. Job should pass in this parameter a value that it try to optimize
248 * for example the number of packets it processed.
251 * 0 if job's period was not updated (job target equals *job_value*)
252 * 1 if job's period was updated
253 * -EINVAL if job is NULL or job was not started (it have no context).
256 rte_jobstats_finish(struct rte_jobstats *job, int64_t job_value);
259 * Set execute period of given job.
266 * If zero, skip period saturation to min, max range.
269 rte_jobstats_set_period(struct rte_jobstats *job, uint64_t period,
272 * Set minimum execute period of given job. Current period will be checked
273 * against new minimum value.
278 * New minimum period value.
281 rte_jobstats_set_min(struct rte_jobstats *job, uint64_t period);
283 * Set maximum execute period of given job. Current period will be checked
284 * against new maximum value.
289 * New maximum period value.
292 rte_jobstats_set_max(struct rte_jobstats *job, uint64_t period);
295 * Set update period callback that is invoked after job finish.
297 * If application wants to do more sophisticated calculations than default
298 * it can provide this handler.
302 * @param update_pedriod_cb
303 * Callback to set. If NULL restore default update function.
306 rte_jobstats_set_update_period_function(struct rte_jobstats *job,
307 rte_job_update_period_cb_t update_period_cb);
310 * Function resets job statistics.
313 * Job which statistics will be reset.
316 rte_jobstats_reset(struct rte_jobstats *job);
322 #endif /* JOBSTATS_H_ */