\documentclass{article}
\topmargin=-0.3 truein
\textheight=9 truein
\textwidth=6.1 truein
\oddsidemargin=0.2 truein

\usepackage{psfig}
\usepackage{latexsym}
\usepackage[english]{babel}
\selectlanguage{english}

\title{Portable QoS Manager}

\author{Luca Abeni\\
	RETIS Lab\\
	Scuola Superiore S. Anna, Pisa\\
	luca@sssup.it\\
}

\date{}
\begin{document}
%\setlength{\baselineskip}{1.5\baselineskip}

\maketitle

\begin{abstract}
This document describes a portable reimplementation of the Quality of Service
(QoS) Manager presented in \cite{Abe99-5}.
\end{abstract}


\section{Introduction}
This QoS Manager implements some high-level task models described in
\cite{Abe99-5} automatically assigning the proper amount of the CPU resource
to each managed task. For a complete description of the abstractions exported
by the QoS Manager and of the theory behind them, refer to the cited paper;
in this context only a brief (and incomplete) summary is presented.

\subsection{Task Models}
The QoS Manager basically provides two abstractions: {\tt adaptive tasks}
(using a feedback mechanism for dynamically adapting the scheduling
parameters), and pseudo proportional share tasks.

An adaptive task $\tau_i$ is a stream of instances, or jobs, $J_{i,j}$. Since
only pseudo-periodic adaptive tasks are currently supported, each job
is supposed to arrive at time $r_{i,j} = jT_i$, where $T_i$ is the
task period, and to be characterized by a soft deadline
$\delta_{i,j} = r_{i,j} + D_i = jT_i + D_i$.
The relative soft deadline $D_i$ is also called {\em server period}, or
{\em reserve period}.

Each adaptive task $\tau_i$ will be reserved an amount of time $Q_i$ each
$D_i$ time units, and the QoS manager will automatically adapt the $Q_i$ in
order to serve each job within its soft deadline.

A pseudo proportional share task is guaranteed to receive a fair share of the
CPU, executing at a speed $\frac{w_i}{\sum_j w_j} B_{PPS} S_{cpu}$ where
$w_i$ is the task weight, $B_{PPS}$ is the total CPU bandwidth reserved
to pseudo proportional share tasks, and $S_{cpu}$ is the CPU speed. Basically,
the task will execute for $Q_i$ units of time each
$\frac{Q_i}{\frac{w_i}{\sum_j w_j} B_{PPS}}$, where $Q_i$ is the pseudo
proportional share time quantum, that can be seen as the granularity of the
CPU allocation. Pseudo proportional share tasks are not characterized by the
notion of instance, or period.

\subsection{The Library}
The original QoS Manager, designed to work on the HARTIK kernel \cite{ha},
has been reimplemented in a portable way, so that it could be easily
ported to every OS providing temporal protection in CPU scheduling.
Currently, the only available port is to Linux/RK \cite{rk}.

Each program that need to use the QoS manager must be linked to the QoS
Library ({\tt libqos.a}), located in {\tt LinuxRK/qoslib-0.1}. The library
provides calls for: \begin{itemize}
\item initialize the QoS Manager (creating the QoS Manager task)
\item creating and destroying QoS tasks (adaptive tasks or pseudo
	proportional share tasks)
\item managing the QoS tasks
\end{itemize}

\section{API}
\subsection{Initializing the QoS Manager}
The library call
\begin{quote}
\begin{tt}
int qman\_init(struct qmparm *p)
\end{tt}
\end{quote}
can be used to initialize the QoS Manager, creating the manager task and
the communication ports needed to send requests to it. This function must be
called before using any other QoS function. The function takes as input a
pointer {\tt p} to a {\tt qmparm} structure, defined as follows:
\begin{tt}
\begin{tabbing}
struct \= qmparm \{				\\
    \> float psu;					\\
    \> DWORD psq;					\\
    \> float rmu;					\\
\}
\end{tabbing}
\end{tt}

where {\tt psu} is the fraction of the total CPU bandwidth reserved for
pseudo proportional share tasks, {\tt psq} is the default pseudo
proportional share quantum, and {\tt rmu} is the least upper bound for rate
monotonic. if {\tt p == NULL}, the default values {\tt psu = 0.1},
{\tt psq = 1ms}, and {\tt rmu = 0.69} are assumed.

\subsection{Creating an Adaptive Task}
Currently, only the MultiMedia task model is supported for adaptive tasks.
An adaptive task can be created using the library call
\begin{quote}
\begin{tt}
ID qset\_addtask(struct qparm *t)
\end{tt}
\end{quote}
where {\tt t} is a pointer to a {\tt qparm} structure describing the task
to create. The {\tt qparm} structure is defined as follows:
\begin{tt}
\begin{tabbing}
struct \= qparm \{				\\
    \> char *name;				\\
    \> TASK(*body) (WORD);			\\
    \> int arg;					\\
    \> DWORD wcet;				\\
    \> float w;					\\
    \> int reduce;				\\
    \> DWORD per;				\\
    \> BYTE model;				\\
\}
\end{tabbing}
\end{tt}

The {\tt name} field is a pointer to a string identifying the task, the
{\tt body} field is a pointer to a function containing the task body,
the {\tt arg} field is an optional parameter that can be passed to the task,
the {\tt wcet} field is an optional estimation of the task Worst Case
Execution Time (WCET) expressed in $\mu$seconds, the {\tt w} field is a
weight specifying the task importance, the {\tt reduce} field is the
ratio between the task period {\tt per} (expressed in $\mu$second) and
the server period (soft relative deadline), whereas {\tt model} is currently
not used.

If an initial estimation of the WCET is not available, a small value (like
$1 ms$) is a safe default; the server period is generally assumed to be equal to
the task period, hence $1$ is a safe value for the {\tt reduce} parameter.

The function returns an identifier (of type {\tt ID}) of the created task.

\subsection{Creating a Pseudo Proportional Share Task}
The function
\begin{quote}
\begin{tt}
ID ps\_addtask(struct psparm *t)
\end{tt}
\end{quote}
permits to create a pseudo proportional share task. The parameter {\tt t} is
a pointer to a {\tt psparm} describing the task to be created; the
{\tt psparm} struct is defined as follows:
\begin{tt}
\begin{tabbing}
struct \= psparm \{				\\
    \> char *name;				\\
    \> TASK(*body) (WORD);			\\
    \> int arg;					\\
    \> DWORD quantum;				\\
    \> float w;					\\
\};
\end{tabbing}
\end{tt}

As for adaptive tasks, the {\tt name} fields is a pointer to the task name,
{\tt body} is a pointer to a function containing the task body, and {\tt arg} is
an optional parameter that will be passed to the task.

The {\tt quantum} and {\tt w} fields define the pseudo proportional share
quantum and weight respectively.

Like {\tt qset\_addtask()}, this function returns the identifier (of type
{\tt ID}) of the created task.

\subsection{Terminating Tasks}
Each task created by the QoS manager is correctly terminated (releasing
all the used CPU bandwidth to the QoS manager) when the execution arrives
to the end of the task body. Alternatively, a task can explicitly terminate
using the
\begin{quote}
\begin{tt}
void qtask\_end(int retvalue)
\end{tt}
\end{quote}
library call.

\subsection{Changing Task Periods}
When an adaptive task is created (using the {\tt qset\_addtask()} library
call), a period for it is specified in the {\tt qparm} struct. However,
the task period can be changed every time that the task needs to adapt its
QoS, using one of the following functions:
\begin{quote}
\begin{tt}
void p\_change(ID task, WORD newp)
\end{tt}
\end{quote}
\begin{quote}
\begin{tt}
void qtask\_changeperiod(WORD newp)
\end{tt}
\end{quote}

The {\tt p\_change()} library call can be used to change the period of task
{\tt task} to {\tt newp}, while {\tt qtask\_changeperiod()} will change the
period of the calling task (supposed to be an adaptive task created by the
QoS manager). The server server period is changed according to the {\tt reduce}
parameter specified at task creation time (if {\tt reduce == 1}, the server server
period is equal to the task period).

\subsection{Ending a Task Instance}
The library call
\begin{quote}
\begin{tt}
DWORD qtask\_endcycle(void)
\end{tt}
\end{quote}
notifies to the QoS Manager that the calling adaptive tasks finished executing
an instance. The {\tt qtask\_endcycle()} function: \begin{itemize}
\item computes a {\em ``scheduling error''} to understand if the task has
	been assigned a sufficient amount of CPU time
\item applies a {\em feedback function} to compute a new amount of requested
	CPU time
\item sends the new request to the QoS Manager task
\item blocks the task waiting for the next instances.
\end{itemize}

The function also returns the compute scheduling error, that can be used by the
task to perform some application dependent QoS adaptation.

\subsection{Selecting a Feedback Function}
The library call
\begin{quote}
\begin{tt}
void setreq(struct reqactions *p)
\end{tt}
\end{quote}
permits to specify an alternative feedback function. The library provides a
``constant'' feedback function as a default, but it is possible to specify a
different one, described by the {\tt p} parameter. Currently, only a simple
proportional feedback function is provided (in the predefined variable
{\tt adjactions} variable) as an alternative: it can be installed using 
\begin{quote}
\begin{tt}
setreq(\&adjactions);
\end{tt}
\end{quote}

See {\tt adj.c}, {\tt include/adj.h}, and {\tt include/req.h} for details.
%\setlength{\baselineskip}{0.66\baselineskip}
\bibliographystyle{plain}
\bibliography{retis}
\end{document}
