QoS Resource Reservation Kernel Module
[QoS Resource Reservation]

Provides high-level Resource Reservation (RR) scheduling services. More...

Data Structures
struct	qres_server
	Main QRES Server struct, conceptually extends the RRES Server struct (in a OO fashion). More...
Files
file	qres_gw.h
	Common defines for the US to KS gateway.
file	qres_gw_ks.h
	QRES UserSpace to KernelSpace gateway common interface.
file	qres_interface.h
	QRES public interface for use by other kernel modules.
file	qres_proc_fs.h
	Support of proc file system.
Typedefs
typedef struct qres_server	qres_server_t
	Main QRES Server struct, conceptually extends the RRES Server struct (in a OO fashion).
Functions
qos_rv	qres_get_exec_abs_time (qres_server_t qres, qres_time_t exec_time, qres_atime_t *abs_time)
	This is used by QMGR kernel mod, too.
qos_rv	qres_gw_ks (qres_op_t op, void __user *up_iparams, unsigned long size)
	Main US-to-KS gateway function.
static qres_server_t *	qres_find_by_rres (server_t *srv)
static kal_lock_t *	qres_get_lock (void)
	Return a spinlock_t suitable for synchronizing against concurrent requests made through the QRES device interface.
qos_rv	qres_init (void)
	Perform QoS Res/Sup initialization.
qos_rv	qres_cleanup (void)
	Perform QoS Res and Sup cleanup.
qos_rv	qres_create_server (qres_params_t param, qres_sid_t p_sid)
	Create a new server for the specified task with provided parameters.
qos_rv	qres_init_server (qres_server_t srv, qres_params_t param)
qos_rv	qres_destroy_server (qres_server_t *srv)
	Detach all tasks from from the specified server, and destroy the server.
qos_rv	_qres_cleanup_server (server_t *srv)
	Virtual destructor override.
qos_rv	qres_attach_task (qres_server_t qres, struct task_struct tsk)
	Attach to the server identified by srv_id the task identified by tsk.
qos_rv	qres_detach_task (qres_server_t qres, struct task_struct tsk)
	Detach the specified task from its server and, if no other tasks reside therein, destroy the server.
qos_rv	qres_set_params (qres_server_t qres, qres_params_t param)
	Change scheduling parameters of the server to which the specified task is attached.
qos_rv	qres_get_params (qres_server_t srv, qres_params_t params)
	Get the scheduling parameters of the server attached to the specified task.
qres_time_t	qres_get_curr_budget (qres_server_t *qres)
	Retrieve the remaining budget for the current server instance.
qres_time_t	qres_get_next_budget (qres_server_t *qres)
	Retrieve the budget to be used for the very next server instance.
qres_time_t	qres_get_appr_budget (qres_server_t *qres)
	Retrieve the budget approved for the subsequent server instances.
qos_rv	qres_get_deadline (qres_server_t qres, struct timespec p_deadline)
	Retrieve the current server deadline.
kal_uid_t	qres_get_owner_uid (qres_server_t *qres)
	Retrieve the owner UID for the current server.
kal_gid_t	qres_get_owner_gid (qres_server_t *qres)
	Retrieve the owner GID for the current server.
static qres_server_t *	qres_find_by_id (qres_sid_t sid)
int	qres_proc_register (void)
void	qres_proc_unregister (void)

Detailed Description

Provides high-level Resource Reservation (RR) scheduling services.

Applications make RR requests through the library API defined in the QoS Resource Reservation Library interface. All bandwidth requests are mediated by the QoS Supervisor Kernel Module module.

Typedef Documentation

typedef struct qres_server qres_server_t

Main QRES Server struct, conceptually extends the RRES Server struct (in a OO fashion).

The QRES Server adds to resource servers of the RRES Module capabilities related to:

interfacing with the applications through the QRES and QSUP libraries;
admission control, through the QSUP Module functionality;
access control, remembering the uid/gid of the server creator (its owner), and comparing them with the uid/gid requesting any further operation on the server (root can do everything on any server, owner can do everything on its servers, all other users can only read server information/parameters.

Function Documentation

qos_rv _qres_cleanup_server ( server_t * srv )

Virtual destructor override.

Referenced by qos_func_define().

qos_rv qres_attach_task	(	qres_server_t *	qres,
		struct task_struct *	tsk
	)

Attach to the server identified by srv_id the task identified by tsk.

Referenced by qos_func_define().

qos_rv qres_cleanup ( void )

Perform QoS Res and Sup cleanup.

After this call, it is not possible to use any qres_xx() call

Perform QoS Res and Sup cleanup.

Cleanup resources associated to the QoS RES Library.

Definition at line 150 of file qres_lib.c.

References for_each_server_safe, server_t::id, qos_chk_do, qos_chk_ok_ret, QOS_E_GENERIC, QOS_E_INCONSISTENT_STATE, QOS_E_INTERNAL_ERROR, qos_log_debug, QOS_OK, qres_destroy_server(), qres_fd, qres_find_by_rres(), and srv.

Referenced by main(), main_body(), qres_cleanup_module(), and qres_init_module().

qos_rv qres_create_server	(	qres_params_t *	param,
		qres_sid_t *	p_sid
	)

Create a new server for the specified task with provided parameters.

Return the new server identifier in *p_sid

Create a new server for the specified task with provided parameters.

Create a new server with specified parameters.

Change scheduling policy of the specified process to benefit of QoS support into the kernel with provided parameters.

Parameters:

	p_params	If the QRES_F_PERSISTENT flag is set in p_params->flags, then the server is not automatically destroyed after detach of the last thread. Instead, it keeps existing, where further threads may be attached to it by using the a qres_sid_t value for identification.
	p_sid	Pointer to a qres_sid_t variable that is filled with the server ID of the created server. This ID is needed to perform any further operation on the created server (attaching/detaching threads, getting or setting parameters, destroying the server).

Note:: If the QRES_WATCHDOG has been enabled in the module configuration, then, if a persistent server remains empty (with no attached threads) for too much time, the system destroys it automatically. This is a precaution for avoiding persistence of "unreachable" servers in the system, due to programming bugs or application crashes.

Todo:: Implement the QRES_WATCHDOG feature.

Definition at line 74 of file qres_lib.c.

References check_open(), IOCTL_OP_CREATE_SERVER, qres_iparams_t::params, qos_chk_rv, qos_int_rv, QOS_OK, qres_fd, and qres_iparams_t::server_id.

Referenced by main(), main_body(), main_loop(), and qres_gw_ks().

qos_rv qres_destroy_server ( qres_server_t * srv )

Detach all tasks from from the specified server, and destroy the server.

qos_rv qres_detach_task	(	qres_server_t *	qres,
		struct task_struct *	tsk
	)

Detach the specified task from its server and, if no other tasks reside therein, destroy the server.

Referenced by qos_func_define().

static qres_server_t* qres_find_by_id ( qres_sid_t sid ) [inline, static]

Definition at line 171 of file qres_interface.h.

References qres_find_by_rres(), and rres_find_by_id().

Referenced by qos_func_define().

static qres_server_t* qres_find_by_rres ( server_t * srv ) [inline, static]

Definition at line 51 of file qres_interface.h.

References qos_chk, and qres_server::rres.

Referenced by _qres_get_bandwidth(), qos_func_define(), qres_cleanup(), and qres_find_by_id().

qres_time_t qres_get_appr_budget ( qres_server_t * qres )

Retrieve the budget approved for the subsequent server instances.

Whenever a change of budget is requested, either as a result of a qres_set_params() or as a result of the creation of a new server, each server that has been approved a budget increase from the supervisor may undergo (if such increase in not immediately and entirely available) a transitory period during which the current budget, as returned by qres_get_curr_budget(), may change multiple times, until it reaches the approved value.

qres_time_t qres_get_curr_budget ( qres_server_t * qres )

Retrieve the remaining budget for the current server instance.

qos_rv qres_get_deadline	(	qres_server_t *	qres,
		struct timespec *	p_deadline
	)

Retrieve the current server deadline.

qos_rv qres_get_exec_abs_time	(	qres_server_t *	qres,
		qres_time_t *	exec_time,
		qres_atime_t *	abs_time
	)

This is used by QMGR kernel mod, too.

Referenced by qos_func_define().

static kal_lock_t* qres_get_lock ( void ) [inline, static]

Return a spinlock_t suitable for synchronizing against concurrent requests made through the QRES device interface.

Before calling any of the functions defined in qres_interface.h, the caller should have gained a lock on the spinlock_t variable returned by this function. This is usually accomplished by using the qres_lock_irqsave and qres_unlock_irqrestore macros. Though, for more complex cases, this function may be useful as well.

Definition at line 71 of file qres_interface.h.

References rres_get_spinlock().

qres_time_t qres_get_next_budget ( qres_server_t * qres )

Retrieve the budget to be used for the very next server instance.

kal_gid_t qres_get_owner_gid ( qres_server_t * qres )

Retrieve the owner GID for the current server.

This field is set automatically by the QRES module, whenever a process, creates a server, to the process' egid.

Definition at line 392 of file qresmod/qres.c.

References qres_server::owner_gid.

kal_uid_t qres_get_owner_uid ( qres_server_t * qres )

Retrieve the owner UID for the current server.

This field is set automatically by the QRES module, whenever a process, creates a server, to the process' euid.

Definition at line 386 of file qresmod/qres.c.

References qres_server::owner_uid.

Referenced by authorize_for_server().

qos_rv qres_get_params	(	qres_server_t *	srv,
		qres_params_t *	params
	)

Get the scheduling parameters of the server attached to the specified task.

Note:: Returned budget values may be slightly higher than the ones set through qres_init_server() or qres_set_params(), because any granted (budget, period) pair corresponds to a qos_bw_t value (fixed-point representation of the ratio budget/period).

qos_rv qres_gw_ks	(	qres_op_t	op,
		void __user *	up_iparams,
		unsigned long	size
	)

Main US-to-KS gateway function.

Copies parameters from US to KS, checks if requested operation is allowed by the calling process, distinguishes among various kinds of requests, calling appropriate per-request functions. If needed, copies return parameters back from KS to US.

Todo:: avoid copy_from_user and copy_to_user with entire iparams struct when unneeded.

Copies parameters from US to KS, checks if requested operation is allowed by the calling process, distinguishes among various kinds of requests, calling appropriate per-request functions. If needed, copies return parameters back from KS to US.

Assuming the limits configured in the supervisor are not violated by the request, for what concerns security of the OS w.r.t. uid and euid of the requesting process, the access control model should satisfy the following requirements:

let "user process" denote a process with a non-zero effective uid, "root process" one with null euid
a user process should not be able to change parameters of, or destroy, a server created by a privileged process; the only exception may occurr if the process dies and there are no more processes left in a non-persistent server
a user process should not be able to attach any processes owned by anyone to a server created by a privileged process
a privileged process should be able to create and destroy servers, attach and detach threads at will
a privileged process may emulate creation of a server by a normal user if it sets its own euid to the one of the user
if a privileged process is placed into a server owned by an unprivileged user, then the user may keep changing the server parameters and/or destroy the server as usual (destruction of a server only means detach of contained processes, not kill)

Todo:: avoid copy_from_user and copy_to_user with entire iparams struct when unneeded.

Definition at line 262 of file qres_gw_ks.c.

References call_sync, COPY_FROM_USER_TO, QOS_E_INTERNAL_ERROR, qos_log_debug, qos_log_err, QOS_OK, qos_strerror(), qres_create_server(), QRES_OP_ATTACH_TO_SERVER, QRES_OP_CREATE_SERVER, QRES_OP_DESTROY_SERVER, QRES_OP_DETACH_FROM_SERVER, QRES_OP_GET_APPR_BUDGET, QRES_OP_GET_CURR_BUDGET, QRES_OP_GET_DEADLINE, QRES_OP_GET_EXEC_TIME, QRES_OP_GET_NEXT_BUDGET, QRES_OP_GET_PARAMS, QRES_OP_GET_SERVER_ID, QRES_OP_GET_WEIGHT, QRES_OP_SET_PARAMS, QRES_OP_SET_WEIGHT, and server_id.

Referenced by device_ioctl().

qos_rv qres_init ( void )

Perform QoS Res/Sup initialization.

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

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

Perform QoS Res/Sup initialization.

Initializes the QoS RES library.

Definition at line 140 of file qres_lib.c.

References offsetof, QOS_E_INTERNAL_ERROR, QOS_E_MISSING_COMPONENT, qos_log_crit, qos_log_debug, QOS_OK, QRES_DEV_PATHNAME, and qres_fd.

Referenced by check_open(), main(), main_body(), and qres_init_module().

qos_rv qres_init_server	(	qres_server_t *	srv,
		qres_params_t *	param
	)

Referenced by qos_func_define().

int qres_proc_register ( void )

Definition at line 67 of file qres_proc_fs.c.

Referenced by qres_init_module().

void qres_proc_unregister ( void )

Definition at line 68 of file qres_proc_fs.c.

Referenced by qres_cleanup_module().

qos_rv qres_set_params	(	qres_server_t *	qres,
		qres_params_t *	param
	)

Change scheduling parameters of the server to which the specified task is attached.

QoS Resource Reservation Kernel Module [QoS Resource Reservation]

Data Structures

Files

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation

QoS Resource Reservation Kernel Module
[QoS Resource Reservation]