\usepackage{todonotes}
\usepackage[backend=biber,style=alphabetic,sortcites=true]{biblatex}
\usepackage{tabularx}
+\usepackage{textcomp}
\addbibresource{rpp_simulink.bib}
% header
\section*{Revision history}
+{\small
\noindent\begin{tabularx}{\linewidth}{|l|l|l|X|}
\rowcolor[gray]{0.9}\hline
Revision & Date & Author(s) & Comments \\ \hline
Added support for Eaton Hydraulics
Controller board (TMS570LS1227).
\\\hline
-\end{tabularx}
+ 0.5.5 & 2015-08-27 & Sojka, Horn & rpp-lib: HAL merged into DRV
+ layer, FreeRTOS upgraded to version 8.2.2.
+ \\\hline
+
+ 0.6 & 2015-09-03 & Sojka & Multi-rate models can be
+ compiled in multi-tasking mode
+ (see
+ sec.~\ref{sec-singlet-multit-modes}
+ and \ref{sec:mult-multi-thre}).
+ Added board init block (sec.
+ \ref{sec:block:sfunction_hydctr_init.c}).
+ Documented halcogen directory in
+ sec.~\ref{sec-rpp-lib-subdirectory-content-description}.
+ \\\hline
+
+ 0.6a & 2015-09-11 & Sojka & Removed reference of
+ Simulink blocks that are not
+ part of Eaton distribution.
+ \\\hline
+
+ 0.7 & 2015-10-05 & Sojka & Simulink GIO blocks
+ (sec.
+ \ref{sec:block:sfunction_gio_in.c},
+ \ref{sec:block:sfunction_gio_out.c})
+ have different parameters and
+ support certain SPI5 pins on the
+ tms570\_hydctr board. Parameters
+ of old GIO blocks are
+ automatically transformed to the
+ new ones.
+
+ Added section \ref{sec:board-init-hydctr}: ``Hydraulics controller
+ initialization demo''.
+ \\\hline
+\end{tabularx}
+}
\tableofcontents
\newpage
low-level run-time C library and a tool for interactive testing of
hardware and software functionality.
-Originally, the RPP project was created for a custom TMS570-based board
-and the port to other platforms such as RM48 HDK and TMS570 HDK
-development kits. Porting to other platforms was done under a contract
-from Eaton Corporation.
+Originally, the RPP project was created for a custom TMS570-based
+board. Subsequently, it was ported to other board such as RM48 HDK and
+TMS570 HDK development kits under a contract from Eaton Corporation.
The document contains step-by-step instructions for installation of
development tools, information about Simulink Coder configuration,
% exclusively on the bottom layer, not on any lower level layer (except for a
% couple of exceptions).
\item Each layer should provide a unified layer interface
- (\texttt{rpp.h}, \texttt{drv.h}, \texttt {hal.h}, \texttt{sys.h} and
+ (\texttt{rpp.h}, \texttt{drv.h}, \texttt{sys.h} and
\texttt{os.h}), so that higher layers depend on the lower layer's interface
and not on individual elements from that layer.
\end{compactitem}
As a consequence of this division the source code files and interface files are
placed in private directories like \texttt{drv/din.h}. With this organization
user applications only needs to include the top layer interface files (for
-example \texttt{rpp/rpp\_can.h}) to be able to use the selected library API.
+example \texttt{rpp/rpp.h}) to be able to use the selected library API.
The rest of the section provides basic description of each layer.
\subsection{Operating System layer}
\label{sec-operating-system-layer}
-This is an interchangeable operating system layer containing the
+This is an interchangeable operating system (OS) layer containing the
FreeRTOS source files. The system can be easily replaced by another
version. For example it is possible to compile the RPP library for
Linux (using POSIX version of the FreeRTOS), which can be desirable
The following FreeRTOS versions are distributed:
\begin{description}
- \item[6.0.4\_posix] POSIX version, usable for compilation of the library
-for Linux system.
- \item[7.0.2] Preferred version of the FreeRTOS, distributed by
-Texas Instruments. This version has been tested and is used in the current
-version of the library.
- \item[7.4.0] Newest version distributed by the Texas Instruments.
- \item[7.4.2] Newer version available from FreeRTOS pages. Slightly
-modified to run on \tgname{} MCU.
+\item[6.0.4\_posix] POSIX version, usable for compilation of the
+ library for Linux system.
+\item[8.2.2] Currently used FreeRTOS version. This is the version
+ downloaded from FreeRTOS.org with changes in directory structure.
+ Namely, include files have added the \emph{os/} prefix and platform
+ dependent code (portable) for \tgname{} is copied to the same
+ directory as platform independent code.
\end{description}
-\noindent
-Both 7.4.x version were tested and work, but the testing was not so
-extensive as with the used 7.0.2 version.
-
\subsection{System Layer}
\label{sec-system-layer}
This layer contains system files with data types definitions, clock definitions,
folder.
Large part of this layer was generated by the HalCoGen tool (see
-Section~\ref{sec-halcogen}).
-
-\subsection{HAL abstraction layer}
-\label{sec-hal-abstraction-layer}
-Hardware Abstraction Layer (HAL) provides an abstraction over the real
-hardware. For example imagine an IO port with 8 pins. First four pins
-are connected directly to the GPIO pins on the MCU, another four pins
-are connected to an external integrated circuit, communicating with
-the MCU via SPI. This layer allows to control the IO pins
-independently of how that are connected to the MCU, providing a single
-unified API.
-
-Note that this functionality is not needed in the current version for
-\tgtBoardName, because all IOs are controlled directly by GPIO pins.
-
-As a result, the higher layers do not have to know anything about the
-wiring of the peripherals, they can just call read, write or configure
-function with a pin name as a parameter and the HAL handles all the
-details.
-
-The source files can be found in
-\texttt{$\langle$rpp\_lib$\rangle$/rpp/src/hal} and the header files can
-be found in \texttt{$\langle$rpp\_lib$\rangle$/rpp/include/hal} folder.
+Section~\ref{sec-halcogen}). Some files were then modified by hand.
\subsection{Drivers layer}
\label{sec-drivers-layer}
The Drivers layer contains code for controlling the RPP peripherals.
Typically, it contains code implementing IRQ handling, software
queues, management threads, etc. The layer benefits from the lower
-layers thus it is not too low level, but still there are some
+layer thus it is not too low level, but still there are some
peripherals like ADC, which need some special procedure for
initialization and running, that would not be very intuitive for the
-user.
+typical end user.
The source files can be found in
\texttt{$\langle$rpp\_lib$\rangle$/rpp/src/drv} and the header files can
The following sections describe how to start working with individual
packages.
+\ifx\tgtId\tgtIdTMSRPP
+\subsection{Getting sources from git repository}
+\begin{verbatim}
+git clone --recursive git@rtime.felk.cvut.cz:jenkicar/rpp-simulink
+\end{verbatim}
+If you get release packages, follow the instructions in the next sections.
+\fi
+
\subsection{rpp-simulink}
\label{sec-rpp-simulink-installation}
This section describes how to install the rpp-simulink project, which
\item Configure the compiler \#include search path to contain
project's \texttt{include} directory, \penalty-100
- \texttt{\$\{RPP\_LIB\_ROOT\}/os/7.0.2/include} and
+ \texttt{\$\{RPP\_LIB\_ROOT\}/os/8.2.2/include} and
\texttt{\$\{RPP\_LIB\_ROOT\}/rpp/include}, in that order.
\includegraphics[scale=.43]{images/base_5.png}
use. In the Matlab command window run the \texttt{mex -setup}
command and select the native C compiler.
-\begin{lstlisting}[basicstyle=\tt\footnotesize]
+\begin{lstlisting}[basicstyle=\texttt\footnotesize]
>> mex -setup
Welcome to mex -setup. This utility will help you set up
\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}
\begin{compactitem}
\item User documentation should be placed in header files, not in source
code, and should be Doxygen formatted using autobrief. Documentation for each
-function present is mandatory.
+function present is mandatory and must mention whether the function is
+thread safe or not.
\item Function declarations in the headers files is for public functions
only. Do not declare local/static/private functions in the header.
\item Documentation in source code files should be non-doxygen formatted
board, including the Simulink models and test suite. It includes
instructions for the CGT Linker about target memory layout and where
to place various code sections.
+
+\item[halcogen/] HalCoGen project files for the supported boards and
+ scripts for automated conversion of HalCoGen-generated files for use
+ in rpp-lib.
+
+ Note: This is work in progress. Currently only ``pinmux'' files for
+ tms570\_hydctr board were produced by the scripts here.
+
\item[os/] OS layers directory. See
Section~\ref{sec-operating-system-layer} for more information about
currently available operating system versions and
\begin{compactitem}
\item Configure include search path to contain the directory of
used FreeRTOS version, e.g.
- \texttt{\repo/os/7.0.2/include}. See Section
+ \texttt{\repo/os/8.2.2/include}. See Section
\ref{sec-software-architecture}.
\item Include \texttt{rpp/rpp.h} header file or just the needed
peripheral specific header files such as \texttt{rpp/can.h}.
\section{Changing operating system}
\label{sec-changing-os}
The C Support Library contains by default the FreeRTOS operating
-system in version 7.0.2. This section describes what is necessary to
+system in version 8.2.2. This section describes what is necessary to
change in the library and other packages in order to replace the
operating system.
the operating system header files.
Current implementation for FreeRTOS includes a header file
-\texttt{\repo/rpp/lib/os/\-7.0.2\-include/os.h}, which
+\texttt{\repo/rpp/lib/os/\-8.2.2\-include/os.h}, which
contains all necessary declarations and definitions for the FreeRTOS.
We suggest to provide a similar header file for your operating system as
well.
template for generation of the \texttt{ert\_main.c} file, containing
the main function, has to be modified to use proper functions for task
creation, task timing and semaphores. The template is stored in
-\texttt{\repo/rpp/rpp/rpp\_srmain.tlc} file.
+\texttt{\repo/rpp/rpp/rpp\_mrmain.tlc} file.
\chapter{Simulink Coder Target}
\label{chap-simulink-coder-target}
\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
\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
\clearpage
\input{block_desc.tex}
+\newpage
\section{Compilation}
\label{sec-simulink-compilation}
The first step, before any attempt to compile demo or other models, is to compile the S-Functions of the RPP blocks. The S-Functions are compiled during the Configuring Simulink for RPP, described in Section \ref{sec-configuration-simulink-for-rpp}. If you want to recompile the S-Functions without reconfiguring the Simulink, open the Matlab and run those commands in the Matlab commad line:
up-to-date.
The YAML documentation block may look like this:
-\begin{lstlisting}[language=c,basicstyle=\tt\footnotesize]
+\begin{lstlisting}[language=c,basicstyle=\texttt\footnotesize]
/*
%YAML 1.2
---
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:}
different rate. This is implemented with multiple Simulink tasks, each
running at different rate. In the generated code, these tasks are
called from a singe thread and therefore no task can preempt another
-one.
+one. See Section \ref{sec-singlet-mode} for more details.
The state of each LED is printed to the Serial Communication Interface
(115200-8-N-1) when toggled.
\label{tab:multirate_st_led_desc}
\end{center}
+\subsection{Multi-rate MultiTasking demo}
+\label{sec:mult-multi-thre}
+
+\begin{figure}[H]\begin{center}
+\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 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 also printed to the Serial Communication
+Interface (115200-8-N-1) when toggled.
+
+\begin{center}
+ \begin{tabular}{lll}
+ \rowcolor[gray]{0.9}
+ LED & pin & rate [s] \\
+ 1 & NHET1\_25 & 0.3 \\
+ 2 & NHET1\_05 & 0.5 \\
+ 3 & NHET1\_00 & 1.0 \\
+ \end{tabular}
+ \captionof{table}{LEDs connection and rate}
+ \label{tab:multirate_mt_led_desc}
+\end{center}
+
+\subsection{Hydraulics controller initialization demo}
+\label{sec:board-init-hydctr}
+\begin{figure}[H]
+ \centering
+ \includegraphics[scale=0.45]{images/demo_board_init_hydctr.png}
+ \caption{board\_init\_hydctr demo}
+ \label{fig:board_init_hydctr}
+\end{figure}
+
+\paragraph{Description}
+
+This demo shows how to use the \emph{Board Init} block to initialize
+SPI devices on the Hydraulics Controller board. Additionally, it shows
+how to use unused SPI pins on the MCU as general-purpose IOs. If both
+Board Init and GIO SPI blocks are used together, care must be taken
+about the order in which the blocks are initialized. GIO blocks that
+represent SPI pins must be initialized \emph{after} the Board Init
+block. This can be ensured by giving the GIO blocks higher priority
+than the Board Init block.
\chapter{Command line testing tool}
\label{chap-rpp-test-software}
\textbf{115200-8-N-1}. When the software starts, the received welcome message
and prompt should look like:
-
+\bigskip
\ifx\tgtId\tgtIdTMSRPP
-\begin{verbatim}
-Rapid Prototyping Platform v00.01-001
-Test Software version v0.2-261-gb6361ca
-CTU in Prague 2014
--->
-\end{verbatim}
+\noindent\texttt{Rapid Prototyping Platform v00.01-001\\
+Test Software version \input{version.tex}\\
+CTU in Prague 2014\\
+-->
+}
\else
-\begin{verbatim}
-Ti HDK \mcuname, FreeRTOS 7.0.2
-Test Software version eaton-0.1-beta-8-g91419f5
-CTU in Prague 10/2014
--->
-\end{verbatim}
+\noindent\texttt{Ti HDK \mcuname, FreeRTOS 7.0.2\\
+Test Software version \input{version.tex}\\
+CTU in Prague 10/2014\\
+-->
+}
\fi
+\bigskip
+
Type in command help for a complete list of available command, or help command
for a description of concrete command.
same description is also available in the program itself via the
\texttt{help} command.
+% Pandoc generates \tightlist in its output. Since we don't use pandoc
+% template, we have put its definition here.
+\providecommand{\tightlist}{%
+ \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
+
\input{rpp-test-sw-cmds.tex}
\chapter{Glossary}