\usepackage{todonotes}
\usepackage[backend=biber,style=alphabetic,sortcites=true]{biblatex}
\usepackage{tabularx}
+\usepackage{textcomp}
\addbibresource{rpp_simulink.bib}
% header
\newcommand{\superscript}[1]{\ensuremath{^{\textrm{\small#1}}}}
\newcommand{\subscript}[1]{\ensuremath{_{\textrm{\small#1}}}}
+% Supported targets - to be used with \ifx\tgtId\tgtIdXXX
+\def\tgtIdTMSHDK{tms570\_hdk}
+\def\tgtIdRMHDK{rm48\_hdk}
+\def\tgtIdTMSRPP{tms570\_rpp}
+\def\tgtIdHydCtr{tms570\_hydctr}
+
+% Include target specific macros etc.
+\input{target_def}
+
\begin{document}
% Title
\HRule
\vspace{0.4cm}
{\huge \bfseries Simulink code generation target for Texas~Instruments
- RM48 platform\par}
+ \tgname{} platform\par}
+\vspace{0.8cm}
+{\Large Version for \tgtBoardName{} board\par}
\vspace{0.4cm}
\HRule \\[1.5cm]
\section*{Revision history}
+{\small
\noindent\begin{tabularx}{\linewidth}{|l|l|l|X|}
\rowcolor[gray]{0.9}\hline
Revision & Date & Author(s) & Comments \\ \hline
cleanup \\ \hline
0.3 & 2015-03-31 & Sojka, Horn & Added sections
- \ref{sec-changing-os}, \ref{sec:adding-new-funct} and \ref{sec:mult-single-thre}, minor updates. \\ \hline
+ \ref{sec-changing-os}, \ref{sec:adding-new-funct} and
+ \ref{sec:mult-single-thre}. Minor
+ updates. \\ \hline
+
+ 0.4 & 2015-04-30 & Sojka, Horn & Added support for TMS570 HDK
+ platform. All RPP software
+ supports multiple
+ platforms by
+ recompilation. \\ \hline
+
+ 0.5 beta & 2015-07-03 & Sojka & Updated section \ref{sec:adding-new-funct}.
+ Added support for Eaton Hydraulics
+ Controller board (TMS570LS1227).
+ \\\hline
+
+ 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
\label{chap-introduction}
This text documents software part of Rapid Prototyping Platform (RPP)
-project for Texas Instruments RM48 safety microcontroller. The
-software consists of code generation target for Simulink Embedded
-Coder, a low-level run-time C library and a tool for interactive
-testing of hardware and software functionality.
+project for Texas Instruments \tgname{} safety microcontroller
+developed by Czech Technical University in Prague (CTU). The software
+consists of code generation target for Simulink Embedded Coder, a
+low-level run-time C library and a tool for interactive testing of
+hardware and software functionality.
-Originally, the RPP project was created for TMS570 microcontroller and
-the port to RM48 was derived from it under a contract with 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,
\section{Background}
\label{sec-background}
-The Rapid Prototyping Platform is an control unit based on TMDSRM48HDK
-development kit from Texas Instruments. Cental to the kit is the
-RM48L952 MCU -- an ARM Cortex R4 based microcontroller developed by
-Texas Instruments. This MCU contains several protective mechanisms
-(two cores in lockstep, error correction mechanisms for SRAM and Flash
-memory, voltage monitoring, etc.) to fulfill the requirements for
-safety critical applications.
-See~\cite{rm48xtechnicalreferencemanual2013} for details.
+In this document, the term \emph{Rapid Prototyping Platform} denotes a
+hardware board and accompanying software. The hardware board is
+\tgtBoardName{} based on ARM Cortex R4 safety microcontroller
+\mcuname{}. This MCU contains several protective mechanisms (two cores
+in lockstep, error correction mechanisms for SRAM and Flash memory,
+voltage monitoring, etc.) to fulfill the requirements for safety
+critical applications. See~\cite{\tgrefman} for details.
In order to develop non-trivial applications for the RPP, an operating
system is necessary. The RPP is based on FreeRTOS -- a simple
another block. This block can implement some clever algorithm and its
output is passed to another block, which sends the computed value as a
message over CAN bus to some other MCU. Such a model can be simulated
-and tested even before the real hardware is available by replacinf the
+and tested even before the real hardware is available by replacing the
input and output blocks with simulated ones. Once the hardware is
ready, C code is automatically generated from the model by a Simulink
Coder. The code is then compiled by the MCU compatible compiler and
\section{Hardware description}
\label{sec-hardware-description}
-This section provides a brief description of the Texas Instrument
-TMDSRM48HDK development kit. For a more detailed information refer to
-\cite{rm48hdkusersguide2013}. The kit is depicted in
-Figure~\ref{fig-board_photo}.
-
-\begin{figure}\begin{center}
- \noindent
- \includegraphics[width=300px]{images/board.png}
- \caption{The TMDSRM48HDK kit \cite[p. 8]{rm48hdkusersguide2013}}
- \label{fig-board_photo}
-\end{center}\end{figure}
-
-Only a subset of peripherals available on the kit is currently
-supported by the RPP software. A block diagram in
-Figure~\ref{fig-blocks} ilustrates the supported peripherals and their
-connection to the MCU, expansion connectors and other components on
-the development kit. For pinout description of the implemented
-peripherals refer the RM48HDK User's Guide
-\cite{rm48hdkusersguide2013}. The main features of supported
-peripherals are provided in the following subsections.
-
-\begin{figure}\begin{center}
- \noindent
- \includegraphics[width=400px]{images/blocks.png}
- \caption{Block diagram of supported peripherals}
- \label{fig-blocks}
-\end{center}\end{figure}
-
-\subsection{Digital Inputs and Outputs (DIN and DOUT)}
-\label{par-digital-inputs-outputs}
- \begin{compactitem}
- \item 46 pins available on Expansion connector J11.
- \item 8 pins available on GIOA
- \item 8 pins available on GIOB
- \item 30 pins available on NHET1. Pins NHET1 6 and NHET1 13 are disabled.
- \item All the pins are configurable as inputs and outputs with different modes:
- \begin{compactitem}
- \item Push/Pull or Open Drain for Output configuration.
- \item Pull up, Pull down or tri-stated for Input configuration.
- \end{compactitem}
- \item Some of the pins are connected to LEDs or to a button. See
- Figure~\ref{fig-blocks} or refer to~\cite{rm48hdkusersguide2013}.
- \end{compactitem}
-
-\subsection{Analog Input (ADC)}
-\label{par-analog-input}
-\vbox{% Keep this on the same page
- \begin{compactitem}
- \item 16 channels available on the Expansion connector J9.
- \item Range for 0 -- 5 Volts.
- \item 12 bits resolution.
- \end{compactitem}
-}
-\subsection{CAN bus (CAN)}
-\label{par-can}
-\begin{compactitem}
- \item Up to three CAN ports
- \begin{compactitem}
- \item 2 ports equipped with physical layer CAN transciever
- connected to J2 and J3 connectors.
- \item All 3 ports available as link-level interface on the
- Expansion connector J11.
- \end{compactitem}
- \item High speed.
- \item Recovery from errors.
- \item Detection of network errors.
-\end{compactitem}
-
-\subsection{Serial Communication Interface (SCI)}
-\label{par-sci}
-\begin{compactitem}
- \item 1 port available on connector J7.
- \item Configurable baud rate. Tested with 9600 and 115200 bps.
- \item RS232 compatible.
-\end{compactitem}
+\input{hwdesc}
\section{Software architecture}
\label{sec-software-architecture}
% 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{os.h}), so that top layers depends on the layer interface
+ (\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 RM48 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 of
-for TMDSRM48HDK, 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
\item GtkTerm 0.99.7-rc1
\item TI Code Composer Studio 5.5.0.00077
\item Matlab 2013b 64b with Embedded Coder
- \item HalCoGen 4.00 (optionally)
- \item Uncrustify 0.59 (optionally, see Section \ref{sec-compilation})
- \item Doxygen 1.8.4 (optionally, see Section \ref{sec-compiling-api-documentation})
- \item Git 1.7.10.4 (optionally)
+ \item HalCoGen 4.00 (optional)
+ \item Uncrustify 0.59 (optional, see Section \ref{sec-compilation})
+ \item Doxygen 1.8.4 (optional, see Section \ref{sec-compiling-api-documentation})
+ \item Git 1.7.10.4 (optional)
\end{itemize}
\subsection{Windows environment}
\item Bray Terminal v1.9b
\item TI Code Composer Studio 5.5.0.00077
\item Matlab 2013b 64b with Embedded Coder
- \item HalCoGen 4.00 (optionally)
- \item Doxygen 1.8.4 (optionally, see Section \ref{sec-compiling-api-documentation})
- \item Uncrustify 0.59 (optionally, see Section \ref{sec-compilation})
- \item Git 1.9.4.msysgit.2 (optionally)
+ \item HalCoGen 4.00 (optional)
+ \item Doxygen 1.8.4 (optional, see Section \ref{sec-compiling-api-documentation})
+ \item Uncrustify 0.59 (optional, see Section \ref{sec-compilation})
+ \item Git 1.9.4.msysgit.2 (optional)
\end{itemize}
\section{Software tools}
\label{sec-matlab-simulink}
Matlab Simulink is a set of tools, runtime environment and development
environment for Model--Based \cite{modelbasedwiki2013} applications development,
-simulations and generation code for target platforms. Supported Matlab Simulink
+simulations and code generation for target platforms. Supported Matlab Simulink
version is R2013b for 64 bits Linux and Windows. A licence for an Embedded Coder is
necessary to be able to generate code from Simulink models, containing RPP blocks.
The tool is available for Windows at
\begin{quotation}
-\url{http://www.ti.com/tool/halcogen?keyMatch=halcogen&tisearch=Search-EN}
+\url{http://www.ti.com/tool/halcogen}
\end{quotation}
The HalCoGen has been used in early development stage of the RPP
are:
\begin{description}
-\item[rpp-lib] Contains the source code of the RPP library, described
- in Chapter \ref{chap-c-support-library}. If you want to make any
- changes in the drivers or RPP API, this library has to be compiled
- and linked with applications in the other two packages. The library compile
- procedure can be found in Section \ref{sec-compilation}.
\item[rpp-simulink] Contains the source code of Matlab Simulink
blocks, demo models and scripts for downloading the generated
- firmware to the target from Matlab/Simulink. Details can be
+ firmware to the target board from Matlab/Simulink. Details can be
found in Chapter \ref{chap-simulink-coder-target}.
The package also contains the binary of the RPP Library and all its
- headers and other files necessary for building and downloading the
- models.
+ headers and other files necessary for building and downloading
+ Simulink models.
\item[rpp-test-sw] Contains an application for interactive testing and
- control of the RPP board over the serial interface. Details can be
+ control of the \tgtBoardName{} board over the serial interface. Details can be
found in Chapter~\ref{chap-rpp-test-software}.
The package also contains the binary of the RPP Library and all
headers and other files necessary for building and downloading the
application.
+\item[rpp-lib] Contains the source code of the RPP library, described
+ in Chapter \ref{chap-c-support-library}. If you want to make any
+ changes in the drivers or the RPP API, this library has to be
+ compiled and linked with applications in the other two packages.
+ Library compilation is described in Section \ref{sec-compilation}.
\end{description}
The following sections describe how to start working with individual
packages.
-\subsection{rpp-lib}
-\label{sec-rpp-lib-installation}
-
-This section describes how to open the rpp-lib project in Code
-Composer Studio and how to use the resulting static library in an
-application. This is only necessary if you need to modify the library
-for some reason.
-
-\begin{enumerate}
- \item Unzip the \texttt{rpp-lib-version.zip} file.
- \item Open the Code Composer Studio (see Section \ref{sec-ti-ccs}).
- \item Import the rpp-lib project as described in
- Section~\ref{sec-openning-of-existing-project}.
- \item Compile the static library using the procedure from Section
- \ref{sec-compilation}. The compiled library \texttt{rpp-lib.lib}
- will appear in the project root directory.
- \item Either copy the compiled library and the content of the
- \texttt{rpp/include} directory to the application, where you
- want to use it or use the library in place, as described in
- Section~\ref{sec:creating-new-project}.
- \begin{itemize}
- \item In the rpp-simulink application the library is located in
- the \texttt{rpp/lib} folder.
- \item In the rpp-test-sw application the library is located in
- the \texttt{rpp-lib} folder.
- \end{itemize}
-\end{enumerate}
+\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}
\begin{enumerate}
\item Unzip the \texttt{rpp-test-sw-version.zip} file.
\item Open the Code Composer Studio (see Section \ref{sec-ti-ccs}).
- \item Follow the procedure for opening the projects in CCS in
- Section \ref{sec-openning-of-existing-project} and open both
- \texttt{rpp-lib} and \texttt{rpp-test-sw} projects.
+ \item Import the \texttt{rpp-test-sw} project as described in
+ Section \ref{sec-openning-of-existing-project}.
\item Right click on the \texttt{rpp-test-sw} project in the
\textsc{Project Explorer} and select \textsc{Build Project}.
\item Follow the instructions in
Section~\ref{sec-running-software-on-hw} to download, debug and
- run the software on the target hardware. If CCS asks you whether
- to proceed with the detected errors in \texttt{rpp-lib} project.
- Ignore them and click the \textsc{Proceed} button to continue.
+ run the software on the target hardware.
+\end{enumerate}
+
+\subsection{rpp-lib}
+\label{sec-rpp-lib-installation}
+
+This section describes how to open the rpp-lib project in Code
+Composer Studio and how to use the resulting static library in an
+application. This is only necessary if you need to modify the library
+for some reason.
+
+\begin{enumerate}
+ \item Unzip the \texttt{rpp-lib-version.zip} file.
+ \item Open the Code Composer Studio (see Section \ref{sec-ti-ccs}).
+ \item Import the rpp-lib project from directory
+ \texttt{rpp-lib-XXX/build/\tgtId} as described in
+ Section~\ref{sec-openning-of-existing-project}.
+ \item Compile the static library by selecting \textsc{Project
+ $\rightarrow$ Build Project} (see Section
+ \ref{sec-compilation} for more information). The compiled
+ library \texttt{rpp-lib.lib} and file
+ \texttt{Makefile.config} will appear in the
+ \texttt{rpp-lib-XXX} directory.
+ \item Either copy the compiled library and the content of the
+ \texttt{rpp/include} directory to the application, where you
+ want to use it or use the library in place, as described in
+ Section~\ref{sec:creating-new-project}.
+ \begin{itemize}
+ \item In the rpp-simulink application the library is located in
+ the \texttt{rpp/lib} folder.
+ \item In the rpp-test-sw application the library is located in
+ the \texttt{rpp-lib} folder.
+ \end{itemize}
\end{enumerate}
\section{Code Composer Studio usage}
\label{sec-code-composerpstudio-usage}
-\subsection{Opening of existing project}
+\subsection{Opening an existing project}
\label{sec-openning-of-existing-project}
The procedure for opening a project is similar to opening a project in
the standard Eclipse IDE.
\newpage
\subsection{Creating new project}
\label{sec:creating-new-project}
-Follow these steps to create an application for RM48 MCU compiled with
+Follow these steps to create an application for \tgname{} MCU compiled with
CGT.
\begin{compactenum}
-\item Create a new empty CCS project. Select RM48L952 device, XDS100v2
+\item Create a new empty CCS project. Select \mcuname{} device, XDS100v2
connection and set Linker command file to
- \texttt{rpp-lib/rpp/RM48L952FlashLnk.cmd}.
+ \texttt{rpp-lib/build/\tgtId/\ldscriptname}.
\noindent\includegraphics[scale=0.45]{images/base_1.png}
\item Configure the compiler \#include search path to contain
project's \texttt{include} directory, \penalty-100
- \texttt{\$\{RPP\_LIB\_ROOT\}/os/7.0.2\_rm48/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}
\newpage
\item Add \texttt{\$\{RPP\_LIB\_ROOT\}/rpp-lib.lib} to the list of
linked libraries before the runtime support library
- (\texttt{rtsv7R4\_T\_le\_v3D16\_eabi.lib}).
+ (\texttt{\tgtRtlib}).
\noindent\includegraphics[scale=.45]{images/base_3.png}
\textsc{Resume}.
\item If your application fails to run with a \texttt{\_dabort} interrupt, check
that the linker script selected in step 1 is not excluded from the build.
-You can do this by right clicking on the file \texttt{RM48L952FlashLnk.cmd}
+You can do this by right clicking the \texttt{\ldscriptname} file
in the \textsc{Project Explorer} and unchecking the \textsc{Exclude from build}
item. The Code Composer Studio sometimes automaticaly excludes this file from
-the build process when creating the new project.
+the build process when creating a new project.
% \item If not already created for another project, create new target
% configuration. Select \textsc{Windows $\rightarrow$ Show View
% $\rightarrow$ Target Configurations}. In the shown window, click
% on \textsc{New Target Configuration} icon and configure XDS100v2
-% connection and RM48L952 device as shown below. Click \textsc{Save},
+% connection and \mcuname{} device as shown below. Click \textsc{Save},
% connect your board and click \textsc{Test Connection}.
% \medskip
\item Optionally, you can change debugger configuration by selecting
\textsc{Run $\rightarrow$ Debug Configurations}. In the
\textsc{Target} tab, you can configure not to break at \texttt{main}
- or not to erase the whole flash, but only necessary sectors (see the
+ or not to erase the whole flash, but necessary sectors only (see the
figure below).
\includegraphics[width=\linewidth]{images/debug_conf_flash.png}
\end{compactenum}
-\subsubsection{Steps to configure new POSIX application:}
-Such an application can be used to test certain FreeRTOS features on
-Linux and can be compiled with a native GCC compiler.
-
-\begin{compactenum}
- \item Create a new managed C project that uses Linux GCC toolchain.
- \item Create a source folder \texttt{src}. Link all files from original
-CCS application to this folder.
- \item Create a normal folder \texttt{include}. Create a folder
-\texttt{rpp} inside of it.
- \item Add common \texttt{.gitignore} to the root of that project:
-\lstset{language=}
-\begin{lstlisting}
-Debug
-Release
-.settings/*
-\end{lstlisting}
- \item Add new variable \texttt{RPP\_LIB\_ROOT} and point to this
-repository branch root.\newline{}
-\noindent\includegraphics[width=\linewidth]{images/base_posix_1.png}
- \item Configure compiler to include local includes, CCS application
-includes, OS includes for POSIX and RPP includes, in that order.\newline{}
-\noindent\includegraphics[width=\linewidth]{images/base_posix_2.png}
-\newpage
- \item Add \texttt{rpp} and \texttt{pthread} to linker libraries and add
-\texttt{RPP\_LIB\_ROOT} to the library search path.\newline{}
-\noindent\includegraphics[width=\linewidth]{images/base_posix_3.png}
-\end{compactenum}
+%% Comment this out for Eaton
+% \subsubsection{Steps to configure new POSIX application:}
+% Such an application can be used to test certain FreeRTOS features on
+% Linux and can be compiled with a native GCC compiler.
+
+% \begin{compactenum}
+% \item Create a new managed C project that uses Linux GCC toolchain.
+% \item Create a source folder \texttt{src}. Link all files from original
+% CCS application to this folder.
+% \item Create a normal folder \texttt{include}. Create a folder
+% \texttt{rpp} inside of it.
+% \item Add common \texttt{.gitignore} to the root of that project:
+% \lstset{language=}
+% \begin{lstlisting}
+% Debug
+% Release
+% .settings/*
+% \end{lstlisting}
+% \item Add new variable \texttt{RPP\_LIB\_ROOT} and point to this
+% repository branch root.\newline{}
+% \noindent\includegraphics[width=\linewidth]{images/base_posix_1.png}
+% \item Configure compiler to include local includes, CCS application
+% includes, OS includes for POSIX and RPP includes, in that order.\newline{}
+% \noindent\includegraphics[width=\linewidth]{images/base_posix_2.png}
+% \newpage
+% \item Add \texttt{rpp} and \texttt{pthread} to linker libraries and add
+% \texttt{RPP\_LIB\_ROOT} to the library search path.\newline{}
+% \noindent\includegraphics[width=\linewidth]{images/base_posix_3.png}
+% \end{compactenum}
\subsubsection{Content of the application}
\label{sec-running-software-on-hw}
\subsubsection{Code Composer Studio Project}
\label{sec-ccs-run-project}
-When the application is distributed as a CCS project, you have to open the
+When an application is distributed as a CCS project, you have to open the
project in the CCS as described in the Section
\ref{sec-openning-of-existing-project}. Once the project is opened and built, it
can be easily downloaded to the target hardware with the following procedure:
\begin{enumerate}
- \item Connect the Texas Instruments XDS100v2 USB emulator to the JTAG
-port.
- \item Connect a USB cable to the XDS100v2 USB emulator and the
-development computer.
+\ifx\tgtId\tgtIdTMSRPP
+ \item Connect the Texas Instruments XDS100v2 USB emulator to the JTAG port.
+ \item Connect a USB cable to the XDS100v2 USB emulator and the development computer.
+\else
+ \item Connect the USB cable to the \tgtBoardName{} board.
+\fi
\item Plug in the power supply.
\item In the Code Composer Studio click on the
\textsc{Run$\rightarrow$Debug}. The project will be optionally built and
\textsc{File$\rightarrow$New$\rightarrow$CCS Project}.
\item In the dialog window, type in a project name, for example
myBinaryLoad, Select \textsc{Device
-variant} (ARM, Cortex R, RM48L952, Texas Instruments XDS100v2 USB Emulator)
+variant} (ARM, Cortex R, \mcuname, Texas Instruments XDS100v2 USB Emulator)
and select project template to \textsc{Empty Project}. The filled dialog should
look like in Figure~\ref{fig-new-empty-project}
-\item Click on the \textsc{Finish} button and a new empty project will
+\item Click the \textsc{Finish} button and a new empty project will
be created.
\item In the \textsc{Project Explorer} right-click on the project and
select \textsc{Debug as$\rightarrow$Debug configurations}.
\item Click \textsc{New launch configuration} button
\item Rename the New\_configuration to, for example, myConfiguration.
\item Select configuration target file by clicking the \textsc{File
-System} button, finding and selecting the \texttt{RM48L952.ccxml} file. The result
+System} button, finding and selecting the \texttt{rpp-lib-XXX/build/\tgtId/\tgconfigfilename} file. The result
should look like in Figure~\ref{fig-debug-conf-main-diag}.
\item In the \textsc{program} pane select the binary file you want to
download to the board. Click on the \textsc{File System} button,
find and select the binary file. Try, for example
\texttt{rpp-test-sw.out}. The result should look like in
Figure~\ref{fig-debug-conf-program-diag}.
- \item You may also tune the target configuration like in the Section
-\ref{sec-target-configuration}.
-\item Finish the configuration by clicking on the \textsc{Apply}
- button and download the code by clicking on the \textsc{Debug}
- button. You can later invoke the download also from the
+\item You may also tune the target configuration as described in
+ Section \ref{sec-target-configuration}.
+\item Finish the configuration by clicking the \textsc{Apply} button
+ and download the code by clicking the \textsc{Debug} button. You can
+ later invoke the download also from the
\textsc{Run$\rightarrow$Debug} CCS menu. It is not necessary to
create more Debug configurations and CCS empty projects as you can
easily change the binary file in the Debug configuration to load a
\item In the dialog window select \textsc{Target} pane.
\item In the \textsc{Flash Settings}, \textsc{Erase Options} select
\textsc{Necessary sectors only}.
- \item Save the configuration by clicking on the \textsc{Apply} button
+ \item Save the configuration by clicking the \textsc{Apply} button
and close the dialog.
\end{enumerate}
\section{Matlab Simulink usage}
\label{sec-matlab-simulink-usage}
-This section describes the basic tasks for working with the RPP code
+This section describes the basics of working with the RPP code
generation target for Simulink. For a more detailed description of the
code generation target refer to
Chapter~\ref{chap-simulink-coder-target}.
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 Create new model or load a demo:
- Demos are located in \texttt{\repo/rpp/demos} or you can start a new
- model and configure target to RPP. For new models see Section
- \ref{sec-crating-new-model} below.
+ Demos are located in \texttt{\repo/rpp/demos}. Creation of new
+ models is described in Section~\ref{sec-crating-new-model} below.
\end{enumerate}
\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}
Code $\rightarrow$ Build Model}.
\end{enumerate}
-If you want to run the model on the RPP board, see Section
+To run the model on the \tgtBoardName{} board continue with Section
\ref{sec-running-model-on-hw}.
\subsection{Running models on the RPP board}
\label{sec-running-model-on-hw}
-To run the model on the target RPP hardware you have to enable the download
+To run the model on the \tgtBoardName{} hardware you have to enable the download
feature and build the model by following this procedure:
\begin{enumerate}
\item Open the model you want to run (see
Section~\ref{sec-openning-demo-models} for example with demo
models).
- \item Click on \textsc{Simulation$\rightarrow$Model Configuration
-Parameters}.
-\item In the \textsc{Code Generation$\rightarrow$RPP Options} pane
- check the \textsc{Download compiled binary to RPP} checkbox.
- \item Click the \textsc{OK} button, connect the target HW to the computer
-like in the Section \ref{sec-ccs-run-project} and build the model by \textsc{Code $\rightarrow$ C/C++
-Code $\rightarrow$ Build Model}. If the build
-ends with a success, the download process will start and once the downloading is
-finished, the application will run immediatelly.
+ \item Click on \textsc{Simulation$\rightarrow$Model Configuration
+ Parameters}.
+ \item In the \textsc{Code Generation$\rightarrow$RPP Options} pane
+ check the \textsc{Download compiled binary to RPP} checkbox. Click
+ the \textsc{OK} button
+ \item Connect the target hardware to the computer (see Section
+ \ref{sec-ccs-run-project}) and build the model by \textsc{Code
+ $\rightarrow$ C/C++ Code $\rightarrow$ Build Model}. If the build
+ succeeds, the download process will start automatically and once
+ the downloading is finished, the application will run immediately.
\end{enumerate}
%%\subsubsection{Using OpenOCD for downloading}
\label{sec-configuration-serial-interface}
The main mean for communication with the RPP board is the serial line.
Each application may define its own serial line settings, but the
-following settings is the default one:
+following settings are the default:
\begin{itemize}
\item Baudrate: 115200
\item Flow control: none
\end{itemize}
-Use GtkTerm in Linux or Bray Terminal for accessing the serial
-interface. On TMDSRM48HDK, the serial line is tunneled over the USB
-cable. % See Section \ref{sec-hardware-description} for reference about
+Use GtkTerm on Linux or Bray Terminal on Windows for accessing the
+serial interface. On \tgtBoardName{} board, the serial line is tunneled over
+the USB.
+% TODO: Conditional compilation
+ % See Section \ref{sec-hardware-description} for reference about
% the position of the serial interface connector on the RPP board.
\section{Bug reporting}
\section{Introduction}
\label{sec-description}
The RPP C Support Library (also called RPP library) defines the API for
-working with the board. It includes drivers and an operating system.
+working with the board. It includes drivers and the operating system.
The library is
designed from the board user perspective and exposes a simplified high-level API
to handle the board's peripheral modules in a safe manner. The library is
The RPP library can be used in any project, where the RPP hardware
support is required and it is also used in two applications --
-Simulink Coder target, described in Chapter
+Simulink Coder Target, described in Chapter
\ref{chap-simulink-coder-target}, and the command line testing tool,
described in Chapter \ref{chap-rpp-test-software}.
\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
code package:
\begin{description}
-\item[rpp-lib.lib and librpp.a] static RPP libraries.
+\item[rpp-lib.lib] Compiled RPP library.
- The first one is the library for Simulink models and other ARM/RM48
- applications, the other can be used for POSIX simulation. This files
- are placed here by the Makefile, when the library is built.
+ The library is needed for Simulink models and other ARM/\tgname{}
+ applications. It is placed here by the Makefile, when the library is
+ compiled.
-\item[apps/] Demo applications related to the RPP library.
+\item[apps/] Various applications related to the RPP library.
This include the CCS studio project for generating of the static
library and a test suite. The test suit in this directory has
nothing common with the test suite described later in
Chapter~\ref{chap-rpp-test-software} and those two suits are going
to be merged in the future. Also other Hello World applications are
- included as a reference about how to create an RM48 application.
+ included as a reference about how to create an \tgname{}
+ application.
+\item[build] The library can be compiled for multiple targets. Each
+ supported target has a subdirectory here, which stores configuration
+ of how to compile the library and applications for different target.
+ Each subdirectory contains a CCS project and Makefiles to build the
+ library for the particular target.
+\item[build/$\langle$target$\rangle$/Makefile.config] Configuration
+ for the particular target. This includes compiler and linker
+ switches etc.
+\item[build/$\langle$target$\rangle$/*.cmd]
+CGT Linker command file.
+
+This file is used by all applications that need to tun on the RPP
+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
\item[rpp/] Main directory for the RPP library.
\item[rpp/doc/] RPP Library API
documentation.
-\item[rpp/RM48L952FlashLnk.cmd] CGT Linker command file.
-
- This file is used by all applications linked for the RPP 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[rpp/include/\{layer\} and rpp/src/\{layer\}] Interface files and
implementations files for given \texttt{\{layer\}}. See
Section~\ref{sec-software-architecture} for details on the RPP
\label{sec-compilation}
To compile the library open the Code Composer studio project
-\texttt{rpp-lib} (see Section~\ref{sec-openning-of-existing-project})
-and build the project (\textsc{Project $\rightarrow$ Build Project}).
-If the build process is successful, the \texttt{rpp-lib.lib} file will
-appear in the library root directory.
+\texttt{rpp-lib} from appropriate \texttt{build/<target>} directory
+(see Section~\ref{sec-openning-of-existing-project}) and build the
+project (\textsc{Project $\rightarrow$ Build Project}). If the build
+process is successful, the \texttt{rpp-lib.lib} and
+\texttt{Makefile.config} files will appear in the library root
+directory.
It is also possible to compile the library using the included
\texttt{Makefile}. From the Linux command line run:
\begin{lstlisting}[language=bash]
-cd <library-root>
-make lib
+cd <library-root>/build/<target>/Debug #or Release
+make
\end{lstlisting}
Note that this only works if Code Composer Studio is installed in
\texttt{/opt/ti} directory. Otherwise, you have to set
On Windows command line run:
\begin{lstlisting}[language=bash]
-cd <library-root>
+cd <library-root>\build\<target>\Debug
set CCS_UTILS_DIR=C:\ti\ccsv5\utils
C:\ti\ccsv5\utils\bin\gmake.exe lib
\end{lstlisting}
-You have to use \texttt{gmake.exe} is instead of \texttt{make} and it
-is necessary to set variable \texttt{CCS\_UTILS\_DIR} manually. You
-can also edit \texttt{\repo/Debug/GNUmakefile} and set the variable
+You have to use \texttt{gmake.exe} instead of \texttt{make} and it is
+necessary to set variable \texttt{CCS\_UTILS\_DIR} manually. You can
+also edit \texttt{\repo/build/Makefile.rules.arm} and set the variable
there.
Note that the Makefile still requires the Code Composer Studio (ARM
The relevant aspects for compiling and linking an application using
the RPP library are summarized below.
-\subsection{ARM target (RPP board)}
-\label{sec:arm-target-rpp}
+% \subsection{ARM target (RPP board)}
+% \label{sec:arm-target-rpp}
The detailed instructions are presented in
Section~\ref{sec:creating-new-project}. Here we briefly repeat the
\begin{compactitem}
\item Configure include search path to contain the directory of
used FreeRTOS version, e.g.
- \texttt{\repo/os/7.0.2\_rm48/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}.
\item Add library \texttt{rpp-lib.lib} to the linker libraries.
The RPP library must be placed before Texas Instruments
- support library \texttt{rtsv7R4\_T\_le\_v3D16\_eabi.lib}.
+ support library \tgtRtlib.
\item Use the provided linker command file
- \texttt{RM48L952FlashLnk.cmd}.
+ \texttt{\ldscriptname}.
\end{compactitem}
-\subsection{POSIX target}
-\label{sec:posix-target}
+% \subsection{POSIX target}
+% \label{sec:posix-target}
- \begin{compactitem}
- \item Include headers files of the OS for Simulation. At the time
- of this writing the OS is POSIX FreeRTOS 6.0.4.
- \item Include header files for the RPP library or for modules you
- want to use (rpp\_can.h for CAN module for example).
- \item Add library \texttt{librpp.a} to the linker libraries.
- \item Add \texttt{pthread} to the linker libraries.
- \end{compactitem}
+% \begin{compactitem}
+% \item Include headers files of the OS for Simulation. At the time
+% of this writing the OS is POSIX FreeRTOS 6.0.4.
+% \item Include header files for the RPP library or for modules you
+% want to use (rpp\_can.h for CAN module for example).
+% \item Add library \texttt{librpp.a} to the linker libraries.
+% \item Add \texttt{pthread} to the linker libraries.
+% \end{compactitem}
\section{Compiling API documentation}
\label{sec-compiling-api-documentation}
\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\_rm48/\-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}
-The Simulink Coder Target allows to convert Simulink models to a C code,
+The Simulink Coder Target allows to convert Simulink models to C code,
compile it and download to the board.
\section{Introduction}
This target also provides support for automatic download of the compiled binary to the RPP
board.
-\begin{figure}[H]\begin{center}
+\begin{figure}\begin{center}
\noindent
\includegraphics[scale=.45]{images/tlc_process.png}
\caption{TLC code generation process. \cite[p. 1-6]{targetlanguagecompiler2013}}
\begin{itemize}
\item Sampling frequencies up to 1\,kHz.
-\item Supports only single-tasking single rate and multi rates systems. Support
- for multitasking systems 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
wrapper on the \texttt{loadti.sh}, \texttt{loadti.bat} and \texttt{loadopenocd.sh} script. More information on the \texttt{loadti.sh}
script can be found in:
\begin{verbatim}
-<css>/ccs_base/scripting/examples/loadti/readme.txt
+<ccs>/ccs_base/scripting/examples/loadti/readme.txt
http://processors.wiki.ti.com/index.php/Loadti
\end{verbatim}
implemented for the simulink target.
\item \textbf{Use OpenOCD to download the compiled binary}: This feature is not yet
-implemented for the RM48L952 simulink target.
+implemented for the \mcuname{} simulink target.
+% TODO Not true - use conditional compilation here.
\item \textbf{Print model metadata to SCI at start}: if set this option will
print a message to the Serial Communication Interface when the model start
reading.
\item[refs/] Contains third party references, which license allows the
distribution.
- \item[rpp/blocks] Contains the TLC files, which defines the blocks for
-the Matlab Simulink and \texttt{rpp\_lib.slx}, which is the Simulink RPP
-Library, containing all the Simulink blocks for RPP.
+\item[rpp/blocks] Contains the Simulink blocks specific to the
+ \tgtBoardName{} board and their sources (.c and .tlc files). When an
+ user calls \texttt{rpp\_setup.m}, these files are processed and
+ Simulink block library \texttt{rpp\_lib.slx} is created.
\item[rpp/blocks/tlc\_c]Contains the templates for C code generation from the
Matlab Simulink model.
\item[rpp/demos] Contains demo models, which purpose is to serve as a
\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
\item \texttt{Outputs}: \newline{}
Code here will be placed in the \texttt{void
$\langle$modelname$\rangle$\_step(void)} function. Should be used to get the
-inputs o a block and/or to set the outputs of that block.
+inputs of a block and/or to set the outputs of that block.
\end{itemize}
-The general layout of the TLC files implemented for this project are:
+The general layout of the TLC files implemented for this project is:
\begin{itemize}
\item In \texttt{BlockTypeSetup}: \newline{}
Call common function \texttt{\%$<$RppCommonBlockTypeSetup(block, system)$>$} that will include the
This function is called only once before the first step is issued. Default values for blocks IOs
should be placed here.
\item \texttt{void $\langle$modelname$\rangle$\_terminate(void)}: \newline{}
- This function is called when terminating the model. This should be used to free memory of revert
- other operations made on the initialization function. With current implementation this function
+ This function is called when terminating the model. This should be used to free memory or revert
+ other operations made in the initialization function. With current implementation this function
should never be called unless an error is detected and in most models it is empty.
\end{compactitem}
\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:
"C:\ti\ccsv5\utils\bin\"gmake.exe lib
\end{lstlisting}
-Both commands will create a directory for each compiled demo, which will contai the generated C code and binary file with the firmware. To download the firmware to the board and run it see Section \ref{sec-running-software-on-hw}.
+Both commands will create a directory for each compiled demo, which will contain the generated C code and binary file with the firmware. To download the firmware to the board and run it, see Section \ref{sec-running-software-on-hw}.
\end{enumerate}
\section{Adding new functionality}
blocks library. The new block creation process consists of several steps:
\begin{enumerate}
\item Addition of the new functionality to the RPP C support library.
- \item Definition of the block in a C file (Section~\ref{sec:block-definition-c})
- \item Compilation of the block definition to C MEX file
+ \item Definition of the block interface as a C MEX S-Function
+ (Section~\ref{sec:block-definition-c})
+ \item Compilation of the block definition to MEX file
(Section~\ref{sec:c-mex-file})
\item Creation of the code generator template (TLC) file
(Section~\ref{sec:tlc-file-creation}).
\item Creation of an S-Function block in the RPP block library
- and ``connecting'' of this block to the C MEX and TLC files
+ and ``connecting'' this block with the C MEX and TLC files
(Section~\ref{sec:creation-an-s})
\item Optional: Creation of the mask for the new block. The mask
specifies graphical representation of the block as well as
the content of the block parameters dialog box.
\end{enumerate}
-The following subsections demonstrates the procedure on an example of a simple user defined block.
+The following subsections demonstrate the procedure on an example of a simple user defined block.
-\subsection{Block definition in a C file}
+\subsection{Block interface definition in a C MEX S-function}
\label{sec:block-definition-c}
In order to use a custom block in the Simulink model, Simulink must know
a certain number of block attributes, such as the number and type of
block inputs, outputs and parameters. These attributes are specified
-by a set of functions in a C file. This C file gets compiled by a MEX
-compiler into a C MEX file and is then used in an S-Function block.
+by a set of functions in a C file. This C file gets compiled by the MEX
+compiler into a MEX file and is then used in an S-Function block.
Simulink calls the functions in the C MEX file to obtain the above
mentioned block attributes. In case of RPP blocks, no other
functionality is present in the C MEX file.
the C files as a reference.
Every C file that will be used with the RPP library should begin with
-a block of text in the YAML\footnote{\url{http://yaml.org/},
+a comment in YAML\footnote{\url{http://yaml.org/},
\url{https://en.wikipedia.org/wiki/YAML}} format. The information in
this block is used to automatically generate both printed and on-line
documentation. Although this block is not mandatory, it is highly
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
---
\item Outputs
\end{enumerate}
-For detail description about each one of those functions, refer to
+For detailed description about each one of those functions, refer to
\cite{targetlanguagecompiler2013}. A simple TLC file, which generates
some code may look like this:
\begin{lstlisting}[language=c]
\subsection{Creation of an S-Function block in the RPP block library}
\label{sec:creation-an-s}
-User defined blocks in Simulink can be included in the model as
+User defined Simulink blocks can be included in the model as
S-Function blocks. Follow this procedure to create a new block in the
RPP block library:
\begin{enumerate}
- \item Open the \texttt{\repo/rpp/blocks/rpp\_lib.slx} file in Matlab.
- \item Unlock it for editing by choosing \textsc{Diagram$\rightarrow$Unlock Library}.
- \item Open a Simulink Library Browser (\textsc{View$\rightarrow$Library Browser}) and from
-\textsc{Simulink$\rightarrow$User-Defined Functions} drag the S-Function block and drop it in the
-RPP Library.
-\item Double click on the just created S-Function block and in the
- dialog window write the name of the S-Functions C MEX file without
- the extension (e.g. sfunction\_myblock) in the \textsc{S-function
- name} field.
- \item If your block has some parameters, write their names in the \textsc{S-function parameters}
-field, separated by commas. The result should like like in the Figure~\ref{fig-simulink_s_fun_cfg}.
- \item Now you should see the new Simulink block with the right
- number of inputs and outputs.
- \item Optional: Every user-defined block should have a
- \emph{mask}, which provides some useful information about
- the name of the block, configuration dialog for parameters
- and names of the IO signals. The block can be used even
- without the mask, but it is not as user friendly as with the
- proper mask. See \cite[Section ``Block
- Masks'']{mathworks13:simul_2013b} for more information.
- \item Save the library and follow the procedure in
- Section~\ref{sec-crating-new-model} to use the new block in
- the model.
+\item Create a new Simulink library by selecting
+ \textsc{File$\rightarrow$New$\rightarrow$Library} and save it as
+ \texttt{\repo\-/rpp/blocks/rpp\_$\langle$name$\rangle$.slx}.
+ Alternatively, open an existing library.
+\item In case of opening an existing library, unlock it for editing by
+ choosing \textsc{Diagram$\rightarrow$Unlock Library}.
+\item Open a Simulink Library Browser
+ (\textsc{View$\rightarrow$Library Browser}) open
+ \textsc{Simulink$\rightarrow$User-Defined Functions} and drag the
+ \textsc{S-Function} block into the newly created library.
+\item Double click on the just created \textsc{S-Function} block and
+ fill in the \textsc{S-function name} field. Put there the name
+ (without the extension) of the created C MEX S-Function, e.g.
+ sfunction\_myblock. The result should like like in
+ Figure~\ref{fig-simulink_s_fun_cfg}.
+ \begin{figure}[h]\begin{center}
+ \noindent
+ \includegraphics[scale=.45]{images/simulink_s_fun_config.png}
+ \caption{Configuration dialog for user defined S-function.}
+ \label{fig-simulink_s_fun_cfg}
+ \end{center}\end{figure}
+\item If your block has some parameters, write their names (you can
+ choose them arbitrarily) in the \textsc{S-function parameters}
+ field, separated by commas. \label{item:1}
+\item Now you should see the new Simulink block with the right number
+ of inputs and outputs.
+\item Optional: Every user-defined block can have a \emph{mask}, which
+ provides some useful information about the name of the block,
+ configuration dialog for parameters and names of the IO signals. The
+ block can be used even without the mask, but it is not as user
+ friendly as with proper mask. Right-click the block and select
+ \textsc{Mask$\rightarrow$Create Mask...}. In the definition of
+ parameters, use the same names as in step~\ref{item:1}. See
+ \cite[Section ``Block Masks'']{mathworks13:simul_2013b} for more
+ information.
+\item Save the library and run \texttt{rpp\_setup} (or just
+ \texttt{rpp\_generate\_lib}) from Matlab command line to add the newly
+ created block to RPP block library (\texttt{rpp\_lib.slx}).
+\end{enumerate}
-\begin{figure}[H]\begin{center}
-\noindent
-\includegraphics[scale=.45]{images/simulink_s_fun_config.png}
-\caption{Configuration dialog for user defined S-function.}
-\label{fig-simulink_s_fun_cfg}
-\end{center}\end{figure}
+Now, you can start using the new block in Simulink models as described
+in Section~\ref{sec-crating-new-model}.
-\end{enumerate}
\section{Demos reference}
The Simulink RPP Demo Library is a set of Simulink models that use blocks from
\item Use function-call mechanism to process received messages
\end{compactenum}
+\subsection{Continuous time demo}
+\begin{figure}[H]\begin{center}
+\noindent
+\includegraphics[scale=.45]{images/demo_continuous.png}
+\caption{The demonstration of contiuous time.}
+\end{center}\end{figure}
+
+\textbf{Description:}
+
+This demo contains two integrators, which are running at continuous time. The main goal
+of this demo is to verify that the generated code is compilable and is working even when
+discrete and continuous time blocks are combined together.
+
\subsection{Simulink Demo model}
\begin{figure}[H]\begin{center}
\noindent
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}
\label{sec-rpp-test-sw-intro}
The \texttt{rpp-test-suite} is a RPP application developed testing and direct
control of the RPP hardware. The test suite implements a command processor,
-which is listening for a commands and prints some output related to the commands
+which is listening for commands and prints some output related to the commands
on the serial interface. The command processor is modular and each peripheral
-has its commands in a separated module.
+has its commands in a separate module.
The command processor is implemented in \texttt{$\langle$rpp-test-sw$\rangle$/cmdproc} and commands
modules are implemented in \texttt{$\langle$rpp-test-sw$\rangle$/commands} directory.
\textbf{115200-8-N-1}. When the software starts, the received welcome message
and prompt should look like:
-\begin{verbatim}
-Ti HDK RM48L952, FreeRTOS 7.0.2
-Test Software version eaton-0.1-beta-8-g91419f5
-CTU in Prague 10/2014
--->
-\end{verbatim}
+\bigskip
+\ifx\tgtId\tgtIdTMSRPP
+\noindent\texttt{Rapid Prototyping Platform v00.01-001\\
+Test Software version \input{version.tex}\\
+CTU in Prague 2014\\
+-->
+}
+\else
+\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}
\textit{Analog Output.} \newline{}
Mnemonic to refer to or something related to the analog output (DAC) hardware module.
+\item[API] \textit{Application Programming Interface}
+
\item[CAN]
\textit{Controller Area Network.} \newline{}
The CAN Bus is a vehicle bus standard designed to allow microcontrollers and devices to
In this project it is also used as mnemonic to refer to or something related to the CAN
hardware module.
+\item[CCS] \textit{Code Composer Studio} \\
+ Eclipse-based IDE provided by Texas Instruments.
+
\item[CGT]
\textit{Code Generation Tools.} \newline{}
Name given to the tool set produced by Texas Instruments used to compile, link, optimize,
projects / pes-rpp / rpp-simulink.git / blobdiff