rtsched/rtsched-doc.tex

\documentclass{article}

\usepackage{rtsched}
\usepackage{url}
\usepackage{multido}

\title{The \texttt{rtsched} package for \LaTeX \\ (version 2.0)}
\author{Giuseppe Lipari}

\begin{document}

\maketitle

\listoffigures

\section{Introduction}

In this document, I give an overview of the \texttt{rtsched} \LaTeX
package, which can be used to easily draw chronograms (GANTT charts).
These diagrams are quite common in real-time scheduling research.

The package depends on keyval and TikZ/PGF, both widely
available on any \TeX distribution.

The drawing capabilities are completely based on TikZ. Thus, you can compile
 a document that uses \texttt{rtsched} package with modern tools producing pdf document
as \texttt{pdfLaTeX}, \texttt{XeLaTeX} or \texttt{LuaLaTeX}.

As said, the style works also with Beamer, and it is also possible to
use animations.

You can find more examples of usage of this style in my lectures,
which can be downloaded at the following address:
\url{http://retis.sssup.it/~lipari/courses/}.

I prefer to demonstrate the capabilities of the package by a set of
examples. You can just cut and paste the examples and play with them
as you wish.

\section{Basic commands}

\subsection{Simple example with two tasks}

In Figure \ref{fig:ex1} I show a simple example of the Rate Monotonic
schedule of two simple tasks, followed by the code that generated it.
To draw the grid, with the numbers, you have to use the
\texttt{RTGrid} environment:
\begin{verbatim}
\begin{RTGrid}[options]{n}{t}
...
\end{RTGrid}
\end{verbatim}
\noindent where \texttt{n} is the number of horizontal axis (one per
task, in this case), and \texttt{t} is the length of the axis in time
units. This also draws the task labels on the left, and the numbering
on the bottom.

Every job arrival is depicted with an upward arrow; a deadline is
depicted by a downward arrow (not very visible here, since it concides
with the next arrival, see Figure \ref{fig:ex1c} for deadlines
different from periods). The task execution is depicted by a gray box.

The arrival of a job and the corresponding deadline can be obtained by
using the following commands:
\begin{verbatim}
\TaskArrival{i}{t}
\TaskArrDeadl{i}{t}{reld}
\end{verbatim}
\noindent where \texttt{i} is the task index (from 1 to \texttt{n}
included), \texttt{t} is the arrival time, and \texttt{reld} is the
relative deadline; an absolute deadline will be drawn at \texttt{t +
  reld}.

In this example there are a lot of repetitions. These can be avoided
if you use the \texttt{multido} macro from the \texttt{multido} package, as shown in the example of
Figure \ref{fig:ex1a}.

To draw the execution rectangle, you can use the following command:
\begin{verbatim}
\TaskExecution{i}{t1}{t2}
\TaskExecDelta{i}{t}{delta}
\end{verbatim}
The first one is used to draw an execution rectangle of height 1-unit
for the \texttt{i}-th task from \texttt{t1} to \texttt{t2}. The second
command draws a rectangle from \texttt{t} to \texttt{t+delta}.

In Figure \ref{fig:ex1b}, you can see how to only draw arrival upward
arrows, and how to specify offsets. Finally, in Figure \ref{fig:ex1c}
you can see an example with 2 tasks with relative deadlines different
from periods (the so-called \emph{constrained deadline tasks}).

\begin{figure}[!htbp]
  \centering
  % 2 tasks, for 20 units of time
  % we specify the width (10cm is the default
  % value, so we will stop specifying it from now on)
  \begin{RTGrid}[width=10cm]{2}{20}
    %% the first job of task 1 arrives at time 0, 
    %% with a relative deadline of 4 
    \TaskArrDead{1}{0}{4}     
    %% the second job arrives at time 4
    \TaskArrDead{1}{4}{4}
    %% etc
    \TaskArrDead{1}{8}{4}
    \TaskArrDead{1}{12}{4}
    \TaskArrDead{1}{16}{4}

    %% the task executes in intervals [0,1], [4,5], etc.
    \TaskExecution{1}{0}{1}
    \TaskExecution{1}{4}{5}
    \TaskExecution{1}{8}{9}
    \TaskExecution{1}{12}{13}
    \TaskExecution{1}{16}{17}

    %% the second task
    \TaskArrDead{2}{0}{4}
    \TaskArrDead{2}{6}{4}
    \TaskArrDead{2}{12}{4}
    \TaskExecution{2}{1}{4}
    \TaskExecution{2}{6}{8}
    \TaskExecution{2}{9}{10}
    \TaskExecution{2}{13}{16}
  \end{RTGrid}
\begin{verbatim}
  % 2 tasks, for 20 units of time
  % we specify the width (10cm is the default
  % value, so we will stop specifying it from now on)
  \begin{RTGrid}[width=10cm]{2}{20}
    %% the first job of task 1 arrives at time 0, 
    %% with a relative deadline of 4 
    \TaskArrDead{1}{0}{4}     
    %% the second job arrives at time 4
    \TaskArrDead{1}{4}{4}
    %% etc
    \TaskArrDead{1}{8}{4}
    \TaskArrDead{1}{12}{4}
    \TaskArrDead{1}{16}{4}

    %% the task executes in intervals [0,1], [4,5], etc.
    \TaskExecution{1}{0}{1}
    \TaskExecution{1}{4}{5}
    \TaskExecution{1}{8}{9}
    \TaskExecution{1}{12}{13}
    \TaskExecution{1}{16}{17}

    %% the second task
    \TaskArrDead{2}{0}{4}
    \TaskArrDead{2}{6}{4}
    \TaskArrDead{2}{12}{4}
    \TaskExecution{2}{1}{4}
    \TaskExecution{2}{6}{8}
    \TaskExecution{2}{9}{10}
    \TaskExecution{2}{13}{16}
  \end{RTGrid}
\end{verbatim}
  \caption{Two tasks, with deadline equal to period, RM scheduling}
  \label{fig:ex1}
\end{figure}

\begin{figure}[!htbp]
  \centering
  \begin{RTGrid}{2}{20}
    \multido{\n=0+4}{5}{        % 5 instances of period 4 
      \TaskArrDead{1}{\n}{4}    % draws the arrival and deadline
      \TaskExecDelta{1}{\n}{1}  % draws execution (highest priority), 
                                % from \n to \n+1
    }
 
    \multido{\n=0+6}{3}{        % 3 instances of period 6 
      \TaskArrDead{2}{\n}{6}    % draws the arrival and deadline
    }
    % no simple formula for lowest priority, sorry!
    \TaskExecution{2}{1}{4}
    \TaskExecution{2}{6}{8}
    \TaskExecution{2}{9}{10}
    \TaskExecution{2}{13}{16}    
  \end{RTGrid}

\begin{verbatim}
  \begin{RTGrid}{2}{20}
    \multido{\n=0+4}{5}{        % 4 instances of period 4 
      \TaskArrDead{1}{\n}{4}    % draws the arrival and deadline
      \TaskExecDelta{1}{\n}{1}  % draws execution (highest priority), 
                                % from \n to \n+1
    }
 
    \multido{\n=0+6}{3}{        % 3 instances of period 6 
      \TaskArrDead{2}{\n}{6}    % draws the arrival and deadline
    }
    % no simple formula for lowest priority, sorry!
    \TaskExecution{2}{1}{4}
    \TaskExecution{2}{6}{8}
    \TaskExecution{2}{9}{10}
    \TaskExecution{2}{13}{16}    
  \end{RTGrid}
\end{verbatim}
  \caption{Using multido to avoid repetitions}
  \label{fig:ex1a}
\end{figure}

\begin{figure}[!htbp]
  \centering
  \begin{RTGrid}{3}{14}
    \multido{\n=0+3}{4}{        % 4 instances of period 3, starting from 0 
      \TaskArrival{1}{\n}       % draws only the arrival
      \TaskExecDelta{1}{\n}{1}  % draws execution (highest priority), 
                                % from \n to \n+1
    }
 
    \multido{\n=3+4}{3}{        % 3 instances of period 4, starting from 3 
      \TaskArrival{2}{\n}       % draws only the arrival
    }
    \TaskExecDelta{2}{4}{1}
    \TaskExecDelta{2}{7}{1}
    \TaskExecDelta{2}{11}{1}

    \multido{\n=1+5}{3}{        % 3 instances of period 5, starting from 1 
      \TaskArrival{3}{\n}       % draws only the arrival
    }
    \TaskExecDelta{3}{1}{1}
    \TaskExecDelta{3}{8}{1}
    \TaskExecDelta{3}{12}{1}
  \end{RTGrid}

\begin{verbatim}
  \begin{RTGrid}{3}{14}
    \multido{\n=0+3}{4}{        % 4 instances of period 3 
      \TaskArrival{1}{\n}       % draws only the arrival
      \TaskExecDelta{1}{\n}{1}} % draws execution (highest priority), 
                                % from \n to \n+1
 
    \multido{\n=3+4}{3}{        % 3 instances of period 4, starting from 3 
      \TaskArrival{2}{\n}}      % draws only the arrival

    \TaskExecDelta{2}{4}{1}
    \TaskExecDelta{2}{7}{1}
    \TaskExecDelta{2}{11}{1}

    \multido{\n=1+5}{3}{        % 3 instances of period 5, starting from 1 
      \TaskArrival{3}{\n}}      % draws only the arrival

    \TaskExecDelta{3}{1}{1}
    \TaskExecDelta{3}{8}{1}
    \TaskExecDelta{3}{12}{1}
  \end{RTGrid}
\end{verbatim}
  \caption{Three tasks with offsets, and only arrivals with no deadlines}
  \label{fig:ex1b}
\end{figure}

\begin{figure}[!htbp]
  \centering
  \begin{RTGrid}[width=8cm]{2}{15}
    \multido{\n=0+6}{3}{
    \TaskArrDead{1}{\n}{3}}
    \multido{\n=2+8}{2}{
    \TaskArrDead{2}{\n}{5}}
  \end{RTGrid}
\begin{verbatim}
    \multido{\n=0+6}{3}{
    \TaskArrDead{1}{\n}{3}}
    \multido{\n=2+8}{2}{
    \TaskArrDead{2}{\n}{5}}
\end{verbatim}
  \caption{Deadlines less than periods}
  \label{fig:ex1c}
\end{figure}

It is also possible to visualise preempted tasks with a hatched fill
style. An example is in Figure~\ref{fig:resp-time} that uses command
\texttt{TaskRespTime}. 

\begin{figure}
  \centering
  \begin{RTGrid}{2}{20}
    \multido{\n=0+4}{5}{        % 5 instances of period 4 
      \TaskArrDead{1}{\n}{4}    % draws the arrival and deadline
      \TaskExecDelta{1}{\n}{1}  % draws execution (highest priority), 
                                % from \n to \n+1
    }
 
    \multido{\n=0+6}{3}{        % 3 instances of period 6 
      \TaskArrDead{2}{\n}{6}    % draws the arrival and deadline
    }

    \TaskRespTime{2}{0}{4}
    \TaskExecution{2}{1}{4}
    \TaskRespTime{2}{6}{4}
    \TaskExecution{2}{6}{8}
    \TaskExecution{2}{9}{10}
    \TaskRespTime{2}{12}{4}
    \TaskExecution{2}{13}{16}    
  \end{RTGrid}  
\begin{verbatim}
  \begin{RTGrid}{2}{20}
    \multido{\n=0+4}{5}{         
      \TaskArrDead{1}{\n}{4}    
      \TaskExecDelta{1}{\n}{1}}
    \multido{\n=0+6}{3}{        
      \TaskArrDead{2}{\n}{6}}

    \TaskRespTime{2}{0}{4}    % draws the hatched rectangle in [0,4]
    \TaskExecution{2}{1}{4}   % draws execution (over the previous rectangle)
    \TaskRespTime{2}{6}{4}    % draws the hatched rectangle in [6,10]
    \TaskExecution{2}{6}{8}   % draws execution
    \TaskExecution{2}{9}{10}  % draws execution
    \TaskRespTime{2}{12}{4}   % draws the hatched rectangle in [12,16]
    \TaskExecution{2}{13}{16} % draws execution   
  \end{RTGrid}  
\end{verbatim}
  \caption{Example with TaskRespTime}
  \label{fig:resp-time}
\end{figure}


\subsection{Controlling visualization}

It is possible to specify many options in the \texttt{RTGrid}
environment. Maybe you don't like the grid: then, you can decide to
not visualise it as in Figure \ref{fig:ex2}, where we also removed the
task symbols.
\begin{figure}[!htbp]
  \centering
  %% no grid and no symbols
  \begin{RTGrid}[nogrid=1,nosymbols=1]{2}{20}
    \multido{\n=0+4}{5}{         
      \TaskArrDead{1}{\n}{4}    
      \TaskExecDelta{1}{\n}{1}}
    \multido{\n=0+6}{3}{         
        \TaskArrDead{2}{\n}{6}}
    \TaskExecution{2}{1}{4}
    \TaskExecution{2}{6}{8}
    \TaskExecution{2}{9}{10}
    \TaskExecution{2}{13}{16}        
  \end{RTGrid}
\begin{verbatim}
  %% no grid and no symbols
  \begin{RTGrid}[nogrid=1,nosymbols=1]{2}{20}
    \multido{\n=0+4}{5}{         
      \TaskArrDead{1}{\n}{4}    
      \TaskExecDelta{1}{\n}{1}}
    \multido{\n=0+6}{3}{         
        \TaskArrDead{2}{\n}{6}}
    \TaskExecution{2}{1}{4}
    \TaskExecution{2}{6}{8}
    \TaskExecution{2}{9}{10}
    \TaskExecution{2}{13}{16}        
  \end{RTGrid}
\end{verbatim}
  \caption{Removing visualization of the grid and of the task names}
  \label{fig:ex2}
\end{figure}

The next figure \ref{fig:ex2a} uses different task symbols, does not
show the numbers on the time line, and the color of the boxes that
denote the execution of the second instance of the second task are
changed to red. Also, I am changing the width, so the figure looks
smaller. Notice that you can directly specify colors using the TikZ
 way (color!percentage for example).

\begin{figure}[!htbp]
  \centering
  %% specify 1) no numbers on the time line, 2) a different symbol, 3)
  %% a different size of the symbol using latex size commands (default is \normalsize).
  %% Notice that you should not use the math mode in the
  %% specification of the symbol, as the symbol is already used in a
  %% math environment inside the macro
  \begin{RTGrid}[width=8cm,symbol=\gamma,nonumbers=1,labelsize=\small]{2}{20}
    \multido{\n=0+4}{5}{         
      \TaskArrDead{1}{\n}{4}    
      \TaskExecDelta{1}{\n}{1}}
    \multido{\n=0+6}{3}{         
      \TaskArrDead{2}{\n}{6}    
    }
    %% here, the border changes to cyan, and the fill to white
    \TaskExecution[linecolor=cyan,color=white]{2}{1}{4}
    %% the next two boxes are filled with red instead of gray
    \TaskExecution[color=red]{2}{6}{8}
    \TaskExecution[color=red!50]{2}{9}{10}
    \TaskExecution{2}{13}{16}        
  \end{RTGrid}

\begin{verbatim}
  %% specify 1) no numbers on the time line, 2) a different symbol, 3)
  %% a different size of the symbol (default is \normalsize).
  %% Notice that you should not use the math mode in the
  %% specification of the symbol, as the symbol is already used in a
  %% math environment inside the macro
  \begin{RTGrid}[symbol=\gamma,nonumbers=1,labelsize=\Large]{2}{20}
    \multido{\n=0+4}{5}{         
      \TaskArrDead{1}{\n}{4}    
      \TaskExecDelta{1}{\n}{1}}
    \multido{\n=0+6}{3}{         
      \TaskArrDead{2}{\n}{6}    
    }
    %% here, the border changes to cyan, and the fill to white
    \TaskExecution[linecolor=cyan,color=white]{2}{1}{4}
    %% the next two boxes are filled with red instead of gray
    \TaskExecution[color=red]{2}{6}{8}
    \TaskExecution[color=red]{2}{9}{10}
    \TaskExecution{2}{13}{16}        
  \end{RTGrid}
\end{verbatim}
  \caption{Different symbols (with \textbackslash Large size), no numbers, a different
    task color}
  \label{fig:ex2a}
\end{figure}

Do you want to specify an arbitrary symbol at a certain row?
No problem! See the example in Figure \ref{fig:ex2b}. Here we use the command:
\begin{verbatim}
\RowLabel{i}{label}
\end{verbatim}
which writes the \texttt{label} at the specified row (index 1 stays at
the top). Here we show also how to specify an arbitrary starting
number in the time line, using the \texttt{numoffset=12} option.

\begin{figure}[!htbp]
  \centering
  %% specify 1) no numbers on the time line, 2) number starting from
  %% 12
  \begin{RTGrid}[nosymbols=1,numoffset=12]{2}{20}
    %% the symbol for the first row
    \RowLabel{1}{Server}
    %% the symbol for the second row
    \RowLabel{2}{$\Pi_2$}
    \multido{\n=0+4}{5}{         
      \TaskArrDead{1}{\n}{4}    
      \TaskExecDelta{1}{\n}{1}}
    \multido{\n=0+6}{3}{         
      \TaskArrDead{2}{\n}{6}
    }
    \TaskExecution{2}{1}{4}
    \TaskExecution{2}{6}{8}
    \TaskExecution{2}{9}{10}
    \TaskExecution{2}{13}{16}        
  \end{RTGrid}
\begin{verbatim}
  %% specify 1) no numbers on the time line, 2) number starting from 12
  \begin{RTGrid}[nosymbols=1,numoffset=12]{2}{20}
    %% the symbol for the first row
    \RowLabel{1}{Server}
    %% the symbol for the second row
    \RowLabel{2}{$\Pi_2$}
    \multido{\n=0+4}{5}{         
      \TaskArrDead{1}{\n}{4}    
      \TaskExecDelta{1}{\n}{1}}
    \multido{\n=0+6}{3}{         
      \TaskArrDead{2}{\n}{6}
    }
    \TaskExecution{2}{1}{4}
    \TaskExecution{2}{6}{8}
    \TaskExecution{2}{9}{10}
    \TaskExecution{2}{13}{16}        
  \end{RTGrid}
\end{verbatim}
  \caption{Arbitrary symbols with an appropriate offset, no grid, numbering starting from 12}
  \label{fig:ex2b}
\end{figure}

% In the last example (Figure \ref{fig:ex2c}), we show an empty grid in
% which we specify width and height.

% \begin{figure}[!htbp]
%   \centering
%   %% 3 tasks, 10 units of time
%   \begin{RTGrid}[width=12cm, height=4cm]{3}{10}
    
%   \end{RTGrid}

% \begin{verbatim}
%   %% 3 tasks, 10 units of time
%   \begin{RTGrid}[width=12cm, height=4cm]{3}{10}
    
%   \end{RTGrid}
% \end{verbatim}
%   \caption{Empty grid with strange width and height}
%   \label{fig:ex2c}
% \end{figure}

\subsection{Highlighting and labeling objects}

Sometimes it may be important to say that one task has caused the
activation of another task. You can use the following command, as
shown in Figure \ref{fig:ex3a}:
\begin{verbatim}
\Activation{i}{t1}{j}{t2}
\end{verbatim}
which draws an arrow from the baseline of task \texttt{i} at time
\texttt{t1} to the baseline of task \texttt{j} at time \texttt{t2}.
Also, you can put an arbitrary label inside a shadow box with the
following command:
\begin{verbatim}
\Label{y}{x}{label}
\end{verbatim}
which draws a boxed label at position \texttt{x,y} in the grid.

Finally, it is possible to draw a rectangular box with rounded corners
to highlight a portion of the schedule with \texttt{RTBox}:
\begin{verbatim}
\RTBox{t1}{t2}
\end{verbatim}

\begin{figure}[!htbp]
  \centering
  \begin{RTGrid}{2}{20}
    \RTBox{12}{16}
    \multido{\n=0+6}{4}{
      \TaskArrival{1}{\n}
      \TaskExecDelta{1}{\n}{2}}
    \TaskArrival{2}{10}
    \TaskExecDelta[exeheight=1.5]{2}{10}{3}
    \Activation{1}{8}{2}{10}
    \Label{6}{7}{$\delta$}
  \end{RTGrid}
\begin{verbatim}
  \begin{RTGrid}{2}{20}
    \RTBox{12}{16}
    \multido{\n=0+6}{4}{
      \TaskArrival{1}{\n}
      \TaskExecDelta{1}{\n}{2}}
    \TaskArrival{2}{10}
    \TaskExecDelta[exeheight=1.5]{2}{10}{3}
    \Activation{1}{8}{2}{10}
    \Label{6}{7}{$\delta$}
  \end{RTGrid}
\end{verbatim}
  \caption{Activation (from one task to another one), and an arbitrary label}
  \label{fig:ex3a}
\end{figure}

Notice that the order with which the objects are drawn is exactly the
same as the order in which they are specified in the code, excepted 
for horizontal axes, arrivals and deadlines that are always drawn on the foreground.
 For example, in Figure \ref{fig:ex3a}, the executions of all the tasks are
drawn on top of the box. You can try to move the \texttt{RTBox}
command at the end to see what happens.

\subsection{Priority Inheritance}

An example of task locking/unlocking and the use of the Priority
Inheritance Protocol is shown in Figure \ref{fig:pi}. Here, task
$\tau_3$ locks resource $S$ at time $t=2$. This is obtained by using
command:
\begin{verbatim}
\TaskLock{3}{2}{S}
\end{verbatim}
Unlock is similarly obtained by using command: 
\begin{verbatim}
\TaskUnlock{3}{7}{S}
\end{verbatim}

Task $\tau_1$ tries to lock the same resource at time $t=5$. The
priority of $\tau_1$ is then inherited by $\tau_3$: the inheritance
rule is depicted by using a dashed tick arrow from the baseline of
$\tau_1$ to $\tau_3$, using command:
\begin{verbatim}
\Inherit{1}{3}{4}
\end{verbatim}
The fact that $\tau_3$ is executing inside a critical section is
denoted by putting a label inside the execution block, using the
following command:
\begin{verbatim}
\TaskExecution[color=white,execlabel=S]{3}{4}{5}
\end{verbatim}

\begin{figure}
  \centering
  \begin{RTGrid}[width=12cm]{3}{25}
    \TaskArrDead{3}{0}{20}
    \TaskExecution{3}{0}{2}
    \TaskLock{3}{2}{S}
    \TaskExecution[color=white,execlabel=S]{3}{2}{3}
    \TaskArrDead{1}{3}{9}  
    \TaskExecution{1}{3}{4}
    \TaskLock{1}{4}{S}
    \Inherit{1}{3}{4}
    \TaskExecution[color=white,execlabel=S]{3}{4}{5}
    \TaskArrDead{2}{5}{12}
    \TaskExecution[color=white,execlabel=S]{3}{5}{7}
    \TaskUnlock{3}{7}{S}
    \TaskExecution[color=white,execlabel=S]{1}{7}{9}
    \TaskUnlock{1}{9}{S}
    \TaskExecution{1}{9}{10}
    \TaskExecution{2}{10}{15}
    \TaskExecution{3}{15}{17}
  \end{RTGrid}
  \caption{Task blocking on resources: the Priority Inheritance Protocol}
  \label{fig:pi}
\begin{verbatim}
  \begin{RTGrid}[width=12cm]{3}{25}
    \TaskArrDead{3}{0}{20}
    \TaskExecution{3}{0}{2}
    \TaskLock{3}{2}{S}
    \TaskExecution[color=white,execlabel=S]{3}{2}{3}
    \TaskArrDead{1}{3}{9}  
    \TaskExecution{1}{3}{4}
    \TaskLock{1}{4}{S}
    \Inherit{1}{3}{4}
    \TaskExecution[color=white,execlabel=S]{3}{4}{5}
    \TaskArrDead{2}{5}{12}
    \TaskExecution[color=white,execlabel=S]{3}{5}{7}
    \TaskUnlock{3}{7}{S}
    \TaskExecution[color=white,execlabel=S]{1}{7}{9}
    \TaskUnlock{1}{9}{S}
    \TaskExecution{1}{9}{10}
    \TaskExecution{2}{10}{15}
    \TaskExecution{3}{15}{17}
    \end{RTGrid}
\end{verbatim}
  \caption{Priority Inheritance example}
  \label{fig:ex4}
\end{figure}

\end{document}
%%% Local Variables: 
%%% mode: latex
%%% TeX-master: t
%%% End: