xref: /dpdk/lib/jobstats/rte_jobstats.h (revision c6552d9a8deffa448de2d5e2e726f50508c1efd2)
199a2dd95SBruce Richardson /* SPDX-License-Identifier: BSD-3-Clause
299a2dd95SBruce Richardson  * Copyright(c) 2015 Intel Corporation
399a2dd95SBruce Richardson  */
499a2dd95SBruce Richardson 
599a2dd95SBruce Richardson #ifndef JOBSTATS_H_
699a2dd95SBruce Richardson #define JOBSTATS_H_
799a2dd95SBruce Richardson 
899a2dd95SBruce Richardson #include <stdint.h>
999a2dd95SBruce Richardson 
1099a2dd95SBruce Richardson #include <rte_memory.h>
1199a2dd95SBruce Richardson 
1299a2dd95SBruce Richardson #ifdef __cplusplus
1399a2dd95SBruce Richardson extern "C" {
1499a2dd95SBruce Richardson #endif
1599a2dd95SBruce Richardson 
1699a2dd95SBruce Richardson #define RTE_JOBSTATS_NAMESIZE 32
1799a2dd95SBruce Richardson 
1899a2dd95SBruce Richardson /* Forward declarations. */
1999a2dd95SBruce Richardson struct rte_jobstats_context;
2099a2dd95SBruce Richardson struct rte_jobstats;
2199a2dd95SBruce Richardson 
2299a2dd95SBruce Richardson /**
2399a2dd95SBruce Richardson  * This function should calculate new period and set it using
2499a2dd95SBruce Richardson  * rte_jobstats_set_period() function. Time spent in this function will be
2599a2dd95SBruce Richardson  * added to job's runtime.
2699a2dd95SBruce Richardson  *
2799a2dd95SBruce Richardson  * @param job
2899a2dd95SBruce Richardson  *  The job data structure handler.
2999a2dd95SBruce Richardson  * @param job_result
3099a2dd95SBruce Richardson  *  Result of calling job callback.
3199a2dd95SBruce Richardson  */
3299a2dd95SBruce Richardson typedef void (*rte_job_update_period_cb_t)(struct rte_jobstats *job,
3399a2dd95SBruce Richardson 		int64_t job_result);
3499a2dd95SBruce Richardson 
35*c6552d9aSTyler Retzlaff struct __rte_cache_aligned rte_jobstats {
3699a2dd95SBruce Richardson 	uint64_t period;
3799a2dd95SBruce Richardson 	/**< Estimated period of execution. */
3899a2dd95SBruce Richardson 
3999a2dd95SBruce Richardson 	uint64_t min_period;
4099a2dd95SBruce Richardson 	/**< Minimum period. */
4199a2dd95SBruce Richardson 
4299a2dd95SBruce Richardson 	uint64_t max_period;
4399a2dd95SBruce Richardson 	/**< Maximum period. */
4499a2dd95SBruce Richardson 
4599a2dd95SBruce Richardson 	int64_t target;
4699a2dd95SBruce Richardson 	/**< Desired value for this job. */
4799a2dd95SBruce Richardson 
4899a2dd95SBruce Richardson 	rte_job_update_period_cb_t update_period_cb;
4999a2dd95SBruce Richardson 	/**< Period update callback. */
5099a2dd95SBruce Richardson 
5199a2dd95SBruce Richardson 	uint64_t exec_time;
5299a2dd95SBruce Richardson 	/**< Total time (sum) that this job was executing. */
5399a2dd95SBruce Richardson 
5499a2dd95SBruce Richardson 	uint64_t min_exec_time;
5599a2dd95SBruce Richardson 	/**< Minimum execute time. */
5699a2dd95SBruce Richardson 
5799a2dd95SBruce Richardson 	uint64_t max_exec_time;
5899a2dd95SBruce Richardson 	/**< Maximum execute time. */
5999a2dd95SBruce Richardson 
6099a2dd95SBruce Richardson 	uint64_t exec_cnt;
6199a2dd95SBruce Richardson 	/**< Execute count. */
6299a2dd95SBruce Richardson 
6399a2dd95SBruce Richardson 	char name[RTE_JOBSTATS_NAMESIZE];
6499a2dd95SBruce Richardson 	/**< Name of this job */
6599a2dd95SBruce Richardson 
6699a2dd95SBruce Richardson 	struct rte_jobstats_context *context;
6799a2dd95SBruce Richardson 	/**< Job stats context object that is executing this job. */
68*c6552d9aSTyler Retzlaff };
6999a2dd95SBruce Richardson 
70*c6552d9aSTyler Retzlaff struct __rte_cache_aligned rte_jobstats_context {
7199a2dd95SBruce Richardson 	/** Variable holding time at different points:
7299a2dd95SBruce Richardson 	 * -# loop start time if loop was started but no job executed yet.
7399a2dd95SBruce Richardson 	 * -# job start time if job is currently executing.
7499a2dd95SBruce Richardson 	 * -# job finish time if job finished its execution.
7599a2dd95SBruce Richardson 	 * -# loop finish time if loop finished its execution. */
7699a2dd95SBruce Richardson 	uint64_t state_time;
7799a2dd95SBruce Richardson 
7899a2dd95SBruce Richardson 	uint64_t loop_executed_jobs;
7999a2dd95SBruce Richardson 	/**< Count of executed jobs in this loop. */
8099a2dd95SBruce Richardson 
8199a2dd95SBruce Richardson 	/* Statistics start. */
8299a2dd95SBruce Richardson 
8399a2dd95SBruce Richardson 	uint64_t exec_time;
8499a2dd95SBruce Richardson 	/**< Total time taken to execute jobs, not including management time. */
8599a2dd95SBruce Richardson 
8699a2dd95SBruce Richardson 	uint64_t min_exec_time;
8799a2dd95SBruce Richardson 	/**< Minimum loop execute time. */
8899a2dd95SBruce Richardson 
8999a2dd95SBruce Richardson 	uint64_t max_exec_time;
9099a2dd95SBruce Richardson 	/**< Maximum loop execute time. */
9199a2dd95SBruce Richardson 
9299a2dd95SBruce Richardson 	/**
9399a2dd95SBruce Richardson 	 * Sum of time that is not the execute time (ex: from job finish to next
9499a2dd95SBruce Richardson 	 * job start).
9599a2dd95SBruce Richardson 	 *
9699a2dd95SBruce Richardson 	 * This time might be considered as overhead of library + job scheduling.
9799a2dd95SBruce Richardson 	 */
9899a2dd95SBruce Richardson 	uint64_t management_time;
9999a2dd95SBruce Richardson 
10099a2dd95SBruce Richardson 	uint64_t min_management_time;
10199a2dd95SBruce Richardson 	/**< Minimum management time */
10299a2dd95SBruce Richardson 
10399a2dd95SBruce Richardson 	uint64_t max_management_time;
10499a2dd95SBruce Richardson 	/**< Maximum management time */
10599a2dd95SBruce Richardson 
10699a2dd95SBruce Richardson 	uint64_t start_time;
10799a2dd95SBruce Richardson 	/**< Time since last reset stats. */
10899a2dd95SBruce Richardson 
10999a2dd95SBruce Richardson 	uint64_t job_exec_cnt;
11099a2dd95SBruce Richardson 	/**< Total count of executed jobs. */
11199a2dd95SBruce Richardson 
11299a2dd95SBruce Richardson 	uint64_t loop_cnt;
11399a2dd95SBruce Richardson 	/**< Total count of executed loops with at least one executed job. */
114*c6552d9aSTyler Retzlaff };
11599a2dd95SBruce Richardson 
11699a2dd95SBruce Richardson /**
11799a2dd95SBruce Richardson  * Initialize given context object with default values.
11899a2dd95SBruce Richardson  *
11999a2dd95SBruce Richardson  * @param ctx
12099a2dd95SBruce Richardson  *  Job stats context object to initialize.
12199a2dd95SBruce Richardson  *
12299a2dd95SBruce Richardson  * @return
12399a2dd95SBruce Richardson  *  0 on success
12499a2dd95SBruce Richardson  *  -EINVAL if *ctx* is NULL
12599a2dd95SBruce Richardson  */
12699a2dd95SBruce Richardson int
12799a2dd95SBruce Richardson rte_jobstats_context_init(struct rte_jobstats_context *ctx);
12899a2dd95SBruce Richardson 
12999a2dd95SBruce Richardson /**
13099a2dd95SBruce Richardson  * Mark that new set of jobs start executing.
13199a2dd95SBruce Richardson  *
13299a2dd95SBruce Richardson  * @param ctx
13399a2dd95SBruce Richardson  *  Job stats context object.
13499a2dd95SBruce Richardson  */
13599a2dd95SBruce Richardson void
13699a2dd95SBruce Richardson rte_jobstats_context_start(struct rte_jobstats_context *ctx);
13799a2dd95SBruce Richardson 
13899a2dd95SBruce Richardson /**
13999a2dd95SBruce Richardson  * Mark that there is no more jobs ready to execute in this turn. Calculate
14099a2dd95SBruce Richardson  * stats for this loop turn.
14199a2dd95SBruce Richardson  *
14299a2dd95SBruce Richardson  * @param ctx
14399a2dd95SBruce Richardson  *  Job stats context.
14499a2dd95SBruce Richardson  */
14599a2dd95SBruce Richardson void
14699a2dd95SBruce Richardson rte_jobstats_context_finish(struct rte_jobstats_context *ctx);
14799a2dd95SBruce Richardson 
14899a2dd95SBruce Richardson /**
14999a2dd95SBruce Richardson  * Function resets job context statistics.
15099a2dd95SBruce Richardson  *
15199a2dd95SBruce Richardson  * @param ctx
15299a2dd95SBruce Richardson  *  Job stats context which statistics will be reset.
15399a2dd95SBruce Richardson  */
15499a2dd95SBruce Richardson void
15599a2dd95SBruce Richardson rte_jobstats_context_reset(struct rte_jobstats_context *ctx);
15699a2dd95SBruce Richardson 
15799a2dd95SBruce Richardson /**
15899a2dd95SBruce Richardson  * Initialize given job stats object.
15999a2dd95SBruce Richardson  *
16099a2dd95SBruce Richardson  * @param job
16199a2dd95SBruce Richardson  *  Job object.
16299a2dd95SBruce Richardson  * @param name
16399a2dd95SBruce Richardson  *  Optional job name.
16499a2dd95SBruce Richardson  * @param min_period
16599a2dd95SBruce Richardson  *  Minimum period that this job can accept.
16699a2dd95SBruce Richardson  * @param max_period
16799a2dd95SBruce Richardson  *  Maximum period that this job can accept.
16899a2dd95SBruce Richardson  * @param initial_period
16999a2dd95SBruce Richardson  *  Initial period. It will be checked against *min_period* and *max_period*.
17099a2dd95SBruce Richardson  * @param target
17199a2dd95SBruce Richardson  *  Target value that this job try to achieve.
17299a2dd95SBruce Richardson  *
17399a2dd95SBruce Richardson  * @return
17499a2dd95SBruce Richardson  *  0 on success
17599a2dd95SBruce Richardson  *  -EINVAL if *job* is NULL
17699a2dd95SBruce Richardson  */
17799a2dd95SBruce Richardson int
17899a2dd95SBruce Richardson rte_jobstats_init(struct rte_jobstats *job, const char *name,
17999a2dd95SBruce Richardson 		uint64_t min_period, uint64_t max_period, uint64_t initial_period,
18099a2dd95SBruce Richardson 		int64_t target);
18199a2dd95SBruce Richardson 
18299a2dd95SBruce Richardson /**
18399a2dd95SBruce Richardson  * Set job desired target value. Difference between target and job value
18499a2dd95SBruce Richardson  * value must be used to properly adjust job execute period value.
18599a2dd95SBruce Richardson  *
18699a2dd95SBruce Richardson  * @param job
18799a2dd95SBruce Richardson  *  The job object.
18899a2dd95SBruce Richardson  * @param target
18999a2dd95SBruce Richardson  *  New target.
19099a2dd95SBruce Richardson  */
19199a2dd95SBruce Richardson void
19299a2dd95SBruce Richardson rte_jobstats_set_target(struct rte_jobstats *job, int64_t target);
19399a2dd95SBruce Richardson 
19499a2dd95SBruce Richardson /**
19599a2dd95SBruce Richardson  * Mark that *job* is starting of its execution in context of *ctx* object.
19699a2dd95SBruce Richardson  *
19799a2dd95SBruce Richardson  * @param ctx
19899a2dd95SBruce Richardson  *  Job stats context.
19999a2dd95SBruce Richardson  * @param job
20099a2dd95SBruce Richardson  *  Job object.
20199a2dd95SBruce Richardson  * @return
20299a2dd95SBruce Richardson  *  0 on success
20399a2dd95SBruce Richardson  *  -EINVAL if *ctx* or *job* is NULL or *job* is executing in another context
20499a2dd95SBruce Richardson  *  context already,
20599a2dd95SBruce Richardson  */
20699a2dd95SBruce Richardson int
20799a2dd95SBruce Richardson rte_jobstats_start(struct rte_jobstats_context *ctx, struct rte_jobstats *job);
20899a2dd95SBruce Richardson 
20999a2dd95SBruce Richardson /**
21099a2dd95SBruce Richardson  * Mark that *job* finished its execution, but time of this work will be skipped
21199a2dd95SBruce Richardson  * and added to management time.
21299a2dd95SBruce Richardson  *
21399a2dd95SBruce Richardson  * @param job
21499a2dd95SBruce Richardson  *  Job object.
21599a2dd95SBruce Richardson  *
21699a2dd95SBruce Richardson  * @return
21799a2dd95SBruce Richardson  *  0 on success
21899a2dd95SBruce Richardson  *  -EINVAL if job is NULL or job was not started (it have no context).
21999a2dd95SBruce Richardson  */
22099a2dd95SBruce Richardson int
22199a2dd95SBruce Richardson rte_jobstats_abort(struct rte_jobstats *job);
22299a2dd95SBruce Richardson 
22399a2dd95SBruce Richardson /**
22499a2dd95SBruce Richardson  * Mark that *job* finished its execution. Context in which it was executing
22599a2dd95SBruce Richardson  * will receive stat update. After this function call *job* object is ready to
22699a2dd95SBruce Richardson  * be executed in other context.
22799a2dd95SBruce Richardson  *
22899a2dd95SBruce Richardson  * @param job
22999a2dd95SBruce Richardson  *  Job object.
23099a2dd95SBruce Richardson  * @param job_value
23199a2dd95SBruce Richardson  *  Job value. Job should pass in this parameter a value that it try to optimize
23299a2dd95SBruce Richardson  *  for example the number of packets it processed.
23399a2dd95SBruce Richardson  *
23499a2dd95SBruce Richardson  * @return
23599a2dd95SBruce Richardson  *  0 if job's period was not updated (job target equals *job_value*)
23699a2dd95SBruce Richardson  *  1 if job's period was updated
23799a2dd95SBruce Richardson  *  -EINVAL if job is NULL or job was not started (it have no context).
23899a2dd95SBruce Richardson  */
23999a2dd95SBruce Richardson int
24099a2dd95SBruce Richardson rte_jobstats_finish(struct rte_jobstats *job, int64_t job_value);
24199a2dd95SBruce Richardson 
24299a2dd95SBruce Richardson /**
24399a2dd95SBruce Richardson  * Set execute period of given job.
24499a2dd95SBruce Richardson  *
24599a2dd95SBruce Richardson  * @param job
24699a2dd95SBruce Richardson  *  The job object.
24799a2dd95SBruce Richardson  * @param period
24899a2dd95SBruce Richardson  *  New period value.
24999a2dd95SBruce Richardson  * @param saturate
25099a2dd95SBruce Richardson  *  If zero, skip period saturation to min, max range.
25199a2dd95SBruce Richardson  */
25299a2dd95SBruce Richardson void
25399a2dd95SBruce Richardson rte_jobstats_set_period(struct rte_jobstats *job, uint64_t period,
25499a2dd95SBruce Richardson 		uint8_t saturate);
25599a2dd95SBruce Richardson /**
25699a2dd95SBruce Richardson  * Set minimum execute period of given job. Current period will be checked
25799a2dd95SBruce Richardson  * against new minimum value.
25899a2dd95SBruce Richardson  *
25999a2dd95SBruce Richardson  * @param job
26099a2dd95SBruce Richardson  *  The job object.
26199a2dd95SBruce Richardson  * @param period
26299a2dd95SBruce Richardson  *  New minimum period value.
26399a2dd95SBruce Richardson  */
26499a2dd95SBruce Richardson void
26599a2dd95SBruce Richardson rte_jobstats_set_min(struct rte_jobstats *job, uint64_t period);
26699a2dd95SBruce Richardson /**
26799a2dd95SBruce Richardson  * Set maximum execute period of given job. Current period will be checked
26899a2dd95SBruce Richardson  * against new maximum value.
26999a2dd95SBruce Richardson  *
27099a2dd95SBruce Richardson  * @param job
27199a2dd95SBruce Richardson  *  The job object.
27299a2dd95SBruce Richardson  * @param period
27399a2dd95SBruce Richardson  *  New maximum period value.
27499a2dd95SBruce Richardson  */
27599a2dd95SBruce Richardson void
27699a2dd95SBruce Richardson rte_jobstats_set_max(struct rte_jobstats *job, uint64_t period);
27799a2dd95SBruce Richardson 
27899a2dd95SBruce Richardson /**
27999a2dd95SBruce Richardson  * Set update period callback that is invoked after job finish.
28099a2dd95SBruce Richardson  *
28199a2dd95SBruce Richardson  * If application wants to do more sophisticated calculations than default
28299a2dd95SBruce Richardson  * it can provide this handler.
28399a2dd95SBruce Richardson  *
28499a2dd95SBruce Richardson  * @param job
28599a2dd95SBruce Richardson  *  Job object.
28699a2dd95SBruce Richardson  * @param update_period_cb
28799a2dd95SBruce Richardson  *  Callback to set. If NULL restore default update function.
28899a2dd95SBruce Richardson  */
28999a2dd95SBruce Richardson void
29099a2dd95SBruce Richardson rte_jobstats_set_update_period_function(struct rte_jobstats *job,
29199a2dd95SBruce Richardson 		rte_job_update_period_cb_t update_period_cb);
29299a2dd95SBruce Richardson 
29399a2dd95SBruce Richardson /**
29499a2dd95SBruce Richardson  * Function resets job statistics.
29599a2dd95SBruce Richardson  *
29699a2dd95SBruce Richardson  * @param job
29799a2dd95SBruce Richardson  *  Job which statistics will be reset.
29899a2dd95SBruce Richardson  */
29999a2dd95SBruce Richardson void
30099a2dd95SBruce Richardson rte_jobstats_reset(struct rte_jobstats *job);
30199a2dd95SBruce Richardson 
30299a2dd95SBruce Richardson #ifdef __cplusplus
30399a2dd95SBruce Richardson }
30499a2dd95SBruce Richardson #endif
30599a2dd95SBruce Richardson 
30699a2dd95SBruce Richardson #endif /* JOBSTATS_H_ */
307