qmgr_lib.h File Reference

Basic Application Programming Interface for feedback based QoS management. More...

#include <linux/aquosa/qmgr.h>
#include <linux/aquosa/submodules_internal_ks.h>
#include <linux/aquosa/submodules_internal_us.h>
#include <linux/aquosa/qmgr_params.h>

Go to the source code of this file.

Functions
qos_rv	qmgr_init (void)
	Initializes the QMGR library.
qos_rv	qmgr_cleanup (void)
	Finalizes the QMGR library.
qos_rv	qmgr_get_ctrl_location (int ctrl_type, qmgr_location_t *location)
	Gets the configured location for the specified predictor.
qos_rv	qmgr_get_pred_location (int pred_type, qmgr_location_t *location)
	Gets the configured location for the specified controller.
qos_rv	qmgr_set_predictor (qmgr_pred_type_t type)
	Sets a predictor to be used with default parameters.
qmgr_pred_type_t	qmgr_get_predictor (void)
	Retrieves the predictor currently set.
qos_rv	qmgr_set_controller (qmgr_ctrl_type_t type)
	Sets a controller to be used with default parameters.
qmgr_ctrl_type_t	qmgr_get_controller (void)
	Retrieves the feedback controller currently set.
qos_rv	qmgr_start (void)
	Creates the QMGR from previously set parameters (through the set_fb and set_pred functions).
qos_rv	qmgr_stop (void)
	Destroys the QMGR component and its associated resources.
qos_rv	qmgr_pause (void)
	Stops the feedback based bandwidth assignment.
qos_rv	qmgr_continue (void)
	Starts again the feedback based bandwidth assignment that has been put in pause through a previous call to qmgr_pause().
qos_rv	qmgr_begin_cycle (void)
	Notifies to the QoS Manager that a new job has just arrived.
qos_rv	qmgr_begin_cycle_deadline (struct timespec *abs_dl)
qos_rv	qmgr_set_max_bandwidth (float max_bw)
	Sets the saturation bandwidth value for the controller.
qos_rv	qmgr_set_min_bandwidth (float min_bw)
	Set the minimum guaranteed bandwidth for the controlled server.
float	qmgr_get_max_bandwidth (void)
	Retrieves the current saturation bandwidth value for the controller.
qos_rv	qmgr_set_task_period (qres_time_t usecs)
	Sets the task period, in microseconds.
qres_time_t	qmgr_get_task_period (void)
	Retrieves the task period, in microseconds.
qos_rv	qmgr_set_server_period (qres_time_t usecs)
	Sets the QRES server period, in microseconds.
qres_time_t	qmgr_get_server_period (void)
	Retrieves the QRES server period, in microseconds.
qos_rv	qmgr_end_cycle (qres_time_t *p_sched_error, qres_time_t *p_exec_time)
	Normal end of job.
qos_rv	qmgr_end_cycle_skip (qres_time_t *p_sched_error, qres_time_t *p_exec_time)
	End of job without updating predictor.
qos_rv	qmgr_end_cycle_param (qres_time_t *p_sched_error, qres_time_t *p_exec_time, void *)
	End of job providing application-defined parameters to an application-defined predictor or controller.
qos_rv	qmgr_get_deadline (struct timespec *p_deadline)
	Retrieve the current QMGR control loop deadline.
Variables
qmgr_lib_descriptor_t	pred_lib_descriptors [QMGR_NUM_PREDS]
	Wether or not the qmgr_create() function has already been called.
qmgr_lib_descriptor_t	ctrl_lib_descriptors [QMGR_NUM_CTRLS]
	Library descriptors for all controllers.
qmgr_params_t	qmgr_params

---

Detailed Description

Basic Application Programming Interface for feedback based QoS management.

Definition in file qmgr_lib.h.

---

Function Documentation

qos_rv qmgr_begin_cycle

(

void

)

Notifies to the QoS Manager that a new job has just arrived.

Begin of a job.

This function should be called in the callback handling arrival of a new job, e.g. in the signal handler of a periodically delivered signal, or in the code segment managing arrival and buffering of a new packet.

It is used by the architecture to push into a queue the absolute deadline w.r.t. which the scheduling error will be computed when the just arrived job will finish computation. The qmgr_end_cycle() function pops out deadlines from this queue in order to compute the scheduling error experimented by each job.

This mechanism allows to synchronize the controller view of the task periodic activations and the task itself, so that even if the job inter-activation time is not exactly equal to the value set with qmgr_set_task_period(), or is not exactly constant (as caused by the use of the Linux setitimer() syscall, for instance), the controller keeps resynchronizing continuously with the application and no drifts occurr.

Note:

Due to the variability of the actual instant at which a task is assigned its budget, within a server period, this function has also the side effect to add a random noise of half a server period in the computation of scheduling error values.

Communicates to the QoS Manager that a new job has just begun. This call is useful, whenever the last job finished before its deadline, for communicating with no ambiguity the temporal reference the QoS Manager should refer to when computing scheduling error values.

qos_rv qmgr_cleanup

(

void

)

Finalizes the QMGR library.

This function may be called if the application does not need anymore QMGR services, so that associated resources may be freed.

qos_rv qmgr_continue

(

void

)

Starts again the feedback based bandwidth assignment that has been put in pause through a previous call to qmgr_pause().

After calling this function, the task bandwidth assignment is again controlled by the feedback mechanism, as before the qmgr_pause() function call.

qos_rv qmgr_end_cycle	(	qres_time_t *	p_sched_error,
		qres_time_t *	p_exec_time
	)

Normal end of job.

p_sched_error, if not NULL, allows the application to read the experimented scheduling error, in us, of the finishing job.

p_exec_time, if not NULL, allows the application to read the experimented execution time, in us, of the finishing job.

Computation of the scheduling error value is performed as follows:

• if $ {prev} > 0 $, then $ {k+1} = t_{curr} - (t_{prev} - {prev}) - T $
• if $ {prev} 0 $, then $ {k+1} = t_{curr} - b_{prev} - T $ where:
• $ t_{curr} $ is the time measured during this qmgr_end_cycle) call
• $ t_{prev} $ is the time measured during last qmgr_end_cycle() call
• $ b_{prev} $ is the time measured during the last qmgr_begin_cycle() call

qmgr_ctrl_type_t qmgr_get_controller

(

void

)

Retrieves the feedback controller currently set.

The controller is set through one of the qmgr_set_ctrl_* functions. If no controller is currently set, then returns QMGR_CTRL_NONE.

qos_rv qmgr_get_deadline

(

struct timespec *

p_deadline

)

Retrieve the current QMGR control loop deadline.

When called after qmgr_begin_cycle(), this function returns the deadline that has been used for feedback-based scheduling in the last control computations.

float qmgr_get_max_bandwidth

(

void

)

Retrieves the current saturation bandwidth value for the controller.

Returns:

The current saturation value, in the open range ]0,1[.

qmgr_pred_type_t qmgr_get_predictor

(

void

)

Retrieves the predictor currently set.

Predictor is either set through the qmgr_set_pred_* functions or it is chosen as default by a controller. If no predictor is currently set, then returns QMGR_PRED_NONE.

qres_time_t qmgr_get_server_period

(

void

)

Retrieves the QRES server period, in microseconds.

qres_time_t qmgr_get_task_period

(

void

)

Retrieves the task period, in microseconds.

qos_rv qmgr_init

(

void

)

Initializes the QMGR library.

Checks that the kernel supports QoS Management, then initializes the QMGR library.

Returns:

QOS_OK if initialization was succesful QOS_E_MISSING_COMPONENT if kernel does not support QoS management

qos_rv qmgr_pause

(

void

)

Stops the feedback based bandwidth assignment.

After calling this function, the task keeps running with the last assigned bandwidth, and no further control is applied until explicitly requested by calling the qmgr_continue() function.

qos_rv qmgr_set_controller

(

qmgr_ctrl_type_t

type

)

Sets a controller to be used with default parameters.

If a predictor has not already been set, then the controller assigns a default predictor, which depends on the controller type, with default parameters.

qos_rv qmgr_set_max_bandwidth

(

float

max_bw

)

Sets the saturation bandwidth value for the controller.

Parameters:

max_bw

The new saturation value, in the open range ]0,1[.

qos_rv qmgr_set_predictor

(

qmgr_pred_type_t

type

)

Sets a predictor to be used with default parameters.

qos_rv qmgr_set_server_period

(

qres_time_t

usecs

)

Sets the QRES server period, in microseconds.

qos_rv qmgr_set_task_period

(

qres_time_t

usecs

)

Sets the task period, in microseconds.

qos_rv qmgr_start

(

void

)

Creates the QMGR from previously set parameters (through the set_fb and set_pred functions).

Todo:

qmgr_start(), _pause(), _continue(), _stop() WARNING: _continue() should be able to re-start predictors with the right computation times (the time between _pause() and _stop() should *not* be accounted by the predictor)

---

Variable Documentation

qmgr_lib_descriptor_t pred_lib_descriptors[QMGR_NUM_PREDS]

Wether or not the qmgr_create() function has already been called.

When the QMGR component is successfully instantiated, either in KS or in US, qmgr_created is set to 1. Library descriptors for all predictors