doc: Document MultiTasking feature

Initial version from Michal Horn revised by Michal Sojka.

diff --git a/doc/rpp_simulink.tex b/doc/rpp_simulink.tex
index e4ca36692dcc14de77d25cb6733ed2a9d59f115c..96a8c0f8def655a39ac72d746ee675d53bedcf62 100644 (file)
--- a/doc/rpp_simulink.tex
+++ b/doc/rpp_simulink.tex
@@ -1207,7 +1207,19 @@ Section~\ref{sec-running-model-on-hw}.
      \item Solver: \emph{discrete}
      \item Fixed-step size: \emph{Sampling period in seconds. Minimum
          is 0.001.}
-        \item Tasking mode: \textit{SingleTasking}.
+        \item Tasking mode -- choose between the following:
+         \begin{compactitem}
+         \item \textit{Auto} selects SingleTasking modes for
+            single-rate model or MultiTasking mode for multi-rate
+            models. See Section \ref{sec-singlet-multit-modes}
+         \item \textit{SingleTasking} selects SingleTasking mode. See
+            Section \ref{sec-singlet-mode} for details.
+         \item \textit{MultiTasking} select MultiTasking mode. In
+            this mode \textit{Higher priority value indicates higher
+              task priority} should be checked. See Section
+            \ref{sec-multit-mode} for details.
+         \end{compactitem}
+
           \begin{figure}
                 \centering
                 \includegraphics[scale=.45]{images/simulink_solver.png}
@@ -1678,10 +1690,9 @@ board.
 
 \begin{itemize}
 \item Sampling frequencies up to 1\,kHz.
-\item Multi-rate models are executed in a single thread in
-  non-preemptive manner. Support for multi-threaded execution will be
-  available in the final version and will require careful audit of the
-  RPP library with respect to thread-safe code.
+\item Multi-rate models can be executed in a single or multiple OS
+  tasks. Multi-tasking mode allows high-rate tasks to preempt low-rate
+  tasks. See Section \ref{sec-singlet-multit-modes} for more details.
 \item No External mode support yet. We work on it.
 \item Custom compiler options, available via OPTS variable in
   \emph{Make command} at \emph{Code Generation} tab (see Figure
@@ -1790,6 +1801,41 @@ downloader.
        \item[rpp/rpp] Contains set of support script for the Code Generator.
 \end{description}
 
+\section{Tasking modes}
+\label{sec-singlet-multit-modes}
+
+This section describes two different modes (single- and multi-tasking)
+of how generated code of multi-rate models can be executed. Tasking
+mode can be selected for every model in the configuration dialog as
+described in Section \ref{sec-crating-new-model}.
+
+For single-rate models, the mode selection does not matter. For
+multi-rate models, the mode selection becomes important as it may
+influence certain system properties such as safety or performance.
+
+\subsection{SingleTasking mode}
+\label{sec-singlet-mode}
+In this mode all Simulink tasks, defined by their sampling rate, run
+in a single operating system task (thread). This means that the period
+of the highest rate Simulink task cannot be greater than the
+worst-case execution time of all Simulink tasks together. On the other
+hand, using this mode reduces the risk of failures caused by task
+synchronization errors, e.g. race conditions, deadlocks.
+
+\subsection{MultiTasking mode}
+\label{sec-multit-mode}
+
+In this mode every Simulink task, defined by its sampling rate, runs
+in its own operating system task (thread). Thread priorities are
+assigned based on task rates in such a way that tasks with higher
+rates can preempt tasks with lower rates. This means that the period
+of the fastest sampling rate is limited only by the execution time of
+this task and not of all the tasks in the system.
+
+This mode offers more efficient use of system resources (CPU) but
+there is a possibility of failures caused by task synchronization
+errors.
+
 \section{Block Library Overview}
 \label{sec-block-library-overview}
 The Simulink Block Library is a set of blocks that allows Simulink models to use
@@ -2406,13 +2452,13 @@ This demo will print \texttt{Hello Simulink} to the Serial Communication Interfa
 character per second. The output speed is driven by the Simulink model step which is set to one
 second.
 
-\subsection{Multi-rate single thread demo}
+\subsection{Multi-rate SingleTasking demo}
 \label{sec:mult-single-thre}
 
 \begin{figure}[H]\begin{center}
 \noindent
 \includegraphics[scale=.45]{images/demo_multirate_st.png}
-\caption{Multi-rate singlet hread Simulink demo for RPP.}
+\caption{Multi-rate SingleTasking Simulink demo for RPP.}
 \end{center}\end{figure}
 
 \textbf{Description:}
@@ -2445,17 +2491,20 @@ The state of each LED is printed to the Serial Communication Interface
 \noindent
 \includegraphics[scale=.45]{images/demo_multirate_mt.png}
 \caption{Multi-rate MultiTasking Simulink demo for RPP.}
+\label{fig:multitasking-demo}
 \end{center}\end{figure}
 
 \textbf{Description:}
 
-This demo will toggle LEDs on the Hercules Development Kit with
-different rate. This is implemented with multiple Simulink tasks, each
-running at different rate. In the generated code, every subrate task
-runs in its own thread. See Section \ref{sec-multit-mode} for more details.
+This demo toggles LEDs on the Hercules Development Kit with different
+rate (different colors in Figure~\ref{fig:multitasking-demo}). This is
+implemented with multiple Simulink tasks, each running at different
+rate. In the generated code, every subrate task runs in its own
+operating system thread. See Section \ref{sec-multit-mode} for more
+details.
 
-The state of each LED is printed to the Serial Communication Interface
-(115200-8-N-1) when toggled.
+The state of each LED is also printed to the Serial Communication
+Interface (115200-8-N-1) when toggled.
 
 \begin{center}
        \begin{tabular}{lll}